From 6e362e815ea119b3f6db97b21c10fee3279b5c6b Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Sat, 15 Feb 2020 03:01:17 +0000 Subject: CTAN sync 202002150301 --- macros/latex/contrib/fewerfloatpages/README.md | 23 + macros/latex/contrib/fewerfloatpages/changes.txt | 1 + .../fewerfloatpages/fewerfloatpages-code.pdf | Bin 0 -> 595536 bytes .../fewerfloatpages/fewerfloatpages-code.tex | 4 + .../fewerfloatpages/fewerfloatpages-doc.pdf | Bin 0 -> 421147 bytes .../fewerfloatpages/fewerfloatpages-doc.tex | 10 + .../contrib/fewerfloatpages/fewerfloatpages.dtx | 1350 + .../contrib/fewerfloatpages/fewerfloatpages.ins | 66 + macros/latex/contrib/fewerfloatpages/l3doc-TUB.cls | 2306 + macros/latex/contrib/glossaries-extra/CHANGES | 120 + macros/latex/contrib/glossaries-extra/README | 25 +- .../glossaries-extra/glossaries-extra-code.pdf | Bin 898453 -> 1358261 bytes .../glossaries-extra/glossaries-extra-manual.html | 25345 ++++---- .../glossaries-extra/glossaries-extra-manual.pdf | Bin 787643 -> 784782 bytes .../glossaries-extra/glossaries-extra-manual.tex | 3930 +- .../contrib/glossaries-extra/glossaries-extra.dtx | 2992 +- .../contrib/glossaries-extra/glossaries-extra.ins | 4 +- .../samples/sample-abbr-styles.pdf | Bin 512876 -> 537720 bytes .../samples/sample-abbr-styles.tex | 10 + .../glossaries-extra/samples/sample-abbrv.pdf | Bin 44761 -> 44742 bytes .../glossaries-extra/samples/sample-accsupp.pdf | Bin 82623 -> 82832 bytes .../samples/sample-acronym-desc.pdf | Bin 50368 -> 50350 bytes .../glossaries-extra/samples/sample-acronym.pdf | Bin 36745 -> 36728 bytes .../glossaries-extra/samples/sample-alias.pdf | Bin 43875 -> 43857 bytes .../samples/sample-altmodifier.pdf | Bin 35308 -> 35290 bytes .../samples/sample-alttree-marginpar.pdf | Bin 91061 -> 90979 bytes .../samples/sample-alttree-sym.pdf | Bin 69498 -> 69519 bytes .../glossaries-extra/samples/sample-alttree.pdf | Bin 54848 -> 55731 bytes .../samples/sample-autoindex-hyp.pdf | Bin 141700 -> 141967 bytes .../glossaries-extra/samples/sample-autoindex.pdf | Bin 161138 -> 161468 bytes .../glossaries-extra/samples/sample-crossref.pdf | Bin 41294 -> 41275 bytes .../glossaries-extra/samples/sample-crossref2.pdf | Bin 41613 -> 41603 bytes .../glossaries-extra/samples/sample-docdef.pdf | Bin 45257 -> 45245 bytes .../glossaries-extra/samples/sample-entrycount.pdf | Bin 54623 -> 54604 bytes .../glossaries-extra/samples/sample-external.pdf | Bin 34187 -> 34170 bytes .../glossaries-extra/samples/sample-fmt.pdf | Bin 75268 -> 75249 bytes .../glossaries-extra/samples/sample-footnote.pdf | Bin 63232 -> 63216 bytes .../glossaries-extra/samples/sample-header.pdf | Bin 125912 -> 125893 bytes .../glossaries-extra/samples/sample-indexhook.pdf | Bin 42722 -> 42711 bytes .../samples/sample-initialisms.pdf | Bin 81618 -> 81573 bytes .../glossaries-extra/samples/sample-linkcount.pdf | Bin 38234 -> 38216 bytes .../samples/sample-mixed-abbrv-styles.pdf | Bin 57823 -> 57809 bytes .../glossaries-extra/samples/sample-mixedsort.pdf | Bin 45154 -> 45141 bytes .../glossaries-extra/samples/sample-mixture.pdf | Bin 159578 -> 159904 bytes .../glossaries-extra/samples/sample-name-font.pdf | Bin 202110 -> 202074 bytes .../glossaries-extra/samples/sample-nested.pdf | Bin 67736 -> 67719 bytes .../samples/sample-noidx-restricteddocdefs.pdf | Bin 47582 -> 47572 bytes .../glossaries-extra/samples/sample-onelink.pdf | Bin 44455 -> 44500 bytes .../samples/sample-onthefly-utf8.pdf | Bin 106071 -> 106058 bytes .../samples/sample-onthefly-xetex.pdf | Bin 19859 -> 19641 bytes .../glossaries-extra/samples/sample-onthefly.pdf | Bin 43481 -> 43469 bytes .../glossaries-extra/samples/sample-pages.pdf | Bin 38801 -> 38788 bytes .../glossaries-extra/samples/sample-postdot.pdf | Bin 37059 -> 37045 bytes .../glossaries-extra/samples/sample-postlink.pdf | Bin 67890 -> 67872 bytes .../glossaries-extra/samples/sample-prefix.pdf | Bin 33119 -> 33107 bytes .../samples/sample-record-nameref.pdf | Bin 71315 -> 71296 bytes .../glossaries-extra/samples/sample-record.pdf | Bin 50230 -> 50214 bytes .../samples/sample-restricteddocdefs.pdf | Bin 47895 -> 47883 bytes .../glossaries-extra/samples/sample-suppl-hyp.pdf | Bin 34944 -> 34926 bytes .../samples/sample-suppl-main-hyp.pdf | Bin 46402 -> 46382 bytes .../glossaries-extra/samples/sample-suppl-main.pdf | Bin 31607 -> 31596 bytes .../glossaries-extra/samples/sample-suppl.pdf | Bin 13423 -> 13411 bytes .../glossaries-extra/samples/sample-trans.pdf | Bin 49455 -> 49436 bytes .../glossaries-extra/samples/sample-undef.pdf | Bin 33231 -> 33214 bytes .../samples/sample-unitentrycount.pdf | Bin 61051 -> 61034 bytes .../contrib/glossaries-extra/samples/sample.pdf | Bin 45747 -> 45727 bytes macros/latex/contrib/glossaries/CHANGES | 47 + macros/latex/contrib/glossaries/INSTALL | 6 +- macros/latex/contrib/glossaries/README | 81 - macros/latex/contrib/glossaries/README.md | 128 + .../latex/contrib/glossaries/glossaries-code.pdf | Bin 1198329 -> 1228026 bytes .../latex/contrib/glossaries/glossaries-user.html | 60045 ++++++++++++------- .../latex/contrib/glossaries/glossaries-user.pdf | Bin 892459 -> 1240202 bytes .../latex/contrib/glossaries/glossaries-user.tex | 10400 +++- macros/latex/contrib/glossaries/glossaries.dtx | 1551 +- macros/latex/contrib/glossaries/glossaries.ins | 4 +- .../latex/contrib/glossaries/glossariesbegin.html | 72 +- .../latex/contrib/glossaries/glossariesbegin.pdf | Bin 186404 -> 186071 bytes .../latex/contrib/glossaries/glossariesbegin.tex | 4 +- .../contrib/glossaries/glossary2glossaries.html | 16 +- .../contrib/glossaries/glossary2glossaries.pdf | Bin 143108 -> 143127 bytes .../contrib/glossaries/glossary2glossaries.tex | 2 +- macros/latex/contrib/glossaries/makeglossaries | 7 +- .../latex/contrib/glossaries/makeglossaries-lite.1 | 2 +- .../contrib/glossaries/makeglossaries-lite.lua | 4 +- macros/latex/contrib/glossaries/makeglossaries.1 | 2 +- .../samples/glossary-lipsum-examples.pdf | Bin 248661 -> 248661 bytes .../contrib/glossaries/samples/minimalgls.pdf | Bin 49952 -> 49023 bytes .../contrib/glossaries/samples/minimalgls.tex | 19 +- .../contrib/glossaries/samples/mwe-acr-desc.pdf | Bin 37957 -> 37957 bytes .../contrib/glossaries/samples/mwe-acr-desc.tex | 3 + .../latex/contrib/glossaries/samples/mwe-acr.pdf | Bin 33649 -> 33649 bytes .../latex/contrib/glossaries/samples/mwe-acr.tex | 3 + .../latex/contrib/glossaries/samples/mwe-gls.pdf | Bin 29939 -> 29939 bytes .../latex/contrib/glossaries/samples/mwe-gls.tex | 3 + .../contrib/glossaries/samples/sample-FnDesc.pdf | Bin 58812 -> 58812 bytes .../contrib/glossaries/samples/sample-FnDesc.tex | 2 + .../glossaries/samples/sample-chap-hyperfirst.pdf | Bin 54816 -> 54816 bytes .../glossaries/samples/sample-chap-hyperfirst.tex | 2 + .../contrib/glossaries/samples/sample-crossref.pdf | Bin 53450 -> 56716 bytes .../contrib/glossaries/samples/sample-crossref.tex | 21 +- .../glossaries/samples/sample-custom-acronym.pdf | Bin 82178 -> 82178 bytes .../glossaries/samples/sample-custom-acronym.tex | 2 + .../contrib/glossaries/samples/sample-dot-abbr.pdf | Bin 52796 -> 52796 bytes .../contrib/glossaries/samples/sample-dot-abbr.tex | 2 + .../contrib/glossaries/samples/sample-dual.pdf | Bin 36455 -> 36455 bytes .../contrib/glossaries/samples/sample-dual.tex | 6 +- .../glossaries/samples/sample-entrycount.pdf | Bin 36834 -> 36834 bytes .../glossaries/samples/sample-entrycount.tex | 2 + .../contrib/glossaries/samples/sample-entryfmt.pdf | Bin 34899 -> 34899 bytes .../contrib/glossaries/samples/sample-entryfmt.tex | 2 + .../glossaries/samples/sample-font-abbr.pdf | Bin 50703 -> 50703 bytes .../glossaries/samples/sample-font-abbr.tex | 4 +- .../contrib/glossaries/samples/sample-ignored.pdf | Bin 31808 -> 31808 bytes .../contrib/glossaries/samples/sample-ignored.tex | 2 + .../contrib/glossaries/samples/sample-index.pdf | Bin 43373 -> 43373 bytes .../contrib/glossaries/samples/sample-index.tex | 2 + .../contrib/glossaries/samples/sample-inline.pdf | Bin 147206 -> 147456 bytes .../contrib/glossaries/samples/sample-inline.tex | 20 +- .../contrib/glossaries/samples/sample-langdict.pdf | Bin 38855 -> 38866 bytes .../contrib/glossaries/samples/sample-langdict.tex | 8 +- .../contrib/glossaries/samples/sample-newkeys.pdf | Bin 39192 -> 39192 bytes .../contrib/glossaries/samples/sample-newkeys.tex | 2 + .../glossaries/samples/sample-noidxapp-utf8.pdf | Bin 96316 -> 96316 bytes .../glossaries/samples/sample-noidxapp-utf8.tex | 2 + .../contrib/glossaries/samples/sample-noidxapp.pdf | Bin 67177 -> 67177 bytes .../contrib/glossaries/samples/sample-noidxapp.tex | 2 + .../glossaries/samples/sample-nomathhyper.pdf | Bin 41741 -> 41741 bytes .../glossaries/samples/sample-nomathhyper.tex | 2 + .../glossaries/samples/sample-numberlist.pdf | Bin 41972 -> 42099 bytes .../glossaries/samples/sample-numberlist.tex | 16 +- .../contrib/glossaries/samples/sample-prefix.pdf | Bin 43254 -> 46274 bytes .../contrib/glossaries/samples/sample-prefix.tex | 36 +- .../latex/contrib/glossaries/samples/sample-si.pdf | Bin 21710 -> 21710 bytes .../latex/contrib/glossaries/samples/sample-si.tex | 2 + .../samples/sample-storage-abbr-desc.pdf | Bin 39892 -> 39892 bytes .../samples/sample-storage-abbr-desc.tex | 2 + .../glossaries/samples/sample-storage-abbr.pdf | Bin 37659 -> 37659 bytes .../glossaries/samples/sample-storage-abbr.tex | 2 + macros/latex/contrib/glossaries/samples/sample.pdf | Bin 104092 -> 120028 bytes macros/latex/contrib/glossaries/samples/sample.tex | 53 +- .../contrib/glossaries/samples/sample4col.pdf | Bin 43320 -> 43320 bytes .../contrib/glossaries/samples/sample4col.tex | 4 + .../latex/contrib/glossaries/samples/sampleAcr.pdf | Bin 65501 -> 65501 bytes .../latex/contrib/glossaries/samples/sampleAcr.tex | 5 + .../contrib/glossaries/samples/sampleAcrDesc.pdf | Bin 65607 -> 92747 bytes .../contrib/glossaries/samples/sampleAcrDesc.tex | 15 +- .../contrib/glossaries/samples/sampleCustomAcr.pdf | Bin 93606 -> 151108 bytes .../contrib/glossaries/samples/sampleCustomAcr.tex | 7 +- .../latex/contrib/glossaries/samples/sampleDB.pdf | Bin 47037 -> 47801 bytes .../latex/contrib/glossaries/samples/sampleDB.tex | 6 +- .../contrib/glossaries/samples/sampleDesc.pdf | Bin 48390 -> 48390 bytes .../contrib/glossaries/samples/sampleDesc.tex | 7 + .../latex/contrib/glossaries/samples/sampleEq.pdf | Bin 155651 -> 156215 bytes .../latex/contrib/glossaries/samples/sampleEq.tex | 11 +- .../contrib/glossaries/samples/sampleEqPg.pdf | Bin 169202 -> 169434 bytes .../contrib/glossaries/samples/sampleEqPg.tex | 34 +- .../contrib/glossaries/samples/sampleFnAcrDesc.pdf | Bin 91335 -> 148775 bytes .../contrib/glossaries/samples/sampleFnAcrDesc.tex | 7 +- .../latex/contrib/glossaries/samples/sampleNtn.pdf | Bin 98826 -> 98650 bytes .../latex/contrib/glossaries/samples/sampleNtn.tex | 21 +- .../contrib/glossaries/samples/samplePeople.pdf | Bin 47452 -> 47452 bytes .../contrib/glossaries/samples/samplePeople.tex | 4 +- .../latex/contrib/glossaries/samples/sampleSec.pdf | Bin 65662 -> 65662 bytes .../latex/contrib/glossaries/samples/sampleSec.tex | 4 + .../contrib/glossaries/samples/sampleSort.pdf | Bin 95209 -> 95162 bytes .../contrib/glossaries/samples/sampleSort.tex | 8 +- .../contrib/glossaries/samples/sampleaccsupp.pdf | Bin 41155 -> 81349 bytes .../contrib/glossaries/samples/sampleaccsupp.tex | 84 +- .../contrib/glossaries/samples/sampleacronyms.pdf | Bin 37201 -> 37201 bytes .../contrib/glossaries/samples/sampleacronyms.tex | 2 + .../contrib/glossaries/samples/sampletree.pdf | Bin 59809 -> 60185 bytes .../contrib/glossaries/samples/sampletree.tex | 7 +- .../contrib/glossaries/samples/sampleutf8.pdf | Bin 44939 -> 44939 bytes .../contrib/glossaries/samples/sampleutf8.tex | 2 + .../latex/contrib/glossaries/samples/samplexdy.pdf | Bin 133571 -> 133467 bytes .../latex/contrib/glossaries/samples/samplexdy.tex | 6 +- .../contrib/glossaries/samples/samplexdy2.pdf | Bin 68393 -> 68393 bytes .../contrib/glossaries/samples/samplexdy2.tex | 2 + .../contrib/glossaries/samples/samplexdy3.pdf | Bin 178630 -> 178519 bytes .../contrib/glossaries/samples/samplexdy3.tex | 4 +- macros/latex/contrib/l3kernel/CHANGELOG.md | 15 +- macros/latex/contrib/l3kernel/README.md | 2 +- macros/latex/contrib/l3kernel/expl3.dtx | 4 +- macros/latex/contrib/l3kernel/expl3.pdf | Bin 584331 -> 584486 bytes macros/latex/contrib/l3kernel/interface3.pdf | Bin 1540169 -> 1540326 bytes macros/latex/contrib/l3kernel/interface3.tex | 2 +- macros/latex/contrib/l3kernel/l3alloc.dtx | 2 +- macros/latex/contrib/l3kernel/l3basics.dtx | 2 +- macros/latex/contrib/l3kernel/l3bootstrap.dtx | 2 +- macros/latex/contrib/l3kernel/l3box.dtx | 2 +- macros/latex/contrib/l3kernel/l3candidates.dtx | 2 +- macros/latex/contrib/l3kernel/l3clist.dtx | 2 +- macros/latex/contrib/l3kernel/l3coffins.dtx | 2 +- macros/latex/contrib/l3kernel/l3color-base.dtx | 2 +- macros/latex/contrib/l3kernel/l3debug.dtx | 2 +- macros/latex/contrib/l3kernel/l3deprecation.dtx | 2 +- macros/latex/contrib/l3kernel/l3doc.dtx | 2 +- macros/latex/contrib/l3kernel/l3docstrip.dtx | 2 +- macros/latex/contrib/l3kernel/l3docstrip.pdf | Bin 263040 -> 263202 bytes macros/latex/contrib/l3kernel/l3expan.dtx | 2 +- macros/latex/contrib/l3kernel/l3file.dtx | 2 +- macros/latex/contrib/l3kernel/l3final.dtx | 2 +- macros/latex/contrib/l3kernel/l3flag.dtx | 2 +- macros/latex/contrib/l3kernel/l3fp-assign.dtx | 2 +- macros/latex/contrib/l3kernel/l3fp-aux.dtx | 2 +- macros/latex/contrib/l3kernel/l3fp-basics.dtx | 2 +- macros/latex/contrib/l3kernel/l3fp-convert.dtx | 2 +- macros/latex/contrib/l3kernel/l3fp-expo.dtx | 2 +- macros/latex/contrib/l3kernel/l3fp-extended.dtx | 2 +- macros/latex/contrib/l3kernel/l3fp-logic.dtx | 2 +- macros/latex/contrib/l3kernel/l3fp-parse.dtx | 2 +- macros/latex/contrib/l3kernel/l3fp-random.dtx | 2 +- macros/latex/contrib/l3kernel/l3fp-round.dtx | 2 +- macros/latex/contrib/l3kernel/l3fp-traps.dtx | 2 +- macros/latex/contrib/l3kernel/l3fp-trig.dtx | 2 +- macros/latex/contrib/l3kernel/l3fp.dtx | 2 +- macros/latex/contrib/l3kernel/l3fparray.dtx | 2 +- macros/latex/contrib/l3kernel/l3int.dtx | 2 +- macros/latex/contrib/l3kernel/l3intarray.dtx | 2 +- .../latex/contrib/l3kernel/l3kernel-functions.dtx | 2 +- macros/latex/contrib/l3kernel/l3keys.dtx | 2 +- macros/latex/contrib/l3kernel/l3legacy.dtx | 2 +- macros/latex/contrib/l3kernel/l3luatex.dtx | 2 +- macros/latex/contrib/l3kernel/l3msg.dtx | 2 +- macros/latex/contrib/l3kernel/l3names.dtx | 2 +- macros/latex/contrib/l3kernel/l3news.pdf | Bin 379209 -> 379209 bytes macros/latex/contrib/l3kernel/l3news01.pdf | Bin 113529 -> 113529 bytes macros/latex/contrib/l3kernel/l3news02.pdf | Bin 140777 -> 140777 bytes macros/latex/contrib/l3kernel/l3news03.pdf | Bin 137983 -> 137983 bytes macros/latex/contrib/l3kernel/l3news04.pdf | Bin 107122 -> 107122 bytes macros/latex/contrib/l3kernel/l3news05.pdf | Bin 105090 -> 105090 bytes macros/latex/contrib/l3kernel/l3news06.pdf | Bin 140797 -> 140797 bytes macros/latex/contrib/l3kernel/l3news07.pdf | Bin 119092 -> 119092 bytes macros/latex/contrib/l3kernel/l3news08.pdf | Bin 152413 -> 152413 bytes macros/latex/contrib/l3kernel/l3news09.pdf | Bin 235516 -> 235516 bytes macros/latex/contrib/l3kernel/l3news10.pdf | Bin 140297 -> 140297 bytes macros/latex/contrib/l3kernel/l3news11.pdf | Bin 159154 -> 159154 bytes macros/latex/contrib/l3kernel/l3news12.pdf | Bin 192383 -> 192383 bytes macros/latex/contrib/l3kernel/l3prefixes.pdf | Bin 59418 -> 59418 bytes macros/latex/contrib/l3kernel/l3prg.dtx | 2 +- macros/latex/contrib/l3kernel/l3prop.dtx | 2 +- macros/latex/contrib/l3kernel/l3quark.dtx | 2 +- macros/latex/contrib/l3kernel/l3regex.dtx | 2 +- macros/latex/contrib/l3kernel/l3seq.dtx | 2 +- macros/latex/contrib/l3kernel/l3skip.dtx | 2 +- macros/latex/contrib/l3kernel/l3sort.dtx | 2 +- macros/latex/contrib/l3kernel/l3str-convert.dtx | 2 +- macros/latex/contrib/l3kernel/l3str.dtx | 2 +- macros/latex/contrib/l3kernel/l3styleguide.pdf | Bin 279782 -> 279927 bytes macros/latex/contrib/l3kernel/l3styleguide.tex | 2 +- macros/latex/contrib/l3kernel/l3syntax-changes.pdf | Bin 227512 -> 227669 bytes macros/latex/contrib/l3kernel/l3syntax-changes.tex | 2 +- macros/latex/contrib/l3kernel/l3sys.dtx | 2 +- macros/latex/contrib/l3kernel/l3term-glossary.pdf | Bin 186295 -> 186450 bytes macros/latex/contrib/l3kernel/l3term-glossary.tex | 2 +- macros/latex/contrib/l3kernel/l3text-case.dtx | 81 +- macros/latex/contrib/l3kernel/l3text.dtx | 25 +- macros/latex/contrib/l3kernel/l3tl-analysis.dtx | 2 +- macros/latex/contrib/l3kernel/l3tl.dtx | 2 +- macros/latex/contrib/l3kernel/l3token.dtx | 2 +- macros/latex/contrib/l3kernel/l3unicode.dtx | 2 +- macros/latex/contrib/l3kernel/source3.pdf | Bin 5770856 -> 5772243 bytes macros/latex/contrib/l3kernel/source3.tex | 2 +- macros/latex/contrib/l3packages/CHANGELOG.md | 8 +- macros/latex/contrib/l3packages/README.md | 4 +- macros/latex/contrib/l3packages/l3keys2e.dtx | 4 +- macros/latex/contrib/l3packages/l3keys2e.pdf | Bin 347451 -> 347442 bytes macros/latex/contrib/l3packages/xfp.dtx | 4 +- macros/latex/contrib/l3packages/xfp.pdf | Bin 309823 -> 309821 bytes macros/latex/contrib/l3packages/xfrac.dtx | 4 +- macros/latex/contrib/l3packages/xfrac.ins | 3 +- macros/latex/contrib/l3packages/xfrac.pdf | Bin 454245 -> 454234 bytes macros/latex/contrib/l3packages/xparse.dtx | 8 +- macros/latex/contrib/l3packages/xparse.pdf | Bin 501908 -> 501912 bytes macros/latex/contrib/l3packages/xtemplate.dtx | 4 +- macros/latex/contrib/l3packages/xtemplate.pdf | Bin 416332 -> 416321 bytes macros/latex/contrib/subfiles/README | 2 +- macros/latex/contrib/subfiles/subfiles.dtx | 200 +- macros/latex/contrib/subfiles/subfiles.pdf | Bin 211014 -> 241574 bytes macros/latex/required/babel/base/README.md | 16 +- macros/latex/required/babel/base/babel.dtx | 727 +- macros/latex/required/babel/base/babel.ins | 2 +- macros/latex/required/babel/base/babel.pdf | Bin 754441 -> 755671 bytes macros/latex/required/babel/base/bbcompat.dtx | 2 +- macros/xetex/latex/xecjk/xeCJK.dtx | 74 +- macros/xetex/latex/xecjk/xeCJK.pdf | Bin 1277275 -> 1278188 bytes macros/xetex/latex/xecjk/xunicode-symbols.pdf | Bin 292982 -> 292977 bytes 288 files changed, 70320 insertions(+), 40002 deletions(-) create mode 100644 macros/latex/contrib/fewerfloatpages/README.md create mode 100644 macros/latex/contrib/fewerfloatpages/changes.txt create mode 100644 macros/latex/contrib/fewerfloatpages/fewerfloatpages-code.pdf create mode 100644 macros/latex/contrib/fewerfloatpages/fewerfloatpages-code.tex create mode 100644 macros/latex/contrib/fewerfloatpages/fewerfloatpages-doc.pdf create mode 100644 macros/latex/contrib/fewerfloatpages/fewerfloatpages-doc.tex create mode 100644 macros/latex/contrib/fewerfloatpages/fewerfloatpages.dtx create mode 100644 macros/latex/contrib/fewerfloatpages/fewerfloatpages.ins create mode 100644 macros/latex/contrib/fewerfloatpages/l3doc-TUB.cls delete mode 100644 macros/latex/contrib/glossaries/README create mode 100644 macros/latex/contrib/glossaries/README.md (limited to 'macros') diff --git a/macros/latex/contrib/fewerfloatpages/README.md b/macros/latex/contrib/fewerfloatpages/README.md new file mode 100644 index 0000000000..25a2f6d771 --- /dev/null +++ b/macros/latex/contrib/fewerfloatpages/README.md @@ -0,0 +1,23 @@ +# fewerfloatpages package + +----- + +This package implements a float algorithm extension for handling float +pages. It attempts to reduce the number of unnecessary (fairly empty) +float pages while making sure that floats nevertheless stay close to +their call-outs. Several aspects of the algorithm behavior are +adjustable. + +Package source can be found below: + +https://github.com/FrankMittelbach/fmitex/ + +The license is LPPL 1.3c. + +----- + +Copyright (C) 2019-2020 Frank Mittelbach
+
+All rights reserved. + + diff --git a/macros/latex/contrib/fewerfloatpages/changes.txt b/macros/latex/contrib/fewerfloatpages/changes.txt new file mode 100644 index 0000000000..67a21fc352 --- /dev/null +++ b/macros/latex/contrib/fewerfloatpages/changes.txt @@ -0,0 +1 @@ +No changes yet diff --git a/macros/latex/contrib/fewerfloatpages/fewerfloatpages-code.pdf b/macros/latex/contrib/fewerfloatpages/fewerfloatpages-code.pdf new file mode 100644 index 0000000000..305431fc07 Binary files /dev/null and b/macros/latex/contrib/fewerfloatpages/fewerfloatpages-code.pdf differ diff --git a/macros/latex/contrib/fewerfloatpages/fewerfloatpages-code.tex b/macros/latex/contrib/fewerfloatpages/fewerfloatpages-code.tex new file mode 100644 index 0000000000..97d00e0877 --- /dev/null +++ b/macros/latex/contrib/fewerfloatpages/fewerfloatpages-code.tex @@ -0,0 +1,4 @@ +% this will typeset documentation + code + +\AtBeginDocument{\AlsoImplementation} +\input{fewerfloatpages.dtx} diff --git a/macros/latex/contrib/fewerfloatpages/fewerfloatpages-doc.pdf b/macros/latex/contrib/fewerfloatpages/fewerfloatpages-doc.pdf new file mode 100644 index 0000000000..df15415a7d Binary files /dev/null and b/macros/latex/contrib/fewerfloatpages/fewerfloatpages-doc.pdf differ diff --git a/macros/latex/contrib/fewerfloatpages/fewerfloatpages-doc.tex b/macros/latex/contrib/fewerfloatpages/fewerfloatpages-doc.tex new file mode 100644 index 0000000000..0d4c6d779f --- /dev/null +++ b/macros/latex/contrib/fewerfloatpages/fewerfloatpages-doc.tex @@ -0,0 +1,10 @@ +% this will typeset only documentation but not the code + +\AtBeginDocument{\OnlyDescription +% \let\tableofcontents\relax + \IndexPrologue + {\section*{Index} + \markboth{Index}{Index} + \addcontentsline{toc}{section}{Index}} + } +\input{fewerfloatpages.dtx} diff --git a/macros/latex/contrib/fewerfloatpages/fewerfloatpages.dtx b/macros/latex/contrib/fewerfloatpages/fewerfloatpages.dtx new file mode 100644 index 0000000000..01903de287 --- /dev/null +++ b/macros/latex/contrib/fewerfloatpages/fewerfloatpages.dtx @@ -0,0 +1,1350 @@ +% \iffalse meta-comment +% +%% File: fewerfloatpages.dtx (C) Copyright 2019-2020 Frank Mittelbach +% +% It may be distributed and/or modified under the conditions of the +% LaTeX Project Public License (LPPL), either version 1.3c of this +% license or (at your option) any later version. The latest version +% of this license is in the file +% +% https://www.latex-project.org/lppl.txt +% +% The development version of the bundle can be found below +% +% https://github.com/FrankMittelbach/fmitex/ +% +% for those people who are interested or want to report an issue. +% + +\def\fewerfloatpagesdate {2020/02/14} +\def\fewerfloatpagesversion{v1.0a} + + +%<*driver> +\documentclass + [final] + {l3doc-TUB} +\hfuzz=1.6pt % not even one tt character, don't worry. + +\makeatletter + \@mparswitchfalse +\makeatother + +\setcounter{page}{1} + +\newcommand\ctr[1]{\texttt{\upshape#1}} +\newcommand\option[1]{\texttt{\upshape#1}} +\newcommand\mnote[1]{\marginpar{\raggedleft\em #1}} + +\usepackage{csquotes} +\EnableCrossrefs +\CodelineIndex + + +\begin{document} + \DocInput{fewerfloatpages.dtx} +\addtolength\signaturewidth{42pt} +\makesignature +\end{document} +% +% +% \fi +% +% +% \title{The \texttt{fewerfloatpages} package\thanks{The current +% package version is \texttt{\fewerfloatpagesversion} dated +% \fewerfloatpagesdate.}} +% \author{Frank Mittelbach} +% \address{Mainz, Germany} +% \netaddress{https://www.latex-project.org} +% \personalURL{https://ctan.org/pkg/fewerfloatpages} +% +% \maketitle +% +% +% \begin{abstract} +% +% \LaTeX{}'s float algorithm has the tendency to produce fairly +% empty float pages, i.e., pages containing only floats but with a +% lot of free space remaining that could easily be filled with nearby +% text. There are good reasons for this behavior; nevertheless, the +% results look unappealing and in many cases documents are +% unnecessarily enlarged. +% +% The \pkg{fewerfloatpages} package provides an extended algorithm +% that improves on this behavior without the need for manual intervention by +% the user. +% +% \end{abstract} +% +% \microtypesetup{protrusion=false} +% \tableofcontents +% \microtypesetup{protrusion=true} +% +% \DoNotIndex{\@fpmin} +% \DoNotIndex{\@testwrongwidth} +% \DoNotIndex{\@cons} +% \DoNotIndex{\@currbox} +% \DoNotIndex{\@currtype} +% \DoNotIndex{\@elt} +% \DoNotIndex{\@empty} +% \DoNotIndex{\@gobble} +% \DoNotIndex{\@ne} +% \DoNotIndex{\@next} +% \DoNotIndex{\@spaces} +% \DoNotIndex{\@tempcnta} +% \DoNotIndex{\@tempcntb} +% \DoNotIndex{\@tempdima} +% \DoNotIndex{\@tempdimb} +% \DoNotIndex{\@testtrue} +% \DoNotIndex{\@undefined} +% \DoNotIndex{\@vtryfc} +% \DoNotIndex{\@xxxii} +% \DoNotIndex{\@ztryfc} +% \DoNotIndex{\fl@trace} +% \DoNotIndex{\@bitor} +% \DoNotIndex{\NeedsTeXFormat} +% \DoNotIndex{\TeX} +% \DoNotIndex{\advance} +% \DoNotIndex{\begingroup} +% \DoNotIndex{\bx@B} +% \DoNotIndex{\bx@D} +% \DoNotIndex{\bx@I} +% \DoNotIndex{\count} +% \DoNotIndex{\def} +% \DoNotIndex{\divide} +% \DoNotIndex{\else} +% \DoNotIndex{\endgroup} +% \DoNotIndex{\fi} +% \DoNotIndex{\gdef} +% \DoNotIndex{\global} +% \DoNotIndex{\ht} +% \DoNotIndex{\if@test} +% \DoNotIndex{\if@twocolumn} +% \DoNotIndex{\ifdim} +% \DoNotIndex{\ifnum} +% \DoNotIndex{\ifodd} +% \DoNotIndex{\ifx} +% \DoNotIndex{\let} +% \DoNotIndex{\maxdimen} +% \DoNotIndex{\multiply} +% \DoNotIndex{\newcommand} +% \DoNotIndex{\newcount} +% \DoNotIndex{\newcounter} +% \DoNotIndex{\providecommand} +% \DoNotIndex{\relax} +% \DoNotIndex{\renewcommand} +% \DoNotIndex{\reserved@a} +% \DoNotIndex{\sixt@@n} +% \DoNotIndex{\space} +% \DoNotIndex{\string} +% \DoNotIndex{\the} +% \DoNotIndex{\tw@} +% \DoNotIndex{\typeout} +% \DoNotIndex{\xdef} +% \DoNotIndex{\z@} +% +% +% \section{Introduction} + +% We start by giving a quick overview of \LaTeX{}'s float algorithm +% and the problems that result from the approach used. +% +% We then look in some detail into possible alterations and +% improvements to that algorithm and discuss possible issues that +% need to be resolved. In this section we also describe all +% configuration possibilities of the extended algorithm. +% +% The final section then documents the code changes that are +% necessary to \LaTeX{} kernel macros to implement the extension. +% +% \subsection{A quick overview of \LaTeX's float algorithm} +% +% \LaTeX{}'s output routine uses a greedy algorithm to place floats +% near to their call-outs in the source document. The decision of how +% to place a float is made when the float is first encountered. If +% possible it is placed onto the current page, either in mid-text, +% on top or into the bottom area, depending on what is allowed for +% the float and how many floats are already placed into those +% areas. +% +% If the float can't be placed immediately, it goes into a defer +% list, and in order to not accumulate too many unplaced floats +% \LaTeX{} tries to empty that list whenever there is a chance. This +% chance comes after the next page break: \LaTeX{} then starts a +% special ``float page'' algorithm in which it examines the defer +% list and from it forms float pages (i.e., pages that contain only +% floats). If necessary, it generates several float pages and only +% stops if there are no floats waiting to be placed, or there are +% too few floats to form a float page, or there are only floats left +% that are for one or another reason not allowed to be placed in +% this way. +% +% Finally \LaTeX{} looks at the remaining floats and tries to place +% as many of them as possible into the top and bottom area of the +% next page. Then it continues to process further text to fill the +% text part of that page. Details on the exact behavior of the +% algorithm are discussed in \cite{fmi:floatplacement}. +% +% +% \subsection{The typical float page and its problems} +% +% \LaTeX{} considers a float page to be successfully built if its +% floats take up more than \cs{floatpagefraction} of the whole +% page. By default this parameter is set to \texttt{.5} which means +% that such float pages may end up being half empty. +% +% Many users think that this is not a good value and try to improve on +% it by enforcing a higher percentage (such as 80\%) only to find +% that this prevents \LaTeX{} in many cases from successfully +% generating any float page, with the effect that all floats are +% suddenly piling up at the end of the document. +% +% Why is this the case? In a nutshell, because a higher percentage +% makes it much more likely that a float can't be +% placed, because it is not big enough to be used on its +% own and no other nearby floats can be combined with +% it, because their combination violates some other restriction, +% e.g., together they are bigger than a page, not all of them are +% allowed to go on float pages, etc. The moment that happens this +% float prevents the placement of all later floats of the same +% class too (i.e., all figures) and disaster is ensured. In most +% cases these floats will then never get placed, because they need a +% float of the right size from a different class to appear, which +% may in theory happen but is, unfortunately, unlikely. +% +% Thus,\mnote{Tinkering with the parameter settings will usually +% produce unwanted effects} while tempting, tinkering with this +% parameter by making it larger is usually not a good idea, unless +% you are prepared to place most if not all of your floats +% manually, by overwriting the placement algorithm on the level of +% individual floats (e.g., using \texttt{!}\@ syntax and/or +% shifting its position in the source document). +% +% Why does the current algorithm have these problems? To some extent, +% because it offers only global parameters that need to fit +% different scenarios and thus settings that are suitable when many +% floats need to be placed result in sub-optimal paginations in +% document parts that contain only a few floats, and vice versa. +% To overcome this problem, either one can try to develop +% algorithms with many more configurable parameters that act +% differently in different scenarios or one can let the algorithm +% follow a main strategy, configurable with only a few parameters +% (like today), but monitor the process and make more local +% adjustments and corrections depending on the actual outcome of +% that base strategy and additional knowledge of the actual +% situation in a given document part. This is the +% approach taken by the extension implemented in this package. +% +% \section{Improvements to the float page algorithm} +% +% A simple way to improve on the existing algorithm, without +% compromising its main goal of placing the floats as fast as +% possible and as close as possible to their call-outs, is the +% following: as long as there are many floats waiting to be placed, +% generate float pages as necessary to get them placed (using the +% current algorithm and its parameters). + +% Once we are unable to build further float pages, do some level +% of backtracking by checking if we have actually succeeded in +% placing all floats. If there are still floats waiting to be +% placed then assume that what has been done so far is the best +% possible way to place as many floats as possible (which it +% probably is). However, if we have been able to place all floats +% onto float pages then check if the last float page is +% sufficiently full; if not, undo that float page and instead +% redistribute its floats into the top and bottom area of the next +% upcoming page. This way the floats will be combined with further +% text and we avoid a possible half-empty float page. +% +% This approach will not resolve all the problematic scenarios +% where we find that \LaTeX{} has decided to favor fairly empty +% float pages over some tighter type of placement. It will, +% however, help to improve typical cases that do not involve too +% many floats. For\mnote{A typical case where we don't really want +% \LaTeX{} to make a float page} a example, if a single (larger) +% float appears near the end of a page, then using the standard +% algorithm it can't be immediately placed (because there isn't +% enough free space on the current page). It is therefore moved to +% the defer list and at the page break it is then placed onto a +% float page (possibly by itself, if it is large enough to allow +% for that) even though it could perfectly well go into the top or +% bottom area of the next page and thus be combined with textual +% material on that page. +% +% With the new algorithm this float page is reexamined and unless +% it is pretty much filled up already, it is unraveled and its +% floats are redistributed into the top and bottom areas of the +% next page. If, however, we have many floats waiting on the defer +% list, the normal float page algorithm will first place as many of +% them as possible into float pages and only the last of these +% pages will be subject to a closer inspection and a possible +% unraveling. +% +% An extension of this idea (and the one that we actually +% implement) is to monitor the whole float page generation process +% and instead of just considering the last float page in the sequence +% for unraveling, we look at each prospective float page in turn and +% based on the current situation (e.g., number of floats still +% being unplaced, free space on the float page, etc.)\@ decide +% whether this float page should be produced or whether we should +% stop making float pages and instead place the pending floats into +% top and bottom areas of the upcoming page. +% +% +% \subsection{Details on the extended algorithm} +% +% The main idea of the extended algorithm is to avoid unnecessary cases of +% float pages especially if those float pages are fairly +% empty.\mnote{Don't unravel a float page if there are too many +% floats on the defer list} +% Natural candidates are single float pages, but even in cases where +% the current \LaTeX{} algorithm produces several sequential float +% pages the extended algorithm may decide to replace them by normal +% pages under certain conditions. +% However, the main goal +% is and should remain to place as many floats as soon as possible +% and so generating float pages when many floats are waiting is +% usually essential. +% +% \begin{variable}{floatpagedeferlimit} +% \begin{syntax} +% \cs{setcounter}\{floatpagedeferlimit\}\Arg{number} +% \end{syntax} +% Whether or not unraveling for a float page is considered at all +% is guided by the counter \ctr{floatpagedeferlimit}. As long as +% there are more floats waiting on the defer list than this number, +% float pages are not considered for unraveling. The default is +% \texttt{3} which corresponds to the default value for +% \ctr{totalnumber}, i.e., with that setting the unraveling of a +% floating page has a fighting chance to place all floats into the +% top and bottom areas on the current page. +% It would also resolve cases for up to three floats, each larger than +% \cs{floatpagefraction}, where the standard \LaTeX{} algorithm would +% produce three individual float pages.\strut +% \end{variable} +% +% If you set the counter to \texttt{1} then only the last float +% page in a sequence is considered, and only if it contains only a +% single float and if there are no other floats that are still +% waiting to be placed. If you set it to \texttt{0}, then the +% extension is disabled, because float pages are produced only if +% there was at least one float on the defer list. +% +% Even\mnote{Don't unravel if the float page contains many floats} +% if we set \ctr{floatpagedeferlimit} to a fairly high value, we +% may not want to unravel float pages that contain many floats. To +% support this case there is a second counter that guides the +% algorithm in this respect. +% +% \begin{variable}{floatpagekeeplimit} +% \begin{syntax} +% \cs{setcounter}\{floatpagekeeplimit\}\Arg{number} +% \end{syntax} +% Whenever the float page contains at least +% \ctr{floatpagekeeplimit} floats it will not be unraveled. The +% default is also \texttt{3} so that float pages with three or more +% floats are not touched. Obviously the counter can have any effect +% only if it has a value less than or equal to +% \ctr{floatpagedeferlimit} because this is tested first.\strut +% \end{variable} +% +% +% There are, however, a number of other situations in which we +% shouldn't unravel a float page even if the above checks for the +% size of the defer list were passed successfully.\mnote{Don't +% unravel if the float page contains at least one \texttt{\upshape +% [p]} float} The most important one is the case when the float +% page contains at least one float that is allowed \emph{only} on +% float pages (i.e., has a \texttt{[p]} argument). Such a float +% would not be placeable in a top/bottom area on any page and thus +% would be repeatedly sent back to the defer list (possibly forever). +% +% The other case where unraveling would normally be +% counterproductive is when the particular float page is nearly or +% completely filled up with floats.\mnote{Don't unravel if the +% float page is nearly filled} If we unravel it, then it is +% certain that we can place only some of the floats into the top or +% bottom area of the next page, while some would end up on the defer +% list. That in turn means that these deferred floats float even +% further away from their call-out positions than need be. +% +% \begin{variable}{\floatpagekeepfraction} +% \begin{syntax} +% \cs{renewcommand}\cs{floatpagekeepfraction}\Arg{decimal} +% \end{syntax} +% So what is a good way to determine if a float page is ``full +% enough''? A possible answer is that if the remaining free space +% on that page is less than \cs{textfraction} we consider it full +% enough to stay. \cs{textfraction} defines the minimum amount of +% space that has to be occupied by text on a normal page, thus if +% all floats together need so much space that this amount of text +% could not fit, then trying to place all floats onto a +% normal page can't succeed and some of them would get deferred for +% sure. To allow for further flexibility the algorithm uses +% the variable \cs{floatpagekeepfraction} (defaulting to +% \cs{textfraction}) so if desired a lower (or even a higher) +% boundary can be set.\strut +% \end{variable} +% +% The above parameters give some reasonable configuration +% possibilities to guide the algorithm as to when and when not to unravel +% a possible float page and instead produce further normal pages. +% It should be noted, however, that except for the case of setting +% \ctr{floatpagedeferlimit} to \texttt{1}, there is always a chance +% that floats drift further away from their call-outs, because they +% may not be immediately placeable due to other parameter settings +% of the float algorithm. For example, the counter +% \texttt{topnumber} (default value 2) limits the number of floats +% that can be placed in the top area on a normal page and if more +% remain after unraveling only two can immediately go in this area. +% +% +% \subsection{Possible pitfalls and how to avoid them} +% +% The algorithm detects if a float is allowed only on float pages +% (i.e., is given in the source as \texttt{[p]}) and it will ensure +% that float pages containing such floats are not unraveled. +% +% However, if you have a float with the default specifier +% \texttt{[tbp]} whose size is larger than the allowed size of the +% top or bottom area (e.g., larger than \cs{topfraction} +% \texttimes{} \cs{textheight}), then this effectively means it can +% only be placed on a float page. +% +% However, according to the specifier the float is allowed to go +% into the top or bottom area, so the algorithm, as explained so +% far, would be allowed to unravel and when that float later is +% considered for top or bottom placement it will get again deferred +% and thus move from one page to the next, most likely messing up +% the whole float placement. +% +% There\mnote{\option{checktb} (option)} are two possible ways to +% improve the algorithm to avoid this disaster. One way +% would be to check the float size when it is initially encountered +% and remove any specifier that is technically not possible because +% of the parameter settings and the float size. A possible +% disadvantage is that this determination will be done once and any +% later (temporary) change to the float parameters will have no +% effect. This is currently the package default. It can be +% explicitly selected by specifying the option \option{checktb}. In +% this case you might see warnings like +%\begin{verbatim} +% LaTeX Warning: Float too large for top area: t changed to p on line ... +%\end{verbatim} +% +% Another\mnote{\option{addbang} (option)} possibility is that we automatically add a +% \texttt{!}\@ specifier to all floats during unraveling, i.e., when +% we send them back for reevaluation. This way such floats become +% placeable into top and bottom areas regardless of their size. This +% may result in fewer pages at the cost of violating the area size +% restrictions once in a while. It is specified with the option \option{addbang}. +% +% If\mnote{\option{nocheck} (option)} you prefer no automatic +% adjustment of the specifiers, add the option \option{nocheck}. +% In this case you might find that floats of certain sizes are +% unplaceable and thus get delayed to the end of the document. If +% that happens, the remedy is either to explicitly specify +% \texttt{[p]} or \texttt{[hp]} for such a float (to ensure that +% they aren't subject to unraveling) or to manually add an +% exclamation specifier, e.g., \texttt{[!tp]} so that \LaTeX{} +% doesn't use the size restrictions in its algorithm. +% +% +% +% \subsection{Tracing the algorithm} +% +% The\mnote{\option{trace} (option)} package offers the option +% \option{trace}, which if used, will result in messages such as +%\begin{verbatim} +% [1] +% fewerfloatpages: PAGE: trying to make a float page +% fewerfloatpages: ----- \@deferlist: \bx@B \bx@D +% fewerfloatpages: starting with \bx@B +% fewerfloatpages: --> success: \bx@B \bx@D +% fewerfloatpages: ----- current float page unraveled +% (free space 192.50336pt > 109.99832pt) +% [2] +%\end{verbatim} +% which means that the algorithm is trying to make a float page +% from the defer list which at that point contained two floats (the +% float boxes \cs[no-index]{bx@B} and \cs[no-index]{bx@D}), that it +% was able to produce a float page containing just +% \cs[no-index]{bx@B} and \cs[no-index]{bx@D}, and that the extended +% algorithm then decided to unravel that float page, because it has +% an unused space of \texttt{192.5pt}, i.e., roughly 16 text lines. With the current +% \cs{floatpagekeepfraction} that is too much empty space on the +% page. +% +% Or it might say +%\begin{verbatim} +% fewerfloatpages: PAGE: trying to make a float page +% fewerfloatpages: ----- \@deferlist: \bx@D \bx@F \bx@G \bx@H \bx@I +% fewerfloatpages: starting with \bx@D +% fewerfloatpages: --> success: \bx@D \bx@F +% fewerfloatpages: ----- too many deferred floats for unraveling (5 > 3) +% [3] +%\end{verbatim} +% which means that the algorithm made a float page out of the first +% two floats from the defer list (i.e., 3 remained). +% That +% page was kept regardless of the amount of free space it contained +% because we have a total of 5 floats on the defer list and the +% counter \ctr{floatpagedeferlimit} has its default value of \texttt{3}. +% +% The above tracing messages are both from the same test +% document. What they also (implicitly) show is that the unraveling +% that happened after page~1 resulted in only one float (\cs[no-index]{bx@B}) +% being placed on page~2, because we see the second one (\cs[no-index]{bx@D}) +% reappearing in the defer list after page~2 got finished. In other +% words it was moved one page further away from its call-out: the +% price for getting a nicely filled page~2 instead of a fairly empty +% float page with roughly 200 points left empty. +% The final part of that test document then exhibits another +% type of message: +%\begin{verbatim} +% fewerfloatpages: PAGE: trying to make a float page +% fewerfloatpages: ----- \@deferlist: \bx@G \bx@H \bx@I +% fewerfloatpages: starting with \bx@G +% fewerfloatpages: --> success: \bx@G \bx@H \bx@I +% fewerfloatpages: ----- all floats placed on float page(s) +% fewerfloatpages: ----- current float page kept, full enough +% (free space 38.99496pt < 109.99832pt) +% [4] +%\end{verbatim} +% This means that the remaining floats (that were left unplaced +% after float page~3 got constructed) formed a float +% page and that float page was the last in sequence (i.e., all +% floats have been placed). However, this time the algorithm decided not +% to unravel it, because it is nicely full: there are only 39 points +% of free space left on that page. +% +% Three other possible messages are shown in this sequence of +% tracing lines from a second test document (which is using some uncommon +% settings: \ctr{floatpagedeferlimit} is \texttt{10} and +% \ctr{floatpagekeeplimit} is \texttt{5}): +%\begin{verbatim} +% [1] +% fewerfloatpages: PAGE: trying to make a float page +% fewerfloatpages: ----- \@deferlist: \bx@B \bx@C \bx@D \bx@E \bx@F \bx@G \bx@H +% fewerfloatpages: starting with \bx@B +% fewerfloatpages: --> success: \bx@B \bx@C \bx@D \bx@E \bx@F \bx@G \bx@H +% fewerfloatpages: ----- current float page kept (contains at least 5 floats) +% [2] [3] +%\end{verbatim} +% In this case 7 floats have been waiting on the defer list and the +% algorithm was able to construct a float page using all of them. +% The algorithm then keeps that page because it has 5 or more floats +% in it (the value of the \ctr{floatpagekeeplimit} counter). +% +% The next message in that test document shows what happens +% when there are not enough floats waiting or they are simply too +% small (to even get past the \cs{floatpagefraction} limit): +%\begin{verbatim} +% fewerfloatpages: PAGE: trying to make a float page +% fewerfloatpages: ----- \@deferlist: \bx@I \bx@J +% fewerfloatpages: starting with \bx@I +% fewerfloatpages: --> fail +% fewerfloatpages: starting with \bx@J +% fewerfloatpages: --> fail +% fewerfloatpages: --> fail: no float page made +% [4] +%\end{verbatim} +% So no float page was made, but for some reason (that becomes clear +% later) the two floats also didn't got distributed into the top or +% bottom area of the next page. Instead they remained on the +% defer list and during processing of page~4 one more float was +% found so that after that page the defer list had grown to +% length~3: +% +%\begin{verbatim} +% fewerfloatpages: PAGE: trying to make a float page +% fewerfloatpages: ----- \@deferlist: \bx@I \bx@J \bx@K +% fewerfloatpages: starting with \bx@I +% fewerfloatpages: --> success: \bx@I \bx@J \bx@K +% fewerfloatpages: ----- current float page kept, contains a float +% fewerfloatpages: with p but no t or b specifier +% [5] +%\end{verbatim} +% This time all floats could be placed, but again the float page +% wasn't unraveled (even though in the test document it contained a +% lot of white space) because of the fact that one of its floats (in fact +% the first though that can only be deduced implicitly) was +% specified as a \enquote{float page only} float. This explains why +% on page~4 \cs[no-index]{bx@I} couldn't be placed into the top or bottom +% area and then all following floats of the same class (the test +% document contained only \env{figure} floats) couldn't be placed +% either. +% +% If\mnote{Detailed tracing of the complete algorithm} you want +% detailed tracing of the complete algorithm, also load the +% \pkg{fltrace} package and enable the tracing with +% \cs{tracefloats} anywhere in your document. Note, however, that +% the resulting output is very detailed but rather low-level and +% unpolished. +% +% +% +% +% +% \subsection{Local (manual) adjustments} +% +% If the extended algorithm is used you will get fewer float pages +% that contain a noticeable amount of white space. By adjusting +% \cs{floatpagekeepfraction} and the counters \ctr{floatpagekeeplimit} and +% \ctr{floatpagedeferlimit} you can direct the algorithm to unravel more or +% fewer of the otherwise generated float pages. However, in some cases +% it might happen that redistribution of the floats into the top and +% bottom areas of the next page(s) may result in some of them +% drifting too far away from their call-outs. If that happens, you can +% either try to change the general parameters or you could help the +% algorithm along by using the optional argument of individual float +% environments. +% The two main tools at your disposal are +% \begin{itemize} +% \item +% using the \texttt{[!..]} notation to allow the float to go into +% the top or bottom area even if it would be normally prevented by +% other restrictions; +% \item +% using \texttt{[p]} to force a float into a float page as that +% prevents the algorithm from unravelling the float page which contains +% that float. +% \end{itemize} +% As an alternative you can, of course, temporarily alter the +% definition of the command \cs{floatpagekeepfraction} or the values +% of two counters in mid-document, but remember that they are not +% looked at when a float is encountered in the source but when we +% are at a page break and \LaTeX{} attempts to empty the defer list, +% which is usually later and unfortunately somewhat asynchronous, +% i.e., not easy to predict. +% +% +% \StopEventually{ +% \begin{thebibliography}{1} +% \raggedright +% \bibitem{fmi:floatplacement} +% Frank Mittelbach. +% \newblock How to influence the position of float environments like figure and table in \LaTeX? +% \newblock \textsl{TUG}boat 35:3, 2014.\\ +% \newblock \url{https://www.latex-project.org/publications/indexbytopic/2e-floats/} +% \bibitem{source2e} +% \LaTeX{} Project Team. +% \newblock The \LaTeXe{} Sources (660+ pages), 2020.\\ +% \newblock \url{https://www.latex-project.org/help/documentation} +% \end{thebibliography} +% \ifx\thisissuepageref\undefined ^^A is this TUB production ??? if not gen index +% \setlength\IndexMin{200pt} \PrintIndex +% \fi +%} +% +% +% +% \section{The implementation} +% +% We start off with the package announcement. Requiring a fairly new +% \LaTeX{} kernel is not absolutely necessary but it will help to +% ensure that we patch what we think we patch and in the future it +% means that will can be assured that the rollback functionality of +% the kernel is available in case will need to support several +% releases of the package. +% \begin{macrocode} +%<*package> +\NeedsTeXFormat{LaTeX2e}[2018-04-01] +% \end{macrocode} +% +% \begin{macrocode} +\ProvidesPackage{fewerfloatpages} + [\fewerfloatpagesdate\space \fewerfloatpagesversion\space + improve float page generation (FMi)] +% \end{macrocode} +% +% \subsection{Option handling} +% +% This release of the package has four options: \option{trace} +% for tracing the algorithm, \option{addbang} and +% \option{checktb} to handle cases where the float size in +% combination with the float specifiers makes it difficult if not +% impossible to place the floats, and \option{nocheck} to not make +% adjustments for that case. +% +% The option \option{trace} enables tracing of the algorithm and is +% implemented by giving the command \cs[no-index]{fl@trace} (which is also +% used by the \pkg{fltrace} package) a suitable definition. +% +% To handle the case that the \pkg{fltrace} package is loaded +% first, we use \cs[no-index]{providecommand}, so that its definition is not +% overwritten, but used if it is already available. If the package is +% loaded later everything works fine because it unconditionally +% defines \cs[no-index]{fl@trace}, i.e., overwrites whatever +% \pkg{fewerfloatpages} has defined. +% +% \begin{macrocode} +\DeclareOption{trace} + {\providecommand\fl@trace[1]% + {{\let\@elt\@empty\typeout{fewerfloatpages: #1}}}} +% \end{macrocode} +% +% The other three options are mutually exclusive so we number them 0 +% to 2 in the command \cs[no-index]{fp@strategy} to ensure that +% only one is ever active. Option \option{nocheck} does nothing, with +% the cost that some floats may float to the end of the +% document. Option \option{addbang} adds a \texttt{!}\@ to floats +% that are sent back for reevaluation when a float page gets +% unraveled. Option \option{checktb} implements a different +% approach to handling problematic floats: the vertical +% size of a float is checked, and if it is too large to be allowed +% into the top or the bottom area, any \texttt{t} or \texttt{b} +% specifier is replaced by \texttt{p} (or dropped if \texttt{p} is +% already specified). +% \begin{macrocode} +\def\fp@strategy{0}% +\DeclareOption{nocheck}{\def\fp@strategy{0}} % better name? +\DeclareOption{addbang}{\def\fp@strategy{1}} +\DeclareOption{checktb}{\def\fp@strategy{2}} +% \end{macrocode} +% The actual implementation is done later. The default is +% currently \option{checktb} but this may change to +% \option{addbang} based on user feedback. +% \begin{macrocode} +\ExecuteOptions{checktb} +\ProcessOptions +% \end{macrocode} +% +% +% \subsection{Tracing code} +% +% \begin{macro}[internal]{\fl@trace} +% The command \cs[no-index]{fl@trace} is used to output tracing information. +% By default the tracing of the algorithm is turned off, so +% \cs[no-index]{fl@trace} will simply swallow its argument. But if +% \pkg{fltrace} is loaded or the option \option{trace} is given +% then the command already has a definition so we don't change it +% here. +% \begin{macrocode} +\providecommand\fl@trace[1]{} +% \end{macrocode} +% \end{macro} +% +% +% \subsection{User-level interfaces} +% +% For the most part the packages provides internal code that +% extends the float algorithm of \LaTeX{}. There are, however, also +% three new parameters that guide this algorithm; they are defined +% in this section. +% +% \begin{macro}[var]{\floatpagekeepfraction} +% The fraction that the algorithm uses to decide whether a given float +% page is so full that it would be pointless to unravel it for the +% reasons outlined above. The default is whatever fraction has been +% chosen as the minimum amount of text that needs to be on a normal +% page (i.e., \cs{textfraction}). +% \begin{macrocode} +\newcommand\floatpagekeepfraction{\textfraction} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}[var]{floatpagedeferlimit,\c@floatpagedeferlimit} + +% The algorithm will only consider unraveling float pages if there +% are not too many floats on the defer list. The definition of +% \enquote{too many} is provided through the counter +% \ctr{floatpagedeferlimit} if there are more floats waiting to be +% placed; float pages are generated until their number falls below +% this level. Thus, a value of \texttt{0} will disable the whole +% algorithm and a value of \texttt{1} means that only float pages +% with a single float might get unraveled and only if there aren't +% others still waiting to be placed. +% \begin{macrocode} +\newcounter{floatpagedeferlimit} \setcounter{floatpagedeferlimit}{3} +% \end{macrocode} +% \end{macro} + + + +% \begin{macro}[var]{floatpagekeeplimit,\c@floatpagekeeplimit} +% +% A float page that contains at least this number of floats will +% also be kept. The default is \texttt{3} but if you have a lot of +% small floats it might be better to set this to a higher +% value. +% \begin{macrocode} +\newcounter{floatpagekeeplimit} \setcounter{floatpagekeeplimit}{3} +% \end{macrocode} +% \end{macro} + + + + + +% \subsection{Patching the \LaTeX{} kernel commands} +% + + +% +% \begin{macro}[internal]{\@tryfcolumn} +% The main macro we have to patch to extend \LaTeX's algorithm is +% \cs{@tryfcolumn}. That command is changed when \pkg{fltrace} +% gets loaded, so we make our definition as late as possible to +% ensure that it will survive. +% \begin{macrocode} +\AtBeginDocument{% +% \end{macrocode} +% +% \begin{macrocode} +\def \@tryfcolumn #1{% + \global \@fcolmadefalse + \ifx #1\@empty + \else + \fl@trace{PAGE: trying to make a float + \if@twocolumn column/page\else page\fi}% + \fl@trace{----- \string #1: #1}% + \xdef\@trylist{#1}% + \global \let \@failedlist \@empty + \begingroup + \let \@elt \@xtryfc \@trylist + \endgroup +% \end{macrocode} +% Up to this point the definition is the same as in the original +% algorithm. At this point the switch \cs[no-index]{if@fcolmade} tells us if making a +% float page was successful and the original algorithm then called +% \cs[no-index]{@vtryfc} and removed the floats used for this float page from the defer list. +% +% In the extended algorithm this is the place where things start to +% differ as we may not want that float page to actually come into +% existence. +% \begin{macrocode} + \if@fcolmade +% \end{macrocode} +% As a first step we count the number of floats in the defer list +% and save the result in \cs{fp@candidates}. +% \begin{macrocode} + \fp@candidates\z@ + \def\@elt##1{\advance\fp@candidates\@ne}% + #1% + \let\@elt\relax +% \end{macrocode} +% Now we compare this number with the values of the counter \ctr{floatpagedeferlimit} +% and if it is higher we definitely want to keep the float +% page. The rationale is that if we unravel now, then all floats from +% the defer list need to go into the top/bottom areas (or get +% deferred again but to a later page) and so a high number means the defer list will +% not get shortened very much and too many floats will get delayed further. +% \begin{macrocode} + \ifnum \fp@candidates >\c@floatpagedeferlimit + \fl@trace{----- too many deferred floats for unraveling + (\the\fp@candidates\space> \the\c@floatpagedeferlimit)}% + \else +% \end{macrocode} +% +% Otherwise we do a bit more testing. First we set \cs[no-index]{if@fcolmade} +% back to false; after all our goal is to not keep the float page. If +% during the tests we decide otherwise we set it back to true, which +% then signals that it should stay. +% +% We also count the floats on the float page, reusing \cs[no-index]{fp@candidates} +% for that, which is why we initialize it to zero. +% \begin{macrocode} + \global\@fcolmadefalse + \fp@candidates\z@ +% \end{macrocode} +% The actual checking is done with +% \cs{fp@analyse@floats@for@unraveling} and it loops over +% \cs{@flsucceed}, i.e., the floats for that float page. This +% checks if any float for that page has only a \texttt{[p]} +% specifier and if so it sets \cs[no-index]{if@fcolmade} back to +% \texttt{true} and as a side effect it also does the counting for +% us. Furthermore, it also changes the switch to true if it finds +% at least \ctr{floatpagekeeplimit} floats on that page. +% \begin{macrocode} + \let\@elt\fp@analyse@floats@for@unraveling + \@flsucceed + \let\@elt\relax +% \end{macrocode} +% Now we recheck the state of the switch and if it still says +% \texttt{false}, all tests so far indicate that we don't want the float +% page. +% \begin{macrocode} + \if@fcolmade \else +% \end{macrocode} +% But we aren't done yet: the float page might be nicely filled, +% in which case it would be a shame to unravel it. During the above +% loop we also measured the free space on the float page and stored +% it in \cs{fp@unused@space} (see \cs{@xtryfc} below). We now +% compare that to the maximum free space that we consider to be +% still okay and if there is more we finally do the unraveling. +% \begin{macrocode} + \@tempdima\floatpagekeepfraction\@colht + \ifdim \fp@unused@space >\@tempdima + \fl@trace{----- current float page unraveled^^J% + \@spaces\@spaces\@spaces\space\space\space + (free space \fp@unused@space\space > \the\@tempdima)}% +% \end{macrocode} +% For this we basically return all floats back to the +% defer list. The switch is still \texttt{false} so it doesn't need +% changing. +% \begin{macrocode} + \xdef #1{\@failedlist\@flsucceed\@flfail}% +% \end{macrocode} +% However, we may also want to add a \texttt{!}\@ specifier to each of +% the floats (if the \option{addbang} option was given) +% so we loop over all the floats once more to get this +% done.\footnote{This could have been integrated with +% \cs{fp@analyse@floats@for@unraveling} but there is not much gain if +% any and by keeping it separate the processing logic seems clearer to me.} +% \begin{macrocode} + \let\@elt\fp@maybe@add@bang + \@flsucceed + \let\@elt\relax + \else +% \end{macrocode} +% But if we want to keep the float page after all, we have to set +% the switch back to \texttt{true} so that the rest of the +% algorithm proceeds correctly. +% \begin{macrocode} + \global \@fcolmadetrue + \fl@trace{----- current float page kept, full enough^^J% + \@spaces\@spaces\@spaces\space\space\space + (free space \fp@unused@space\space < \the\@tempdima)}% + \fi + \fi + \fi +% \end{macrocode} +% The next \cs[no-index]{else} matches the first \cs[no-index]{if@fcolmade}, i.e., the +% case that the algorithm wasn't able to make any float page. If +% we are tracing the algorithm, we want to tell the user about this. +% \begin{macrocode} + \else + \fl@trace{ --> fail: no float page made}% + \fi +% \end{macrocode} +% +% Finally, at this point we are back in the original algorithm. Now the +% switch tells the truth about whether or not we want to make a float +% page, and if so, we go ahead and produce it. +% \begin{macrocode} + \if@fcolmade + \@vtryfc #1% + \fi + \fi}% +}% -- END of \AtBeginDocument +% \end{macrocode} +% \end{macro} +% +% \pagebreak +% +% +% \begin{macro}[internal]{\@makefcolumn} +% +% In contrast to \cs{@tryfcolumn} this macro will always make float +% pages out of the deferred floats. It is used by \cs{clearpage} +% when we really need the floats to get out because there is no further +% text coming up. Thus, in that case we should not unravel the +% float pages. That would happen with the kernel definition of +% \cs{@makefcolumn} as that calls \cs{@tryfcolumn} which we just +% changed above. We therefore modify its definition to include the +% original code for \cs{@tryfcolumn} instead of calling our updated +% version. +% +% Again this change is made at \verb=\begin{document}= so that it +% is not overwritten in case \pkg{fltrace} is loaded afterwards. +% \begin{macrocode} +\AtBeginDocument{% +\def\@makefcolumn #1{% + \begingroup + \@fpmin -\maxdimen + \let \@testfp \@gobble +% \end{macrocode} +% At this point the original definition called \cs[no-index]{@tryfcolumn} and +% the lines above ensured that it was always succeeding in making +% a float page. However, since we have changed that command to do unraveling +% we had better not use it any more. Instead we replace it by its original +% definition (with the addition of two tracing lines). +% \begin{macrocode} + \global \@fcolmadefalse + \ifx #1\@empty + \else + \fl@trace{PAGE: trying to make a float + \if@twocolumn column/page\else page\fi}% + \fl@trace{----- \string #1: #1}% + \xdef\@trylist{#1}% + \global \let \@failedlist \@empty + \begingroup + \let \@elt \@xtryfc \@trylist + \endgroup + \if@fcolmade + \@vtryfc #1% + \fi + \fi + \endgroup +}% +}% -- END of \AtBeginDocument +% \end{macrocode} +% \end{macro} +% +% +% +% +% \begin{macro}[internal]{\@xtryfc} +% The only change to \cs{@xtryfc} is the addition of the +% \cs[no-index]{fl@trace} calls. But this extra tracing info is generally +% useful and should also be done in the \pkg{fltrace} package. +% +% The macro initiates a float page trial starting with the first +% float in \cs{@trylist}. More detailed explanations can be found +% in the documented sources of the \LaTeX{} kernel~\cite{source2e}. +% \begin{macrocode} +\def\@xtryfc #1{% + \fl@trace{ starting with \string#1}% + \@next\reserved@a\@trylist{}{}% + \@currtype \count #1% + \divide\@currtype\@xxxii + \multiply\@currtype\@xxxii + \@bitor \@currtype \@failedlist + \@testfp #1% + \@testwrongwidth #1% + \ifdim \ht #1>\@colht + \@testtrue + \fi + \if@test + \@cons\@failedlist #1% + \fl@trace{ --> fail}% + \else + \@ytryfc #1% + \fi +}% +% \end{macrocode} +% \end{macro} +% +% +% +% +% +% +% \begin{macro}[internal]{\@ytryfc} +% +% The command \cs{@ytryfc}, which is also part of the code in the +% kernel, loops through the defer list and tries to build a float +% page starting with the float passed to it in |#1|. If it succeeds, +% the floats that are part of the float page are listed in +% \cs{@flsucceed} and the switch \cs[no-index]{if@fcolmade} is set to +% \texttt{true}. Also of interest to us is that inside the code +% \cs[no-index]{@tempdima} holds the size taken up by the floats, so we can +% use this to calculate the unused space on the float page and +% store it in \cs{fp@unused@space} for use in our extended +% algorithm. +% \begin{macrocode} +\def\@ytryfc #1{% + \begingroup + \gdef\@flsucceed{\@elt #1}% + \global\let\@flfail\@empty + \@tempdima\ht #1% + \let\@elt\@ztryfc + \@trylist + \ifdim \@tempdima >\@fpmin + \global\@fcolmadetrue +% \end{macrocode} +% This branch is executed when the floats together are big enough +% to form a float page. Thus, this is the right place to calculate +% the free space by subtracting the used space from the column +% height (which may not be the full height if there are spanning +% floats in two column mode). +% \begin{macrocode} + \@tempdimb\@colht + \advance\@tempdimb-\@tempdima + \xdef\fp@unused@space{\the\@tempdimb}% +% \end{macrocode} +% The remaining code is again unchanged except that we added two +% additional tracing lines (though those should be added to +% the \pkg{fltrace} package too one of these days). +% \begin{macrocode} + \else + \@cons\@failedlist #1% + \fl@trace{ --> fail}% + \fi + \endgroup + \if@fcolmade + \let\@elt\@gobble + \fl@trace{ --> success: \@flsucceed}% + \fi} +% \end{macrocode} +% \end{macro} +% +% +% +% +% \begin{macro}[internal]{\@largefloatcheck} +% +% The final kernel macro we need to patch is +% \cs{@largefloatcheck}. This is called when a float box is +% constructed and it checks if that box is larger than the available +% \cs{textheight}, which would mean it could never be placed +% anywhere, not even on a float page. The code therefore reduces +% the box size as necessary and issues a warning. +% +% This macro is therefore a natural candidate to also check if the +% float size is too large for the float to go into top or bottom +% areas (if the option \option{checktb} is used). +% \begin{macrocode} +\def \@largefloatcheck{% + \ifdim \ht\@currbox>\textheight + \@tempdima -\textheight + \advance \@tempdima \ht\@currbox + \@latex@warning {Float too large for page by \the\@tempdima}% + \ht\@currbox \textheight + \fi +% \end{macrocode} +% The \cs{fp@maybe@check@tb} does the checking (or nothing if the +% option is not given). +% \begin{macrocode} + \fp@maybe@check@tb +} +% \end{macrocode} +% \end{macro} +% +% +% +% +% +% \subsection{Internal helper commands and parameters} +% +% +% \begin{macro}[internal]{\fp@candidates} +% We use an internal counter to count the number of floats in the +% defer list and on a float page under construction. +% \begin{macrocode} +\newcount\fp@candidates +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}[internal]{\fp@unused@space} +% In \cs{fp@unused@space} we store the amount of free space +% on the current float page. +% \begin{macrocode} +\def\fp@unused@space{} +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}[internal]{\fp@analyse@floats@for@unraveling} +% With \cs{fp@analyse@floats@for@unraveling} we loop over the +% floats on the float page, i.e., |#1| will be one such float. +% +% One of its tasks is to count the floats (in \cs{fp@candidates}) and +% check if +% there are at least \ctr{floatpagekeeplimit} of them (which means +% the float page should definitely be kept). +% +% Its most important task, however, is to check if one of the floats +% has only a \texttt{p} specifier but no other. In that case it is +% essential that we not unravel the float page because such a +% float would then only go back onto the defer list as it has no +% place to go except a float page. +% \begin{macrocode} +\def\fp@analyse@floats@for@unraveling#1{% + \advance\fp@candidates\@ne + \ifnum \fp@candidates <\c@floatpagekeeplimit +% \end{macrocode} +% So far we haven't got enough floats to know that this float page +% should be kept so we check the given float specifiers. +% +% The test may look a little weird,\footnote{\enquote{Little} might +% be an understatement. Encoding a lot of information in individual +% bits of the counter value associated with a float was a great way +% in the early days of \LaTeX{} to preserve macro space (and +% absolutely essential back then), but these days \ldots{} Anyway, +% it is the way it is and that part can't really be changed without +% breaking a lot of packages.} but what we want to know is this: +% is there a \texttt{p} (third bit) but neither a \texttt{b} +% (second bit) nor a \texttt{t} (first bit). We don't care about +% \texttt{h} or \texttt{!} which are the next two bits in the float +% counter nor any of its higher bits (which encode the type of +% float). So we divide the integer number by 8, which drops +% the two least significant bits (think of the integer +% represented in binary format), and then multiply it again by 8. As +% a result the first two bits are zeroed out. We then compare the +% result with the original value and if the two values are the same +% then the \texttt{b} and \texttt{t} bits must both have been zero +% from the start. And since the float was on a float page we also +% know that it had a \texttt{p} specifier. +% \begin{macrocode} + \@tempcntb\count#1% + \divide\@tempcntb 8\relax + \multiply\@tempcntb 8\relax + \ifnum \count#1=\@tempcntb +% \end{macrocode} +% In that case we set \cs[no-index]{if@fcolmade} to \texttt{true} +% to signal that this float page should be kept, generate a tracing +% message and change \cs[no-index]{@elt} to become +% \cs[no-index]{@gobble} to quickly jump over any remaining floats +% in the loop without doing further tests or generate further +% tracing messages. +% \begin{macrocode} + \global \@fcolmadetrue + \fl@trace{----- current float page kept, contains a float}% + \fl@trace{\@spaces\space\space with p but no t or b specifier}% + \let\@elt\@gobble + \fi +% \end{macrocode} +% On the other hand, if we have seen enough floats we also know +% that the float page should be kept, so change the switch, give +% some tracing info and stop checking: +% \begin{macrocode} + \else + \global \@fcolmadetrue + \fl@trace{----- current float page kept + (contains at least \the\fp@candidates\space floats)}% + \let\@elt\@gobble + \fi +} +% \end{macrocode} +% \end{macro} +% +% +% +% +% \begin{macro}[internal]{\fp@maybe@add@bang} +% +% The helper \cs{fp@maybe@add@bang} is used to loop through all of +% the floats of a float page (receiving each as |#1| in turn) and +% add a \texttt{!}\@ specifier if there wasn't one before. +% +% However, we only define it if we implement strategy 1 which is +% option \option{addbang}. +% \begin{macrocode} +\ifnum\fp@strategy=1 + \def\fp@maybe@add@bang#1{% +% \end{macrocode} +% Find out if the fourth bit is set (which means no \texttt{!}\@) +% and if so subtract 16 from the float counter which means setting +% it to zero. +% \begin{macrocode} + \@boxfpsbit #1\sixt@@n + \ifodd \@tempcnta + \global\advance\count#1-\sixt@@n + \fi + } +\else + \let\fp@maybe@add@bang\@gobble +\fi +% \end{macrocode} +% \end{macro} +% +% +% +% +% \begin{macro}[internal]{\fp@maybe@check@tb} +% The code in \cs{fp@maybe@check@tb} is used in +% \cs{@largefloatcheck} to test if the float has a \texttt{t} or +% \texttt{b} specifier but is too large to fit into the +% respective area. This test is not made by default but only if the +% option \option{checktb} is used, i.e., strategy~2. +% \begin{macrocode} +\ifnum\fp@strategy=2 + \def\fp@maybe@check@tb{% +% \end{macrocode} +% Again this is a case of +% looking at various bits in the float counter value in binary +% notation. +% If the specifier contained a \texttt{!}\@ we are ok and it would +% be wrong to change the specifier, because in +% that case size restrictions for areas do not apply. For this we +% have to test the fourth bit which means dividing by 16 and then +% checking if the result is odd or even (odd means there was no +% \texttt{!}\@).\footnote{I'm sure we had good reasons to +% implement it this way in 1992\Dash we probably saved a few bytes +% which was important back then. But it is certainly odd that for +% \texttt{!}\@ a value of zero means that it was specified on the +% float while for all other specifiers a value of \texttt{1} +% indicates that the specifier was given.} The kernel +% \cs{@getfpsbit} does this for us and stores the result in +% \cs[no-index]{@tempcnta} so we can test this with \cs[no-index]{ifodd} to see if the +% bit was set. +% \begin{macrocode} + \@getfpsbit \sixt@@n + \ifodd \@tempcnta +% \end{macrocode} +% If there was no \texttt{!}\@ we check if the height of the +% float is too large to fit into the top area. +% \begin{macrocode} + \ifdim \ht\@currbox>\topfraction\textheight +% \end{macrocode} +% +% If that is the case we also check the first bit of the float +% counter to see if a \texttt{t} was specified. For this we use +% \cs{@getfpsbit} again but this time with \texttt{2} as the argument +% since we test the first bit. +% \begin{macrocode} + \@getfpsbit \tw@ + \ifodd \@tempcnta +% \end{macrocode} +% If \texttt{t} was specified we need to remove it (next line) and +% add (if not already present) a \texttt{p} instead. This is done +% by \cs[no-index]{fp@add@p@bit}. Finally we add a warning for the user about +% the change. +% \begin{macrocode} + \global\advance\count\@currbox -\tw@ + \fp@add@p@bit + \@latex@warning {Float too large for top area: t changed to p}% + \fi + \fi +% \end{macrocode} +% A similar test and action is needed for bottom floats; here we +% need to look at and zero out the second bit (i.e., using 4 as a value). +% \begin{macrocode} + \ifdim \ht\@currbox>\bottomfraction\textheight + \@getfpsbit 4\relax + \ifodd \@tempcnta + \global\advance\count\@currbox -4\relax + \fp@add@p@bit + \@latex@warning {Float too large for bottom area: + b changed to p}% + \fi + \fi + \fi + } +% \end{macrocode} +% In all other cases \cs{fp@maybe@check@tb} does nothing. +% \begin{macrocode} +\else \let\fp@maybe@check@tb\relax \fi +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}[internal]{\fp@add@p@bit} +% The command \cs{fp@add@p@bit} adds the \texttt{p} specifier which +% means checking the third bit and if not set, adding 8 to the float counter. +% \begin{macrocode} +\def\fp@add@p@bit{% + \@getfpsbit 8\relax + \ifodd \@tempcnta \else \global\advance\count\@currbox 8\relax \fi} +% \end{macrocode} +% \end{macro} +% +% +% \ifx\thisissuepageref\undefined ^^A is this TUB production ??? if not gen index +% \subsection{Patches that will eventually go into \pkg{fltrace}} +% +% The \pkg{fewerfloatpages} package added some additional general +% tracing info into some of the kernel functions which isn't +% currently available when using only the \pkg{fltrace} package. As +% that tracing info is generally useful for understanding what the +% base part of the float algorithm does, it should also be added to +% the latter package. +% +% \fi +% +% \begin{macrocode} +%<*package> +% \end{macrocode} +% \Finale +% + + +\endinput diff --git a/macros/latex/contrib/fewerfloatpages/fewerfloatpages.ins b/macros/latex/contrib/fewerfloatpages/fewerfloatpages.ins new file mode 100644 index 0000000000..d3e1ef0563 --- /dev/null +++ b/macros/latex/contrib/fewerfloatpages/fewerfloatpages.ins @@ -0,0 +1,66 @@ +%% +%% This file will generate fast loadable files and documentation +%% driver files from the dtx file(s) in this package when run through +%% LaTeX or TeX. +%% +%% Copyright 2019-2020 Frank Mittelbach +%% +%% +%% This file is part of the fewerfloatpages Bundle for LaTeX. +%% ------------------------------------------------------- +%% +%% It may be distributed and/or modified under the +%% conditions of the LaTeX Project Public License, either version 1.3c +%% of this license or (at your option) any later version. +%% The latest version of this license is in +%% http://www.latex-project.org/lppl.txt +%% and version 1.3c or later is part of all distributions of LaTeX +%% version 2005/12/01 or later. +%% +%% In particular, NO PERMISSION is granted to modify the contents of this +%% file since it contains the legal notices that are placed in the files +%% it generates. +%% +%% +%% +%% --------------- start of docstrip commands ------------------ +%% +\input l3docstrip + +\keepsilent + +\usedir{tex/latex/contrib/fewerfloatpages} + +\preamble + +This is a generated file. + +Copyright 2019-2020 Frank Mittelbach + +This file was generated from file(s) of the LaTeX `fewerfloatpages Bundle'. +-------------------------------------------------------------------------- + +It may be distributed and/or modified under the +conditions of the LaTeX Project Public License, either version 1.3c +of this license or (at your option) any later version. +The latest version of this license is in + http://www.latex-project.org/lppl.txt +and version 1.3c or later is part of all distributions of LaTeX +version 2008 or later. + +This file may only be distributed together with a copy of the LaTeX +`fewerfloatpages Bundle'. You may however distribute the `fewerfloatpages Bundle' +without such generated files. + +The newest sources can be found below + + https://github.com/FrankMittelbach/fmitex/ + +where one can also log issues in case there are any. + +\endpreamble + + +\generate{\file{fewerfloatpages.sty}{\from{fewerfloatpages.dtx}{package}}} + +\endbatchfile diff --git a/macros/latex/contrib/fewerfloatpages/l3doc-TUB.cls b/macros/latex/contrib/fewerfloatpages/l3doc-TUB.cls new file mode 100644 index 0000000000..f18911e685 --- /dev/null +++ b/macros/latex/contrib/fewerfloatpages/l3doc-TUB.cls @@ -0,0 +1,2306 @@ +%% +%% This is file `l3doc-TUB.cls' +%% +%% The original source files were: +%% +%% l3doc.dtx (with options: `class') + several manual changes! +%% +%% Copyright (C) 1990-2018 The LaTeX3 Project +%% +%% It may be distributed and/or modified under the conditions of +%% the LaTeX Project Public License (LPPL), either version 1.3c of +%% this license or (at your option) any later version. The latest +%% version of this license is in the file: +%% +%% https://www.latex-project.org/lppl.txt +%% +%% File: l3doc.dtx Copyright (C) 1990-2018 The LaTeX3 project +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +%% This is really a temporary file intended for a single article +%% written for TugBoat It is a copy of l3doc.cls with a couple of +%% changes, nothing more. Eventually this will get replaced by a real +%% class once l3doc.cls gets properly split into a class part and a +%% support part. +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +%% If you use this for anything other than processing the documents it +%% was meant for (which so far is 2) you are on your own :-) +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\RequirePackage{expl3,xparse,calc} +\ProvidesExplClass{l3doc-TUB}{2020/02/14}{} + {L3 Experimental documentation class (special version for TUGboat with fixes)} +\clist_new:N \g_docinput_clist +\seq_new:N \g_doc_functions_seq +\seq_new:N \g_doc_macros_seq +\bool_new:N \l__codedoc_detect_internals_bool +\bool_set_true:N \l__codedoc_detect_internals_bool +\tl_new:N \l__codedoc_detect_internals_tl +\tl_new:N \l__codedoc_detect_internals_cs_tl +\coffin_new:N \l__codedoc_output_coffin +\coffin_new:N \l__codedoc_functions_coffin +\coffin_new:N \l__codedoc_descr_coffin +\coffin_new:N \l__codedoc_syntax_coffin +\box_new:N \g__codedoc_syntax_box +\bool_new:N \l__codedoc_in_function_bool +\bool_new:N \l__codedoc_long_name_bool +\dim_new:N \l__codedoc_trial_width_dim +\int_new:N \l__codedoc_nested_macro_int +\bool_new:N \l__codedoc_macro_tested_bool +\prop_new:N \g__codedoc_missing_tests_prop +\seq_new:N \g__codedoc_not_tested_seq +\seq_new:N \g__codedoc_testfiles_seq +\bool_new:N \l__codedoc_macro_internal_set_bool +\bool_new:N \l__codedoc_macro_internal_bool +\bool_new:N \l__codedoc_macro_TF_bool +\bool_new:N \l__codedoc_macro_pTF_bool +\bool_new:N \l__codedoc_macro_noTF_bool +\bool_new:N \l__codedoc_macro_EXP_bool +\bool_new:N \l__codedoc_macro_rEXP_bool +\bool_new:N \l__codedoc_macro_var_bool +\tl_new:N \l__codedoc_override_module_tl +\tl_set:Nn \l__codedoc_override_module_tl { \q_no_value } +\tl_new:N \l__codedoc_macro_documented_tl +\bool_new:N \g__codedoc_lmodern_bool +\bool_new:N \g__codedoc_checkfunc_bool +\bool_new:N \g__codedoc_checktest_bool +\bool_new:N \g__codedoc_kernel_bool +\tl_new:N \l__codedoc_tmpa_tl +\tl_new:N \l__codedoc_tmpb_tl +\int_new:N \l__codedoc_tmpa_int +\int_new:N \l__codedoc_tmpa_seq +\tl_new:N \l__codedoc_names_block_tl +\seq_new:N \g__codedoc_variants_seq +\bool_new:N \l__codedoc_names_verb_bool +\seq_new:N \l__codedoc_names_seq +\seq_new:N \g__codedoc_nested_names_seq +\tl_const:Nx \c__codedoc_backslash_tl { \iow_char:N \\ } +\exp_last_unbraced:NNo + \cs_new_eq:NN \c__codedoc_backslash_token { \c__codedoc_backslash_tl } +\tl_new:N \l__codedoc_index_macro_tl +\tl_new:N \l__codedoc_index_key_tl +\tl_new:N \l__codedoc_index_module_tl +\bool_new:N \l__codedoc_index_internal_bool +\tl_new:N \g__codedoc_module_name_tl +\tl_const:Nn \c__codedoc_iow_rule_tl + { ======================================== } +\tl_const:Nn \c__codedoc_iow_mid_rule_tl + { -------------------------------------- } +\box_new:N \l__codedoc_macro_box +\box_new:N \l__codedoc_macro_index_box +\int_new:N \l__codedoc_macro_int +\tl_new:N \l__codedoc_cmd_tl +\tl_new:N \l__codedoc_cmd_index_tl +\tl_new:N \l__codedoc_cmd_module_tl +\bool_new:N \l__codedoc_cmd_noindex_bool +\bool_new:N \l__codedoc_cmd_replace_bool +\bool_new:N \l__codedoc_in_implementation_bool +\bool_new:N \g__codedoc_typeset_documentation_bool +\bool_new:N \g__codedoc_typeset_implementation_bool +\bool_set_true:N \g__codedoc_typeset_documentation_bool +\bool_set_true:N \g__codedoc_typeset_implementation_bool +\tl_new:N \g__codedoc_base_name_tl +\prop_new:N \l__codedoc_variants_prop +\clist_new:N \l__codedoc_function_label_clist +\bool_new:N \l__codedoc_no_label_bool +\tl_new:N \l__codedoc_date_added_tl +\tl_new:N \l__codedoc_date_updated_tl +\tl_new:N \l__codedoc_macro_argument_tl +\cs_new_eq:NN \__codedoc_tmpa:w ? +\cs_new_eq:NN \__codedoc_tmpb:w ? +\cs_generate_variant:Nn \seq_set_split:Nnn { NoV } +\cs_generate_variant:Nn \seq_gput_right:Nn { Nf } +\cs_generate_variant:Nn \str_case:nn { fn } +\cs_generate_variant:Nn \tl_count:n { f } +\cs_generate_variant:Nn \tl_greplace_all:Nnn { Nx , Nno } +\cs_generate_variant:Nn \tl_if_empty:nTF { f } +\cs_generate_variant:Nn \tl_if_head_eq_charcode:nNTF { o } +\cs_generate_variant:Nn \tl_if_head_eq_charcode:nNT { o } +\cs_generate_variant:Nn \tl_if_head_eq_charcode:nNF { o } +\cs_generate_variant:Nn \tl_if_head_eq_meaning:nNF { V } +\cs_generate_variant:Nn \tl_if_in:nnTF { no , oo } +\cs_generate_variant:Nn \tl_if_in:NnTF { No } +\cs_generate_variant:Nn \tl_if_in:NnT { No } +\cs_generate_variant:Nn \tl_if_in:NnF { No } +\cs_generate_variant:Nn \tl_remove_all:Nn { Nx } +\cs_generate_variant:Nn \tl_replace_all:Nnn { Nx , Nnx, No , Nno } +\cs_generate_variant:Nn \tl_replace_once:Nnn { Noo } +\cs_generate_variant:Nn \tl_to_str:n { f , o } +\cs_generate_variant:Nn \prop_get:NnNTF { Nx } +\cs_generate_variant:Nn \prop_put:Nnn { Nx } +\cs_generate_variant:Nn \prop_gput:Nnn { NVx } +\prg_new_protected_conditional:Npnn \__codedoc_if_almost_str:n #1 { TF , T , F } + { + \int_compare:nNnTF + { \tl_count:n {#1} } + < { \tl_count:f { \tl_to_str:f {#1} } } + { \prg_return_false: } + { \prg_return_true: } + } +\cs_generate_variant:Nn \__codedoc_if_almost_str:nT { V } +\cs_new_protected:Npn \__codedoc_trim_right:Nn #1#2 + { + \cs_set:Npn \__codedoc_tmp:w ##1 #2 ##2 \q_stop { \exp_not:n {##1} } + \tl_set:Nx #1 { \exp_after:wN \__codedoc_tmp:w #1 #2 \q_stop } + } +\cs_generate_variant:Nn \__codedoc_trim_right:Nn { No } +\prg_new_protected_conditional:Npnn \__codedoc_str_if_begin:nn #1#2 { TF , T , F } + { + \tl_if_in:ooTF + { \exp_after:wN \scan_stop: \tl_to_str:n {#1} } + { \exp_after:wN \scan_stop: \tl_to_str:n {#2} } + { \prg_return_true: } + { \prg_return_false: } + } +\prg_generate_conditional_variant:Nnn \__codedoc_str_if_begin:nn + { oo } { TF , T , F } +\cs_new_protected:Npn \__codedoc_replace_at_at:N #1 + { + \bool_if:NT \l__codedoc_in_implementation_bool + { + \bool_if:NT \l__codedoc_detect_internals_bool + { \__codedoc_detect_internals:N #1 } + } + \tl_if_empty:NF \g__codedoc_module_name_tl + { + \exp_args:NNo \__codedoc_replace_at_at_aux:Nn + #1 \g__codedoc_module_name_tl + } + } +\cs_new_protected:Npx \__codedoc_replace_at_at_aux:Nn #1#2 + { + \tl_replace_all:Nnn #1 { \token_to_str:N @ } { @ } + \tl_replace_all:Nnn #1 { \token_to_str:N _ } { _ } + \tl_replace_all:Nnn #1 { @ @ @ @ } { \token_to_str:N a a } + \tl_replace_all:Nnn #1 { _ _ @ @ } { _ _ #2 } + \tl_replace_all:Nnn #1 { _ @ @ } { _ _ #2 } + \tl_replace_all:Nnn #1 { @ @ } { _ _ #2 } + \tl_replace_all:Nnn #1 { \token_to_str:N a a } { @ @ } + } +\group_begin: + \char_set_catcode_active:N \^^M + \cs_new_protected:Npn \__codedoc_detect_internals:N #1 + { + \tl_set_eq:NN \l__codedoc_detect_internals_tl #1 + \tl_replace_all:Non \l__codedoc_detect_internals_tl { \token_to_str:N _ } { _ } + \seq_set_split:NnV \l__codedoc_tmpa_seq { _ _ } \l__codedoc_detect_internals_tl + \seq_pop_left:NN \l__codedoc_tmpa_seq \l__codedoc_detect_internals_tl + \seq_map_variable:NNn \l__codedoc_tmpa_seq \l__codedoc_detect_internals_tl + { + \__codedoc_trim_right:No \l__codedoc_detect_internals_tl + \c_catcode_active_space_tl + \__codedoc_trim_right:Nn \l__codedoc_detect_internals_tl ^^M + \__codedoc_if_detect_internals_ok:NF \l__codedoc_detect_internals_tl + { + \tl_set_eq:NN \l__codedoc_detect_internals_cs_tl \l__codedoc_detect_internals_tl + \__codedoc_trim_right:Nn \l__codedoc_detect_internals_tl _ + \__codedoc_trim_right:Nn \l__codedoc_detect_internals_tl : + \__codedoc_trim_right:No \l__codedoc_detect_internals_tl { \token_to_str:N : } + \msg_warning:nnxxx { l3doc-TUB } { foreign-internal } + { \tl_to_str:N \l__codedoc_detect_internals_cs_tl } + { \tl_to_str:N \l__codedoc_detect_internals_tl } + { \tl_to_str:N \g__codedoc_module_name_tl } + } + } + } +\group_end: +\prg_new_protected_conditional:Npnn \__codedoc_if_detect_internals_ok:N #1 { F } + { + \__codedoc_str_if_begin:ooTF {#1} { \g__codedoc_module_name_tl _ } + { \prg_return_true: } + { + \__codedoc_str_if_begin:ooTF {#1} { \g__codedoc_module_name_tl : } + { \prg_return_true: } + { + \bool_if:NTF \g__codedoc_kernel_bool + { + \__codedoc_str_if_begin:ooTF {#1} { kernel _ } + { \prg_return_true: } + { \prg_return_false: } + } + { \prg_return_false: } + } + } + } +\cs_new:Npn \__codedoc_signature_base_form:n #1 + { \__codedoc_signature_base_form_aux:n #1 \q_stop } +\cs_new:Npn \__codedoc_signature_base_form_aux:n #1 + { + \str_case:nnTF {#1} + { + { N } { N } + { c } { N } + { n } { n } + { o } { n } + { f } { n } + { x } { n } + { V } { n } + { v } { n } + } + { \__codedoc_signature_base_form_aux:n } + { \__codedoc_signature_base_form_aux:w #1 } + } +\cs_new:Npn \__codedoc_signature_base_form_aux:w #1 \q_stop + { \exp_not:n {#1} } +\cs_new:Npn \__codedoc_predicate_from_base:n #1 + { + \__codedoc_get_function_name:n {#1} + \tl_to_str:n { _p: } + \__codedoc_get_function_signature:n {#1} + } +\cs_new:Npn \__codedoc_get_function_name:n #1 + { \__codedoc_split_function_do:nn {#1} { \use_i:nnn } } +\cs_new:Npn \__codedoc_get_function_signature:n #1 + { \__codedoc_split_function_do:nn {#1} { \use_ii:nnn } } +\cs_set_protected:Npn \__codedoc_tmpa:w #1 + { + \cs_new:Npn \__codedoc_split_function_do:nn ##1 + { + \exp_after:wN \__codedoc_split_function_auxi:w + \tl_to_str:n {##1} \q_mark \c_true_bool + #1 \q_mark \c_false_bool + \q_stop + } + \cs_new:Npn \__codedoc_split_function_auxi:w + ##1 #1 ##2 \q_mark ##3##4 \q_stop ##5 + { \__codedoc_split_function_auxii:w {##5} ##1 \q_mark \q_stop {##2} ##3 } + \cs_new:Npn \__codedoc_split_function_auxii:w + ##1##2 \q_mark ##3 \q_stop + { ##1 {##2} } + } +\exp_args:No \__codedoc_tmpa:w { \token_to_str:N : } +\cs_generate_variant:Nn \__codedoc_split_function_do:nn { o } +\cs_new_protected:Npn \__codedoc_key_get_base:nN #1#2 + { + \__codedoc_if_almost_str:nTF {#1} + { + \__codedoc_key_get_base_TF:nN {#1} \l__codedoc_tmpa_tl + \tl_set:Nx #2 + { \__codedoc_split_function_do:on \l__codedoc_tmpa_tl { \__codedoc_base_form_aux:nnN } } + } + { \tl_set:Nn #2 {#1} } + } +\cs_new:Npx \__codedoc_key_get_base_TF:nN #1#2 + { + \tl_set:Nx #2 { \exp_not:N \tl_to_str:n {#1} \scan_stop: } + \tl_if_in:NnTF #2 { \tl_to_str:n { F } \scan_stop: } + { + \tl_if_in:NnF #2 { \tl_to_str:n { TF } \scan_stop: } + { + \tl_replace_once:Nnn #2 + { \tl_to_str:n { F } \scan_stop: } + { \tl_to_str:n { TF } \scan_stop: } + } + } + { + \tl_replace_once:Nnn #2 + { \tl_to_str:n { T } \scan_stop: } + { \tl_to_str:n { TF } \scan_stop: } + } + \tl_remove_once:Nn #2 { \scan_stop: } + } +\cs_new:Npn \__codedoc_base_form_aux:nnN #1#2#3 + { + \exp_not:n {#1} + \bool_if:NT #3 + { + \token_to_str:N : + \str_if_eq:nnTF { #1 ~ } { \exp_args } + { \exp_not:n {#2} } + { \__codedoc_signature_base_form:n {#2} } + } + } +\cs_new_protected:Npn \__codedoc_base_form_signature_do:nnn #1#2#3 + { + \__codedoc_split_function_do:nn {#1} + { \__codedoc_base_form_aux:nnnnnN {#1} {#2} {#3} } + } +\cs_new_protected:Npn \__codedoc_base_form_aux:nnnnnN #1#2#3#4#5#6 + { + \bool_if:NTF #6 + { + \tl_if_head_eq_charcode:nNTF {#4} : + { #2 {#1} } + { + \use:x + { + \exp_not:n {#3} + { \__codedoc_base_form_aux:nnN {#4} {#5} #6 } + } + {#4} {#5} + } + } + { #2 {#1} } + } +\prg_new_conditional:Npnn \__codedoc_date_compare:nNn #1#2#3 { TF , T , F , p } + { \__codedoc_date_compare_aux:w #1--- \q_mark #2 #3--- \q_stop } +\cs_new:Npn \__codedoc_date_compare_aux:w + #1 - #2 - #3 - #4 \q_mark #5 #6 - #7 - #8 - #9 \q_stop + { + \__codedoc_date_compare_aux:nnnNnnn + { \tl_if_empty:nTF {#1} { 0 } {#1} } + { \tl_if_empty:nTF {#2} { 0 } {#2} } + { \tl_if_empty:nTF {#3} { 0 } {#3} } + #5 + { \tl_if_empty:nTF {#6} { 0 } {#6} } + { \tl_if_empty:nTF {#7} { 0 } {#7} } + { \tl_if_empty:nTF {#8} { 0 } {#8} } + } +\cs_new:Npn \__codedoc_date_compare_aux:nnnNnnn #1#2#3#4#5#6#7 + { + \int_compare:nNnTF {#1} = {#5} + { + \int_compare:nNnTF {#2} = {#6} + { + \int_compare:nNnTF {#3} #4 {#7} + { \prg_return_true: } { \prg_return_false: } + } + { + \int_compare:nNnTF {#2} #4 {#6} + { \prg_return_true: } { \prg_return_false: } + } + } + { + \int_compare:nNnTF {#1} #4 {#5} + { \prg_return_true: } { \prg_return_false: } + } + \use_none:n + \q_stop + } +\cs_new:Npn \__codedoc_gprop_name:n #1 { g__codedoc ~ \tl_to_str:n {#1} } +\cs_new:Npn \__codedoc_lseq_name:n #1 { l__codedoc ~ \tl_to_str:n {#1} } +\msg_new:nnnn { l3doc-TUB } { no-signature-TF } + { Function/macro~'#1'~cannot~be~turned~into~a~conditional. } + { + A~function~or~macro~environment~with~option~pTF,~TF~or~noTF~ + received~the~argument~'#1'.~This~function's~name~has~no~ + ':'~hence~it~is~not~clear~where~to~add~'_p'~or~'TF'.~ + Please~follow~expl3~naming~conventions. + } +\msg_new:nnn { l3doc-TUB } { deprecated-function } + { The~deprecated~function(s)~'#1'~should~have~been~removed~on~#2. } +\msg_new:nnn { l3doc-TUB } { date-format } + { The~date~'#1'~should~be~given~in~YYYY-MM-DD~format. } +\msg_new:nnn { l3doc-TUB } { syntax-nested-function } + { + The~'syntax'~environment~should~be~used~in~the~ + innermost~'function'~environment. + } +\msg_new:nnn { l3doc-TUB } { multiple-syntax } + { + The~'syntax'~environment~should~only~be~used~once~in~ + a~'function'~environment. + } +\msg_new:nnn { l3doc-TUB } { deprecated-option } + { The~option~'#1'~has~been~deprecated~for~'#2'. } +\msg_new:nnn { l3doc-TUB } { foreign-internal } + { + A~control~sequence~of~the~form~'...__#1'~was~used.~ + It~should~only~be~used~in~the~module~'#2' + \tl_if_empty:nF {#3} { ,~not~in~'#3' } . + } +\DeclareOption { a5paper } { \@latexerr { Option~not~supported } { } } +\DeclareOption { full } + { + \bool_gset_true:N \g__codedoc_typeset_documentation_bool + \bool_gset_true:N \g__codedoc_typeset_implementation_bool + } +\DeclareOption { onlydoc } + { + \bool_gset_true:N \g__codedoc_typeset_documentation_bool + \bool_gset_false:N \g__codedoc_typeset_implementation_bool + } +\DeclareOption { check } + { \bool_gset_true:N \g__codedoc_checkfunc_bool } +\DeclareOption { nocheck } + { \bool_gset_false:N \g__codedoc_checkfunc_bool } +\DeclareOption { checktest } + { \bool_gset_true:N \g__codedoc_checktest_bool } +\DeclareOption { nochecktest } + { \bool_gset_false:N \g__codedoc_checktest_bool } +\DeclareOption { kernel } + { \bool_gset_true:N \g__codedoc_kernel_bool } +\DeclareOption { stdmodule } + { \bool_gset_false:N \g__codedoc_kernel_bool } +\DeclareOption { cm-default } + { \bool_gset_false:N \g__codedoc_lmodern_bool } +\DeclareOption { lm-default } + { \bool_gset_true:N \g__codedoc_lmodern_bool } +\DeclareOption* { \PassOptionsToClass { \CurrentOption } { ltugboat } } +\ExecuteOptions { full, kernel, nocheck, nochecktest, lm-default } +%%FMi \PassOptionsToClass { a4paper } { article } +\msg_new:nnn { l3doc-TUB } { input-cfg } + { Local~config~file~l3doc-TUB.cfg~loaded. } +\file_if_exist:nT { l3doc-TUB.cfg } + { + \file_input:nT { l3doc-TUB.cfg } + { + \cs_if_exist:cF { ExplMakeTitle } + { \msg_info:nn { l3doc-TUB } { input-cfg } } + } + } +\ProcessOptions +\LoadClass[final]{ltugboat} +\RequirePackage{doc} + +\newcommand\bibname{References} % otherwise \bibname is undefined at \Finale +\TBtocsectionspace=0pt plus 1pt + +\IndexPrologue + {\section*{Index} + \markboth{Index}{Index} + \addcontentsline{toc}{section}{Index} + \noindent + Underlined numbers point to the definition, + italicized numbers denote the pages where the + corresponding entry is described, + all others indicate the places where it is used.} +%\EnableCrossrefs +%\CodelineIndex + +\RequirePackage + { + microtype, + array, + alphalph, + amsmath, + amssymb, + booktabs, + color, + colortbl, + hologo, + enumitem, + pifont, + textcomp, + trace, + underscore, + csquotes, + fancyvrb, + verbatim + } +\raggedbottom +\bool_if:NT \g__codedoc_lmodern_bool + { + \RequirePackage[T1]{fontenc} + \RequirePackage{lmodern} + \group_begin: + \ttfamily + \DeclareFontShape{T1}{lmtt}{m}{it}{<->ec-lmtto10}{} + \group_end: + } + +\RequirePackage{hypdoc} + +%%FMi: +\hypersetup{allcolors=black} + +\cs_gset:Npn \MakePrivateLetters + { + \char_set_catcode_letter:N \@ + \char_set_catcode_letter:N \_ + \char_set_catcode_letter:N \: + } +\setcounter{StandardModuleDepth}{1} +\@addtoreset{CodelineNo}{part} +\tl_replace_once:Nnn \theCodelineNo + { \HDorg@theCodelineNo } + { \textcolor[gray]{0.5} { \sffamily\tiny\arabic{CodelineNo} } } +\fvset{gobble=2} +\cs_gset_eq:NN \verbatim \Verbatim +\cs_gset_eq:NN \endverbatim \endVerbatim +\cs_set_protected:Npn \ifnot@excluded + { + \exp_args:Nxx \expanded@notin + { \c__codedoc_backslash_tl \tl_to_str:N \macro@namepart , } + { \exp_args:NV \tl_to_str:n \index@excludelist } + } +\cs_new:Npn \pdfstringnewline { : ~ } +\DeclareExpandableDocumentCommand + { \__codedoc_pdfstring_newline:w } { s o m } { \pdfstringnewline #3 } +\pdfstringdefDisableCommands + { \cs_set_eq:NN \\ \__codedoc_pdfstring_newline:w } +\setlength \textwidth { 385pt } +\addtolength \marginparwidth { 30pt } +\addtolength \oddsidemargin { 20pt } +\addtolength \evensidemargin { 20pt } +\cs_new_eq:NN \__codedoc_oldlist:nn \list +\cs_gset:Npn \list #1 #2 + { \__codedoc_oldlist:nn {#1} { #2 \dim_zero:N \listparindent } } +\setlength \parindent { 2em } +\setlength \itemindent { 0pt } +\setlength \parskip { 1pt plus 3pt minus 0pt } +\tl_gset:Nn \partname {File} +\@addtoreset{section}{part} +\cs_gset:Npn \l@section #1#2 + { + \ifnum \c@tocdepth >\z@ + \addpenalty\@secpenalty + \addvspace{\TBtocsectionspace}% + \setlength\@tempdima{2.5em} % was 1.5em + \begingroup + \parindent \z@ \rightskip \@pnumwidth + \parfillskip -\@pnumwidth + \leavevmode \TBtocsectionfont + \advance\leftskip\@tempdima + \hskip -\leftskip + #1\nobreak\hfil \nobreak\hb@xt@\@pnumwidth{\hss #2}\par + \endgroup + \fi + } +\cs_gset:Npn \l@subsection + { \@dottedtocline{2}{2.5em}{2.3em} } % #2 = 1.5em +\AtBeginDocument + { + \MakeShortVerb \" + \MakeShortVerb \| + \onecolumn + \SelfDocumenting + } +\AtEndDocument + { + \DeleteShortVerb \" + \DeleteShortVerb \| + } +\providecommand*\eTeX{\hologo{eTeX}} +\providecommand*\IniTeX{\hologo{iniTeX}} +\providecommand*\Lua{Lua} +\providecommand*\LuaTeX{\hologo{LuaTeX}} +\providecommand*\pdfTeX{\hologo{pdfTeX}} +\providecommand*\XeTeX{\hologo{XeTeX}} +\providecommand*\pTeX{p\kern-.2em\hologo{TeX}} +\providecommand*\upTeX{up\kern-.2em\hologo{TeX}} +\providecommand*\epTeX{$\varepsilon$-\pTeX} +\providecommand*\eupTeX{$\varepsilon$-\upTeX} +\DeclareDocumentCommand \cmd { O{} m } + { \__codedoc_cmd:no {#1} { \token_to_str:N #2 } } +\DeclareDocumentCommand \cs { O{} m } + { \__codedoc_cmd:no {#1} { \c__codedoc_backslash_tl #2 } } +\DeclareDocumentCommand \tn { O{} m } + { + \__codedoc_cmd:no + { module = TeX , replace = false , #1 } + { \c__codedoc_backslash_tl #2 } + } +\DeclareDocumentCommand \meta { m } + { \__codedoc_meta:n {#1} } +\DeclareExpandableDocumentCommand + { \__codedoc_pdfstring_cmd:w } { o m } { \token_to_str:N #2 } +\DeclareExpandableDocumentCommand + { \__codedoc_pdfstring_cs:w } { o m } { \textbackslash \tl_to_str:n {#2} } +\cs_new:Npn \__codedoc_pdfstring_meta:w #1 + { < \tl_to_str:n {#1} > } +\pdfstringdefDisableCommands + { + \cs_set_eq:NN \cmd \__codedoc_pdfstring_cmd:w + \cs_set_eq:NN \cs \__codedoc_pdfstring_cs:w + \cs_set_eq:NN \tn \__codedoc_pdfstring_cs:w + \cs_set_eq:NN \meta \__codedoc_pdfstring_meta:w + } +\newcommand\Arg[1] + { \texttt{\char`\{} \meta{#1} \texttt{\char`\}} } +\providecommand\marg[1]{ \Arg{#1} } +\providecommand\oarg[1]{ \texttt[ \meta{#1} \texttt] } +\providecommand\parg[1]{ \texttt( \meta{#1} \texttt) } +\DeclareRobustCommand \file {\nolinkurl} +\DeclareRobustCommand \env {\texttt} +\DeclareRobustCommand \pkg {\textsf} +\DeclareRobustCommand \cls {\textsf} +\NewDocumentCommand \EnableDocumentation { } + { \bool_gset_true:N \g__codedoc_typeset_documentation_bool } +\NewDocumentCommand \EnableImplementation { } + { \bool_gset_true:N \g__codedoc_typeset_implementation_bool } +\NewDocumentCommand \DisableDocumentation { } + { \bool_gset_false:N \g__codedoc_typeset_documentation_bool } +\NewDocumentCommand \DisableImplementation { } + { \bool_gset_false:N \g__codedoc_typeset_implementation_bool } +\NewDocumentEnvironment { documentation } { } + { + \bool_if:NTF \g__codedoc_typeset_documentation_bool + { \bool_set_false:N \l__codedoc_in_implementation_bool } + { \comment } + } + { \bool_if:NF \g__codedoc_typeset_documentation_bool { \endcomment } } +\NewDocumentEnvironment { implementation } { } + { + \bool_if:NTF \g__codedoc_typeset_implementation_bool + { \bool_set_true:N \l__codedoc_in_implementation_bool } + { \comment } + } + { \bool_if:NF \g__codedoc_typeset_implementation_bool { \endcomment } } +\DeclareDocumentEnvironment { variable } { O{} +v } + { + \bool_if:NTF \l__codedoc_in_implementation_bool + { \__codedoc_macro:nnw { var , #1 } {#2} } + { \__codedoc_function:nnw {#1} {#2} } + } + { + \bool_if:NTF \l__codedoc_in_implementation_bool + { \__codedoc_macro_end: } + { \__codedoc_function_end: } + } +\DeclareDocumentEnvironment { function } { O{} +v } + { \__codedoc_function:nnw {#1} {#2} } + { \__codedoc_function_end: } +\DeclareDocumentEnvironment { macro } { O{} +v } + { \__codedoc_macro:nnw {#1} {#2} } + { \__codedoc_macro_end: } +\NewDocumentEnvironment { syntax } { } + { \__codedoc_syntax:w } + { + \__codedoc_syntax_end: + \ignorespacesafterend + } +\NewDocumentEnvironment { texnote } { } + { + \endgraf + \vspace{3mm} + \small\textbf{\TeX~hackers~note:} + } + { + \vspace{3mm} + } +\NewDocumentEnvironment { arguments } { } + { + \enumerate [ + nolistsep , + label = \texttt{\#\arabic*} ~ : , + labelsep = * , + ] + } + { + \endenumerate + } +\NewDocumentCommand { \CodedocExplain } { } + { \CodedocExplainEXP \ \CodedocExplainREXP \ \CodedocExplainTF } +\NewDocumentCommand { \CodedocExplainEXP } { } + { + \raisebox{\baselineskip}[0pt][0pt]{\hypertarget{expstar}{}}% + \__codedoc_typeset_exp:\ indicates~fully~expandable~functions,~which~ + can~be~used~within~an~\texttt{x}-type~argument~(in~plain~ + \TeX{}~terms,~inside~an~\cs{edef}),~as~well~as~within~an~ + \texttt{f}-type~argument. + } +\NewDocumentCommand { \CodedocExplainREXP } { } + { + \raisebox{\baselineskip}[0pt][0pt]{\hypertarget{rexpstar}{}}% + \__codedoc_typeset_rexp:\ indicates~ + restricted~expandable~functions,~which~can~be~used~within~an~ + \texttt{x}-type~argument~but~cannot~be~fully~expanded~within~an~ + \texttt{f}-type~argument. + } +\NewDocumentCommand { \CodedocExplainTF } { } + { + \raisebox{\baselineskip}[0pt][0pt]{\hypertarget{explTF}{}}% + \__codedoc_typeset_TF:\ indicates~conditional~(\texttt{if})~functions~ + whose~variants~with~\texttt{T},~\texttt{F}~and~\texttt{TF}~ + argument~specifiers~expect~different~ + \enquote{true}/\enquote{false}~branches. + } +\keys_define:nn { l3doc-TUB/cmd } + { + index .tl_set:N = \l__codedoc_cmd_index_tl , + module .tl_set:N = \l__codedoc_cmd_module_tl , + no-index .bool_set:N = \l__codedoc_cmd_noindex_bool , + replace .bool_set:N = \l__codedoc_cmd_replace_bool , + } +\cs_new_protected:Npn \__codedoc_cmd:nn #1#2 + { + \bool_set_false:N \l__codedoc_cmd_noindex_bool + \bool_set_true:N \l__codedoc_cmd_replace_bool + \tl_set:Nn \l__codedoc_cmd_index_tl { \q_no_value } + \tl_set:Nn \l__codedoc_cmd_module_tl { \q_no_value } + \keys_set:nn { l3doc-TUB/cmd } {#1} + \tl_set:Nn \l__codedoc_cmd_tl {#2} + \bool_if:NT \l__codedoc_cmd_replace_bool + { + \tl_set_rescan:Nnn \l__codedoc_tmpb_tl { } { _ } + \tl_replace_all:Non \l__codedoc_cmd_tl \l__codedoc_tmpb_tl { _ } + \__codedoc_replace_at_at:N \l__codedoc_cmd_tl + \tl_replace_all:Nno \l__codedoc_cmd_tl { _ } \l__codedoc_tmpb_tl + } + \mode_if_math:T { \mbox } + { + \verbatim@font + \__codedoc_if_almost_str:VT \l__codedoc_cmd_tl + { + \tl_set:Nx \l__codedoc_cmd_tl { \tl_to_str:N \l__codedoc_cmd_tl } + \tl_replace_all:Non \l__codedoc_cmd_tl + { \token_to_str:N _ } { \_ } + } + \tl_replace_all:Nnn \l__codedoc_cmd_tl { ~ } { \@xobeysp } + \l__codedoc_cmd_tl + \@ + } + \bool_if:NF \l__codedoc_cmd_noindex_bool + { + \quark_if_no_value:NF \l__codedoc_cmd_index_tl + { + \tl_set:Nx \l__codedoc_cmd_tl + { \c_backslash_str \exp_not:o { \l__codedoc_cmd_index_tl } } + } + + \exp_args:No \__codedoc_key_get:n { \l__codedoc_cmd_tl } + \quark_if_no_value:NF \l__codedoc_cmd_module_tl + { + \tl_set:Nx \l__codedoc_index_module_tl + { \tl_to_str:N \l__codedoc_cmd_module_tl } + } + \__codedoc_special_index_module:ooonN + { \l__codedoc_index_key_tl } + { \l__codedoc_index_macro_tl } + { \l__codedoc_index_module_tl } + { usage } + \l__codedoc_index_internal_bool + } + } +\cs_generate_variant:Nn \__codedoc_cmd:nn { no } +\cs_new_protected:Npn \__codedoc_meta:n #1 + { + \tl_set:Nn \l__codedoc_tmpa_tl {#1} + \tl_map_inline:nn + { { 3 } { 4 } { 7 } { 8 } { 11 } { 12 } { 13 } } + { + \tl_set_rescan:Nnn \l__codedoc_tmpb_tl + { \char_set_catcode:nn { `_ } {##1} } { _ } + \tl_replace_all:Non \l__codedoc_tmpa_tl \l__codedoc_tmpb_tl + { \__codedoc_ensuremath_sb:n } + } + \exp_args:NV \__codedoc_meta_original:n \l__codedoc_tmpa_tl + } +\cs_new_protected:Npn \__codedoc_ensuremath_sb:n #1 + { \ensuremath { \sb {#1} } } +\cs_new_protected:Npn \__codedoc_meta_original:n #1 + { + \ensuremath \langle + \mode_if_math:T { \nfss@text } + { + \meta@font@select + \edef \meta@hyphen@restore + { \hyphenchar \the \font \the \hyphenchar \font } + \hyphenchar \font \m@ne + \language \l@nohyphenation + #1 \/ + \meta@hyphen@restore + } + \ensuremath \rangle + } +\cs_new_protected:Npn \__codedoc_typeset_exp: + { \hyperlink{expstar} {$\star$} } +\cs_new_protected:Npn \__codedoc_typeset_rexp: + { \hyperlink{rexpstar} {\ding{73}} } % hollow star +\cs_new_protected:Npn \__codedoc_typeset_TF: + { + \hyperlink{explTF} + { + \color{black} + \itshape TF + \makebox[0pt][r] + { + \color{red} + \underline { \phantom{\itshape TF} \kern-0.1em } + } + } + } +\cs_new_protected:Npn \__codedoc_typeset_aux:n #1 + { + { \color[gray]{0.5} #1 } + } +\cs_new_protected:Npn \__codedoc_get_hyper_target:nN #1#2 + { + \tl_set:Nx #2 { \tl_to_str:n {#1} } + \tl_replace_all:Nxn #2 { \iow_char:N \_ } { / } + \tl_remove_all:Nx #2 { \iow_char:N \\ } + \tl_put_left:Nn #2 { doc/function// } + } +\cs_generate_variant:Nn \__codedoc_get_hyper_target:nN { o , x } +\cs_new_protected:Npn \__codedoc_names_get_seq:nN #1#2 + { + \tl_set:Nx \l__codedoc_tmpa_tl { \tl_to_str:n {#1} } + \bool_if:NTF \l__codedoc_names_verb_bool + { + \seq_clear:N #2 + \seq_put_right:NV #2 \l__codedoc_tmpa_tl + } + { + \tl_remove_all:Nx \l__codedoc_tmpa_tl + { \iow_char:N \^^M \iow_char:N \% } + \tl_remove_all:Nx \l__codedoc_tmpa_tl { \tl_to_str:n { ^ ^ A } } + \tl_remove_all:Nx \l__codedoc_tmpa_tl { \iow_char:N \^^I } + \tl_remove_all:Nx \l__codedoc_tmpa_tl { \iow_char:N \^^M } + \__codedoc_replace_at_at:N \l__codedoc_tmpa_tl + \exp_args:NNx \seq_set_from_clist:Nn #2 + { \tl_to_str:N \l__codedoc_tmpa_tl } + } + } +\cs_new_protected:Npn \__codedoc_names_parse: + { + \tl_clear:N \l__codedoc_names_block_tl + \seq_map_function:NN + \l__codedoc_names_seq + \__codedoc_names_parse_one:n + } +\cs_new_protected:Npn \__codedoc_names_parse_one:n #1 + { + \__codedoc_split_function_do:nn {#1} + { \__codedoc_names_parse_one_aux:nnNn } + {#1} + } +\cs_new_protected:Npn \__codedoc_names_parse_one_aux:nnNn #1#2#3#4 + { + \bool_if:NTF #3 + { + \tl_if_head_eq_charcode:nNTF {#2} : + { \__codedoc_names_parse_aux:nnn {#4} {#4} { \scan_stop: } } + { + \exp_args:Nx \__codedoc_names_parse_aux:nnn + { \__codedoc_base_form_aux:nnN {#1} {#2} #3 } + {#1} {#2} + } + } + { + \bool_if:NT \l__codedoc_macro_TF_bool + { \msg_error:nnx { l3doc-TUB } { no-signature-TF } {#4} } + \__codedoc_names_parse_aux:nnn {#4} {#4} { \scan_stop: } + } + } +\cs_new_protected:Npn \__codedoc_names_parse_aux:nnn #1 + { \exp_args:Nc \__codedoc_names_parse_aux:Nnn { \__codedoc_lseq_name:n {#1} } } +\cs_new_protected:Npn \__codedoc_names_parse_aux:Nnn #1#2#3 + { + \tl_if_in:NnF \l__codedoc_names_block_tl {#1} + { + \tl_put_right:Nn \l__codedoc_names_block_tl {#1} + \seq_clear_new:N #1 + \seq_put_right:Nn #1 {#2} + } + \seq_put_right:Nn #1 {#3} + } +\cs_new_protected:Npn \__codedoc_names_typeset: + { + \tl_map_function:NN \l__codedoc_names_block_tl + \__codedoc_names_typeset_auxi:n + } +\cs_new_protected:Npn \__codedoc_names_typeset_auxi:n #1 + { + \seq_pop:NN #1 \l__codedoc_tmpa_tl + \tl_gset_eq:NN \g__codedoc_base_name_tl \l__codedoc_tmpa_tl + \tl_greplace_all:Nno \g__codedoc_base_name_tl + { ~ } { \c_catcode_other_space_tl } + \seq_get:NN #1 \l__codedoc_tmpa_tl + \str_if_eq:eeTF { \l__codedoc_tmpa_tl } { \scan_stop: } + { + \seq_gclear:N \g__codedoc_variants_seq + \__codedoc_names_typeset_auxii:x { \g__codedoc_base_name_tl } + } + { + \seq_gset_eq:NN \g__codedoc_variants_seq #1 + \seq_gpop:NN \g__codedoc_variants_seq \l__codedoc_tmpb_tl + \__codedoc_names_typeset_auxii:x + { \g__codedoc_base_name_tl : \l__codedoc_tmpb_tl } + } + } +\cs_new_protected:Npn \__codedoc_names_typeset_auxii:n #1 + { + \bool_if:NT \l__codedoc_macro_pTF_bool + { + \__codedoc_names_typeset_block:xN + { \__codedoc_predicate_from_base:n {#1} } + \c_false_bool + } + \bool_if:NT \l__codedoc_macro_noTF_bool + { \__codedoc_names_typeset_block:nN {#1} \c_false_bool } + \__codedoc_names_typeset_block:nN {#1} \l__codedoc_macro_TF_bool + } +\cs_generate_variant:Nn \__codedoc_names_typeset_auxii:n { x } +\cs_new_protected:Npn \__codedoc_names_typeset_block:nN + { + \int_compare:nNnTF \l__codedoc_nested_macro_int = 0 + { \__codedoc_typeset_function_block:nN } + { \__codedoc_macro_typeset_block:nN } + } +\cs_generate_variant:Nn \__codedoc_names_typeset_block:nN { x } +\prg_new_conditional:Npnn \__codedoc_if_macro_internal:n #1 { p , T , F , TF } + { + \bool_if:NTF \l__codedoc_macro_internal_set_bool + { + \bool_if:NTF \l__codedoc_macro_internal_bool + { \prg_return_true: } { \prg_return_false: } + } + { + \tl_if_empty:fTF + { + \exp_after:wN \__codedoc_if_macro_internal_aux:w + \tl_to_str:n { #1 ~ __ } + } + { \prg_return_false: } { \prg_return_true: } + } + } +\exp_last_unbraced:NNNNo + \cs_new:Npn \__codedoc_if_macro_internal_aux:w #1 { \tl_to_str:n { __ } } { } +\cs_new_protected:Npn \__codedoc_names_block_base_map:N #1 + { + \tl_map_inline:Nn \l__codedoc_names_block_tl + { + \group_begin: + \seq_set_eq:NN \l__codedoc_tmpa_seq ##1 + \seq_pop:NN \l__codedoc_tmpa_seq \l__codedoc_tmpa_tl + \seq_get:NN \l__codedoc_tmpa_seq \l__codedoc_tmpb_tl + \exp_args:NNx + \group_end: + #1 + { + \l__codedoc_tmpa_tl + \str_if_eq:eeF { \l__codedoc_tmpb_tl } { \scan_stop: } + { : \l__codedoc_tmpb_tl } + \bool_if:NT \l__codedoc_macro_TF_bool { TF } + } + } + } +\keys_define:nn { l3doc-TUB/function } + { + TF .value_forbidden:n = true , + TF .code:n = + { + \bool_set_true:N \l__codedoc_macro_TF_bool + } , + EXP .value_forbidden:n = true , + EXP .code:n = + { + \bool_set_true:N \l__codedoc_macro_EXP_bool + \bool_set_false:N \l__codedoc_macro_rEXP_bool + } , + rEXP .value_forbidden:n = true , + rEXP .code:n = + { + \bool_set_false:N \l__codedoc_macro_EXP_bool + \bool_set_true:N \l__codedoc_macro_rEXP_bool + } , + pTF .value_forbidden:n = true , + pTF .code:n = + { + \bool_set_true:N \l__codedoc_macro_pTF_bool + \bool_set_true:N \l__codedoc_macro_TF_bool + \bool_set_true:N \l__codedoc_macro_EXP_bool + \bool_set_false:N \l__codedoc_macro_rEXP_bool + } , + noTF .value_forbidden:n = true , + noTF .code:n = + { + \bool_set_true:N \l__codedoc_macro_noTF_bool + \bool_set_true:N \l__codedoc_macro_TF_bool + } , + added .code:n = { \__codedoc_date_set:Nn \l__codedoc_date_added_tl {#1} }, + updated .code:n = { \__codedoc_date_set:Nn \l__codedoc_date_updated_tl {#1} } , + deprecated .code:n = { \__codedoc_deprecated_on:n {#1} } , + tested .code:n = { } , + label .code:n = + { + \clist_set:Nn \l__codedoc_function_label_clist {#1} + \bool_set_true:N \l__codedoc_no_label_bool + } , + verb .value_forbidden:n = true , + verb .bool_set:N = \l__codedoc_names_verb_bool , + module .tl_set:N = \l__codedoc_override_module_tl , + } +\cs_new_protected:Npn \__codedoc_date_set:Nn #1#2 + { + \tl_set:Nn #1 {#2} + \regex_replace_once:nnNF + { \A(\d\d\d\d)[-/](\d\d?)[-/](\d\d?)\Z } { \1-\2-\3 } #1 + { + \msg_error:nnn { l3doc-TUB } { date-format } {#2} + \tl_set:Nn #1 { 1970-01-01 } + } + } +\cs_new_protected:Npn \__codedoc_deprecated_on:n #1 + { + \__codedoc_date_set:Nn \l__codedoc_tmpa_tl {#1} + \exp_args:No \__codedoc_date_compare:nNnT + { \l__codedoc_tmpa_tl } < { \tex_year:D - \tex_month:D - \tex_day:D } + { + \msg_error:nnxx { l3doc-TUB } { deprecated-function } + { \tl_to_str:N \l__codedoc_macro_argument_tl } + { \l__codedoc_tmpa_tl } + } + \bool_set_true:N \l__codedoc_macro_internal_bool + \bool_set_true:N \l__codedoc_macro_internal_set_bool + } +\cs_new_protected:Npn \__codedoc_function:nnw #1#2 + { + \__codedoc_function_typeset_start: + \__codedoc_function_init: + \tl_set:Nn \l__codedoc_macro_argument_tl {#2} + \keys_set:nn { l3doc-TUB/function } {#1} + \__codedoc_names_get_seq:nN {#2} \l__codedoc_names_seq + \__codedoc_names_parse: + \__codedoc_function_typeset: + \__codedoc_function_reset: + \__codedoc_function_descr_start:w + } +\cs_new_protected:Npn \__codedoc_function_end: + { + \__codedoc_function_descr_stop: + \__codedoc_function_assemble: + \__codedoc_function_typeset_stop: + } +\cs_new_protected:Npn \__codedoc_function_typeset_start: + { + \par \bigskip \noindent + } +\cs_new_protected:Npn \__codedoc_function_typeset_stop: + { + \par + \allowbreak + } +\cs_new_protected:Npn \__codedoc_function_init: + { + \box_if_empty:NF \g__codedoc_syntax_box + { \msg_error:nn { l3doc-TUB } { syntax-nested-function } } + \coffin_clear:N \l__codedoc_descr_coffin + \box_gclear:N \g__codedoc_syntax_box + \coffin_clear:N \l__codedoc_syntax_coffin + \coffin_clear:N \l__codedoc_functions_coffin + \bool_set_false:N \l__codedoc_macro_TF_bool + \bool_set_false:N \l__codedoc_macro_pTF_bool + \bool_set_false:N \l__codedoc_macro_noTF_bool + \bool_set_false:N \l__codedoc_macro_EXP_bool + \bool_set_false:N \l__codedoc_macro_rEXP_bool + \bool_set_false:N \l__codedoc_no_label_bool + \bool_set_false:N \l__codedoc_names_verb_bool + \bool_set_true:N \l__codedoc_in_function_bool + \clist_clear:N \l__codedoc_function_label_clist + \tl_set:Nn \l__codedoc_override_module_tl { \q_no_value } + \char_set_active_eq:NN \< \__codedoc_shorthand_meta: + \char_set_catcode_active:N \< + } +\cs_new_protected:Npn \__codedoc_shorthand_meta: + { \mode_if_math:TF { < } { \__codedoc_shorthand_meta:w } } +\cs_new_protected_nopar:Npn \__codedoc_shorthand_meta:w #1 > { \meta {#1} } +\cs_new_protected:Npn \__codedoc_function_reset: + { + \tl_set:Nn \l__codedoc_override_module_tl { \q_no_value } + } +\cs_new_protected:Npn \__codedoc_function_typeset: + { + \dim_zero:N \l__codedoc_trial_width_dim + \hcoffin_set:Nn \l__codedoc_functions_coffin { \__codedoc_typeset_functions: } + \dim_set:Nn \l__codedoc_trial_width_dim + { \box_wd:N \l__codedoc_functions_coffin } + \bool_set:Nn \l__codedoc_long_name_bool + { \dim_compare_p:nNn \l__codedoc_trial_width_dim > {\marginparwidth + 1cm} } % FMi crude fix + } +\cs_new_protected:Npn \__codedoc_function_descr_start:w + { + \vcoffin_set:Nnw \l__codedoc_descr_coffin { \textwidth } + \noindent \ignorespaces + } +\cs_new_protected:Npn \__codedoc_function_descr_stop: + { \vcoffin_set_end: } +\cs_new_protected:Npn \__codedoc_function_assemble: + { + \hcoffin_set:Nn \l__codedoc_syntax_coffin + { \box_use_drop:N \g__codedoc_syntax_box } + \bool_if:NTF \l__codedoc_long_name_bool + { + \coffin_join:NnnNnnnn + \l__codedoc_output_coffin {hc} {vc} + \l__codedoc_syntax_coffin {l} {T} + {0pt} {0pt} + \coffin_join:NnnNnnnn + \l__codedoc_output_coffin {l} {t} + \l__codedoc_functions_coffin {r} {t} + {-\marginparsep} {0pt} + \coffin_join:NnnNnnnn + \l__codedoc_output_coffin {l} {b} + \l__codedoc_descr_coffin {l} {t} + {0.75\marginparwidth + \marginparsep} {-\medskipamount} + \coffin_typeset:Nnnnn \l__codedoc_output_coffin + {\l__codedoc_descr_coffin-l} {\l__codedoc_descr_coffin-t} + {0pt} {0pt} + } + { + \coffin_join:NnnNnnnn + \l__codedoc_output_coffin {hc} {vc} + \l__codedoc_syntax_coffin {l} {t} + {0pt} {0pt} + \coffin_join:NnnNnnnn + \l__codedoc_output_coffin {l} {b} + \l__codedoc_descr_coffin {l} {t} + {0pt} {-\medskipamount} + \coffin_join:NnnNnnnn + \l__codedoc_output_coffin {l} {t} + \l__codedoc_functions_coffin {r} {t} + {-\marginparsep} {0pt} + \coffin_typeset:Nnnnn \l__codedoc_output_coffin + {\l__codedoc_syntax_coffin-l} {\l__codedoc_syntax_coffin-T} + {0pt} {0pt} + } + } +\cs_new_protected:Npn \__codedoc_typeset_functions: + { + \small\ttfamily + \HD@savedestfalse + \HD@target + \Hy@MakeCurrentHref { HD. \int_use:N \c@HD@hypercount } + \begin{tabular} [t] { @{} l @{} >{\hspace{\tabcolsep}} r @{} } + \toprule + \__codedoc_function_extra_labels: + \__codedoc_names_typeset: + \__codedoc_typeset_dates: + \bottomrule + \end{tabular} + \normalfont\normalsize + } +\cs_new_protected:Npn \__codedoc_typeset_function_block:nN #1#2 + { + \__codedoc_function_index:x + { #1 \bool_if:NT #2 { \tl_to_str:n {TF} } } + \__codedoc_function_label:xN {#1} #2 + #1 + \bool_if:NT #2 { \__codedoc_typeset_TF: } + \__codedoc_typeset_expandability: + \seq_if_empty:NF \g__codedoc_variants_seq + { \__codedoc_typeset_variant_list:nN {#1} #2 } + \\ + } +\cs_generate_variant:Nn \__codedoc_typeset_function_block:nN { x } +\cs_new_protected:Npn \__codedoc_function_index:n #1 + { + \seq_gput_right:Nn \g_doc_functions_seq {#1} + \__codedoc_special_index:nn {#1} { usage } + } +\cs_generate_variant:Nn \__codedoc_function_index:n { x } +\cs_new_protected:Npn \__codedoc_typeset_expandability: + { + & + \bool_if:NT \l__codedoc_macro_EXP_bool { \__codedoc_typeset_exp: } + \bool_if:NT \l__codedoc_macro_rEXP_bool { \__codedoc_typeset_rexp: } + } +\cs_new_protected:Npn \__codedoc_typeset_variant_list:nN #1#2 + { + \\ + \__codedoc_typeset_aux:n { \__codedoc_get_function_name:n {#1} } + : + \int_compare:nTF { \seq_count:N \g__codedoc_variants_seq == 1 } + { \seq_use:Nn \g__codedoc_variants_seq { } } + { + \textrm( + \seq_use:Nn \g__codedoc_variants_seq { \textrm| } + \textrm) + } + \bool_if:NT #2 { \__codedoc_typeset_TF: } + \__codedoc_typeset_expandability: + } +\cs_new_protected:Npn \__codedoc_function_extra_labels: + { + \bool_if:NT \l__codedoc_no_label_bool + { + \clist_map_inline:Nn \l__codedoc_function_label_clist + { + \__codedoc_get_hyper_target:oN { \token_to_str:N ##1 } + \l__codedoc_tmpa_tl + \exp_args:No \label { \l__codedoc_tmpa_tl } + } + } + } +\cs_new_protected:Npn \__codedoc_function_label:nN #1#2 + { + \bool_if:NF \l__codedoc_no_label_bool + { + \__codedoc_get_hyper_target:xN + { + \exp_not:n {#1} + \bool_if:NT #2 { \tl_to_str:n {TF} } + } + \l__codedoc_tmpa_tl + \exp_args:No \label { \l__codedoc_tmpa_tl } + } + } +\cs_generate_variant:Nn \__codedoc_function_label:nN { x } +\cs_new:Npn \__codedoc_typeset_dates: + { + \bool_lazy_and:nnF + { \tl_if_empty_p:N \l__codedoc_date_added_tl } + { \tl_if_empty_p:N \l__codedoc_date_updated_tl } + { \midrule } + \tl_if_empty:NF \l__codedoc_date_added_tl + { + \multicolumn { 2 } { @{} r @{} } + { \scriptsize New: \, \l__codedoc_date_added_tl } \\ + } + + \tl_if_empty:NF \l__codedoc_date_updated_tl + { + \multicolumn { 2 } { @{} r @{} } + { \scriptsize Updated: \, \l__codedoc_date_updated_tl } \\ + } + } +\dim_new:N \l__codedoc_syntax_dim +\cs_new_protected:Npn \__codedoc_syntax:w + { + \box_if_empty:NF \g__codedoc_syntax_box + { \msg_error:nn { l3doc-TUB } { multiple-syntax } } + \dim_set:Nn \l__codedoc_syntax_dim + { + \textwidth + \bool_if:NT \l__codedoc_long_name_bool + { + 0.75 \marginparwidth - \l__codedoc_trial_width_dim } + } + \hbox_gset:Nw \g__codedoc_syntax_box + \small \ttfamily + \arrayrulecolor{white} + \begin{tabular} { @{} l @{} } + \toprule + \begin{minipage}[t]{\l__codedoc_syntax_dim} + \raggedright + \obeyspaces + \obeylines + } +\cs_new_protected:Npn \__codedoc_syntax_end: + { + \end{minipage} + \end{tabular} + \arrayrulecolor{black} + \hbox_gset_end: + \bool_if:NF \l__codedoc_in_function_bool + { + \begin{quote} + \mode_leave_vertical: + \box_use_drop:N \g__codedoc_syntax_box + \end{quote} + } + } +\keys_define:nn { l3doc-TUB/macro } + { + aux .value_forbidden:n = true , + aux .code:n = + { + \msg_warning:nnnn { l3doc-TUB } { deprecated-option } + { aux } { function/macro } + } , + internal .value_forbidden:n = true , + internal .code:n = + { + \bool_set_true:N \l__codedoc_macro_internal_bool + \bool_set_true:N \l__codedoc_macro_internal_set_bool + } , + int .value_forbidden:n = true , + int .code:n = + { + \bool_set_true:N \l__codedoc_macro_internal_bool + \bool_set_true:N \l__codedoc_macro_internal_set_bool + } , + var .value_forbidden:n = true , + var .code:n = + { \bool_set_true:N \l__codedoc_macro_var_bool } , + TF .value_forbidden:n = true , + TF .code:n = + { \bool_set_true:N \l__codedoc_macro_TF_bool } , + pTF .value_forbidden:n = true , + pTF .code:n = + { + \bool_set_true:N \l__codedoc_macro_TF_bool + \bool_set_true:N \l__codedoc_macro_pTF_bool + \bool_set_true:N \l__codedoc_macro_EXP_bool + \bool_set_false:N \l__codedoc_macro_rEXP_bool + } , + noTF .value_forbidden:n = true , + noTF .code:n = + { + \bool_set_true:N \l__codedoc_macro_TF_bool + \bool_set_true:N \l__codedoc_macro_noTF_bool + } , + EXP .value_forbidden:n = true , + EXP .code:n = + { + \bool_set_true:N \l__codedoc_macro_EXP_bool + \bool_set_false:N \l__codedoc_macro_rEXP_bool + } , + rEXP .value_forbidden:n = true , + rEXP .code:n = + { + \bool_set_false:N \l__codedoc_macro_EXP_bool + \bool_set_true:N \l__codedoc_macro_rEXP_bool + } , + tested .code:n = + { + \bool_set_true:N \l__codedoc_macro_tested_bool + } , + added .code:n = {} , % TODO + updated .code:n = {} , % TODO + deprecated .code:n = { \__codedoc_deprecated_on:n {#1} } , + verb .bool_set:N = \l__codedoc_names_verb_bool , + module .tl_set:N = \l__codedoc_override_module_tl , + documented-as .tl_set:N = \l__codedoc_macro_documented_tl , + } +\cs_new_protected:Npn \__codedoc_macro:nnw #1#2 + { + \__codedoc_macro_init: + \tl_set:Nn \l__codedoc_macro_argument_tl {#2} + \keys_set:nn { l3doc-TUB/macro } {#1} + \__codedoc_names_get_seq:nN {#2} \l__codedoc_names_seq + \__codedoc_names_parse: + \__codedoc_macro_save_names: + \__codedoc_names_typeset: + \__codedoc_macro_dump: + \__codedoc_macro_reset: + } +\cs_new_protected:Npn \__codedoc_macro_init: + { + \int_incr:N \l__codedoc_nested_macro_int + \bool_set_false:N \l__codedoc_macro_internal_bool + \bool_set_false:N \l__codedoc_macro_internal_set_bool + \bool_set_false:N \l__codedoc_macro_TF_bool + \bool_set_false:N \l__codedoc_macro_pTF_bool + \bool_set_false:N \l__codedoc_macro_noTF_bool + \bool_set_false:N \l__codedoc_macro_EXP_bool + \bool_set_false:N \l__codedoc_macro_rEXP_bool + \bool_set_false:N \l__codedoc_macro_var_bool + \bool_set_false:N \l__codedoc_macro_tested_bool + \bool_set_false:N \l__codedoc_names_verb_bool + \tl_set:Nn \l__codedoc_override_module_tl { \q_no_value } + \tl_clear:N \l__codedoc_macro_documented_tl + \cs_set_eq:NN \testfile \__codedoc_print_testfile:n + \box_clear:N \l__codedoc_macro_index_box + \vbox_set:Nn \l__codedoc_macro_box + { + \hbox:n + { + \strut + \int_compare:nNnT \l__codedoc_macro_int = 0 + { \HD@target } + } + \vskip \int_eval:n { \l__codedoc_macro_int - 1 } \baselineskip + } + } +\cs_new_protected:Npn \__codedoc_macro_reset: + { + \tl_set:Nn \l__codedoc_override_module_tl { \q_no_value } + } +\cs_new_protected:Npn \__codedoc_macro_save_names: + { + \tl_if_empty:NTF \l__codedoc_macro_documented_tl + { \__codedoc_names_block_base_map:N \__codedoc_macro_save_names_aux:n } + { + \seq_gput_right:Nf \g__codedoc_nested_names_seq + { \exp_after:wN \token_to_str:N \l__codedoc_macro_documented_tl } + } + } +\cs_new_protected:Npn \__codedoc_macro_save_names_aux:n #1 + { \seq_gput_right:Nn \g__codedoc_nested_names_seq {#1} } +\cs_new_protected:Npn \__codedoc_macro_dump: + { + \topsep\MacroTopsep + \trivlist + \cs_set:Npn \makelabel ##1 + { + \llap + { + \hbox_unpack_clear:N \l__codedoc_macro_index_box + \vtop to \baselineskip + { + \vbox_unpack_clear:N \l__codedoc_macro_box + \vss + } + } + } + \item [ ] + } +\cs_new_protected:Npn \__codedoc_macro_typeset_block:nN #1#2 + { + \__codedoc_macro_single:nNN {#1} \c_true_bool #2 + \seq_if_empty:NF \g__codedoc_variants_seq + { + \__codedoc_macro_typeset_variant_list:xN + { \__codedoc_get_function_name:n {#1} } #2 + } + } +\cs_generate_variant:Nn \__codedoc_macro_typeset_block:nN { x } +\cs_new_protected:Npn \__codedoc_macro_typeset_variant_list:nN #1#2 + { + \seq_map_inline:Nn \g__codedoc_variants_seq + { \__codedoc_macro_single:nNN { #1 : ##1 } \c_false_bool #2 } + } +\cs_generate_variant:Nn \__codedoc_macro_typeset_variant_list:nN { x } +\cs_new_protected:Npn \__codedoc_macro_single:nNN #1#2#3 + { + \tl_set:Nn \saved@macroname {#1} + \__codedoc_macro_typeset_one:nN {#1} #3 + \bool_if:NT #3 { \DoNotIndex {#1} } + \exp_args:Nx \__codedoc_macro_index:nN + { #1 \bool_if:NT #3 { \tl_to_str:n { TF } } } + #2 + } +\cs_new_protected:Npn \__codedoc_macro_index:nN #1#2 + { + \DoNotIndex {#1} + \bool_if:NT #2 + { + \__codedoc_if_macro_internal:nF {#1} + { \seq_gput_right:Nn \g_doc_macros_seq {#1} } + \hbox_set:Nw \l__codedoc_macro_index_box + \hbox_unpack_clear:N \l__codedoc_macro_index_box + \int_gincr:N \c@CodelineNo + \__codedoc_special_index:nn {#1} { main } + \int_gdecr:N \c@CodelineNo + \exp_args:NNNo \hbox_set_end: + \tl_set:Nn \saved@indexname { \l__codedoc_index_key_tl } + } + } +\cs_new_protected:Npn \__codedoc_macro_typeset_one:nN #1#2 + { + \vbox_set:Nn \l__codedoc_macro_box + { + \vbox_unpack_clear:N \l__codedoc_macro_box + \hbox { \llap { \__codedoc_print_macroname:nN {#1} #2 \ } } + } + \int_incr:N \l__codedoc_macro_int + } +\cs_new_protected:Npn \__codedoc_print_macroname:nN #1#2 + { + \strut + \__codedoc_get_hyper_target:xN + { + \exp_not:n {#1} + \bool_if:NT #2 { \tl_to_str:n {TF} } + } + \l__codedoc_tmpa_tl + \cs_if_exist:cTF { r@ \l__codedoc_tmpa_tl } + { \exp_last_unbraced:NNo \hyperref [ \l__codedoc_tmpa_tl ] } + { \use:n } + { + \int_compare:nTF { \str_count:n {#1} <= 28 } + { \MacroFont } { \MacroLongFont } + \tl_set:Nn \l__codedoc_tmpa_tl {#1} + \tl_replace_all:Nno \l__codedoc_tmpa_tl + { ~ } { \c_catcode_other_space_tl } + \__codedoc_macroname_prefix:o \l__codedoc_tmpa_tl + \__codedoc_macroname_suffix:N #2 + } + } +\cs_new_protected:Npn \__codedoc_macroname_prefix:n #1 + { + \__codedoc_if_macro_internal:nTF {#1} + { \__codedoc_typeset_aux:n {#1} } {#1} + } +\cs_generate_variant:Nn \__codedoc_macroname_prefix:n { o } +\cs_new_protected:Npn \__codedoc_macroname_suffix:N #1 + { \bool_if:NTF #1 { \__codedoc_typeset_TF: } { } } +\providecommand \MacroLongFont + { + \fontfamily{lmtt}\fontseries{lc}\small + } +\cs_new_protected:Npn \__codedoc_print_testfile:n #1 + { + \bool_set_true:N \l__codedoc_macro_tested_bool + \tl_if_eq:nnF {#1} {*} + { + \seq_if_in:NnF \g__codedoc_testfiles_seq {#1} + { + \seq_gput_right:Nn \g__codedoc_testfiles_seq {#1} + \par + \__codedoc_print_testfile_aux:n {#1} + } + } + } +\cs_new_protected:Npn \__codedoc_print_testfile_aux:n #1 + { + \footnotesize + ( + \textit + { + The~ test~ suite~ for~ this~ command,~ + and~ others~ in~ this~ file,~ is~ \textsf{#1} + }. + )\par + } +\DeclareDocumentCommand \TestFiles {m} + { + \par + \textit + { + The~ following~ test~ files~ are~ + used~ for~ this~ code:~ \textsf{#1}. + } + \par \ignorespaces + } +\DeclareDocumentCommand \UnitTested { } { \testfile* } +\DeclareDocumentCommand \TestMissing { m } + { \__codedoc_test_missing:n {#1} } +\cs_new_protected:Npn \__codedoc_test_missing:n #1 + { + \__codedoc_test_missing_aux:Nxn + \g__codedoc_missing_tests_prop + { \seq_use:Nn \l__codedoc_names_seq { , } } + { { \g_file_curr_name_str \iow_char:N \ (#1) } } + } +\cs_new_protected:Npn \__codedoc_test_missing_aux:Nnn #1#2#3 + { + \prop_get:NnNTF #1 {#2} \l__codedoc_tmpa_tl + { \tl_put_right:Nn \l__codedoc_tmpa_tl { , #3 } } + { \tl_set:Nn \l__codedoc_tmpa_tl {#3} } + \prop_put:Nno #1 {#2} \l__codedoc_tmpa_tl + } +\cs_generate_variant:Nn \__codedoc_test_missing_aux:Nnn { Nx } +\cs_new_protected:Npn \__codedoc_macro_end: + { + \endtrivlist + \__codedoc_macro_end_check_tested: + \int_compare:nNnT \l__codedoc_nested_macro_int = 1 + { \__codedoc_macro_end_style:n { \__codedoc_print_end_definition: } } + } +\cs_new_protected:Npn \__codedoc_macro_end_check_tested: + { + \bool_lazy_all:nT + { + { \g__codedoc_checktest_bool } + { ! \l__codedoc_macro_var_bool } + { ! \l__codedoc_macro_tested_bool } + } + { + \seq_set_filter:NNn \l__codedoc_tmpa_seq \l__codedoc_names_seq + { ! \__codedoc_if_macro_internal_p:n {##1} } + \seq_gput_right:Nx \g__codedoc_not_tested_seq + { + \seq_use:Nn \l__codedoc_tmpa_seq { , } + \bool_if:NTF \l__codedoc_macro_pTF_bool {~(pTF)} + { \bool_if:NT \l__codedoc_macro_TF_bool {~(TF)} } + } + } + } +\cs_new_protected:Npn \__codedoc_macro_end_style:n #1 + { + \nobreak \noindent + { \footnotesize ( \emph{#1} ) \par } + } +\cs_new_protected:Npn \__codedoc_macro_end_wrap_item:n #1 + { + \tl_set:Nn \l__codedoc_tmpa_tl {#1} + \tl_replace_all:Non \l__codedoc_tmpa_tl + { \token_to_str:N _ } { \_ } + \texttt { \l__codedoc_tmpa_tl } + } +\cs_new_protected:Npn \__codedoc_print_end_definition: + { + \seq_set_map:NNn \l__codedoc_tmpa_seq + \g__codedoc_nested_names_seq + { \exp_not:n { \__codedoc_macro_end_wrap_item:n {##1} } } + End~ definition~ for~ + \int_compare:nTF { \seq_count:N \l__codedoc_tmpa_seq <= 3 } + { + \seq_use:Nnnn \l__codedoc_tmpa_seq + { \,~and~ } { \,,~ } { \,,~and~ } + } + { \seq_item:Nn \l__codedoc_tmpa_seq {1}\,~and~others } + \@. + \__codedoc_print_documented: + } +\cs_new_protected:Npn \__codedoc_print_documented: + { + \seq_gset_filter:NNn \g__codedoc_nested_names_seq + \g__codedoc_nested_names_seq + { ! \__codedoc_if_macro_internal_p:n {##1} } + \seq_if_empty:NF \g__codedoc_nested_names_seq + { + \int_set:Nn \l__codedoc_tmpa_int + { \seq_count:N \g__codedoc_nested_names_seq } + \int_compare:nNnTF \l__codedoc_tmpa_int = 1 {~This~} {~These~} + \bool_if:NTF \l__codedoc_macro_var_bool {variable} {function} + \int_compare:nNnTF \l__codedoc_tmpa_int = 1 {~is~} {s~are~} + documented~on~page~ + \__codedoc_get_hyper_target:xN + { \seq_item:Nn \g__codedoc_nested_names_seq { 1 } } + \l__codedoc_tmpa_tl + \exp_args:Nx \pageref { \l__codedoc_tmpa_tl } . + } + \seq_gclear:N \g__codedoc_nested_names_seq + } +\newcommand*{\DescribeOption} + { + \leavevmode + \@bsphack + \begingroup + \MakePrivateLetters + \Describe@Option + } +\newcommand*{\Describe@Option}[1] + { + \endgroup + \marginpar{ + \raggedleft + \PrintDescribeEnv{#1} + } + \SpecialOptionIndex{#1} + \@esphack + \ignorespaces + } +\newcommand*{\SpecialOptionIndex}[1] + { + \@bsphack + \begingroup + \HD@target + \let\HDorg@encapchar\encapchar + \edef\encapchar usage + { + \HDorg@encapchar hdclindex{\the\c@HD@hypercount}{usage} + } + \index + { + #1\actualchar{\protect\ttfamily#1}~(option) + \encapchar usage + } + \index + { + options:\levelchar#1\actualchar{\protect\ttfamily#1} + \encapchar usage + } + \endgroup + \@esphack + } +\font \manual = manfnt \scan_stop: +\cs_gset:Npn \dbend { {\manual\char127} } +\newenvironment {danger} + { + \begin{trivlist}\item[]\noindent + \begingroup\hangindent=2pc\hangafter=-2 + \cs_set:Npn \par{\endgraf\endgroup} + \hbox to0pt{\hskip-\hangindent\dbend\hfill}\ignorespaces + } + { + \par\end{trivlist} + } +\newenvironment {ddanger} + { + \begin{trivlist}\item[]\noindent + \begingroup\hangindent=3.5pc\hangafter=-2 + \cs_set:Npn \par{\endgraf\endgroup} + \hbox to0pt{\hskip-\hangindent\dbend\kern2pt\dbend\hfill}\ignorespaces + }{ + \par\end{trivlist} + } +\newenvironment{TemplateInterfaceDescription}[1] + { + \subsection{The~object~type~`#1'} + \begingroup + \@beginparpenalty\@M + \description + \def\TemplateArgument##1##2{\item[Arg:~##1]##2\par} + \def\TemplateSemantics + { + \enddescription\endgroup + \subsubsection*{Semantics:} + } + } + { + \par\bigskip + } +\newenvironment{TemplateDescription}[2] + { + \subsection{The~template~`#2'~(object~type~#1)} + \subsubsection*{Attributes:} + \begingroup + \@beginparpenalty\@M + \description + \def\TemplateKey##1##2##3##4 + { + \item[##1~(##2)]##3% + \ifx\TemplateKey##4\TemplateKey\else + \hfill\penalty500\hbox{}\hfill Default:~##4% + \nobreak\hskip-\parfillskip\hskip0pt\relax + \fi + \par + } + \def\TemplateSemantics + { + \enddescription\endgroup + \subsubsection*{Semantics~\&~Comments:} + } + } + { \par \bigskip } +\newenvironment{InstanceDescription}[4][xxxxxxxxxxxxxxx] + { + \subsubsection{The~instance~`#3'~(template~#2/#4)} + \subsubsection*{Attribute~values:} + \begingroup + \@beginparpenalty\@M + \def\InstanceKey##1##2{\>\textbf{##1}\>##2\\} + \def\InstanceSemantics{\endtabbing\endgroup + \vskip-30pt\vskip0pt + \subsubsection*{Layout~description~\&~Comments:}} + \tabbing + xxxx\=#1\=\kill + } + { \par \bigskip } +\DeclareDocumentCommand \OnlyDescription { } + { \bool_gset_false:N \g__codedoc_typeset_implementation_bool } +\DeclareDocumentCommand \AlsoImplementation { } + { \bool_gset_true:N \g__codedoc_typeset_implementation_bool } +\DeclareDocumentCommand \StopEventually { m } + { + \bool_if:NTF \g__codedoc_typeset_implementation_bool + { + \@bsphack + \tl_gset:Nn \g__codedoc_finale_tl { #1 \check@checksum } + \init@checksum + \@esphack + } + { #1 \endinput } + } +\DeclareDocumentCommand \Finale { } + { \tl_use:N \g__codedoc_finale_tl } +\tl_new:N \g__codedoc_finale_tl +\cs_new_protected:Npn \__codedoc_input:n #1 + { + \tl_gclear:N \g__codedoc_module_name_tl + \MakePercentIgnore + \input{#1} + \MakePercentComment + } +\DeclareDocumentCommand \DocInput { m } + { + \clist_map_inline:nn {#1} + { + \clist_put_right:Nn \g_docinput_clist {##1} + \__codedoc_input:n {##1} + } + } +\DeclareDocumentCommand \DocInputAgain { } + { \clist_map_function:NN \g_docinput_clist \__codedoc_input:n } +\NewDocumentCommand \DocInclude { m } + { + \relax\clearpage + \docincludeaux + \IfFileExists{#1.fdd} + { \cs_set:Npn \currentfile{#1.fdd} } + { \cs_set:Npn \currentfile{#1.dtx} } + \int_compare:nNnTF \@auxout = \@partaux + { \@latexerr{\string\include\space cannot~be~nested}\@eha } + { \@docinclude #1 } + } +\cs_gset:Npn \@docinclude #1 + { + \clearpage + \immediate\write\@mainaux{\string\@input{#1.aux}} + \@tempswatrue + \if@partsw + \@tempswafalse + \cs_set:Npx \@tempb{#1} + \@for\@tempa:=\@partlist\do + { + \ifx\@tempa\@tempb\@tempswatrue\fi + } + \fi + \if@tempswa + \cs_set_eq:NN \@auxout \@partaux + \immediate\openout\@partaux #1.aux + \immediate\write\@partaux{\relax} + \cs_set_eq:NN \@ltxdoc@PrintIndex \PrintIndex + \cs_set_eq:NN \PrintIndex \relax + \cs_set_eq:NN \@ltxdoc@PrintChanges \PrintChanges + \cs_set_eq:NN \PrintChanges \relax + \cs_set_eq:NN \@ltxdoc@theglossary \theglossary + \cs_set_eq:NN \@ltxdoc@endtheglossary \endtheglossary + \part{\currentfile} + { + \cs_set_eq:NN \ttfamily\relax + \cs_gset:Npx \filekey + { \filekey, \thepart = { \ttfamily \currentfile } } + } + \DocInput{\currentfile} + \cs_set_eq:NN \PrintIndex \@ltxdoc@PrintIndex + \cs_set_eq:NN \PrintChanges \@ltxdoc@PrintChanges + \cs_set_eq:NN \theglossary \@ltxdoc@theglossary + \cs_set_eq:NN \endtheglossary \@ltxdoc@endtheglossary + \clearpage + \@writeckpt{#1} + \immediate \closeout \@partaux + \else + \@nameuse{cp@#1} + \fi + \cs_set_eq:NN \@auxout \@mainaux + } +\cs_gset:Npn \codeline@wrindex #1 + { + \immediate\write\@indexfile + { + \string\indexentry{#1} + { \filesep \int_use:N \c@CodelineNo } + } + } +\tl_gclear:N \filesep +\cs_gset:Npn \docincludeaux + { + \tl_set:Nn \thepart { \alphalph { part } } + \tl_set:Nn \filesep { \thepart - } + \cs_set_eq:NN \filekey \use_none:n + \tl_gput_right:Nn \index@prologue + { + \cs_gset:Npn \@oddfoot + { + \parbox { \textwidth } + { + \strut \footnotesize + \raggedright { \bfseries File~Key: } ~ \filekey + } + } + \cs_set_eq:NN \@evenfoot \@oddfoot + } + \cs_gset_eq:NN \docincludeaux \relax + \cs_gset:Npn \@oddfoot + { + \cs_if_exist:cTF { ver @ \currentfile } + { File~\thepart :~{\ttfamily\currentfile}~ } + { + \GetFileInfo{\currentfile} + File~\thepart :~{\ttfamily\filename}~ + Date:~\ExplFileDate\ % space + Version~\ExplFileVersion + } + \hfill \thepage + } + \cs_set_eq:NN \@evenfoot \@oddfoot + } +\group_begin: + \char_set_catcode_other:N \^^A + \char_set_catcode_active:N \^^S + \char_set_catcode_active:N \^^B + \char_set_catcode_other:N \^^L + \char_set_catcode_other:N \^^R + \char_set_lccode:nn { `\^^A } { `\% } + \char_set_lccode:nn { `\^^S } { `\ } + \char_set_lccode:nn { `\^^B } { `\\ } + \char_set_lccode:nn { `\^^L } { `\{ } + \char_set_lccode:nn { `\^^R } { `\} } + \tex_lowercase:D + { + \group_end: + \cs_set_protected:Npn \xmacro@code + #1 ^^A ^^S^^S^^S^^S ^^Bend ^^Lmacrocode^^R + { \__codedoc_xmacro_code:n {#1} \end{macrocode} } + } +\group_begin: + \char_set_catcode_active:N \< + \char_set_catcode_active:N \> + \cs_new_protected:Npn \__codedoc_xmacro_code:n #1 + { + \tl_if_in:nnTF {#1} { < @ @ = } + { \__codedoc_xmacro_code:w #1 \q_stop } + { + \tl_set:Nn \l__codedoc_tmpa_tl {#1} + \__codedoc_replace_at_at:N \l__codedoc_tmpa_tl + \tl_use:N \l__codedoc_tmpa_tl + } + } + \cs_new_protected:Npn \__codedoc_xmacro_code:w #1 < @ @ = #2 > #3 \q_stop + { + \tl_set:Nn \l__codedoc_tmpa_tl {#1} + \__codedoc_replace_at_at:N \l__codedoc_tmpa_tl + + \tl_gset:Nn \g__codedoc_module_name_tl {#2} + \tl_put_right:Nn \l__codedoc_tmpa_tl { < @ @ = #2 > } + + \tl_set:Nn \l__codedoc_tmpb_tl {#3} + \__codedoc_replace_at_at:N \l__codedoc_tmpb_tl + \tl_put_right:No \l__codedoc_tmpa_tl { \l__codedoc_tmpb_tl } + + \tl_use:N \l__codedoc_tmpa_tl + } +\group_end: +\iow_new:N \g__codedoc_func_iow +\tl_new:N \l__codedoc_doc_def_tl +\tl_new:N \l__codedoc_doc_undef_tl +\tl_new:N \l__codedoc_undoc_def_tl +\cs_new_protected:Npn \__codedoc_show_functions_defined: + { + \bool_lazy_and:nnT + { \g__codedoc_typeset_implementation_bool } { \g__codedoc_checkfunc_bool } + { + \iow_term:x { \c__codedoc_iow_separator_tl \iow_newline: } + \iow_open:Nn \g__codedoc_func_iow { \c_sys_jobname_str .cmds } + + \tl_clear:N \l__codedoc_doc_def_tl + \tl_clear:N \l__codedoc_doc_undef_tl + \tl_clear:N \l__codedoc_undoc_def_tl + \seq_map_inline:Nn \g_doc_functions_seq + { + \seq_if_in:NnTF \g_doc_macros_seq {##1} + { + \tl_put_right:Nx \l__codedoc_doc_def_tl + { ##1 \iow_newline: } + \iow_now:Nn \g__codedoc_func_iow { > ~ ##1 } + } + { + \tl_put_right:Nx \l__codedoc_doc_undef_tl + { ##1 \iow_newline: } + \iow_now:Nn \g__codedoc_func_iow { ! ~ ##1 } + } + } + \seq_map_inline:Nn \g_doc_macros_seq + { + \seq_if_in:NnF \g_doc_functions_seq {##1} + { + \tl_put_right:Nx \l__codedoc_undoc_def_tl + { ##1 \iow_newline: } + \iow_now:Nn \g__codedoc_func_iow { ? ~ ##1 } + } + } + \__codedoc_functions_typeout:nN + { + Functions~both~documented~and~defined: \iow_newline: + (In~order~of~being~documented) + } + \l__codedoc_doc_def_tl + \__codedoc_functions_typeout:nN + { Functions~documented~but~not~defined: } + \l__codedoc_doc_undef_tl + \__codedoc_functions_typeout:nN + { Functions~defined~but~not~documented: } + \l__codedoc_undoc_def_tl + + \iow_close:N \g__codedoc_func_iow + \iow_term:x { \c__codedoc_iow_separator_tl } + } + } +\AtEndDocument { \__codedoc_show_functions_defined: } +\cs_new_protected:Npn \__codedoc_functions_typeout:nN #1#2 + { + \tl_if_empty:NF #2 + { + \typeout + { + \c__codedoc_iow_midrule_tl \iow_newline: + #1 \iow_newline: + \c__codedoc_iow_midrule_tl \iow_newline: + #2 + } + \tl_clear:N #2 + } + } +\cs_new_protected:Npn \__codedoc_show_not_tested: + { + \bool_if:NT \g__codedoc_checktest_bool + { + \tl_clear:N \l__codedoc_tmpa_tl + \prop_if_empty:NF \g__codedoc_missing_tests_prop + { + \cs_set:Npn \__codedoc_tmpa:w ##1##2 + { + \iow_newline: + \space\space\space\space \exp_not:n {##1} + \clist_map_function:nN {##2} \__codedoc_tmpb:w + } + \cs_set:Npn \__codedoc_tmpb:w ##1 + { + \iow_newline: + \space\space\space\space\space\space * ~ ##1 + } + \tl_put_right:Nx \l__codedoc_tmpa_tl + { + \iow_newline: \iow_newline: + The~ following~ macro(s)~ have~ incomplete~ tests: + \iow_newline: + \prop_map_function:NN + \g__codedoc_missing_tests_prop \__codedoc_tmpa:w + } + } + \seq_if_empty:NF \g__codedoc_not_tested_seq + { + \cs_set:Npn \__codedoc_tmpa:w ##1 + { \clist_map_function:nN {##1} \__codedoc_tmpb:w } + \cs_set:Npn \__codedoc_tmpb:w ##1 + { + \iow_newline: + \space\space\space\space ##1 + } + \tl_put_right:Nx \l__codedoc_tmpa_tl + { + \iow_newline: + \iow_newline: + The~ following~ macro(s)~ do~ not~ have~ any~ tests: + \iow_newline: + \seq_map_function:NN + \g__codedoc_not_tested_seq \__codedoc_tmpa:w + } + } + \tl_if_empty:NF \l__codedoc_tmpa_tl + { + \int_set:Nn \l__codedoc_tmpa_int { \etex_interactionmode:D } + \errorstopmode + \ClassError { l3doc-TUB } { \l__codedoc_tmpa_tl } { } + \int_set:Nn \etex_interactionmode:D { \l__codedoc_tmpa_int } + } + } + } +\AtEndDocument { \__codedoc_show_not_tested: } +\g@addto@macro \theindex { \MakePrivateLetters } +\cs_gset:Npn \verbatimchar {&} +\setcounter { IndexColumns } { 2 } +\IndexPrologue + { + \section*{Index} + \markboth{Index}{Index} + \addcontentsline{toc}{section}{Index} + The~italic~numbers~denote~the~pages~where~the~ + corresponding~entry~is~described,~ + numbers~underlined~point~to~the~definition,~ + all~others~indicate~the~places~where~it~is~used. + } +\cs_gset_protected:Npn \SpecialIndex #1 + { + \@bsphack + \__codedoc_special_index:nn {#1} { } + \@esphack + } +\msg_new:nnn { l3doc-TUB } { print-index-howto } + { + Generate~the~index~by~executing\\ + \iow_indent:n + { makeindex~-s~gind.ist~-o~\c_sys_jobname_str.ind~\c_sys_jobname_str.idx } + } +\tl_gput_right:Nn \PrintIndex + { \AtEndDocument { \msg_info:nn { l3doc-TUB } { print-index-howto } } } +\cs_gset_protected:Npn \it@is@a #1 + { + \use:x + { + \__codedoc_special_index_module:nnnnN + {#1} + { \bslash #1 } + { } + { } + \c_false_bool + } + } +\cs_new_protected:Npn \__codedoc_special_index:nn #1#2 + { + \__codedoc_key_get:n {#1} + \quark_if_no_value:NF \l__codedoc_override_module_tl + { \tl_set_eq:NN \l__codedoc_index_module_tl \l__codedoc_override_module_tl } + \__codedoc_special_index_module:ooonN + { \l__codedoc_index_key_tl } + { \l__codedoc_index_macro_tl } + { \l__codedoc_index_module_tl } + {#2} + \l__codedoc_index_internal_bool + } +\cs_generate_variant:Nn \__codedoc_special_index:nn { o } +\tl_new:N \l__codedoc_index_escaped_macro_tl +\tl_new:N \l__codedoc_index_escaped_key_tl +\cs_new_protected:Npn \__codedoc_special_index_module:nnnnN #1#2#3#4#5 + { + \use:x + { + \exp_not:n { \__codedoc_special_index_aux:nnnnnn {#1} {#2} } + \tl_if_empty:nTF {#3} + { { } { } { } } + { + \str_if_eq:eeTF {#3} { TeX } + { + { TeX~and~LaTeX2e } + { \string\TeX{}~and~\string\LaTeXe{} } + } + { + {#3} + { \string\pkg{#3} } + } + { \bool_if:NT #5 { ~internal } ~commands: } + } + } + {#4} + } +\cs_generate_variant:Nn \__codedoc_special_index_module:nnnnN { ooo } +\cs_new_protected:Npn \__codedoc_special_index_aux:nnnnnn #1#2#3#4#5#6 + { + \tl_set:Nn \l__codedoc_index_escaped_key_tl {#1} + \__codedoc_quote_special_char:N \l__codedoc_index_escaped_key_tl + \__codedoc_special_index_set:Nn \l__codedoc_index_escaped_macro_tl {#2} + \str_if_eq:onTF { \@currenvir } { macrocode } + { \codeline@wrindex } + { + \str_case:nnF {#6} + { + { main } { \codeline@wrindex } + { usage } { \index } + } + { \HD@target \index } + } + { + \tl_if_empty:nF { #3 #4 #5 } + { #3 #5 \actualchar #4 #5 \levelchar } + \l__codedoc_index_escaped_key_tl + \actualchar + { + \token_to_str:N \verbatim@font \c_space_tl + \l__codedoc_index_escaped_macro_tl + } + \encapchar + hdclindex{\the\c@HD@hypercount}{#6} + } + } +\cs_new_protected:Npn \__codedoc_special_index_set:Nn #1#2 + { + \tl_set:Nx #1 { \tl_to_str:n {#2} } + \__codedoc_if_almost_str:nTF {#2} + { + \tl_replace_all:Non #1 { \tl_to_str:n { __ } } + { + \verbatimchar + \token_to_str:N \_ \token_to_str:N \_ + \token_to_str:N \verb * \verbatimchar + } + \exp_args:Nx \tl_map_inline:nn + { \tl_to_str:N \verbatimchar \token_to_str:N _ } + { + \tl_replace_all:Nnn #1 {##1} + { + \verbatimchar \c__codedoc_backslash_tl ##1 + \token_to_str:N \verb * \verbatimchar + } + } + \tl_set:Nx #1 + { + \token_to_str:N \verb * \verbatimchar + #1 \verbatimchar + } + } + { + \tl_set:Nn #1 {#2} + \tl_replace_all:Non #1 + { \c__codedoc_backslash_tl } + { \token_to_str:N \bslash \c_space_tl } + } + \__codedoc_quote_special_char:N #1 + } +\cs_new_protected:Npn \__codedoc_quote_special_char:N #1 + { + \tl_map_inline:nn { \quotechar \actualchar \encapchar \levelchar } + { + \tl_replace_all:Nxn #1 + { \tl_to_str:N ##1 } { \quotechar \tl_to_str:N ##1 } + } + } +\cs_new_protected:Npn \__codedoc_key_get:n #1 + { + \__codedoc_key_get_base:nN {#1} \l__codedoc_index_macro_tl + \tl_set:Nx \l__codedoc_index_key_tl + { \tl_to_str:N \l__codedoc_index_macro_tl } + \tl_clear:N \l__codedoc_index_module_tl + \tl_if_in:NoTF \l__codedoc_index_key_tl { \tl_to_str:n { __ } } + { \bool_set_true:N \l__codedoc_index_internal_bool } + { \bool_set_false:N \l__codedoc_index_internal_bool } + \tl_if_head_eq_charcode:oNT + { \l__codedoc_index_key_tl } \c__codedoc_backslash_token + { \__codedoc_key_pop: } + \tl_if_in:NoTF \l__codedoc_index_key_tl { \token_to_str:N : } + { \__codedoc_key_func: } + { + \tl_if_in:NoTF \l__codedoc_index_key_tl { \token_to_str:N _ } + { \__codedoc_key_var: } + { + \tl_if_in:NoT \l__codedoc_index_key_tl { \token_to_str:N @ } + { \tl_set:Nn \l__codedoc_index_module_tl { TeX } } + } + } + } +\cs_new_protected:Npn \__codedoc_key_pop: + { + \tl_set:Nx \l__codedoc_index_key_tl + { \tl_tail:N \l__codedoc_index_key_tl } + } +\cs_new_protected:Npn \__codedoc_key_trim_module:n #1 + { + \cs_set:Npn \__codedoc_tmpa:w ##1 #1 ##2 \q_stop + { \exp_not:n {##1} } + \tl_set:Nx \l__codedoc_index_module_tl + { \exp_after:wN \__codedoc_tmpa:w \l__codedoc_index_module_tl #1 \q_stop } + } +\cs_new_protected:Npn \__codedoc_key_drop_underscores: + { + \tl_if_head_eq_charcode:oNT { \l__codedoc_index_key_tl } _ + { \__codedoc_key_pop: \__codedoc_key_drop_underscores: } + } +\cs_new_protected:Npn \__codedoc_key_func: + { + \tl_if_head_eq_charcode:oNT { \l__codedoc_index_key_tl } . + { \__codedoc_key_pop: } + \__codedoc_key_drop_underscores: + \tl_set_eq:NN \l__codedoc_index_module_tl \l__codedoc_index_key_tl + \exp_args:No \__codedoc_key_trim_module:n { \token_to_str:N : } + \exp_args:No \__codedoc_key_trim_module:n { \token_to_str:N _ } + } +\cs_new_protected:Npn \__codedoc_key_var: + { + \exp_args:Nx \tl_if_head_eq_charcode:nNTF + { \exp_args:No \str_tail:n \l__codedoc_index_key_tl } _ + { + \str_case:fn { \str_head:N \l__codedoc_index_key_tl } + { + { q } { \tl_set:Nn \l__codedoc_index_module_tl { quark } } + { s } { \tl_set:Nn \l__codedoc_index_module_tl { quark } } + } + \__codedoc_key_pop: + \__codedoc_key_pop: + \__codedoc_key_drop_underscores: + \tl_if_empty:NT \l__codedoc_index_module_tl + { + \seq_set_split:NoV \l__codedoc_tmpa_seq + { \token_to_str:N _ } \l__codedoc_index_key_tl + \tl_set:Nx \l__codedoc_index_module_tl + { + \int_case:nnF { \seq_count:N \l__codedoc_tmpa_seq } + { + { 0 } { } + { 1 } { int } + { 2 } { \seq_item:Nn \l__codedoc_tmpa_seq { 2 } } + } + { \seq_item:Nn \l__codedoc_tmpa_seq { 1 } } + } + } + } + { + \tl_set_eq:NN \l__codedoc_index_module_tl \l__codedoc_index_key_tl + \exp_args:No \__codedoc_key_trim_module:n { \token_to_str:N _ } + } + } +\GlossaryPrologue + { + \part*{Change~History} + {\GlossaryParms\ttfamily\hyphenchar\font=`\-} + \markboth{Change~History}{Change~History} + \addcontentsline{toc}{part}{Change~History} + } +\msg_new:nnn { l3doc-TUB } { print-changes-howto } + { + Generate~the~change~list~by~executing\\ + \iow_indent:n + { makeindex~-s~gglo.ist~-o~\c_sys_jobname_str.gls~\c_sys_jobname_str.glo } + } +\tl_gput_right:Nn \PrintChanges + { \AtEndDocument { \msg_info:nn { l3doc-TUB } { print-changes-howto } } } +\bool_if:NTF \g__codedoc_typeset_implementation_bool + { + \RecordChanges + \CodelineIndex + \EnableCrossrefs + \AlsoImplementation + } + { + \CodelineNumbered + \DisableCrossrefs + \OnlyDescription + } + +%%FMi + +\def\maketitle{\@ifstar + {\@articletitlefalse\@r@maketitle}% + {\@articletitletrue\@r@maketitle}% +} + +%% +%% +%% End of file `l3doc-TUB.cls'. diff --git a/macros/latex/contrib/glossaries-extra/CHANGES b/macros/latex/contrib/glossaries-extra/CHANGES index 922ea958be..72ab865c70 100644 --- a/macros/latex/contrib/glossaries-extra/CHANGES +++ b/macros/latex/contrib/glossaries-extra/CHANGES @@ -1,3 +1,123 @@ +1.42 (2020-02-13): + + * glossaries-extra.sty: + + - added support for glossaries.sty 'disablemakegloss' option + (introduced to glossaries.sty v4.45). + + - new package option 'prefix' automatically loads glossaries-prefix.sty + + - added warnings if \forallacronyms, \acrshort etc are used with + new abbreviation interface. + + - added warning if order=letter used with record=only or record=nameref + + - added check for existence of \alsoname + + - changed \glsseeitemformat, \glsxtrhiername, \Glsxtrhiername, + \GlsXtrhiername, \GLSxtrhiername, \GLSXTRhiername + to use \glsfmtname and \glsfmttext (or case-variants) + to ensure formatting is applied. + + - \glsfmtfull and \Glsfmtfull PDF case now use \glspdffmtfull + + - \glsfmtfullpl and \Glsfmtfullpl PDF case now use \glspdffmtfullpl + + - added missing text key to long-short, short-long, footnote, + postfootnote, long-short-sc, short-sc-long, short-sc-footnote, + short-sc-postfootnote, long-short-sm, short-sm-long, + short-sm-footnote, short-sm-postfootnote, long-short-em, + long-em-short-em, short-em-long, short-em-long-em, + short-em-footnote, short-em-postfootnote, long-short-user, + long-postshort-user, short-postlong-user, short-long-user, + long-hyphen-noshort-desc-noreg, long-hyphen-postshort-hyphen, + short-hyphen-long-hyphen, short-hyphen-postlong-hyphen + styles. + + - new abbreviation styles: short-footnote-desc (and synonym + footnote-desc), short-postfootnote-desc (and synonym + postfootnote-desc), short-sc-footnote-desc, + short-sc-postfootnote-desc, short-sm-footnote-desc, + short-sm-postfootnote-desc, short-em-footnote-desc, + short-em-postfootnote-desc. + + - added glosssymbolfont attribute + + - \glossentrysymbol: added check for \texorpdfstring (the TeX + inner part is now robust) + + - new entry formatting commands: + + \glspdffmtfull, \glspdffmtfullpl, + \GLSfmtname, \GLSfmttext, \GLSfmtplural, \GLSfmtfirst, \GLSfmtfirstpl, + \GLSfmtlong, \GLSfmtlongpl, \GLSfmtfull, \GLSfmtfullpl + \GLSxtrtitleshort, \GLSxtrtitleshortpl, \GLSxtrtitlename, + \GLSxtrtitletext, \GLSxtrtitleplural, \GLSxtrtitlefirst, + \GLSxtrtitlefirstplural, \GLSxtrtitlelong, \Glsxtrtitlelongpl, + \GLSxtrtitlefull, \GLSxtrtitlefullpl, + \glsxtrpdfentryfmt (used by \glsxtrentryfmt in PDF bookmarks) + + - new entry referencing command: \glsentrypdfsymbol + + - new cross-referencing command: \glsxtrusealias + + - new buffering command: \GlsXtrDiscardUnsetBuffering + + - new list commands: + + \glsxtrfieldformatlist + \glsxtrfieldformatcsvlist + \GlsXtrIfFieldValueInCsvList + \forallabbreviationlists + + - Bug fixes: + + - corrected interference caused by 'acronym'/'acronyms' + package option with abbreviation display style + + - moved \protect inside \glsxtrscsuffix (otherwise it + interferes with all caps) + + - corrected missing space factor with 'insertdots' attribute + + - \glslink with record was causing an undefined control + sequence error (\glslabel) in the post-link hook when + entries are undefined + + - restored original definition of \glsdohyperlink and + added \glsxtrdohyperlink to reference attributes instead. + + - \GlsXtrSetAltModifier now has a check to ensure '*' or '+' + haven't been used as the alternative modifier. + + - corrected accessibility support for abbreviations + + - redefine \@gls@entry@field so that it uses \csuse instead of + \csname (in the event commands like \glsentrytext are used + in captions or section headings with bib2gls) + + * glossaries-extra-bib2gls.sty: + + - \glsxtrdisplaylocnameref now checks for the existence of + \glsxtrlocfmt + + - New command: \glsxtrequationlocfmt + + - Redefined \glsdisplaynumberlist and \glsentrynumberlist + to work with bib2gls + + * glossary-bookindex.sty: + + - replaced hardcoded 'index.' prefix in pdfbookmark with + new command \glsxtrbookindexbookmarkprefix + + * glossaries-extra-stylemods.sty: + + - new commands: + + \glstreeNoDescSymbolPreLocation + \glstreegroupheaderskip + 1.41 (2019-04-09): * glossary-topic.sty: diff --git a/macros/latex/contrib/glossaries-extra/README b/macros/latex/contrib/glossaries-extra/README index 6f39a09e00..618f8951da 100644 --- a/macros/latex/contrib/glossaries-extra/README +++ b/macros/latex/contrib/glossaries-extra/README @@ -1,8 +1,17 @@ -LaTeX Package : glossaries-extra v1.41 - -Last Modified : 2019-04-09 +LaTeX Package : glossaries-extra v1.42 (2020-02-13) Author : Nicola Talbot + https://www.dickimaw-books.com/contact + +LICENCE + +This material is subject to the LaTeX Project Public License. +See http://www.ctan.org/license/lppl1.3 +for the details of that license. + +Copyright 2015-2020 Nicola Talbot + +DESCRIPTION This package provides improvements and extra features to the glossaries package. Some of the default glossaries.sty behaviour @@ -18,11 +27,7 @@ minimal working examples for testing the glossaries-extra package. (The base glossaries package provides additional files, but this one needs glossaries-extra.sty.) -LICENCE - -This material is subject to the LaTeX Project Public License. -See http://www.ctan.org/license/lppl1.3 -for the details of that license. - -Author's home page: http://www.dickimaw-books.com/ +SEE ALSO: +https://ctan.org/pkg/glossaries +https://ctan.org/pkg/bib2gls diff --git a/macros/latex/contrib/glossaries-extra/glossaries-extra-code.pdf b/macros/latex/contrib/glossaries-extra/glossaries-extra-code.pdf index 8272e2c862..34dea1ecae 100644 Binary files a/macros/latex/contrib/glossaries-extra/glossaries-extra-code.pdf and b/macros/latex/contrib/glossaries-extra/glossaries-extra-code.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.html b/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.html index bf636b8fa4..a03a84c694 100644 --- a/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.html +++ b/macros/latex/contrib/glossaries-extra/glossaries-extra-manual.html @@ -61,10 +61,11 @@ .cmtt-8{font-family: monospace;} .cmtt-8{font-family: monospace;} .cmti-8{font-size:80%; font-style: italic;} -p.noindent { text-indent: 0em } -td p.noindent { text-indent: 0em; margin-top:0em; } -p.nopar { text-indent: 0em; } -p.indent{ text-indent: 1.5em } +p{margin-top:0;margin-bottom:0} +p.indent{text-indent:0;} +p + p{margin-top:1em;} +p + div, p + pre {margin-top:1em;} +div + p, pre + p {margin-top:1em;} @media print {div.crosslinks {visibility:hidden;}} a img { border-top: 0; border-left: 0; border-right: 0; } center { margin-top:1em; margin-bottom:1em; } @@ -87,7 +88,7 @@ div.obeylines-v p { margin-top:0; margin-bottom:0; } td.displaylines {text-align:center; white-space:nowrap;} .centerline {text-align:center;} .rightline {text-align:right;} -div.verbatim {font-family: monospace; white-space: nowrap; text-align:left; clear:both; } +div.verbatim {font-family: monospace,monospace; white-space: nowrap; text-align:left; clear:both; } .fbox {padding-left:3.0pt; padding-right:3.0pt; text-indent:0pt; border:solid black 0.4pt; } div.fbox {display:table} div.center div.fbox {text-align:center; clear:both; padding-left:3.0pt; padding-right:3.0pt; text-indent:0pt; border:solid black 0.4pt; } @@ -122,7 +123,9 @@ td.td01{ padding-left:0pt; padding-right:5pt; } td.td10{ padding-left:5pt; padding-right:0pt; } td.td11{ padding-left:5pt; padding-right:5pt; } table[rules] {border-left:solid black 0.4pt; border-right:solid black 0.4pt; } -.hline hr, .cline hr{ height : 1px; margin:0px; } +.hline hr, .cline hr{ height : 0px; margin:0px; } +.hline td, .cline td{ padding: 0; } +.hline hr, .cline hr{border:none;border-top:1px solid black;} .tabbing-right {text-align:right;} span.TEX {letter-spacing: -0.125em; } span.TEX span.E{ position:relative;top:0.5ex;left:-0.0417em;} @@ -132,8 +135,9 @@ span.LATEX span.TEX{ position:relative; left: -0.4em; } div.float, div.figure {margin-left: auto; margin-right: auto;} div.float img {text-align:center;} div.figure img {text-align:center;} -.marginpar {width:20%; float:right; text-align:left; margin-left:auto; margin-top:0.5em; font-size:85%; text-decoration:underline;} -.marginpar p{margin-top:0.4em; margin-bottom:0.4em;} +.marginpar,.reversemarginpar {width:20%; float:right; text-align:left; margin-left:auto; margin-top:0.5em; font-size:85%; text-decoration:underline;} +.marginpar p,.reversemarginpar p{margin-top:0.4em; margin-bottom:0.4em;} +.reversemarginpar{float:left;} table.equation {width:100%;} .equation td{text-align:center; } td.equation { margin-top:1em; margin-bottom:1em; } @@ -188,7 +192,9 @@ table.gather {width:100%;} div.gather-star {text-align:center;} table[rules] {border-left:solid black 0.4pt; border-right:solid black 0.4pt; } div.longtable{text-align:center;} +table.longtable{margin-left:auto; margin-right: auto;} .supertabular {text-align:center} +.warningsymbol { color: red; font-weight: bold;} div.important { border : solid red; } div.verbatim { font-family: monospace; white-space: nowrap; text-align:left; clear:both; padding-top: 2ex; padding-bottom: 2ex;} span.HoLogo-XeLaTeX span.HoLogo-Xe{margin-right:-.13em;} @@ -218,7 +224,7 @@ a span.HoLogo-TeX span.HoLogo-e{text-decoration:none;} >

glossaries-extra.sty v1.41: an extension to the +class="cmr-17">glossaries-extra.sty v1.42: an extension to the glossaries package

@@ -242,7 +248,7 @@ href="http://www.dickimaw-books.com/" class="url" >http://www.dickimaw-books.com/

2019-04-09

+class="cmr-12">2020-02-13

@@ -265,9 +271,9 @@ class="cmss-10">glossaries version 4.19 (or above). This document assumes glossaries package.

The file example-glossaries-xr.tex contains dummy entries with cross-references -that may be used for creating minimal working examples for testing the -example-glossaries-xr.tex contains dummy entries with +cross-references that may be used for creating minimal working examples for testing +the glossaries-extra package. (The base glossaries package provides additional files, but this one needs New or Modified Package Options
2 Modifications to Existing Commands and Styles
 2.1 Entry Indexing +href="#definingentries" id="QQ2-1-6">Defining Entries
 2.2 Cross-References (“see” and “see also”) +href="#sec:wrglossary" id="QQ2-1-7">Entry Indexing
 2.3 Entry Display Style Modifications +href="#sec:see" id="QQ2-1-8">Cross-References (“see” and “see also”)
 2.4 Entry Counting Modifications +href="#sec:entryfmtmods" id="QQ2-1-9">Entry Display Style Modifications
 2.5 First Use Flag +href="#sec:entrycountmods" id="QQ2-1-10">Entry Counting Modifications
 2.6 Plurals +href="#sec:glsunset" id="QQ2-1-11">First Use Flag
 2.7 Nested Links +href="#plurals" id="QQ2-1-12">Plurals
 2.8 Acronym Style Modifications +href="#sec:nested" id="QQ2-1-13">Nested Links
 2.9 glossary-bookindex package +href="#sec:acronymmods" id="QQ2-1-14">Acronym Style Modifications
 2.10 glossary-longextra package -
 2.11 glossary-topic package -
 2.12 Glossary Style Modifications -
  2.12.1 Style Hooks -
  2.12.2 Number List -
  2.12.3 The glossaries-extra-stylemods Package +href="#glossaries" id="QQ2-1-16">Glossaries +
  2.10.1 Glossary Style Modifications
3 Abbreviations +href="#newglossarystyles" id="QQ2-1-21">New Glossary Styles
 3.1 Tagging Initials +href="#x1-210003.1" id="QQ2-1-22">glossary-bookindex package
 3.2 Abbreviation Styles +href="#x1-220003.2" id="QQ2-1-23">glossary-longextra package
 3.3 Shortcut Commands -
 3.4 Predefined Abbreviation Styles -
  3.4.1 Predefined Abbreviation Styles that Set the Regular Attribute -
  3.4.2 Predefined Abbreviation Styles that Don’t Set the Regular Attribute -
 3.5 Defining New Abbreviation Styles +href="#x1-230003.3" id="QQ2-1-24">glossary-topic package
4 Entries in Sectioning Titles, Headers, Captions and Contents +href="#sec:abbreviations" id="QQ2-1-25">Abbreviations +
 4.1 Tagging Initials +
 4.2 Abbreviation Styles +
 4.3 Shortcut Commands +
 4.4 Predefined Abbreviation Styles +
  4.4.1 Predefined Abbreviation Styles that Set the Regular Attribute +
  4.4.2 Predefined Abbreviation Styles that Don’t Set the Regular Attribute +
 4.5 Defining New Abbreviation Styles
5 Categories +href="#sec:headtitle" id="QQ2-1-34">Entries in Sectioning Titles, Headers, Captions and Contents +
 5.1 Simplistic Approach +
 5.2 New Commands Designed for Chapter/Section Headings
6 Counting References -
 6.1 Entry Counting (First Use Flag) -
 6.2 Link Counting +href="#sec:categories" id="QQ2-1-37">Categories
7 Auto-Indexing +href="#sec:countref" id="QQ2-1-38">Counting References +
 7.1 Entry Counting (First Use Flag) +
 7.2 Link Counting
8 On-the-Fly Document Definitions -
9 bib2gls: Managing Reference Databases +href="#sec:autoindex" id="QQ2-1-41">Auto-Indexing +
9 bib2gls: Managing Reference Databases
 9.1 Selection +href="#selection" id="QQ2-1-43">Selection
 9.2 Sorting and Displaying the Glossary +href="#sortinganddisplayingtheglossary" id="QQ2-1-44">Sorting and Displaying the Glossary
 9.3 The The glossaries-extra-bib2gls package
  9.3.1 Supplemental Locations +href="#sec:supplocations" id="QQ2-1-46">Supplemental Locations
  9.3.2 Nameref Record +href="#sec:recordnameref" id="QQ2-1-47">Nameref Record
  9.3.3 Helper Commands for Resource Options +href="#sec:resourcecommands" id="QQ2-1-48">Helper Commands for Resource Options
 9.4 Supplementary Commands +href="#supplementarycommands" id="QQ2-1-49">Supplementary Commands
 9.5 Record Counting +href="#sec:recordcount" id="QQ2-1-50">Record Counting
10 Miscellaneous New Commands +href="#sec:miscnew" id="QQ2-1-51">Miscellaneous New Commands
 10.1 Entry Fields +href="#sec:fields" id="QQ2-1-52">Entry Fields
 10.2 Display All Entries Without Sorting or Indexing +href="#sec:printunsrt" id="QQ2-1-53">Display All Entries Without Sorting or Indexing
 10.3 Standalone Entry Items +href="#sec:glossentry" id="QQ2-1-54">Standalone Entry Items
 10.4 Entry Aliases +href="#sec:alias" id="QQ2-1-55">Entry Aliases
11 Supplemental Packages -
 11.1 Prefixes or Determiners -
 11.2 Accessibility Support +href="#sec:onthefly" id="QQ2-1-56">On-the-Fly Document Definitions
12 Sample Files +href="#sec:supplemental" id="QQ2-1-57">Supplemental Packages +
 12.1 Prefixes or Determiners +
 12.2 Accessibility Support
13 Multi-Lingual Support +href="#sec:samples" id="QQ2-1-60">Sample Files +
14 Multi-Lingual Support
Glossary

@@ -803,7 +812,7 @@ class="cmtt-10">\setabbreviationstyle before \newacronym. See §3 §4 Abbreviations for further details.)

@@ -880,9 +889,7 @@ href="#styopt.debug">debug=true and uses -


\glsxtrwrglossmark 


\glsxtrwrglossmark

@@ -1060,29 +1067,42 @@ class="cmtt-10">loc-prefix which will only apply if the entry has a number list.)

+prefix
Load the glossaries-prefix package (if not already loaded). +
accsupp
Load the glossaries-accsupp package (if not already loaded). -

If you want to define styles that can interface with the accessibility support + id="dx1-4036"> package (if not already loaded). +

The glossaries-accsupp package 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-accsupp use the use the \glsaccessxxx⟩ type of commands instead of \glsentryxxx⟩ (for example, \glsaccesstext instead of + id="dx1-4039"> instead of \glsentrytext). If ). If glossaries-accsupp hasn’t been loaded those commands are + id="dx1-4041"> hasn’t been loaded those commands are equivalent (for example, \glsaccesstext just does \glsentrytext) but if it @@ -1091,101 +1111,101 @@ class="cmtt-10">\glsaccessxxx⟩ commands will add the accessibility information. (See §11.2 §12.2 Accessibility Support for further details.) -

Note that the

Note that the accsupp option can only be used as a package option (and can’t + id="dx1-4042"> option can only be used as a package option (and can’t be set with \glossariesextrasetup) since the ) since the glossaries-accsupp package must + id="dx1-4044"> package must be loaded before glossaries-extra if it’s required.

stylemods
This is a ⟨key⟩=⟨value⟩ option used to load the glossaries-extra-stylemods + id="dx1-4046"> 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.12 §2.10.1 Glossary Style Modifications for further details. There are two special keyword values: stylemods=default (equivalent to omitting the value) and (equivalent to omitting the value) and stylemods=all, which + id="dx1-4048">, which loads all the predefined styles.
undefaction
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 undefaction=error, which produces an error message (the + id="dx1-4050">, which produces an error message (the default for glossaries). You can switch this to a warning message (and ?? appearing in the text) with undefaction=warn. -

Undefined entries can’t be picked up by any commands that iterate + id="dx1-4051">. +

Undefined entries can’t be picked up by any commands that iterate over a glossary list. This includes \forglsentries and and \glsaddall. + id="dx1-4053">.
- - - -

-

Note that

+

Note that \ifglsused will display ?? in the document text with + id="dx1-4054"> will display ?? in the document text with undefaction=warn if the entry hasn’t been defined, as the underlying boolean + id="dx1-4055"> 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.5 §2.6 First Use Flag for further details.

indexcrossrefs
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 @@ -1194,65 +1214,65 @@ class="cmss-10">true, this will automatically index any class="cmss-10">false, but it will be automatically switched on if you use the see or or seealso keys + id="dx1-4058"> keys in any entries (unless autoseeindex=false). To force it off, even if you + id="dx1-4059">). To force it off, even if you use the see or or seealso key, you need to explicitly set key, you need to explicitly set indexcrossrefs to + id="dx1-4062"> to false. -

Note that

Note that bib2gls can automatically find dependent entries when it parses the .bib source file. The record option automatically implements + id="dx1-4064"> option automatically implements indexcrossrefs=false. + id="dx1-4065">.

autoseeindex
(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 + 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=only option automatically implements option automatically implements autoseeindex=false. -

For example, if an entry is defined as + id="dx1-4070">. +

For example, if an entry is defined as @@ -1260,7 +1280,7 @@ class="cmss-10">=false \newglossaryentry{foo}{name={foo},description={},see={bar,baz}}

-

then with

then with autoseeindex=true, this is equivalent to @@ -1272,7 +1292,7 @@ class="cmtt-10">autoseeindex=true, this is equivalent to  
\glossariesextrasetup{indexcrossrefs=true}  
\GlsXtrSetField{foo}{see}{bar,baz} -

but with

but with autoseeindex=false, this is equivalent to @@ -1282,19 +1302,19 @@ class="cmtt-10">autoseeindex=false, this is equivalent to \newglossaryentry{foo}{name={foo},description={}}  
\GlsXtrSetField{foo}{see}{bar,baz} -

Note that

Note that indexcrossrefs isn’t automatically implemented by the presence of the + id="dx1-4071"> isn’t automatically implemented by the presence of the see key when key when autoseeindex is false. -

It’s therefore possible to remove the cross-references from the location lists and + id="dx1-4073"> is false. +

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. @@ -1306,25 +1326,25 @@ class="cmss-10">glossaries) to record

(New to v1.08.) This is a ⟨key⟩=⟨value⟩ option provided for the benefit of bib2gls (see §9 bib2gls: Managing Reference Databases). -

The option may only be set in the preamble and can’t be used after +

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-4076"> is assumed. Permitted values:

\makenoidxglossaries. This setting href="#styopt.undefaction">undefaction=error. + id="dx1-4077">.
only
The indexing is performed by bib2gls (see §9 \makenoidxglossaries is permitted. This setting imp href="#styopt.undefaction">undefaction=warn and automatically loads the supplementary + id="dx1-4079"> and automatically loads the supplementary glossaries-extra-bib2gls package. (There should be no need to explicitly + id="dx1-4080"> package. (There should be no need to explicitly load glossaries-extra-bib2gls.) -

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): @@ -1378,53 +1398,53 @@ class="cmtt-10">myDoc.tex):  
bib2gls myDoc  
pdflatex myDoc -

-

Note that

+

Note that record=only will prevent the will prevent the see from automatically + id="dx1-4083"> from automatically implementing \glssee. (bib2gls deals with the see field.) You + id="dx1-4085"> field.) You may explicitly use \glssee in the document, but bib2gls will ignore the cross-reference if the see field was already set for that + id="dx1-4087"> field was already set for that entry. -

The

The record=only option will automatically set the option will automatically set the glossaries package’s sort=none option if available. (That option value was only introduced to + id="dx1-4089"> option if available. (That option value was only introduced to glossaries v4.30.)

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-4091"> but additionally records the current label information given by \@currentlabel and \@currentHref, and provides a more reliable way of @@ -1433,7 +1453,7 @@ class="cmtt-10">\theHcounter⟩ for the given location. This option requires hyperref otherwise it will fall back on the usual location records. + id="dx1-4092"> 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-4093"> 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

This option is best used with counter=chapter or or counter=section if you + id="dx1-4095"> 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-4096">, only the location number is shown. Similarly for counter=equation (or (or equations=true). + id="dx1-4098">).

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. This option should be used with \makeglossaries but not \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

The glossaries should be displayed using \printglossary (or \printglossaries). This option is expected to be used with bib2gls’s sort=none setting and so glossaries-extra-bib2gls is not automatically + id="dx1-4107"> is not automatically loaded. -

The document build process is (assuming the file is called

The document build process is (assuming the file is called myDoc.tex): @@ -1530,16 +1550,16 @@ class="cmtt-10">myDoc.tex):  
makeglossaries myDoc  
pdflatex myDoc -

-

With the recording on (

+

With the recording on (record=only or or record=alsoindex), any of the commands + id="dx1-4109">), any of the commands that would typically index the entry (such as \gls, \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 @@ -1566,21 +1586,21 @@ class="cmtt-10">bib2gls: Managing Reference Databases). You may want to consider using \glsadd after the caption (not before). For  
  \glsadd{foobar}  
\end{figure} -

+

indexcounter
(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-4126">. 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 @@ -1658,26 +1678,26 @@ href="#glo:numberlist">number list href="#styopt.counter">counter=wrglossary. -

This option works by incrementing . +

This option works by incrementing wrglossary and adding and adding \label. This can + id="dx1-4132">. This can cause a problem if the indexing occurs in an equation environment as environment as amsmath + id="dx1-4135"> forbids multiple occurrences of \label (resulting in the “Multiple \label’s” error). It’s best to change the counter to page or or equation when in maths mode + id="dx1-4137"> when in maths mode with this option. For example: @@ -1689,22 +1709,22 @@ class="cmss-10">equation\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-4140"> 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-4141">) 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-4142"> counter but this value is substituted with the page reference when number list is typeset. Since the counter is used by all + id="dx1-4143">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-4146"> 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-4149"> counter was used. -

Since

Since bib2gls is designed specifically to work with glossaries-extra, bib2gls (v1.4+) will check for wrglossary locations. If the default + id="dx1-4152"> locations. If the default --merge-wrglossary-records is on, then any records for the same page for a given entry will be merged. In the above example with three references on page 5, only a single record for page 5 for that entry will be added to the number list and it will link back to the first instance on + id="dx1-4153">number list and it will link back to the first instance on that page. Whereas if you use the --no-merge-wrglossary-records switch, the number list will contain three instance of page 5, with + id="dx1-4154">number list will contain three instance of page 5, with each linking to the corresponding place on that page. In both cases, consecutive pages can form ranges, but it may look strange in the second case. -

See the

See the bib2gls documentation for the save-index-counter resource option for more details. @@ -1776,7 +1796,7 @@ class="cmtt-10">save-index-counter resource option docdef

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 @@ -1785,10 +1805,10 @@ class="cmss-10">true is assumed):
  • \newglossaryentry is not permitted in the is not permitted in the document environment + id="dx1-4159"> 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-4162"> 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-4164"> 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 in @@ -1814,31 +1834,31 @@ class="cmtt-10">\newglossaryentry. (For example, when the glossary is dis class="E">EX 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-4168">. If your glossaries occur at the end of the document, consider using docdef=restricted instead. + id="dx1-4169"> instead.

  • (new to version 1.06) \newglossaryentry is permitted in the + id="dx1-4171"> 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 @@ -1847,15 +1867,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-4176"> 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 @@ -1863,12 +1883,12 @@ 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-4177"> 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 .gls files). href="#styopt.docdef">docdef=restricted but + id="dx1-4179"> but creates the .glsdefs file for atom’s autocomplete support. This file @@ -1893,22 +1913,22 @@ class="cmss-10">glossaries-extra and so associated problems with the href="#styopt.docdef">docdef=restricted, entries may + id="dx1-4180">, 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.

-

The

The glossaries package allows \newglossaryentry within the document + id="dx1-4181"> 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-4185"> environment, despite all the associated drawbacks, you can restore this with docdef=true. Note that this doesn’t change the + id="dx1-4187">. 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-4189"> 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 §8 +class="cmsy-10">§11 On-the-Fly Document Definitions.

nomissingglstext
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 @@ -1963,21 +1983,26 @@ class="description">This is a boolean option. If true, this will suppress the abbreviations
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. In addition, it defines a shortcut +class="cmtt-10">\glsxtrabbrvtype to this label. (The file extensions are glg-abr, + gls-abr and glo-abr.) In addition, this option defines a shortcut command -


\printabbreviations 


\printabbreviations[options]

-

+

which is equivalent to

]
If glossaries-extra-bib2gls is also loaded then this option will additionally + id="dx1-4196"> is also loaded then this option will additionally provide: -


\printunsrtabbreviations 


\printunsrtabbreviations[options] -

-

+class="cmtt-10">]


+

which uses \printunsrtglossary. -

The title of the new glossary is given by -


\abbreviationsname  . +

The title of the new glossary is given by +


\abbreviationsname

-

+

If this command is already defined, it’s left unchanged. Otherwise it’s defined to “Abbreviations” if babel hasn’t been loaded or 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 + id="dx1-4202"> it’s likely you will need to change this. (See §13 §14 Multi-Lingual Support for further details.) -

If you don’t use the

If you don’t use the abbreviations package option, the package option, the \abbreviationsname command won’t be defined (unless it’s defined by an included language file).
-

-

If the

+

If the abbreviations option is used and the option is used and the acronym option provided by the + id="dx1-4205"> option provided by the glossaries package hasn’t been used, then \acronymtype will be set to + id="dx1-4206"> will be set to \glsxtrabbrvtype so that acronyms defined with so that acronyms defined with \newacronym can be added + id="dx1-4208"> can be added to the list of abbreviations. If you want acronyms in the main glossary and other abbreviations in the main:

\renewcommand*{\acronymtype}{main}
-

-

Note that there are no analogous options to the

+

Note that there are no analogous options to the glossaries package’s acronymlists + id="dx1-4209"> option (or associated commands) as the abbreviation mechanism is handled differently with glossaries-extra. @@ -2077,22 +2097,19 @@ class="cmss-10">glossaries-extra. symbols

This is passed to glossaries but will additionally define -


\glsxtrnewsymbol 


\glsxtrnewsymbol[options]{label}{symbol} -

-

+class="cmtt-10">}


+

which is equivalent to

}
Note that the sort key is set to the ⟨ key is set to the ⟨label⟩ not the ⟨symbol⟩ as the symbol will likely contain commands. -

If

If glossaries-extra-bib2gls is also loaded then this option will additionally + id="dx1-4213"> is also loaded then this option will additionally provide: -


\printunsrtsymbols 


\printunsrtsymbols[options]

-

+

which uses \printunsrtglossary. + id="dx1-4215">.

numbers
This is passed to glossaries but will additionally define -


\glsxtrnewnumber 


\glsxtrnewnumber[options]{number}

-

+

which is equivalent to

}
-

If

If glossaries-extra-bib2gls is also loaded then this option will additionally + id="dx1-4218"> is also loaded then this option will additionally provide: -


\printunsrtnumbers 


\printunsrtnumbers[options]

-

+

which uses \printunsrtglossary. + id="dx1-4220">.

acronyms (or acronym)
This is passed to glossaries but if glossaries-extra-bib2gls is + id="dx1-4223"> is also loaded then this option will additionally provide: -


\printunsrtacronyms 


\printunsrtacronyms[options]

-

+

which uses \printunsrtglossary. -

This option defines a new glossary with the label . +

This option defines a new glossary with the label acronym not acronyms. You may find it easier to reference it with the command \acronymtype. + id="dx1-4226">.
-

+

index
This is passed to glossaries but if glossaries-extra-bib2gls is also loaded then this + id="dx1-4228"> is also loaded then this option will additionally provide: -


\printunsrtindex 


\printunsrtindex[options]

-

+

which uses \printunsrtglossary. + id="dx1-4230">.

shortcuts
Unlike the glossaries package option of the same name, this option isn’t boolean but has multiple values: @@ -2252,11 +2259,11 @@ class="cmss-10">glossaries package option of the same name, this option i href="#styopt.shortcuts">shortcuts=acronyms (or (or shortcuts=acro): set the shortcuts provided + id="dx1-4233">): set the shortcuts provided by the glossaries package for acronyms (such as \ac). Note that the @@ -2272,13 +2279,13 @@ class="cmss-10">glossaries-extra href="#styopt.shortcuts">shortcuts=ac. + id="dx1-4234">.
  • shortcuts=ac: set the shortcuts provided by the : set the shortcuts provided by the glossaries package for acronyms (such as \ac) but uses the \gls. href="#styopt.shortcuts">shortcuts=abbreviations (or (or shortcuts=abbr): + id="dx1-4237">): set the abbreviation shortcuts provided by glossaries-extra. (See §3.3 +class="cmsy-10">§4.3 Shortcut Commands.) These settings don’t switch on the acronym shortcuts provided by the glossaries package. href="#styopt.shortcuts">shortcuts=other: set the “other” shortcut commands, but not the shortcut + id="dx1-4238">: set the “other” shortcut commands, but not the shortcut commands for abbreviations or the acronym shortcuts provided by glossaries. The “other” shortcuts are:
    • \newentry equivalent to equivalent to \newglossaryentry + id="dx1-4240">
    • \newsym equivalent to equivalent to \glsxtrnewsymbol (see the (see the symbols + id="dx1-4243"> option).
    • \newnum equivalent to equivalent to \glsxtrnewnumber (see the (see the numbers + id="dx1-4246"> option).
  • shortcuts=all (or (or shortcuts=true): implements ): implements shortcuts=ac, + id="dx1-4249">, shortcuts=abbreviations and and shortcuts=other. + id="dx1-4251">.
  • shortcuts=none (or (or shortcuts=false): don’t define any of the shortcut + id="dx1-4253">): don’t define any of the shortcut commands (default).
  • -

    Note that multiple invocations of the

    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 -


    \glossariesextrasetup 


    \glossariesextrasetup{options}

    -

    +

    The abbreviations and and docdef options may only be used in the preamble. Additionally, + id="dx1-4257"> options may only be used in the preamble. Additionally, docdef can’t be used after can’t be used after \makenoidxglossaries. + id="dx1-4259">.

    -

    -

    +

    Top

    2. Modifications to Existing Commands and Styles

    -

    The +

    Top

    2.1 Defining Entries

    +

    The glossaries package provides \nopostdesc which may be used in the which may be used in the description -to suppress the post-description hook. The to +suppress the post-description hook. The glossaries-extra package provides another command -


    \glsxtrnopostpunc 


    \glsxtrnopostpunc

    -

    +

    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 @@ -2445,12 +2452,10 @@ class="cmtt-10">\glsxtrpostdescription not before.) The post-description hook can counter-act the effect of \glsxtrnopostpunc using -


    \glsxtrrestorepostpunc 


    \glsxtrrestorepostpunc

    -

    +

    These commands have no effect outside of the glossary (except with standalone entries that use \glsxtractivatenopost and §10.3 Standalone Entry Items). -

    The glossaries package provides -


    \glsseeitemformat  \glsseeitemformat{label}

    -

    -to format items in a cross-reference list (identified with the see key or \glssee). This -was originally defined to use \glsentryname{label} 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 -setting, so glossaries v3.0 changed the default definition of this command to -use \glsentrytext instead. Since the name and text 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 -glossaries v4.0) it makes more sense to restore this command to its original -behaviour, but to take account of abbreviations glossaries-extra redefines this -as: - - - -

    -
    -\renewcommand*{\glsseeitemformat}[1]{% - 
     \ifglshasshort{\glslabel}{\glsaccesstext{#1}}{\glsaccessname{#1}}% - 
    } -
    -

    If you want to restore the glossaries v3.0+ definition just do: - - - -

    -
    -\renewcommand*{\glsseeitemformat}[1]{\glsentrytext{#1}} -
    -

    The glossaries-extra package provides \glsxtrhiername 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. See §2.2 Cross-References (“see” and “see also”) for -further details. -

    The commands used by

    The commands used by glossaries to automatically produce an error if an entry is undefined (such as \glsdoifexists) are changed to take the ) are changed to take the undefaction option into + id="dx1-6006"> option into account. -

    The \newignoredglossary{type} command now (as from v1.11) has a starred -version that doesn’t automatically switch off the hyperlinks. This starred version may -be used with the targeturl attribute to create a link to an external URL. (See §5 -Categories for further details.) As from v1.12 both the starred and unstarred version -check that the glossary doesn’t already exist. (The glossaries package omits this -check.) -

    You can now provide an ignored glossary with: -


    \provideignoredglossary  \provideignoredglossary{type}

    -

    -which will only define the glossary if it doesn’t already exist. This also has a starred -version that doesn’t automatically switch off hyperlinks. -

    The individual glossary displaying commands \printglossary, \printnoidxglossary -and \printunsrtglossary have two extra keys: -

    -
      -
    • target. This is a boolean key which can be used to switch off the automatic - hypertarget for each entry. Unlike \glsdisablehyper this doesn’t switch - off hyperlinks, so any cross-references within the glossary won’t be affected. - This is a way of avoiding duplicate target warnings if a glossary needs to - be displayed multiple times. -
    • -
    • targetnameprefix={prefix}. Another way of avoiding duplicate target names - is to set a prefix used for the names. Unlike changing \glolinkprefix - this doesn’t affect any hyperlinks (such as those created with \gls). -
    • -
    • prefix={prefix}. If you do actually want to locally change \glolinkprefix, - you can use the prefix key instead. You need to use the matching prefix - key in commands like \gls. -
    • -
    • label={label}. Labels the glossary with \label{label} and also defines - - - - \@currentlabelname to the glossary’s TOC title (to provide text for - \nameref). You can also set the label before the glossary using: -


      \glsxtrsetglossarylabel  \glsxtrsetglossarylabel{label}

      -

      - but take care of duplicate labels if it’s not scoped.

    -

    The

    The \newglossaryentry command has three new keys:

    -

    The test file example-glossaries-xr.tex contains dummy entries with a mixture of -

    This apply to all entry defining commands (such as \newabbreviation). +

    The test file example-glossaries-xr.tex contains dummy entries with a +mixture of see, , alias and and seealso keys for use with minimal working examples. There are also + id="dx1-6013"> keys for use with minimal working examples. +There are also example-glossaries-*.bib files that correspond to each example-glossaries-*.bib files that correspond to each example-glossaries-*.tex -file for testing example-glossaries-*.tex file for testing bib2gls. -

    The

    The \longnewglossaryentry command now has a starred version (as from v1.12) that doesn’t automatically insert

    -
    +
    \leavevmode\unskip\nopostdesc
    -

    at the end of the description field. -


    \longnewglossaryentry 

    at the end of the description field. +


    \longnewglossaryentry*{label}{options} -{}{description}

    -

    +

    The descriptionplural key is left unset unless explicitly set in ⟨ 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: -


    \glsxtrpostlongdescription 


    \glsxtrpostlongdescription

    -

    +

    This can be redefined to allow the post-description hook to work but retain the \unskip part if required. For example: @@ -2726,60 +2562,58 @@ class="cmtt-10">\unskip part if required. For example:

    -
    +
    \renewcommand*{\glsxtrpostlongdescription}{\leavevmode\unskip}
    -

    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 + id="dx1-6018"> package’s treatment of the descriptionplural key. Since a plural description doesn’t make much sense for + id="dx1-6019"> key. Since a plural description doesn’t make much sense for multi-paragraph descriptions, the default behaviour with glossaries-extra’s + id="dx1-6020">’s \longnewglossaryentry is to simply leave the plural description unset unless explicitly set using the descriptionplural key. The key. The glossaries.sty version of this command sets the description’s plural form to the same as the singular.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 command (defined through the index package option) is modified + id="dx1-6029"> package option) is modified so that the category defaults to index. The . The \newacronym command is modified + id="dx1-6031"> command is modified to use the new abbreviation interface provided by glossaries-extra. (See §3 +class="cmsy-10">§4 Abbreviations.) -

    The

    The \makeglossaries command now has an optional argument. -


    \makeglossaries 


    \makeglossaries[list]

    -

    +

    If ⟨list⟩ is empty, \makeglossaries behaves as per its original definition in the @@ -2787,44 +2621,44 @@ 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 + id="dx1-6033"> package option. Without the optional argument, it’s permitted with record=alsoindex. With the optional + id="dx1-6034">. 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.) -

    If you use the optional argument ⟨

    If you use the optional argument ⟨list⟩, you can’t define entries in the document (even with the docdef option).
    -

    -

    You will need at least version 2.20 of option).

    +

    +

    You will need at least version 2.20 of makeglossaries or at least version 1.3 of the Lua alternative makeglossaries-lite (both distributed with (both distributed with glossaries v4.27) to allow for this use of \makeglossaries[list]. Alternatively, use the automake + id="dx1-6040"> option. +

    -

    Top

    2.1 Entry Indexing

    -

    As from version 1.31, there is a new command like \glsadd where the mandatory -argument is a comma-separated list of labels: -


    \glsaddeach 

    Top

    2.2 Entry Indexing

    +

    As from version 1.31, there is a new command like \glsadd where the mandatory +argument is a comma-separated list of labels: +


    \glsaddeach[options]{list}

    -

    +

    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). -


    \GlsXtrAutoAddOnFormat 


    \GlsXtrAutoAddOnFormat[label]{format list} -{}{glsadd options}

    -

    +class="cmtt-10">} +


    +

    The optional argument ⟨label⟩ defaults to \glslabel and indicates the label to use in @@ -2902,51 +2732,51 @@ class="cmtt-10">format={⟨format} prepended to the list. -

    For example, with: +

    For example, with:

    -
    +
    \GlsXtrAutoAddOnFormat{hyperbf}{counter=chapter}
    -

    then

    then \gls[format=hyperbf]{sample} will be equivalent to

    -
    +
    \glsadd[format=hyperbf,counter=chapter]{sample}\gls[format=hyperbf]{sample}
    -

    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:

    -
    +
    \GlsXtrAutoAddOnFormat[dual.\glslabel]{hyperbf}{}
    -

    In this case

    In this case \gls[format=hyperbf]{sample} will now be equivalent to:

    -
    +
    \glsadd[format=hyperbf]{dual.sample}\gls[format=hyperbf]{sample}
    -

    -

    +

    \GlsXtrAutoAddOnFormat is not applied to \glsadd as it could cause an infinite loop.
    -

    -The

    +

    The glossaries-extra package provides extra keys for commands like \gls and \glstext:

    noindex
    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 indexonlyfirst package option provided + id="dx1-7004"> package option provided by glossaries, as 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 + id="dx1-7006"> to selected entries, rather than all of them, you can use the indexonlyfirst attribute, see attribute, see §5 §6 Categories for further details.) Note that the noindex key isn’t available for key isn’t available for \glsadd (and (and \glsaddall) + id="dx1-7010">) since the whole purpose of that command is to index an entry.
    wrgloss
    (New to v1.14.) This is may only take the values before or after. By @@ -3005,20 +2835,18 @@ class="cmtt-10">wrgloss=after for specific instances. Note that this opti doesn’t have an effect if the indexing has been suppressed through other settings (such as noindex). -

    The default value is set up using -


    \glsxtrinitwrgloss  ). +

    The default value is set up using +


    \glsxtrinitwrgloss

    -

    +

    which is defined as:

    -
    +
    \newcommand*{\glsxtrinitwrgloss}{%  
     \glsifattribute{\glslabel}{wrgloss}{after}%  
     {% @@ -3029,31 +2857,29 @@ class="cmtt-10">\glsxtrinitwrgloss

     
     }%  
    }
    -

    This sets the conditional -


    \ifglsxtrinitwrglossbefore  \ifglsxtrinitwrgloss

    -

    +

    This sets the conditional +


    \ifglsxtrinitwrgloss

    +

    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 attribute to after to automatically use this as the default for entries with that category attribute. (Note that adding wrgloss to the default options in to the default options in \GlsXtrSetDefaultGlsOpts will override + id="dx1-7017"> will override \glsxtrinitwrgloss.)

    hyperoutside
    (New to v1.21.) This is a boolean key. The default is hyperoutside=true, which puts the hyperlink outside }
    You can use the hyperoutside category attribute to set the default for a + id="dx1-7019"> category attribute to set the default for a given category. This can be combined with the use of the textformat + id="dx1-7020"> attribute to counteract any interference caused by \hyperlink. For example: -
    +
    \glssetcategoryattribute{mathrelation}{hyperoutside}{false}
    -

    will set

    will set hyperoutside=false for all entries that are assigned to the category mathrelation and @@ -3116,10 +2942,10 @@ class="cmtt-10">mathrelation and

    -
    +
    \glssetcategoryattribute{mathrelation}{textformat}{mathrel}
    -

    will use

    will use \mathrel instead of \glstextformat resulting in:

    @@ -3136,164 +2962,270 @@ class="cmsy-10">}
    for entries with the category key set to key set to mathrelation.
    textformat
    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 + id="dx1-7023"> attribute and \glstextformat. See the soul example in example in §2.5 §2.6 First Use Flag.
    prefix
    Locally redefines \glolinkprefix to the given value. It should match the + id="dx1-7026"> to the given value. It should match the prefix for the desired glossary.
    thevalue
    Explicitly set the location to this value (see below).
    theHvalue
    Set the corresponding hyperlink location (see below).
    -

    There is a new hook that’s used each time indexing information is written to the -external glossary files: -


    \glsxtrdowrglossaryhook  \glsxtrdowrglossaryhook{label

    You can set the default options used by \glslink, \gls etc with: +


    \GlsXtrSetDefaultGlsOpts{options}

    -

    -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 -are set by the \gls-like and \glstext-like commands: -


    \glslinkpresetkeys  \glslinkpresetkeys

    -

    -(The base package provides \glslinkpostsetkeys that’s used immediately after the -options are set.) +

    +For example, if you mostly don’t want to index entries then you can do: + + + +

    +
    +\GlsXtrSetDefaultGlsOpts{noindex} +
    +

    and then use, for example, \gls[noindex=false]{sample} when you actually want +the location added to the number list. These defaults may be overridden by other +settings (such as category attributes) in addition to any settings passed in the option +argument of commands like \glslink and \gls. +

    Note that if you don’t want any indexing, just omit \makeglossaries and +\printglossaries (or analogous commands). If you want to adjust the +default for wrgloss, it’s better to do this by redefining \glsxtrinitwrgloss +instead. +

    \GlsXtrSetDefaultGlsOpts doesn’t affect \glsadd.
    +

    +

    If you want to change the default value of format, you can instead use: +


    \GlsXtrSetDefaultNumberFormat{format}

    +

    +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 +overridden): + + + +

    +
    +\backmatter + 
    \GlsXtrSetDefaultNumberFormat{hyperit} +
    +

    +

    Commands like \gls have star (*) and plus (+) modifiers as a short cut for +hyper=false and hyper=true. The glossaries-extra package provides a way to add a +third modifier, if required, using +


    \GlsXtrSetAltModifier{char}{options}

    +

    +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). +

    When choosing the character ⟨char⟩ take care of any changes in category code. +
    +

    +

    Example: + + + +

    +
    +\GlsXtrSetAltModifier{!}{noindex} +
    +

    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 -

    As from version 1.30 there are also similar hooks for +

    +\gls[noindex,hyper=false]{sample} +
    +

    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 +external glossary files: +


    \glsxtrdowrglossaryhook{label}

    +

    +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 +are set by the \gls-like and \glstext-like commands: +


    \glslinkpresetkeys

    +

    +(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 \glsadd: -


    \glsaddpresetkeys 


    \glsaddpresetkeys

    -

    +

    and -


    \glsaddpostsetkeys 


    \glsaddpostsetkeys

    -

    +

    For example, to default to using the equation counter in maths mode: + id="dx1-7043"> counter in maths mode:

    -
    +
    \renewcommand{\glslinkpresetkeys}{%  
     \ifmmode \setkeys{glslink}{counter=equation}\fi}  
    \renewcommand{\glsaddpresetkeys}{%  
     \ifmmode \setkeys{glossadd}{counter=equation}\fi}
    -

    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 + id="dx1-7044"> in the optional argument of \gls or \glsadd. (As from version 1.37, a simpler method is to just use the equations package option.) -

    Alternatively, to enforce this (overriding the option argument): + id="dx1-7045"> package option.) +

    Alternatively, to enforce this (overriding the option argument):

    -
    +
    \renewcommand{\glslinkpostsetkeys}{%  
     \ifmmode \setkeys{glslink}{counter=equation}\fi}  
    \renewcommand{\glsaddpostsetkeys}{%  
     \ifmmode \setkeys{glossadd}{counter=equation}\fi}
    -

    -

    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 and theHvalue. + id="dx1-7047">. These keys are designed for manually adding explicit locations rather than obtaining the value from the associated counter. As from version 1.19, these two keys are also available for commands like \gls and \glslink. The thevalue keys is intended + id="dx1-7048"> 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 is for the location value. The other key theHvalue can + id="dx1-7050"> can be used to extract a prefix value for the first argument of commands like \glsnoidxdisplayloc. Its value must be in the format ⟨. Its value must be in the format ⟨prefix⟩⟨location⟩. In general, there’s little need for this key as the prefix is typically associated with a counter that can be used to form hypertargets. -

    If you use

    If you use thevalue, you must make sure that you use an indexing application + id="dx1-7052">, you must make sure that you use an indexing application that will accept the given value.
    -

    -

    For example,

    +

    For example, makeindex will only accept locations in the form [⟨ will only accept locations in the form [⟨num⟩⟨sep⟩]*⟨num⟩ @@ -3306,37 +3238,37 @@ instances of a number followed by the recognised separator character (set with \glsSetCompositor). This means that makeindex won’t accept, for + id="dx1-7054"> won’t accept, for example,

    -
    +
    \glsadd[thevalue={Supplementary Material}]{sample}
    -

    This location value will be accepted by

    This location value will be accepted by bib2gls, since it will allow any location and will only try forming ranges if the location matches any of its numerical patterns. In the case of xindy, you’ll need to add a rule that can match the value. + id="dx1-7056">, you’ll need to add a rule that can match the value. If you’re using hyperref, you may need to use the , you may need to use the format key to prevent a + id="dx1-7058"> key to prevent a hyperlink if one can’t naturally be formed from the prefix, counter and location value. -

    For example, suppose the file

    For example, suppose the file suppl.tex contains:

    -
    +
    \documentclass{article}  
    \usepackage{glossaries-extra}  
    \newglossaryentry{sample}{name={sample},description={an example}} @@ -3347,17 +3279,17 @@ class="cmtt-10">suppl.tex contains:  
    \gls{sample}.  
    \end{document}
    -

    This has an entry on page S.2. Suppose another document wants to include this +

    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 to S.2. For example:

    -
    +
    \documentclass{article}  
    \usepackage{glossaries-extra}  
    \makeglossaries @@ -3368,59 +3300,59 @@ example:  
    \glsadd[thevalue={S.2}]{sample}  
    \end{document}
    -

    This location value will be accepted by

    This location value will be accepted by makeindex as it’s in the form ⟨ 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 externallocation attribute to the location of the PDF file. For example: + id="dx1-7061"> attribute to the location of the PDF file. For example:

    -
    +
    \glssetcategoryattribute{supplemental}{externallocation}{suppl.pdf}  
    \newglossaryentry{sample}{category=supplemental,  
     name={sample},description={an example}}
    -

    Next you need to add

    Next you need to add glsxtrsupphypernumber as the format:

    -
    +
    \glsadd[thevalue={S.2},format=glsxtrsupphypernumber]{sample}
    -

    Both documents will need to use the

    Both documents will need to use the hyperref package. Remember that the counter + id="dx1-7062"> package. Remember that the counter used for the location also needs to match. If \theHcounter⟩ is defined in the other document and doesn’t match in the referencing document, then you need to use theHvalue to set the appropriate value. See the accompanying sample files + id="dx1-7063"> to set the appropriate value. See the accompanying sample files sample-suppl-hyp.tex and sample-suppl-main-hyp.tex for an example that uses hyperref. -

    The hyperlink for the supplementary location may or . +

    The hyperlink for the supplementary location may or may not take you to the relevant place in the external PDF file depending on your PDF viewer. Some may not support external links, and some may take you to the first page or last visited page.
    -

    -

    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 attribute). For multiple + id="dx1-7065"> attribute). For multiple sources, you need to use bib2gls version 1.7+, which is the better method in general as it can automatically fetch the relevant locations from the .aux files of the designated external documents without the need to explicitly use \glsadd. -

    +

    -

    Top

    2.2

    Top

    2.3 Cross-References (“see” and “see also”)

    -

    The value of the

    The value of the see key is now saved as a field. This isn’t the case with 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 + id="dx1-8002"> 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 + id="dx1-8003"> key can’t be used before \makeglossaries (since the file hasn’t been opened yet). It’s also the + id="dx1-8004"> (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 + id="dx1-8005"> 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 + id="dx1-8006"> 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 + id="dx1-8008"> environment on the next run. -

    This modification allows

    This modification allows glossaries-extra to provide -


    \glsxtraddallcrossrefs 


    \glsxtraddallcrossrefs

    -

    +

    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. +

    As a by-product of this enhancement, the see key will now work for entries + id="dx1-8012"> key will now work for entries defined in the document environment, but it’s still best to define entries in the + id="dx1-8013"> environment, but 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 + id="dx1-8015"> 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-8016"> package option, which can be used to suppress the error when the see key + id="dx1-8017"> key is used before \makeglossaries, so seenoindex=ignore will allow the will allow the see + id="dx1-8019"> 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 -


    \glsxtrusesee 


    \glsxtrusesee{label}

    -

    +

    This internally uses -


    \glsxtruseseeformat 


    \glsxtruseseeformat{tag}{xr list}

    -

    +

    where ⟨tag⟩ and ⟨xr list⟩ are obtained from the value of the entry’s see field (if + id="dx1-8022"> field (if non-empty). By default, this just does \glsseeformat[tagxr 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-8024"> 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{tagxr list}. The third argument is always ignored and is present for makeindex, which always requires a final argument to encapsulate the associated + id="dx1-8026">, which always requires a final argument to encapsulate the associated location. The command -



    \glsseelist{xr list}

    -

    +

    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-8028"> package, with each item in the list formatted according to: -



    \glsseeitem{label}

    -

    +

    This is defined by the glossaries package to:

    + id="dx1-8030"> package to:

    \glshyperlink[\glsseeitemformat{}
    So the actual formatting for each cross-referenced entry is performed by \glsseeitemformat, which is redefined by , which is redefined by glossaries-extra, as described in , as described in §2 Modifications to Existing Commands and Styles. This now displays the value of the text field for abbreviations and the value of the field for abbreviations and the value of the name field otherwise. There’s no + id="dx1-8034"> field otherwise. There’s no indication of the entry hierarchy, which could confuse the reader. Therefore, as from glossaries-extra v1.37, there are some new commands that include the hierarchical + id="dx1-8035"> v1.37, there are some new commands that include the hierarchical information. You may prefer to redefine \glsseeitemformat to use one of this if you have sub-entries. For example: -
    +
    \renewcommand*{\glsseeitemformat}[1]{\glsxtrhiername{#1}}
    -

    -

    The command: -


    \glsxtrhiername 

    +

    The glossaries package provides +


    \glsseeitemformat{label}

    +

    +to format items in a cross-reference list (identified with the see key or \glssee). This +was originally defined to use \glsentryname{label} 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 +setting, so glossaries v3.0 changed the default definition of this command to +use \glsentrytext instead. Since the name and text 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 +glossaries v4.0) it makes more sense to restore this command to its original +behaviour, but to take account of abbreviations glossaries-extra redefines this +as: + + + +

    +
    +\renewcommand*{\glsseeitemformat}[1]{% + 
     \ifglshasshort{\glslabel}{\glsfmttext{#1}}{\glsfmtname{#1}}% + 
    } +
    +

    (Note that as from glossaries-extra version 1.42, this now uses \glsfmttext and +\glsfmtname instead of just referencing the text and name fields. This helps to ensure +that any formatting is correctly applied.) +

    If you want to restore the glossaries v3.0+ definition just do: + + + +

    +
    +\renewcommand*{\glsseeitemformat}[1]{\glsentrytext{#1}} +
    +

    +

    The glossaries-extra package provides \glsxtrhiername 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. +


    \glsxtrhiername{label}

    -

    +

    performs a recursive action:

    1. If the entry given by ⟨If the entry given by ⟨label⟩ has a parent, then \glsxtrhiername{parent @@ -3660,92 +3658,82 @@ class="cmtt-10">} is done followed by \glsxtrhiernamesep then:
    2. If the entry given by ⟨If the entry given by ⟨label⟩ is an abbreviation (that is, it has the short field + id="dx1-8051"> field set) then the short form is displayed (using \glsaccessshort) otherwise - the name is displayed (using \glsaccessname).
    -

    The first step above is skipped if the entry doesn’t have a parent. Each level is separated +class="cmtt-10">\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 by: -


    \glsxtrhiernamesep 


    \glsxtrhiernamesep

    -

    +

    which defaults to “ ”. This can be redefined as appropriate. -

    There are some case-changing variants: -


    \Glsxtrhiername 

    There are some case-changing variants: +


    \Glsxtrhiername{label}

    -

    +

    The top-level has the first letter changed to upper case (either \Glsaccessshort or +class="cmtt-10">\Glsfmtshort or \Glsaccessname). There’s no case-change for sub-entries. -


    \GlsXtrhiername  \Glsfmtname). There’s no case-change for sub-entries. +


    \GlsXtrhiername{label}

    -

    +

    All levels have the first letter changed to upper case (either \Glsaccessshort or +class="cmtt-10">\Glsfmtshort or \Glsaccessname). -


    \GLSxtrhiername  \Glsfmtname). +


    \GLSxtrhiername{label}

    -

    +

    The top-level is converted to upper case (either \GLSaccessshort or \GLSaccessname). +class="cmtt-10">\GLSfmtshort or \GLSfmtname). There’s no case-change for sub-entries. -


    \GLSXTRhiername 


    \GLSXTRhiername{label}

    -

    +

    All levels are converted to upper case (either \GLSaccessshort or \GLSaccessname). -

    Suppose you want to suppress the number list using \GLSfmtshort or \GLSfmtname). + + + +

    Suppose you want to suppress the number list using nonumberlist. This + id="dx1-8058">. This will automatically prevent the cross-references from being displayed. The seeautonumberlist package option will automatically enable the number list for entries + id="dx1-8059"> package option will automatically enable the number list for entries that have the see key set, but this will also show the rest of the number + id="dx1-8061"> key set, but this will also show the rest of the number list. - - - -

    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: @@ -3753,22 +3741,22 @@ example:

    -
    +
    \renewcommand*{\glsxtrpostdescgeneral}{%  
     \ifglshasfield{see}{\glscurrententrylabel}  
     {, \glsxtrusesee{\glscurrententrylabel}}%  
     {}%  
    }
    -

    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

    As from v1.16, there’s a separate seealso key. Unlike key. Unlike see, this doesn’t have an + id="dx1-8065">, this doesn’t have an optional part for the textual tag. The syntax seealso={xr-labelsxr-labels} but the information is stored in a separate field. If you need a different tag, use the see key + id="dx1-8066"> key instead (or redefine \seealsoname or \glsxtruseseealsoformat, described below). -

    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-8067"> key using: -


    \glsxtruseseealso 


    \glsxtruseseealso{label}

    -

    +

    This works in much the same way as \glsxtrusesee but it internally uses -


    \glsxtruseseeformat 


    \glsxtruseseealsoformat{xr list}

    -

    +

    For example:

    -
    +
    \renewcommand*{\glsxtrpostdescgeneral}{%  
     \ifglshasfield{see}{\glscurrententrylabel}  
     {, \glsxtrusesee{\glscurrententrylabel}}% @@ -3821,27 +3805,38 @@ For example:  
     {}%  
    }
    -

    -

    The actual unformatted comma-separated list ⟨

    +

    The alias 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): +


    \glsxtrusealias{label}

    +

    +

    The actual unformatted comma-separated list ⟨xr-list⟩ stored in the seealso field + id="dx1-8072"> field can be accessed with: -


    \glsxtrseealsolabels 


    \glsxtrseealsolabels{label}

    -

    +

    This will just expand to the ⟨xr-labels⟩ provided in the value of the seealso key. There’s + id="dx1-8074"> key. There’s no corresponding command to access the see field. If you really need to access it, you + id="dx1-8075"> 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-8076">, 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 -


    \glsxtrseelist 


    \glsxtrseelist{xr list}

    -

    +

    which fully expands its argument and passes it to \glsseelist. -

    The

    The seealso key implements the automatic indexing using -


    \glsxtrindexseealso  key implements the automatic indexing using +


    \glsxtrindexseealso{label}{xr list}

    -

    +

    which just does

    }{xr list} + + +
    unless the xindy option is used with option is used with glossaries v4.30+, in which case a distinct + id="dx1-8081"> v4.30+, in which case a distinct seealso cross-reference class is used instead. -

    +

    The command that produces this “see also” text is +


    \seealsoname

    +

    +If \alsoname (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 \alsoname is used by general indexing packages, such as +makeidx, 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 +without affecting general indexing (with \index) then redefine \seealsoname +instead. +

    - - - -

    Top

    2.3

    Top

    2.4 Entry Display Style Modifications

    -

    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 line in the glossary). This text is referred to as the “link-text” regardless of 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 + id="dx1-9002">) used in the link-text by commands like \gls, , \glsxtrfull, , \glsxtrshort and and \glsxtrlong (but not commands like + id="dx1-9007"> (but not commands like \glslink, , \glsfirst and and \glstext) is changed by glossaries-extra to test for regular entries, which are determined as follows: @@ -3947,78 +3962,79 @@ entries, which are determined as follows:

  • If an entry is assigned to a category that has the regular attribute set (see attribute set (see §5 +class="cmsy-10">§6 Categories), the entry is considered a regular entry, even if it has a value for the short key. In this case key. In this case \glsentryfmt uses \glsgenentryfmt + id="dx1-9012"> (provided by glossaries), which uses the first (or (or firstplural) value on ) value on first use and the text (or (or plural) value on subsequent use. + id="dx1-9017">) value on subsequent use.
  • An entry that doesn’t have a value for the short key is assumed to + id="dx1-9018"> key is assumed to be a regular entry, even if the regular attribute isn’t set to “true” + id="dx1-9019"> attribute isn’t set to “true” (since it can’t be an abbreviation without the short form). In this case \glsentryfmt uses \glsgenentryfmt. + id="dx1-9020">.
  • If an entry does has a value for the short key and hasn’t been marked as + id="dx1-9021"> key and hasn’t been marked as a regular entry through the regular attribute, it’s not considered a regular + id="dx1-9022"> attribute, it’s not considered a regular + + + entry. In this case \glsentryfmt uses \glsxtrgenabbrvfmt (defined by + id="dx1-9023"> (defined by glossaries-extra) which is governed by the abbreviation style (see §3.2 +class="cmsy-10">§4.2 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 now puts \glsgenentry in the argument of + id="dx1-9025"> in the argument of the new command -


    \glsxtrregularfont 


    \glsxtrregularfont{text}

    -

    +

    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 @@ -4026,115 +4042,103 @@ you can redefine \glsxtrregularfont. This is more precise than changing \glstextformat which is applied to all linking commands for all entries, unless + id="dx1-9027"> which is applied to all linking commands for all entries, unless overridden by the textformat attribute. -

    For example: + id="dx1-9028"> attribute. +

    For example:

    -
    +
    \renewcommand*{\glsxtrregularfont}[1]{\textsf{#1}}
    -

    You can access the label through

    You can access the label through \glslabel. For example, you can query the category:

    -
    +
    \renewcommand*{\glsxtrregularfont}[1]{%  
     \glsifcategory{\glslabel}{general}{\textsf{#1}}{#1}}
    -

    or query the category attribute, for example, provide a custom attribute called +

    or query the category attribute, for example, provide a custom attribute called font:

    -
    +
    \glssetcategoryattribute{general}{font}{sf}  
    \renewcommand*{\glsxtrregularfont}[1]{%  
     \glsifattribute{\glslabel}{font}{sf}{\textsf{#1}}{#1}}
    -

    As from version 1.21, it’s simpler to just do, for example: +

    As from version 1.21, it’s simpler to just do, for example:

    -
    +
    \glssetcategoryattribute{general}{textformat}{textsf}
    -

    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: -


    \glsxtrabbreviationfont 


    \glsxtrabbreviationfont{text}

    -

    +

    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 -


    \glsxtrpostlinkhook 


    \glsxtrpostlinkhook

    -

    +

    This command will discard a following full stop (period) if the discardperiod attribute + id="dx1-9032"> attribute is set to “true” for the current entry’s category. It will also do -


    \glsxtrpostlink 


    \glsxtrpostlink

    -

    +

    if a full stop hasn’t be discarded and -


    \glsxtrpostlinkendsentence 


    \glsxtrpostlinkendsentence

    -

    +

    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: -


    \glsxtrifcustomdiscardperiod 


    \glsxtrifcustomdiscardperiod{true} -{}{false}

    -

    +

    You can access the field’s label using \glslabel. This command should do ⟨true⟩ if the @@ -4145,12 +4149,12 @@ definition is simply:

    -
    +
    \newcommand*{\glsxtrifcustomdiscardperiod}[2]{#2}
    -

    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.) -

    Avoid the use of

    Avoid the use of \gls-like and \glstext-like commands within the post-link hook as they will cause interference. Consider using commands like @@ -4159,45 +4163,43 @@ class="cmtt-10">\glsentrytext, \glsaccesstext or \glsxtrp (§2.7 §2.8 Nested Links) instead.
    -

    -

    By default

    +

    By default \glsxtrpostlink just does \glsxtrpostlinkcategory if + id="dx1-9036"> if it exists, where ⟨category⟩ is the category label for the current entry. (For example, for the general category, category, \glsxtrpostlinkgeneral if it has been defined.) -

    You can define the post-link hook command using

    You can define the post-link hook command using \newcommand, for example:

    -
    +
    \newcommand*{\glsxtrpostlinkgeneral}{%  
     \glsxtrpostlinkAddDescOnFirstUse  
    }
    -

    or, as from v1.31, you can use -


    \glsdefpostlink 

    or, as from v1.31, you can use +


    \glsdefpostlink{category}{definition}

    -

    +

    This is simply a shortcut for:

    definition}
    Note that it doesn’t check if the command has already been defined. -

    The sentence-ending hook is slightly more complicated. If the command +

    The sentence-ending hook is slightly more complicated. If the command \glsxtrpostlinkcategory is defined the hook will do that and then insert a + id="dx1-9039"> is defined the hook will do that and then insert a full stop with the space factor adjusted to match the end of sentence. If \glsxtrpostlinkcategory hasn’t been defined, the space factor is adjusted to match + id="dx1-9040"> hasn’t been defined, the space factor is adjusted to match the end of sentence. This means that if you have, for example, an entry that ends with a full stop, a redundant following full stop will be discarded and the space factor adjusted (in case the entry is in uppercase) unless the entry is followed by additional material, in which case the following full stop is no longer redundant and needs to be reinserted. -

    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: -


    \glsxtrpostlinkAddDescOnFirstUse  \glsxtrpostlinkAddDescOnFirstUse -

    -

    +


    \glsxtrpostlinkAddDescOnFirstUse

    +

    This will add the description in parentheses on first use. -

    For example, suppose you want to append the description in parentheses on first +

    For example, suppose you want to append the description in parentheses on first use for entries in the symbol category: + id="dx1-9045"> category:

    -
    +
    \newcommand*{\glsxtrpostlinksymbol}{%  
      \glsxtrpostlinkAddDescOnFirstUse  
    }
    -

    -


    \glsxtrpostlinkAddSymbolOnFirstUse  \glsxtrpostlinkAddSymbolOnFirstUse -

    -

    +

    +


    \glsxtrpostlinkAddSymbolOnFirstUse

    +

    This will append the symbol (if defined) in parentheses on first use. (Does nothing if the symbol hasn’t been set.) -


    \glsxtrpostlinkAddSymbolDescOnFirstUse  \glsxtrpostlinkAddSymbolDescOnFirstUse -

    -

    +


    \glsxtrpostlinkAddSymbolDescOnFirstUse

    +

    (New to v1.31.) On first use, this will append first use, this will append \space(⟨symbol⟩, ⟨description⟩) if the symbol is defined otherwise it just appends \space(⟨description⟩). -

    If you want to provide your own custom format be aware that you can’t use +

    If you want to provide your own custom format be aware that you can’t use \ifglsused within the post- within the post-link-text hook as by this point the first use flag will have been unset. Instead you can use -


    \glsxtrifwasfirstuse 


    \glsxtrifwasfirstuse{true}{false}

    -

    +

    This will do ⟨true⟩ if the last used entry was the first use for that entry, otherwise it + id="dx1-9054">first use for that entry, otherwise it will do ⟨false⟩. (Requires at least glossaries v4.19 to work properly.) This command is locally set by commands like \gls, so don’t rely on it outside of the post-link-text + id="dx1-9055">link-text hook. -

    Note that commands like

    Note that commands like \glsfirst and and \glsxtrfull fake first use for the + id="dx1-9057"> fake first use for the benefit of the post-link-text hooks by setting link-text hooks by setting \glsxtrifwasfirstuse to \@firstoftwo. (Although, depending on the styles in use, they may not exactly match the text produced by \gls-like commands on first use.) However, the + id="dx1-9060">-like commands on first use.) However, the short-postfootnote style alters style alters \glsxtrfull so that it fakes non-first use otherwise + id="dx1-9063">first use otherwise the inline full format would include the footnote, which is inappropriate.
    -

    -

    For example, if you want to place the description in a footnote after the link-text +

    +

    For example, if you want to place the description in a footnote after the link-text on first use for the first use for the general category: + id="dx1-9066"> category:

    -
    +
    \newcommand*{\glsxtrpostlinkgeneral}{%  
      \glsxtrifwasfirstuse{\footnote{\glsentrydesc{\glslabel}}}{}%  
    }
    -

    -

    The

    +

    The short-postfootnote abbreviation style uses the post- abbreviation style uses the post-link-text hook to place the footnote after trailing punctuation characters. -

    You can set the default options used by \glslink, \gls etc with: -


    \GlsXtrSetDefaultGlsOpts  \GlsXtrSetDefaultGlsOpts{options}

    -

    -For example, if you mostly don’t want to index entries then you can do: +

    +

    +

    Top

    2.5 Entry Counting Modifications

    +

    If you are using bib2gls you may find it more convenient to use the record +count commands described in §9 bib2gls: Managing Reference Databases +instead. +

    The \glsenableentrycount command is modified to allow for the entrycount +attribute. This means that you not only need to enable entry counting with +\glsenableentrycount, but you also need to set the appropriate attribute (see §6 +Categories). +

    For example, instead of just doing:

    -
    -\GlsXtrSetDefaultGlsOpts{noindex} +
    +\glsenableentrycount
    -

    and then use, for example, \gls[noindex=false]{sample} when you actually want -the location added to the number list. These defaults may be overridden by other -settings (such as category attributes) in addition to any settings passed in the option -argument of commands like \glslink and \gls. -

    Note that if you don’t want any indexing, just omit \makeglossaries and -\printglossaries (or analogous commands). If you want to adjust the -default for wrgloss, it’s better to do this by redefining \glsxtrinitwrgloss -instead. -

    \GlsXtrSetDefaultGlsOpts doesn’t affect \glsadd.
    -

    -

    If you want to change the default value of format, you can instead use: -


    \GlsXtrSetDefaultNumberFormat{format}

    -

    -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 -overridden): - - - -

    -
    -\backmatter - 
    \GlsXtrSetDefaultNumberFormat{hyperit} -
    -

    -

    Commands like \gls have star (*) and plus (+) modifiers as a short cut for -hyper=false and hyper=true. The glossaries-extra package provides a way to add a -third modifier, if required, using -


    \GlsXtrSetAltModifier  \GlsXtrSetAltModifier{char}{options} -

    -

    -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). -

    When choosing the character ⟨char⟩ take care of any changes in category code. -
    -

    -

    Example: - - - -

    -
    -\GlsXtrSetAltModifier{!}{noindex} -
    -

    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 - - - -

    -
    -\gls[noindex,hyper=false]{sample} -
    -

    you can use \gls*[noindex]{sample} or \gls![hyper=false]{sample} but you -can’t combine the * and ! modifiers. -

    Location lists displayed with \printnoidxglossary internally use -


    \glsnoidxdisplayloc  \glsnoidxdisplayloc{prefix}{counter}{format} -{location}

    -

    -This command is provided by glossaries, but is modified by glossaries-extra to check -for the start and end range formation identifiers ( and ) which are discarded to -obtain the actual control sequence name that forms the location formatting -command. -

    If the range identifiers aren’t present, this just uses -


    \glsxtrdisplaysingleloc  \glsxtrdisplaysingleloc{format}{location} -

    -

    -otherwise it uses -


    \glsxtrdisplaystartloc  \glsxtrdisplaystartloc{format}{location} -

    -

    -for the start of a range (where the identifier has been stripped from ⟨format⟩) -or -


    \glsxtrdisplayendloc  \glsxtrdisplayendloc{format}{location} -

    -

    -for the end of a range (where the identifier has been stripped from ⟨format⟩). -

    By default the start range command saves the format in -


    \glsxtrlocrangefmt  \glsxtrlocrangefmt

    -

    -and does -
    \glsxtrdisplaysingleloc{format}{location} -
    -(If the format is empty, it will be replaced with glsnumberformat.) -

    The end command checks that the format matches the start of the range, -does -


    \glsxtrdisplayendlochook  \glsxtrdisplayendlochook{format}{location} -

    -

    -(which does nothing by default), followed by -
    \glsxtrdisplaysingleloc{format}{location} -
    -and then sets \glsxtrlocrangefmt to empty. - - - -

    This means that the list - - - -

    -
    -\glsnoidxdisplayloc{}{page}{(textbf}{1}, - 
    \glsnoidxdisplayloc{}{page}{textbf}{1}, - 
    \glsnoidxdisplayloc{}{page}{)textbf}{1}. -
    -

    doesn’t display any differently from +

    you now need to do:

    -\glsnoidxdisplayloc{}{page}{textbf}{1}, - 
    \glsnoidxdisplayloc{}{page}{textbf}{1}, - 
    \glsnoidxdisplayloc{}{page}{textbf}{1}. -
    -

    but it does make it easier to define your own custom list handler that can -accommodate the ranges. -

    -

    -

    Top

    2.4 Entry Counting Modifications

    -

    If you are using bib2gls you may find it more convenient to use the record -count commands described in §9 bib2gls: Managing Reference Databases -instead. -

    The \glsenableentrycount command is modified to allow for the entrycount -attribute. This means that you not only need to enable entry counting with -\glsenableentrycount, but you also need to set the appropriate attribute (see §5 -Categories). -

    For example, instead of just doing: - - - -

    -
    -\glsenableentrycount -
    -

    you now need to do: - - - -

    -
    \glsenableentrycount  
    \glssetcategoryattribute{abbreviation}{entrycount}{1}
    -

    This will enable the entry counting for entries in the

    This will enable the entry counting for entries in the abbreviation category, but any + id="dx1-10004"> category, but any entries assigned to other categories will be unchanged. -

    Further information about entry counting, including the new per-unit feature, is +

    Further information about entry counting, including the new per-unit feature, is described in §6.1 §7.1 Entry Counting (First Use Flag). -

    +

    -

    Top

    2.5

    Top

    2.6 First Use Flag

    -

    The

    The glossaries package provides -



    \ifglsused{label}{true}{false}

    -

    +

    to determine whether or not an entry has been used. This requires the entry to have been defined. If the entry is undefined, then the underlying boolean variable doesn’t exist and so is neither true nor false. This command will produce an error with the @@ -4691,44 +4427,40 @@ default undefaction=error mode and a warning with mode and a warning with undefaction=warn and, where + id="dx1-11003"> and, where appropriate, displays ?? in the document text to denote an undefined reference. With both modes, neither ⟨true⟩ nor ⟨false⟩ will be performed if ⟨label⟩ doesn’t exist. -

    The

    The record option automatically implements option automatically implements undefaction=warn since no entries + id="dx1-11005"> since no entries will be defined until they have been selected by bib2gls. In this case, you may prefer to use: -


    \GlsXtrIfUnusedOrUndefined 


    \GlsXtrIfUnusedOrUndefined{label}{true} -{}{false}

    -

    +

    (new to v1.34) which does ⟨true⟩ if the entry given by ⟨label⟩ is undefined or if @@ -4737,41 +4469,37 @@ class="cmtt-10">\ifglsused nor \GlsXtrIfUnusedOrUndefined should be used in the post-link hook as the first use flag will have already been unset before the hook is performed. (Instead, \glsxtrifwasfirstuse should be used, see should be used, see §2.3 §2.4 Entry Display Style Modifications.) -

    There are two new commands provided with version 1.31+: -


    \glslocalreseteach 

    There are two new commands provided with version 1.31+: +


    \glslocalreseteach{list}

    -

    +

    and -


    \glslocalunseteach 


    \glslocalunseteach{list}

    -

    +

    These behave like \glslocalreset and \glslocalunset but the argument is a +comma-separated list of labels. -comma-separated list of labels. -

    The internal command used by

    The internal command used by \glsunset is modified first to allow for the changing in entry counting, described above, but also to allow for buffering pending unsets when commands like \gls are used in a context where changing a boolean variable can cause things to go wrong. One example of this is using \gls in one of the commands provided with the package. For example: + id="dx1-11012">package. For example:

    -
    +
    \ul{Some text about \gls{html}.}
    -

    This causes the confusing error: +

    This causes the confusing error:

    -
    +
    Glossary entry `{html}' has not been defined.
    -

    The simplest workaround is to put

    The simplest workaround is to put \gls{html} inside the argument of \mbox. For example: @@ -4803,29 +4531,27 @@ example:

    -
    +
    \ul{Some text about \mbox{\gls{html}}.}
    -

    This can work provided it’s not the first use of this entry. It if is, then unsetting the +

    This can work provided it’s not the first use of this entry. It if is, then unsetting the first use flag causes a problem and results in the error:

    -
    +
    ! Package soul Error: Reconstruction failed.
    -

    The

    The glossaries-extra package provides a way of temporarily switching off \glsunset so that it just makes a note of the entry’s label but doesn’t actually perform the change: -


    \GlsXtrStartUnsetBuffering 


    \GlsXtrStartUnsetBuffering

    -

    +

    The unstarred version doesn’t check for duplicates, so the internal list may end up with multiple occurrences of the same label. The starred version only adds a label to the internal list if it’s not already in it. Note that this @@ -4833,14 +4559,12 @@ buffering only applies to the global \glsunset and does not affect the local \glslocalunset. -

    Later you can restore

    Later you can restore \glsunset and unset all buffered labels using: -


    \GlsXtrStopUnsetBuffering 


    \GlsXtrStopUnsetBuffering

    -

    +

    The starred form \GlsXtrStopUnsetBuffering* uses \glslocalunset instead. For @@ -4849,7 +4573,7 @@ example:

    -
    +
    \documentclass{article}  
    \usepackage[T1]{fontenc}  
    \usepackage{soul} @@ -4862,50 +4586,54 @@ example:  
    Next use: \gls{html}.  
    \end{document}
    -

    Before you stop the unset buffering, you can iterate over the current buffer +

    Before you stop the unset buffering, you can iterate over the current buffer using -


    \GlsXtrForUnsetBufferedList 


    \GlsXtrForUnsetBufferedList{cs} -

    -

    +class="cmtt-10">}


    +

    where ⟨cs⟩ is a control sequence that takes a single argument (which is the entry label). This is best used with the starred version \GlsXtrStartUnsetBuffering* to avoid duplicates. -

    Note that since the change in the first use flag now doesn’t occur until +

    You can discard the buffer and restore \glsunset to its normal behaviour with +(new to v1.42): +


    \GlsXtrDiscardUnsetBuffering

    +

    +

    Note that since the change in the first use flag now doesn’t occur until \GlsXtrStopUnsetBuffering, multiple references of the same term within the buffering zone will always be treated as first use (if the term wasn’t used before the buffering started).
    -

    -

    There can still be a problem here as content within

    +

    There can still be a problem here as content within \mbox can’t break across a line so you may end up with an overfull line or excessive white space within the paragraph. -

    An alternative is to use

    An alternative is to use \protect:

    -
    +
    \GlsXtrStartUnsetBuffering  
    \ul{Some text about \protect\gls{html}.}  
    \GlsXtrStopUnsetBuffering
    -

    but the formatting (underlining in this example) won’t be applied. Another +

    but the formatting (underlining in this example) won’t be applied. Another possibility is:

    -
    +
    \usepackage[T1]{fontenc}  
    \usepackage{soul}  
    \usepackage{glossaries-extra} @@ -4922,31 +4650,29 @@ possibility is:  
    Next use: \gls{html}.  
    \end{document}
    -

    This moves

    This moves \gls outside of \ul and uses textformat to locally change the formatting + id="dx1-11017"> to locally change the formatting command used by \gls (which is normally given by \glstextformat or the textformat attribute) to a custom command attribute) to a custom command \gul, which locally changes the regular font and the default abbreviation font to use \ul. It then uses -


    \GlsXtrExpandedFmt 


    \GlsXtrExpandedFmt{cs}{text}

    -

    +

    which (protected) fully expands ⟨text⟩ before applying ⟨cs⟩, which must be a control @@ -4958,137 +4684,135 @@ something that \ul can’t deal with. For example, if an abbreviation style is used that contains complex formatting or if the field value contains problematic content. -

    +

    -

    Top

    2.6

    Top

    2.7 Plurals

    -

    Some languages, such as English, have a general rule that plurals are formed from +

    Some languages, such as English, have a general rule that plurals are formed from the singular with a suffix appended. This isn’t an absolute rule. There are plenty of exceptions (for example, geese, children, churches, elves, fairies, sheep). The glossaries package allows the package allows the plural key to be optional when + id="dx1-12002"> key to be optional when defining entries. In some cases a plural may not make any sense (for example, the term is a symbol) and in some cases the plural may be identical to the singular. -

    To make life easier for languages where the majority of plurals can simply be +

    To make life easier for languages where the majority of plurals can simply be formed by appending a suffix to the singular, the glossaries package lets the package lets the plural + id="dx1-12004"> field default to the value of the text field with field with \glspluralsuffix appended. This + id="dx1-12006"> appended. This command is defined to be just the letter “s”. This means that the majority of terms don’t need to have the plural supplied as well, and you only need to use it for the + id="dx1-12007"> supplied as well, and you only need to use it for the exceptions. -

    For languages that don’t have this general rule, the

    For languages that don’t have this general rule, the plural field will always need to + id="dx1-12008"> field will always need to be supplied, where needed. -

    There are other plural fields, such as

    There are other plural fields, such as firstplural, , longplural and and shortplural. Again, if + id="dx1-12011">. Again, if you are using a language that doesn’t have a simple suffix rule, you’ll have to supply the plural forms if you need them (and if a plural makes sense in the context). -

    If these fields are omitted, the

    If these fields are omitted, the glossaries package follows these rules:

    + id="dx1-12012"> package follows these rules:

    • If firstplural is missing, then is missing, then \glspluralsuffix is appended to the first + id="dx1-12014"> field, if that field has been supplied. If the first field hasn’t been supplied + id="dx1-12015"> field hasn’t been supplied but the plural field has been supplied, then the field has been supplied, then the firstplural field defaults to + id="dx1-12017"> field defaults to the plural field. If the field. If the plural field hasn’t been supplied, then both the field hasn’t been supplied, then both the plural + id="dx1-12020"> and firstplural fields default to the fields default to the text field (or field (or name, if no , if no text field) with + id="dx1-12024"> field) with \glspluralsuffix appended.
    • If the longplural field is missing, then field is missing, then \glspluralsuffix is appended to the long field, if the field, if the long field has been supplied. + id="dx1-12027"> field has been supplied.
    • If the shortplural field is missing then, field is missing then, with the base glossaries acronym mechanism, \acrpluralsuffix is appended to the is appended to the short field. + id="dx1-12031"> field.
    -

    This

    This last case is changed with glossaries-extra. With this extension package, the shortplural field defaults to the field defaults to the short field with field with \abbrvpluralsuffix appended + id="dx1-12034"> appended unless overridden by category attributes. This suffix command is set by the abbreviation styles. This means that every time an abbreviation style is implemented, \abbrvpluralsuffix is redefined. In most cases its redefined to use -


    \glsxtrabbrvpluralsuffix 


    \glsxtrabbrvpluralsuffix

    -

    +

    which defaults to just \glspluralsuffix. Some of the abbreviation styles have their own command for the plural suffix, such as

    If you require a mixture (for example, in a multilingual document), there are two +

    If you require a mixture (for example, in a multilingual document), there are two attributes that affect the short plural suffix formation. The first is aposplural which + id="dx1-12036"> which uses the suffix

    -
    +
    '\abbrvpluralsuffix
    -

    That is, an apostrophe followed by

    That is, an apostrophe followed by \abbrvpluralsuffix is appended. The second attribute is noshortplural which suppresses the suffix and simply sets which suppresses the suffix and simply sets shortplural to the + id="dx1-12038"> to the same as short. -

    + id="dx1-12039">. +

    -

    Top

    2.7

    Top

    2.8 Nested Links

    -

    Complications arise when you use

    Complications arise when you use \gls in the value of the in the value of the name field (or field (or text or or first + id="dx1-13004"> fields, if set). This tends to occur with abbreviations that extend other abbreviations. For example, SHTML is an abbreviation for SSI enabled HTML, where SSI is an abbreviation for Server Side Includes and HTML is an abbreviation for Hypertext Markup Language. -

    Things can go wrong if we try the following with the

    Things can go wrong if we try the following with the glossaries package:

    -
    +
    \newacronym{ssi}{SSI}{Server Side Includes}  
    \newacronym{html}{HTML}{Hypertext Markup Language}  
    \newacronym{shtml}{S\gls{html}}{\gls{ssi} enabled \gls{html}}
    -

    -

    The main problems are: +

    +

    The main problems are:

    1. The first letter upper casing commands, such as \Gls, won’t work for the + id="dx1-13007">, won’t work for the shtml entry on first use if the long form is displayed before the short form (which is the default abbreviation style). This will attempt to do -
      +
      \gls{\uppercase ssi} enabled \gls{html}
      -

      which just doesn’t work. Grouping the

      which just doesn’t work. Grouping the \gls{ssi} doesn’t work either as this will effectively try to do

      -
      +
      \uppercase{\gls{ssi}} enabled \gls{html}
      -

      This will upper case the label

      This will upper case the label ssi so the entry won’t be recognised. This problem will also occur if you use the all capitals version, such as \GLS. + id="dx1-13009">.

    2. The long and abbreviated forms accessed through \glsentrylong and + id="dx1-13012"> and \glsentryshort are no longer expandable and so can’t be used be used in + id="dx1-13013"> are no longer expandable and so can’t be used be used in contexts that require this, such as PDF bookmarks.
    3. The nested commands may end up in the sort key, which will confuse the + id="dx1-13016"> key, which will confuse the indexing.
    4. The shtml entry produces inconsistent results depending on whether the ssi @@ -5225,18 +4949,18 @@ class="cmtt-10">shtml. For example: -
      +
      This section discusses \gls{ssi}, \gls{html} and \gls{shtml}.
      -

      This produces: +

      This produces:

      -

      This section discusses server side includes (SSI), hypertext +

      This section discusses server side includes (SSI), hypertext markup language (HTML) and SSI enabled HTML (SHTML).

      -

      So the

      So the first use of the shtml entry produces “SSI enabled HTML (SHTML)”. -

      Now let’s suppose the

      Now let’s suppose the html entry is used before the shtml but the ssi entry is @@ -5246,41 +4970,41 @@ class="cmtt-10">shtml entry, for example:

      -
      +
      The sample files are either \gls{html} or \gls{shtml}, but let's  
      first discuss \gls{ssi}.
      -

      This produces: +

      This produces:

      -

      The sample files are either hypertext markup language (HTML) +

      The sample files are either hypertext markup language (HTML) or server side includes (SSI) enabled HTML (SHTML), but let’s first discuss SSI.

      -

      So the

      So the first use of the shtml entry now produces “server side includes (SSI) enabled HTML (SHTML)”, which looks a bit strange. -

      Now let’s suppose the

      Now let’s suppose the shtml entry is used before (or without) the other two entries:

      -
      +
      This article is an introduction to \gls{shtml}.
      -

      This produces: +

      This produces:

      -

      This article is an introduction to server side includes (SSI) +

      This article is an introduction to server side includes (SSI) enabled hypertext markup language (HTML) (SHTML).

      -

      So the

      So the first use of the shtml entry now produces “server side includes (SSI) enabled hypertext markup language (HTML) (SHTML)”, which is even more strange. -

      This is all aggravated by setting the style using the

      This is all aggravated by setting the style using the glossaries package’s \setacronymstyle. For example: @@ -5288,22 +5012,22 @@ class="cmtt-10">\setacronymstyle. For example:

      -
      +
      \setacronymstyle{long-short}
      -

      as this references the label through the use of

      as this references the label through the use of \glslabel when displaying the long and short forms, but this value changes with each use of \gls, so instead of displaying “(SHTML)” at the end of the first use, it now displays “(HTML)”, since \glslabel has been changed to html by \gls{html}. -

      Another oddity occurs if you reset the

      Another oddity occurs if you reset the html entry between uses of the shtml entry. For example: @@ -5311,27 +5035,27 @@ class="cmtt-10">shtml

      -
      +
      \gls{shtml} ... \glsreset{html}\gls{shtml}
      -

      The next use of

      The next use of shtml produces “Shypertext markup language (HTML)”, which is downright weird. -

      Even without this, the short form has nested formatting commands, which +

      Even without this, the short form has nested formatting commands, which amount to \acronymfont{S\acronymfont{HTML}}. This may not be a problem for some styles, but if you use one of the “sm” styles (that use \textsmaller), + id="dx1-13023">), this will produce an odd result.

    5. Each time the shtml entry is used, the html entry will also be indexed and marked as used, and on first use this will happen to both the ssi and html @@ -5339,86 +5063,86 @@ class="cmtt-10">html helpful to the reader.
    6. If hyperref is in use, you’ll get nested hyperlinks and there’s no consistent way + id="dx1-13029"> is in use, you’ll get nested hyperlinks and there’s no consistent way of dealing with this across the available PDF viewers. If on the first + id="dx1-13030">first use case, the user clicks on the “HTML” part of the “SSI enabled HTML (SHTML)” link, they may be directed to the HTML entry in the glossary or they may be directed to the SHTML entry in the glossary.
    -

    For these reasons it’s better to use the simple expandable commands +

    For these reasons it’s better to use the simple expandable commands like \glsentrytext or or \glsentryshort in the definition of other entries + id="dx1-13032"> in the definition of other entries (although that doesn’t fix the first problem). Alternatively use something like:

    -
    +
    \newacronym  
     [description={\acrshort{ssi} enabled \acrshort{html}}]  
     {shtml}{SHTML}{SSI enabled HTML}
    -

    with

    with glossaries or:

    -
    +
    \newabbreviation  
     [description={\glsxtrshort{ssi} enabled \glsxtrshort{html}}]  
     {shtml}{SHTML}{SSI enabled HTML}
    -

    with

    with glossaries-extra. This fixes all the above listed problems (as long as you don’t use \glsdesc). Note that replacing ). Note that replacing \gls with \acrshort in the original example may fix the first use issue, but it doesn’t fix any of the other problems listed above. -

    If it’s simply that you want to use the abbreviation font, you can use +

    If it’s simply that you want to use the abbreviation font, you can use \glsabbrvfont:

    -
    +
    \setabbreviationstyle{long-short-sc}  
    \newabbreviation{ssi}{ssi}{server-side includes}  
    \newabbreviation{html}{html}{hypertext markup language}  
    \newabbreviation{shtml}{shtml}{\glsabbrvfont{ssi} enabled  
    \glsabbrvfont{html}}
    -

    This will pick up the font style setting of the outer entry (shtml, in the above case). +

    This will pick up the font style setting of the outer entry (shtml, in the above case). This isn’t a problem in the above example as all the abbreviations use the same style. -

    However if you’re really determined to use

    However if you’re really determined to use \gls in a field that may be included + id="dx1-13035"> in a field that may be included within some link-text, glossaries-extra patches internals used by the linking commands so that if \gls (or plural or case changing variants) occurs in the link-text it will + id="dx1-13037">link-text it will behave as though you used \glstext[hyper=false,noindex] instead. Grouping is also added so that, for example, when \gls{shtml} is used for the first time the long @@ -5427,19 +5151,19 @@ form

    -
    +
    \gls{ssi} enabled \gls{html}
    -

    is treated as +

    is treated as

    -
    +
    {\glstext[hyper=false,noindex]{ssi}} enabled  
    {\glstext[hyper=false,noindex]{html}}
    -

    This overcomes problems 

    This overcomes problems 4, 5 and 6 listed above, but still doesn’t fix problems 2. Problem 3 usually won’t be an issue as most abbreviation styles set the sort + id="dx1-13039"> key to the short form, so using these commands in the long form but not the short form will only affect entries with a style that sorts according to the long form (such as long-noshort-desc). -

    Additionally, any instance of the long form commands, such as ). +

    Additionally, any instance of the long form commands, such as \glsxtrlong or + id="dx1-13041"> or \acrlong will be temporarily redefined to just use

    + id="dx1-13042"> will be temporarily redefined to just use

    {\glsentrylong{label}}
    (or case-changing versions). Similarly the short form commands, such as \glsxtrshort or or \acrshort will use will use \glsentryshort in the argument of either + id="dx1-13046"> in the argument of either \glsabbrvfont (for \glsxtrshort) or shtml entry had instead been defined as: -
    +
    \newacronym{shtml}{SHTML}{\acrshort{ssi} enabled \acrshort{html}}
    -

    then (using the

    then (using the long-short style) the style) the first use will be like

    -
    +
    {\acronymfont{\glsentryshort{ssi}}} enabled  
    {\acronymfont{\glsentryshort{html}}} (SHTML)
    -

    whereas if the entry is defined as: +

    whereas if the entry is defined as:

    -
    +
    \newabbreviation{shtml}{SHTML}{\glsxtrshort{ssi} enabled  
    \glsxtrshort{html}}
    -

    then the

    then the first use will be like:

    -
    +
    {\glsabbrvfont{\glsentryshort{ssi}}} enabled  
    {\glsabbrvfont{\glsentryshort{html}}} (SHTML)
    -

    Note that the first optional argument of

    Note that the first optional argument of \acrshort or \glsxtrshort is ignored in this context. (The final optional argument will be inserted, if present.) The abbreviation style that governs \glsabbrvfont will be set for will be set for \glsxtrshort. Note + id="dx1-13051">. Note that \acrshort doesn’t set the abbreviation style. -

    Alternatively you can use: -


    \glsxtrp 

    Alternatively you can use: +


    \glsxtrp{field}{label}

    -

    +

    where ⟨field⟩ is the field label and corresponds to a command in the form \gls\glstext) or in the form \glsxtrfield⟩ (e.g. \glsxtrshort). -

    There’s a shortcut command for the most common fields: -


    \glsps 

    There’s a shortcut command for the most common fields: +


    \glsps{label}

    -

    +

    which is equivalent to \glsxtrp{short}{label}, and -


    \glspt 


    \glspt{label}

    -

    +

    which is equivalent to \glsxtrp{text}{label}. -

    The

    The \glsxtrp command behaves much like the \glsfmtfield⟩ commands described in §4 §5 Entries in Sectioning Titles, Headers, Captions and Contents but the post-link hook is also suppressed and extra grouping is added. It automatically sets hyper to to false and noindex to to true. If you want to change this, you can use -


    \glsxtrsetpopts 


    \glsxtrsetpopts{options}

    -

    +

    For example:

    -
    +
    \glsxtrsetpopts{hyper=false}
    -

    will just switch off the hyperlinks but not the indexing. Be careful using +

    will just switch off the hyperlinks but not the indexing. Be careful using this command or you can end up back to the original problem of nested links. -

    The hyper link is re-enabled within glossaries. This is done through the +

    The hyper link is re-enabled within glossaries. This is done through the command: -


    \glossxtrsetpopts 


    \glossxtrsetpopts

    -

    +

    which by default just does

    -
    +
    \glsxtrsetpopts{noindex}
    -

    You can redefine this if you want to adjust the setting when

    You can redefine this if you want to adjust the setting when \glsxtrp is used in the glossary. For example:

    -
    +
    \renewcommand{\glossxtrsetpopts}{\glsxtrsetpopts{noindex=false}}
    -

    -

    For example, +

    +

    For example,

    -
    +
    \glsxtrp{short}{ssi}
    -

    is equivalent to +

    is equivalent to

    -
    +
    {\let\glspostlinkhook\relax  
     \glsxtrshort[hyper=false,noindex]{ssi}[]%  
    }
    -

    in the main body of the document or +

    in the main body of the document or

    -
    +
    {\let\glspostlinkhook\relax  
     \glsxtrshort[noindex]{ssi}[]%  
    }
    -

    inside the glossary. (Note the post-link hook is locally disabled.) -

    If

    inside the glossary. (Note the post-link hook is locally disabled.) +

    If \glsxtrp{short}{ssi} occurs in a sectioning mark, it’s equivalent to

    -
    +
    {\glsxtrheadshort{ssi}}
    -

    (which recognises the

    (which recognises the headuc attribute.) -

    If attribute.) +

    If hyperref has been loaded, then the bookmark will use has been loaded, then the bookmark will use \glsentryfield⟩ (\glsentryshort{ssi} in the above example). -

    There are similar commands -


    \Glsxtrp 

    There are similar commands +


    \Glsxtrp{field}{label}

    -

    +

    for first letter upper case and -


    \GLSxtrp 


    \GLSxtrp{field}{label}

    -

    +

    for all upper case. -

    If you use any of the case-changing commands, such as

    If you use any of the case-changing commands, such as \Gls or or \Glstext, (either + id="dx1-13064">, (either all caps or first letter upper casing) don’t use any of the linking commands, such as \gls or or \glstext, in the definition of entries for any of the fields that may be used + id="dx1-13066">, in the definition of entries for any of the fields that may be used by those case-changing commands.
    -

    -

    You can, with care, protect against issue 

    +

    You can, with care, protect against issue 1 by inserting an empty group at the start if the long form starts with a command that breaks the first letter uppercasing commands like \Gls, but you still won’t be able to use the all caps commands, such as \GLS. -

    If you

    If you really need nested commands, the safest method is

    -
    +
    \newabbreviation{shtml}{shtml}{{}\glsxtrp{short}{ssi} enabled  
    \glsxtrp{short}{html}}
    -

    but be aware that it may have some unexpected results occasionally. -

    Example document: +

    but be aware that it may have some unexpected results occasionally. +

    Example document:

    -
    +
    \documentclass{report}  
    \usepackage[utf8]{inputenc}  
    \usepackage[T1]{fontenc} @@ -5782,23 +5492,23 @@ class="cmti-10">really need nested commands, the safest method is  
    \printglossaries  
    \end{document}
    -

    -

    +

    +

    -

    Top

    2.8

    Top

    2.9 Acronym Style Modifications

    +

    The glossaries-extra package provides a new way of dealing with abbreviations and -

    The glossaries-extra package provides a new way of dealing with abbreviations and redefines \newacronym to use to use \newabbreviation (see §3 §4 Abbreviations). The simplest way to update a document that uses \newacronym from glossaries-extra is do just add

    -
    +
    \setabbreviationstyle[acronym]{long-short}
    -

    before you define any entries. For example, the following document using just +

    before you define any entries. If you have used commands like \acrshort, \acrlong +and \acrfull, you need to substitute them with \glsxtrshort, \glsxtrlong and +\glsxtrfull. (This includes plural and case-changing forms.) Your text editor’s +search and replace function should help with this. If you have used the shortcuts +package option then use shortcuts=ac in order to continue using the shortcut +commands like \ac. With this setting, \acs will use \glsxtrshort instead of \acrshort etc. +

    For example, the following document using just glossaries

    -
    +
    \documentclass{article}  
    \usepackage[acronym,nopostdot,toc]{glossaries}  
    \makeglossaries @@ -5830,13 +5573,13 @@ class="cmss-10">glossaries  
    \printglossaries  
    \end{document}
    -

    can be easily adapted to use

    can be easily adapted to use glossaries-extra:

    -
    +
    \documentclass{article}  
    \usepackage[acronym]{glossaries-extra}  
    \makeglossaries @@ -5847,14 +5590,14 @@ class="cmss-10">glossaries-extra:  
    \printglossaries  
    \end{document}
    -

    Table 

    Table 2.1 lists the nearest equivalent glossaries-extra abbreviation styles for the predefined acronym styles provided by glossaries, but note that the new styles use different formatting commands. See §3.4 §4.4 Predefined Abbreviation Styles for further details.

    @@ -5862,7 +5605,7 @@ details. -


    @@ -5879,44 +5622,44 @@ class="cmtt-10">\setabbreviationstyle[⟨category]{new-style-name}
    +class="cmtt-10">}
    + id="dx1-14016">

    + id="dx1-14018">

    + id="dx1-14022">

    + id="dx1-14024">

    + id="dx1-14026">

    + id="dx1-14028">

    + id="dx1-14030">

    + id="dx1-14032">

    + id="dx1-14036">

    + id="dx1-14038">

    + id="dx1-14040">

    + id="dx1-14042">

    + id="dx1-14044">

    + id="dx1-14046">

    + id="dx1-14048">

    + id="dx1-14050">

    + id="dx1-14052">

    + id="dx1-14054">

    Old Style Name

    Old Style Name

    New Style Name

    long-sc-short

    long-short-sc

    long-sm-short

    long-short-sm

    long-sp-short

    long-short

    with \renewcommand{{#1}}

    short-long

    short-long

    sc-short-long

    short-sc-long

    sm-short-long

    short-sm-long

    long-short-desc

    long-short-desc

    long-sc-short-desc

    long-short-sc-desc

    long-sm-short-desc

    long-short-sm-desc

    long-sp-short-desc

    long-short-desc

    with \renewcommand{{#1}}

    short-long-desc

    short-long-desc

    sc-short-long-desc

    short-sc-long-desc

    sm-short-long-desc

    short-sm-long-desc

    dua

    long-noshort

    dua-desc

    long-noshort-desc

    footnote

    short-footnote

    footnote-sc

    short-sc-footnote

    footnote-sm

    short-sm-footnote

    footnote-desc

    short-footnote-desc

    footnote-sc-desc

    short-sc-footnote-desc

    footnote-sm-desc

    short-sm-footnote-desc

    + id="dx1-14056">


    -

    The reason for introducing the new style of abbreviation commands provided by +

    The reason for introducing the new style of abbreviation commands provided by glossaries-extra is because the original acronym commands provided by glossaries are @@ -6115,3290 +5858,3274 @@ class="cmss-10">glossaries-extra. However, if you really want to restore the generic acronym function provided by glossaries you can use -


    \RestoreAcronyms 


    \RestoreAcronyms

    -

    +

    (before any use of \newacronym). -

    \RestoreAcronyms should not be used in combination with the newer glossaries-extra abbreviations. Don’t combine old and new style entries with the same type. The original . The original glossaries acronym mechanism doesn’t work well with the newer glossaries-extra commands. -

    If you use

    If you use \RestoreAcronyms, don’t use any of the commands provided by glossaries-extra intended for abbreviations (such as \glsxtrshort or or \glsfmtshort) + id="dx1-14060">) with entries defined via \newacronym as it will cause unexpected results. + id="dx1-14061"> as it will cause unexpected results.
    -

    -

    In general, there’s rarely any need for

    +

    In general, there’s rarely any need for \RestoreAcronyms. If you have a document that uses \newacronymstyle, then it’s best to either stick with just + id="dx1-14062">, then it’s best to either stick with just glossaries for that document or define an equivalent abbreviation style with \newabbreviationstyle. (See . (See §3.5 §4.5 Defining New Abbreviation Styles for further details.) -


    \glsacspace 


    \glsacspace{label}

    -

    +

    The space command \glsacspace used by the long-sp-short acronym style provided + id="dx1-14065"> acronym style provided by glossaries is modified so that it uses -


    \glsacspacemax 


    \glsacspacemax

    -

    +

    instead of the hard-coded 3em. This is a command not a length and so can be changed using \renewcommand. -

    Any of the new abbreviation styles that use

    Any of the new abbreviation styles that use \glsxtrfullsep (such as (such as long-short) + id="dx1-14068">) can easily be changed to use \glsacspace with

    -
    +
    \renewcommand*{\glsxtrfullsep}[1]{\glsacspace{#1}}
    -

    -

    The

    +

    The first use acronym font command -



    \firstacronymfont{text}

    -

    +

    is redefined to use the first use abbreviation font command first use abbreviation font command \glsfirstabbrvfont. + id="dx1-14071">. This will be reset if you use \RestoreAcronyms. -

    The subsequent use acronym font command -


    The subsequent use acronym font command +


    \acronymfont{text}

    -

    +

    is redefined to use the subsequent use abbreviation font command \glsabbrvfont. + id="dx1-14072">. This will be reset if you use \RestoreAcronyms.

    -

    Top

    2.9 glossary-bookindex package

    -

    As from v1.21, glossaries-extra has a new supplementary package glossary-bookindex -which provides the glossary style bookindex. This is very similar to the mcolindexgroup -style but is designed for indexes, so by default only the name and location list -are displayed. You can either load this package explicitly and then set the -style: +

    Top

    2.10 Glossaries

    +

    The \newignoredglossary{type} command now (as from v1.11) has a starred +version that doesn’t automatically switch off the hyperlinks. This starred version may +be used with the targeturl attribute to create a link to an external URL. (See §6 +Categories for further details.) As from v1.12 both the starred and unstarred version +check that the glossary doesn’t already exist. (The glossaries package omits this +check.) +

    You can now provide an ignored glossary with: +


    \provideignoredglossary{type}

    +

    +which will only define the glossary if it doesn’t already exist. This also has a starred +version that doesn’t automatically switch off hyperlinks. +

    The individual glossary displaying commands \printglossary, \printnoidxglossary +and \printunsrtglossary have extra keys: +

    +
      +
    • target. This is a boolean key which can be used to switch off the automatic + hypertarget for each entry. Unlike \glsdisablehyper this doesn’t switch + off hyperlinks, so any cross-references within the glossary won’t be affected. + This is a way of avoiding duplicate target warnings if a glossary needs to + be displayed multiple times. +
    • +
    • targetnameprefix={prefix}. Another way of avoiding duplicate target names + is to set a prefix used for the names. Unlike changing \glolinkprefix + this doesn’t affect any hyperlinks (such as those created with \gls). +
    • +
    • prefix={prefix}. If you do actually want to locally change \glolinkprefix, + you can use the prefix key instead. You need to use the matching prefix + key in commands like \gls. +
    • +
    • label={label}. Labels the glossary with \label{label} and also defines + \@currentlabelname to the glossary’s TOC title (to provide text for + \nameref). You can also set the label before the glossary using: +


      \glsxtrsetglossarylabel{label}

      +

      + but take care of duplicate labels if it’s not scoped.

    +

    -
    -\usepackage{glossaries-extra} - 
    \usepackage{glossary-bookindex} - 
    \setglossarystyle{bookindex} -
    -

    or use both the

    Top

    2.10.1 Glossary Style Modifications

    +

    The glossaries-extra-stylemods package (more conveniently loaded through the +glossaries-extra stylemods and style options: + id="dx1-16002"> option) modifies some of the predefined styles that are +provided with the glossaries package. These modifications are described in more detail +in §2.10.1 The glossaries-extra-stylemods Package. +

    The glossaries package tries to determine the group title from its label by first +checking if \labelgroupname exists. If it doesn’t exist, then the title is assumed to be +the same as the label. For example, when typesetting the “A” letter group, glossaries +first checks if \Agroupname exists. This could potentially cause conflict with another +package that may have some other meaning for \Agroupname, so glossaries-extra first +checks for the existence of the internal command \glsxtr@grouptitle@label⟩ +which shouldn’t clash with another package. You can set the group title +using +


    \glsxtrsetgrouptitle{label}{title}

    +

    +For example:

    -
    -\usepackage[stylemods=bookindex,style=bookindex]{glossaries-extra} +
    +\glsxtrsetgrouptitle{A}{A (a)}
    -

    The bookindex style only supports a maximum hierarchical level of 2 (top-level, -level 1 and level 2). It’s primarily designed for use with bib2gls. It may be used -with other indexing options, but some features may not be present and UTF-8 -characters may cause a problem with non-Unicode engines in letter group -headings or PDF bookmarks. (bib2gls uses numeric identifies by default to -avoid these problems. If numbers show up in the group headings instead of -the appropriate characters, check that you have used the record package -option.) -

    The number of columns is given by -


    \glsxtrbookindexcols  \glsxtrbookindexcols

    -

    -which defaults to 2. -

    This style uses the multicols environment. If the command -


    \glsxtrbookindexcolspread  \glsxtrbookindexcolspread

    -

    -isn’t empty then it’s supplied as the optional argument following \begin{multicols} -{n}. You can switch from multicols to multicols* by redefining -


    \glsxtrbookindexmulticolsenv  \glsxtrbookindexmulticolsenv

    -

    -For example - - - +

    This uses a global assignment. If you need to scope the change you can +use +


    \glsxtrlocalsetgrouptitle{label}{title}

    +

    +

    -
    -\renewcommand{\glsxtrbookindexmulticolsenv}{multicols*} +
    Style Hooks
    +

    The commands \glossentryname and \glossentrydesc are modified to take into +account the glossname, glossnamefont, glossdesc and glossdescfont attributes +(see §6 Categories). This means you can make simple font or case-changing +modifications to the name and description without defining a new glossary +style. +

    (New to version 1.42.) The command \glossentrysymbol is modified to take into +account the glosssymbolfont. Note that, unlike the above, there’s no corresponding +attribute to change the case as it’s usually not appropriate to change the case of a +symbol (and for some symbols, such as pictographs, there’s no concept of case). If +\texorpdfstring has been defined \glossentrysymbol will be defined to do: +

    +
    +\texorpdfstring{TEX code}{PDF}
    -

    -

    Each top-level entry is displayed using -


    \glsxtrbookindexname  \glsxtrbookindexname{ The ⟨TEX code⟩ part is robust and deals with the actual typesetting of the symbol. +The ⟨PDF⟩ part is simply: +


    \glsentrypdfsymbol{label}

    -

    -where the entry is identified by ⟨label⟩. This just does \glossentryname{

    +which is defined to just do \glsentrysymbol{label} by -default. For example, if you want the symbol to be included: +class="cmtt-10">}. The chances are that the code +in the symbol key won’t be valid in the PDF bookmarks, so you can redefine +\glsentrypdfsymbol to use a more appropriate field. (If you do redefine this +command, remember that it needs to fully expand.) +

    For example, if you are using glossaries-accsupp, you could use the symbolaccess +field:

    -
    -\renewcommand*{\glsxtrbookindexname}[1]{% - 
     \glossentryname{#1}% - 
     \ifglshassymbol{#1}{\space (\glossentrysymbol{#1})}{}% - 
    } +
    +\renewcommand{\glsentrypdfsymbol}[1]{\glsentrysymbolaccess{#1}}
    -

    or if you want the description (if set): +

    Alternatively, if you are using bib2gls you can use the TEX parser library to +interpret a copy of the symbol field and use that. For example, with the resource +options:

    -
    -\renewcommand*{\glsxtrbookindexname}[1]{% - 
     \glossentryname{#1}% - 
     \ifglshasdesc{#1}{\space \glossentrydesc{#1}\glspostdescription}{}% - 
    } +
    +  replicate-fields={symbol=user1}, + 
      interpret-fields={user1}
    -

    (which picks up the post-description hook). -

    Alternatively you can use the \glsxtrpostnamecategory⟩ hook to append -information after the name according to the entry’s category. -

    Sub-entries are displayed using -


    \glsxtrbookindexsubname  \glsxtrbookindexsubname{label}

    -

    -which just defaults to \glsxtrbookindexname{label}. -

    The separator used before the location list for top-level entries is given -by -


    \glsxtrbookindexprelocation  \glsxtrbookindexprelocation{label} -

    -

    -where ⟨label⟩ is the entry’s label. This checks if the location field has been set. If it -has, it does +

    This stores the interpreted value of the symbol in the user1 field, so you can then +do:

    -
    -,\glsxtrprelocation +
    +\renewcommand{\glsentrypdfsymbol}[1]{\glsentryuseri{#1}}
    -

    otherwise it just does \glsxtrprelocation (which defaults to \space). If you’re not -using bib2gls, the location field won’t be set. -

    The separator used before the location list for sub-entries is given by -


    \glsxtrbookindexsubprelocation  \glsxtrbookindexsubprelocation{label} -

    -

    -which defaults to \glsxtrbookindexprelocation{label}. -

    The actual location list is encapsulated with: -


    \glsxtrbookindexlocation  \glsxtrbookindexlocation{

    (You may need XƎLATEX or LuaLATEX with this method.) This allows +\glossentrysymbol to be used in a section heading with standalone definitions. +

    If you want to adapt a style to use another field instead of name, you can +use +


    \glossentrynameother{label}{location +class="cmitt-10">field⟩}

    +

    +This behaves just like \glossentryname (that is, it obeys glossname, glossnamefont or list\glsnamefont and uses the post-name hook) but it uses the given ⟨field⟩ instead of +name. The ⟨field⟩ argument must be the internal field name (for example desc rather +than description). See the key to field mappings table in the glossaries user +manual. +

    There is a hook after \glossentryname and \Glossentryname: +


    \glsxtrpostnamehook{label}

    -

    -for top-level entries and -


    \glsxtrbookindexsublocation  \glsxtrbookindexsublocation{

    +By default this checks the indexname attribute. If the attribute exists for the +category to which the label belongs, then the name is automatically indexed +using +


    \glsxtrdoautoindexname{label} +class="cmtt-10">}{indexname}

    +

    +See §8 Auto-Indexing for further details. +

    As from version 1.04, the post-name hook \glsxtrpostnamehook will also use {location list}


    -

    -for sub-entries. These both just do ⟨location list⟩ by default. -

    The separator used between a top-level parent and child entry is given -by -


    \glsxtrbookindexparentchildsep  \glsxtrbookindexparentchildsep -

    -

    -This defaults to \nopagebreak. -

    The separator used between a sub-level parent and child entry is given -by -


    \glsxtrbookindexparentsubchildsep  \glsxtrbookindexparentsubchildsep -

    -

    -This defaults to \glsxtrbookindexparentchildsep. -

    The separator between top-level entries is given by -


    \glsxtrbookindexbetween  \glsxtrbookindexbetween{label1}{label2} -

    -

    -This comes after the entry given by ⟨label1⟩, if the entry has no children, or after the -last descendent otherwise, so it always comes immediately before the entry given by -⟨label2⟩ unless the entry occurs at the start of a group. This does nothing by -default. -

    The separator between two level 1 entries is given by -


    \glsxtrbookindexsubbetween  \glsxtrbookindexsubbetween{label1}{label2} -

    +class="cmtt-10">\glsxtrpostname
    category⟩ if it exists. You can use \glscurrententrylabel to +obtain the entry label with the definition of this command. For example, +suppose you are using a glossary style the doesn’t display the symbol, you can +insert the symbol after the name for a particular category, say, the “symbol” +category: -

    -

    The separator between two level 2 entries is given by -


    \glsxtrbookindexsubsubbetween  \glsxtrbookindexsubsubbetween{label1} -{label2 +
    +\newcommand*{\glsxtrpostnamesymbol}{\space + 
     (\glsentrysymbol{\glscurrententrylabel})} +
    +

    For convenience, as from v1.31, you can use +


    \glsdefpostname{category}{definition}

    -

    -At the end of each letter group, the following hooks are done in order: -


    \glsxtrbookindexsubsubatendgroup  \glsxtrbookindexsubsubatendgroup +

    +This is simply a shortcut for:

    +
    \csdef{glsxtrpostnamecategory}{sub-sub-label}

    -

    -


    \glsxtrbookindexsubatendgroup  \glsxtrbookindexsubatendgroup{sub-labeldefinition} -

    -

    -


    \glsxtrbookindexatendgroup  \glsxtrbookindexatendgroup{ +
    Note that it doesn’t check if the command has already been defined. +

    As from version 1.25, the post-name hook also does +


    \glsextrapostnamehook{label} -

    -

    -where ⟨sub-sub-label⟩ is the label of the last level 2 entry, ⟨sub-label⟩ is the label of the -last level 1 entry and ⟨label⟩ is the label of the last level 0 entry. -

    For example, the resource option seealso=omit instructs bib2gls to omit the +class="cmtt-10">}


    +

    +(before \glsxtrpostnamecategory⟩) to allow for additional non-category related code. +This does nothing by default. +

    The post-description code used within the glossary is modified so that it also +does +


    \glsxtrpostdescription

    +

    +This occurs before the original \glspostdescription, so if the nopostdot=false +option is used, it will be inserted before the terminating full stop. +

    This new command will do \glsxtrpostdesccategory⟩ if it exists, where +⟨category⟩ is the category label associated with the current entry. For example seealso cross-reference from the location list. (The see cross-reference will still be -added unless you also have see=omit.) The seealso cross-reference can instead be -appended after the child entries using: +class="cmtt-10">\glsxtrpostdescgeneral for entries with the category set to general or +\glsxtrpostdescacronym for entries with the category set to acronym. For +convenience, as from v1.31, you can use +


    \glsdefpostdesc{category}{definition}

    +

    +This is simply a shortcut for:

    +
    +\csdef{glsxtrpostdesccategory}{definition} +
    +
    Note that it doesn’t check if the command has already been defined. +

    Since both \glossentry and \subglossentry set +


    \glscurrententrylabel

    + + + +

    +to the label for the current entry, you can use this within the definition of these +post-description hooks if you need to reference the label. +

    For example, suppose you want to insert the plural form in brackets after the +description in the glossary, but only for entries in the general category, then you could +do:

    -
    -\renewcommand{\glsxtrbookindexatendgroup}[1]{% - 
      \glsxtrifhasfield{seealso}{#1}{\glstreesubitem\glsxtruseseealso{#1}}{}% - 
    } - 
    \renewcommand{\glsxtrbookindexbetween}[2]{% - 
      \glsxtrbookindexatendgroup{#1}% - 
    }% - 
    \renewcommand{\glsxtrbookindexsubatendgroup}[1]{% - 
      \glsxtrifhasfield{seealso}{#1}{\glstreesubsubitem\glsxtruseseealso{#1}}{}% - 
    } - 
    \renewcommand{\glsxtrbookindexsubbetween}[2]{% - 
      \glsxtrbookindexsubatendgroup{#1}% - 
    } - 
    \renewcommand{\glsxtrbookindexsubsubatendgroup}[1]{% - 
      \glsxtrifhasfield{seealso}{#1}% - 
      {\glstreeitem\hspace*{40pt}\glsxtruseseealso{#1}}{}% - 
    } - 
    \renewcommand{\glsxtrbookindexsubsubbetween}[2]{% - 
      \glsxtrbookindexsubsubatendgroup{#1}% - 
    } +
    +\renewcommand{\glsxtrpostdescgeneral}{\space + 
     (plural: \glsentryplural{\glscurrententrylabel})}
    -

    This uses \glstreesubitem and \glstreesubsubitem to indent the cross-reference -according to the next level down, so the cross-reference for a top-level entry is aligned -with the sub-entries, and a level 1 entry has its cross-reference aligned with -sub-sub-entries. In the event that a level 2 entry has a cross-reference, this is -indented a bit further (but it won’t be aligned with any deeper level as the bookindex -style only supports a maximum of two sub-levels). -

    The bookindex style uses group headings. (If you use bib2gls remember to invoke -it with the --group or -g switch.) The heading will use -


    \glsxtrbookindexbookmark  \glsxtrbookindexbookmark{group title

    This means you don’t have to define a custom glossary style, which you may find +more complicated. (It also allows more flexibility if you decide to change the +underlying glossary style.) +

    This feature can’t be used for glossary styles that ignore \glspostdescription or if +you redefine \glspostdescription without including \glsxtrpostdescription. +(For example, if you redefine \glspostdescription to do nothing instead of using +the nopostdot option to suppress the terminating full stop.) See §2.10.1 The +glossaries-extra-stylemods Package to patch the predefined styles provided by glossaries +that are missing \glspostdescription.
    +

    +

    +

    +
    Number List
    +

    The number list is now placed inside the argument of +


    \GlsXtrFormatLocationList{number list}

    +

    +This is internally used by \glossaryentrynumbers. The nonumberlist option +redefines \glossaryentrynumbers so that it doesn’t display the number list, but it +still saves the number list in case it’s required. +

    If you want to suppress the number list always use the nonumberlist option +instead of redefining \glossaryentrynumbers to do nothing.
    +

    +

    For example, to change the font for the entire number list redefine +\GlsXtrFormatLocationList as appropriate. Don’t modify \glossaryentrynumbers. +

    Sometimes users like to insert “page” or “pages” in front of the number list. This +is quite fiddly to do with the base glossaries package, but glossaries-extra provides a +way of doing this. First you need to enable this option and specify the text to display +using: +


    \GlsXtrEnablePreLocationTag{page}{name} -

    -

    -If \pdfbookmark has been defined, this will use that command to bookmark the -group title. If section=chapter is set (default if chapters are defined) then this -uses level 1 otherwise it uses level 2. You can redefine this command if this -isn’t appropriate. If \pdfbookmark hasn’t been defined, this command does -nothin. -

    The group heading is formatted according to -


    \glsxtrbookindexformatheader  \glsxtrbookindexformatheader{group title} -

    - - - -

    -which is defined as +class="cmitt-10">pages⟩}


    +

    +where ⟨page⟩ is the text to display if the number list only contains a single location and +⟨pages⟩ is the text to display otherwise. For example:

    -
    -\newcommand*{\glsxtrbookindexformatheader}[1]{% - 
      \par{\centering\glstreegroupheaderfmt{#1}\par}% - 
    } +
    +\GlsXtrEnablePreLocationTag{Page: }{Pages: }
    -

    where \glstreegroupheaderfmt is provided by the glossary-tree package, which is -automatically loaded. Note that the entry names aren’t encapsulated with -\glstreenamefmt. -

    The glossary-bookindex package provides some supplementary commands that -aren’t used by default, but may be used when adjusting the style. These commands -should only be used within one of the \print…glossary commands. (That is, they -should only be used in glossary styles.) -


    \glsxtrbookindexmarkentry  \glsxtrbookindexmarkentry{label

    An extra run is required when using this command. +

    Use glsignore not @gobble as the format if you want to suppress the page +number (and only index the entry once).
    +

    +

    See the accompanying sample file sample-pages.tex. +

    Note that bib2gls can be instructed to insert a prefix at the start of non-empty +location lists, which can be used as an alternative to \GlsXtrEnablePreLocationTag. +

    Location lists displayed with \printnoidxglossary internally use +


    \glsnoidxdisplayloc{prefix}{counter}{format}{location}

    -

    -This writes information to the .aux file that can be read on the next run to obtain -the first and last entry on each page of the glossary. -

    You can display the first entry associated with the current page using: -


    \glsxtrbookindexfirstmark  \glsxtrbookindexfirstmark

    -and the last entry associated with the current page using: -


    \glsxtrbookindexlastmark  \glsxtrbookindexlastmark

    -

    -These do nothing if there are no entries marked on the current page (or if the -document build isn’t up to date). -

    The entry is formatted using: -


    \glsxtrbookindexfirstmarkfmt  \glsxtrbookindexfirstmarkfmt{labelglossaries, but is modified by glossaries-extra to check +for the start and end range formation identifiers ( and ) which are discarded to +obtain the actual control sequence name that forms the location formatting +command. +

    If the range identifiers aren’t present, this just uses +


    \glsxtrdisplaysingleloc{format}{location}

    +

    +otherwise it uses +


    \glsxtrdisplaystartloc{format}{location}

    +

    +for the start of a range (where the identifier has been stripped from ⟨format⟩) +or +


    \glsxtrdisplayendloc{format}{location}

    +

    +for the end of a range (where the identifier has been stripped from ⟨format⟩). +

    By default the start range command saves the format in +


    \glsxtrlocrangefmt

    +

    +and does +
    \glsxtrdisplaysingleloc{format}{location} -


    -

    -for the first instance and -


    \glsxtrbookindexlastmarkfmt  \glsxtrbookindexlastmarkfmt{label +(If the format is empty, it will be replaced with glsnumberformat.) +

    The end command checks that the format matches the start of the range, +does +


    \glsxtrdisplayendlochook{format}{location}

    +

    +(which does nothing by default), followed by +
    \glsxtrdisplaysingleloc{format}{location} -


    -

    -for the last. -

    These commands are designed for use in page headers or footers where the page -number is stable. For example, \glsxtrbookindexname can be redefined to mark the -current entry: -

    -
    -\renewcommand{\glsxtrbookindexname}[1]{% - 
      \glsxtrbookindexmarkentry{#1}% - 
      \glossentryname{#1}% - 
    } -
    -

    If you only want to mark the top-level entries, remember to redefine -\glsxtrbookindexsubname as it defaults to \glsxtrbookindexname: +
    +and then sets \glsxtrlocrangefmt to empty. +

    This means that the list

    -
    -\renewcommand{\glsxtrbookindexsubname}[1]{% - 
      \glossentryname{#1}% - 
    } +
    +\glsnoidxdisplayloc{}{page}{(textbf}{1}, + 
    \glsnoidxdisplayloc{}{page}{textbf}{1}, + 
    \glsnoidxdisplayloc{}{page}{)textbf}{1}.
    -

    -

    Then if you’re using fancyhdr you can set the page style to show the first and last -entry for the current page with: +

    doesn’t display any differently from

    -
    -  \pagestyle{fancy}% - 
      \lhead{\thepage}% - 
      \lfoot{\glsxtrbookindexfirstmark}% - 
      \cfoot{}% - 
      \rfoot{\glsxtrbookindexlastmark}% +
    +\glsnoidxdisplayloc{}{page}{textbf}{1}, + 
    \glsnoidxdisplayloc{}{page}{textbf}{1}, + 
    \glsnoidxdisplayloc{}{page}{textbf}{1}.
    -

    -

    +

    but it does make it easier to define your own custom list handler that can +accommodate the ranges. +

    -

    Top

    2.10 glossary-longextra package

    -

    As from version 1.37, the glossaries-extra package comes with the supplementary -package glossary-longextra that provides additional styles, listed below, that use the -longtable environment. If you know that your glossary won’t span more than a page -and you need to use it in a context that’s incompatible with longtable, you can -instead setup these styles to use tabular instead. In order to do this you must -use -


    \GlsLongExtraUseTabulartrue  \GlsLongExtraUseTabulartrue

    -

    -before the style is set. For example: +

    The glossaries-extra-stylemods Package
    +

    As from v1.02, glossaries-extra now includes the package glossaries-extra-stylemods that +will redefine the predefined styles to include the post-description hook (for those that +are missing it). You will need to make sure the styles have already been defined +before loading glossaries-extra. For example:

    -
    -\GlsLongExtraUseTabulartrue - 
    \setglossarystyle{long-name-desc} +
    +\usepackage{glossaries-extra} + 
    \usepackage{glossary-longragged} + 
    \usepackage{glossaries-extra-stylemods}
    -

    or +

    Alternatively you can load glossary-name.sty at the same time by passing ⟨name⟩ +as a package option to glossaries-extra-stylemods. For example:

    -
    -\GlsLongExtraUseTabulartrue - 
    \printunsrtglossary[style={long-name-desc}] +
    +\usepackage{glossaries-extra} + 
    \usepackage[longragged]{glossaries-extra-stylemods}
    -

    If you use this setting, you can change the default vertical alignment with: -


    \glslongextraTabularVAlign  \glslongextraTabularVAlign

    -

    -The default definition is c. -

    The column titles are formatted according to: -


    \glslongextraHeaderFmt  \glslongextraHeaderFmt{text}

    -

    -which simply does \textbf{text} by default. -

    The name column has the title given by \entryname and the column alignment is -given by: -


    \glslongextraNameAlign  \glslongextraNameAlign

    -

    -which expands to l (left) by default. -

    The symbol column (where applicable) has the title given by \symbolname and -the column alignment is given by: -


    \glslongextraSymbolAlign  \glslongextraSymbolAlign

    -

    -which expands to c (centred) by default. -

    The location list column (where applicable) has the title given by \pagelistname -and the column alignment is given by: -


    \glslongextraLocationAlign  \glslongextraLocationAlign

    -

    -which expands to +

    Another option is to use the stylemods key when you load glossaries-extra. You can +omit a value if you only want to use the predefined styles that are automatically +loaded by glossaries (for example, the long3col style):

    -
    ->{\raggedright}p{\glspagelistwidth} +
    +\usepackage[style=long3col,stylemods]{glossaries-extra}
    -

    by default. (Ragged-right paragraph, \glspagelistwidth is defined in glossary-long, -which is automatically loaded.) -

    The description column has the title given by \descriptionname and the column -alignment is given by: -


    \glslongextraDescAlign  \glslongextraDescAlign

    -

    -which expands to +

    Or the value of stylemods may be a comma-separated list of the style package +identifiers. For example:

    -
    ->{\raggedright}p{\glsdescwidth} +
    +\usepackage[style=mcoltree,stylemods=mcols]{glossaries-extra}
    -

    by default. (Ragged-right paragraph, \glsdescwidth is defined in glossary-long, -which is automatically loaded.) -

    Unlike the long styles provided by the base glossaries package, these new styles try -to determine the value of \glsdescwidth at the start of the glossary according to the -number of columns provided by the style. The calculations are performed by the -following commands: -


    \glslongextraSetDescWidth  \glslongextraSetDescWidth

    -

    -This is used by the styles that have a name and description column. The value of -\glsdescwidth is computed as: +

    Remember to group the value if it contains any commas: + + +

    -
    -\glsdescwidth = \linewidth- 4\tabcolsep- W
-
    -

    where W is a guess at the width of the name column. This is first set to the width of -the name column header:

    -
    -\settowidth{width}{\glslongextraHeaderFmt\entryname} +
    +\usepackage[stylemods={mcols,longbooktabs}]{glossaries-extra}
    -
    If any names in that column are larger than this, then you need to specify the widest -name using: -


    \glslongextraSetWidest  \glslongextraSetWidest{widest name}

    -

    -or -


    \glslongextraUpdateWidest  \glslongextraUpdateWidest{text}

    -

    -These work like the analogous commands \glssetwidest and \glsupdatewidest -provided with the alttree style, but in this case there’s no hierarchy. The default -widest name is obtained from the alttree top-level name if set, otherwise it’s empty, -so you can use bib2gls’s set-widest option. If you have the entry counter enabled, -you will need to include this with the name for the extra material to be taken into -account. -

    The name isn’t shown for child entries by default, but if you change this and you -want to use bib2gls’s set-widest option (for bib2gls v1.8+) then you need to -redefine: +

    +

    Note that the inline style is dealt with slightly differently. The original definition +provided by the glossary-inline package uses \glspostdescription at the end of the +glossary (not after each entry description) within the definition of \glspostinline. +The style modification changes this so that \glspostinline just does a full stop +followed by space factor adjustment, and the description \glsinlinedescformat and +sub-entry description formats \glsinlinesubdescformat are redefined to include +\glsxtrpostdescription (not \glspostdescription). This means that the +modified inline style isn’t affected by the nopostdot option, but the post-description +category hook can still be used. +

    The tabular-like styles, such as long are adjusted so that the \ifglsnogroupskip +conditional (set with nogroupskip) is moved outside of the definition of +\glsgroupskip to avoid problems that cause an “Incomplete \iftrue” error with +\printunsrtglossary and \printnoidxglossary. This means that if you want to +change this conditional using \setupglossaries or using the nogroupskip option in +\printglossary, \printnoidxglossary or \printunsrtglossary, you must also +reset the glossary style. +

    As from version 1.21, the hard-coded \space before the number list in many of +the predefined styles is replaced with +


    \glsxtrprelocation

    +

    +This just defaults to \space but may be redefined as required. For example: -


    \glslongextraUpdateWidestChild  \glslongextraUpdateWidestChild{level} +

    +
    +\renewcommand{\glsxtrprelocation}{\dotfill} +
    +

    +

    The list styles use +


    \glslistprelocation

    +

    +(which defaults to \glsxtrprelocation) for top-level items and +


    \glslistchildprelocation

    +

    +(which defaults to \glslistprelocation) for child items. +

    As from v1.31, the description (including the post-description hook) is governed +by: +


    \glslistdesc{label}

    +

    +for the list and altlist styles (but not the listdotted variations). +

    For just the list style and its letter group variations (not the altlist or listdotted +variations) the number list for child entries is followed by +


    \glslistchildpostlocation

    +

    +which defaults to a full stop. +

    The default value of \glslistdottedwidth is changed so that it’s set at the start +of the document (if it hasn’t been changed in the preamble). This should +take into account situations where \hsize isn’t set until the start of the +document. +

    The separator between groups (if not nogroupskip) is now given by: +


    \glslistgroupskip

    +

    +This defaults to \indexspace with penalties to deter page breaks. This command +isn’t used if nogroupskip is set. +

    The glossary-tree package introduced new commands in v4.22, \glstreegroupheaderfmt +and \glstreenavigationfmt, which are used to format the letter group +headings and the navigation elements for the appropriate styles. These two +new commands are defined in terms of \glstreenamefmt since that was +the command originally used for the group headings and navigation. This +now allows these different elements to be defined independently, but the +most common redefinition is for \glstreenamefmt to remove the bold in +the name. If the bold is still required for the group heading and navigation +elements, then both other commands also need redefining. To simplify matters, if {\glstreenamefmt has been defined, as from v1.31 glossaries-extra-stylemods +defines: +


    \glstreedefaultnamefmt{text}

    -

    -This does nothing by default, but if you are including the child names then you need -to redefine this command: -

    -
    -\renewcommand{\glslongextraUpdateWidestChild}[2]{% - 
     \glslongextraUpdateWidest{#2}% - 
    } -
    -

    -

    If you prefer to set an explicit width for the description column then you need to -redefine \glslongextraSetDescWidth. For example: +

    +which simply does \textbf{text} and redefines \glstreenamefmt, +\glstreegroupheaderfmt and \glstreenavigationfmt all in terms of +\glstreedefaultnamefmt. +

    This means that if you want to change all three to use a particular style you only +need to redefine \glstreedefaultnamefmt, but if you only want to redefine +\glstreenamefmt without affecting the other two commands, then you now +can. +

    The separator between groups without headers is given by: +


    \glstreegroupskip

    +

    +This defaults to just \indexspace without penalties. This command isn’t +used if nogroupskip is set. (The penalties introduced in v1.41 were moved to +\glstreeheadergroupskip in v1.42 as they are inappropriate when there’s no +header.) +

    The separator between groups with headers is now given by (as from +v1.42): +


    \glstreegroupheaderskip

    +

    +This defaults to \glstreegroupskip with penalties to deter page breaks after the +group heading. +

    The styles that display the group titles now use: +


    \glstreePreHeader{label}{title}

    +

    +where ⟨label⟩ is the group label and ⟨title⟩ is the group title. This does nothing by +default and is inserted before the group title. You can redefine it to add the group +title to the PDF bookmarks. For example, if the glossary title uses \chapter +then:

    -
    -\renewcommand{\glslongextraSetDescWidth}{% - 
      \setlength{\glsdescwidth}{0.6\linewidth}% +
    +\renewcommand{\glstreePreHeader}[2]{% + 
     \pdfbookmark[1]{#2}{\currentglossary.#1}%  
    }
    -

    -

    The styles that have a name, symbol and description, \glsdescwidth is set -with: -


    \glslongextraSymSetDescWidth  \glslongextraSymSetDescWidth

    -

    -This first uses \glslongextraSetDescWidth and then subtracts 2\tabcolsep and -the width of the symbol column header from \glsdescwidth. This assumes that the -symbol column header is larger than any of the symbols. If this isn’t appropriate then -you can redefine this command. For example: - - - -

    -
    -\renewcommand{\glslongextraSymSetDescWidth}{% - 
      \glslongextraSetDescWidth - 
      \addtolength{\glsdescwidth}{-3cm}% - 
    } -
    -

    or - - - -

    -
    -\renewcommand{\glslongextraSymSetDescWidth}{% - 
      \setlength{\glsdescwidth}{.5\linewidth}% - 
    } -
    -

    -

    For the styles that have a name, description and location column, \glsdescwidth -is set using: -


    \glslongextraLocSetDescWidth  \glslongextraLocSetDescWidth

    -

    -This uses \glslongextraSetDescWidth and then subtracts 2\tabcolsep and -\glspagelistwidth from \glsdescwidth. You can redefine this command to set -both \glsdescwidth and \glspagelistwidth if appropriate. -

    For the styles that have a name, description, symbol and location column, -\glsdescwidth is set using: -


    \glslongextraSymLocSetDescWidth  \glslongextraSymLocSetDescWidth -

    -

    -This uses \glslongextraSymSetDescWidth and then subtracts 2\tabcolsep and -\glspagelistwidth from \glsdescwidth. Again, you can redefine this command to -explicitly set both lengths. -

    In all cases, the top-level name is formatted according to: -


    \glslongextraNameFmt  \glslongextraNameFmt{

    will insert section-level bookmarks. The use of \currentglossary helps to provide +unique bookmark labels in the event of multiple glossaries. +

    The index-like and tree-like styles insert the pre-number list space with +


    \glstreeprelocation

    +

    +(which defaults to \glsxtrprelocation) for top-level items and +


    \glstreechildprelocation

    +

    +(which defaults to \glstreeprelocation) for child items. +

    As from version 1.31, the glossaries-extra-stylemods package also provides: +


    \glstreenonamedesc{label}

    -

    -This does

    -
    -\glsentryitem{

    +which is used by the treenoname styles to display the pre-description separator, the +description and the post-description hook. Similarly for the symbol: +


    \glstreenonamesymbol{label}\glstarget{}

    +

    +The above are just used for top-level entries. Child entries don’t have the name or +symbol displayed for the treenoname styles, so there’s only a command for the child +description: +


    \glstreenonamechilddesc{label}{\glossentryname{}

    +

    +

    For the tree styles (but not the treenoname or alttree styles), the description is +displayed using: +


    \glstreedesc{label}} -
    -
    which includes the entry counter (if enabled), the target and the post-name -link. -

    The top-level description is formatted according to: -


    \glslongextraDescFmt  \glslongextraDescFmt{}

    +

    +and the symbol with: +


    \glstreesymbol{label}

    -

    -This does \glossentrydesc{label} followed by the post-description hook. -

    The styles that have a symbol column format the symbol using: -


    \glslongextraSymbolFmt  \glslongextraSymbolFmt{

    +Again the above two commands are just for top-level entries. The child entries +use: +


    \glstreechilddesc{label}

    -

    -This just does \glossentrysymbol{label}. -

    The styles that have a location list column format the list using: -


    \glslongextraLocationFmt  \glslongextraLocationFmt{

    +for the description and +


    \glstreechildsymbol{label}{locations} -

    +class="cmtt-10">}

    +

    +for the symbol. As from version 1.41, there are now wrapper commands +for \glstreedesc and \glstreechilddesc that check for the description -

    -This just does ⟨locations⟩ and ignores the label. -

    The child entries have their name formatted according to: -


    \glslongextraSubNameFmt  \glslongextraSubNameFmt{level


    \glstreeDescLoc{label}{location}

    +

    +for top-level entries and +


    \glstreeChildDescLoc{label} -

    -

    -where ⟨level⟩ is the hierarchical level. This defaults to:

    -
    +class="cmtt-10">}{⟨location}

    +

    +for sub-entries. +

    If either the symbol or description is present these will use \glstreeprelocation +or \glstreechildprelocation, respectively. Otherwise, both will use (from +v1.42): +


    \glstreeNoDescSymbolPreLocation

    +

    +The default is a space. This means that you could have, say, a comma followed by a +space for terms that are simply an alias, but just have a space for terms that have a +description that ends with a full stop (or that just have a symbol without a +description) where the comma would be inappropriate. +

    Note that version 1.42 has corrected an error that was introduced to v1.41 that +caused the name to run into the location list if there was no symbol and no +description. +

    As from version 1.05, the glossaries-extra-stylemods package provides some +additional commands for use with the alttree style to make it easier to modify. These +commands are only defined if the glossary-tree package has already been loaded, +which is typically the case unless the notree option has been used when loading \glssubentryitem{label}\glstarget{label}{\strut} -

    -
    This includes the sub-entry counter (if enabled) and the target but doesn’t show the -name. The child description is formatted according to: -


    \glslongextraSubDescFmt  \glslongextraSubDescFmt{glossaries. +


    \gglssetwidest[level}{label} -

    -

    -which defaults to just \glslongextraDescFmt{label} -

    The child symbol is formatted (where appropriate) according to: -


    \glslongextraSubSymbolFmt  \glslongextraSubSymbolFmt{]{name}

    +

    +(New to version 1.21.) This is like \glssetwidest (provided by glossary-tree) but +performs a global assignment. +


    \eglssetwidest[level}{label} -

    -

    -This just does \glslongextraSymbolFmt{label} by default. -

    The styles that have a location list column format the list for child entries -using: -


    \glslongextraLocationFmt  \glslongextraSubLocationFmt]{name}

    +

    +This is like \glssetwidest but performs a protected expansion on ⟨name⟩. This has a +localised effect. For a global setting, use +


    \xglssetwidest[level{label} -{locations]{name}

    -

    -This just does ⟨locations⟩ and ignores the level and label. -

    The letter group headings are formatted according to: -


    \glslongextraGroupHeading  \glslongextraGroupHeading{n}{label} -

    -

    -which does nothing by default. The first argument ⟨n⟩ is the number of columns in the -table. The second argument ⟨label⟩ is the group label (not the title, although they may -happen to be the same). -

    This can be redefined to show the group heading. For example: +

    +The following only set the value if ⟨name⟩ is wider than the current value (new to +version 1.23). Local update: +


    \glsupdatewidest[level]{name}

    +

    +Global update: +


    \gglsupdatewidest[level]{name}

    +

    +Locale update (expands ⟨name⟩): +


    \eglsupdatewidest[level]{name}

    +

    +Global update (expands ⟨name⟩): -

    -
    -\renewcommand*{\glslongextraGroupHeading}[2]{% - 
      \glsxtrgetgrouptitle{#2}{\thisgrptitle}% - 
      \glslongextraHeaderFmt{\thisgrptitle}% - 
      \tabularnewline - 
      \noalign{\vskip\normalbaselineskip}% - 
    } -
    -

    This ignores the first argument and just puts the group title in the first column -formatted according to \glslongextraHeaderFmt (to match the column -header). -

    Remember that you can also adjust the styles through category attributes. The -name column’s title is given by \entryname, the description column’s title is given by +


    \xglsupdatewidest[level]{name}

    +

    +

    The widest entry value can later be retrieved using +


    \glsgetwidestname

    +

    +for the top-level entries and +


    \glsgetwidestsubname{level}

    +

    +for sub-entries, where ⟨level⟩ is the level number. +

    Note that if you are using bib2gls, you can use the resource option set-widest +which will try to determine the widest name of all the selected entries. This isn’t +guaranteed to work as it may depend on fonts or commands that bib2gls +can’t replicate, but it should be suitable for names that just consist of text, +and can be more efficient than iterating over all the defined entries using +TEX. +

    The command \glsfindwidesttoplevelname provided by glossary-tree has a +CamelCase synonym: +


    \glsFindWidestTopLevelName[glossary list]

    +

    +Similar commands are also provided: +


    \glsFindWidestUsedTopLevelName[glossary list]

    +

    +This has an additional check that the entry has been used. Naturally this is only +useful if the glossaries that use the alttree style occur at the end of the document. +This command should be placed just before the start of the glossary. (Alternatively, +place it at the end of the document and save the value in the auxiliary file for the +next run.) +


    \glsFindWidestUsedAnyName[glossary list]

    +

    +This is like the previous command but if doesn’t check the parent key. This is useful if +all levels should have the same width for the name. +


    \glsFindWidestAnyName[glossary list]

    +

    +This is like the previous command but doesn’t check if the entry has been +used. +


    \glsFindWidestUsedLevelTwo[glossary list]

    +

    +This is like \glsFindWidestUsedTopLevelName but also sets the first two sub-levels +as well. Any entry that has a great-grandparent is ignored. +


    \glsFindWidestLevelTwo[glossary list]

    +

    +This is like the previous command but doesn’t check if the entry has been +used. +


    \glsFindWidestUsedAnyNameSymbol[glossary list]{register} +

    + + + +

    +This is like \glsFindWidestUsedAnyName but also measures the symbol. The length +of the widest symbol is stored in ⟨register⟩. +


    \glsFindWidestAnyNameSymbol[glossary list]{register}

    +

    +This is like the previous command but it doesn’t check if the entry has been +used. +


    \glsFindWidestUsedAnyNameSymbolLocation[glossary list]{symbol \descriptionname and (where present) the symbol column’s title is given by +class="cmitt-10">register⟩}{location register}

    +

    +This is like \glsFindWidestUsedAnyNameSymbol but also measures the number list. +This requires \glsentrynumberlist (see the glossaries user manual). The length of +the widest symbol is stored in ⟨symbol register⟩ and the length of the widest number +list is stored in ⟨location register⟩. +


    \glsFindWidestAnyNameSymbolLocation[glossary list]{symbol \symbolname, as for the other long styles that have headers. -

    -
    long-name-desc This is like the longragged-booktabs style but doesn’t show the - location list (regardless of the nonumberlist option). The name is shown in - the first column and the description in the second. -

    The symbol is not displayed. The header row is produced with: -


    \glslongextraNameDescHeader  \glslongextraNameDescHeader

    -

    - This essentially uses the same code as for longragged-booktabs but makes it - easier to adjust the header without having to define a new style. This is defined - as: +class="cmitt-10">register⟩}{location register}


    +

    +This is like the previous command but it doesn’t check if the entry has been +used. +


    \glsFindWidestUsedAnyNameLocation[glossary list]{register} +

    +

    +This is like \glsFindWidestUsedAnyNameSymbolLocation but doesn’t measure the +symbol. The length of the widest number list is stored in ⟨register⟩. +


    \glsFindWidestAnyNameLocation[glossary list]{register}

    +

    +This is like the previous command but doesn’t check if the entry has been +used. +

    The layout of the symbol, description and number list is governed by +


    \glsxtralttreeSymbolDescLocation{label}{number list}

    +

    +for top-level entries and +


    \glsxtralttreeSubSymbolDescLocation{label}{number list}

    +

    +for sub-entries. +

    There is now a user level command that performs the initialisation for the alttree +style: +


    \glsxtralttreeInit

    +

    +

    The paragraph indent for subsequent paragraphs in multi-paragraph descriptions +is provided by the length +


    \glsxtrAltTreeIndent

    +

    + + + +

    For additional commands that are available with the alttree style, +see the documented code (glossaries-extra-code.pdf). See also the +accompanying sample files sample-alttree.tex, sample-alttree-sym.tex and +sample-alttree-marginpar.tex.

    -
    - \glslongextraNameDescTabularHeader\endhead -  
    \glslongextraNameDescTabularFooter\endfoot -
    -

    where: -


    \glslongextraNameDescTabularHeader  \glslongextraNameDescTabularHeader -

    -

    - sets up the header and -


    \glslongextraNameDescTabularFooter  \glslongextraNameDescTabularFooter -

    -

    - sets up the footer. If you have setup the tabular version of this style then the - above two commands are used at the start and end of the tabular environment - (and \glslongextraNameDescHeader isn’t used). -

    For example, to simply remove the header and footer (for the default longtable - version of the style): +

    +

    Top

    3. New Glossary Styles

    +

    The glossaries-extra package comes with some new styles. The associated style +package needs to be loaded. This can be done with \usepackage but it’s simpler to +use the stylemods option. +

    +

    Top

    3.1 glossary-bookindex package

    +

    As from v1.21, glossaries-extra has a new supplementary package glossary-bookindex +which provides the glossary style bookindex. This is very similar to the mcolindexgroup +style but is designed for indexes, so by default only the name and location list +are displayed. You can either load this package explicitly and then set the +style:

    -
    - \renewcommand{\glslongextraNameDescHeader}{} +
    +\usepackage{glossaries-extra} + 
    \usepackage{glossary-bookindex} + 
    \setglossarystyle{bookindex}
    -

    Or to change the name alignment to centred: +

    or use both the stylemods and style options:

    -
    - \renewcommand{\glslongextraNameAlign}{c} +
    +\usepackage[stylemods=bookindex,style=bookindex]{glossaries-extra}
    -

    -

    -
    long-name-desc-loc This is like the long-name-desc style but has a third column for - the location list. The longtable header is given by: -


    \glslongextraNameDescLocationHeader  \glslongextraNameDescLocationHeader -

    -

    - which similarly defined in terms of the commands used for the tabular - version: -


    \glslongextraNameDescLocationTabularHeader  \glslongextraNameDescLocationTabularHeader -

    -

    - and -


    \glslongextraNameDescLocationTabularFooter  \glslongextraNameDescLocationTabularFooter -

    -

    -

    -
    long-desc-name This is like the long-name-desc style but swaps the columns. Note - that if the entry counter is displayed it will appear at the start of the - second column by default. The longtable header is formatted according - to: -


    \glslongextraDescNameHeader  \glslongextraDescNameHeader

    -

    - which similarly defined in terms of the commands used for the tabular - version: -


    \glslongextraDescNameTabularHeader  \glslongextraDescNameTabularHeader -

    -

    - and -


    \glslongextraDescNameTabularFooter  \glslongextraDescNameTabularFooter -

    -

    +

    The bookindex style only supports a maximum hierarchical level of 2 (top-level, +level 1 and level 2). It’s primarily designed for use with bib2gls. It may be used +with other indexing options, but some features may not be present and UTF-8 +characters may cause a problem with non-Unicode engines in letter group +headings or PDF bookmarks. (bib2gls uses numeric identifies by default to +avoid these problems. If numbers show up in the group headings instead of +the appropriate characters, check that you have used the record package +option.) +

    The number of columns is given by +


    \glsxtrbookindexcols

    +

    +which defaults to 2. +

    This style uses the multicols environment. If the command +


    \glsxtrbookindexcolspread

    +

    +isn’t empty then it’s supplied as the optional argument following \begin{multicols} +{n}. You can switch from multicols to multicols* by redefining +


    \glsxtrbookindexmulticolsenv

    +

    +For example -

    -
    long-loc-desc-name This has three columns containing the location list, - description and name. The longtable header is formatted according - to: -


    \glslongextraLocationDescNameHeader  \glslongextraLocationDescNameHeader -

    -

    - which similarly defined in terms of the commands used for the tabular - version: -


    \glslongextraLocationDescNameTabularHeader  \glslongextraLocationDescNameTabularHeader -

    -

    - and -


    \glslongextraLocationDescNameTabularFooter  \glslongextraLocationDescNameTabularFooter -

    -

    -

    -
    long-name-desc-sym This is has three columns, with the name in the first, the - description in the second and the symbol in the third. -

    The longtable header row is produced with: -


    \glslongextraNameDescSymHeader  \glslongextraNameDescSymHeader -

    -

    - which similarly defined in terms of the commands used for the tabular - version: -


    \glslongextraNameDescSymTabularHeader  \glslongextraNameDescSymTabularHeader -

    -

    - and -


    \glslongextraNameDescSymTabularFooter  \glslongextraNameDescSymTabularFooter -

    -

    -

    -
    long-name-desc-sym-loc This is has four columns, with the name in the first, the - description in the second, the symbol in the third and the location list in the - fourth. -

    The longtable header row is produced with: - - - -


    \glslongextraNameDescSymLocationHeader  \glslongextraNameDescSymLocationHeader -

    -

    - which similarly defined in terms of the commands used for the tabular - version: -


    \glslongextraNameDescSymLocationTabularHeader  - \glslongextraNameDescSymLocationTabularHeader

    -

    - and -


    \glslongextraNameDescSymLocationTabularFooter  - \glslongextraNameDescSymLocationTabularFooter

    -

    -

    -
    long-name-sym-desc This is like the long-name-desc-sym but the second and third - column are swapped. The longtable header row is given by: -


    \glslongextraNameSymDescHeader  \glslongextraNameSymDescHeader -

    -

    - which similarly defined in terms of the commands used for the tabular - version: -


    \glslongextraNameSymDescTabularHeader  \glslongextraNameSymDescTabularHeader -

    -

    - and -


    \glslongextraNameSymDescTabularFooter  \glslongextraNameSymDescTabularFooter -

    -

    -

    -
    long-name-sym-desc-loc This is like the long-name-desc-sym-loc but the second and - third column are swapped. The longtable header row is given by: -


    \glslongextraNameSymDescLocationHeader  \glslongextraNameSymDescLocationHeader -

    -

    - which similarly defined in terms of the commands used for the tabular - version: -


    \glslongextraNameSymDescLocationTabularHeader  - \glslongextraNameSymDescLocationTabularHeader

    - - - -

    - and -


    \glslongextraNameSymDescLocationTabularFooter  - \glslongextraNameSymDescLocationTabularFooter

    -

    -

    -
    long-sym-desc-name This has the symbol in the first column, the description in the - second and the name in the third. The longtable header row is given - by: -


    \glslongextraSymDescNameHeader  \glslongextraSymDescNameHeader -

    -

    - which similarly defined in terms of the commands used for the tabular - version: -


    \glslongextraSymDescNameTabularHeader  \glslongextraSymDescNameTabularHeader -

    -

    - and -


    \glslongextraSymDescNameTabularFooter  \glslongextraSymDescNameTabularFooter -

    -

    -

    -
    long-loc-sym-desc-name This has the location list in the first column, symbol in the - second column, the description in the third and the name in the fourth. The - longtable header row is given by: -


    \glslongextraLocationSymDescNameHeader  \glslongextraLocationSymDescNameHeader -

    -

    - which similarly defined in terms of the commands used for the tabular - version: -


    \glslongextraLocationSymDescNameTabularHeader  - \glslongextraLocationSymDescNameTabularHeader

    -

    - and -


    \glslongextraLocationSymDescNameTabularFooter  - \glslongextraLocationSymDescNameTabularFooter

    -

    - - - -

    -
    long-desc-sym-name This has the description in the first column, the symbol in the - second and the name in the third. The longtable header row is given - by: -


    \glslongextraDescSymNameHeader  \glslongextraDescSymNameHeader -

    -

    - which similarly defined in terms of the commands used for the tabular - version: -


    \glslongextraDescSymNameTabularHeader  \glslongextraDescSymNameTabularHeader -

    -

    - and -


    \glslongextraDescSymNameTabularFooter  \glslongextraDescSymNameTabularFooter -

    -

    -

    -
    long-loc-desc-sym-name This has the location list in the first column, the description - in the second column, the symbol in the third and the name in the fourth. The - longtable header row is given by: -


    \glslongextraLocationDescSymNameHeader  \glslongextraLocationDescSymNameHeader -

    -

    - which similarly defined in terms of the commands used for the tabular - version: -


    \glslongextraLocationDescSymNameTabularHeader  - \glslongextraLocationDescSymNameTabularHeader

    -

    - and -


    \glslongextraLocationDescSymNameTabularFooter  - \glslongextraLocationDescSymNameTabularFooter

    -

    -
    +
    +\renewcommand{\glsxtrbookindexmulticolsenv}{multicols*} +
    +

    +

    Each top-level entry is displayed using +


    \glsxtrbookindexname{label}

    +

    +where the entry is identified by ⟨label⟩. This just does \glossentryname{label} by +default. For example, if you want the symbol to be included: -

    -

    Top

    2.11 glossary-topic package

    -

    As from version 1.40, the glossaries-extra package comes with the supplementary -package glossary-topic that provides glossary styles designed for hierarchical glossaries -where the top-level entries are topic titles. This package automatically loads the -multicols package. If the glossary-tree package is also loaded then commands like -\glssetwidest can be used on these styles in much the same way as for the alttree -style. If a widest value isn’t set then these styles behave more like the tree -style. -

    -topic
    This style is similar to the tree style but the indentation doesn’t start until - the second sub-item level. The top-level entries have the name displayed - in a larger font with the description following in a new paragraph. This - style doesn’t support the nogroupskip setting. -
    -topicmcols
    This style is like the topic style but the sub-entries are placed inside a - multicols environment. The environment name is supplied in the value of the - command: -


    \glstopicColsEnv  \glstopicColsEnv

    -

    - You can change this to the starred form. For example: +

    +\renewcommand*{\glsxtrbookindexname}[1]{% + 
     \glossentryname{#1}% + 
     \ifglshassymbol{#1}{\space (\glossentrysymbol{#1})}{}% + 
    } +
    +

    or if you want the description (if set):

    -
    - \renewcommand{\glstopicColsEnv}{multicols*} +
    +\renewcommand*{\glsxtrbookindexname}[1]{% + 
     \glossentryname{#1}% + 
     \ifglshasdesc{#1}{\space \glossentrydesc{#1}\glspostdescription}{}% + 
    }
    -

    The number of columns is given by the command: -


    \glstopicCols  \glstopicCols

    -

    - The default value is 2.

    -

    Both styles use the following commands. -


    \glstopicParIndent  \glstopicParIndent

    -

    -This command is a length that’s used for the paragraph indentation in any -multi-paragraph description for top-level entries, but not for the first paragraph (at -the start of the description) which isn’t indented. -


    \glstopicSubIndent  \glstopicSubIndent

    -

    -This command is a length that’s used to calculate the hanging indentation for -sub-entries. The level 1 sub-entries don’t indent the name. Level n sub-entries have -the name indented by (n- 1)×\glstopicSubIndent. The hanging indent depends on -whether or not a widest name has been set for the level. -


    \glstopicInit  \glstopicInit

    -

    -Hook used at the start of the glossary. Does nothing by default. -

    Although the styles don’t support letter groups by default, if you have many -topics (top-level entries) and you feel that it would help the reader to divide them up -into headed letter groups, you can redefine: -


    \glstopicGroupHeading  \glstopicGroupHeading{group label

    (which picks up the post-description hook). +

    Alternatively you can use the \glsxtrpostnamecategory⟩ hook to append +information after the name according to the entry’s category. +

    Sub-entries are displayed using +


    \glsxtrbookindexsubname{label}

    -

    -This does nothing by default. If you want to redefine it, you can fetch the -title corresponding to the group label with \glsxtrgetgrouptitle. For -example: +

    +which just defaults to \glsxtrbookindexname{label}. +

    The separator used before the location list for top-level entries is given +by +


    \glsxtrbookindexprelocation{label}

    +

    +where ⟨label⟩ is the entry’s label. This checks if the location field has been set. If it +has, it does

    -
    -\renewcommand*{\glstopicGroupHeading}[1]{% - 
      \glsxtrgetgrouptitle{#1}{\thisgrptitle}% - 
      \section*{\thisgrptitle}% - 
    } +
    +,\glsxtrprelocation
    -

    Remember that if you use

    otherwise it just does \glsxtrprelocation (which defaults to \space). If you’re not +using bib2gls, you will need the --group (or -g) switch to -support this. -


    \glstopicItem  \glstopicItem{bib2gls, the location field won’t be set. +

    The separator used before the location list for sub-entries is given by +


    \glsxtrbookindexsubprelocation{label}

    +

    +which defaults to \glsxtrbookindexprelocation{label}. +

    The actual location list is encapsulated with: +


    \glsxtrbookindexlocation{label}{location list}

    -

    -Used to format the name, symbol, description and location list for the top-level -entries. This starts with a paragraph break followed by: -


    \glstopicPreSkip  \glstopicPreSkip

    -

    -which defaults to \medskip. There is then a hook: -


    \glstopicMarker  \glstopicMarker{

    +for top-level entries and +


    \glsxtrbookindexsublocation{label}{location list}

    -

    -which does nothing by default, but may be redefined. For example, to add a line to -the table of contents. The name and symbol are set in the form of a title -using: -


    \glstopicTitle  \glstopicTitle{label

    +for sub-entries. These both just do ⟨location list⟩ by default. +

    The separator used between a top-level parent and child entry is given +by +


    \glsxtrbookindexparentchildsep

    +

    +This defaults to \nopagebreak. +

    The separator used between a sub-level parent and child entry is given +by +


    \glsxtrbookindexparentsubchildsep

    +

    +This defaults to \glsxtrbookindexparentchildsep. +

    The separator between top-level entries is given by +


    \glsxtrbookindexbetween{label1}{label2}

    -

    -This uses \Glossentryname which converts the first letter to upper case. If there’s a -symbol, this is added in parentheses. Both name and symbol (if present) are -encapsulated by -


    \glstopicTitleFont  \glstopicTitleFont{text

    +This comes after the entry given by ⟨label1⟩, if the entry has no children, or after the +last descendent otherwise, so it always comes immediately before the entry given by +⟨label2⟩ unless the entry occurs at the start of a group. This does nothing by +default. +

    The separator between two level 1 entries is given by +


    \glsxtrbookindexsubbetween{label1}{label2}

    -This uses a bold, large font by default. -

    If the entry has the description key set (tested with \ifglshasdesc) then a -paragraph break is inserted followed by: -


    \glstopicMidSkip  \glstopicMidSkip

    -

    -which defaults to \smallskip. This is followed by the description which is formatted -according to: -


    \glstopicDesc  \glstopicDesc{label

    The separator between two level 2 entries is given by +


    \glsxtrbookindexsubsubbetween{label1}{label2}

    +

    +At the end of each letter group, the following hooks are done in order: +


    \glsxtrbookindexsubsubatendgroup{sub-sub-label}

    -

    -This just does \Glossentrydesc{label} followed by the post-description -hook. -

    A paragraph break followed by: -


    \glstopicPostSkip  \glstopicPostSkip

    -

    -comes next regardless of whether or not the description was displayed. This defaults -to \smallskip. This is then followed by: -


    \glstopicLoc  \glstopicLoc{label}{location list}

    -

    -which may be used to display the location list, but does nothing by default. -

    The sub-entries first set up the paragraph and hanging indentations using: -


    \glstopicAssignSubIndent  \glstopicAssignSubIndent{level}

    -

    -This uses: -


    \glstopicAssignWidest  \glstopicAssignWidest{level}

    -

    -to determine if a widest name has been set for the given level. -

    The sub-entry has its information displayed using: -


    \glstopicSubItem  \glstopicSubItem{level}{label}{location} -

    -

    -This encapsulates the name with: -


    \glstopicSubNameFont  \glstopicSubNameFont{text}

    -

    -By default this just uses \textbf. This is followed by: -


    \glstopicSubItemSep  \glstopicSubItemSep

    -

    -which defaults to \quad. The name and separator are passed in the ⟨text⟩ argument -of: -


    \glstopicSubItemBox  \glstopicSubItemBox{level}{text

    +


    \glsxtrbookindexsubatendgroup{sub-label}

    -

    -If a widest name was set for the given level, this will put ⟨text⟩ inside a box of that -width otherwise it just does ⟨text⟩. -

    This is followed by the symbol in parentheses if set. Then, if the description is set, -the description and post-description hook are displayed followed by: -


    \glstopicSubPreLocSep  \glstopicSubPreLocSep

    -

    -(This command isn’t used if the description isn’t set.) -

    Finally the location list is displayed using: -


    \glstopicSubLoc  \glstopicSubLoc{

    +


    \glsxtrbookindexatendgroup{label}{location}

    -

    -which just does ⟨location⟩ by default. -

    -

    -

    Top

    2.12 Glossary Style Modifications

    -

    The glossaries-extra-stylemods package (more conveniently loaded through the +

    +where ⟨sub-sub-label⟩ is the label of the last level 2 entry, ⟨sub-label⟩ is the label of the +last level 1 entry and ⟨label⟩ is the label of the last level 0 entry. +

    For example, the resource option seealso=omit instructs bib2gls to omit the glossaries-extra stylemods option) modifies some of the predefined styles that are -provided with the glossaries package. These modifications are described in more detail -in §2.12.3 The glossaries-extra-stylemods Package. +class="cmtt-10">seealso cross-reference from the location list. (The see cross-reference will still be +added unless you also have see=omit.) The seealso cross-reference can instead be +appended after the child entries using: -

    The glossaries package tries to determine the group title from its label by first -checking if \labelgroupname exists. If it doesn’t exist, then the title is assumed to be -the same as the label. For example, when typesetting the “A” letter group, glossaries -first checks if \Agroupname exists. This could potentially cause conflict with another -package that may have some other meaning for \Agroupname, so glossaries-extra first -checks for the existence of the internal command \glsxtr@grouptitle@label⟩ -which shouldn’t clash with another package. You can set the group title -using -


    \glsxtrsetgrouptitle  \glsxtrsetgrouptitle{label +
    +\renewcommand{\glsxtrbookindexatendgroup}[1]{% + 
      \glsxtrifhasfield{seealso}{#1}{\glstreesubitem\glsxtruseseealso{#1}}{}% + 
    } + 
    \renewcommand{\glsxtrbookindexbetween}[2]{% + 
      \glsxtrbookindexatendgroup{#1}% + 
    }% + 
    \renewcommand{\glsxtrbookindexsubatendgroup}[1]{% + 
      \glsxtrifhasfield{seealso}{#1}{\glstreesubsubitem\glsxtruseseealso{#1}}{}% + 
    } + 
    \renewcommand{\glsxtrbookindexsubbetween}[2]{% + 
      \glsxtrbookindexsubatendgroup{#1}% + 
    } + 
    \renewcommand{\glsxtrbookindexsubsubatendgroup}[1]{% + 
      \glsxtrifhasfield{seealso}{#1}% + 
      {\glstreeitem\hspace*{40pt}\glsxtruseseealso{#1}}{}% + 
    } + 
    \renewcommand{\glsxtrbookindexsubsubbetween}[2]{% + 
      \glsxtrbookindexsubsubatendgroup{#1}% + 
    } +
    +

    This uses \glstreesubitem and \glstreesubsubitem to indent the cross-reference +according to the next level down, so the cross-reference for a top-level entry is aligned +with the sub-entries, and a level 1 entry has its cross-reference aligned with +sub-sub-entries. In the event that a level 2 entry has a cross-reference, this is +indented a bit further (but it won’t be aligned with any deeper level as the bookindex +style only supports a maximum of two sub-levels). +

    The bookindex style uses group headings. (If you use bib2gls remember to invoke +it with the --group or -g switch.) The heading will use +


    \glsxtrbookindexbookmark{group title}{titlename}

    -

    -For example: +

    +If \pdfbookmark has been defined, this will use that command to bookmark the +group title. If section=chapter is set (default if chapters are defined) then this +uses level 1 otherwise it uses level 2. You can redefine this command if this +isn’t appropriate. If \pdfbookmark hasn’t been defined, this command does +nothin. +

    The group heading is formatted according to +


    \glsxtrbookindexformatheader{group title}

    +

    +which is defined as

    -
    -\glsxtrsetgrouptitle{A}{A (a)} +
    +\newcommand*{\glsxtrbookindexformatheader}[1]{% + 
      \par{\centering\glstreegroupheaderfmt{#1}\par}% + 
    }
    -

    This uses a global assignment. If you need to scope the change you can -use -


    \glsxtrlocalsetgrouptitle  \glsxtrlocalsetgrouptitle{label}{title} -

    -

    -

    -

    -

    Top

    2.12.1 Style Hooks

    -

    The commands \glossentryname and \glossentrydesc are modified to take into -account the glossname, glossdesc and glossdescfont attributes (see §5 Categories). This -means you can make simple case-changing modifications to the name and description -without defining a new glossary style. -

    If you want to adapt a style to use another field instead of name, you can -use -


    \glossentrynameother  \glossentrynameother{

    where \glstreegroupheaderfmt is provided by the glossary-tree package, which is +automatically loaded. Note that the entry names aren’t encapsulated with +\glstreenamefmt. +

    The glossary-bookindex package provides some supplementary commands that +aren’t used by default, but may be used when adjusting the style. These commands +should only be used within one of the \print…glossary commands. (That is, they +should only be used in glossary styles.) +


    \glsxtrbookindexmarkentry{label}{field}

    -

    -This behaves just like \glossentryname (that is, it obeys glossname, glossnamefont or -\glsnamefont and uses the post-name hook) but it uses the given ⟨field⟩ instead of -name. The ⟨field⟩ argument must be the internal field name (for example desc rather -than description). See the key to field mappings table in the glossaries user -manual. -

    There is a hook after \glossentryname and \Glossentryname: -


    \glsxtrpostnamehook  \glsxtrpostnamehook{

    +This writes information to the .aux file that can be read on the next run to obtain +the first and last entry on each page of the glossary. +

    You can display the first entry associated with the current page using: +


    \glsxtrbookindexfirstmark

    +

    +and the last entry associated with the current page using: +


    \glsxtrbookindexlastmark

    +

    +These do nothing if there are no entries marked on the current page (or if the +document build isn’t up to date). +

    The entry is formatted using: +


    \glsxtrbookindexfirstmarkfmt{label}

    -

    -By default this checks the indexname attribute. If the attribute exists for the -category to which the label belongs, then the name is automatically indexed -using -


    \glsxtrdoautoindexname{

    +for the first instance and +


    \glsxtrbookindexlastmarkfmt{label}{indexname}

    -

    -See §7 Auto-Indexing for further details. -

    As from version 1.04, the post-name hook \glsxtrpostnamehook will also use -\glsxtrpostnamecategory⟩ if it exists. You can use \glscurrententrylabel to -obtain the entry label with the definition of this command. For example, -suppose you are using a glossary style the doesn’t display the symbol, you can -insert the symbol after the name for a particular category, say, the “symbol” -category: +class="cmtt-10">}


    +

    +for the last. +

    These commands are designed for use in page headers or footers where the page +number is stable. For example, \glsxtrbookindexname can be redefined to mark the +current entry:

    -
    -\newcommand*{\glsxtrpostnamesymbol}{\space - 
     (\glsentrysymbol{\glscurrententrylabel})} -
    -

    For convenience, as from v1.31, you can use -


    \glsdefpostname  \glsdefpostname{category}{definition}

    -

    -This is simply a shortcut for:

    -
    -\csdef{glsxtrpostnamecategory}{definition} +
    +\renewcommand{\glsxtrbookindexname}[1]{% + 
      \glsxtrbookindexmarkentry{#1}% + 
      \glossentryname{#1}% + 
    }
    -
    Note that it doesn’t check if the command has already been defined. -

    As from version 1.25, the post-name hook also does -


    \glsextrapostnamehook  \glsextrapostnamehook{label}

    -

    -(before \glsxtrpostnamecategory⟩) to allow for additional non-category related code. -This does nothing by default. -

    The post-description code used within the glossary is modified so that it also -does -


    \glsxtrpostdescription  \glsxtrpostdescription

    -

    -This occurs before the original \glspostdescription, so if the nopostdot=false -option is used, it will be inserted before the terminating full stop. -

    This new command will do \glsxtrpostdesccategory⟩ if it exists, where -⟨category⟩ is the category label associated with the current entry. For example -\glsxtrpostdescgeneral for entries with the category set to general or -\glsxtrpostdescacronym for entries with the category set to acronym. For -convenience, as from v1.31, you can use -


    \glsdefpostdesc  \glsdefpostdesc{category}{definition}

    -

    -This is simply a shortcut for:

    -
    +

    If you only want to mark the top-level entries, remember to redefine \csdef{glsxtrpostdesccategory}{definition} -

    -
    Note that it doesn’t check if the command has already been defined. -

    Since both \glossentry and \subglossentry set -


    \glscurrententrylabel  \glscurrententrylabel

    - - - -

    -to the label for the current entry, you can use this within the definition of these -post-description hooks if you need to reference the label. -

    For example, suppose you want to insert the plural form in brackets after the -description in the glossary, but only for entries in the general category, then you could -do: +class="cmtt-10">\glsxtrbookindexsubname as it defaults to \glsxtrbookindexname:

    -
    -\renewcommand{\glsxtrpostdescgeneral}{\space - 
     (plural: \glsentryplural{\glscurrententrylabel})} +
    +\renewcommand{\glsxtrbookindexsubname}[1]{% + 
      \glossentryname{#1}% + 
    }
    -

    This means you don’t have to define a custom glossary style, which you may find -more complicated. (It also allows more flexibility if you decide to change the -underlying glossary style.) -

    This feature can’t be used for glossary styles that ignore \glspostdescription or if -you redefine \glspostdescription without including \glsxtrpostdescription. -(For example, if you redefine \glspostdescription to do nothing instead of using -the nopostdot option to suppress the terminating full stop.) See §2.12.3 The -glossaries-extra-stylemods Package to patch the predefined styles provided by glossaries -that are missing \glspostdescription.
    -

    -

    -

    -

    Top

    2.12.2 Number List

    -

    The number list is now placed inside the argument of -


    \GlsXtrFormatLocationList  \GlsXtrFormatLocationList{number list} -

    -

    -This is internally used by \glossaryentrynumbers. The nonumberlist option -redefines \glossaryentrynumbers so that it doesn’t display the number list, but it -still saves the number list in case it’s required. -

    If you want to suppress the number list always use the nonumberlist option -instead of redefining \glossaryentrynumbers to do nothing.
    -

    -

    If you want to, for example, change the font for the entire number list -then redefine \GlsXtrFormatLocationList as appropriate. Don’t modify -\glossaryentrynumbers. -

    Sometimes users like to insert “page” or “pages” in front of the number list. This -is quite fiddly to do with the base glossaries package, but glossaries-extra provides a -way of doing this. First you need to enable this option and specify the text to display -using: -


    \GlsXtrEnablePreLocationTag  \GlsXtrEnablePreLocationTag{page}{pages} -

    -

    -where ⟨page⟩ is the text to display if the number list only contains a single location and -⟨pages⟩ is the text to display otherwise. For example: +

    +

    Then if you’re using fancyhdr you can set the page style to show the first and last +entry for the current page with:

    -
    -\GlsXtrEnablePreLocationTag{Page: }{Pages: } +
    +  \pagestyle{fancy}% + 
      \lhead{\thepage}% + 
      \lfoot{\glsxtrbookindexfirstmark}% + 
      \cfoot{}% + 
      \rfoot{\glsxtrbookindexlastmark}%
    -

    An extra run is required when using this command. -

    Use glsignore not @gobble as the format if you want to suppress the page -number (and only index the entry once).
    -

    -

    See the accompanying sample file sample-pages.tex. -

    Note that bib2gls can be instructed to insert a prefix at the start of non-empty -location lists, which can be used as an alternative to \GlsXtrEnablePreLocationTag. -

    +

    +

    -

    Top

    2.12.3 The glossaries-extra-stylemods Package

    -

    As from v1.02, glossaries-extra now includes the package glossaries-extra-stylemods that -will redefine the predefined styles to include the post-description hook (for those that -are missing it). You will need to make sure the styles have already been defined -before loading glossaries-extra. For example: +

    Top

    3.2 glossary-longextra package

    +

    As from version 1.37, the glossaries-extra package comes with the supplementary +package glossary-longextra that provides additional styles, listed below, that use the +longtable environment. If you know that your glossary won’t span more than a page +and you need to use it in a context that’s incompatible with longtable, you can +instead setup these styles to use tabular instead. In order to do this you must +use +


    \GlsLongExtraUseTabulartrue

    +

    +before the style is set. For example:

    -
    -\usepackage{glossaries-extra} - 
    \usepackage{glossary-longragged} - 
    \usepackage{glossaries-extra-stylemods} +
    +\GlsLongExtraUseTabulartrue + 
    \setglossarystyle{long-name-desc}
    -

    Alternatively you can load glossary-name.sty at the same time by passing ⟨name⟩ -as a package option to glossaries-extra-stylemods. For example: +

    or

    -
    -\usepackage{glossaries-extra} - 
    \usepackage[longragged]{glossaries-extra-stylemods} +
    +\GlsLongExtraUseTabulartrue + 
    \printunsrtglossary[style={long-name-desc}]
    -

    Another option is to use the stylemods key when you load glossaries-extra. You can -omit a value if you only want to use the predefined styles that are automatically -loaded by glossaries (for example, the long3col style): - - - -

    -
    -\usepackage[style=long3col,stylemods]{glossaries-extra} -
    -

    Or the value of stylemods may be a comma-separated list of the style package -identifiers. For example: +

    If you use this setting, you can change the default vertical alignment with: +


    \glslongextraTabularVAlign

    +

    +The default definition is c. +

    The column titles are formatted according to: +


    \glslongextraHeaderFmt{text}

    +

    +which simply does \textbf{text} by default. +

    The name column has the title given by \entryname and the column alignment is +given by: +


    \glslongextraNameAlign

    +

    +which expands to l (left) by default. +

    The symbol column (where applicable) has the title given by \symbolname and +the column alignment is given by: +


    \glslongextraSymbolAlign

    +

    +which expands to c (centred) by default. +

    The location list column (where applicable) has the title given by \pagelistname +and the column alignment is given by: +


    \glslongextraLocationAlign

    +

    +which expands to

    -
    -\usepackage[style=mcoltree,stylemods=mcols]{glossaries-extra} +
    +>{\raggedright}p{\glspagelistwidth}
    -

    Remember to group the value if it contains any commas: +

    by default. (Ragged-right paragraph, \glspagelistwidth is defined in glossary-long, +which is automatically loaded.) +

    The description column has the title given by \descriptionname and the column +alignment is given by: +


    \glslongextraDescAlign

    +

    +which expands to

    -
    -\usepackage[stylemods={mcols,longbooktabs}]{glossaries-extra} +
    +>{\raggedright}p{\glsdescwidth}
    -

    -

    Note that the inline style is dealt with slightly differently. The original definition -provided by the glossary-inline package uses \glspostdescription at the end of the -glossary (not after each entry description) within the definition of \glspostinline. -The style modification changes this so that \glspostinline just does a full stop -followed by space factor adjustment, and the description \glsinlinedescformat and -sub-entry description formats \glsinlinesubdescformat are redefined to include -\glsxtrpostdescription (not \glspostdescription). This means that the -modified inline style isn’t affected by the nopostdot option, but the post-description -category hook can still be used. -

    The tabular-like styles, such as long are adjusted so that the \ifglsnogroupskip -conditional (set with nogroupskip) is moved outside of the definition of -\glsgroupskip to avoid problems that cause an “Incomplete \iftrue” error with -\printunsrtglossary and \printnoidxglossary. This means that if you want to -change this conditional using \setupglossaries or using the nogroupskip option in +

    by default. (Ragged-right paragraph, \glsdescwidth is defined in glossary-long, +which is automatically loaded.) +

    Unlike the long styles provided by the base glossaries package, these new styles try +to determine the value of \glsdescwidth at the start of the glossary according to the +number of columns provided by the style. The calculations are performed by the +following commands: +


    \glslongextraSetDescWidth

    +

    +This is used by the styles that have a name and description column. The value of \printglossary, \printnoidxglossary or \printunsrtglossary, you must also -reset the glossary style. -

    As from version 1.21, the hard-coded \space before the number list in many of -the predefined styles is replaced with -


    \glsxtrprelocation  \glsxtrprelocation

    -

    -This just defaults to \space but may be redefined as required. For example: - - - +class="cmtt-10">\glsdescwidth is computed as:

    -
    -\renewcommand{\glsxtrprelocation}{\dotfill} +
    + \glsdescwidth = \linewidth- 4\tabcolsep- W +
    +

    +where W is a guess at the width of the name column. This is first set to the width of +the name column header:

    +
    +\settowidth{width}{\glslongextraHeaderFmt\entryname}
    -

    -

    The list styles use -


    \glslistprelocation  \glslistprelocation

    -

    -(which defaults to \glsxtrprelocation) for top-level items and -


    \glslistchildprelocation  \glslistchildprelocation

    -

    -(which defaults to \glslistprelocation) for child items. -

    As from v1.31, the description (including the post-description hook) is governed -by: -


    \glslistdesc  \glslistdesc{label If any names in that column are larger than this, then you need to specify the widest +name using: +


    \glslongextraSetWidest{widest name}

    -

    -for the list and altlist styles (but not the listdotted variations). -

    For just the list style and its letter group variations (not the altlist or listdotted -variations) the number list for child entries is followed by -


    \glslistchildpostlocation  \glslistchildpostlocation

    -

    -which defaults to a full stop. -

    The default value of \glslistdottedwidth is changed so that it’s set at the start -of the document (if it hasn’t been changed in the preamble). This should -take into account situations where \hsize isn’t set until the start of the -document. -

    The separator between groups (if not nogroupskip) is now given by: -


    \glslistgroupskip  \glslistgroupskip

    -

    -This defaults to \indexspace with penalties to deter page breaks. This command -isn’t used if nogroupskip is set. -

    The glossary-tree package introduced two new commands in glossaries version 4.22, -\glstreegroupheaderfmt and \glstreenavigationfmt, which are used to format -the letter group headings and the navigation elements for the appropriate styles. -These two new commands are defined in terms of \glstreenamefmt since that was -the command originally used for the group headings and navigation. This -now allows these different elements to be defined independently, but the -most common redefinition is for \glstreenamefmt to remove the bold in -the name. If the bold is still required for the group heading and navigation -elements, then both other commands also need redefining. To simplify matters, if -\glstreenamefmt has been defined, as from v1.31 glossaries-extra-stylemods -defines: -


    \glstreedefaultnamefmt  \glstreedefaultnamefmt{

    +or +


    \glslongextraUpdateWidest{text}

    -

    -which simply does \textbf{text} and redefines \glstreenamefmt, -\glstreegroupheaderfmt and \glstreenavigationfmt all in terms of -\glstreedefaultnamefmt. This means that if you want to change all three to use a -particular style you only need to redefine \glstreedefaultnamefmt, but if you only -want to redefine \glstreenamefmt without affecting the other two commands, then -you now can. -

    The separator between groups (if not nogroupskip) is now given by: -


    \glstreegroupskip  \glstreegroupskip

    -

    -This defaults to \indexspace with penalties to deter page breaks. This command -isn’t used if nogroupskip is set (except for the styles that display the group -titles). -

    The styles that display the group titles now use: -


    \glstreePreHeader  \glstreePreHeader{label

    +These work like the analogous commands \glssetwidest and \glsupdatewidest +provided with the alttree style, but in this case there’s no hierarchy. The default +widest name is obtained from the alttree top-level name if set, otherwise it’s empty, +so you can use bib2gls’s set-widest option. If you have the entry counter enabled, +you will need to include this with the name for the extra material to be taken into +account. +

    The name isn’t shown for child entries by default, but if you change this and you +want to use bib2gls’s set-widest option (for bib2gls v1.8+) then you need to +redefine: +


    \glslongextraUpdateWidestChild{level}{titletext}

    -

    -where ⟨label⟩ is the group label and ⟨title⟩ is the group title. This does nothing by -default and is inserted before the group title. You can redefine it to add the group -title to the PDF bookmarks. For example, if the glossary title uses \chapter -then: +

    +This does nothing by default, but if you are including the child names then you need +to redefine this command:

    -
    -\renewcommand{\glstreePreHeader}[2]{% - 
     \pdfbookmark[1]{#2}{\currentglossary.#1}% +
    +\renewcommand{\glslongextraUpdateWidestChild}[2]{% + 
     \glslongextraUpdateWidest{#2}%  
    }
    -

    will insert section-level bookmarks. The use of \currentglossary helps to provide -unique bookmark labels in the event of multiple glossaries. -

    The index-like and tree-like styles insert the pre-number list space with -


    \glstreeprelocation  \glstreeprelocation

    -

    -(which defaults to \glsxtrprelocation) for top-level items and -


    \glstreechildprelocation  \glstreechildprelocation

    -

    -(which defaults to \glstreeprelocation) for child items. -

    As from version 1.31, the glossaries-extra-stylemods package also provides: -


    \glstreenonamedesc  \glstreenonamedesc{label}

    -

    -which is used by the treenoname styles to display the pre-description separator, the -description and the post-description hook. Similarly for the symbol: -


    \glstreenonamesymbol  \glstreenonamesymbol{label}

    -

    -The above are just used for top-level entries. Child entries don’t have the name or -symbol displayed for the treenoname styles, so there’s only a command for the child -description: -


    \glstreenonamechilddesc  \glstreenonamechilddesc{

    +

    If you prefer to set an explicit width for the description column then you need to +redefine \glslongextraSetDescWidth. For example: + + + +

    +
    +\renewcommand{\glslongextraSetDescWidth}{% + 
      \setlength{\glsdescwidth}{0.6\linewidth}% + 
    } +
    +

    +

    The styles that have a name, symbol and description, \glsdescwidth is set +with: +


    \glslongextraSymSetDescWidth

    +

    +This first uses \glslongextraSetDescWidth and then subtracts 2\tabcolsep and +the width of the symbol column header from \glsdescwidth. This assumes that the +symbol column header is larger than any of the symbols. If this isn’t appropriate then +you can redefine this command. For example: + + + +

    +
    +\renewcommand{\glslongextraSymSetDescWidth}{% + 
      \glslongextraSetDescWidth + 
      \addtolength{\glsdescwidth}{-3cm}% + 
    } +
    +

    or + + + +

    +
    +\renewcommand{\glslongextraSymSetDescWidth}{% + 
      \setlength{\glsdescwidth}{.5\linewidth}% + 
    } +
    +

    +

    For the styles that have a name, description and location column, \glsdescwidth +is set using: +


    \glslongextraLocSetDescWidth

    +

    +This uses \glslongextraSetDescWidth and then subtracts 2\tabcolsep and +\glspagelistwidth from \glsdescwidth. You can redefine this command to set +both \glsdescwidth and \glspagelistwidth if appropriate. +

    For the styles that have a name, description, symbol and location column, +\glsdescwidth is set using: +


    \glslongextraSymLocSetDescWidth

    +

    +This uses \glslongextraSymSetDescWidth and then subtracts 2\tabcolsep and +\glspagelistwidth from \glsdescwidth. Again, you can redefine this command to +explicitly set both lengths. +

    In all cases, the top-level name is formatted according to: +


    \glslongextraNameFmt{label}

    -

    -

    For the tree styles (but not the treenoname or alttree styles), the description is -displayed using: -


    \glstreedesc  \glstreedesc{

    +This does

    +
    +\glsentryitem{label}

    -

    -and the symbol with: -


    \glstreesymbol  \glstreesymbol{}\glstarget{label}{\glossentryname{label}} +
    +
    which includes the entry counter (if enabled), the target and the post-name +link. +

    The top-level description is formatted according to: +


    \glslongextraDescFmt{label}

    -

    -Again the above two commands are just for top-level entries. The child entries -use: -


    \glstreechilddesc  \glstreechilddesc{

    +This does \glossentrydesc{label} followed by the post-description hook. +

    The styles that have a symbol column format the symbol using: +


    \glslongextraSymbolFmt{label}

    -

    -for the description and -


    \glstreechildsymbol  \glstreechildsymbol{

    +This just does \glossentrysymbol{label}. +

    The styles that have a location list column format the list using: +


    \glslongextraLocationFmt{label}{locations}

    -

    -for the symbol. +

    +This just does ⟨locations⟩ and ignores the label. -

    As from version 1.41, there are now wrapper commands for \glstreedesc and -\glstreechilddesc that check for the description and symbol to determine whether -or not to insert a space (\glstreeprelocation or \glstreechildprelocation) -before the page list. These are: -


    \glstreeDescLoc  \glstreeDescLoc{label

    The child entries have their name formatted according to: +


    \glslongextraSubNameFmt{level}{location}

    -

    -for top-level entries and -


    \glstreeChildDescLoc  \glstreeChildDescLoc{label}{location} -

    -

    -for sub-entries. This prevents a spurious space for terms that don’t have a symbol or -description but do have a location list (for example, aliases). -

    As from version 1.05, the glossaries-extra-stylemods package provides some -additional commands for use with the alttree style to make it easier to modify. These -commands are only defined if the glossary-tree package has already been loaded, -which is typically the case unless the notree option has been used when loading -glossaries. -


    \gglssetwidest  \gglssetwidest[level]{name}

    -

    -(New to version 1.21.) This is like \glssetwidest (provided by glossary-tree) but -performs a global assignment. -


    \eglssetwidest  \eglssetwidest[level]{name}

    -

    -This is like \glssetwidest but performs a protected expansion on ⟨name⟩. This has a -localised effect. For a global setting, use -


    \xglssetwidest  \xglssetwidest[level]{name}

    -

    -The following only set the value if ⟨name⟩ is wider than the current value (new to -version 1.23). Local update: -


    \glsupdatewidest  \glsupdatewidest[

    +where ⟨level⟩ is the hierarchical level. This defaults to:

    +
    +\glssubentryitem{label}\glstarget{label}{\strut} +
    +
    This includes the sub-entry counter (if enabled) and the target but doesn’t show the +name. The child description is formatted according to: +


    \glslongextraSubDescFmt{level]{name}{label}

    -

    -Global update: -


    \gglsupdatewidest  \gglsupdatewidest[

    +which defaults to just \glslongextraDescFmt{label} +

    The child symbol is formatted (where appropriate) according to: +


    \glslongextraSubSymbolFmt{level]{name}{label}

    -

    -Locale update (expands ⟨name⟩): -


    \eglsupdatewidest  \eglsupdatewidest[

    +This just does \glslongextraSymbolFmt{label} by default. +

    The styles that have a location list column format the list for child entries +using: +


    \glslongextraSubLocationFmtlevel]{name{label}{locations}

    -

    -Global update (expands ⟨name⟩): -


    \xglsupdatewidest  \xglsupdatewidest[level]{name

    +This just does ⟨locations⟩ and ignores the level and label. +

    The letter group headings are formatted according to: +


    \glslongextraGroupHeading{n}{label}

    -

    -

    The widest entry value can later be retrieved using -


    \glsgetwidestname  \glsgetwidestname

    -

    -for the top-level entries and -


    \glsgetwidestsubname  \glsgetwidestsubname{level

    +which does nothing by default. The first argument ⟨n⟩ is the number of columns in the +table. The second argument ⟨label⟩ is the group label (not the title, although they may +happen to be the same). +

    This can be redefined to show the group heading. For example: + + + +

    +
    +\renewcommand*{\glslongextraGroupHeading}[2]{% + 
      \glsxtrgetgrouptitle{#2}{\thisgrptitle}% + 
      \glslongextraHeaderFmt{\thisgrptitle}% + 
      \tabularnewline + 
      \noalign{\vskip\normalbaselineskip}% + 
    } +
    +

    This ignores the first argument and just puts the group title in the first column +formatted according to \glslongextraHeaderFmt (to match the column +header). +

    Remember that you can also adjust the styles through category attributes. The +name column’s title is given by \entryname, the description column’s title is given by +\descriptionname and (where present) the symbol column’s title is given by +\symbolname, as for the other long styles that have headers. +

    +
    long-name-desc This is like the longragged-booktabs style but doesn’t show the + location list (regardless of the nonumberlist option). The name is shown in + the first column and the description in the second. +

    The symbol is not displayed. The header row is produced with: +


    \glslongextraNameDescHeader

    +

    + This essentially uses the same code as for longragged-booktabs but makes it + easier to adjust the header without having to define a new style. This is defined + as: + + + +

    +
    + \glslongextraNameDescTabularHeader\endhead +  
    \glslongextraNameDescTabularFooter\endfoot +
    +

    where: +


    \glslongextraNameDescTabularHeader

    +

    + sets up the header and +


    \glslongextraNameDescTabularFooter

    +

    + sets up the footer. If you have setup the tabular version of this style then the + above two commands are used at the start and end of the tabular environment + (and \glslongextraNameDescHeader isn’t used). +

    For example, to simply remove the header and footer (for the default longtable + version of the style): + + + +

    +
    + \renewcommand{\glslongextraNameDescHeader}{} +
    +

    Or to change the name alignment to centred: + + + +

    +
    + \renewcommand{\glslongextraNameAlign}{c} +
    +

    +

    +
    long-name-desc-loc This is like the long-name-desc style but has a third column for + the location list. The longtable header is given by: +


    \glslongextraNameDescLocationHeader

    +

    + which similarly defined in terms of the commands used for the tabular + version: +


    \glslongextraNameDescLocationTabularHeader

    +

    + and +


    \glslongextraNameDescLocationTabularFooter

    +

    +

    +
    long-desc-name This is like the long-name-desc style but swaps the columns. Note + that if the entry counter is displayed it will appear at the start of the + second column by default. The longtable header is formatted according + to: +


    \glslongextraDescNameHeader

    +

    + which similarly defined in terms of the commands used for the tabular + version: +


    \glslongextraDescNameTabularHeader

    +

    + and +


    \glslongextraDescNameTabularFooter

    +

    +

    +
    long-loc-desc-name This has three columns containing the location list, + description and name. The longtable header is formatted according + to: + + + +


    \glslongextraLocationDescNameHeader

    +

    + which similarly defined in terms of the commands used for the tabular + version: +


    \glslongextraLocationDescNameTabularHeader

    +

    + and +


    \glslongextraLocationDescNameTabularFooter

    +

    +

    +
    long-name-desc-sym This is has three columns, with the name in the first, the + description in the second and the symbol in the third. +

    The longtable header row is produced with: +


    \glslongextraNameDescSymHeader

    +

    + which similarly defined in terms of the commands used for the tabular + version: +


    \glslongextraNameDescSymTabularHeader

    +

    + and +


    \glslongextraNameDescSymTabularFooter

    +

    +

    +
    long-name-desc-sym-loc This is has four columns, with the name in the first, the + description in the second, the symbol in the third and the location list in the + fourth. +

    The longtable header row is produced with: +


    \glslongextraNameDescSymLocationHeader

    +

    + which similarly defined in terms of the commands used for the tabular + version: +


    \glslongextraNameDescSymLocationTabularHeader

    +

    + and +


    \glslongextraNameDescSymLocationTabularFooter

    +

    + + + +

    +
    long-name-sym-desc This is like the long-name-desc-sym but the second and third + column are swapped. The longtable header row is given by: +


    \glslongextraNameSymDescHeader

    +

    + which similarly defined in terms of the commands used for the tabular + version: +


    \glslongextraNameSymDescTabularHeader

    +

    + and +


    \glslongextraNameSymDescTabularFooter

    +

    +

    +
    long-name-sym-desc-loc This is like the long-name-desc-sym-loc but the second and + third column are swapped. The longtable header row is given by: +


    \glslongextraNameSymDescLocationHeader

    +

    + which similarly defined in terms of the commands used for the tabular + version: +


    \glslongextraNameSymDescLocationTabularHeader

    +

    + and +


    \glslongextraNameSymDescLocationTabularFooter

    +

    +

    +
    long-sym-desc-name This has the symbol in the first column, the description in the + second and the name in the third. The longtable header row is given + by: +


    \glslongextraSymDescNameHeader

    +

    + which similarly defined in terms of the commands used for the tabular + version: +


    \glslongextraSymDescNameTabularHeader

    +

    + and +


    \glslongextraSymDescNameTabularFooter

    +

    + + + +

    +
    long-loc-sym-desc-name This has the location list in the first column, symbol in the + second column, the description in the third and the name in the fourth. The + longtable header row is given by: +


    \glslongextraLocationSymDescNameHeader

    +

    + which similarly defined in terms of the commands used for the tabular + version: +


    \glslongextraLocationSymDescNameTabularHeader

    +

    + and +


    \glslongextraLocationSymDescNameTabularFooter

    +

    +

    +
    long-desc-sym-name This has the description in the first column, the symbol in the + second and the name in the third. The longtable header row is given + by: +


    \glslongextraDescSymNameHeader

    +

    + which similarly defined in terms of the commands used for the tabular + version: +


    \glslongextraDescSymNameTabularHeader

    +

    + and +


    \glslongextraDescSymNameTabularFooter

    +

    +

    +
    long-loc-desc-sym-name This has the location list in the first column, the description + in the second column, the symbol in the third and the name in the fourth. The + longtable header row is given by: +


    \glslongextraLocationDescSymNameHeader

    +

    + which similarly defined in terms of the commands used for the tabular + version: +


    \glslongextraLocationDescSymNameTabularHeader

    +

    + and + + + +


    \glslongextraLocationDescSymNameTabularFooter

    +

    +

    +
    +

    +

    +

    Top

    3.3 glossary-topic package

    +

    As from version 1.40, the glossaries-extra package comes with the supplementary +package glossary-topic that provides glossary styles designed for hierarchical glossaries +where the top-level entries are topic titles. This package automatically loads the +multicols package. If the glossary-tree package is also loaded then commands like +\glssetwidest can be used on these styles in much the same way as for the alttree +style. If a widest value isn’t set then these styles behave more like the tree +style. +

    +topic
    This style is similar to the tree style but the indentation doesn’t start until + the second sub-item level. The top-level entries have the name displayed + in a larger font with the description following in a new paragraph. This + style doesn’t support the nogroupskip setting. +
    +topicmcols
    This style is like the topic style but the sub-entries are placed inside a + multicols environment. The environment name is supplied in the value of the + command: +


    \glstopicColsEnv

    +

    + You can change this to the starred form. For example: + + + +

    +
    + \renewcommand{\glstopicColsEnv}{multicols*} +
    +

    The number of columns is given by the command: +


    \glstopicCols

    +

    + The default value is 2.

    +

    Both styles use the following commands. +


    \glstopicParIndent

    +

    +This command is a length that’s used for the paragraph indentation in any +multi-paragraph description for top-level entries, but not for the first paragraph (at +the start of the description) which isn’t indented. +


    \glstopicSubIndent

    +

    +This command is a length that’s used to calculate the hanging indentation for +sub-entries. The level 1 sub-entries don’t indent the name. Level n sub-entries have +the name indented by (n- 1)×\glstopicSubIndent. The hanging indent depends on +whether or not a widest name has been set for the level. +


    \glstopicInit

    +

    +Hook used at the start of the glossary. Does nothing by default. +

    Although the styles don’t support letter groups by default, if you have many +topics (top-level entries) and you feel that it would help the reader to divide them up +into headed letter groups, you can redefine: +


    \glstopicGroupHeading{group label}

    +

    +This does nothing by default. If you want to redefine it, you can fetch the +title corresponding to the group label with \glsxtrgetgrouptitle. For +example: -

    -for sub-entries, where ⟨level⟩ is the level number. -

    Note that if you are using +

    +

    Remember that if you use bib2gls, you can use the resource option set-widest -which will try to determine the widest name of all the selected entries. This isn’t -guaranteed to work as it may depend on fonts or commands that bib2gls -can’t replicate, but it should be suitable for names that just consist of text, -and can be more efficient than iterating over all the defined entries using -TEX. -

    The command \glsfindwidesttoplevelname provided by glossary-tree has a -CamelCase synonym: -


    \glsFindWidestTopLevelName  \glsFindWidestTopLevelName[glossary list] -

    -

    -Similar commands are also provided: -


    \glsFindWidestUsedTopLevelName  \glsFindWidestUsedTopLevelName[glossary -list]

    -

    -This has an additional check that the entry has been used. Naturally this is only -useful if the glossaries that use the alttree style occur at the end of the document. -This command should be placed just before the start of the glossary. (Alternatively, -place it at the end of the document and save the value in the auxiliary file for the -next run.) -


    \glsFindWidestUsedAnyName  \glsFindWidestUsedAnyName[glossary list] -

    -

    -This is like the previous command but if doesn’t check the parent key. This is useful if -all levels should have the same width for the name. -


    \glsFindWidestAnyName  \glsFindWidestAnyName[glossary list]

    -

    -This is like the previous command but doesn’t check if the entry has been -used. -


    \glsFindWidestUsedLevelTwo  \glsFindWidestUsedLevelTwo[glossary list] -

    -

    -This is like \glsFindWidestUsedTopLevelName but also sets the first two sub-levels -as well. Any entry that has a great-grandparent is ignored. -


    \glsFindWidestLevelTwo  \glsFindWidestLevelTwo[glossary list] -

    -

    -This is like the previous command but doesn’t check if the entry has been -used. -


    \glsFindWidestUsedAnyNameSymbol  \glsFindWidestUsedAnyNameSymbol -[glossary list]{registerbib2gls, you will need the --group (or -g) switch to +support this. +


    \glstopicItem{label}{location list}

    -

    -This is like \glsFindWidestUsedAnyName but also measures the symbol. The length -of the widest symbol is stored in ⟨register⟩. +

    +Used to format the name, symbol, description and location list for the top-level +entries. This starts with a paragraph break followed by: +


    \glstopicPreSkip

    +

    +which defaults to \medskip. There is then a hook: +


    \glstopicMarker{label}

    +

    +which does nothing by default, but may be redefined. For example, to add a line to +the table of contents. The name and symbol are set in the form of a title +using: +


    \glstopicTitle{label}

    +

    +This uses \Glossentryname which converts the first letter to upper case. If there’s a +symbol, this is added in parentheses. Both name and symbol (if present) are +encapsulated by +


    \glstopicTitleFont{text}

    +

    +This uses a bold, large font by default. +

    If the entry has the description key set (tested with \ifglshasdesc) then a +paragraph break is inserted followed by: +


    \glstopicMidSkip

    +

    +which defaults to \smallskip. This is followed by the description which is formatted +according to: +


    \glstopicDesc{label}

    +

    +This just does \Glossentrydesc{label} followed by the post-description +hook. +

    A paragraph break followed by: +


    \glstopicPostSkip

    +

    +comes next regardless of whether or not the description was displayed. This defaults +to \smallskip. This is then followed by: -


    \glsFindWidestAnyNameSymbol  \glsFindWidestAnyNameSymbol[glossary -list]{register}

    -

    -This is like the previous command but it doesn’t check if the entry has been -used. -


    \glsFindWidestUsedAnyNameSymbolLocation  \glsFindWidestUsedAnyNameSymbolLocation -[glossary list]{symbol register}{location register}

    -

    -This is like \glsFindWidestUsedAnyNameSymbol but also measures the number list. -This requires \glsentrynumberlist (see the glossaries user manual). The length of -the widest symbol is stored in ⟨symbol register⟩ and the length of the widest number -list is stored in ⟨location register⟩. -


    \glsFindWidestAnyNameSymbolLocation  \glsFindWidestAnyNameSymbolLocation -[glossary list]{symbol register


    \glstopicLoc{label}{location registerlocation list}

    -

    -This is like the previous command but it doesn’t check if the entry has been -used. -


    \glsFindWidestUsedAnyNameLocation  \glsFindWidestUsedAnyNameLocation -[glossary list]{register

    +which may be used to display the location list, but does nothing by default. +

    The sub-entries first set up the paragraph and hanging indentations using: +


    \glstopicAssignSubIndent{level}

    -

    -This is like \glsFindWidestUsedAnyNameSymbolLocation but doesn’t measure the -symbol. The length of the widest number list is stored in ⟨register⟩. -


    \glsFindWidestAnyNameLocation  \glsFindWidestAnyNameLocation[glossary -list]{register

    +This uses: +


    \glstopicAssignWidest{level}

    -

    -This is like the previous command but doesn’t check if the entry has been -used. -

    The layout of the symbol, description and number list is governed by -


    \glsxtralttreeSymbolDescLocation  \glsxtralttreeSymbolDescLocation -{

    +to determine if a widest name has been set for the given level. +

    The sub-entry has its information displayed using: +


    \glstopicSubItem{level}{label}{number listlocation}

    -

    -for top-level entries and -


    \glsxtralttreeSubSymbolDescLocation  \glsxtralttreeSubSymbolDescLocation -{

    +This encapsulates the name with: +


    \glstopicSubNameFont{text}

    +

    +By default this just uses \textbf. This is followed by: +


    \glstopicSubItemSep

    +

    +which defaults to \quad. The name and separator are passed in the ⟨text⟩ argument +of: +


    \glstopicSubItemBox{level}{text}

    +

    +If a widest name was set for the given level, this will put ⟨text⟩ inside a box of that +width otherwise it just does ⟨text⟩. +

    This is followed by the symbol in parentheses if set. Then, if the description is set, +the description and post-description hook are displayed followed by: +


    \glstopicSubPreLocSep

    +

    +(This command isn’t used if the description isn’t set.) +

    Finally the location list is displayed using: +


    \glstopicSubLoc{label}{number listlocation}

    -

    -for sub-entries. -

    There is now a user level command that performs the initialisation for the alttree -style: -


    \glsxtralttreeInit  \glsxtralttreeInit

    -

    -

    The paragraph indent for subsequent paragraphs in multi-paragraph descriptions -is provided by the length -


    \glsxtrAltTreeIndent  \glsxtrAltTreeIndent

    -

    - - - -

    For additional commands that are available with the alttree style, see the -documented code (glossaries-extra-code.pdf). For examples, see the -accompanying sample files sample-alttree.tex, sample-alttree-sym.tex and -sample-alttree-marginpar.tex. +

    +which just does ⟨location⟩ by default.

    -

    -

    Top

    3.

    +

    Top

    4. Abbreviations

    -

    The new abbreviation system provided by

    The new abbreviation system provided by glossaries-extra is more flexible than the acronym handling provided by the base glossaries package. The glossaries-extra package modifies the underlying formatting used by \gls (and -its variants) so that terms that are recognised as abbreviations can have -their formatting dealt with by the style. You therefore need to select an -abbreviation style that ensures that \gls (and its variants) displays the desired -output. -

    Don’t use commands like \glstext or \glsfirst with abbreviations as they -aren’t flexible enough to handle some abbreviation styles and unexpected -results may occur. Use commands like \gls (and its +variants) so that terms that are recognised as abbreviations can have their +formatting dealt with by the style. You therefore need to select an abbreviation +style that ensures that \gls (and its variants) displays the desired output. +See the file sample-abbr-styles.pdf for samples of all provided abbreviation +styles. +

    Don’t use \glsfirst, \Glsfirst or \GLSfirst with abbreviations as they aren’t +flexible enough to handle some abbreviation styles and unexpected results may occur. +(To a lesser degree, this also applies to \glstext etc.) Use commands like +\glsfmttext, \glsfmtshort or \glsfmtlong in -section headings or captions instead of \gls. If you don’t want the full form -to show on first use of \gls use one of the “nolong” or “noshort” styles. -
    -

    -

    Abbreviations include acronyms (words formed from initial letters, such as +class="cmtt-10">\glsfmtlong in section headings or captions instead +of \gls. If you don’t want the full form to show on first use of \gls use one of the +“nolong” or “noshort” styles.

    +

    +

    This lack of flexibility in \glsfirst can be demonstrated with the following +document: + + + +

    +
    +\documentclass{article} + 
    \usepackage{glossaries-extra} + 
    \setabbreviationstyle{footnote} + 
    \newabbreviation{ex}{EX}{Example} + 
    \begin{document} + 
    Compare \gls{ex}['s] with \glsfirst{ex}['s]. + 
    \end{document} +
    +

    The first use \gls has the footnote marker after the inserted material “EX’s1” but +\glsfirst has it before the inserted material “EX1’s” which is inappropriate. Note +that if the style is changed to postfootnote, the footnote marker appears after the +inserted material as \footnote is in the post-link hook. +

    There are some instances where \glstext can be useful. It’s used internally by +\glsfmttext, which in turn is used by \glsseelistformat if the entry has a +short form. If \glsfmtshort is used, this enforces the short form, but if +\glsfmttext is used, then the long form will be used for the “noshort” styles, which +is more appropriate. In this particular situation, there’s no need to worry +about inserted material as the final optional argument isn’t supported by +\glsfmttext. +

    Abbreviations include acronyms (words formed from initial letters, such as “laser”), initialisms (initial letters of a phrase, such as “html”, that aren’t pronounced as words) and contractions (where parts of words are omitted, often replaced by an apostrophe, such as “don’t”). The “acronym” code provided by the @@ -9406,19 +9133,16 @@ replaced by an apostrophe, such as “don’t”). The “acrony class="cmss-10">glossaries package is misnamed as it’s more often than not used for initialisms instead. Acronyms tend not to be expanded on first use (although they may need + id="dx1-24010">first use (although they may need to be described for readers unfamiliar with the term). They are therefore more like a regular term, which may or may not require a description in the glossary. -

    The

    The glossaries-extra package corrects this misnomer, and provides better abbreviation handling, with -


    \newabbreviation 


    \newabbreviation[options]{}{short}{long} -

    -

    -

    This sets the }


    +

    +

    This sets the category key to key to abbreviation by default, but that value may be overridden in ⟨options⟩. The category may have attributes that modify the way abbreviations are defined. For example, the insertdots attribute will automatically + id="dx1-24013"> attribute will automatically insert full stops (periods) into ⟨short⟩ or the noshortplural attribute will set the default + id="dx1-24014"> attribute will set the default value of the shortplural key to just ⟨ key to just ⟨short⟩ (without appending the plural suffix). See §5 +class="cmsy-10">§6 Categories for further details. -

    See

    See §2.7 §2.8 Nested Links regarding the pitfalls of using commands like \gls or + id="dx1-24016"> or \glsxtrshort within ⟨ within ⟨short⟩ or ⟨long⟩. -

    Make sure that you set the category attributes before defining new abbreviations -or they may not be correctly applied.
    -

    -

    The \newacronym command provided by the glossaries package is redefined by +

    Make sure that you set the category attributes before defining new abbreviations +or they may not be correctly applied.
    +

    +

    The \newacronym command provided by the glossaries package is redefined by glossaries-extra to use \newabbreviation with the category set to set to acronym (see also §2.8 §2.9 Acronym Style Modifications) so -


    \newacronym 


    \newacronym[options]{short}{long}

    -

    +

    is now equivalent @@ -9520,7 +9241,7 @@ class="cmtt-10">{⟨long}
    -

    The

    The \newabbreviation command is superficially similar to the glossaries package’s \newacronym but you can apply different styles to differe default style is short-nolong for entries in the for entries in the acronym category and category and short-long for + id="dx1-24023"> for entries in the abbreviation category. (These aren’t the same as the acronym + id="dx1-24024"> category. (These aren’t the same as the acronym styles provided by the glossaries package, although they may produce similar results.) -

    The way the abbreviations are displayed by commands like

    The way the abbreviations are displayed by commands like \gls varies according to the abbreviation style. The styles are set according to the entry’s category so, unlike the base glossaries package, you can have different abbreviation styles within the same glossary. -

    There are two types of full forms. The display full form, which is used on +

    There are two types of full forms. The display full form, which is used on first use by commands like \gls and the inline full form, which is used by + id="dx1-24026"> and the inline full form, which is used by commands like \glsxtrfull. For some of the abbreviation styles, such as + id="dx1-24027">. For some of the abbreviation styles, such as long-short, the display and inline forms are the same. In the case of styles + id="dx1-24028">, the display and inline forms are the same. In the case of styles such as short-nolong or or short-footnote, the display and inline full forms are + id="dx1-24030">, the display and inline full forms are different. -

    These formatting commands aren’t stored in the

    These formatting commands aren’t stored in the short, , shortplural, , long or + id="dx1-24033"> or longplural fields, which means they won’t be used within commands like + id="dx1-24034"> fields, which means they won’t be used within commands like \glsentryshort (but they are used within commands like \glsxtrshort and \glsfmtshort). Note that \glsxtrlong and the case-changing variants don’t use + id="dx1-24035"> and the case-changing variants don’t use \glsfirstlongfont. -

    You can apply the formatting command used for the short form to some arbitrary +

    You can apply the formatting command used for the short form to some arbitrary text using -


    \glsuseabbrvfont 


    \glsuseabbrvfont{text}{category}

    -

    + + + +

    where ⟨category⟩ is the category label that identifies the abbreviation style. Similarly for the formatting command use by the long form: -


    \glsuselongfont 


    \glsuselongfont{text}{category}

    -

    - - - +

    +

    You can’t use the acronym commands provided by the base package with the new +abbreviations provided by the glossaries-extra package. The style commands that +replace \setacronymstyle, \acrshort etc are described in §4.2 Abbreviation Styles. +The acronymlists package option and associated commands aren’t supported. The +\forallacronyms command, which iterates over all acronym lists, should be replaced +with: +


    \forallabbreviationlists{cs}{body}

    +

    -

    Top

    3.1

    Top

    4.1 Tagging Initials

    -

    If you would like to tag the initial letters in the long form such that those letters are +

    If you would like to tag the initial letters in the long form such that those letters are underlined in the glossary but not in the main part of the document, you can use -


    \GlsXtrEnableInitialTagging 


    \GlsXtrEnableInitialTagging{categories} -{}{cs}

    -

    +

    before you define your abbreviations. -

    This command (robustly) defines ⟨

    This command (robustly) defines ⟨cs⟩ (a control sequence) to accept a single argument, which is the letter (or letters) that needs to be tagged. The normal behaviour of this command within the document is to simply do its argument, but in the glossary it’s activated for those categories that have the tagging attribute set to + id="dx1-25002"> attribute set to “true”. For those cases it will use -


    \glsxtrtagfont 


    \glsxtrtagfont{text}

    -

    +

    This command defaults to \underline{text} but may be redefined as required. -

    The control sequence ⟨

    The control sequence ⟨cs⟩ can’t already be defined when used with the unstarred version of \GlsXtrEnableInitialTagging for safety reasons. The starred @@ -9666,39 +9402,39 @@ class="cmti-10">cs⟩. As with redefining any commands, ensure that you don’t redefine something important. In fact, just forget the existence of the starred version and let’s pretend I didn’t mention it. -

    The first argument of

    The first argument of \GlsXtrEnableInitialTagging is a comma-separated list of category names. The tagging attribute will automatically be set for those + id="dx1-25005"> attribute will automatically be set for those categories. You can later set this attribute for other categories (see §5 §6 Categories) but this must be done before the glossary is displayed. -

    The accompanying sample file

    The accompanying sample file sample-mixtures.tex uses initial tagging for both the acronym and and abbreviation categories: + id="dx1-25007"> categories:

    -
    +
    \GlsXtrEnableInitialTagging{acronym,abbreviation}{\itag}
    -

    This defines the command

    This defines the command \itag which can be used in the definitions. For example:

    -
    +
    \newacronym  
     [description={a system for detecting the location and  
     speed of ships, aircraft, etc, through the use of radio @@ -9710,28 +9446,25 @@ example:  
    \newabbreviation{xml}{XML}  
     {e\itag{x}tensible \itag{m}arkup \itag{l}anguage}
    -

    The underlining of the tagged letters only occurs in the glossary and then only for +

    The underlining of the tagged letters only occurs in the glossary and then only for entries with the tagging attribute set. -

    + id="dx1-25008"> attribute set. +

    -

    Top

    3.2

    Top

    4.2 Abbreviation Styles

    -

    The abbreviation style must be set before abbreviations are defined using: -


    \setabbreviationstyle 

    The abbreviation style must be set before abbreviations are defined using: +


    \setabbreviationstyle[category]{style-name} -

    -

    +class="cmtt-10">}


    +

    where ⟨style-name⟩ is the name of the style and ⟨category⟩ is the category label @@ -9744,22 +9477,22 @@ modify one or more of the attributes associated with the given category. For example, the long-noshort and and short-nolong styles set the styles set the regular attribute to + id="dx1-26004"> attribute to true. -

    If you want to apply different styles to groups of abbreviations, assign a +

    If you want to apply different styles to groups of abbreviations, assign a different category to each group and set the style for the given category.
    -

    -

    Note that

    +

    Note that \setacronymstyle is disabled by is disabled by glossaries-extra. Use

    }
    instead. The original acronym interface can be restored with \RestoreAcronyms (see + id="dx1-26006"> (see §2.8 §2.9 Acronym Style Modifications). However the original acronym interface is incompatible with all the commands described here. -

    Abbreviations can be used with the standard

    Abbreviations can be used with the standard glossaries commands, such as \gls, + id="dx1-26007">, but don’t use the acronym commands like \acrshort (which use (which use \acronymfont). + id="dx1-26009">). The short form can be produced with: -


    \glsxtrshort 


    \glsxtrshort[options]{label}[insert]

    -

    +

    (Use this instead of \acrshort.) -

    The long form can be produced with -


    \glsxtrlong  .) +

    The long form can be produced with +


    \glsxtrlong[options]{label}[insert]

    -

    +

    (Use this instead of \acrlong.) -

    The .) +

    The inline full form can be produced with -


    \glsxtrfull 


    \glsxtrfull[options]{label}[insert]

    -

    +

    (This this instead of \acrfull.) -

    In general, it’s best not to use commands like .) +

    In general, it’s best not to use commands like \glsfirst for abbreviations, + id="dx1-26016"> for abbreviations, especially if you use the ⟨insert⟩ optional argument. Use either \gls (possibly with a reset) or \glsxtrfull.
    -

    -

    As mentioned earlier, the inline full form may not necessarily match the format +

    +

    As mentioned earlier, the inline full form may not necessarily match the format used on first use with \gls. For example, the short-nolong style only displays the + id="dx1-26018"> style only displays the short form on first use, but the full form will display the long form followed by the + id="dx1-26019">first use, but the full form will display the long form followed by the short form in parentheses. -

    If you want to use an abbreviation in a chapter or section title, use the +

    If you want to use an abbreviation in a chapter or section title, use the commands described in §4 §5 Entries in Sectioning Titles, Headers, Captions and Contents instead.
    -

    -

    The arguments ⟨

    +

    The arguments ⟨options⟩, ⟨label⟩ and ⟨insert⟩ are the same as for commands such as \glstext. There are also analogous case-changing commands: -

    First letter upper case short form: -


    \Glsxtrshort 

    First letter upper case short form: +


    \Glsxtrshort[options]{label}[insert]

    -

    -

    First letter upper case long form: -


    \Glsxtrlong 

    +

    First letter upper case long form: +


    \Glsxtrlong[options]{label}[insert]

    -

    -

    First letter upper case inline full form: -


    \Glsxtrfull 

    +

    First letter upper case inline full form: +


    \Glsxtrfull[options]{label}[insert]

    -

    -

    All upper case short form: +

    +

    All upper case short form: -


    \Glsxtrshort 


    \GLSxtrshort[options]{label}[insert]

    -

    -

    All upper case long form: -


    \Glsxtrlong 

    +

    All upper case long form: +


    \GLSxtrlong[options]{label}[insert]

    -

    -

    All upper case inline full form: -


    \GLSxtrfull 

    +

    All upper case inline full form: +


    \GLSxtrfull[options]{label}[insert]

    -

    -

    Plural forms are also available. -

    Short form plurals: -


    \glsxtrshortpl 

    +

    Plural forms are also available. +

    Short form plurals: +


    \glsxtrshortpl[options]{label}[insert]

    -

    -


    \Glsxtrshortpl 

    +


    \Glsxtrshortpl[options]{label}[insert]

    -

    -


    \GLSxtrshortpl 

    +


    \GLSxtrshortpl[options]{label}[insert]

    -

    -

    Long form plurals: -


    \glsxtrlongpl 

    +

    Long form plurals: +


    \glsxtrlongpl[options]{label}[insert]

    -

    -


    \Glsxtrlongpl 

    +


    \Glsxtrlongpl[options]{label}[insert]

    -

    -


    \GLSxtrlongpl 

    +


    \GLSxtrlongpl[options]{label}[insert]

    -

    -

    Full form plurals: -


    \glsxtrfullpl 

    +

    Full form plurals: +


    \glsxtrfullpl[options]{label}[insert]

    -

    -


    \Glsxtrfullpl 

    +


    \Glsxtrfullpl[options]{label}[insert]

    -

    -


    \GLSxtrfullpl 

    +


    \GLSxtrfullpl[options]{label}[insert]

    -

    -

    Be careful about using

    +

    Be careful about using \glsentryfull, \Glsentryfull, \glsentryfullpl and @@ -10071,49 +9768,48 @@ class="cmtt-10">\Glsentryfullpl. These commands will use the currently ap than the style in use when the entry was defined. If you have mixed styles, you’ll need to use \glsxtrfull instead. Similarly for instead. Similarly for \glsentryshort etc.
    -

    -

    +

    +

    -

    Top

    3.3

    Top

    4.3 Shortcut Commands

    -

    The abbreviation shortcut commands can be enabled using the package option -

    The abbreviation shortcut commands can be enabled using the shortcuts=abbreviation (or =abbreviations +package option (or shortcuts=abbr) or ) or shortcuts=ac. (You can use -both settings at the same time.) The provided shortcut commands listed in -table 3.1. + id="dx1-27003">. (You can use both settings at the +same time.) The provided shortcut commands listed in table 4.1.

    -


    Table 3.1: Abbreviation Shortcut Commands
    +>Table 4.1: Abbreviation Shortcut Commands
    (shortcuts=abbreviation) + id="dx1-27009"> + id="dx1-27012"> + id="dx1-27015"> + id="dx1-27018"> + id="dx1-27021"> + id="dx1-27024"> + id="dx1-27027"> + id="dx1-27030"> + id="dx1-27033"> + id="dx1-27036"> + id="dx1-27039"> + id="dx1-27042"> + id="dx1-27045"> + id="dx1-27048"> + id="dx1-27051"> + id="dx1-27054"> + id="dx1-27057"> + id="dx1-27060"> + id="dx1-27063"> + id="dx1-27066"> + id="dx1-27069"> + id="dx1-27072"> + id="dx1-27075"> + id="dx1-27078">
    (shortcuts=ac)
    \ab \ac \cgls
    \abp \acp \cglspl
    \as \acs \glsxtrshort
    \asp \acsp \glsxtrshortpl
    \al \acl \glsxtrlong
    \alp \aclp \glsxtrlongpl
    \af \acf \glsxtrfull
    \afp \acfp \glsxtrfullpl
    \Ab \Ac \cgls
    \Abp \Acp \cglspl
    \As \Acs \Glsxtrshort
    \Asp \Acsp \Glsxtrshortpl
    \Al \Acl \Glsxtrlong
    \Alp \Aclp \Glsxtrlongpl
    \Af \Acf \Glsxtrfull
    \Afp \Acfp \Glsxtrfullpl
    \AB \AC \cGLS
    \ABP \ACP \cGLSpl
    \AS \ACS \GLSxtrshort
    \ASP \ACSP \GLSxtrshortpl
    \AL \ACL \GLSxtrlong
    \ALP \ACLP \GLSxtrlongpl
    \AF \ACF \GLSxtrfull
    \AFP \ACFP \GLSxtrfullpl
    \newabbr \newabbr \newabbreviation
    + id="dx1-27081">

    -

    Top

    3.4

    Top

    4.4 Predefined Abbreviation Styles

    -

    There are two types of abbreviation styles: those that treat the abbreviation as a +

    There are two types of abbreviation styles: those that treat the abbreviation as a regular entry (so that \gls uses uses \glsgenentryfmt) and those that don’t treat the + id="dx1-28002">) and those that don’t treat the abbreviation as a regular entry (so that \gls uses uses \glsxtrgenabbrvfmt). -

    The regular entry abbreviation styles set the ). +

    The regular entry abbreviation styles set the regular attribute to “true” for the + id="dx1-28005"> attribute to “true” for the category assigned to each abbreviation with that style. This means that on first use, \gls uses the value of the uses the value of the first field and on subsequent use field and on subsequent use \gls uses the value of the + id="dx1-28009"> uses the value of the text field (and analogously for the plural and case-changing versions). The field (and analogously for the plural and case-changing versions). The short and + id="dx1-28011"> and long fields are set as appropriate and may be accessed through commands like + id="dx1-28012"> fields are set as appropriate and may be accessed through commands like \glsxtrshort. -

    The other abbreviation styles don’t modify the . +

    The other abbreviation styles don’t modify the regular attribute. The attribute. The first + id="dx1-28015"> and text fields (and their plural forms) are set and can be accessed through + id="dx1-28016"> fields (and their plural forms) are set and can be accessed through commands like \glsfirst, but they aren’t used by commands like \gls, which + id="dx1-28017">, which instead use the short form (stored in the short key) and the display full + id="dx1-28018"> key) and the display full format (through commands like \glsxtrfullformat that are defined by the + id="dx1-28019"> that are defined by the style). -

    In both cases, the first use of

    In both cases, the first use of \gls may not match the text produced by + id="dx1-28021"> may not match the text produced by \glsfirst (and likewise for the plural and case-changing versions). -

    The sample file (and likewise for the plural and case-changing versions). +

    The sample file sample-abbr-styles.tex demonstrates all predefined styles described here. -

    For the “sc” styles that use

    For the “sc” styles that use \textsc, be careful about your choice of fonts as + id="dx1-28023">, be careful about your choice of fonts as some only have limited support. For example, you may not be able to combine bold and small-caps. I recommend that you at least use the fontenc package with the package with the T1 option or something similar.
    -

    -

    The parenthetical styles, such as

    +

    Many of the styles have helper commands in the form \glsxtr...name and +\glsxtr...sort that are expanded within the name and sort fields when the +abbreviation is defined. These commands may use the helper token registers available +within \newabbreviation, such as \glsshorttok. The contents of a register can be +accessed with \theregister⟩. It’s essential that these expand when the abbreviation is +defined so don’t hide them behind no-expandable content if you redefine these helper +commands. +

    The parenthetical styles, such as long-short, use -


    \glsxtrparen  , use +


    \glsxtrparen{text}

    -

    +

    to set the parenthetical material. This just puts parentheses around the text: (⟨text⟩). -

    The basic abbreviation styles, such as

    The basic abbreviation styles, such as long-short and and short-long use -


    \glsabbrvdefaultfont  use +


    \glsabbrvdefaultfont{text}

    -

    + + + +

    for the short form. This just does ⟨text⟩ by default. (That is, no font change is applied.) On first use, -


    \glsfirstabbrvdefaultfont 


    \glsfirstabbrvdefaultfont{text}

    -

    +

    is used instead. By default, this just does \glsabbrvdefaultfont. The long form is formatted according to -


    \glslongdefaultfont 


    \glslongdefaultfont{text}

    - - - -

    +

    which again just does ⟨text⟩ (no font change). On first use, -


    \glsfirstlongdefaultfont 


    \glsfirstlongdefaultfont{text}

    -

    +

    is used instead. This just does \glslongdefaultfont. The plural suffix used for the short form is given by -


    \glsxtrabbrvpluralsuffix 


    \glsxtrabbrvpluralsuffix

    -

    +

    which defaults to \glspluralsuffix. -

    The small-cap styles, such as . +

    The small-cap styles, such as long-short-sc and and short-sc-long, use -


    \glsabbrvscfont  , use +


    \glsabbrvscfont{text}

    -

    +

    which uses \textsc.3.1 +href="#fn1x4" id="fn1x4-bk">4.1 On first use -


    \glsabbrvdefaultfont 


    \glsfirstabbrvscfont{text}

    -

    +

    is used instead. This uses \glsabbrvscfont by default. So redefine, \glsabbrvscfont to change first and subsequent uses or \glsfirstabbrvscfont to change just the first use. -

    The long form for the small-cap styles uses

    The long form for the small-cap styles uses \glslongdefaultfont or \glsfirstlongdefaultfont, as with the basic style. The suffix is given by -


    \glsxtrscsuffix 


    \glsxtrscsuffix

    -

    +

    This is defined as

    -
    +
    \newcommand*{\glsxtrscsuffix}{\glstextup{\glsxtrabbrvpluralsuffix}}
    -

    The

    The \glstextup command is provided by command is provided by glossaries and is used to switch off the small caps font for the suffix. If you override the default short plural using the shortplural key when you define the abbreviation you will need to make the + id="dx1-28046"> key when you define the abbreviation you will need to make the appropriate adjustment if necessary. (Remember that the default plural suffix behaviour can be modified through the use of the aposplural and and noshortplural + id="dx1-28048"> attributes. See §5 §6 Categories for further details.) -

    The small styles, such as

    The small styles, such as long-short-sm and and short-sm-long, use -


    \glsabbrvsmfont  , use +


    \glsabbrvsmfont{text}

    -

    +

    which uses \textsmaller. (This requires the relsizes package, which isn’t loaded by + id="dx1-28052"> package, which isn’t loaded by glossaries-extra, so must be loaded explicitly.) On first use -


    \glsfirstabbrvsmfont 


    \glsfirstabbrvsmfont{text}

    -

    +

    is used instead. This uses \glsabbrvsmfont by default. -

    The long form for the smaller styles uses

    The long form for the smaller styles uses \glslongdefaultfont or \glsfirstlongdefaultfont, as with the basic style. The suffix is given by -


    \glsxtrsmsuffix 


    \glsxtrsmsuffix

    -

    +

    which defaults to just \glsxtrabbrvpluralsuffix. -

    The “short-em” (emphasize short) styles, such as

    The “short-em” (emphasize short) styles, such as long-short-em or or short-em-long, + id="dx1-28056">, use -


    \glsabbrvemfont 


    \glsabbrvemfont{text}

    -

    +

    On first use -


    \glsfirstabbrvemfont 


    \glsfirstabbrvemfont{text}

    -

    +

    is used instead. This uses \glsabbrvemfont by default. The suffix is given by -


    \glsxtremsuffix 


    \glsxtremsuffix

    -

    +

    which defaults to just \glsxtrabbrvpluralsuffix. The long form is as for the basic style unless the style is a “long-em” style. -

    The “long-em” (emphasize long) styles, such as

    The “long-em” (emphasize long) styles, such as long-em-short-em or or short-em-long-em, + id="dx1-28061">, use -


    \glsfirstlongemfont 


    \glsfirstlongemfont{long-form}

    -

    +

    instead of \glsfirstlongdefaultfont{long-form} and -


    \glslongemfont 


    \glslongemfont{long-form}

    -

    +

    instead of \glslongdefaultfont{long-form}. The first form \glsfirstlongemfont is initialised to use \glslongemfont. -

    The user styles have similar commands: -


    \glsabbrvuserfont 

    The user styles have similar commands: +


    \glsabbrvuserfont{text}

    -

    +

    for the short form, -


    \glsfirstabbrvuserfont 


    \glsfirstabbrvuserfont{text}

    -

    +

    for the first use short form, -


    \glslonguserfont 


    \glslonguserfont{text}

    -

    +

    for the long form, -


    \glsfirstlonguserfont 


    \glsfirstlonguserfont{text}

    -

    +

    for the first use long form, and -


    \glsxtrusersuffix 


    \glsxtrusersuffix

    -

    +

    for the short plural suffix. -

    Similarly for the hyphen styles: -


    \glsabbrvhyphenfont 

    Similarly for the hyphen styles: +


    \glsabbrvhyphenfont{text}

    -

    +

    for the short form, -


    \glsfirstabbrvhyphenfont 


    \glsfirstabbrvhyphenfont{text}

    -

    +

    for the first use short form, -


    \glslonghyphenfont 


    \glslonghyphenfont{text}

    -

    +

    for the long form, -


    \glsfirstlonghyphenfont 


    \glsfirstlonghyphenfont{text}

    -

    +

    for the first use long form, and -


    \glsxtrhyphensuffix 


    \glsxtrhyphensuffix

    -

    +

    for the short plural suffix. -

    Similarly for the “only” styles, such as

    Similarly for the “only” styles, such as long-only-short-only: -


    \glsabbrvonlyfont  : +


    \glsabbrvonlyfont{text}

    -

    +

    for the short form, -


    \glsfirstabbrvonlyfont 


    \glsfirstabbrvonlyfont{text}

    -

    +

    for the first use short form, -


    \glslongonlyfont 


    \glslongonlyfont{text}

    -

    +

    for the long form, -


    \glsfirstlongonlyfont 


    \glsfirstlongonlyfont{text}

    -

    +

    for the first use long form, and -


    \glsxtronlysuffix 


    \glsxtronlysuffix

    -

    +

    for the short plural suffix. -

    Note that by default inserted material (provided in the final optional argument of +

    Note that by default inserted material (provided in the final optional argument of commands like \gls), is placed outside the font command in the predefined styles. To move it inside, use: -


    \glsxtrinsertinsidetrue 


    \glsxtrinsertinsidetrue

    -

    +

    This applies to all the predefined styles. For example:

    -
    +
    \setabbreviationstyle{long-short}  
    \renewcommand*{\glsfirstlongdefaultfont}[1]{\emph{#1}}  
    \glsxtrinsertinsidetrue
    -

    This will make the long form and the inserted text emphasized, whereas the default +

    This will make the long form and the inserted text emphasized, whereas the default (without \glsxtrinsertinsidetrue) would place the inserted text outside of the emphasized font. -

    Note that for some styles, such as the

    Note that for some styles, such as the short-long, the inserted text would be + id="dx1-28081">, the inserted text would be placed inside the font command for the short form (rather than the long form in the above example). -

    Remember that

    Remember that \textsc renders lowercase letters as small capitals. Uppercase letters are rendered as normal uppercase letters, so if you specify the short form in @@ -10950,49 +10599,47 @@ convert its argument to lowercase. For example:

    -
    +
    \renewcommand*{\glsabbrvscfont}[1]{\textsc{\MakeLowercase{#1}}}
    -

    -

    If you want to easily switch between the “sc” and “sm” styles, you may find it +

    +

    If you want to easily switch between the “sc” and “sm” styles, you may find it easier to redefine this command to convert case:

    -
    +
    \renewcommand*{\glsabbrvscfont}[1]{\textsc{\MakeTextLowercase{#1}}}  
    \renewcommand*{\glsabbrvsmfont}[1]{\textsmaller{\MakeTextUppercase{#1}}}
    -

    -

    Some of the styles use -


    \glsxtrfullsep 

    +

    Some of the styles use +


    \glsxtrfullsep{label}

    -

    +

    as a separator between the long and short forms. This is defined as a space by default, but may be changed as required. For example:

    -
    +
    \renewcommand*{\glsxtrfullsep}[1]{~}
    -

    or +

    or

    -
    +
    \renewcommand*{\glsxtrfullsep}[1]{\glsacspace{#1}}
    -

    -

    The new naming scheme for abbreviation styles is as follows:

    +

    +

    The new naming scheme for abbreviation styles is as follows:

    • field1⟩[field2⟩[-modifier2⟩][-user] -

      This is for the parenthetical styles. The

      This is for the parenthetical styles. The -modifier⟩ parts may be omitted. These styles display ⟨field1⟩ or ⟨field2⟩ starts with “no” then that element is omitted from the display style (no parenthetical part) but is included in the inline style. -

      If the

      If the -modifier⟩ part is present, then the field has a font changing command applied to it. The special modifier -only indicates that field is only present according to whether or not the entry has been used. -

      If

      If post is present then ⟨field2⟩ is placed after the link-text using the post-link hook. -

      If the

      If the -user part is present, then the user1 value, if provided, is inserted + id="dx1-28084"> value, if provided, is inserted into the parenthetical material . (The field used for the inserted material may be changed.) -

      Examples:

      +

      Examples:

      • long-noshort-sc: ⟨: ⟨field1⟩ is the long form, the short form is set in smallcaps but omitted in the display style.
      • long-em-short-em: both the long form and the short form are + id="dx1-28086">: both the long form and the short form are emphasized. The short form is in parentheses.
      • long-short-em: the short form is emphasized but not the long form. + id="dx1-28087">: the short form is emphasized but not the long form. The short form is in parentheses.
      • long-short-user: if the : if the user1 key has been set, this produces the style + id="dx1-28089"> key has been set, this produces the style ⟨long⟩ (⟨short⟩, ⟨short⟩).
      • long-hyphen-postshort-hyphen: the short form and the inserted + id="dx1-28090">: the short form and the inserted material (provided by the final optional argument of commands like \gls) is moved to the post-link hook. The long form is formatted @@ -11087,31 +10734,31 @@ class="cmtt-10">\glsfirstabbrvhyphenfont on first
      • style-noreg -

        Some styles set the

        Some styles set the regular attribute. In some cases, there’s a version of the + id="dx1-28091"> attribute. In some cases, there’s a version of the style that doesn’t set this attribute. For example, long-em-noshort-em sets the + id="dx1-28092"> sets the regular attribute. The attribute. The long-em-noshort-em-noreg style is a minor variation that + id="dx1-28094"> style is a minor variation that style that doesn’t set the attribute. -

        There are a few “noshort” styles, such as

        There are a few “noshort” styles, such as long-hyphen-noshort-noreg, that have + id="dx1-28095">, that have “-noreg” version without a regular version. This is because the style won’t work properly with the regular set, but the naming scheme is maintained for + id="dx1-28096"> set, but the naming scheme is maintained for consistency with the other “noshort” styles.

      • modifier1⟩]-[post]footnote -

        The display style uses ⟨

        The display style uses ⟨field1⟩ followed by a footnote with the other field in it. If post is present then the footnote is placed after the link-text using the post-link hook. The inline style does ⟨field1⟩ followed by the other field in parentheses. -

        If

        If -modifier1⟩ is present, ⟨field1⟩ has a font-changing command applied to it. -

        Examples:

        +

        Examples:

        • short-footnote: short form in the text with the long form in the + id="dx1-28098">: short form in the text with the long form in the footnote.
        • short-sc-postfootnote: short form in smallcaps with the long form in + id="dx1-28099">: short form in smallcaps with the long form in the footnote outside of the link-text.
        -

        Take care with the footnote styles. Remember that there are some situations + id="dx1-28100">link-text.
      +

      Take care with the footnote styles. Remember that there are some situations where \footnote doesn’t work.
      -

      + id="dx1-28101"> doesn’t work.

    +

  • style-desc -

    Like ⟨

    Like ⟨style⟩ but the description key must be provided when defining abbreviations + id="dx1-28102"> key must be provided when defining abbreviations with this style. -

    Examples:

    +

    Examples:

  • -

    Not all combinations that fit the above syntax are provided. Pre-version 1.04 +

    Not all combinations that fit the above syntax are provided. Pre-version 1.04 styles that didn’t fit this naming scheme are either provided with a synonym (where the former name wasn’t ambiguous) or provided with a deprecated synonym (where the former name was confusing). The deprecated style names generate a warning using: -


    \GlsXtrWarnDeprecatedAbbrStyle  \GlsXtrWarnDeprecatedAbbrStyle -{


    \GlsXtrWarnDeprecatedAbbrStyle{old-name}{new-name}

    -

    +

    where ⟨old-name⟩ is the deprecated name and ⟨new-name⟩ is the preferred name. You can suppress these warnings by redefining this command to do nothing. -

    +

    -

    Top

    3.4.1

    Top

    4.4.1 Predefined Abbreviation Styles that Set the Regular Attribute

    -

    The following abbreviation styles set the

    The following abbreviation styles set the regular attribute to “true” for all categories + id="dx1-29001"> attribute to “true” for all categories that have abbreviations defined with any of these styles.

    short-nolong
    This only displays the short form on first use. The name is set to the + id="dx1-29004"> is set to the short form through the command -


    \glsxtrshortnolongname 


    \glsxtrshortnolongname

    -

    +

    (Similarly for the other shortmodifier\newacronym) for it to take effect. Make sure to \protect any formatting commands (or anything else that shouldn’t be expanded). -

    The

    The description is set to the long form. The inline full form displays ⟨ is set to the long form. The inline full form displays ⟨short⟩ (⟨long⟩). The long form on its own can be displayed through commands like \glsxtrlong. + id="dx1-29007">.

    short
    A synonym for short-nolong. + id="dx1-29009">.
    nolong-short
    Like short-nolong but the inline full form displays ⟨ but the inline full form displays ⟨long⟩ (⟨short⟩).
    short-sc-nolong
    Like short-nolong but redefines but redefines \glsabbrvfont to use \glsabbrvscfont (which defaults to (which defaults to \textsc).
    short-sc
    A synonym for short-sc-nolong + id="dx1-29016"> @@ -11304,11 +10945,11 @@ class="cmss-10">short-sc-nolongnolong-short-sc
    Like short-sc-nolong but the inline full form displays ⟨ but the inline full form displays ⟨long⟩ (⟨short⟩). The name is still obtained from modifier⟩ unless indicated short-sm-nolong
    Like short-nolong but redefines but redefines \glsabbrvfont to use \glsabbrvsmfont (which defaults to (which defaults to \textsmaller).
    short-sm
    A synonym for short-sm-nolong. + id="dx1-29023">.
    nolong-short-sm
    Like short-sm-nolong but the inline full form displays ⟨ but the inline full form displays ⟨long⟩ (⟨short⟩). @@ -11358,33 +10999,33 @@ class="cmti-10">short⟩). short-em-nolong
    Like short-nolong but redefines but redefines \glsabbrvfont to use \glsabbrvemfont. + id="dx1-29028">.
    short-em
    A synonym for short-em-nolong + id="dx1-29030">
    nolong-short-em
    Like short-em-nolong but the inline full form displays ⟨ but the inline full form displays ⟨long⟩ (⟨short⟩). @@ -11392,20 +11033,18 @@ class="cmti-10">short⟩). short-nolong-desc
    Like the short-nolong style, but the style, but the name is set to the full form + id="dx1-29035"> is set to the full form obtained by expanding -


    \glsxtrshortdescname 


    \glsxtrshortdescname

    -

    +

    (Similarly for the other shortmodifier\protect fragile and formatting commands and only redefin before \newabbreviation (or \newacronym). -

    The

    The description must be supplied by the user. You may prefer to use + id="dx1-29037"> must be supplied by the user. You may prefer to use the short-nolong style with the post-description hook set to display + id="dx1-29038"> style with the post-description hook set to display the long form and override the description key. (See the sample file + id="dx1-29039"> key. (See the sample file sample-acronym-desc.tex.)

    short-desc
    A synonym for short-nolong-desc. + id="dx1-29041">.
    short-sc-nolong-desc
    Like short-nolong but redefines but redefines \glsabbrvfont to use \glsabbrvscfont (which defaults to (which defaults to \textsc). @@ -11460,83 +11099,81 @@ class="cmtt-10">\textsc). short-sc-desc
    A synonym for short-sc-nolong-desc. + id="dx1-29046">.
    short-sm-nolong-desc
    Like short-nolong-desc but redefines but redefines \glsabbrvfont to use \glsabbrvsmfont (which defaults to (which defaults to \textsmaller).
    short-sm-desc
    A synonym for short-sm-nolong-desc. + id="dx1-29051">.
    short-em-nolong-desc
    Like short-nolong-desc but redefines but redefines \glsabbrvfont to use \glsabbrvemfont. + id="dx1-29054">.
    short-em-desc
    A synonym for short-em-nolong-desc. + id="dx1-29056">.
    long-noshort-desc
    This style only displays the long form, regardless of first or subsequent use of commands \gls. The short form may be accessed + id="dx1-29058">. The short form may be accessed through commands like \glsxtrshort. The inline full form displays ⟨. The inline full form displays ⟨long⟩ (⟨short⟩). -

    The

    The sort key are set to the long form. The key are set to the long form. The name key is also set to the long form, + id="dx1-29061"> key is also set to the long form, but this is done by expanding -


    \glsxtrlongnoshortdescname 


    \glsxtrlongnoshortdescname

    -

    +

    (Similarly for the other longmodifier-desc styles, unless indicated otherwise.) This command should only be redefined before abbreviations are defined, and any fragile or formatting commands within it need protecting. -

    The

    The description must be provided by the user. The predefined glossary styles + id="dx1-29063"> must be provided by the user. The predefined glossary styles won’t display the short form. You can use the post-description hook to automatically append the short form to the description. The inline full form will display ⟨short⟩). long-desc

    A synonym for long-noshort-desc. + id="dx1-29065">.
    long-noshort-sc-desc
    Like the long-noshort-desc style but the short form (accessed + id="dx1-29067"> style but the short form (accessed through commands like \glsxtrshort) use ) use \glsabbrvscfont. (This style was + id="dx1-29069">. (This style was originally called long-desc-sc. Renamed in version 1.04, but original name + id="dx1-29070">. Renamed in version 1.04, but original name retained as a deprecated synonym for backward-compatibility.)
    long-noshort-sm-desc
    Like long-noshort-desc but redefines but redefines \glsabbrvfont to use \glsabbrvsmfont. (This style was originally called . (This style was originally called long-desc-sm. Renamed in + id="dx1-29074">. Renamed in version 1.04, but original name retained as a deprecated synonym for backward-compatibility.) @@ -11605,60 +11242,58 @@ class="cmss-10">long-desc-smlong-noshort-em-desc
    Like long-noshort-desc but redefines but redefines \glsabbrvfont to use \glsabbrvemfont. The long form isn’t emphasized. (This style was originally + id="dx1-29077">. The long form isn’t emphasized. (This style was originally called long-desc-em. Renamed in version 1.04, but original name retained as a + id="dx1-29078">. Renamed in version 1.04, but original name retained as a deprecated synonym for backward-compatibility.)
    long-em-noshort-em-desc
    New to version 1.04, like long-noshort-desc but + id="dx1-29080"> but redefines \glsabbrvfont to use \glsabbrvemfont. The long form uses + id="dx1-29081">. The long form uses \glsfirstlongemfont and and \glslongemfont. + id="dx1-29083">.
    long-noshort
    This style doesn’t really make sense if you don’t use the short form anywhere in the document, but is provided for completeness. This is like the long-noshort-desc style, but the style, but the sort key is set to the short + id="dx1-29086"> key is set to the short form. The name key is also set to the short form, but this is done by + id="dx1-29087"> key is also set to the short form, but this is done by expanding -


    \glsxtrlongnoshortname 


    \glsxtrlongnoshortname

    -

    +

    (Similarly for other longmodifier-noshortmodifier⟩ styles, unless indicated otherwise.) This command should only be redefined before abbreviations are defined, and fragile or formatting commands should be protected. -

    The

    The description is set to the long form. + id="dx1-29089"> is set to the long form.

    long
    A synonym for long-noshort + id="dx1-29091">
    long-noshort-sc
    Like the long-noshort style but the short form (accessed through + id="dx1-29093"> style but the short form (accessed through commands like \glsxtrshort) use ) use \glsabbrvscfont. (This style was originally + id="dx1-29095">. (This style was originally called long-sc. Renamed in version 1.04, but original name retained as a + id="dx1-29096">. Renamed in version 1.04, but original name retained as a deprecated synonym for backward-compatibility.)
    long-noshort-sm
    Like long-noshort but redefines but redefines \glsabbrvfont to use \glsabbrvsmfont. (This style was originally called . (This style was originally called long-sm. Renamed in + id="dx1-29100">. Renamed in version 1.04, but original name retained as a deprecated synonym for backward-compatibility.)
    long-noshort-em
    This style is like long-noshort but redefines but redefines \glsabbrvfont to use \glsabbrvemfont. The long form isn’t emphasized. (This style was originally + id="dx1-29103">. The long form isn’t emphasized. (This style was originally called long-em. Renamed in version 1.04, but original name retained as a + id="dx1-29104">. Renamed in version 1.04, but original name retained as a deprecated synonym for backward-compatibility.)
    long-em-noshort-em
    New to version 1.04, this style is like long-noshort but redefines + id="dx1-29106"> but redefines \glsabbrvfont to use \glsabbrvemfont, , \glsfirstlongfont to use \glsfirstlongemfont and \glslongfont to use \glslongemfont. The short form isn’t used by commands like \gls, but can be obtained using + id="dx1-29108">, but can be obtained using \glsxtrshort. The related style . The related style long-em-noshort-em-noreg doesn’t set the + id="dx1-29110"> doesn’t set the regular attribute. + id="dx1-29111"> attribute.
    -

    +

    -

    Top

    3.4.2

    Top

    4.4.2 Predefined Abbreviation Styles that Don’t Set the Regular Attribute

    -

    The following abbreviation styles will set the

    The following abbreviation styles will set the regular attribute to “false” if it has + id="dx1-30001"> attribute to “false” if it has previously been set. If it hasn’t already been set, it’s left unset. Other attributes may also be set, depending on the style.

    long-short
    On first use, this style uses the format ⟨long⟩ (⟨short⟩). The inline and display full forms are the same. The sort key is set to the short form. The key is set to the short form. The name + id="dx1-30005"> is also set to the short form through -


    \glsxtrlongshortname 


    \glsxtrlongshortname

    -

    +

    (Similarly for other longmodifiermodifier⟩ styles, unless indicated class="cmtt-10">\the\glslongtok and the short form can be referenced with \the\glsshorttok. -

    The

    The description is set to the long form. The long and short forms are separated + id="dx1-30007"> is set to the long form. The long and short forms are separated by \glsxtrfullsep. If you want to insert material within the parentheses (such as a translation), try the long-short-user style. + id="dx1-30008"> style.

    long-short-sc
    Like long-short but redefines but redefines \glsabbrvfont to use \glsabbrvscfont. + id="dx1-30011">.
    long-short-sm
    Like long-short but redefines but redefines \glsabbrvfont to use \glsabbrvsmfont. + id="dx1-30014">.
    long-short-em
    Like long-short but redefines but redefines \glsabbrvfont to use \glsabbrvemfont. + id="dx1-30017">.
    long-em-short-em
    New to version 1.04, this style is like long-short-em but redefines + id="dx1-30019"> but redefines \glsfirstlongfont to use \glsfirstlongemfont. + id="dx1-30020">. @@ -11875,20 +11508,18 @@ class="cmtt-10">\glsfirstlongemfontlong-only-short-only
    New to version 1.17, this style only shows the long form on first use and only shows the short form on subsequent use. The inline full form \glsxtrfull shows the long form followed by the short form in parentheses. The name field is obtained from -


    \glsxtronlyname  field is obtained from +


    \glsxtronlyname

    -

    +

    Any redefinition of this command must come before the abbreviations are defined as it expands on definition. Make sure you protect any commands that shouldn’t be expanded. The long form can be referenced @@ -11900,21 +11531,19 @@ class="cmtt-10">\the\glsshorttok. long-only-short-only-desc

    New to version 1.17, this style is like long-only-short-only + id="dx1-30025"> but the user must supply the description. The name field is obtained + id="dx1-30026"> field is obtained from -


    \glsxtronlydescname 


    \glsxtronlydescname

    -

    +

    Any redefinition of this command must come before the abbreviations are defined as it expands on definition. Make sure you protect any commands that shouldn’t be expanded. The long form can be referenced @@ -11926,41 +11555,39 @@ class="cmtt-10">\the\glsshorttok. long-em-noshort-em-noreg

    New to version 1.17, this style is like long-em-noshort-em + id="dx1-30029"> but doesn’t set the regular attribute. + id="dx1-30030"> attribute.
    long-short-user
    This style was introduced in version 1.04. It’s like the long-short style + id="dx1-30032"> style but additional information can be inserted into the parenthetical material. This checks the value of the field given by -


    \glsxtruserfield 


    \glsxtruserfield

    -

    +

    (which defaults to useri) using \ifglshasfield (provided by (provided by glossaries). If the field hasn’t been set, the style behaves like the long-short style and produces + id="dx1-30035"> style and produces ⟨long⟩ (⟨short⟩) but if the field has been set, the contents of that field are inserted @@ -11969,53 +11596,49 @@ class="cmti-10">long⟩ (⟨short⟩, ⟨field-value⟩). The format is governed by -


    \glsxtruserparen 


    \glsxtruserparen{text}{label}

    -

    +

    where ⟨text⟩ is the short form (for the long-short-user style) or the long form (for + id="dx1-30037"> style) or the long form (for the short-long-user style). This command first inserts a space using + id="dx1-30038"> style). This command first inserts a space using \glsxtrfullsep and then the parenthetical content (using \glsxtrparen). + id="dx1-30039">). The description is set to -


    \glsuserdescription  is set to +


    \glsuserdescription{long}{label}

    -

    +

    The default definition ignores the ⟨label⟩ and encapsulates ⟨long⟩ with \glslonguserfont. -

    The

    The name is obtained by expanding is obtained by expanding \glsxtrlongshortname (see above). The ⟨text⟩ argument includes the font formatting command, short} in the case of the long-short-user style and style and \glsfirstlongfont{long} in the case of the short-long-user style. -

    For example: + id="dx1-30044"> style. +

    For example:

    -
    +
    \setabbreviationstyle[acronym]{long-short-user}  
    \newacronym{tug}{TUG}{\TeX\ User Group}  
    \newacronym  
     [user1={German Speaking \TeX\ User Group}]  
     {dante}{DANTE}{Deutschsprachige Anwendervereinigung \TeX\ e.V}
    -

    On first use,

    On first use, \gls{tug} will appear as:

    -

    T

    TEX User Group (TUG)

    -

    whereas

    whereas \gls{dante} will appear as:

    -

    Deutschsprachige Anwendervereinigung T

    Deutschsprachige Anwendervereinigung TEX e.V (DANTE, German Speaking TEX User Group)

    -

    The short form is formatted according to -


    \glsabbrvuserfont 

    The short form is formatted according to +


    \glsabbrvuserfont{text}

    -

    +

    and the plural suffix is given by -


    \glsxtrusersuffix 


    \glsxtrusersuffix

    -

    -

    These may be redefined as appropriate. For example, if you want a smallcaps +

    +

    These may be redefined as appropriate. For example, if you want a smallcaps style, you can just set these commands to those used by the long-short-sc + id="dx1-30047"> style:

    -
    +
    \renewcommand{\glsabbruserfont}[1]{\glsabbrvscfont{#1}}  
    \renewcommand{\glsxtrusersuffix}{\glsxtrscsuffix}
    -

    +

    long-noshort-noreg
    This style is like long-noshort but it doesn’t set the but it doesn’t set the regular + id="dx1-30050"> attribute.
    long-noshort-desc-noreg
    This style is like long-noshort-desc but it doesn’t set the + id="dx1-30052"> but it doesn’t set the regular attribute. + id="dx1-30053"> attribute.
    long-short-desc
    On first use, this style uses the format ⟨long⟩ (⟨short⟩). The inline and display full forms are the same. The name is set to the full + id="dx1-30056"> is set to the full form. The sort key is set to ⟨ key is set to ⟨long⟩ (⟨short⟩). Before version 1.04, this was incorrectly set to the short form. If you want to revert back to this you can redefine -


    \glsxtrlongshortdescsort 


    \glsxtrlongshortdescsort

    -

    +

    For example:

    -
    +
    \renewcommand*{\glsxtrlongshortdescsort}{\the\glsshorttok}
    -

    The

    The description must be supplied by the user. The long and short + id="dx1-30059"> must be supplied by the user. The long and short forms are separated by \glsxtrfullsep. The name field is obtained + id="dx1-30060"> field is obtained from -


    \glsxtrlongshortdescname 


    \glsxtrlongshortdescname

    -

    +

    (Similarly for other longmodifier\the\glsshorttok. long-short-sc-desc

    Like long-short-desc but redefines but redefines \glsabbrvfont to use \glsabbrvscfont. + id="dx1-30064">.
    long-short-sm-desc
    Like long-short-desc but redefines but redefines \glsabbrvfont to use \glsabbrvsmfont. + id="dx1-30067">.
    long-short-em-desc
    Like long-short-desc but redefines but redefines \glsabbrvfont to use \glsabbrvemfont. + id="dx1-30070">.
    long-em-short-em-desc
    New to version 1.04, this style is like long-short-em-desc but + id="dx1-30072"> but redefines \glsfirstlongfont to use \glsfirstlongemfont. + id="dx1-30073">.
    long-em-noshort-em-desc-noreg
    New to version 1.17, this style is like long-em-noshort-em-desc but doesn’t set the but doesn’t set the regular attribute. + id="dx1-30076"> attribute.
    long-short-user-desc
    New to version 1.04, this style is like a cross between the long-short-desc style and the style and the long-short-user style. The display and + id="dx1-30079"> style. The display and inline forms are as for long-short-user and the and the name key is obtained + id="dx1-30081"> key is obtained from -


    \glsxtrlongshortuserdescname 


    \glsxtrlongshortuserdescname

    -

    +

    Again, this should only be redefined before \newabbreviation (or \newacronym), and fragile and formatting commands need protecting. -

    The

    The description key must be supplied in the optional argument of + id="dx1-30083"> key must be supplied in the optional argument of \newabbreviation (or \newacronym). The sort key is set to ⟨ key is set to ⟨long⟩ (⟨short⟩) as per the long-short-desc style. + id="dx1-30085"> style.

    short-nolong-noreg
    This is like short-nolong but doesn’t set the but doesn’t set the regular attribute. + id="dx1-30088"> attribute.
    nolong-short-noreg
    This is like nolong-short but doesn’t set the but doesn’t set the regular attribute. + id="dx1-30091"> attribute.
    short-long
    On first use, this style uses the format ⟨short⟩ (⟨long⟩). The inline and display full forms are the same. The name and and sort keys are set to the + id="dx1-30095"> keys are set to the short form. The description is set to the long form. The short and long + id="dx1-30096"> is set to the long form. The short and long forms are separated by \glsxtrfullsep. If you want to insert material within the parentheses (such as a translation), try the short-long-user + id="dx1-30097"> style. -

    The

    The name field is obtained from -


    \glsxtrshortlongname  field is obtained from +


    \glsxtrshortlongname

    -

    +

    (Similarly for other shortmodifier\the\glsshorttok. short-sc-long

    Like short-long but redefines but redefines \glsabbrvfont to use \glsabbrvscfont. + id="dx1-30102">.
    short-sm-long
    Like short-long but redefines but redefines \glsabbrvfont to use \glsabbrvsmfont. + id="dx1-30105">.
    short-em-long
    Like short-long but redefines but redefines \glsabbrvfont to use \glsabbrvemfont. + id="dx1-30108">.
    short-em-long-em
    New to version 1.04, this style is like short-em-long but redefines + id="dx1-30110"> but redefines \glsfirstlongfont to use \glsfirstlongemfont. + id="dx1-30111">.
    short-long-user
    New to version 1.04. This style is like the long-short-user style but + id="dx1-30113"> style but with the long and short forms switched. The parenthetical material is governed by the same command \glsxtruserparen, but the first argument supplied to it + id="dx1-30114">, but the first argument supplied to it is the long form instead of the short form. The name field is obtained by + id="dx1-30115"> field is obtained by expanding -


    \glsxtrshortlongname 


    \glsxtrshortlongname

    -

    +

    Again, this should only be redefined before \newabbreviation (or \newacronym) and commands that should be expanded need to be protected. The description is set to is set to \glsuserdescription{long}{}. short-nolong-desc-noreg

    This style is like short-nolong-desc but it doesn’t set the + id="dx1-30119"> but it doesn’t set the regular attribute. + id="dx1-30120"> attribute.
    short-long-desc
    On first use, this style uses the format ⟨short⟩ (⟨long⟩). The inline and display full forms are the same. The name is set to the full + id="dx1-30123"> is set to the full form. The description must be supplied by the user. The short and long + id="dx1-30124"> must be supplied by the user. The short and long forms are separated by \glsxtrfullsep. The name field is obtained + id="dx1-30125"> field is obtained from -


    \glsxtrshortlongdescname 


    \glsxtrshortlongdescname

    -

    +

    (Similarly for other shortmodifier\the\glsshorttok. short-sc-long-desc

    Like short-long-desc but redefines but redefines \glsabbrvfont to use \glsabbrvscfont. + id="dx1-30129">.
    short-sm-long-desc
    Like short-long-desc but redefines but redefines \glsabbrvfont to use \glsabbrvsmfont. + id="dx1-30132">.
    short-em-long-desc
    Like short-long-desc but redefines but redefines \glsabbrvfont to use \glsabbrvemfont. + id="dx1-30135">.
    short-em-long-em-desc
    New to version 1.04, this style is like short-em-long-desc but + id="dx1-30137"> but redefines \glsfirstlongfont to use \glsfirstlongemfont. + id="dx1-30138">.
    short-long-user-desc
    New to version 1.04, this style is like a cross between the short-long-desc style and the style and the short-long-user style. The display and + id="dx1-30141"> style. The display and inline forms are as for short-long-user, but the , but the name key is obtained + id="dx1-30143"> key is obtained from -


    \glsxtrshortlonguserdescname 


    \glsxtrshortlonguserdescname

    -

    +

    Again, this should only be redefined before \newabbreviation (or \newacronym), and fragile and formatting commands need protecting. -

    The

    The description key must be supplied in the optional argument of + id="dx1-30145"> key must be supplied in the optional argument of \newabbreviation (or \newacronym). @@ -12593,36 +12198,34 @@ class="cmtt-10">\newacronym). short-footnote

    On first use, this style displays the short form with the long form as a footnote. This style automatically sets the nohyperfirst attribute to “true” for + id="dx1-30148"> attribute to “true” for the supplied category, so the first use won’t be hyperlinked (but the footnote + id="dx1-30149">first use won’t be hyperlinked (but the footnote marker may be, if the hyperref package is used). -

    The inline full form uses the ⟨ package is used). +

    The inline full form uses the ⟨short⟩ (⟨long⟩) style. The name is set to the short + id="dx1-30151"> is set to the short form. The description is set to the long form. The is set to the long form. The name key is obtained by - expanding -


    \glsxtrfootnotename  key is obtained by + expanding: +


    \glsxtrfootnotename

    -

    +

    (Similarly for other shortmodifierfootnote styles, unless class="cmtt-10">\newabbreviation (or \newacronym), and fragile or formatting commands should be protected from expansion. -

    As from version 1.05, all the footnote styles use: -


    \glsfirstlongfootnotefont 

    As from version 1.05, all the footnote styles use: +


    \glsfirstlongfootnotefont{text} -

    -

    +class="cmtt-10">}


    +

    to format the long form on first use or for the full form and -


    \glslongfootnotefont  first use or for the full form and +


    \glslongfootnotefont{text}

    -

    +

    to format the long form elsewhere (for example, when used with \glsxtrlong). -

    As from version 1.07, all the footnote styles use: -


    \glsxtrabbrvfootnote 

    As from version 1.07, all the footnote styles use: +


    \glsxtrabbrvfootnote{label}{long}

    -

    +

    By default, this just does \footnote{long} (the first argument is ignored). For @@ -12679,282 +12275,438 @@ class="cmtt-10">} (the first argument is ignored). For

    -
    +
    \renewcommand{\glsxtrabbrvfootnote}[2]{%  
      \footnote{\glshyperlink[#2]{#1}}%  
    }
    -

    or to include the short form with a hyperlink: +

    or to include the short form with a hyperlink:

    -
    +
    \renewcommand{\glsxtrabbrvfootnote}[2]{%  
      \footnote{\glshyperlink[\glsfmtshort{#1}]{#1}: #2}%  
    }
    -

    Note that I haven’t used commands like

    Note that I haven’t used commands like \glsxtrshort to avoid interference (see §2.3 §2.4 Entry Display Style Modifications and §2.7 §2.8 Nested Links).

    footnote
    A synonym for short-footnote. + id="dx1-30161">.
    short-sc-footnote
    Like short-footnote but redefines but redefines \glsabbrvfont to use \glsabbrvscfont. (This style was originally called . (This style was originally called footnote-sc. Renamed in + id="dx1-30165">. Renamed in version 1.04, but original name retained as a deprecated synonym for backward-compatibility.)
    short-sc-footnote
    Like short-footnote but redefines but redefines \glsabbrvfont to use \glsabbrvsmfont. (This style was originally called . (This style was originally called footnote-sm. Renamed in + id="dx1-30169">. Renamed in version 1.04, but original name retained as a deprecated synonym for backward-compatibility.)
    short-em-footnote
    Like short-footnote but redefines but redefines \glsabbrvfont to use \glsabbrvemfont. (This style was originally called . (This style was originally called footnote-em. Renamed in + id="dx1-30173">. Renamed in version 1.04, but original name retained as a deprecated synonym for backward-compatibility.)
    +short-footnote-desc
    (New to v1.42.) This is similar to short-footnote, but the + description must be supplied by the user. The name field is obtained + from: +


    \glsxtrfootnotedescname

    +

    + which defaults to ⟨short⟩ followed by ⟨long⟩ in parentheses, and the sort field is + obtained from: +


    \glsxtrfootnotedescsort

    +

    + which defaults to just the short form. (Similarly for other + shortmodifier-[post]footnote-desc styles, unless indicated otherwise.) + + + +

    Any redefinition of these commands must come before the abbreviations + are defined as it expands on definition. Make sure you protect any + commands that shouldn’t be expanded. The long form can be referenced + with \the\glslongtok and the short form can be referenced with + \the\glsshorttok. +

    +footnote-desc
    A synonym for short-footnote-desc. +
    +short-sc-footnote-desc
    Like short-footnote-desc but redefines \glsabbrvfont to use + \glsabbrvscfont. +
    +short-sm-footnote-desc
    Like short-footnote-desc but redefines \glsabbrvfont to use + \glsabbrvsmfont. +
    +short-em-footnote-desc
    Like short-footnote-desc but redefines \glsabbrvfont to use + \glsabbrvemfont. +
    short-postfootnote
    This is similar to the short-footnote style but doesn’t modify the + id="dx1-30193"> style but doesn’t modify the category attribute. Instead it changes \glsxtrpostlinkcategory to insert the + id="dx1-30194"> to insert the footnote after the link-text on first use. This will also defer the footnote until after any following punctuation character that’s recognised by \glsxtrifnextpunc. -

    The inline full form uses the ⟨. +

    The inline full form uses the ⟨short⟩ (⟨long⟩) style. The name is set to the short + id="dx1-30198"> is set to the short form. The description is set to the long form. Note that this style will change + id="dx1-30199"> is set to the long form. Note that this style will change \glsxtrfull (and its variants) so that it fakes non-first use. (Otherwise the + id="dx1-30200">first use. (Otherwise the footnote would appear after the inline form.)

    postfootnote
    A synonym for short-postfootnote. - - - + id="dx1-30202">.
    short-sc-postfootnote
    Like short-postfootnote but redefines but redefines \glsabbrvfont to use \glsabbrvscfont. (This style was originally called . (This style was originally called postfootnote-sc. Renamed in + id="dx1-30206">. Renamed in version 1.04, but original name retained as a deprecated synonym for backward-compatibility.)
    short-sm-postfootnote
    Like short-postfootnote but redefines but redefines \glsabbrvfont to use \glsabbrvsmfont. (This style was originally called . (This style was originally called postfootnote-sm. Renamed + id="dx1-30210">. Renamed in version 1.04, but original name retained as a deprecated synonym for backward-compatibility.) + + +
    short-em-postfootnote
    Like short-postfootnote but redefines but redefines \glsabbrvfont to use \glsabbrvemfont. (This style was originally called . (This style was originally called postfootnote-em. Renamed + id="dx1-30214">. Renamed in version 1.04, but original name retained as a deprecated synonym for backward-compatibility.)
    +short-postfootnote-desc
    (New to v1.42.) This is similar to short-postfootnote, but + the description must be supplied by the user. The name and sort are set as for + short-footnote-desc. +
    +postfootnote-desc
    A synonym for short-postfootnote-desc. +
    +short-sc-postfootnote-desc
    Like short-postfootnote-desc but redefines \glsabbrvfont + to use \glsabbrvscfont. +
    +short-sm-postfootnote-desc
    Like short-postfootnote-desc but redefines \glsabbrvfont + to use \glsabbrvsmfont. +
    +short-em-postfootnote-desc
    Like short-postfootnote-desc but redefines \glsabbrvfont + to use \glsabbrvemfont. +
    short-postlong-user
    This style was introduced in version 1.12. It’s like the short-long-user style but defers the parenthetical material to after the link-text. + id="dx1-30233"> style but defers the parenthetical material to after the link-text. This means that you don’t have such a long hyperlink (which can cause problems for the DVI LATEX format) and it also means that the user supplied material can include a hyperlink to another location. The name key is obtained + id="dx1-30234"> key is obtained from \glsxtrshortlongname.
    short-postlong-user-desc
    This style was introduced in version 1.12. It’s like the above short-postlong-user style but the style but the description must be specified. The must be specified. The name + id="dx1-30238"> is obtained from \glsxtrshortlonguserdescname.
    long-postshort-user
    This style was introduced in version 1.12. It’s like the above short-postlong-user style but the long form is shown first and + id="dx1-30240"> style but the long form is shown first and the short form is in the parenthetical material (as for long-short-user) + id="dx1-30241">) style.
    long-postshort-user-desc
    This style was introduced in version 1.12. It’s like the above long-postshort-user style but the style but the description must be specified. The must be specified. The name + id="dx1-30245"> is obtained from \glsxtrlongshortuserdescname. + + +
    long-hyphen-short-hyphen
    This style (new to v1.17) is designed to work with the markwords category attribute. The full form is formatted + id="dx1-30247"> category attribute. The full form is formatted using -


    \glsxtrlonghyphenshort 


    \glsxtrlonghyphenshort{label}{long}{short} - {}{insert}

    - - - -

    +

    where ⟨insert⟩ is the inserted material provided in the final optional argument of commands like \insert. If ⟨insert⟩ start with a hyphen, then this locally redefines \glsxtrwordsep to a hyphen, which means that if the to a hyphen, which means that if the markwords + id="dx1-30250"> attribute is set then the long form will become hyphenated. (If this attribute isn’t set, there’s no alteration to the way the long form is displayed.) The name + id="dx1-30251"> key is obtained from \glsxtrlongshortname. -

    Unlike the other ⟨

    Unlike the other ⟨long⟩ (⟨short⟩) type of styles, such as long-short, this style also + id="dx1-30252">, this style also repeats the insertion in the parenthetical part, so that the first use form is:

    -

    \glsfirstlonghyphenfont{long}\glsfirstabbrvhyphenfont{short}insert⟩)

    -

    The space before the parenthetical material is actually given by +

    The space before the parenthetical material is actually given by \glsxtrfullsep{labelinsert⟩ may be moved into the formatting commands according to the conditional \ifglsxtrinsertinside. -

    For example, if

    For example, if ip is defined using:

    -
    +
    \glssetcategoryattribute{english}{markwords}{true}  
    \setabbreviationstyle[english]{long-hyphen-short-hyphen}  
    \newabbreviation[category=english]{ip}{IP}{Internet Protocol}
    -

    then +

    then

    -
    +
    \gls{ip}[-Adressen]
    -

    will do +

    will do

    -

    Internet-Protocol-Adressen (IP-Adressen)

    -

    on first use, whereas +

    Internet-Protocol-Adressen (IP-Adressen)

    +

    on first use, whereas

    -
    +
    \gls{ip}[ Address]
    -

    will do +

    will do

    -

    Internet Protocol Address (IP Address)

    -

    on first use. -

    Note that the hyphenation isn’t applied when using commands like +

    Internet Protocol Address (IP Address)

    +

    on first use. +

    Note that the hyphenation isn’t applied when using commands like \glsxtrlong. This means that

    -
    +
    \glsxtrlong{ip}[-Adressen]
    -

    will do +

    will do

    -

    Internet Protocol-Adressen

    +

    Internet Protocol-Adressen

    -

    -

    If the

    +

    If the markwords attribute hadn’t been set, then the first use of + id="dx1-30253"> attribute hadn’t been set, then the first use of

    -
    +
    \gls{ip}[-Adressen]
    -

    would do +

    would do

    -

    Internet Protocol-Adressen (IP-Adressen)

    -

    instead. -

    If the inserted material ⟨

    Internet Protocol-Adressen (IP-Adressen)

    +

    instead. +

    If the inserted material ⟨insert⟩ is likely to contain commands like \gls, then use long-hyphen-postshort-hyphen instead to avoid nested links. + id="dx1-30254"> instead to avoid nested links.
    -

    -

    If you want the short version in small-caps, you can just redefine +

    +

    If you want the short version in small-caps, you can just redefine \glsabbrvhyphenfont and \glsxtrhyphensuffix to use the small-caps @@ -13082,65 +12834,65 @@ class="cmtt-10">\glsxtrhyphensuffix to use the small-caps

    -
    +
    \renewcommand{\glsabbrvhyphenfont}{\glsabbrvscfont}  
    \renewcommand{\glsxtrhyphensuffix}{\glsxtrscsuffix}
    -

    Similarly for other font-changing variations. +

    Similarly for other font-changing variations.

    long-hyphen-noshort-desc-noreg
    New to version 1.17, this style is like long-hyphen-short-hyphen-desc except that the parenthetical part is omitted and + id="dx1-30256"> except that the parenthetical part is omitted and the long form is displayed on subsequent use. The short form can be accessed with \glsxtrshort but just uses the default abbreviation font. There’s no regular version of this style as the regular form doesn’t have the flexibility to deal with the hyphen switch. The name is obtained from + id="dx1-30257"> is obtained from \glsxtrlongnoshortdescname.
    long-hyphen-noshort-noreg
    New to version 1.17, this style is like long-hyphen-noshort-desc-noreg but the name is set to the short form and the + id="dx1-30259"> but the name is set to the short form and the description is set to the long form.
    long-hyphen-short-hyphen-desc
    -

    New to version 1.17. This is similar to

    New to version 1.17. This is similar to long-hyphen-short-hyphen but the user + id="dx1-30261"> but the user supplies the description. The name is obtained from is obtained from \glsxtrlongshortdescname.

    long-hyphen-postshort-hyphen
    -

    New to version 1.17. This is similar to

    New to version 1.17. This is similar to long-hyphen-short-hyphen but the + id="dx1-30264"> but the inserted and parenthetical material are moved to the post-link hook. On first use, \gls{}insert
    where -


    \glsxtrposthyphenshort 


    \glsxtrposthyphenshort{label}insert⟩ -

    -

    +class="cmitt-10">insert⟩


    +

    is in the post-link hook. This uses the format:
    insert⟩ (isnert⟩) -

    The singular short form is always used here, even with

    The singular short form is always used here, even with \glspl. (Unlike long-hyphen-long-hyphen.)
    -

    -

    The part in the link-text on first use: -


    \glsxtrlonghyphen  .)
    +

    +

    The part in the link-text on first use: +


    \glsxtrlonghyphen{long}{label}{insert} -

    -

    +class="cmtt-10">}


    +

    checks if ⟨insert⟩ starts with a hyphen. If it does, then \glsxtrwordsep is locally @@ -13217,15 +12963,15 @@ class="cmti-10">insert⟩ for this style without causing nested hyperlinks, but only for commands like \gls. -

    Don’t use

    Don’t use \gls in the ⟨insert⟩ part for commands like \glsxtrfull, \glsxtrshort or \glsxtrlong.
    -

    -

    The inline full display format used by commands like

    +

    The inline full display format used by commands like \glsxtrfull behaves differently to the first use of \gls with this style. It’s better @@ -13240,63 +12986,59 @@ class="cmtt-10">} if you want to ensure the full long-hyphen-postshort-hyphen-desc

    -

    New to version 1.17. This is similar to

    New to version 1.17. This is similar to long-hyphen-postshort-hyphen + id="dx1-30269"> but the user supplies the description. The name is obtained from + id="dx1-30270"> is obtained from \glsxtrlongshortdescname.

    short-hyphen-long-hyphen
    This style (new to v1.17) is like long-hyphen-short-hyphen, + id="dx1-30272">, except that the short form is displayed first followed by the long form in parentheses. The full form is formatted using -


    \glsxtrshorthyphenlong 


    \glsxtrshorthyphenlong{label}{short}{long} - {}{insert}

    -

    +

    which behaves in an analogous way to \glsxtrlonghyphenshort. The name is + id="dx1-30274"> is obtained from \glsxtrshortlongname.

    short-hyphen-long-hyphen-desc
    -

    New to version 1.17. This is similar to

    New to version 1.17. This is similar to short-hyphen-long-hyphen but the user + id="dx1-30276"> but the user supplies the description. The name is obtained from is obtained from \glsxtrshortlongdescname. @@ -13305,12 +13047,12 @@ class="cmtt-10">\glsxtrshortlongdescname. short-hyphen-postlong-hyphen

    This style (new to v1.17) is like long-hyphen-postshort-hyphen, but the short form is displayed first followed by + id="dx1-30279">, but the short form is displayed first followed by the long form in parentheses. On first use, \gls{label}insert
    where -


    \glsxtrposthyphenlong 


    \glsxtrposthyphenlong{label}insert⟩ -

    -

    +class="cmitt-10">insert⟩


    +

    is in the post-link hook. These commands behave in an analogous manner to those used with long-hyphen-postshort-hyphen. The . The name is obtained from + id="dx1-30282"> is obtained from \glsxtrshortlongname. -

    Don’t use

    Don’t use \gls in the ⟨insert⟩ part for commands like \glsxtrfull, \glsxtrshort or \glsxtrlong.
    -

    -

    The inline full display format used by commands like

    +

    The inline full display format used by commands like \glsxtrfull behaves differently to the first use of \gls with this style. It’s better @@ -13375,107 +13114,102 @@ class="cmtt-10">} if you want to ensure the full short-hyphen-postlong-hyphen-desc

    -

    New to version 1.17. This is similar to

    New to version 1.17. This is similar to short-hyphen-postlong-hyphen + id="dx1-30284"> but the user supplies the description. The name is obtained from + id="dx1-30285"> is obtained from \glsxtrshortlongdescname.

    -

    +

    -

    Top

    3.5

    Top

    4.5 Defining New Abbreviation Styles

    -

    New abbreviation styles may be defined using: -


    \newabbreviationstyle 

    New abbreviation styles may be defined using: +


    \newabbreviationstyle{name}{setup}{fmts} -

    -

    - - - -

    where ⟨}


    +

    +

    where ⟨name⟩ is the name of the new style (as used in the mandatory argument of \setabbreviationstyle). This is similar but not identical to the ). This is similar but not identical to the glossaries package’s \newacronymstyle command. -

    You can’t use styles defined by command. + + + +

    You can’t use styles defined by \newacronymstyle with glossaries-extra unless you have reverted \newacronym back to its generic definition from + id="dx1-31004"> back to its generic definition from glossaries (using \RestoreAcronyms). The acronym styles from the ). The acronym styles from the glossaries package can’t be used with abbreviations defined with \newabbreviation.
    -

    -

    The ⟨

    +

    The ⟨setup⟩ argument deals with the way the entry is defined and may set attributes for the given abbreviation category. This argument should redefine -


    \CustomAbbreviationFields 


    \CustomAbbreviationFields

    -

    +

    to set the entry fields including the name (defaults to the short form if omitted), + id="dx1-31007"> (defaults to the short form if omitted), sort, , first, , firstplural. Other fields may also be set, such as . Other fields may also be set, such as text, , plural and + id="dx1-31012"> and description. -

    . +

    \CustomAbbreviationFields is expanded by \newabbreviation so take care to protect commands that shouldn’t be expanded.
    -

    -

    For example, the

    +

    For example, the long-short style has the following in ⟨ style has the following in ⟨setup⟩:

    -
    +
      \renewcommand*{\CustomAbbreviationFields}{%  
        name={\protect\glsabbrvfont{\the\glsshorttok}},  
        sort={\the\glsshorttok}, @@ -13488,24 +13222,24 @@ class="cmti-10">setup⟩:  
        plural={\protect\glsabbrvfont{\the\glsshortpltok}},%  
        description={\the\glslongtok}}%
    -

    Note that the

    Note that the first and and firstplural are set even though they’re not used by + id="dx1-31016"> are set even though they’re not used by \gls. -

    The basic styles, such as

    The basic styles, such as long-short, use commands like , use commands like \glsabbrvfont (which are redefined whenever the style formatting is set) within \CustomAbbreviationFields. Other styles, such as long-em-short-em directly use their own custom commands, such + id="dx1-31018"> directly use their own custom commands, such as \glsabbrvemfont. With these styles, commands like \glsabbrvfont still need to @@ -13513,26 +13247,24 @@ be defined as appropriate in the ⟨fmts⟩ argument even if they’re not used within \CustomAbbreviationFields. -

    The ⟨

    The ⟨setup⟩ argument may also redefine -


    \GlsXtrPostNewAbbreviation 


    \GlsXtrPostNewAbbreviation

    -

    +

    which can be used to assign attributes. (This will automatically be initialised to do nothing.) -

    For example, the

    For example, the short-footnote includes the following in ⟨ includes the following in ⟨setup⟩:

    -
    +
      \renewcommand*{\GlsXtrPostNewAbbreviation}{%  
        \glssetattribute{\the\glslabeltok}{nohyperfirst}{true}%  
        \glshasattribute{\the\glslabeltok}{regular}% @@ -13542,252 +13274,216 @@ class="cmti-10">setup⟩:  
        {}%  
      }%
    -

    This sets the

    This sets the nohyperfirst attribute to “true”. It also unsets the attribute to “true”. It also unsets the regular attribute if it + id="dx1-31022"> attribute if it has previously been set. Note that the nohyperfirst attribute doesn’t get unset by + id="dx1-31023"> attribute doesn’t get unset by other styles, so take care not to switch styles for the same category. -

    You can access the short, long, short plural and long plural values through the +

    You can access the short, long, short plural and long plural values through the following token registers. -

    Short value (defined by

    Short value (defined by glossaries): -


    \glsshorttok 


    \glsshorttok

    -

    -

    Short plural value (defined by

    +

    Short plural value (defined by glossaries-extra): -


    \glsshortpltok 


    \glsshortpltok

    -

    +

    (This may be the default value or, if provided, the value provided by the user through the shortplural key in the optional argument of key in the optional argument of \newabbreviation.) -

    Long value (defined by .) +

    Long value (defined by glossaries): -


    \glslongtok 


    \glslongtok

    -

    -

    Long plural value (defined by

    +

    Long plural value (defined by glossaries-extra): -


    \glslongpltok 


    \glslongpltok

    -

    +

    (This may be the default value or, if provided, the value provided by the user through the longplural key in the optional argument of key in the optional argument of \newabbreviation.) -

    The short or long values may be modified by attributes (such as .) +

    The short or long values may be modified by attributes (such as markwords). The + id="dx1-31032">). The above registers reflect the modification. If you want to access the original (unmodified) short or long form (as provided in the final two arguments of \newabbreviation), then use the commands: -


    \glsxtrorgshort 


    \glsxtrorgshort

    -

    +

    for the short form and -


    \glsxtrorglong 


    \glsxtrorglong

    -

    +

    for the long form. (These may be useful for the sort key to avoid any formatting that + id="dx1-31035"> key to avoid any formatting that may be added by the attribute setting.) -

    There are two other registers available that are defined by

    There are two other registers available that are defined by glossaries: -


    \glslabeltok 


    \glslabeltok

    -

    +

    which contains the entry’s label and -


    \glskeylisttok 


    \glskeylisttok

    -

    +

    which contains the values provided in the optional argument of \newabbreviation. -

    Remember put . +

    Remember put \the in front of the register command as in the examples above. The category label can be access through the command (not a register): -


    \glscategorylabel 


    \glscategorylabel

    -

    +

    This may be used inside the definition of \GlsXtrPostNewAbbreviation. -

    If you want to base a style on an existing style, you can use -


    \GlsXtrUseAbbrStyleSetup 

    If you want to base a style on an existing style, you can use +


    \GlsXtrUseAbbrStyleSetup{name}

    -

    +

    where ⟨name⟩ is the name of the existing style. For example, the long-noshort-sc-desc + id="dx1-31041"> style simply does

    -
    +
    \GlsXtrUseAbbrStyleSetup{long-noshort-desc}
    -

    within ⟨

    within ⟨setup⟩. -

    The ⟨

    The ⟨fmts⟩ argument deals with the way the entry is displayed in the document. This argument should redefine the following commands. -

    The default suffix for the plural short form (if not overridden by the

    The default suffix for the plural short form (if not overridden by the shortplural + id="dx1-31042"> key): -


    \abbrvpluralsuffix 


    \abbrvpluralsuffix

    -

    +

    (Note that this isn’t used for the plural long form, which just uses the regular \glspluralsuffix.) -

    The font used for the short form on

    The font used for the short form on first use or in the full forms: -


    \glsfirstabbrvfont 


    \glsfirstabbrvfont{text}

    -

    -

    The font used for the short form on subsequent use or through commands like +

    +

    The font used for the short form on subsequent use or through commands like \glsxtrshort: -


    \glsabbrvfont  : +


    \glsabbrvfont{text}

    -

    -

    The font used for the long form on first use or in the full forms: -


    \glsfirstlongfont 

    +

    The font used for the long form on first use or in the full forms: +


    \glsfirstlongfont{text}

    -

    -

    The font used for the long form in commands like

    +

    The font used for the long form in commands like \glsxtrlong use: -


    \glslongfont 


    \glslongfont{text}

    -

    -

    Display full form singular no case-change (used by

    +

    Display full form singular no case-change (used by \gls on first use for + id="dx1-31051"> on first use for abbreviations without the regular attribute set): -


    \glsxtrfullformat  attribute set): +


    \glsxtrfullformat{label}{insert}

    -

    -

    Display full form singular first letter converted to upper case (used by

    +

    Display full form singular first letter converted to upper case (used by \Gls on + id="dx1-31055"> on first use for abbreviations without the first use for abbreviations without the regular attribute set): -


    \Glsxtrfullformat  attribute set): +


    \Glsxtrfullformat{label}{insert}

    -

    -

    Display full form plural no case-change (used by

    +

    Display full form plural no case-change (used by \glspl on first use for + id="dx1-31059"> on first use for abbreviations without the regular attribute set): -


    \glsxtrfullplformat  attribute set): +


    \glsxtrfullplformat{label}{}

    -

    -

    Display full form plural first letter converted to upper case (used by

    +

    Display full form plural first letter converted to upper case (used by \Glspl on + id="dx1-31063"> on first use for abbreviations without the regular attribute set): -


    \Glsxtrfullplformat  attribute set): +


    \Glsxtrfullplformat{label}{insert}

    -

    -

    In addition ⟨

    +

    In addition ⟨fmts⟩ may also redefine the following commands that govern the inline full formats. If the style doesn’t redefine them, they will default to the same as the display full forms. -

    Inline singular no case-change (used by

    Inline singular no case-change (used by \glsentryfull, , \glsxtrfull and + id="dx1-31068"> and \GLSxtrfull): -


    \glsxtrinlinefullformat  ): +


    \glsxtrinlinefullformat{label}{insert} -

    -

    -

    Inline singular first letter converted to upper case (used by }


    +

    +

    Inline singular first letter converted to upper case (used by \Glsentryfull and + id="dx1-31071"> and \Glsxtrfull): -


    \Glsxtrinlinefullformat  ): +


    \Glsxtrinlinefullformat{label}{insert} -

    -

    -

    Inline plural no case-change (used by }


    +

    +

    Inline plural no case-change (used by \glsentryfullpl, , \glsxtrfullpl and + id="dx1-31075"> and \GLSxtrfullpl): -


    \glsxtrinlinefullplformat  ): +


    \glsxtrinlinefullplformat{label}{insert} -

    -

    -

    Inline plural first letter converted to upper case (used by }


    +

    +

    Inline plural first letter converted to upper case (used by \Glsentryfullpl and + id="dx1-31078"> and \Glsxtrfullpl): -


    \Glsxtrinlinefullplformat  ): +


    \Glsxtrinlinefullplformat{label}{insert} -

    -

    -

    (New to version 1.17.) You can also modify the way the subsequent use is +class="cmtt-10">}


    +

    +

    (New to version 1.17.) You can also modify the way the subsequent use is formatted by redefining the following four commands, but these won’t be used for abbreviations with the regular attribute set. If the style doesn’t redefine these + id="dx1-31081"> attribute set. If the style doesn’t redefine these commands, the default values are used. -

    Singular with no case-change: -


    \glsxtrsubsequentfmt 

    Singular with no case-change: +


    \glsxtrsubsequentfmt{label}{insert}

    -

    -

    Singular with first letter upper case: -


    \Glsxtrsubsequentfmt  \Glsxtrsubsequentfmt{

    +

    Singular with first letter upper case: +


    \Glsxtrsubsequentfmt{label}{insert}

    +

    +

    Plural with no case-change: +


    \glsxtrsubsequentplfmt{label}{insert}

    -

    +

    -

    Plural with no case-change: -


    \glsxtrsubsequentplfmt  \glsxtrsubsequentplfmt{label}{insert} -

    -

    -

    Plural with first letter upper case: -


    \Glsxtrsubsequentplfmt 

    Plural with first letter upper case: +


    \Glsxtrsubsequentplfmt{label}{insert} -

    -

    -

    If you want to provide support for }


    +

    +

    If you want to provide support for glossaries-accsupp use the following + id="dx1-31086"> use the following \glsaccessxxx⟩ commands (§11.2 §12.2 Accessibility Support) within the definitions of \glsxtrfullformat etc instead of the analogous \glsentryxxx⟩ commands. (If you don’t use glossaries-accsupp, they will just do the corresponding , they will just do the corresponding \glsentryxxx⟩ command.) -

    For example, the

    For example, the short-long style has the following in ⟨ style has the following in ⟨fmts⟩:

    -
    +
      \renewcommand*{\abbrvpluralsuffix}{\glsxtrabbrvpluralsuffix}%  
      \renewcommand*{\glsabbrvfont}[1]{\glsabbrvdefaultfont{##1}}%  
      \renewcommand*{\glsfirstabbrvfont}[1]{\glsfirstabbrvdefaultfont{##1}}% @@ -14005,44 +13677,42 @@ class="cmti-10">fmts⟩:  
        \glsxtrparen{\glsfirstlongfont{\glsaccesslongpl{##1}}}%  
      }%
    -

    Since the inline full commands aren’t redefined, they default to the same as the +

    Since the inline full commands aren’t redefined, they default to the same as the display versions. -

    If you want to base a style on an existing style, you can use -


    \GlsXtrUseAbbrStyleFmts 

    If you want to base a style on an existing style, you can use +


    \GlsXtrUseAbbrStyleFmts{name}

    -

    +

    within ⟨fmts⟩, where ⟨name⟩ is the name of the existing style. For example, the long-short-desc style has the following in ⟨ style has the following in ⟨fmts⟩:

    -
    +
      \GlsXtrUseAbbrStyleFmts{long-short}%
    -

    -

    Here’s an example of an abbreviation style that’s based on

    +

    Here’s an example of an abbreviation style that’s based on long-short that displays + id="dx1-31091"> that displays the short form within \textsf:

    -
    +
    \newabbreviationstyle  
    {custom-sf}% label  
    {% setup @@ -14053,37 +13723,37 @@ class="cmtt-10">\textsf:  
      \renewcommand*{\glsabbrvfont}[1]{\textsf{##1}}%  
    }
    -

    Note that this wouldn’t work if it was instead based on one of the modified versions +

    Note that this wouldn’t work if it was instead based on one of the modified versions such as short-sc-long as they explicitly use their own formatting commands, such as + id="dx1-31092"> as they explicitly use their own formatting commands, such as \glsabbrvemfont. The base styles, such as short-long, use the more generic + id="dx1-31093">, use the more generic \glsabbrvfont etc which makes them easier to adapt than the modified styles. -

    For further details, see the “Abbreviations” section in the documented code +

    For further details, see the “Abbreviations” section in the documented code (glossaries-extra-code.pdf).

    -

    -

    Top

    4.

    +

    Top

    5. Entries in Sectioning Titles, Headers, Captions and Contents

    -

    The

    The glossaries user manual cautions against using commands like \gls in chapter or section titles. The principle problems are:

    • if you have a table of contents, the first use flag will be unset in the contents rather than later in the document;
    • @@ -14100,27 +13770,31 @@ class="cmtt-10">\gls etc) will be converted to upper case and the
    • if you use hyperref, commands like , commands like \gls can’t be expanded to a simple string and only the label will appear in the PDF bookmark (with a warning from hyperref); + id="dx1-32003">);
    • if you use hyperref, you will end up with nested hyperlinks in the table of + id="dx1-32004">, you will end up with nested hyperlinks in the table of contents.
    -

    Similar problems can also occur with captions (except for the page header and bookmark +

    Similar problems can also occur with captions (except for the page header and bookmark issues). -

    To get around all these problems, the +

    Top

    5.1 Simplistic Approach

    +

    To get around all these problems, the glossaries user manual recommends using the expandable non-hyperlink commands, such as \glsentrytext + id="dx1-33001"> (for regular entries) or \glsentryshort (for abbreviations). This is the + id="dx1-33002"> (for abbreviations). This is the simplest solution, but doesn’t allow for special formatting that’s applied to the entry through commands like \glstext or \glsxtrshort. This means that if, for example, you are using one of the abbreviation styles that uses \textsc then the short form displayed with then the short form displayed with \glsentryshort won’t use small caps. If you only have one abbreviation style in use, you can explicitly enclose -

    +
    \chapter{A Chapter about \glsabbrvfont{\glsentryshort{html}}}
    -

    Or, if you are using

    Or, if you are using hyperref: + id="dx1-33004">:

    -
    +
    \chapter{A Chapter about  
    \texorpdfstring{\glsabbrvfont{\glsentryshort{html}}}{\glsentryshort{html}}}
    -

    -

    Since this is a bit cumbersome, you might want to define a new command to do +

    +

    Since this is a bit cumbersome, you might want to define a new command to do this for you. However, if you have mixed styles this won’t work as commands like \gls and \MakeUppercase. -

    The . +

    The glossaries-extra package tries to resolve this by modifying \markright and + id="dx1-33006"> and \markboth and and \@starttoc. If you don’t like this change, you can restore their former definitions using -


    \glsxtrRevertMarks 


    \glsxtrRevertMarks

    -

    +

    If you only want to restore \@starttoc you can use: -


    \glsxtrRevertTocMarks 


    \glsxtrRevertTocMarks

    -

    +

    If you restore the header or table of contents commands, you’ll have to use the glossaries manual’s recommendations of either simply using -

    +
    \chapter[A Chapter about \glsentryshort{html}]{A Chapter about \gls{html}}
    -

    Alternatively, you need to find a way to insert

    Alternatively, you need to find a way to insert \glsxtrmarkhook and \@glsxtrinmark at the start of the header or table of contents either scoped or afterwards cancelled with \@glsxtrnotinmark and \glsxtrrestoremarkhook. -

    If you don’t revert the mark commands back with

    If you don’t revert the mark commands back with \glsxtrRevertMarks, you can use the commands described below in the argument of sectioning commands. You can still use them even if the mark commands have been reverted, but only where they don’t conflict with the page style. -

    The commands listed below all use

    +

    +

    Top

    5.2 New Commands Designed for Chapter/Section Headings

    +

    The commands listed below are designed for use in chapter or section headings. +There are still limitations, but they provide a better solution. They all use +\texorpdfstring if if hyperref has been -loaded so that the expandable non-formatted version is added to the PDF -bookmarks. Note that since the commands that convert the first letter to -upper case aren’t expandable, the non-case-changing version is used for the -bookmarks. -

    These commands essentially behave as though you have used \glsxtrshort (or -equivalent) with the options has been loaded so that the expandable non-formatted +version is added to the PDF bookmarks. Note that since the commands that convert +the first letter to upper case aren’t expandable, the non-case-changing version is used +for the bookmarks. If the required field contains non-expandable (robust or fragile) +commands that cause a problem for the bookmarks then \texorpdfstring will be +needed as appropriate in that field. (Take care if the field has its value expanded +before being assigned.) +

    These commands essentially behave as though you have used \glsxtrshort, +\glstext etc with the options noindex and and hyper=false. The text produced won’t be + id="dx1-34005">. The text produced won’t be converted to upper case in the page headings by default. If you want the text converted to upper case you need to set the headuc attribute to “true” for the + id="dx1-34006"> attribute to “true” for the appropriate category. -

    If you use one of the

    If you use one of the \textsc styles, be aware that the default fonts don’t + id="dx1-34007"> styles, be aware that the default fonts don’t provide bold small-caps or italic small-caps. This means that if the chapter or section title style uses bold, this may override the small-caps setting, in which case the abbreviation will just appear as lower case bold. If the @@ -14251,339 +13933,399 @@ heading style uses italic, the abbreviation may appear in upright small-caps, class="cmti-10">even if you have set the headuc attribute since the all-capitals form still uses \glsabbrvfont. You may want to consider using the slantsc package in this case. -
    -

    -

    Display the short form: -


    \glsfmtshort  package in this case. +
    +

    +

    Display the short form: +


    \glsfmtshort{label}

    -

    -

    Display the plural short form: -


    \glsfmtshortpl 

    +

    Display the plural short form: +


    \glsfmtshortpl{label}

    -

    -

    First letter upper case singular short form: -


    \Glsfmtshort 

    +

    First letter upper case singular short form: +


    \Glsfmtshort{label}

    -

    +

    (No case-change applied to PDF bookmarks.) -

    First letter upper case plural short form: - - - -


    \Glsfmtshortpl 

    First letter upper case plural short form: +


    \Glsfmtshortpl{label}

    -

    +

    +(No case-change applied to PDF bookmarks.) +

    All caps singular short form: +


    \GLSfmtshort{label}

    +

    (No case-change applied to PDF bookmarks.) -

    Display the long form: -


    \glsfmtlong 

    All caps plural short form: +


    \Glsfmtshortpl{label}

    +

    +(No case-change applied to PDF bookmarks.) +

    Display the long form: +


    \glsfmtlong{label}

    -

    -

    Display the plural long form: -


    \glsfmtlongpl 

    +

    Display the plural long form: +


    \glsfmtlongpl{label}

    -

    -

    First letter upper case singular long form: -


    \Glsfmtlong 

    +

    First letter upper case singular long form: +


    \Glsfmtlong{label}

    -

    +

    (No case-change applied to PDF bookmarks.) -

    First letter upper case plural long form: -


    \Glsfmtlongpl 

    First letter upper case plural long form: +


    \Glsfmtlongpl{label}

    -

    +

    +(No case-change applied to PDF bookmarks.) +

    All caps singular long form: +


    \GLSfmtlong{label}

    +

    +(No case-change applied to PDF bookmarks.) +

    All caps plural long form: +


    \GLSfmtlongpl{label}

    +

    (No case-change applied to PDF bookmarks.) -

    There are similar commands for the full form, but note that these use the

    There are similar commands for the full form, but note that these use the inline full form, which may be different from the full form used by \gls. -

    Display the full form: -


    \glsfmtfull  \gls. The PDF version +has to be a simple fully expandable command, so one of two commands that are +unrelated to the style is used instead: +


    \glspdffmtfull{label}

    +

    +for the singular form or: +


    \glspdffmtfullpl{label}

    +

    +for the full form. These simply do the long form followed by the short form in +parentheses. +

    Display the full form: +


    \glsfmtfull{label}

    -

    -

    Display the plural full form: -


    \glsfmtfullpl 

    +

    Display the plural full form: +


    \glsfmtfullpl{label}

    -

    -

    First letter upper case singular full form: -


    \Glsfmtfull 

    +

    First letter upper case singular full form: +


    \Glsfmtfull{label}

    -

    +

    (No case-change applied to PDF bookmarks.) -

    First letter upper case plural full form: -


    \Glsfmtfullpl 

    First letter upper case plural full form: +


    \Glsfmtfullpl{label}

    -

    +

    +(No case-change applied to PDF bookmarks.) +

    All caps singular full form: +


    \GLSfmtfull{label}

    +

    (No case-change applied to PDF bookmarks.) -

    There are also equivalent commands for the value of the

    All caps plural full form: +


    \GLSfmtfullpl{label}

    +

    +(No case-change applied to PDF bookmarks.) +

    There are also equivalent commands for the value of the text field: -


    \glsfmttext  field: +


    \glsfmttext{label}

    -

    -

    First letter converted to upper case: -


    \Glsfmttext 

    +

    First letter converted to upper case: +


    \Glsfmttext{label}

    -

    +

    (No case-change applied to PDF bookmarks.) -

    The plural equivalents: +

    All caps: +


    \GLSfmttext{label}

    -


    \glsfmtplural 

    +(No case-change applied to PDF bookmarks.) +

    The plural equivalents: +


    \glsfmtplural{label}

    -

    -and -


    \Glsfmtplural 

    +First letter upper case: +


    \Glsfmtplural{label}

    -

    -

    Likewise for the value of the

    +and all caps: +


    \GLSfmtplural{label}

    +

    +

    Likewise for the value of the name field: -


    \glsfmtname  field: +


    \glsfmtname{label}

    -

    -

    First letter converted to upper case: -


    \Glsfmtname 

    +

    First letter converted to upper case: +


    \Glsfmtname{label}

    -

    +

    +(No case-change applied to PDF bookmarks.) +

    All caps: +


    \GLSfmtname{label}

    +

    (No case-change applied to PDF bookmarks.) -

    Similarly for the value of the

    Similarly for the value of the first field: -


    \glsfmtfirst  field: +


    \glsfmtfirst{label}

    -

    -

    First letter converted to upper case: -


    \Glsfmtfirst 

    +

    First letter converted to upper case: +


    \Glsfmtfirst{label}

    -

    +

    (No case-change applied to PDF bookmarks.) -

    The plural equivalents: -


    \glsfmtfirstpl 

    All caps: +


    \GLSfmtfirst{label}

    +

    +(No case-change applied to PDF bookmarks.) +

    The plural equivalents: +


    \glsfmtfirstpl{label}

    -

    -and -


    \Glsfmtfirstpl 

    +First letter upper case: +


    \Glsfmtfirstpl{label}

    -

    +

    +and all caps: +


    \GLSfmtfirstpl{label}

    +

    + + +

    -

    -

    Top

    5.

    +

    Top

    6. Categories

    -

    Each entry defined by

    Each entry defined by \newglossaryentry (or commands that internally use it + id="dx1-35001"> (or commands that internally use it such as \newabbreviation) is assigned a category through the ) is assigned a category through the category key. You may + id="dx1-35003"> key. You may add any category that you like, but since the category is a label used in the creation of some control sequences, avoid problematic characters within the category label. (So take care if you have babel shorthands on that make some characters + id="dx1-35004"> shorthands on that make some characters active.) -

    The use of categories can give you more control over the way entries are displayed +

    The use of categories can give you more control over the way entries are displayed in the text or glossary. Note that an entry’s category is independent of the glossary type. Be careful not to confuse category with with type. -

    The default category assumed by . +

    The default category assumed by \newglossaryentry is labelled general. + id="dx1-35007">. Abbreviations defined with \newabbreviation have the category set to abbreviation + id="dx1-35008"> by default. Abbreviations defined with \newacronym have the category set to acronym by default. -

    Additionally, if you have enabled by default. +

    Additionally, if you have enabled \newterm with the with the index package option + id="dx1-35011"> package option that command will set the category to index by default. If you have enabled + id="dx1-35012"> by default. If you have enabled \glsxtrnewsymbol with the with the symbols package option, that command will set the + id="dx1-35014"> package option, that command will set the category to symbol. If you have enabled . If you have enabled \glsxtrnewnumber with the with the numbers package + id="dx1-35017"> package option, that command will set the category to number. -

    You can obtain the category label for a given entry using -


    \glscategory  . +

    You can obtain the category label for a given entry using +


    \glscategory{label}

    -

    +

    This is equivalent to commands like \glsentryname and so may be used in an expandable context. No error is generated if the entry doesn’t exist. -

    You can test the category for a given entry using -


    \glsifcategory 

    You can test the category for a given entry using +


    \glsifcategory{entry-label}{category-label}{true -parttrue part}{false part}

    -

    +class="cmtt-10">} +


    +

    This is equivalent to

    \ifglsfieldeq{entry-label}}
    so any restrictions that apply to \ifglsfieldeq also apply to \glsifcategory. -

    Each category may have a set of attributes. For example, the

    Each category may have a set of attributes. For example, the general and and acronym + id="dx1-35023"> categories have the attribute regular set to “true” to indicate that all entries with + id="dx1-35024"> set to “true” to indicate that all entries with either of those categories are regular entries (as opposed to abbreviations). This attribute is accessed by \glsentryfmt to determine whether to use \glsgenentryfmt or \glsxtrgenabbrvfmt. -

    Other attributes recognised by

    Other attributes recognised by glossaries-extra are:

    nohyperfirst
    When using commands like \gls this will automatically suppress the + id="dx1-35026"> this will automatically suppress the hyperlink on first use for entries with a category that has this attribute set to “true”. (This settings can be overridden by explicitly setting the hyper + id="dx1-35028"> key on or off in the optional argument of commands like \gls.) As from version 1.07, \glsfirst, \Glsfirst, \GLSfirst and their plural versions (which should ideally behave in a similar way to the first use of + id="dx1-35029">first use of \gls or \glspl) now honour this attribute (but not the package-wide @@ -14653,67 +14395,65 @@ class="cmtt-10">\glspl) now honour this attribute (but not the package-wi href="#styopt.hyperfirst">hyperfirst=false option, which matches the behaviour of option, which matches the behaviour of glossaries). If you want + id="dx1-35031">). If you want commands like \glsfirst to ignore the nohyperfirst attribute then just + id="dx1-35032"> attribute then just redefine -


    \glsxtrchecknohyperfirst 


    \glsxtrchecknohyperfirst{label}

    -

    +

    to do nothing.

    nohyper
    When using commands like \gls this will automatically suppress the + id="dx1-35035"> this will automatically suppress the hyperlink for entries with a category that has this attribute set to “true”. (This settings can be overridden by explicitly setting the hyper key on or off in the + id="dx1-35036"> key on or off in the optional argument of commands like \gls.)
    indexonlyfirst
    This is similar to the indexonlyfirst package option but only for entries + id="dx1-35038"> package option but only for entries that have a category with this attribute set to “true”.
    wrgloss
    When using commands like \gls, if this attribute is set to “after”, it will + id="dx1-35040">, if this attribute is set to “after”, it will automatically implement wrgloss=after. (New to v1.14.)
    discardperiod
    If set to “true”, the post-link-text hook will discard a full stop (period) that follows non-plural commands like \newacronym if it’s using \newabbreviation.) This attribute doesn’t apply to the accessibility fields. -

    Note that this can cause a problem if you access a field that doesn’t end with a +

    Note that this can cause a problem if you access a field that doesn’t end with a full stop. For example:

    -
    +
    \newabbreviation  
     [user1={German Speaking \TeX\ User Group}]  
     {dante}{DANTE e.V.}{Deutschsprachige Anwendervereinigung \TeX\  
    e.V.}
    -

    Here the

    Here the short and and long fields end with a full stop, but the fields end with a full stop, but the user1 field doesn’t. + id="dx1-35046"> field doesn’t. The simplest solution in this situation is to put the sentence terminator in the final optional argument. For example:

    -
    +
    \glsuseri{dante}[.]
    -

    This will bring the punctuation character inside the

    This will bring the punctuation character inside the link-text and it won’t be discarded.

    pluraldiscardperiod
    If this attribute is set to “true” and the discardperiod attribute is + id="dx1-35049"> attribute is set to “true”, this will behave as above for the plural commands like \glspl or \newabbreviation.) retainfirstuseperiod
    If this attribute is set to “true” then the full stop won’t be discarded for first use instances, even if discardperiod or or pluraldiscardperiod are + id="dx1-35053"> are set. This is useful for ⟨short⟩ (⟨long⟩) abbreviation styles where only the @@ -14805,52 +14545,48 @@ class="cmtt-10">\newabbreviation.) This attribute doesn’t apply to markwords
    If this attribute is set to “true” any entry defined using \newabbreviation + id="dx1-35055"> will automatically have spaces in the long form replaced with -


    \glsxtrwordsep 


    \glsxtrwordsep

    -

    +

    and each word is encapsulated with -


    \glsxtrword 


    \glsxtrword{word}

    -

    +

    For example:

    -
    +
    \glssetcategoryattribute{abbreviation}{markwords}{true}  
    \newabbreviation{ip}{IP}{Internet Protocol}
    -

    is essentially the same as +

    is essentially the same as

    -
    +
    \newabbreviation{ip}{IP}  
    {\glsxtrword{Internet}\glsxtrwordsep\glsxtrword{Protocol}}
    -

    The “hyphen” styles, such as

    The “hyphen” styles, such as long-hyphen-short-hyphen, take advantage of this + id="dx1-35058">, take advantage of this markup. If the inserted material (provided in the final argument of commands like \gls) starts with a hyphen then ) starts with a hyphen then \glsxtrwordsep is locally redefined to a hyphen. (The default value is a space). Note that this only applies to commands like \glsxtrlong. You can provide your own

    -
    +
    \newcommand{\hyplong}[2][]{%  
     {\def\glsxtrwordsep{-}\glsxtrlong[#1]{#2}}}
    -

    -

    This setting will also adjust the long plural. This attribute is only applicable to +

    +

    This setting will also adjust the long plural. This attribute is only applicable to entries defined using \newabbreviation (or \newacronym if it’s using \newabbreviation.) -

    This setting may result in the

    This setting may result in the \glsxtrword and \glsxtrwordsep markup ending up in the sort field, depending on the style in use.
    -

    + id="dx1-35060"> field, depending on the style in use.

    +

    markshortwords
    This is similar to markwords but applies to the short form. (Only + id="dx1-35062"> but applies to the short form. (Only useful for abbreviations that contain spaces.) This attribute is only applicable to entries defined using \newabbreviation (or \newacronym if it’s using - \newabbreviation.) -

    This setting will only adjust the short plural if the shortplural key isn’t used. - This setting will take precedence over insertdots. -

    This setting may result in the \glsxtrword and \glsxtrwordsep markup - ending up in the sort field, depending on the style in use.
    -

    -

    -insertdots
    If this attribute is set to “true” any entry defined using \newabbreviation - will automatically have full stops (periods) inserted after each letter. The entry - will be defined with those dots present as though they had been present in the - ⟨short⟩ argument of \newabbreviation (rather than inserting them every time - the entry is used). The short plural form defaults to the new dotted version of - the original ⟨short⟩ form with the plural suffix appended. This setting is - incompatible with markshortwords. This attribute is only applicable to - entries defined using \newabbreviation (or \newacronym if it’s using - \newabbreviation.) -

    If you explicitly override the short plural using the shortplural key, you must - explicitly insert the dots yourself (since there’s no way for the code to - determine if the plural has a suffix that shouldn’t be followed by a dot). -
    -

    - - - -

    This attribute is best used with the discardperiod attribute set to “true”. -

    -aposplural
    If this attribute is set to “true”, \newabbreviation will insert an - apostrophe (’) before the plural suffix for the short plural form (unless - explicitly overridden with the shortplural key). The long plural form is - unaffected by this setting. This setting overrides noshortplural. This - attribute is only applicable to entries defined using \newabbreviation (or - \newacronym if it’s using \newabbreviation.) Check with your supervisor, - publisher or editor if you want to use this attribute as this usage is - controversial. -
    -noshortplural
    If this attribute is set to “true”, \newabbreviation won’t append - the plural suffix for the short plural form. This means the short and - shortplural values will be the same unless explicitly overridden. This setting - is incompatible with aposplural. This attribute is only applicable to - entries defined using \newabbreviation (or \newacronym if it’s using - \newabbreviation.) -
    -accessinsertdots
    If this attribute is set to “true” and the glossaries-accsupp package - has been loaded (with the accsupp option), then this behaves like insertdots but - for the shortaccess field instead of the short field. This can be used to assist the - screen reader for initialisms that should be read out letter by letter rather than - as a word. For example: - - - -
    - \glssetcategoryattribute{initialism}{accessinsertdots}{true} -  
    \newabbreviation[category=initialism]{pi}{PI}{Private Investigator} -
    -

    This setting will be overridden by an explicit use of the shortaccess key in the - optional argument of \newabbreviation (or \newacronym). This attribute is - only applicable to entries defined using \newabbreviation (or \newacronym if - it’s using \newabbreviation.) -

    -nameshortaccess
    If this attribute is set to “true”, the access field (used for the name - field’s accessibility support) is set to the shortaccess value. This attribute has no - effect if there’s no accessibility support or if the shortaccess field hasn’t been - assigned or if the access field is used explicitly. This attribute is only applicable - to entries defined using \newabbreviation (or \newacronym if it’s using - \newabbreviation.) -
    -textshortaccess
    Like nameshortaccess but applies to the textaccess field (for use with - regular abbreviations). -
    -firstshortaccess
    Like nameshortaccess but applies to the firstaccess field (for use with - regular abbreviations). -
    -accessaposplural
    This boolean attribute overrides aposplural for the shortpluralaccess - key. Has no effect if there’s no accessibility support or if the shortaccess key - hasn’t been set or if the shortpluralaccess key is explicitly set. If the aposplural is - set and this attribute isn’t set and the shortaccess key is set, then the - aposplural setting governs the default shortpluralaccess setting. If you want - aposplural but don’t want it applied to the accessibility support, set the - accessaposplural attribute to “false”. This attribute is only applicable to + \newabbreviation.) +

    This setting will only adjust the short plural if the shortplural key isn’t used. + This setting will take precedence over insertdots. +

    This setting may result in the \glsxtrword and \glsxtrwordsep markup + ending up in the sort field, depending on the style in use.
    +

    +

    +insertdots
    If this attribute is set to “true” any entry defined using \newabbreviation + will automatically have full stops (periods) inserted after each letter. The entry + will be defined with those dots present as though they had been present in the + ⟨short⟩ argument of \newabbreviation (rather than inserting them every time + the entry is used). The short plural form defaults to the new dotted version of + the original ⟨short⟩ form with the plural suffix appended. This setting is + incompatible with markshortwords. This attribute is only applicable to entries defined using \newabbreviation (or \newacronym if it’s using \newabbreviation.) -
    +

    If you explicitly override the short plural using the shortplural key, you must + explicitly insert the dots yourself (since there’s no way for the code to + determine if the plural has a suffix that shouldn’t be followed by a dot). +
    +

    + + + +

    This attribute is best used with the discardperiod attribute set to “true”. +

    accessnoshortplural
    This boolean attribute overrides aposplural
    If this attribute is set to “true”, \newabbreviation will insert an + apostrophe (’) before the plural suffix for the short plural form (unless + explicitly overridden with the shortplural key). The long plural form is + unaffected by this setting. This setting overrides noshortplural for the - shortpluralaccess key. The same conditions apply as for accessaposplural. This + id="dx1-35074">. This attribute is only applicable to entries defined using \newabbreviation (or \newacronym if it’s using \newabbreviation.) Check with your supervisor, + publisher or editor if you want to use this attribute as this usage is + controversial. +
    +noshortplural
    If this attribute is set to “true”, \newabbreviation won’t append + the plural suffix for the short plural form. This means the short and + shortplural values will be the same unless explicitly overridden. This setting + is incompatible with aposplural. This attribute is only applicable to + entries defined using \newabbreviation (or \newacronym if it’s using + \newabbreviation.)
    headuc
    If this attribute is set to “true”, commands like \glsfmtshort will use the + id="dx1-35081"> will use the upper case version in the page headers. - - -
    tagging
    If this attribute is set to “true”, the tagging command defined by \GlsXtrEnableInitialTagging will be activated to use will be activated to use \glsxtrtagfont in + id="dx1-35084"> in the glossary (see §3.1 §4.1 Tagging Initials).
    entrycount
    Unlike the above attributes, this attribute isn’t boolean but instead must be an integer value and is used in combination with \glsenableentrycount + id="dx1-35086"> (see §2.4 §2.5 Entry Counting Modifications). Leave blank or undefined for categories that shouldn’t have this facility enabled. The value of this attribute is used by \glsxtrifcounttrigger to determine how commands such as to determine how commands such as \cgls + id="dx1-35088"> should behave. -

    With

    With glossaries, commands like \cgls use \cglsformat only if the previous @@ -15204,43 +14789,46 @@ class="cmss-10">glossaries-extra the test is now for entries that have the entrycount attribute set and where the previous + id="dx1-35089"> attribute set and where the previous usage count for that entry is less than or equal to the value of that attribute.

    linkcount
    This attribute is set to true by \GlsXtrEnableLinkCounting (see (see §6.2 +class="cmsy-10">§7.2 Link Counting).
    linkcountmaster
    This attribute is set to the name of the master counter by + + + \GlsXtrEnableLinkCounting if the optional argument is provided (see if the optional argument is provided (see §6.2 +class="cmsy-10">§7.2 Link Counting).
    glossdesc
    The \glossentrydesc command (used in the predefined glossary styles) is + id="dx1-35095"> command (used in the predefined glossary styles) is modified by glossaries-extra to check for this attribute. The attribute may have one of the following values: @@ -15249,34 +14837,31 @@ class="cmss-10">glossaries-extra to check for this attribute. The attribu class="cmtt-10">firstuc: the first letter of the description will be converted to upper case (using \Glsentrydesc). + id="dx1-35096">).
  • title: the description will be used in the argument of the title casing command \capitalisewords (provided by (provided by mfirstuc). If you want to use a + id="dx1-35098">). If you want to use a different command you can redefine: -


    \glsxtrfieldtitlecasecs 


    \glsxtrfieldtitlecasecs{phrase cs} -

    -

    +class="cmtt-10">}


    +

    For example:

    -
    +
    \newcommand*{\glsxtrfieldtitlecasecs}[1]{\xcapitalisefmtwords*{#1}}
    -

    (Note that the argument to

    (Note that the argument to \glsxtrfieldtitlecasecs will be a control sequence whose replacement text is the entry’s description, which is why \xcapitalisefmtwords is needed instead of \capitalisefmtwords.)

  • -

    Any other values of this attribute are ignored. Remember that there are design +

    Any other values of this attribute are ignored. Remember that there are design limitations for both the first letter uppercasing and the title casing commands. See the mfirstuc user manual for further details. + id="dx1-35100"> user manual for further details.

    glossdescfont
    (New to version 1.04) In addition to the above, the modified \glossentrydesc command also checks this attribute. If set, it should be the + id="dx1-35102"> command also checks this attribute. If set, it should be the name of a control sequence (without the leading backslash) that takes one argument. This control sequence will be applied to the description text. For example: -
    +
    \glssetcategoryattribute{general}{glossdescfont}{emph}
    -

    +

    glossname
    As glossdesc but applies to but applies to \glossentryname. Additionally, if this + id="dx1-35105">. Additionally, if this attribute is set to “uc” the name is converted to all capitals.
    indexname
    If set, the \glsxtrpostnamehook hook used at the end of \glossentryname + id="dx1-35107"> will index the entry using \index. See . See §7 §8 Auto-Indexing for further details.
    glossnamefont
    (New to version 1.04) In addition to the above, the modified \glossentryname command also checks this attribute. If set, it should be the + id="dx1-35110"> command also checks this attribute. If set, it should be the name of a control sequence (without the leading backslash) that takes one argument. This control sequence will be applied to the name text. For example: -
    +
    \glssetcategoryattribute{general}{glossnamefont}{emph}
    -

    Note that this overrides

    Note that this overrides \glsnamefont which will only be used if this attribute hasn’t been set. -

    Remember that glossary styles may additionally apply a font change, +

    Remember that glossary styles may additionally apply a font change, such as the list styles which put the name in the optional argument of \item.

    +glosssymbolfont
    (New to version 1.42.) This is similar to glossnamefont and + glossdescfont but is used by \glossentrysymbol. +
    textformat
    (New to version 1.21.) Commands like \gls and \glstext have the link @@ -15380,51 +14980,51 @@ class="cmtt-10">\glstextformat by default. If this hyperoutside
    (New to v1.21.) The attribute value may be false, true or unset. If unset, true is assumed. This indicates the default setting of the hyperoutside + id="dx1-35117"> key, described in §2.1 §2.2 Entry Indexing.
    dualindex
    If set, whenever a glossary entry has information written to the external glossary file through commands like \gls and and \glsadd, a corresponding line + id="dx1-35120">, a corresponding line will be written to the indexing file using \index. See . See §7 §8 Auto-Indexing for further details.
    targeturl
    If set, the hyperlink generated by commands like \gls will be set to the URL provided by this attributes value. For example: -
    +
    \glssetcategoryattribute{general}{targeturl}{master-doc.pdf}
    -

    (See also the accompanying sample file

    (See also the accompanying sample file sample-external.tex.) If the URL contains awkward characters (such as % or ~) remember that the base glossaries package provides commands like \glspercentchar and and \glstildechar that expand to literal characters. -

    If you want to a named anchor within the target URL (notionally adding +

    If you want to a named anchor within the target URL (notionally adding #name⟩ to the URL), then you also need to set targetname to the anchor ⟨ to the anchor ⟨name⟩. You may use \glslabel within ⟨name⟩ which is set by commands like \gls to the entry’s label. -

    All the predefined glossary styles start each entry listing with

    All the predefined glossary styles start each entry listing with \glstarget which sets the anchor to \glolinkprefix\glslabel, so if you want entries to link to glossaries in the URL given by targeturl, you can just + id="dx1-35125">, you can just do:

    -
    +
    \glssetcategoryattribute{general}{targetname}{\glolinkprefix\glslabel}
    -

    (If the target document changed

    (If the target document changed \glolinkprefix then you will need to adjust the above as appropriate.) -

    If the anchor is in the form ⟨

    If the anchor is in the form ⟨name1.name2⟩ then use targetname for the ⟨ for the ⟨name2⟩ part and targetcategory for the ⟨ for the ⟨name1⟩ part. -

    For example: +

    For example:

    -
    +
    \glssetcategoryattribute{general}{targeturl}{master-doc.pdf}  
    \glssetcategoryattribute{general}{targetcategory}{page}  
    \glssetcategoryattribute{general}{targetname}{7}
    -

    will cause all link text for

    will cause all link text for general entries to link to master-doc.pdf#page.7 (page 7 of that PDF). -

    If you want a mixture in your document of entries that link to an internal +

    If you want a mixture in your document of entries that link to an internal glossary and entries that link to an external URL then you can use the starred form of \newignoredglossary for the external list. For + id="dx1-35128"> for the external list. For example:

    -
    +
    \newignoredglossary*{external}  
    \glssetcategoryattribute{external}{targeturl}{master-doc.pdf}  
    \glssetcategoryattribute{general}{targetname}{\glolinkprefix\glslabel} @@ -15514,165 +15114,319 @@ class="cmtt-10">\newignoredglossary  category=external,  
      description={external example}}
    -

    +

    externallocation
    The value should be the file name of the target document when manually indexing an external location (see §2.1 §2.2 Entry Indexing). In general, it’s better to use bib2gls v1.7+ which can handle multiple external sources and doesn’t require this attribute.
    -

    An attribute can be set using: -


    \glssetcategoryattribute 

    If a term is defined using \newabbreviation and accessibility support has been +supplied via the accsupp package option then the following attributes are also +available. If shortaccess isn’t set its value will be obtained from: +


    \glsdefaultshortaccess{short}{long}

    +

    +This is defined by glossaries-accsupp to just do ⟨long⟩ but glossaries-extra redefines it to +do ⟨long⟩ (⟨short⟩). The accessinsertdots, accessaposplural and accessnoshortplural +attributes below refer to the ⟨short⟩ form that’s passed to this command. +

    The following attributes are only applicable to entries defined using +\newabbreviation (or \newacronym if it’s using \newabbreviation). They have no +effect if the accsupp package option hasn’t been used. +

    +accessinsertdots
    If this attribute is set to “true” and the glossaries-accsupp + package has been loaded (with the accsupp option), then this behaves + like insertdots but for the ⟨short⟩ part used in the shortaccess field instead + of the short field. This setting will be overridden by an explicit use of + the shortaccess key in the optional argument of \newabbreviation (or + \newacronym). +
    +accessaposplural
    This boolean attribute overrides aposplural for + + + + the shortpluralaccess key. Has no effect if there’s no accessibility support + or if the shortaccess key hasn’t been set or if the shortpluralaccess key + is explicitly set. If the aposplural is set and this attribute isn’t set and + the shortaccess key is set, then the aposplural setting governs the default + shortpluralaccess setting. If you want aposplural but don’t want it applied to + the accessibility support, set the accessaposplural attribute to “false”. This + attribute is only applicable to entries defined using \newabbreviation (or + \newacronym if it’s using \newabbreviation.) +
    +accessnoshortplural
    + This boolean attribute overrides noshortplural for the shortpluralaccess key. + The same conditions apply as for accessaposplural. This attribute is only + applicable to entries defined using \newabbreviation (or \newacronym if + it’s using \newabbreviation.) +
    +nameshortaccess
    If this attribute is set to “true”, the access field (used for + the name field’s accessibility support) automatically assigned if it’s not + provided. +
    +textshortaccess
    Like nameshortaccess but applies to the textaccess field + automatically assigned if it’s not provided. +
    +firstshortaccess
    Like nameshortaccess but applies to the firstaccess field + automatically assigned if it’s not provided. +
    +

    An attribute can be set using: +


    \glssetcategoryattribute{category-label} -{}{attribute-label}{value}

    -

    +class="cmtt-10">} +


    +

    where ⟨category-label⟩ is the category label, ⟨attribute-label⟩ is the attribute label and ⟨value⟩ is the new value for the attribute. -

    There is a shortcut version to set the

    There is a shortcut version to set the regular attribute to “true”: -


    \glssetregularcategory  attribute to “true”: +


    \glssetregularcategory{category-label} -

    -

    -

    If you need to lookup the category label for a particular entry, you can use the +class="cmtt-10">}


    +

    +

    If you need to lookup the category label for a particular entry, you can use the shortcut command: -


    \glssetattribute 


    \glssetattribute{entry-label}{attribute-label} -{}{value}

    -

    +

    This uses \glssetcategoryattribute with \glscategory to set the attribute. Note that this will affect all other entries that share this entry’s category. -

    You can fetch the value of an attribute for a particular category using: -


    \glsgetcategoryattribute  \glsgetcategoryattribute{category-label} -{attribute-label}

    +

    You can fetch the value of an attribute for a particular category using: -

    +


    \glsgetcategoryattribute{category-label}{attribute-label} +

    +

    Again there is a shortcut if you need to lookup the category label for a given entry: -


    \glsgetattribute 


    \glsgetattribute{entry-label}{attribute-label} -

    -

    -

    You can test if an attribute has been assigned to a given category using: -


    \glshascategoryattribute  }

    +

    +

    You can test if an attribute has been assigned to a given category using: +


    \glshascategoryattribute{category-label} -{}{attribute-label}{true codetrue +code}{false code}

    -

    +

    This uses etoolbox’s ’s \ifcsvoid and does ⟨true code⟩ if the attribute has been set and isn’t blank and isn’t \relax. The shortcut if you need to lookup the category label from an entry is: -


    \glshasattribute 


    \glshasattribute{entry-label}{attribute-label}{true +class="cmitt-10">true code⟩}{false code}{false code}

    -

    -

    You can test the value of an attribute for a particular category using: -


    \glsifcategoryattribute 

    +

    You can test the value of an attribute for a particular category using: +


    \glsifcategoryattribute{category-label} -{}{attribute-label}{value} {} +{true-part}{false-part}

    -

    +

    This tests if the attribute (given by ⟨attribute-label⟩) for the category (given by ⟨true-part⟩ is done. If the attribute isn’t set or is set but isn’t equal to ⟨value⟩, ⟨false part⟩ is done. -

    For example: +

    For example:

    -
    +
    \glsifcategoryattribute{general}{nohyper}{true}{NO HYPER}{HYPER}
    -

    This does “NO HYPER” if the

    This does “NO HYPER” if the general category has the category has the nohyper attribute set to + id="dx1-35183"> attribute set to true otherwise if does “HYPER”. -

    With boolean-style attributes like

    With boolean-style attributes like nohyper, make sure you always test for , make sure you always test for true not false in case the attribute hasn’t been set. -

    Again there’s a shortcut if you need to lookup the category label from a particular +

    Again there’s a shortcut if you need to lookup the category label from a particular entry: -


    \glsifattribute 


    \glsifattribute{entry-label}{attribute-label}{value}{true-part} {true-part} {false-part}

    -

    -

    There’s also a shortcut to determine if a particular category has the

    +

    There’s also a shortcut to determine if a particular category has the regular + id="dx1-35186"> attribute set to “true”: -


    \glsifregularcategory 


    \glsifregularcategory{category-label} -{}{true-part}{false-part}

    -

    +class="cmtt-10">} +


    +

    Alternatively, if you need to lookup the category for a particular entry: -


    \glsifregular 


    \glsifregular{entry-label}{true-part}{false-part} -

    -

    +class="cmtt-10">}


    +

    Note that if the regular attribute hasn’t be set, the above do ⟨ attribute hasn’t be set, the above do ⟨false-part⟩. There are also reverse commands that test if the regular attribute has been set to + id="dx1-35190"> attribute has been set to “false”: -


    \glsifnotregularcategory 


    \glsifnotregularcategory{category-label} -{}{true-part}{false-part}

    -

    +class="cmtt-10">} +


    +

    or for a particular entry: -


    \glsifnotregular 


    \glsifnotregular{entry-label}{true-part}{false-part} -

    -

    +class="cmtt-10">}


    +

    Again, if the regular attribute hasn’t been set, the above do ⟨ attribute hasn’t been set, the above do ⟨false-part⟩, so these reverse commands aren’t logically opposite in the strict sense. -

    You can iterate through all entries with a given category using: -


    You can iterate through all entries with a given category using: +


    \glsforeachincategory[glossary-labels]{label-cs}{body}

    -

    +

    This iterates through all entries in the glossaries identified by the comma-separated list ⟨glossary-labels⟩ that have the category given by ⟨label-cs⟩ (which much be control sequences) to access the current glossary and entry label. If ⟨glossary-labels⟩ is omitted, all glossaries are assumed. +

    Similarly, you can iterate through all entries that have a category with a given +attribute using: -

    Similarly, you can iterate through all entries that have a category with a given -attribute using: -


    \glsforeachwithattribute 


    \glsforeachwithattribute[glossary-labels] +class="cmtt-10">]{⟨attribute-label} {attribute-label} {attribute-value}{glossary-cs}{label-cs}{body} -

    -

    +class="cmtt-10">}


    +

    This will do ⟨body⟩ for each entry that has a category with the attribute ⟨attribute-label⟩ set to ⟨attribute-value⟩. The remaining arguments are as the previous command. -

    You can change the category for a particular entry using the standard glossary +

    You can change the category for a particular entry using the standard glossary field changing commands, such as \glsfielddef. Alternatively, you can + id="dx1-35195">. Alternatively, you can use -


    \glsxtrsetcategory 


    \glsxtrsetcategory{entry-labels}{category-label} -

    -

    +class="cmtt-10">}


    +

    This will change the category to ⟨category-label⟩ for each entry listed in the comma-separated list ⟨entry-labels⟩. This command uses \glsfieldxdef so it will + id="dx1-35197"> so it will expand ⟨category-label⟩ and make the change global. -

    You can also change the category for all entries with a glossary or glossaries +

    You can also change the category for all entries with a glossary or glossaries using: -


    \glsxtrsetcategoryforall 


    \glsxtrsetcategoryforall{glossary-labels} -{}{category-label}

    -

    +class="cmtt-10">} +


    +

    where ⟨glossary-labels⟩ is a comma-separated list of glossary labels.

    -

    -

    Top

    6.

    +

    Top

    7. Counting References

    -

    There are three basic ways of counting entry references: +

    There are three basic ways of counting entry references:

    1. Counting the total number of times Counting the total number of times \glsunset is used (\glsreset resets the count and is best avoided). This is provided by the base glossaries class="cmtt-10">.aux file so that it’s available on the next LATEX run. -

      This method is extended by

      This method is extended by glossaries-extra and is described in §6.1 §7.1 Entry Counting (First Use Flag).

    2. Counting the total number of records. This method is only available with + class="enumerate" id="x1-36004x2">Counting the total number of records. This method is only available with bib2gls and is intended for documents where the term should be displayed differently if it’s only been recorded (indexed) a certain number of times. @@ -15943,7 +15674,7 @@ class="cmsy-10">§9.5 Record Counting for further details.
    3. Counting the number of times the Counting the number of times the \gls-like or \glstext-like commands are used. (That is, those commands that internally use @@ -15958,52 +15689,52 @@ class="cmtt-10">\glslinkpostsetkeys or \glslinkpresetkeys. See §6.2 §7.2 Link Counting for further details.
    -

    Top

    6.1

    Top

    7.1 Entry Counting (First Use Flag)

    -

    As mentioned in

    As mentioned in §2.4 §2.5 Entry Counting Modifications, glossaries-extra modifies the \glsenableentrycount command to allow for the command to allow for the entrycount attribute. This means + id="dx1-37002"> attribute. This means that you not only need to enable entry counting with \glsenableentrycount, but + id="dx1-37003">, but you also need to set the appropriate attribute (see §5 §6 Categories). -

    Remember that entry counting only counts the number of times an entry is used +

    Remember that entry counting only counts the number of times an entry is used by commands that change the first use flag. (That is, all those commands that mark the entry as having been used.) There are many commands that don’t modify this flag and they won’t contribute to the entry use count.
    -

    -

    With

    +

    With glossaries-extra, you may use \cgls instead of instead of \gls even if you haven’t enabled + id="dx1-37006"> even if you haven’t enabled entry counting. You will only get a warning if you use \glsenableentrycount without setting the entrycount attribute. (With attribute. (With glossaries, commands like \cgls + id="dx1-37008"> will generate a warning if \glsenableentrycount hasn’t been used.) The @@ -16011,40 +15742,38 @@ class="cmtt-10">\glsenableentrycount hasn’t been used.) The abbreviation shortcut \ab uses uses \cgls (see §3.3 §4.3 Shortcut Commands). The acronym shortcut \ac uses uses \cgls if it’s been defined with shortcuts=ac (or + id="dx1-37011"> (or shortcuts=all) but uses ) but uses \gls if it’s been defined with shortcuts=acronyms (or + id="dx1-37013"> (or shortcuts=acro). -

    All upper case versions (not provided by ). +

    All upper case versions (not provided by glossaries) are also available: -


    \cGLS 


    \cGLS[options]{label}[insert]

    -

    +

    and -


    \cGLSpl 


    \cGLSpl[options]{label}[insert]

    -

    +

    These are analogous to \cgls and \cglspl but they use -


    \cGLSformat 


    \cGLSformat{label}{insert}

    -

    +

    and -


    \cGLSplformat 


    \cGLSplformat{label}{insert}

    -

    +

    which convert the analogous \cglsformat and \cglsplformat to upper case. -

    Just using

    Just using glossaries:

    -
    +
    \documentclass{article}  
    \usepackage{glossaries}  
    \makeglossaries @@ -16113,17 +15836,17 @@ class="cmss-10">glossaries:  
    \printglossaries  
    \end{document}
    -

    -

    If you switch to

    +

    If you switch to glossaries-extra you must set the entrycount attribute: + id="dx1-37019"> attribute:

    -
    +
    \documentclass{article}  
    \usepackage{glossaries-extra}  
    \makeglossaries @@ -16137,31 +15860,27 @@ class="cmss-10">entrycount\printglossaries  
    \end{document}
    -

    -

    When activated with

    +

    When activated with \glsenableentrycount, commands such as \cgls now + id="dx1-37020"> now use -


    \glsxtrifcounttrigger 


    \glsxtrifcounttrigger{label}{trigger code} -{}{normal code}

    -

    +

    to determine if the entry trips the entry count trigger. The ⟨trigger code⟩ uses commands like \cglsformat and unsets the first use flag. The ⟨normal code⟩ is the code that would ordinarily be performed by whatever the equivalent command is (for @@ -16172,12 +15891,12 @@ class="cmti-10">trigger code⟩ but the usual \gls behaviour in ⟨normal code⟩). -

    The default definition is: +

    The default definition is:

    -
    +
    \newcommand*{\glsxtrifcounttrigger}[3]{%  
     \glshasattribute{#1}{entrycount}%  
     {% @@ -16190,57 +15909,53 @@ class="cmti-10">normal code⟩).  
     {#3}%  
    }
    -

    This means that if an entry is assigned to a category that has the

    This means that if an entry is assigned to a category that has the entrycount + id="dx1-37023"> attribute then the ⟨trigger code⟩ will be used if the previous count value (the number of times the entry was used on the last run) is greater than the value of the attribute. -

    For example, to trigger normal use if the previous count value is greater than +

    For example, to trigger normal use if the previous count value is greater than four:

    -
    +
    \glssetcategoryattribute{abbreviation}{entrycount}{4}
    -

    -

    There is a convenient command provided to enable entry counting, set the +

    +

    There is a convenient command provided to enable entry counting, set the entrycount attribute and redefine attribute and redefine \gls, etc to use , etc to use \cgls etc: -


    \GlsXtrEnableEntryCounting  etc: +


    \GlsXtrEnableEntryCounting{categories} -{}{value}

    -

    +

    The first argument ⟨categories⟩ is a comma-separated list of categories. For each category, the entrycount attribute is set to ⟨ attribute is set to ⟨value⟩. In addition, this does:

    -
    +
    \renewcommand*{\gls}{\cgls}%  
    \renewcommand*{\Gls}{\cGls}%  
    \renewcommand*{\glspl}{\cglspl}% @@ -16248,19 +15963,19 @@ class="cmti-10">value⟩. In addition, this does:  
    \renewcommand*{\GLS}{\cGLS}%  
    \renewcommand*{\GLSpl}{\cGLSpl}%
    -

    This makes it easier to enable entry-counting on existing documents. -

    If you use

    This makes it easier to enable entry-counting on existing documents. +

    If you use \GlsXtrEnableEntryCounting more than once, subsequent uses will just set the entrycount attribute for each listed category. -

    The above example document can then become: + id="dx1-37029"> attribute for each listed category. +

    The above example document can then become:

    -
    +
    \documentclass{article}  
    \usepackage{glossaries-extra}  
    \makeglossaries @@ -16273,45 +15988,42 @@ class="cmss-10">entrycount\printglossaries  
    \end{document}
    -

    -

    The standard entry-counting function describe above counts the number of times +

    +

    The standard entry-counting function describe above counts the number of times an entry has been marked as used throughout the document. (The reset commands will reset the total back to zero.) If you prefer to count per sectional-unit, you can use -


    \GlsXtrEnableEntryUnitCounting  \GlsXtrEnableEntryUnitCounting -{


    \GlsXtrEnableEntryUnitCounting{categories}{value}{counter-name}

    -

    +class="cmtt-10">} +


    +

    where ⟨categories⟩ is a comma-separated list of categories to which this feature should be applied, ⟨value⟩ is the trigger value and ⟨counter-name⟩ is the name of the counter used by the sectional unit. -

    Due to the asynchronous nature of T

    Due to the asynchronous nature of TEX’s output routine, discrepancies will occur in page spanning paragraphs if you use the page counter.
    -

    -

    Note that you can’t use both the document-wide counting and the per-unit + id="dx1-37031"> counter.

    +

    +

    Note that you can’t use both the document-wide counting and the per-unit counting in the same document. -

    The counter value is used as part of a label, which means that

    The counter value is used as part of a label, which means that \thecounter-name⟩ needs to be expandable. Since hyperref also has a similar requirement and provides + id="dx1-37032"> also has a similar requirement and provides \theHcounter-name⟩ as an expandable alternative, \theHcounter-name⟩ if it exists otherwise it will use \thecounter-name⟩. -

    The per-unit counting function uses two attributes:

    The per-unit counting function uses two attributes: entrycount (as before) and + id="dx1-37033"> (as before) and unitcount (the name of the counter). -

    Both the original document-wide counting mechanism and the per-unit counting + id="dx1-37034"> (the name of the counter). +

    Both the original document-wide counting mechanism and the per-unit counting mechanism provide a command that can be used to access the current count value for this run: -


    \glsentrycurrcount 


    \glsentrycurrcount{label}

    -

    +

    and the final value from the previous run: -


    \glsentryprevcount 


    \glsentryprevcount{label}

    -

    +

    In the case of the per-unit counting, this is the final value for the current unit. In both commands ⟨label⟩ is the entry’s label. -

    The per-unit counting mechanism additionally provides: -


    \glsentryprevtotalcount 

    The per-unit counting mechanism additionally provides: +


    \glsentryprevtotalcount{label}

    -

    +

    which gives the sum of all the per-unit totals from the previous run for the entry given by ⟨label⟩, and -


    \glsentryprevmaxcount 


    \glsentryprevmaxcount{label}

    -

    +

    which gives the maximum per-unit total from the previous run. -

    The above two commands are unavailable for the document-wide counting. -

    Example of per-unit counting, where the unit is the chapter: +

    The above two commands are unavailable for the document-wide counting. +

    Example of per-unit counting, where the unit is the chapter:

    -
    +
    \documentclass{report}  
    \usepackage{glossaries-extra}  
    \GlsXtrEnableEntryUnitCounting{abbreviation}{2}{chapter} @@ -16402,11 +16106,11 @@ which gives the maximum per-unit total from the previous run.  
    \printglossaries  
    \end{document}
    -

    In this document, the

    In this document, the css entry is used three times in the first chapter. This is more than the trigger value of 2, so \gls{css} is expanded on first use with the short form used on subsequent use, and the css entries in that @@ -16416,40 +16120,38 @@ only used once, which trips the suppression trigger, so in that chapter, the long form is used and \gls{css} doesn’t get a line added to the glossary file. -

    The

    The html is used a total of three times, but the expansion and indexing suppression trigger is tripped in both chapters because the per-unit total (1 for the first chapter and 2 for the second chapter) is less than or equal to the trigger value. -

    The

    The sample entry has only been used once, but it doesn’t trip the indexing suppression because it’s in the general category, which hasn’t been listed in + id="dx1-37040"> category, which hasn’t been listed in \GlsXtrEnableEntryUnitCounting. -

    The per-unit entry counting can be used for other purposes. In the following +

    The per-unit entry counting can be used for other purposes. In the following example document the trigger value is set to zero, which means the index suppression won’t be triggered, but the unit entry count is used to automatically suppress the hyperlink for commands like \gls by modifying the hook -


    \glslinkcheckfirsthyperhook  by modifying the hook +


    \glslinkcheckfirsthyperhook

    -

    +

    which is used at the end of the macro the determines whether or not to suppress the hyperlink.

    -
    +
    \documentclass{article}  
    \usepackage[colorlinks]{hyperref}  
    \usepackage{glossaries-extra} @@ -16470,22 +16172,22 @@ hyperlink.  
    \printglossaries  
    \end{document}
    -

    This only produces a hyperlink for the first instance of

    This only produces a hyperlink for the first instance of \gls{sample} on each page. -

    The earlier warning about using the

    The earlier warning about using the page counter still applies. If the + id="dx1-37043"> counter still applies. If the first instance of \gls occurs at the top of the page within a paragraph that started on the previous page, then the count will continue from the previous page. -

    +

    -

    Top

    6.2

    Top

    7.2 Link Counting

    -

    As from version 1.26, an alternative method of entry counting is to count the number +

    As from version 1.26, an alternative method of entry counting is to count the number @@ -16499,21 +16201,17 @@ class="cmtt-10">\hyperlink although \@gls@link may use \hyperlink when displaying the link-text.) -

    To enable link counting use the preamble-only command: -


    \GlsXtrEnableLinkCounting 

    To enable link counting use the preamble-only command: +


    \GlsXtrEnableLinkCounting[master counter] -{]{categories}

    -

    +

    where ⟨categories⟩ is a list of category labels. The optional argument ⟨master @@ -16523,24 +16221,22 @@ present, the associated link counter will be reset when the master counter is incremented. This command automatically sets the linkcount attribute for the given + id="dx1-38003"> attribute for the given categories. If the optional argument is present, it also sets the linkcountmaster + id="dx1-38004"> attribute. -

    When enabled, commands like

    When enabled, commands like \gls and \glstext increment the associated counter using -


    \glsxtrinclinkcounter 


    \glsxtrinclinkcounter{counter name}

    -

    +

    This just does \stepcounter{counter name\refstepcounter instead, just redefine this command:

    -
    +
    \renewcommand*{\glsxtrinclinkcounter}[1]{\refstepcounter{#1}}
    -

    -

    You can access the internal count register using -


    \GlsXtrLinkCounterValue 

    +

    You can access the internal count register using +


    \GlsXtrLinkCounterValue{label}

    -

    +

    where ⟨label⟩ is the entry’s label. This will expand to 0 if the counter hasn’t been defined. -

    It’s also possible to access the display value (

    It’s also possible to access the display value (\thecounter⟩) using -


    \GlsXtrTheLinkCounter 


    \GlsXtrTheLinkCounter{counter}

    -

    +

    (This will expand to 0 if the counter hasn’t been defined.) -

    In order to conserve resources, the counter is only defined when it first +

    In order to conserve resources, the counter is only defined when it first needs to be incremented so terms that have been defined but haven’t been used in the document won’t have the associated count register allocated.
    -

    -

    You can test if the counter has been defined using: -


    \GlsXtrIfLinkCounterDef 

    +

    You can test if the counter has been defined using: +


    \GlsXtrIfLinkCounterDef{label}{true}{false} -

    -

    +class="cmtt-10">}


    +

    where ⟨label⟩ is the entry’s label. -

    The counter name can be obtained using -


    \GlsXtrLinkCounterName 

    The counter name can be obtained using +


    \GlsXtrLinkCounterName{label}

    -

    +

    This simply expands to the counter name associated with the entry given by ⟨label⟩ without any check for existence. For example, to change the display command @@ -16616,15 +16303,15 @@ without any check for existence. For example, to change the display command class="cmtt-10">\the⟨counter⟩) using etoolbox: + id="dx1-38010">:

    -
    +
    \csdef{the\GlsXtrLinkCounterName{duck}}{\Roman{\GlsXtrLinkCounterName{duck}}}
    -

    This is useful if you just want to change the display for specific entries but isn’t +

    This is useful if you just want to change the display for specific entries but isn’t convenient if you want to change the display for all entries. Instead, it’s simpler to redefine \GlsXtrTheLinkCounter. For example: @@ -16632,19 +16319,19 @@ class="cmtt-10">\GlsXtrTheLinkCounter. For example:

    -
    +
    \renewcommand*{\GlsXtrTheLinkCounter}[1]{%  
     \GlsXtrIfLinkCounterDef{#1}%  
     {\Roman{\GlsXtrLinkCounterName{#1}}}%  
     {0}%  
    }
    -

    In both cases, the redefinition should be implemented after

    In both cases, the redefinition should be implemented after \GlsXtrEnableLinkCounting. -

    Here’s an example document that uses link counting to disable the hyperlink after +

    Here’s an example document that uses link counting to disable the hyperlink after the first reference. This redefines \glslinkpresetkeys (which is used by both (which is used by both \gls and \glstext) instead of \glstext).

    -
    +
    \documentclass{article}  
    \usepackage[colorlinks]{hyperref}  
    \usepackage{glossaries-extra} @@ -16679,32 +16366,32 @@ class="cmtt-10">\glstext).  
    \printglossaries  
    \end{document}
    -

    The use of

    The use of \glslinkpresetkeys means that the options can override this. For + id="dx1-38012"> means that the options can override this. For example

    -
    +
    \gls[hyper=true]{sample1}
    -

    will override the

    will override the hyper=false setting in \glslinkpresetkeys. If . If \glslinkpostsetkeys + id="dx1-38014"> is used instead, the hyper=false setting will override the setting provided in the optional argument. -

    The

    The abbreviation category doesn’t have the category doesn’t have the linkcount attribute set (since it’s not + id="dx1-38016"> attribute set (since it’s not listed in the argument of \GlsXtrEnableLinkCounting). This means that -

    +
    \ifnum\GlsXtrLinkCounterValue{\glslabel}>1
    -

    will always be false. This means that the abbreviation won’t have

    will always be false. This means that the abbreviation won’t have hyper=false applied. If the test is changed to

    -
    +
    \ifnum\GlsXtrLinkCounterValue{\glslabel}=1  
    \else  
     \setkeys{glslink}{hyper=false}%  
    \fi
    -

    Then the abbreviation will always have

    Then the abbreviation will always have hyper=false applied. -

    To reset the counter every section use the optional argument to set the master +

    To reset the counter every section use the optional argument to set the master counter:

    -
    +
    \GlsXtrEnableLinkCounting[section]{general}
    -

    +

    -

    -

    Top

    7.

    +

    Top

    8. Auto-Indexing

    -

    It’s possible that you may also want a normal index as well as the glossary, +

    It’s possible that you may also want a normal index as well as the glossary, and you may want entries to automatically be added to the index (as in this document). There are two attributes that govern this: indexname and + id="dx1-39001"> and dualindex. -

    The auto-indexing is designed for . +

    The auto-indexing is designed for makeindex syntax. If you’ve used the xindy + id="dx1-39004"> package option, the automatic escaping of xindy special characters in the sort field + id="dx1-39006"> field may result in an incorrect sort value for the \index command used by the auto-indexing. Note also that texindy has a fixed set of special characters + id="dx1-39007"> has a fixed set of special characters (corresponding to makeindex’s defaults) that can’t be customized. You may want to consider using bib2gls and its dual entries as an alternative approach.
    -

    -

    The

    +

    The \glsxtrpostnamehook macro, used at the end of macro, used at the end of \glossentryname and + id="dx1-39011"> and \Glossentryname, checks the , checks the indexname attribute for the category associated with + id="dx1-39013"> attribute for the category associated with that entry. Since \glossentryname is used in the default glossary styles, this makes a convenient way of automatically indexing each entry name at its location in the glossary without fiddling around with the value of the name + id="dx1-39014"> key. -

    The internal macro used by the

    The internal macro used by the glossaries package to write the information to the external glossary file is modified to check for the dualindex attribute. -

    In both cases, the indexing is done through -


    \glsxtrdoautoindexname  attribute. +

    In both cases, the indexing is done through +


    \glsxtrdoautoindexname{label}{attribute-label} -

    -

    +class="cmtt-10">}


    +

    This uses the standard \index command with the sort value taken from the entry’s + id="dx1-39017"> command with the sort value taken from the entry’s sort key and the actual value set to key and the actual value set to \glsentryname{label}. As from v1.16, there are user-level commands available to change the sort and actual value used by the automated index. -

    The actual value is given by -


    \glsxtrautoindexentry 

    The actual value is given by +


    \glsxtrautoindexentry{label}

    -

    +

    where ⟨label⟩ is the entry’s label. The default definition is:

    -
    +
    \newcommand*{\glsxtrautoindexentry}[1]{\string\glsentryname{#1}}
    -

    Note the use of

    Note the use of \string to prevent \glsentryname from being expanded as it’s written to the index file. -

    The sort value is assigned using: -


    \glsxtrautoindexassignsort 

    The sort value is assigned using: +


    \glsxtrautoindexassignsort{cs}{label} -

    -

    +class="cmtt-10">}


    +

    where ⟨label⟩ is the entry label and ⟨cs⟩ is the command which needs to be set to the @@ -16877,458 +16556,212 @@ sort value. The default definition is:

    -
    +
    \newcommand*{\glsxtrautoindexassignsort}[2]{%  
      \glsletentryfield{#1}{#2}{sort}%  
    }
    -

    After this macro is called, ⟨

    After this macro is called, ⟨cs⟩ is then processed to escape any of makeindex’s special + id="dx1-39021">’s special characters. Note that this escaping is only performed on the sort not on the actual value. The escaping of the sort value is performed by -


    \glsxtrautoindexesc 


    \glsxtrautoindexesc

    -

    +

    You can redefine this to do nothing if you want to omit the escaping. You may want to consider providing another field to obtain the appropriate sort value if the one provided in the sort field isn’t suitable (because it may already have had special + id="dx1-39023"> field isn’t suitable (because it may already have had special characters escaped or it may be a numeric value in the case of sort by use or definition). -

    The command used to perform the actual indexing is: -


    \glsxtrautoindex 

    The command used to perform the actual indexing is: +


    \glsxtrautoindex{text}

    -

    +

    This just does \index{text} by default. -

    The entry’s

    The entry’s parent field isn’t referenced in this automated indexing. + id="dx1-39025"> field isn’t referenced in this automated indexing.
    -

    -

    For example, to index the value of the

    +

    For example, to index the value of the first key, instead of the key, instead of the name key: + id="dx1-39027"> key:

    -
    +
    \renewcommand*{\glsxtrautoindexentry}[1]{\string\glsentryfirst{#1}}
    -

    and if the sort value also needs to be set to the

    and if the sort value also needs to be set to the long field, if present, otherwise the + id="dx1-39028"> field, if present, otherwise the sort field: + id="dx1-39029"> field:

    -
    +
    \renewcommand*{\glsxtrautoindexassignsort}[2]{%  
      \ifglshaslong{#2}%  
      {\glsletentryfield{#1}{#2}{long}}%  
      {\glsletentryfield{#1}{#2}{sort}}%  
    }
    -

    -

    If the value of the attribute given by ⟨

    +

    If the value of the attribute given by ⟨attribute-label⟩ is “true”, no encap will be added, otherwise the encap will be the attribute value. For example:

    -
    +
    \glssetcategoryattribute{general}{indexname}{textbf}
    -

    will set the encap to

    will set the encap to textbf which will display the relevant page number in bold whereas

    -
    +
    \glssetcategoryattribute{general}{dualindex}{true}
    -

    won’t apply any formatting to the page number in the index. -

    The location used in the index will always be the page number not the counter +

    won’t apply any formatting to the page number in the index. +

    The location used in the index will always be the page number not the counter used in the glossary. (Unless some other loaded package has modified the definition of \index to use some thing else.)
    -

    -

    By default the

    +

    By default the format key won’t be used with the key won’t be used with the dualindex attribute. You can + id="dx1-39031"> attribute. You can allow the format key to override the attribute value by using the preamble-only + id="dx1-39032"> key to override the attribute value by using the preamble-only command: -


    \GlsXtrEnableIndexFormatOverride  \GlsXtrEnableIndexFormatOverride -

    -

    +


    \GlsXtrEnableIndexFormatOverride

    +

    If you use this command and hyperref has been loaded, then the has been loaded, then the theindex + id="dx1-39035"> environment will be modified to redefine \glshypernumber to allow formats that use + id="dx1-39037"> to allow formats that use that command. -

    The

    The dualindex attribute will still be used on subsequent use even if the + id="dx1-39038"> attribute will still be used on subsequent use even if the indexonlyfirst attribute (or attribute (or indexonlyfirst package option) is set. However, the package option) is set. However, the dualindex + id="dx1-39041"> attribute will honour the noindex key.
    -

    -

    The key.

    +

    +

    The \glsxtrdoautoindexname command will attempt to escape any of \makeindex’s special characters, but there may be special cases where it fails, so take + id="dx1-39043">’s special characters, but there may be special cases where it fails, so take care. This assumes the default makeindex actual, level, quote and encap values (unless any of the commands \actualchar, , \levelchar, , \quotechar or or \encapchar + id="dx1-39048"> have been defined before glossaries-extra is loaded). -

    If this isn’t the case, you can use the following preamble-only commands to set +

    If this isn’t the case, you can use the following preamble-only commands to set the correct characters. -

    Be very careful of possible shifting category codes!
    -

    -


    \GlsXtrSetActualChar 

    Be very careful of possible shifting category codes!
    +

    +


    \GlsXtrSetActualChar{char}

    -

    -Set the actual character to ⟨char⟩. -


    \GlsXtrSetLevelChar  \GlsXtrSetLevelChar{char}

    -

    -Set the level character to ⟨char⟩. -


    \GlsXtrSetEscChar  \GlsXtrSetEscChar{char}

    -

    -Set the escape (quote) character to ⟨char⟩. -


    \GlsXtrSetEncapChar  \GlsXtrSetEncapChar{char}

    - - - -

    -Set the encap character to ⟨char⟩. - - - -

    -

    -

    Top

    8. On-the-Fly Document Definitions

    -

    The commands described here may superficially look like ⟨word\index{word}, -but they behave rather differently. If you want to use \index then just use \index. -
    -

    -

    The glossaries package advises against defining entries in the document -environment. As mentioned in §1.2 New or Modified Package Options above, this -ability is disabled by default with glossaries-extra but can be enabled using the -docdefs package options. -

    Although this can be problematic, the glossaries-extra package provides a way of -defining and using entries within the document environment without the tricks used -with the docdefs option. There are limitations with this approach, so take care with it. -This function is disabled by default, but can be enabled using the preamble-only -command: -


    \GlsXtrEnableOnTheFly  \GlsXtrEnableOnTheFly

    -

    -When used, this defines the commands described below. -

    The commands \glsxtr, \glsxtrpl, \Glsxtr and \Glsxtrpl can’t be used after -the glossaries have been displayed (through \printglossary etc). It’s best not to -mix these commands with the standard glossary commands, such as \gls or there -may be unexpected results.
    -

    -


    \glsxtr  \glsxtr[gls-options][dfn-options]{label}

    -

    -If an entry with the label ⟨label⟩ has already been defined, this just does \gls -[gls-options]{label}. If ⟨label⟩ hasn’t been defined, this will define the entry using: -

    -
    -\newglossaryentry{label}{name={label}, -
     category=\glsxtrcat, -
     description={\nopostdesc}, -
     dfn-options} -
    -
    -

    The ⟨label⟩ must contain any non-expandable commands, such as formatting -commands or problematic characters. If the term requires any of these, they must be -omitted from the ⟨label⟩ and placed in the name key must be provided in the optional -argument ⟨dfn-options⟩.
    -

    - - - -

    The second optional argument ⟨dfn-options⟩ should be empty if the entry has -already been defined, since it’s too late for them. If it’s not empty, a warning will be -generated with -


    \GlsXtrWarning  \GlsXtrWarning{dfn-options}{label

    +Set the actual character to ⟨char⟩. +


    \GlsXtrSetLevelChar{char}

    +

    +Set the level character to ⟨char⟩. +


    \GlsXtrSetEscChar{char}

    +

    +Set the escape (quote) character to ⟨char⟩. +


    \GlsXtrSetEncapChar{char}

    -

    -

    For example, this warning will be generated on the second instance of \glsxtr -below: - - - -

    -
    -\glsxtr[][plural=geese]{goose} - 
     ... later - 
    \glsxtr[][plural=geese]{goose} -
    -

    -

    If you are considering doing something like: -

    -
    -\newcommand*{\goose}{\glsxtr[][plural=geese]{goose}} - 
    \renewcommand*{\GlsXtrWarning}[2]{} - 
     ... later - 
    \goose\ some more text here -
    -

    then don’t bother. It’s simpler and less problematic to just define the entries in the -preamble with \newglossaryentry and then use \gls in the document. -

    There are plural and case-changing alternatives to \glsxtr: -


    \glsxtrpl  \glsxtrpl[gls-options][dfn-options]{label}

    -

    -This is like \glsxtr but uses \glspl instead of \gls. -


    \Glsxtr  \Glsxtr[gls-options][dfn-options]{label}

    -

    -This is like \glsxtr but uses \Gls instead of \gls. -


    \Glsxtrpl  \Glsxtrpl[gls-options][dfn-options]{label}

    -

    -This is like \glsxtr but uses \Glspl instead of \gls. -

    If you use UTF-8 and don’t want the inconvenient of needing to use an -ASCII-only label, then it’s better to use XƎLATEX or LuaLATEX instead of -LATEX (or pdfLATEX). If you really desperately want to use UTF-8 entry labels -without switching to XƎLATEX or LuaLATEX then there is a starred version of -\GlsXtrEnableOnTheFly that allows you to use UTF-8 characters in ⟨label⟩, but it’s -experimental and may not work in some cases. -

    If you use the starred version of \GlsXtrEnableOnTheFly don’t use any -commands in the ⟨label⟩, even if they expand to just text.
    -

    +

    +Set the encap character to ⟨char⟩.

    -

    -

    +

    Top

    9. bib2gls: Managing Reference Databases

    -

    There is a new command line application called

    There is a new command line application called bib2gls, which works in much the same way as a combination of \input or \loadglsentries, the entries can instead be stored in a .bib file and bib2gls can selectively write the appropriate commands to a .glstex file which is loaded using \glsxtrresourcefile (or \GlsXtrLoadResources). -

    This means that you can use a reference managing system, such as JabRef, to +

    This means that you can use a reference managing system, such as JabRef, to maintain the database and it reduces the TEX overhead by only defining the entries that are actually required in the document. If you currently have a .tex file containing glossary definitions to a .bib file using convertgls2bib, supplied with + id="dx1-40003">, supplied with bib2gls.) -

    There are some new commands and options added to

    There are some new commands and options added to glossaries-extra to help assist the integration of bib2gls into the document build process. -

    This chapter just provides a general overview of

    This chapter just provides a general overview of bib2gls. The full details and some sample documents are provided in the bib2gls manual. -

    An example of the contents of

    An example of the contents of .bib file that stores glossary entries that can be extracted with bib2gls:

    -
    +
    @entry{bird,  
      name={bird},  
      description = {feathered animal}, @@ -17401,13 +16834,13 @@ class="cmtt-10">bib2gls:  
      description={a waterbird with a long neck}  
    }
    -

    -

    The follow provides some abbreviations: +

    +

    The follow provides some abbreviations:

    -
    +
    @string{ssi={server-side includes}}  
    @string{html={hypertext markup language}}  
    @abbreviation{shtml, @@ -17426,13 +16859,13 @@ class="cmtt-10">bib2gls:  
      description={a simple interpreted server-side scripting language}  
    }
    -

    -

    Here are some symbols: +

    +

    Here are some symbols:

    -
    +
    preamble{"\providecommand{\mtx}[1]{\boldsymbol{#1}}"}  
    @symbol{M,  
      name={$\mtx{M}$}, @@ -17450,74 +16883,69 @@ preamble{"\providecommand{\mtx}[1]{\boldsymbol{#1}}"}  
      description={a set}  
    }
    -

    -

    To ensure that

    +

    To ensure that bib2gls can find out which entries have been used in the document, you need the record package option: + id="dx1-40010"> package option:

    -
    +
    \usepackage[record]{glossaries-extra}
    -

    If this option’s value is omitted (as above), the normal indexing will be switched off, +

    If this option’s value is omitted (as above), the normal indexing will be switched off, since bib2gls can also sort the entries and collate the locations. -

    If you still want to use an indexing application (for example, you need a custom +

    If you still want to use an indexing application (for example, you need a custom xindy rule), then just use record=alsoindex and continue to use and continue to use \makeglossaries and \printglossary (or \printglossaries), but you also need to instruct bib2gls to omit sorting to save time and to prevent the sort key from being + id="dx1-40015"> key from being set. -

    The

    The .glstex file created by bib2gls is loaded using: -


    \glsxtrresourcefile 


    \glsxtrresourcefile[options]{filename} -

    -

    +class="cmtt-10">}


    +

    (Don’t include the file extension in ⟨filename⟩.) There’s a shortcut version (recommended over the above) that sets ⟨filename⟩ to use \jobname: -


    \GlsXtrLoadResources 


    \GlsXtrLoadResources[options]

    -

    +

    On the first use, this command is a shortcut for

    }
    On subsequent use,9.1 this + id="x1-40019f1"> this command is a shortcut for
    }
    where ⟨n⟩ is the current value of -



    \glsxtrresourcecount

    -

    +

    which is incremented at the end of \GlsXtrLoadResources. Any advisory notes regarding \glsxtrresourcefile also apply to \GlsXtrLoadResources. -

    The

    The \glsxtrresourcefile command writes the line

    filename.glstex if it exists.9.2 + id="x1-40020f2"> -

    Since the

    Since the .glstex file won’t exist on the first LATEX run, the record package + id="dx1-40021"> package option additionally switches on undefaction=warn. Any use of commands like . Any use of commands like \gls or \glstext will produce ?? in the document, since the entries are undefined at this point. Once bib2gls has created the .glstex file the references should be resolved. This may cause a shift in the locations if the actual text produced once the entry is defined is significantly larger than the placeholder ?? (as this can alter the page breaking). -

    Note that as from v1.12,

    Note that as from v1.12, \glsxtrresourcefile temporarily switches the category code of @ to 11 (letter) while it reads the file to allow for any internal commands stored in the location field.

    -

    Top

    9.1 Selection

    -

    The default behaviour is for

    The default behaviour is for bib2gls to select all entries that have a record in the .aux file, and any dependent entries (including parent an class="cmtt-10">glsignore format (for example, \gls[format=glsignore]{duck}) is recognised by bib2gls as a special ignored record. This means that it will match the selection criteria but the record won’t be added to the location list. This means that you won’t get spurious commas in the location list (as can happen with the other indexing @@ -17621,66 +17049,66 @@ methods), so you can do, for example,

    -
    +
    \GlsXtrSetDefaultNumberFormat{glsignore}
    -

    at the start of the front matter and +

    at the start of the front matter and

    -
    +
    \GlsXtrSetDefaultNumberFormat{glsnumberformat}
    -

    at the start of the main matter to prevent any records in the front matter from +

    at the start of the main matter to prevent any records in the front matter from occurring in the location lists. -

    Note that commands like

    Note that commands like \glsaddall and \glsaddallunused don’t work with bib2gls as the command has to iterate over the internal lists of defined entry labels, which will be empty on the first run and on subsequent runs will only contain those entries that have been selected by bib2gls.
    -

    -

    If you want to add all entries to the glossary, you need to tell

    +

    If you want to add all entries to the glossary, you need to tell bib2gls this in the options list. For example:

    -
    +
    \GlsXtrLoadResources[src={terms},selection={all}]
    -

    This will add all entries, regardless of whether or not they have any records in the +

    This will add all entries, regardless of whether or not they have any records in the .aux file. Those that don’t have any records will have an empty location list. See the bib2gls user manual for more details of this option. -

    +

    -

    Top

    9.2 Sorting and Displaying the Glossary

    -

    There are many sorting options provided by

    There are many sorting options provided by bib2gls. The default is to sort according to the system locale. If the document has a language setting, you can use sort=doc to instruct bib2gls to sort according to that. (The language tag obtained from tracklang’s interface is written to the ’s interface is written to the .aux file.) For a multilingual document you need to explicitly set the locale using a well-formed language tag. For example: @@ -17688,26 +17116,26 @@ example:

    -
    +
    \GlsXtrLoadResources[  
      src=terms, % data in terms.bib  
      sort=de-DE-1996 % sort according to this locale  
    ]
    -

    The locale-sensitive sort methods usually ignore most punctuation so for lists of +

    The locale-sensitive sort methods usually ignore most punctuation so for lists of symbols you may find it more appropriate to use one of the letter-base sort methods that sort according to the Unicode value of each character. Alternatively you can provide a custom rule. See the bib2gls manual for full details of all the available sort methods. -

    Since the

    Since the .glstex file only defines those references required within the document (selected according to the selection option) and the definitions have been written in the order corresponding to bib2gls’s sorted list, the glossaries can simply be displayed using \printunsrtglossary (or \printunsrtglossaries), described in href="#sec:printunsrt">§10.2 Display All Entries Without Sorting or Indexing. -

    Suppose the

    Suppose the .bib examples shown above have been stored in the files terms.bib, EX’s path. Then the document might look like:

    -
    +
    \documentclass{article}  
    \usepackage[record]{glossaries-extra}  
    \setabbreviationstyle{long-short-desc} @@ -17740,18 +17168,18 @@ class="E">EX’s path. Then the document might look like:  
    \printunsrtglossaries  
    \end{document}
    -

    The document build process (assuming the document is called

    The document build process (assuming the document is called mydoc) is:

    -
    +
    pdflatex mydoc  
    bib2gls mydoc  
    pdflatex mydoc
    -

    This creates a single glossary containing the entries:

    This creates a single glossary containing the entries: bird, duck, goose, bird, shtml and M entries were added because bib2gls detected (from the .aux file) that they had been used in the document. The other entries were added because bib2gls detected (from the .bib files) that they are referenced by the used entries. In the case of duck and goose, they are in the see field for field for bird. In the case of ssi and html, they are referenced in the description field of field of shtml. These cross-referenced entries won’t have a location list when the glossary is first displayed, but depending on how they are referenced, they may pick up a location list on the next document build. -

    The entries can be separated into different glossaries with different sort +

    The entries can be separated into different glossaries with different sort methods:

    -
    +
    \documentclass{article}  
    \usepackage[record,abbreviations,symbols]{glossaries-extra}  
    \setabbreviationstyle{long-short-desc} @@ -17810,8 +17238,8 @@ methods:  
    \printunsrtglossaries  
    \end{document}
    -

    -

    Or you can have multiple instance of

    +

    Or you can have multiple instance of \GlsXtrLoadResources with the same type, which will produce a glossary with ordered sub-blocks. For example: @@ -17819,7 +17247,7 @@ class="cmtt-10">type, which will produce a glossary with ordered sub-bloc

    -
    +
    \documentclass{article}  
    \usepackage[record,style=indexgroup]{glossaries-extra}  
    \setabbreviationstyle{long-short-desc} @@ -17837,10 +17265,10 @@ class="cmtt-10">type, which will produce a glossary with ordered sub-bloc  
    \printunsrtglossaries  
    \end{document}
    -

    This will result in a glossary where the first group has the title “Abbreviations”, the +

    This will result in a glossary where the first group has the title “Abbreviations”, the second group has the title “Symbols” and then follow the usual letter groups. Note that for this example to work, you must run bib2gls with the --group (or myDoc.tex:

    -
    +
    pdflatex myDoc  
    bib2gls -g myDoc  
    pdflatex myDoc
    -

    The value of the

    The value of the group field must always be a label. You can set the corresponding + id="dx1-42011"> field must always be a label. You can set the corresponding title with \glsxtrsetgrouptitle (see §2.12 Glossary Style Modifications). If no title -is set then the label is used as the group title. -

    You can provide your own custom sort rule. For example, if you are using +class="cmsy-10">§2.10.1 Glossary Style Modifications). If no +title is set then the label is used as the group title. +

    You can provide your own custom sort rule. For example, if you are using XƎLATEX or LuaLATEX:

    ]
    Remember that if you are using inputenc then extended characters, such as é or ø, + id="dx1-42012"> then extended characters, such as é or ø, are active and will expand when written to the .aux file. So with PDFLATEX the @@ -18017,7 +17445,7 @@ class="cmti-10">hex⟩) in the .aux file. bib2gls will recognise this as the character given by the hexadecimal value ⟨\string\uE6 and so on. This is quite cumbersome, but you can use the shortcut \glshex E6 instead, so the above needs to be written as:
    @@ -18164,49 +17592,49 @@ class="cmsy-10">}]
    -

    +

    -

    Top

    9.3 The The glossaries-extra-bib2gls package

    -

    The package option

    The package option record=only (or simply (or simply record) automatically loads the + id="dx1-43002">) automatically loads the supplementary package glossaries-extra-bib2gls, which provides some commands that + id="dx1-43003">, which provides some commands that are specific to bib2gls. The package isn’t loaded by record=alsoindex as that option + id="dx1-43005"> as that option is intended for sorting with makeindex or xindy and it is expected that the sorting will be switched off (with the resource option sort=none). -

    If

    If glossaries-extra-bib2gls is loaded via the is loaded via the record package option then the + id="dx1-43009"> package option then the check for associated language resource files (see §13 §14 Multi-Lingual Support) will also search for the existence of glossariesxtr-script⟩ is the four letter script identifier, such as Latn). -

    This package provides some shortcut commands that use

    This package provides some shortcut commands that use \printunsrtglossary if the + id="dx1-43010"> if the relevant package option has defined the associated glossary: \printunsrtabbreviations, + id="dx1-43011">, \printunsrtacronyms, , \printunsrtsymbols, , \printunsrtnumbers and + id="dx1-43014"> and \printunsrtindex. -


    \glsxtrprovidecommand  . +

    The savenumberlist package option doesn’t have any effect with bib2gls. +The location lists are saved by default, so glossaries-extra-bib2gls patches +\glsentrynumberlist and \glsdisplaynumberlist to work with the location +field +


    \glsxtrprovidecommand{cs}[n][default] -{]{definition}

    -

    +

    This command is intended for use in @preamble. It’s simply defined to \providecommand in glossaries-extra-bib2gls but but bib2gls’s interpreter treats it as \renewcommand. This means that you can override bib2gls’s internal definition of a command without overriding the command definition in the document (if it’s already defined before the resource file is input). For example @@ -18266,11 +17707,11 @@ defined before the resource file is input). For example

    -
    +
    @preamble{"\glsxtrprovidecommand{\int}{integral}"}
    -

    This will force

    This will force bib2gls to treat \int as the word “integral” to assist sorting but if @@ -18278,7 +17719,7 @@ this preamble code is written to the .glstex file (as it is by default) then it won’t override the current definition (provided by the kernel or redefined by a package). -

    The helper commands in the resource files are defined using

    The helper commands in the resource files are defined using \providecommand. For many of them, if you want to provide an alternative definition then you need to define the command before the resource file is loaded. There are a few that may be @@ -18288,10 +17729,8 @@ first LATEX run when the .glstex file doesn’t exist. In this case, you may prefer to use: -


    \glsrenewcommand 


    \glsrenewcommand{cs}[][default]{definition} -

    -

    +class="cmtt-10">}


    +

    This behaves like \renewcommand but only generates a warning rather than an error if the command isn’t already defined so it won’t interrupt the document build. -


    \GlsXtrIndexCounterLink 


    \GlsXtrIndexCounterLink{text}{label} -

    -

    +class="cmtt-10">}


    +

    If the \hyperref command has been defined (that is, command has been defined (that is, hyperref has been + id="dx1-43030"> has been loaded before glossaries-extra) then this command checks for the existence of the text⟩. This command is provided for use with the indexcounter package option combined with package option combined with bib2gls’s save-index-counter resource option. See the bib2gls manual for further details (at least version 1.4). -

    If you use the

    If you use the set-widest resource option, bib2gls v1.8+ will now use: -


    \glsxtrSetWidest 


    \glsxtrSetWidest{type}{level}{text}

    -

    +

    (if it has been defined) to set the widest name for the given glossary type and level. This allows for both the alttree style and the styles provided by style and the styles provided by glossary-longextra, + id="dx1-43037">, which need to know the widest name. -

    If

    If bib2gls can’t determine the widest name (typically because the name field consists of commands that aren’t recognised by the interpreter) then bib2gls v1.8+ will now use: -


    \glsxtrSetWidestFallback 


    \glsxtrSetWidestFallback{max depth}{list} -

    - - - -

    +class="cmtt-10">}


    +

    (if defined). Currently the maximum hierarchical depth ⟨max depth⟩ may only be 0 or 2. This command requires commands provided by the glossaries-extra-stylemods + id="dx1-43041"> + + + package with the alttree style enabled. In this case, it may be simpler to just use + id="dx1-43042"> style enabled. In this case, it may be simpler to just use \glssetwidest. -

    + id="dx1-43043">. +

    -

    Top

    9.3.1 Supplemental Locations

    -


    \glsxtrdisplaysupploc 


    \glsxtrdisplaysupploc{prefix}{counter}{format} -{}{src}{location}

    -

    +class="cmtt-10">} +


    +

    This is used by bib2gls version 1.7+ for supplemental locations, instead of using \glsxtrsupphypernumber with the externallocation attribute. This command sets up + id="dx1-44003"> attribute. This command sets up the location counter and prefix (used in the formation of hyperlinks) and then uses -


    \glsxtrmultisupplocation 


    \glsxtrmultisupplocation{location}{src} -{}{format}

    -

    +

    to format the actual location (with an external hyperlink, if supported). -

    +

    -

    Top

    9.3.2 Nameref Record

    -

    Normally locations are recorded in the

    Normally locations are recorded in the .aux file in the form: -



    \glsxtr@record{label}{}{location}

    -

    +

    The record=nameref option, which requires at least option, which requires at least bib2gls v1.8, instead uses: -



    \glsxtr@record@nameref{label}{href}{hcounter}

    -

    +

    where ⟨title⟩ is obtained from \@currentlabelname and ⟨href ⟩ is obtained from \@currentHref. These commands require hyperref. If they are undefined, ⟨. If they are undefined, ⟨title⟩ and ⟨href ⟩ will be left empty and bib2gls will treat it as a regular record. -

    Be careful with this option as ⟨

    Be careful with this option as ⟨href ⟩ will globally change on every instance of \refstepcounter but ⟨title⟩ won’t necessarily change. It can therefore cause unexpected behaviour.
    -

    -

    The final argument ⟨

    +

    The final argument ⟨hcounter⟩ is obtained from \theHcounter⟩ which provides the partial target name associated with the indexing counter. With the original - - - makeindex/xindy approach, it’s not possible to include this information in the location, so the base glossaries package attempts to derive a prefix from which the + id="dx1-45007"> package attempts to derive a prefix from which the ⟨hcounter⟩ value can be reconstituted by appending the prefix. Unfortunately, not all definitions of counter⟩ are in the form ⟨prefix\thecounter⟩ (most notably the + + + equation counter with chapters) so this can fail. -

    Since counter with chapters) so this can fail. +

    Since bib2gls is customized specifically for use with glossaries-extra, it’s now @@ -18565,7 +17988,7 @@ class="cmti-10">hcounter⟩, so the record=nameref option does this. By providing both + id="dx1-45010"> option does this. By providing both ⟨href ⟩ and ⟨hcounter⟩, you can determine which target you would rather use. The default @@ -18576,10 +17999,10 @@ class="cmtt-10">\refstepcounter. However, you may choose to switch to using the ⟨href ⟩ target, which will take you to the nearest target before the indexing took place. -

    With

    With bib2gls v1.8+, normal locations are displayed using: -



    \glsnoidxdisplayloc{prefix}{format}{location}

    -

    +

    This is provided by the base glossaries package and is simply defined to do: -


    package and is simply defined to do: +


    \setentrycounter[prefix]{}{location}

    -

    +

    Earlier versions of bib2gls only used this in the loclist field and explicitly used + id="dx1-45014"> field and explicitly used \setentrycounter in the location field followed by field followed by \format{}, which follows the code that’s created with the default makeindex setting. The setting. The \setentrycounter command sets up the prefix needed for \glshypernumber to reform the target name from the given location. -

    The locations identified by

    The locations identified by \glsxtr@record@nameref are written by bib2gls to the location list using: -


    \glsxtrdisplaylocnameref 


    \glsxtrdisplaylocnameref{prefix}{counter} -{}{format}{location}{} +{title}{hrefhcounter}{file}

    -

    +

    With normal internal locations, ⟨file⟩ will always be empty. With supplemental locations, ⟨file⟩ will be the external file reference. -

    The default definition is: +

    The default definition is:

    -
    +
    \newcommand*{\glsxtrdisplaylocnameref}[8]{%  
      \ifstrequal{#2}{equation}%  
      {\glsxtrnamereflink{#3}{(#4)}{#2.#7}{#8}}% @@ -18682,11 +18103,9 @@ class="cmti-10">file⟩ will be the external file reference.  
      }%  
    }
    -

    which uses: -


    \glsxtrnamereflink 

    which uses: +


    \glsxtrnamereflink{format}{}{target}{file} -

    -

    +class="cmtt-10">}


    +

    This ignores the ⟨prefix⟩, ⟨counter⟩ and } arguments and instead creates a hyperlink with the target name obtained from ⟨target⟩ (and ⟨file⟩, if not empty). -

    Since pages and equations typically don’t have titles, the default definition of +

    Since pages and equations typically don’t have titles, the default definition of \glsxtrdisplaylocnameref checks the counter was used as the location. If it’s page + id="dx1-45020"> or if ⟨title⟩ is empty, then just the location is used as the hyperlink text. If the counter equation, then the text is the location in parentheses. Otherwise the text is obtained + id="dx1-45021">, then the text is the location in parentheses. Otherwise the text is obtained from ⟨title⟩. -

    If ⟨

    If ⟨file⟩ is empty an internal link is created with: -


    \glsxtrfmtinternalnameref 


    \glsxtrfmtinternalnameref{target}{format} -{}{title}

    -

    +

    otherwise an external link is created with: -


    \glsxtrfmtexternalnameref 


    \glsxtrfmtexternalnameref{target}{format} -{}{title}{file}

    -

    +

    The ⟨file⟩ argument is set by bib2gls for supplemental locations. -

    Here’s alternative definition that uses the ⟨

    Here’s alternative definition that uses the ⟨prefix⟩ and ⟨counter⟩ to reform the target name (as -

    +
    \renewcommand*{\glsxtrdisplaylocnameref}[7]{%  
     \glsxtrnamereflink{#3}{#5}{#6}{#7}%  
    }
    -

    which uses: -


    \glsxtrnameloclink 

    which uses: +


    \glsxtrnameloclink{prefix}{counter}{format} -{}{location}{title}{} +{file}

    -

    +

    This uses the same commands as \glsxtrnamereflink to produce the hyperlinks. -

    In both cases, the link is encapsulated with the text-block command whose +

    In both cases, the link is encapsulated with the text-block command whose name is given by ⟨format⟩, but \glshypernumber is first locally redefined to @@ -18807,8 +18215,8 @@ class="cmti-10">format⟩ is hyperbf then it will simply behave like textbf. -

    For compactness,

    For compactness, bib2gls merges normal records if the ⟨prefix⟩, ⟨location⟩ all match. (An order of precedence can b With nameref records, you can use the --merge-nameref-on switch provided by bib2gls v1.8+ to determine how to merge nameref records. This switch must be followed by one of the following keywords: hcounter (merge on @@ -18833,62 +18241,54 @@ class="cmtt-10">location class="cmti-10">location⟩, as regular records). In all cases, the ⟨counter⟩ must also match. -

    +

    -

    Top

    9.3.3 Helper Commands for Resource Options

    -


    \glshex 


    \glshex

    -

    +

    This is just defined as \string\u, which is required when you need to indicate a Unicode character in the form \uhex⟩ in some of the resource options (as illustrated above). -


    \glscapturedgroup 


    \glscapturedgroup

    -

    +

    This is just defined as \string\$ and is used for the captured group reference in a replacement part of a regular expression substitution (requires at least bib2gls version 1.5). For example:

    -
    +
    sort-replace={{([a-zA-Z])\string\.}{\glscapturedgroup1}}
    -

    This only removes a full stop that follows any of the characters a,…,z or +

    This only removes a full stop that follows any of the characters a,…,z or A,…,Z. -

    If you use the

    If you use the save-child-count resource option, you can test if the childcount field is non-zero using: -


    \GlsXtrIfHasNonZeroChildCount 


    \GlsXtrIfHasNonZeroChildCount{label} -{}{true}{false}

    -

    +

    This internally uses \GlsXtrIfFieldNonZero and will do ⟨false⟩ if the field isn’t set. @@ -18898,39 +18298,35 @@ class="cmti-10">false⟩ you can use \glscurrentfieldvalue to access the value. (It will be 0 in ⟨false⟩ if the field isn’t set.) -

    A convenient shortcut for use in the

    A convenient shortcut for use in the entry-type-aliases setting: -


    \GlsXtrBibTeXEntryAliases 


    \GlsXtrBibTeXEntryAliases

    -

    +

    This provides aliases for BibTEX’s standard entry types to bib2gls’s @bibtexentry entry type (requires at least bib2gls version 1.4). -

    You may also want to provide storage keys for BibT

    You may also want to provide storage keys for BibTEX’s standard fields rather than having to alias them all. This can be done with: -


    \GlsXtrProvideBibTeXFields 


    \GlsXtrProvideBibTeXFields

    -

    +

    Note that BibTEX’s type field clashes with the glossaries package’s package’s type key, so + id="dx1-46010"> key, so this command provides the key bibtextype instead. You can alias it with bibtextype field can be accessed with \glsxtrbibtype. Each of these commands takes the entry label as the sole argument. -

    The

    The glossaries-extra-bib2gls package also provides definitions of the missing + id="dx1-46011"> package also provides definitions of the missing mathematical Greek commands: \Alpha, , \Beta, , \Epsilon, , \Zeta, , \Eta, , \Iota, + id="dx1-46017">, \Kappa, , \Mu, , \Nu, , \Omicron, , \Rho, , \Tau, , \Chi, , \Digamma, , \omicron. These are all + id="dx1-46026">. These are all defined with \providecommand, so they won’t override any definitions provided by any package loaded before glossaries-extra. Since . Since bib2gls’s interpreter recognises these commands, using them instead of explicitly using the Latin characters with the same shape helps to keep the Greek symbols together when sorting. Similarly, if upgreek has been loaded, the missing upright Greek commands are also + id="dx1-46029"> has been loaded, the missing upright Greek commands are also provided. -

    The remaining commands provide common rule blocks for use in the +

    The remaining commands provide common rule blocks for use in the sort-rule resource option. If you want a rule for a specific locale, you can provide similar commands in a file called \IfTrackedLanguageFileExists in the tracklang documentation for further details. - - - + id="dx1-46030"> documentation for further details. If this file is on TEX’s path and the tracklang package (automatically loaded by + id="dx1-46031"> package (automatically loaded by + + + glossaries) detects that the document has requested that language or locale, then the file will automatically be loaded. For example, if you want to provide a rule @@ -19022,7 +18418,7 @@ contains:

    -
    +
    \ProvidesGlossariesExtraLang{welsh}[2018/02/23 v1.0]  
    \@ifpackageloaded{glossaries-extra-bib2gls}  
    { @@ -19060,7 +18456,7 @@ contains:  
    }  
    {}% glossaries-extra-bib2gls.sty not loaded
    -

    (The use of

    (The use of \string is in case the < character has been made active.) You can provide more than one rule-block per local, to allow for loanwords or foreign words. @@ -19068,7 +18464,7 @@ For example, you could provide \glsxtrWelshIRules, \glsxtrWelshIIRules etc. -

    If the rules are for a particular script (independent of language or region) then +

    If the rules are for a particular script (independent of language or region) then they can be provided in a file given by glossariesxtr-scriptglossariesxtr-Cyrl.ldf could contain:

    -
    +
    \ProvidesGlossariesExtraLang{Cyrl}[2018/02/23 v1.0]  
    \newcommand*{\glsxtrGeneralCyrillicIRules}{%  
      % Cyrillic rules @@ -19088,20 +18484,20 @@ class="cmtt-10">glossariesxtr-Cyrl.ldf could contain:  
      % an alternative set of Cyrillic rules  
    }
    -

    (Remember that the required document language scripts need to be tracked through +

    (Remember that the required document language scripts need to be tracked through the tracklang package, in order for these files to be automatically loaded. This + id="dx1-46032"> package, in order for these files to be automatically loaded. This essentially means ensuring you load the appropriate language package before tracklang is loaded by the base is loaded by the base glossaries package or any other package that uses it. + id="dx1-46034"> package or any other package that uses it. See the tracklang documentation for further details.) -

    Alternatively, if the rules are specific to a subject rather than a region or + id="dx1-46035"> documentation for further details.) +

    Alternatively, if the rules are specific to a subject rather than a region or language, then you can provide a supplementary package. For example, if you have a package called, say, mapsymbols that provides map symbols, then the file @@ -19111,7 +18507,7 @@ class="cmtt-10">mapsymbols.sty might contain:

    -
    +
    \NeedsTeXFormat{LaTeX2e}  
    \ProvidesPackage{mapsymbols}  
     some package or font loading stuff here to provide @@ -19127,27 +18523,27 @@ class="cmtt-10">mapsymbols.sty might contain:  
     \string< \glshex 26BD % football 0x26BD  
    }
    -

    and the supplementary file

    and the supplementary file mapsymbols.bib can provide the appropriate definitions for bib2gls:

    -
    +
    @preamble{"\glsxtrprovidecommand{\Harbour}{\char"2693}  
    \glsxtrprovidecommand{\Battlefield}{\char"2694}  
    \glsxtrprovidecommand{\Stadium}{\char"26BD}"}
    -

    Now both the preamble and rule block can be used in the resource set: +

    Now both the preamble and rule block can be used in the resource set:

    -
    +
    \usepackage{mapsymbols}% my custom package  
    \usepackage[record]{glossaries-extra}  
    \GlsXtrLoadResources[ @@ -19169,10 +18565,10 @@ class="cmtt-10">bib2gls:  
     }  
    ]
    -

    -

    The following commands are provided by

    +

    The following commands are provided by glossaries-extra-bib2gls. They should be + id="dx1-46037">. They should be separated by the rule separator characters ; (semi-colon) or , (comma) or @@ -19181,21 +18577,21 @@ class="cmtt-10">& (ampersand) or < (less than). See Java’s RuleBasedCollator documentation for details of the rule syntax. -

    For example, the following will place the mathematical Greek symbols (

    For example, the following will place the mathematical Greek symbols (\alpha, + id="dx1-46038">, \Alpha, , \beta, , \Beta etc) in a block before Latin characters: + id="dx1-46041"> etc) in a block before Latin characters:

    -
    +
    sort-rule={\glsxtrcontrolrules  
     ;\glsxtrspacerules  
     ;\glsxtrnonprintablerules @@ -19210,47 +18606,38 @@ sort-rule={\glsxtrcontrolrules  
     <\glsxtrLatinOslash  
    }
    -

    -


    \glsxtrcontrolrules 

    +


    \glsxtrcontrolrules

    -

    +

    These are control characters that are usually placed at the start of a rule in the ignored section. They typically won’t occur in any sort values, but if they do they should normally be ignored. -


    \glsxtrspacerules 


    \glsxtrspacerules

    -

    +

    These are space characters. They typically come after the control characters with the two blocks separated by a ; (semi-colon). -


    \glsxtrnonprintablerules 


    \glsxtrnonprintablerules

    -

    +

    These are non-printable characters (BOM, tabs, line feed and carriage return). They typically come after the spaces separated by a ; (semi-colon). These characters aren’t checked for by bib2gls when it determines whether or not to use the interpreter, so a TAB or newline character may end up in the sort value if it wasn’t interpreted. -


    \glsxtrcombiningdiacriticrules  \glsxtrcombiningdiacriticrules -

    -

    +


    \glsxtrcombiningdiacriticrules

    +

    These are combining diacritic marks which typically follow the space and non-printable blocks (separated by a semi-colon). This command is defined in terms of sub-block commands: @@ -19258,7 +18645,7 @@ of sub-block commands:

    -
    +
    \newcommand*{\glsxtrcombiningdiacriticrules}{%  
     \glsxtrcombiningdiacriticIrules\string;  
     \glsxtrcombiningdiacriticIIrules\string; @@ -19266,36 +18653,27 @@ of sub-block commands:  
     \glsxtrcombiningdiacriticIVrules  
    }
    -

    If you prefer, you can use the sub-blocks directly in your required ordered. -


    \glsxtrcombiningdiacriticIrules  \glsxtrcombiningdiacriticIrules -

    -

    +

    If you prefer, you can use the sub-blocks directly in your required ordered. +


    \glsxtrcombiningdiacriticIrules

    +

    This contains the combining diacritics: acute, grave, breve, circumflex, caron, ring, vertical line above, diaeresis (umlaut), double acute, tilde, dot above, combining macron. -


    \glsxtrcombiningdiacriticIIrules  \glsxtrcombiningdiacriticIIrules -

    -

    +


    \glsxtrcombiningdiacriticIIrules

    +

    This contains the combining diacritics: short solidus overlay, cedilla, ogonek, dot below, low line, overline, hook above, double vertical line above, double grave accent, candrabindu, inverted breve, turned comma above, comma above, reversed comma above, comma above right, grave accent below, acute accent below. -


    \glsxtrcombiningdiacriticIIIrules  \glsxtrcombiningdiacriticIIIrules -

    -

    +


    \glsxtrcombiningdiacriticIIIrules

    +

    This contains the combining diacritics: left tack below, right tack below, left angle above, horn, left half ring below, up tack below, down tack below, plus sign below, minus sign below, palatalized hook below, retroflex hook below, diaresis below, ring @@ -19307,36 +18685,29 @@ seagull below, x above, vertical tilde, double overline, Greek perispomeni, Gree dialytika tonos, Greek ypogegrammeni, double tilde, double inverted breve, Cyrillic titlo, Cyrillic palatalization, Cyrillic dasia pneumata, Cyrillic psili pneumata. -


    \glsxtrcombiningdiacriticIVrules  \glsxtrcombiningdiacriticIVrules -

    -

    +


    \glsxtrcombiningdiacriticIVrules

    +

    This contains the combining diacritics: left harpoon above, right harpoon above, long vertical line overlay, short vertical line overlay, anticlockwise arrow above, clockwise arrow above, left arrow above, right arrow above, ring overlay, clockwise ring overlay, - - - anticlockwise ring overlay, three dots above, four dots above, enclosing circle, enclosing square, enclosing diamond, enclosing circle backslash, left right arrow above. -


    \glsxtrhyphenrules 


    \glsxtrhyphenrules

    -

    + + + +

    This contains hyphens (including the minus sign 0x2212). This rule block typically comes after the diacritic rules separated by a comma. -


    \glsxtrgeneralpuncrules 


    \glsxtrgeneralpuncrules

    -

    +

    This contains punctuation characters. This rule block typically comes after the hyphen rules separated by a less than (<). As with the combining diacritics, this @@ -19346,20 +18717,18 @@ different order is required:

    -
    +
    \newcommand*{\glsxtrgeneralpuncrules}{%  
      \glsxtrgeneralpuncIrules  
      \string<\glsxtrcurrencyrules  
      \string<\glsxtrgeneralpuncIIrules  
    }
    -

    -


    \glsxtrgeneralpuncIrules 

    +


    \glsxtrgeneralpuncIrules

    -

    +

    This is the first punctuation sub-block containing: underscore, macron, comma, semi-colon, colon, exclamation mark, inverted exclamation mark, question mark, inverted question mark, solidus, full stop, acute accent, grave accent, @@ -19368,32 +18737,26 @@ straight double quote, left guillemet, right guillemet, left parenthesis, right parenthesis, left square bracket, right square bracket, left curly bracket, right curly bracket, section sign, pilcrow sign, copyright sign, registered sign, at sign. -


    \glsxtrcurrencyrules 


    \glsxtrcurrencyrules

    -

    +

    This sub-block contains some currency symbols: currency sign, Thai currency symbol baht, cent sign, colon sign, cruzeiro sign, dollar sign, dong sign, euro sign, French franc sign, lira sign, mill sign, naira sign, peseta sign, pound sign, rupee sign, new sheqel sign, won sign, yen sign. -


    \glsxtrgeneralpuncIIrules 


    \glsxtrgeneralpuncIIrules

    -

    +

    This sub-block contains some other punctuation symbols: asterisk, backslash, ampersand, hash sign, percent sign, plus sign, plus-minus sign, division sign, multiplication sign, less-than sign, equals sign, greater-than sign, not sign, vertical bar (pipe), broken bar, degree sign, micron sign. -


    \glsxtrdigitrules 


    \glsxtrdigitrules

    -

    +

    This rule block contains the Basic Latin digits (0, …, 9) and the subscript and superscript digits (0 0 etc) made equivalent to the corresponding Basic Lat The digit block typically comes after the punctuation rules separated by a less than (<). -


    \glsxtrBasicDigitrules 


    \glsxtrBasicDigitrules

    -

    +

    This rule block contains just the Basic Latin digits (0, …, 9). -


    \glsxtrSubScriptDigitrules 


    \glsxtrSubScriptDigitrules

    -

    +

    This rule block contains just the subscript digits (0 … 9). -


    \glsxtrSuperScriptDigitrules 


    \glsxtrSuperScriptDigitrules

    -

    +

    This rule block contains just the superscript digits (0 … 9). -


    \glsxtrfractionrules 


    \glsxtrfractionrules

    -

    +

    This rule block contains vulgar fraction characters. The digit block typically comes after the digit rules separated by a less than (<). -

    There are a number of Latin rule blocks. Some of these included extended +

    There are a number of Latin rule blocks. Some of these included extended characters or ligatures (such as ß or œ) but they don’t include accented characters. If you require a Latin rule block that includes accented characters, digraphs, trigraphs or other extended characters, then it’s best to provide similar @@ -19447,12 +18802,10 @@ class="cmtt-10">glossariesxtr-⟨tag.ldf file for the particular language or region. -


    \glsxtrGeneralLatinIrules 


    \glsxtrGeneralLatinIrules

    -

    +

    This is just the basic (non-extended) Latin alphabet with the superscript and subscript Latin letters (a a etc) treated as the equivalent basic Latin letter. don’t want the subscripts and superscripts included you can redefine \glsxtrLatinA etc to omit them.) -


    \glsxtrGeneralLatinIIrules 


    \glsxtrGeneralLatinIIrules

    -

    +

    This is like \glsxtrGeneralLatinIrules but it includes eth (Ð) between ‘D’ and ‘E’ and eszett (ß) treated as ‘ss’. -


    \glsxtrGeneralLatinIIIrules 


    \glsxtrGeneralLatinIIIrules

    -

    +

    This is like \glsxtrGeneralLatinIrules but it includes eth (Ð) between ‘D’ and ‘E’ and eszett (ß) treated as ‘sz’. -


    \glsxtrGeneralLatinIVrules 


    \glsxtrGeneralLatinIVrules

    -

    +

    This is like \glsxtrGeneralLatinIrules but it includes eth (Ð) between ‘D’ and ‘E’, ae-ligature (æ) is treated as ‘ae’, oe-ligature (œ) is treated as ‘oe’, eszett (ß) treated as ‘ss’ and thorn (þ) is treated as ‘th’. -


    \glsxtrGeneralLatinVrules 


    \glsxtrGeneralLatinVrules

    -

    +

    This is like \glsxtrGeneralLatinIrules but it includes eth (Ð) between ‘D’ and ‘E’, eszett (ß) treated as ‘ss’ and thorn (þ) treated as ‘th’. -


    \glsxtrGeneralLatinVIrules 


    \glsxtrGeneralLatinVIrules

    -

    +

    This is like \glsxtrGeneralLatinIrules but it includes eth (Ð) between ‘D’ and ‘E’, eszett (ß) treated as ‘sz’ and thorn (þ) treated as ‘th’. -


    \glsxtrGeneralLatinVIIrules 


    \glsxtrGeneralLatinVIIrules

    -

    +

    This is like \glsxtrGeneralLatinIrules but it includes ae-ligature (æ) between ‘A’ and ‘B’, eth (Ð) between ‘D’ and ‘E’, insular G (Ᵹ) instead of ‘G’, oe-ligature between ‘O’ and ‘P’, long s (ſ) equivalent to ‘s’, thorn (þ) between ‘T’ and ‘U’ and wynn (Ƿ) instead of W. -


    \glsxtrGeneralLatinVIIIrules 


    \glsxtrGeneralLatinVIIIrules

    -

    +

    This is like \glsxtrGeneralLatinIrules but ae-ligature (æ) is treated as ‘ae’, oe-ligature (œ) is treated as ‘oe’, eszett (ß) treated as ‘ss’, thorn (þ) is treated as ‘th’, Ø is treated as ‘O’ and ‘Ł’ is treated as ‘L’. -


    \glsxtrLatinA 


    \glsxtrLatinA

    -

    +

    A mini-rule that just covers ‘A’ but includes the sub- and superscript A. -


    \glsxtrLatinE 


    \glsxtrLatinE

    -

    +

    A mini-rule that just covers ‘E’ but includes the subscript E. -


    \glsxtrLatinH 


    \glsxtrLatinH

    -

    +

    A mini-rule that just covers ‘H’ but includes the subscript H. -


    \glsxtrLatinK 


    \glsxtrLatinK

    -

    +

    A mini-rule that just covers ‘K’ but includes the subscript K. -


    \glsxtrLatinI 


    \glsxtrLatinI

    -

    +

    A mini-rule that just covers ‘I’ but includes the superscript I. -


    \glsxtrLatinL 


    \glsxtrLatinL

    -

    +

    A mini-rule that just covers ‘L’ but includes the subscript L. -


    \glsxtrLatinM 


    \glsxtrLatinM

    -

    +

    A mini-rule that just covers ‘M’ but includes the subscript M. -


    \glsxtrLatinN 


    \glsxtrLatinN

    -

    +

    A mini-rule that just covers ‘N’ but includes the sub- and superscript N. -


    \glsxtrLatinO 


    \glsxtrLatinO

    -

    +

    A mini-rule that just covers ‘O’ but includes the sub- and superscript O. -


    \glsxtrLatinP 


    \glsxtrLatinP

    -

    +

    A mini-rule that just covers ‘P’ but includes the subscript P. -


    \glsxtrLatinS 


    \glsxtrLatinS

    -

    +

    A mini-rule that just covers ‘S’ but includes the subscript S. -


    \glsxtrLatinT 


    \glsxtrLatinT

    -

    +

    A mini-rule that just covers ‘T’ but includes the subscript T. -


    \glsxtrLatinX 


    \glsxtrLatinX

    -

    +

    A mini-rule that just covers ‘X’ but includes the subscript X. -


    \glsxtrLatinEszettSs 


    \glsxtrLatinEszettSs

    -

    +

    A mini-rule that just covers eszett (ß) and makes long s (ſ) followed by short ‘s’ equivalent to ‘ß’. (This is used in the above blocks that treat ‘ß’ as ‘ss’.) -


    \glsxtrLatinEszettSz 


    \glsxtrLatinEszettSz

    -

    +

    A mini-rule that just covers eszett (ß) and makes long s (ſ) followed by ‘z’ equivalent to ‘ß’. (This is used in the above blocks that treat ‘ß’ as ‘sz’.) -


    \glsxtrLatinEth 


    \glsxtrLatinEth

    -

    +

    A mini-rule for eth (Ð) so you don’t need to remember the Unicode values. -


    \glsxtrLatinThorn 


    \glsxtrLatinThorn

    -

    +

    A mini-rule for thorn (þ) so you don’t need to remember the Unicode values. -


    \glsxtrLatinAELigature 


    \glsxtrLatinAELigature

    -

    +

    A mini-rule for ae-ligature (æ) so you don’t need to remember the Unicode values. -


    \glsxtrLatinOELigature 


    \glsxtrLatinOELigature

    -

    +

    A mini-rule for oe-ligature (œ) so you don’t need to remember the Unicode values. -


    \glsxtrLatinOslash 


    \glsxtrLatinOslash

    -

    +

    A mini-rule for ‘Ø’ so you don’t need to remember the Unicode values. -


    \glsxtrLatinLslash 


    \glsxtrLatinLslash

    -

    +

    A mini-rule for ‘Ł’ so you don’t need to remember the Unicode values. -


    \glsxtrLatinWynn 


    \glsxtrLatinWynn

    -

    +

    A mini-rule for wynn (Ƿ) so you don’t need to remember the Unicode values. -


    \glsxtrLatinInsularG 


    \glsxtrLatinInsularG

    -

    +

    A mini-rule for insular G (Ᵹ) so you don’t need to remember the Unicode values. -


    \glsxtrLatinSchwa 


    \glsxtrLatinSchwa

    -

    +

    A mini-rule that just covers schwa (Ə) but includes the subscript schwa. (Not used in any of the provided Latin rule blocks described above.) -


    \glsxtrLatinAA 


    \glsxtrLatinAA

    -

    +

    A mini-rule for ‘Å’ so you don’t need to remember the Unicode values. (Not used in any of the provided Latin rule blocks described above.) -


    \glsxtrMathGreekIrules 


    \glsxtrMathGreekIrules

    -

    +

    A rule block for mathematical Greek (\alpha, , \beta etc) and upright Greek + id="dx1-46096"> etc) and upright Greek (\upalpha, etc, from the , etc, from the upgreek package) characters that includes digamma + id="dx1-46098"> package) characters that includes digamma (\digamma and and \Digamma) between epsilon and zeta. The upright and italic versions + id="dx1-46100">) between epsilon and zeta. The upright and italic versions are gathered together into the same letter group. -


    \glsxtrMathGreekIIrules 


    \glsxtrMathGreekIIrules

    -

    +

    As \glsxtrMathGreekIrules but doesn’t include digamma. -


    \glsxtrMathUpGreekIrules 


    \glsxtrMathUpGreekIrules

    -

    +

    A rule block for upright Greek (\upalpha, etc, from the , etc, from the upgreek package) + id="dx1-46104"> package) characters that includes digamma (\digamma and and \Digamma) between epsilon and + id="dx1-46106">) between epsilon and zeta. -


    \glsxtrMathUpGreekIIrules 


    \glsxtrMathUpGreekIIrules

    -

    +

    A rule block for upright Greek (\upalpha, etc, from the , etc, from the upgreek package) that + id="dx1-46109"> package) that doesn’t include digamma. -


    \glsxtrMathItalicGreekIrules 


    \glsxtrMathItalicGreekIrules

    -

    +

    A rule block for mathematical Greek (\alpha, , \Alpha, etc) characters that includes + id="dx1-46112">, etc) characters that includes digamma (\diagamma and and \Digamma) between epsilon and zeta. Note that even + id="dx1-46114">) between epsilon and zeta. Note that even though the upper case \Delta etc are actually rendered upright by LATEX, bib2gls’s interpreter treats them as italic to help keep them close to the lower case versions. -


    \glsxtrMathItalicGreekIIrules 


    \glsxtrMathItalicGreekIIrules

    -

    +

    A rule block for mathematical Greek (\alpha, , \Alpha, etc) characters that doesn’t + id="dx1-46118">, etc) characters that doesn’t include digamma. -


    \glsxtrMathItalicUpperGreekIrules  \glsxtrMathItalicUpperGreekIrules -

    -

    +


    \glsxtrMathItalicUpperGreekIrules

    +

    A rule block for upper case mathematical Greek (\Alpha, , \Beta, etc) characters that + id="dx1-46121">, etc) characters that includes digamma (\Digamma) between epsilon and zeta. -


    \glsxtrMathItalicUpperGreekIIrules  \glsxtrMathItalicUpperGreekIIrules -

    -

    + id="dx1-46122">) between epsilon and zeta. +


    \glsxtrMathItalicUpperGreekIIrules

    +

    A rule block for upper case mathematical Greek (\Alpha, , \Beta, etc) characters that + id="dx1-46125">, etc) characters that doesn’t include digamma. -


    \glsxtrMathItalicLowerGreekIrules  \glsxtrMathItalicLowerGreekIrules -

    -

    +


    \glsxtrMathItalicLowerGreekIrules

    +

    A rule block for lower case mathematical Greek (\alpha, , \beta, etc) characters that + id="dx1-46128">, etc) characters that includes digamma (\digamma) between epsilon and zeta. -


    \glsxtrMathItalicLowerGreekIIrules  \glsxtrMathItalicLowerGreekIIrules -

    -

    + id="dx1-46129">) between epsilon and zeta. +


    \glsxtrMathItalicLowerGreekIIrules

    +

    A rule block for lower case mathematical Greek (\alpha, , \beta, etc) characters that + id="dx1-46132">, etc) characters that doesn’t include digamma. -

    Additionally, there are commands in the form

    Additionally, there are commands in the form \glsxtrUpAlpha, \glsxtrUpBeta etc and \glsxtrMathItalicBeta etc that just cover the upper and lower case forms of a special Greek character (\Upalpha, \upalpha etc - - - and \Alpha, \alpha etc) as well as the following: -


    \glsxtrMathItalicPartial 


    \glsxtrMathItalicPartial

    -

    +

    The partial derivative symbol (). -


    \glsxtrMathItalicNabla 


    \glsxtrMathItalicNabla

    -

    +

    The nabla symbol (). -

    +

    -

    Top

    9.4 Supplementary Commands

    -

    These commands are provided by

    These commands are provided by glossaries-extra for use with bib2gls. -

    The information provided with

    The information provided with \GlsXtrLoadResources is written to the .aux file using

    @@ -19926,15 +19187,13 @@ class="cmtt-10">}
    where ⟨information⟩ is the information to pass to bib2gls. The command in the second argument -


    \glsxtrresourceinit 


    \glsxtrresourceinit

    -

    +

    may be used to temporarily redefine commands before the information is written to the file. This does nothing by default, but may be redefined to allow the use of short commands for convenience. For example, with: @@ -19942,40 +19201,38 @@ commands for convenience. For example, with:

    -
    +
    \renewcommand{\glsxtrresourceinit}{\let\u\glshex}
    -

    you can just use, for example,

    you can just use, for example, \u E6 instead of \string\uE6 in the custom rule. This redefinition of \u is scoped so its original definition is restored after the write operation. -

    If you have multiple resource commands and you want a default set of options you +

    If you have multiple resource commands and you want a default set of options you can supply them in the definition of: -


    \GlsXtrDefaultResourceOptions 


    \GlsXtrDefaultResourceOptions

    -

    +

    For example:

    -
    +
    \renewcommand{\GlsXtrDefaultResourceOptions}{selection=all}
    -

    This should be done before the resource commands. -

    It’s possible to specify label prefixes. For example, modifying the earlier +

    This should be done before the resource commands. +

    It’s possible to specify label prefixes. For example, modifying the earlier example:

    -
    +
    \documentclass{article}  
    \usepackage[record,style=indexgroup]{glossaries-extra}  
    \setabbreviationstyle{long-short-desc} @@ -19996,24 +19253,22 @@ example:  
    \printunsrtglossaries  
    \end{document}
    -

    If you do something like this, you may find it more convenient to define custom +

    If you do something like this, you may find it more convenient to define custom commands that set the prefix. For example:

    -
    +
    \newcommand*{\sym}[2][]{\gls[#1]{sym.#2}}
    -

    The problem with this is that the custom command

    The problem with this is that the custom command \sym doesn’t allow for modifiers (such as \gls* or \gls+). Instead you can use: -


    \glsxtrnewgls 


    \glsxtrnewgls[default options]{prefix}{cs}

    -

    +

    which defines the command ⟨cs⟩ that behaves like

    @@ -20046,136 +19301,123 @@ class="cmtt-10">] -
    +
    \glsxtrnewgls{sym.}{\sym}
    -

    or (to default to no hyperlinks) +

    or (to default to no hyperlinks)

    -
    +
    \glsxtrnewgls[hyper=false]{sym.}{\sym}
    -

    now you can use

    now you can use \sym+{M} to behave like \gls+{sym.M}. -

    If you also want the plural and first letter upper case versions you can +

    If you also want the plural and first letter upper case versions you can use -


    \glsxtrnewglslike 


    \glsxtrnewglslike[default options]{prefix}{\gls-like cs} {\gls-like cs}{\glspl-like cs}{\Gls-like cs}{\Glspl-like cs} -

    -

    +class="cmtt-10">}


    +

    For example:

    -
    +
    \glsxtrnewglslike[hyper=false]{idx.}{\idx}{\idxpl}{\Idx}{\Idxpl}
    -

    For the all caps versions: -


    \glsxtrnewGLSlike 

    For the all caps versions: +


    \glsxtrnewGLSlike[default options]{prefix}{\GLS-like cs} {\GLS-like cs}{\GLSpl-like cs}

    -

    +

    For example:

    -
    +
    \glsxtrnewGLSlike[hyper=false]{idx.}{\IDX}{\IDXpl}
    -

    -

    There’s an analogous command for

    +

    There’s an analogous command for \rgls: -


    \glsxtrnewrgls 


    \glsxtrnewrgls[default options]{prefix}{cs} -

    -

    +class="cmtt-10">}


    +

    and for \rgls, \rglspl, \rGls and \rGlspl: -


    \glsxtrnewrglslike 


    \glsxtrnewrglslike[default options]{prefix}{\rgls-like cs} {\rgls-like cs}{\rglspl-like cs}{\rGls-like cs}{\rGlspl-like cs} -

    -

    +class="cmtt-10">}


    +

    and for the all caps: -


    \glsxtrnewrGLSlike 


    \glsxtrnewrGLSlike[default options]{prefix}{\rGLS-like cs} {\rGLS-like cs}{\rGLSpl-like cs}

    -

    -

    If you provide your own custom command with just

    +

    If you provide your own custom command with just \newcommand that has syntax that starts with [options]{label}, then you can notify bib2gls using: -


    \glsxtridentifyglslike 


    \glsxtridentifyglslike{prefix}{command} -

    -

    +class="cmtt-10">}


    +

    This writes information to the .aux file so that bib2gls can search for the given command when looking for dependencies. -

    Another possibility is to set up known label prefixes, with each one identified +

    Another possibility is to set up known label prefixes, with each one identified by: -


    \glsxtraddlabelprefix 


    \glsxtraddlabelprefix{prefix}

    -

    +

    These should be listed in order of precedence. Since no entries are defined on the first LATEX run, the final prefix should be the fallback. You can prepend a prefix to the list using: -


    \glsxtrprependlabelprefix 


    \glsxtrprependlabelprefix{prefix} -

    -

    +class="cmtt-10">}


    +

    which gives it the highest order of precedence. -

    The ⟨

    The ⟨prefix⟩ argument may be empty. You can clear the list with: -


    \glsxtrclearlabelprefixes 


    \glsxtrclearlabelprefixes

    -

    -

    You can test if a prefix is already in the list with: - - - -


    \glsxtrifinlabelprefixlist 

    +

    You can test if a prefix is already in the list with: +


    \glsxtrifinlabelprefixlist{prefix}{true} -{}{false}

    -

    +

    In general it’s best to avoid adding multiple instances of the same prefix, so you can check with this command before adding a prefix to the list. However, it can be useful + + + to repeat a prefix at the end of the list so that it can be used as a fallback for entries that haven’t yet been defined. -

    With the list of possible prefixes set up (including an empty prefix if necessary), +

    With the list of possible prefixes set up (including an empty prefix if necessary), you can use: -


    \dgls 


    \dgls[options]{label}[insert]

    -

    +

    which behaves like

    prefix⟩ is the first prefix in the list such that class="cmti-10">prefix⟩⟨label⟩ matches a defined entry (or the last entry in the prefix list if none match). -

    There are also analogous commands for the plural and case-changing +

    There are also analogous commands for the plural and case-changing versions: -


    \dglspl 


    \dglspl[options]{label}[insert]

    -

    +

    (uses \glspl), -


    \dGls 


    \dGls[options]{label}[insert]

    -

    +

    (uses \Gls), -


    \dGlspl 


    \dGlspl[options]{label}[insert]

    -

    +

    (uses \Glspl), -


    \dGLS 


    \dGLS[options]{label}[insert]

    -

    +

    (uses \GLS), -


    \dGLSpl 


    \dGLSpl[options]{label}[insert]

    -

    +

    (uses \GLSpl), -


    \dglslink 


    \dglslink[options]{label}[insert]

    -

    +

    (uses \glslink), -


    \dglsdisp 


    \dglsdisp[options]{label}[insert]

    -

    +

    (uses \glsdisp). -

    These commands are essentially provided for a mixture of single and dual entries. +

    These commands are essentially provided for a mixture of single and dual entries. Suppose the file entries.bib contains:

    -
    +
    @index{duck}  
    @dualindexabbreviation{svm,  
      short={SVM}, @@ -20409,12 +19621,12 @@ class="cmtt-10">entries.bib contains:  
        diameter}  
    }
    -

    and suppose the document code is: +

    and suppose the document code is:

    -
    +
    \documentclass{article}  
    \usepackage{hyperref}  
    \usepackage[record,abbreviations,symbols]{glossaries-extra} @@ -20429,7 +19641,7 @@ class="cmtt-10">entries.bib contains:  
    \printunsrtglossaries  
    \end{document}
    -

    This uses the default empty primary prefix and

    This uses the default empty primary prefix and dual. for the dual prefix, so \gls{svm} is referencing the primary entry, which is (essentially) an \gls{pi}, which references the primary @index entry rather than the symbol. -

    What’s really needed is: +

    What’s really needed is:

    -
    +
    \gls{duck}, \gls{dual.svm}, \gls{dual.pi}.
    -

    or with +

    or with

    -
    +
    \GlsXtrLoadResources[src=entries,  
     label-prefix={idx.},  
     dual-prefix={}  
    ]
    -

    then only the entries without a dual need a prefix: +

    then only the entries without a dual need a prefix:

    -
    +
    \gls{idx.duck}, \gls{svm}, \gls{pi}.
    -

    Using

    Using \glsxtrnewglslike, as earlier, this can be simplified to:

    -
    +
    \idx{duck}, \gls{svm}, \gls{pi}.
    -

    but this requires remembering which terms have duals. -

    An alternative is to use

    but this requires remembering which terms have duals. +

    An alternative is to use \dgls instead:

    -
    +
    \documentclass{article}  
    \usepackage{hyperref}  
    \usepackage[record,abbreviations,symbols]{glossaries-extra} @@ -20500,7 +19712,7 @@ class="cmtt-10">\dgls instead:  
    \printunsrtglossaries  
    \end{document}
    -

    On the first LAT

    On the first LATEX call (when the .glstex file doesn’t exist), neither dual.svm) entry to be selected. The location will be adde primary entry’s location list, unless overridden by resource options, such as combine-dual-locations. -

    Once

    Once bib2gls has been run and the .glstex file exists, then \dgls{svm} now behaves like \gls{dual.svm}, which follows the abbreviation style and hyperlinks to the list of abbreviations. -

    Similarly for the index-symbol combination

    Similarly for the index-symbol combination dual.pi and pi. In the case of \dgls{duck} always behaves like \gls{duck}. -

    If you haven’t used

    If you haven’t used combine-dual-locations an extra bib2gls+LATEX run may be required to correct the location lists. -

    If you change the label prefixes, remember to update the corresponding +

    If you change the label prefixes, remember to update the corresponding \glsxtraddlabelprefix{prefix}. If no prefixes have been added to the list (or if the list is cleared), just an empty prefix is assumed. -

    As from version 1.8,

    As from version 1.8, bib2gls provides hooks that identify the label prefixes in the @@ -20568,19 +19780,19 @@ class="cmtt-10">.glstex file:

    \bibglstertiaryprefixlabel{prefix}
    \bibglsdualprefixlabel{prefix}
    \bibglsprimaryprefixlabel{prefix} @@ -20590,12 +19802,12 @@ loaded to set up the prefix list. For example: -
    +
    \newcommand{\bibglsprimaryprefixlabel}[1]{\glsxtraddlabelprefix{#1}}  
    \newcommand{\bibglsdualprefixlabel}[1]{\glsxtrprependlabelprefix{#1}}  
    \GlsXtrLoadResources[src=entries]
    -

    Remember that this will only have an effect once the

    Remember that this will only have an effect once the .glstex file has been created. The prefix list will be empty on the first run (which is treated as a single empty prefix). If this isn’t a suitable fallback, it may be necessary to add one after all the @@ -20604,32 +19816,32 @@ resource commands:

    -
    +
    \newcommand{\bibglsprimaryprefixlabel}[1]{\glsxtraddlabelprefix{#1}}  
    \newcommand{\bibglsdualprefixlabel}[1]{\glsxtrprependlabelprefix{#1}}  
    \GlsXtrLoadResources[src=entries,label-prefix={idx.}]  
    \glsxtraddlabelprefix{idx.}
    -

    Although this rather defeats the purpose of using the hooks as you still have to keep +

    Although this rather defeats the purpose of using the hooks as you still have to keep track of the fallback prefix. -

    +

    -

    Top

    9.5 Record Counting

    -

    As from version 1.1 of

    As from version 1.1 of bib2gls, you can save the total record count for each entry by invoking bib2gls with the --record-count or --record-count-unit switches. These options will ensure that when each entry is written to the .glstex file bib2gls will additionally set the following internal fields for that entry:

      @@ -20640,7 +19852,7 @@ class="cmtt-10">recordcount: set to the total number of records found for class="cmtt-10">recordcount.⟨counter⟩: set to the total number of records found for the entry for the given counter.
    -

    If

    If --record-count-unit is used then additionally:

    • counter.location⟩: set to the total number of records found for the entry for the given counter with the given location.
    -

    Only use the unit counting option if the locations don’t contain any special characters. If +

    Only use the unit counting option if the locations don’t contain any special characters. If you really need it with locations that may contain formatting commands, then you can try redefining: -


    \glsxtrdetoklocation 


    \glsxtrdetoklocation{location}

    -

    +

    so that it detokenizes ⟨location⟩ but take care when using \GlsXtrLocationRecordCount with commands like \thepage as they can end up becoming detokenized too early. -

    Note that the record count includes locations that

    Note that the record count includes locations that bib2gls discards, such as ignored records, duplicates and partial duplicates. It doesn’t include cross-reference records. For example, if section counter (stored in the recordcount.section field) is 1. -

    With the unit counting on as well, the field

    With the unit counting on as well, the field recordcount.page.1 is set to 2, recordcount.page.2 is set to 1, recordcount.page.3 is set to 4 and recordcount.section.3 is set to 1. -

    You can access these fields using the following commands which will expand to +

    You can access these fields using the following commands which will expand to the field value if set or to 0 if unset: -


    \GlsXtrTotalRecordCount 


    \GlsXtrTotalRecordCount{label}

    -

    +

    This expands to the total record count for the entry given by ⟨label⟩.

    -
    +
    \GlsXtrTotalRecordCount{bird}
    -

    expands to 8. -


    \GlsXtrRecordCount 

    expands to 8. +


    \GlsXtrRecordCount{label}{counter}

    -

    +

    This expands to the counter total for the entry given by ⟨label⟩ where ⟨counter⟩ is the @@ -20731,55 +19937,49 @@ counter name. For example:

    -
    +
    \GlsXtrRecordCount{bird}{page}
    -

    expands to 7 and +

    expands to 7 and

    -
    +
    \GlsXtrRecordCount{bird}{section}
    -

    expands to 1. -


    \GlsXtrLocationRecordCount 

    expands to 1. +


    \GlsXtrLocationRecordCount{label}{counter} -{}{location}

    -

    +

    This expands to the total for the given location. For example

    -
    +
    \GlsXtrLocationRecordCount{bird}{page}{3}
    -

    expands to 4. Be careful about using

    expands to 4. Be careful about using \thepage in the ⟨location⟩ part. Remember that due to TEX’s asynchronous output routine, \thepage may not be correct. -

    There are commands analogous to the entry counting commands like

    There are commands analogous to the entry counting commands like \cgls and \cglsformat that are triggered by the record count. These are listed below. -


    \rgls 


    \rglsmodifier[label}[insert]

    -

    -


    \rglspl 

    +


    \rglsplmodifier[label}[insert]

    -

    -


    \rGls 

    +


    \rGlsmodifier[label}[insert]

    -

    -


    \rGlspl 

    +


    \rGlsplmodifier[label}[insert]

    -

    -


    \rGLS 

    +


    \rGLSmodifier[label}[insert]

    -

    -


    \rGLSpl 

    +


    \rGLSplmodifier[label}[insert]

    -

    +

    These commands check the recordcount attribute which, if set, should be a number. + id="dx1-48015"> attribute which, if set, should be a number. For example:

    -
    +
    \glssetcategoryattribute{abbreviation}{recordcount}{1}
    -

    For convenience, you can use -


    \GlsXtrSetRecordCountAttribute 

    For convenience, you can use +


    \GlsXtrSetRecordCountAttribute{category -listcategory list}{n}

    -

    +

    to set the recordcount attribute to ⟨ attribute to ⟨n⟩ for all the categories listed in ⟨category list⟩. -

    The

    The \rgls-like commands use -


    \glsxtrifrecordtrigger 


    \glsxtrifrecordtrigger{label}{trigger code} -{}{normal}

    -

    +

    to determine whether the \rgls-like command should behave like its \gls counterpart (⟨normal⟩) or whether it should instead use ⟨trigger code⟩. -

    This command checks if the

    This command checks if the recordcount attribute is set. If not is just does + id="dx1-48019"> attribute is set. If not is just does ⟨normal⟩, otherwise it tests if -


    \glsxtrrecordtriggervalue 


    \glsxtrrecordtriggervalue{label}

    -

    +

    is greater than the value given in the recordcount attribute for that entry’s category. + id="dx1-48021"> attribute for that entry’s category. If true, this does ⟨normal⟩ otherwise it does ⟨trigger code⟩. The default definition of the @@ -20941,104 +20121,90 @@ trigger value command is:

    -
    +
    \newcommand*{\glsxtrrecordtriggervalue}[1]{%  
     \GlsXtrTotalRecordCount{#1}%  
    }
    -

    The ⟨

    The ⟨trigger code⟩ part writes a record with the format set to set to glstriggerrecordformat (which bib2gls v1.1+ recognises as a special type of ignored location format) and does ⟨trigger format⟩. Then it unsets the first use flag. Note that it doesn’t implement the post-link hook. This ensures that the record count is correct on the next run. -

    The ⟨

    The ⟨trigger format⟩ depends on the \rgls-like command used and will be one of the following: -


    \rglsformat 


    \rglsformat{label}{insert}

    -

    -


    \rglsplformat 

    +


    \rglsplformat{label}{insert}

    -

    -


    \rGlsformat 

    +


    \rGlsformat{label}{insert}

    -

    -


    \rGlsplformat 

    +


    \rGlsplformat{label}{insert}

    -

    -


    \rGLSformat 

    +


    \rGLSformat{label}{insert}

    -

    -


    \rGLSplformat 

    +


    \rGLSplformat{label}{insert}

    -

    +

    These all behave much like their \cglsformat counterparts. If the entry’s regular + id="dx1-48031"> attribute is set or if the entry doesn’t have a long form, the first or first plural is used, otherwise the long or long plural form is used. -

    You can use -


    \glsxtrenablerecordcount 

    You can use +


    \glsxtrenablerecordcount

    -

    +

    to redefine \gls, \glspl, \rGls, class="cmtt-10">\rGlspl, \rGLS, \rGLSpl, respectively, for convenience. -

    If you don’t want the entries that use ⟨

    If you don’t want the entries that use ⟨trigger code⟩ to appear in the glossary, you need to use the resource option trigger-type to assign them to another glossary. @@ -21062,7 +20228,7 @@ For example:

    -
    +
    \documentclass{article}  
    \usepackage[record]{glossaries-extra}  
    \newignoredglossary{ignored} @@ -21079,7 +20245,7 @@ For example:  
    \printunsrtglossaries  
    \end{document}
    -

    In the above,

    In the above, stc and upa both only have one record, so they are assigned to the main one.

    -

    -

    +

    Top

    10. Miscellaneous New Commands

    -

    The

    The glossaries package provides \glsrefentry entry to cross-reference entries + id="dx1-49001"> entry to cross-reference entries when used with the entrycounter or or subentrycounter options. The options. The glossaries-extra package provides a supplementary command -


    \glsxtrpageref 


    \glsxtrpageref{label}

    -

    +

    that works in the same way except that it uses \pageref instead of instead of \ref. -

    You can copy an entry to another glossary using -


    \glsxtrcopytoglossary  . +

    You can copy an entry to another glossary using +


    \glsxtrcopytoglossary{entry-label}{glossary-type} -

    -

    +class="cmtt-10">}


    +

    This appends ⟨entry-label⟩ to the end of the internal list for the glossary given by ⟨glossary-type⟩. Be careful if you use the hyperref package as this may cause duplicate + id="dx1-49008"> package as this may cause duplicate hypertargets. You will need to change \glolinkprefix to another value or disable hyperlinks when you display the duplicate. Alternatively, use the new target key to + id="dx1-49009"> key to switch off the targets:

    -
    +
    \printunsrtglossary[target=false]
    -

    -

    The

    +

    The glossaries package allows you to set preamble code for a given glossary type using \setglossarypreamble. This overrides any previous setting. With glossaries-extra (as from v1.12) you can instead append to the preamble using -


    \apptoglossarypreamble 


    \apptoglossarypreamble[type]{code}

    -

    +

    or prepend using -


    \pretoglossarypreamble 


    \pretoglossarypreamble[type]{code}

    -

    +

    -

    Top

    10.1 Entry Fields

    -

    A field may now be used to store the name of a text-block command that takes a +

    A field may now be used to store the name of a text-block command that takes a single argument. The field is given by -


    \GlsXtrFmtField 


    \GlsXtrFmtField

    -

    +

    The default value is useri. Note that the value must be the control sequence name without the initial backslash. -

    For example: +

    For example:

    -
    +
    \newcommand*{\mtx}[1]{\boldsymbol{#1}}  
    \newcommand*{\mtxinv}[1]{\mtx{#1}\sp{-1}}  
    \newglossaryentry{matrix}{% @@ -21225,13 +20380,11 @@ class="cmti-10">without the initial backslash.  
       $\mtx{M}\mtxinv{M}=\glssymbol{identitymatrix}$}  
    }
    -

    -

    There are two commands provided that allow you to apply the command to an +

    +

    There are two commands provided that allow you to apply the command to an argument: -


    \glsxtrfmt 


    \glsxtrfmt[options]{label}{text}

    -

    +

    This effectively does

    cs name⟩ is the control sequence name supplied in must be defined to take a single required argument. Although it effectively acts like \glslink it misses out the post-link hook. -

    The default ⟨

    The default ⟨default-options⟩ are given by -


    \GlsXtrFmtDefaultOptions 


    \GlsXtrFmtDefaultOptions

    -

    +

    This is defined as noindex but may be redefined as appropriate. Note that the replacement text of \GlsXtrFmtDefaultOptions is prepended to the optional argument of \glslink. -

    As from version 1.23, there’s also a starred version of this command that has a +

    As from version 1.23, there’s also a starred version of this command that has a final optional argument: -


    \glsxtrfmt* 


    \glsxtrfmt*[options]{text}[insert]

    -

    +

    Both the starred and unstarred versions use: -


    \glsxtrfmtdisplay 


    \glsxtrfmtdisplay{cs name}{text}{insert} -

    -

    +class="cmtt-10">}


    +

    within the link text. In the case of the unstarred version ⟨insert⟩ will be empty. It will also be empty if the final option argument is missing from the starred form. If the @@ -21324,7 +20470,7 @@ warning if undefaction=warn). There won’t be a warning or error if the entry is + id="dx1-50006">). There won’t be a warning or error if the entry is defined by the given field is missing. In either case, (the entry is undefined or the field is missing) ⟨cs name⟩ will be -

    +
    \newcommand{\glsxtrfmtdisplay}[3]{\csuse{#1}{#2}#3}
    -

    which puts ⟨

    which puts ⟨text⟩ inside the argument of the control sequence and ⟨insert⟩ outside it (but it will still be inside the link text). -

    Remember that nested links cause a problem so avoid using commands like

    Remember that nested links cause a problem so avoid using commands like \gls or \glsxtrfmt within ⟨text⟩.
    -

    -

    For example: +

    +

    For example:

    -
    +
    \[  
      \glsxtrfmt{matrix}{A}  
      \glsxtrfmt{matrixinv}{A} @@ -21360,64 +20506,71 @@ class="cmti-10">text⟩.
     
      \glssymbol{identitymatrix}  
    \]
    -

    If the default options are set to

    If the default options are set to noindex then \glsxtrfmt won’t index, but will create a hyperlink (if hyperref has been loaded). This can be changed so that it also + id="dx1-50007"> has been loaded). This can be changed so that it also suppresses the hyperlink:

    -
    +
    \renewcommand{\GlsXtrFmtDefaultOptions}{hyper=false,noindex}
    -

    -

    Note that

    +

    Note that \glsxtrfmt won’t work with PDF bookmarks. Instead you can use -


    \glsxtrentryfmt 


    \glsxtrentryfmt{label}{text}

    -

    -This uses \texorpdfstring and will simply expand to ⟨text⟩ within the PDF -bookmarks, but in the document it will do ⟨

    +If hyperref is used, this uses \texorpdfstring and will expand to +


    \glsxtrpdfentryfmt{label}{text}

    +

    +within the PDF bookmarks, but in the document it will do ⟨cs{text} if a control sequence name has -been provided or just ⟨text⟩ otherwise. -

    The } if a control +sequence name has been provided or just ⟨text⟩ otherwise. The PDF bookmark version +simply does ⟨text⟩. It may be redefined, but remember that it needs to expand +fully. +

    The glossaries package provides \glsaddstoragekey to add new keys. This command will cause an error if the key has already been defined. The glossaries-extra package provides a supplementary command that will only define the key if it doesn’t already exist: -


    \glsxtrprovidestoragekey 


    \glsxtrprovidestoragekey{key}{default}{cs} -

    -

    +class="cmtt-10">}


    +

    If the key has already been defined, it will still provide the command given in the third argument ⟨cs⟩ (if it hasn’t already been defined). Unlike cs⟩ may be left empty if you’re happy to just use \glsfieldfetch to fetch the value of this new key. -

    You can test if a key has been provided with: -


    \glsxtrifkeydefined 

    You can test if a key has been provided with: +


    \glsxtrifkeydefined{key}{true}{false}

    -

    +

    This tests if ⟨key⟩ is available for use in the ⟨key⟩= list in the second argument of @@ -21447,22 +20598,20 @@ class="cmtt-10">\newglossaryentry (or the optional argument of commands l class="cmtt-10">\newabbreviation). The corresponding field may not have been set for any of the entries if no default was provided. -

    There are now commands provided to set individual fields. Note that +

    There are now commands provided to set individual fields. Note that these only change the specified field, not any related values. For example, changing the value of the text field won’t update the field won’t update the plural field. There are also + id="dx1-50014"> field. There are also some fields that should really only be set when entries are defined (such as the parent field). Unexpected results may occur if they are subsequently + id="dx1-50015"> field). Unexpected results may occur if they are subsequently changed. -


    \GlsXtrSetField 


    \GlsXtrSetField{label}{field}{value}

    -

    +

    Sets the field given by ⟨field⟩ to ⟨value⟩ for the entry given by ⟨\glsxtrusefield. Note that \glsxtrifkeydefined only + + + tests if a key has been defined for use with commands like \newglossaryentry. If a field without a corresponding key is assigned a value, the key remains undefined. This command is robust. - - - -

    \GlsXtrSetField uses -


    \glsxtrsetfieldifexists 


    \glsxtrsetfieldifexists{label}{field}{code} -

    -

    +class="cmtt-10">}


    +

    where ⟨label⟩ is the entry label and ⟨code⟩ is the assignment code. -

    This command just uses

    This command just uses \glsdoifexists{label}{undefaction=warn. You can redefine + id="dx1-50019">. You can redefine \glsxtrsetfieldifexists to simply do ⟨code⟩ if you want to skip the existence check. Alternatively you can instead use -


    \glsxtrdeffield 


    \glsxtrdeffield{label}{field}arguments{replacement -text}

    -

    +class="cmitt-10">replacement text⟩} +


    +

    This simply uses etoolbox’s ’s \csdef without any checks. This command isn’t robust. There is also a version that uses \protected@csedef instead:10.1 -


    \glsxtredeffield  +


    \glsxtredeffield{label}{field}arguments{replacement -text}

    -

    -


    \gGlsXtrSetField  replacement text} +

    +

    +


    \gGlsXtrSetField{label}{field}{value}

    -

    +

    As \GlsXtrSetField but globally. -


    \eGlsXtrSetField 


    \eGlsXtrSetField{label}{field}{value}

    -

    +

    As \GlsXtrSetField but uses protected expansion. -


    \xGlsXtrSetField 


    \xGlsXtrSetField{label}{field}{value}

    -

    +

    As \gGlsXtrSetField but uses protected expansion. -


    \GlsXtrLetField 


    \GlsXtrLetField{label}{field}{cs}

    -

    +

    Sets the field given by ⟨field⟩ to the replacement text of ⟨cs⟩ for the entry given by ⟨label⟩ (using \let). -


    \csGlsXtrLetField 


    \csGlsXtrLetField{label}{field}{cs name} -

    -

    +class="cmtt-10">}


    +

    As \GlsXtrLetField but the control sequence name is supplied instead. -


    \GlsXtrLetFieldToField 


    \GlsXtrLetFieldToField{label-1}{field-1} -{}{label-2}{field-2}

    -

    +class="cmtt-10">} +


    +

    Sets the field given by ⟨field-1⟩ for the entry given by ⟨label-1⟩ to the field given by @@ -21672,19 +20798,17 @@ class="cmti-10">code⟩} is still used, as for \GlsXtrSetField. -

    The

    The glossaries package provides \ifglshasfield to determine if a field has been + id="dx1-50030"> to determine if a field has been set. The glossaries-extra package provides a simpler version: - - - -


    \glsxtrifhasfield 


    \glsxtrifhasfield{field}{}{true}{false} -

    -

    +class="cmtt-10">}


    +

    (New to v1.19.) Note that in this case the ⟨field⟩ must be the internal field label (for @@ -21712,20 +20835,16 @@ class="cmti-10">true⟩ part is done otherwise it does ⟨false⟩. Within ⟨true⟩ you may use -


    \glscurrentfieldvalue 


    \glscurrentfieldvalue

    -

    +

    to access the field value. This command includes grouping which scopes the ⟨true⟩ and ⟨false⟩ parts. The starred version -


    \glsxtrifhasfield* 


    \glsxtrifhasfield*{field}{}{true}{false} -

    -

    +class="cmtt-10">}


    +

    omits the implicit grouping. -

    Be careful of keys that use

    Be careful of keys that use \relax as the default value (such as the symbol). Use + id="dx1-50034">). Use \ifglshassymbol instead.
    -

    -

    There is also a version that simply uses

    +

    There is also a version that simply uses \ifcsundef. It doesn’t save the field value, but can be used if you only need to check if the field is defined without accessing it: -


    \GlsXtrIfFieldUndef 


    \GlsXtrIfFieldUndef{field}{}{true}{false} -

    -

    -

    There’s a difference between an undefined field and an unset field. An undefined +class="cmtt-10">}

    +

    +

    There’s a difference between an undefined field and an unset field. An undefined field hasn’t been assigned any value (no associated internal control sequence has been defined). If a defined field has been defined to empty, then it’s considered unset. \GlsXtrIfFieldUndef for fields that can only be defined through commands like \GlsXtrSetField.
    -

    -

    You can test if a field value equals a string using -


    \GlsXtrIfFieldEqStr 

    +

    You can test if a field value equals a string using +


    \GlsXtrIfFieldEqStr{field}{}{text}{true} -{}{false}

    -

    +

    If the entry exists and has the given field set to the given text then this does ⟨true⟩ otherwise it does ⟨false⟩. This uses \glsxtrifhasfield to test if the field exists and - - - then compares the replacement text of \glscurrentfieldvalue with ⟨text⟩ using etoolbox’s ’s \ifdefstring. Version 1.39 introduced a starred form of this command, + + + which uses the starred form of \glsxtrifhasfield. -

    As from version 1.31, there’s a similar command: -


    \GlsXtrIfFieldEqXpStr 

    As from version 1.31, there’s a similar command: +


    \GlsXtrIfFieldEqXpStr{field}{label}{text} -{}{true}{false}

    -

    +

    This is like \GlsXtrIfFieldEqStr but first (protected) fully expands ⟨text⟩ (but not the field value). If you want to compare the (protected) full expansion of both the field value and ⟨text⟩ use: -


    \GlsXtrIfXpFieldEqXpStr 


    \GlsXtrIfXpFieldEqXpStr{field}{label}{text} -{}{true}{false}

    -

    +class="cmtt-10">} +


    +

    Again, version 1.39 introduced a starred form of these commands, which use the starred form of \glsxtrifhasfield. -

    As from v1.31, if a field represents a numeric (integer) value, you can use the +

    As from v1.42, you can test if the field value is contained in a comma-separated +list with: +


    \GlsXtrIfFieldValueInCsvList{label}{field}{list}{true}{false} +

    +

    +The unstarred version uses the unstarred form of \glsxtrifhasfield (which +adds grouping so ⟨true⟩ and ⟨false⟩ will be localised). The starred version uses +\glsxtrifhasfield*. If the field value (without expansion) is contained in ⟨list⟩ then +⟨true⟩ is done otherwise ⟨false⟩ is done. If the field hasn’t been set ⟨false⟩ is done. This +internally uses \DTLifinlist provided by datatool-base which performs +a one level expansion on ⟨list⟩. See the datatool documentation for further +details. +

    This command is intended for fields that contain a label. For example, to test if +the category is one of a set of labels: + + + +

    +
    +\GlsXtrIfFieldValueInCsvList{examplelabel}{category}% + 
     {abbreviation,acronym}% set of labels + 
     {true part}{false part} +
    +

    +

    As from v1.31, if a field represents a numeric (integer) value, you can use the following two numeric tests. If the field is set, it must expand to an integer. You may use \glscurrentfieldvalue within ⟨\glscurrentfieldvalue is set accordingly. As from version 1.39, these numeric tests have starred versions. The unstarred versions add implicit grouping. The starred versions don’t. -

    To test if the value is non-zero: -


    \GlsXtrIfFieldNonZero 

    To test if the value is non-zero: +


    \GlsXtrIfFieldNonZero{field}{label}{true} -{}{false}

    -

    +

    Alternatively, you can test if the field expands to a specific number using: -


    \GlsXtrIfFieldEqNum 


    \GlsXtrIfFieldEqNum{field}{}{n}{true} -{}{false}

    -

    +

    This does ⟨true⟩ if the field value equals ⟨n⟩ (using \ifnum for the comparison) otherwise it does ⟨false⟩. For a more general numeric comparison you can use: -


    \GlsXtrIfFieldCmpNum 


    \GlsXtrIfFieldCmpNum{field}{label}{comparison} -{}{n}{true}{false}

    -

    +class="cmtt-10">} +


    +

    where ⟨comparison⟩ is one of =, < or >. -

    The

    The glossaries package provides \glsfieldfetch which can be used to fetch the + id="dx1-50046"> which can be used to fetch the value of the given field and store it in a control sequence. The glossaries-extra package provides another way of accessing the field value: -


    \glsxtrusefield 


    \glsxtrusefield{entry-label}{field-label}

    -

    +

    This works in the same way as commands like \glsentrytext but the field label is specified in the first argument. Note that the ⟨field-label⟩ corresponds to the internal field tag, which isn’t always the same as the key name. See Table 4.1 of the glossaries + id="dx1-50048"> manual. No error occurs if the entry or field haven’t been defined. This command is - - - not robust. -

    There is also a version that converts the first letter to uppercase (analogous to +

    There is also a version that converts the first letter to uppercase (analogous to \Glsentrytext): -


    \Glsxtrusefield 


    \Glsxtrusefield{entry-label}{field-label}

    -

    +

    and, as from v1.37, a command that converts the entire value to upper case: -


    \GLSxtrusefield 


    \GLSxtrusefield{entry-label}{field-label}

    -

    -

    If you want to use a field to store a list that can be used as an

    +

    If you want to use a field to store a list that can be used as an etoolbox internal + id="dx1-50051"> internal list, you can use the following command that adds an item to the field using etoolbox’s ’s \listcsadd: -


    \glsxtrfieldlistadd 


    \glsxtrfieldlistadd{label}{field}{item} -

    -

    +class="cmtt-10">}


    +

    where ⟨label⟩ is the entry’s label, ⟨field⟩ is the entry’s field and ⟨\listgadd, \listeadd and \listxadd: -


    \glsxtrfieldlistgadd 


    \glsxtrfieldlistgadd{label}{field}{item} -

    -

    -


    \glsxtrfieldlisteadd  }

    +

    +


    \glsxtrfieldlisteadd{label}{field}{item} -

    -

    -


    \glsxtrfieldlistxadd  }

    +

    +


    \glsxtrfieldlistxadd{label}{field}{item} -

    -

    +class="cmtt-10">}


    +

    You can then iterate over the list using: -


    \glsxtrfielddolistloop 


    \glsxtrfielddolistloop{label}{field} -

    -

    +class="cmtt-10">}


    +

    or -


    \glsxtrfieldforlistloop 


    \glsxtrfieldforlistloop{label}{field} -{}{handler}

    -

    +

    that internally use \dolistcsloop and \forlistloop, respectively. -

    There are also commands that use \forlistloop, respectively. You can use +\listbreak to break out of the loop (see the etoolbox manual for further +details). +

    For fields that contain comma-separated lists use \glsxtrforcsvfield +instead. +

    New to v1.42: +


    \glsxtrfieldformatlist{label}{field}

    +

    +Like datatool-base’s \DTLformatlist, this iterates over an (etoolbox) internal list and +formats each item. Uses all the same helper commands as \DTLformatlist (the same +list handler macro is used). Unlike the datatool-base command, this command has no +starred version. Grouping is automatically applied. +

    For example, with bib2gls’s save-child-count resource option: + + + +

    +
    +\newcommand*{\listchildren}[1]{% + 
      \GlsXtrIfFieldNonZero{childcount}{#1}% + 
      {child count: \glscurrentfieldvalue; children: + 
       \let\DTLlistformatitem\glsfmtname + 
       \glsxtrfieldformatlist{#1}{childlist}% + 
      }% + 
      {no children}% + 
    } +
    +

    For fields that contain a comma-separated list use \glsxtrfieldformatcsvlist +instead. +

    There are also commands that use \ifinlistcs: -


    \glsxtrfieldifinlist 


    \glsxtrfieldifinlist{label}{}{item}{true} -{}{false}

    -

    +

    and \xifinlistcs -


    \glsxtrfieldxifinlist 


    \glsxtrfieldxifinlist{label}{field}{item} -{}{true}{false}

    - - - -

    -

    See the

    +

    See the etoolbox’s user manual for further details of these commands, in particular + id="dx1-50069">’s user manual for further details of these commands, in particular the limitations of \ifinlist. -

    If the field has a comma-separated list value instead, you can iterate over it +

    If the field has a comma-separated list value instead, you can iterate over it using: -


    \glsxtrforcsvfield 


    \glsxtrforcsvfield{label}{field}{handler} -

    -

    +class="cmtt-10">}


    +

    where again ⟨handler⟩ is a control sequence that takes a single argument. Unlike the etoolbox loops, this doesn’t ignore empty elements nor does it discard leading / + id="dx1-50071"> loops, this doesn’t ignore empty elements nor does it discard leading / trailing spaces. Internally it uses \@for (modified by xfor which is automatically + id="dx1-50072"> which is automatically loaded by glossaries). The ). The xfor package modifies the behaviour of package modifies the behaviour of \@for to allow the loop to be broken prematurely using \@endfortrue. The \glsxtrforcsvfield command locally defines a user level command: -


    \glsxtrendfor 


    \glsxtrendfor

    -

    +

    which is just a synonym for \@endfortrue. -

    The loop is performed within the true part of

    The loop is performed within the true part of \glsxtrifhasfield so scoping is automatically applied. -

    As from version 1.32, if the field given by -


    \GlsXtrForeignTextField 

    New to v1.42: +


    \glsxtrfieldformatcsvlist{label}{field}

    +

    +Like \glsxtrfieldformatcsvlist but for fields that contain comma-separated +lists. +

    As from version 1.32, if the field given by +


    \GlsXtrForeignTextField

    -

    + + + +

    (which defaults to userii) contains a locale tag, then -


    \GlsXtrForeignText 


    \GlsXtrForeignText{entry label}{text}

    -

    +

    can be used to encapsulate ⟨text⟩ in \foreignlanguage{} where ⟨dialect⟩ is obtained from the locale tag through tracklang’s ’s \GetTrackedDialectFromLanguageTag + id="dx1-50080"> command. You need at least tracklang v1.3.6 for this to work properly. The ⟨ v1.3.6 for this to work properly. The ⟨dialect⟩ must be one that’s tracked (which typically means that babel or or polyglossia has been + id="dx1-50083"> has been loaded with the appropriate setting for that language). If \foreignlanguage hasn’t been defined, this just does ⟨text⟩. For example:

    -
    +
    \documentclass{article}  
    \usepackage[main=british,brazilian,ngerman]{babel}  
    \usepackage{glossaries-extra} @@ -22267,31 +21433,29 @@ class="cmti-10">text⟩. For example:  
    \gls{abnt}, \gls{din}.  
    \end{document}
    -

    -

    When using the

    +

    When using the record option, in addition to recording the usual location, you can + id="dx1-50084"> option, in addition to recording the usual location, you can also record the current value of another counter at the same time using the preamble-only command: -


    \GlsXtrRecordCounter 


    \GlsXtrRecordCounter{counter name}

    -

    +

    For example:

    -
    +
    \usepackage[record]{glossaries-extra}  
    \GlsXtrRecordCounter{section}
    -

    Each time an entry is referenced with commands like

    Each time an entry is referenced with commands like \gls or \glstext, the \gls{bird} is used in section 1.2 th -

    +
    \glsxtrfieldlistgadd{bird}{record.section}{1.2}
    -

    Note that there’s no key corresponding to this new

    Note that there’s no key corresponding to this new record.section field, but its value can be accessed with \glsxtrfielduse or the list can be iterated over with \glsxtrfielddolistloop etc. -

    +

    -

    Top

    10.2 Display All Entries Without Sorting or Indexing

    -


    \printunsrtglossary 


    \printunsrtglossary[options]

    -

    +

    This behaves like \printnoidxglossary but never sorts the entries and always lists all the defined entries for the given glossary (and doesn’t require \makenoidxglossaries). If you want to use one of the tabular-like styles with + id="dx1-51002">-like styles with \printunsrtglossary, make sure you load glossaries-extra-stylemods which modifies + id="dx1-51004"> which modifies the definition of \glsgroupskip to avoid the “Incomplete \iftrue” error that may otherwise occur. -

    There’s also a starred form -


    \printunsrtglossary* 

    There’s also a starred form +


    \printunsrtglossary*[options]{code}

    -

    +

    which is equivalent to

    \endgroup class="cmtt-10">\glossarypreamble, the supplied ⟨code⟩ is done before the glossary header. -

    This means you now have the option to simply list all entries on the first +

    This means you now have the option to simply list all entries on the first LATEX run without the need for a post-processor, however there will be no number list in this case, as that has to be set by a post-processor such as bib2gls (see §9 bib2gls: Managing Reference Databases). -

    No attempt is made to gather hierarchical elements. If child entries aren’t defined +

    No attempt is made to gather hierarchical elements. If child entries aren’t defined immediately after their parent entry, they won’t be together in the glossary when using \printunsrtglossary.
    -

    +

    -

    There’s a difference in behaviour depending on whether or not the

    There’s a difference in behaviour depending on whether or not the group key is -defined. If not defined (default), the group label will be formed from the first -letter of the key is +defined. If not defined (default), the group label will be formed from the first letter of +the name field. The corresponding group title will be obtained as -discussed in field. The corresponding group title will be obtained as discussed +in §2.12 §2.10.1 Glossary Style Modifications. This can lead to an odd effect if you are using a style that separates letter groups when the ordering isn’t alphabetical. -

    If the

    If the group key is defined (which it is with the key is defined (which it is with the record option) then the group label + id="dx1-51011"> option) then the group label will be obtained from the value of that field. If the field is empty, no grouping is performed, even if the style supports it. (That is, there won’t be a header or a vertical separation.) If the group field is non-empty, then the corresponding title is obtained + id="dx1-51012"> field is non-empty, then the corresponding title is obtained as described earlier. -

    If you want to use a different field, you can redefine -


    \glsxtrgroupfield 

    If you want to use a different field, you can redefine +


    \glsxtrgroupfield

    -

    +

    to the relevant internal field label, but the group key must still be defined (through the record option or with commands like option or with commands like \glsaddstoragekey) to ensure that \printunsrtglossary uses \glsxtrgroupfield. (This method is used by bib2gls for secondary entries, which have the group label stored in the secondarygroup internal field.) -

    If you have any entries with the

    If you have any entries with the see key set, you will need the key set, you will need the glossaries package + id="dx1-51018"> package option seenoindex=ignore or or seenoindex=warn to prevent an error occurring from the + id="dx1-51020"> to prevent an error occurring from the automated \glssee normally triggered by this key. The record=only package option + id="dx1-51021"> package option will automatically deal with this. -

    For example: +

    For example:

    -
    +
    \documentclass{article}  
    \usepackage{glossaries-extra}  
    \newglossaryentry{zebra}{name={zebra},description={stripy animal}} @@ -22511,191 +21669,169 @@ will automatically deal with this.  
    \printunsrtglossaries  
    \end{document}
    -

    In the above, zebra will be listed before ant as it was defined first. -

    If you allow document definitions with the

    In the above, zebra will be listed before ant as it was defined first. +

    If you allow document definitions with the docdefs option, the document will + id="dx1-51022"> option, the document will require a second LATEX run if the entries are defined after \printunsrtglossary. -

    The optional argument is as for

    The optional argument is as for \printnoidxglossary (except for the sort key, + id="dx1-51023"> key, which isn’t available). -

    All glossaries may be displayed in the order of their definition using: -


    \printunsrtglossaries 

    All glossaries may be displayed in the order of their definition using: +


    \printunsrtglossaries

    -

    +

    which is analogous to \printnoidxglossaries. This just iterates over all defined glossaries (that aren’t on the ignored list) and does \printunsrtglossary[type=⟨type⟩]. -

    To avoid complications caused by

    To avoid complications caused by tabular-like glossary styles, -like glossary styles, \printunsrtglossary iterates over all entries in the selected glossary and appends the appropriate code to an internal command. Once the construction of this command is complete, then it’s performed to display the glossary. This puts the loop outside the style code. For convenience, there’s a hook used within the loop: -


    \printunsrtglossaryentryprocesshook  \printunsrtglossaryentryprocesshook -{


    \printunsrtglossaryentryprocesshook{label}

    -

    +

    This hook should not display any content, but may be used to perform calculations. For example, to calculate widths. Within this hook you can use: -


    \printunsrtglossaryskipentry 


    \printunsrtglossaryskipentry

    -

    +

    to skip the current entry. This will prevent the entry from being added to the internal command. -

    There’s another hook immediately before the internal command containing the +

    There’s another hook immediately before the internal command containing the glossary code is performed: -


    \printunsrtglossarypredoglossary  \printunsrtglossarypredoglossary -

    -

    +


    \printunsrtglossarypredoglossary

    +

    +

    The internal command uses -

    The internal command uses -


    \printunsrtglossaryhandler 


    \printunsrtglossaryhandler{label} -

    -

    +class="cmtt-10">}


    +

    to display each item in the list, where ⟨label⟩ is the current label. -

    By default the handler just does -


    \glsxtrunsrtdo 

    By default the handler just does +


    \glsxtrunsrtdo{label}

    -

    +

    which determines whether to use \glossentry or \subglossentry and checks the location and and loclist fields for the fields for the number list. If you want to use a different field to be used instead of location then redefine: -


    \GlsXtrLocationField  then redefine: +


    \GlsXtrLocationField

    -

    +

    to the internal name of the desired field. For example:

    -
    +
    \renewcommand{\GlsXtrLocationField}{primarylocation}
    -

    -

    Note that if the given location field is undefined or unset, the handler will +

    +

    Note that if the given location field is undefined or unset, the handler will fallback on the loclist field.
    -

    + id="dx1-51037"> field.

    +

    You can instruct bib2gls to omit setting the loclist field with the resource option + id="dx1-51039"> field with the resource option --save-loclist=false to prevent it from being used as a fallback. -

    You can redefine the handler if required. For example, you may want to filter +

    You can redefine the handler if required. For example, you may want to filter entries according to the category label. You can test if a label is contained in a comma-separated list of labels using: -


    \glsxtriflabelinlist 


    \glsxtriflabelinlist{label}{label list}{true} -{}{false}

    -

    +

    The ⟨label⟩ and ⟨label list⟩ will be fully expanded. -

    If you redefine the handler to exclude entries, you may end up with an empty +

    If you redefine the handler to exclude entries, you may end up with an empty glossary. This could cause a problem for the list-based styles.
    -

    -

    For example, if the preamble includes: +

    +

    For example, if the preamble includes:

    -
    +
    \usepackage[record,style=index]{glossaries-extra}  
    \GlsXtrRecordCounter{section}
    -

    then you can print the glossary but first redefine the handler to only select entries +

    then you can print the glossary but first redefine the handler to only select entries that include the current section number in the record.section field:

    -
    +
    \renewcommand{\printunsrtglossaryhandler}[1]{%  
      \glsxtrfieldxifinlist{#1}{record.section}{\thesection}  
      {\glsxtrunsrtdo{#1}}%  
      {}%  
    }
    -

    -

    Alternatively you can use the starred form of

    +

    Alternatively you can use the starred form of \printunsrtglossary which will localise the change:

    -
    +
    \printunsrtglossary*{%  
      \renewcommand{\printunsrtglossaryhandler}[1]{%  
        \glsxtrfieldxifinlist{#1}{record.section}{\thesection} @@ -22704,10 +21840,10 @@ localise the change:  
      }%  
    }
    -

    -

    If you are using the

    +

    If you are using the hyperref package and want to display the same glossary more + id="dx1-51041"> package and want to display the same glossary more than once, you can also add a temporary redefinition of \glolinkprefix to avoid duplicate hypertarget names. For example: @@ -22715,7 +21851,7 @@ duplicate hypertarget names. For example:

    -
    +
    \printunsrtglossary*{%  
      \renewcommand{\printunsrtglossaryhandler}[1]{%  
        \glsxtrfieldxifinlist{#1}{record.section}{\thesection} @@ -22731,7 +21867,7 @@ duplicate hypertarget names. For example:  
      }%  
    }
    -

    Note that this will cause a problem if your descriptions contain commands like

    Note that this will cause a problem if your descriptions contain commands like \gls that need to link an entry that doesn’t appear in the summary. In this case, it’s a better approach to use: @@ -22739,7 +21875,7 @@ better approach to use:

    -
    +
    \printunsrtglossary*{%  
      \renewcommand{\printunsrtglossaryhandler}[1]{%  
        \glsxtrfieldxifinlist{#1}{record.section}{\thesection} @@ -22755,14 +21891,14 @@ better approach to use:  
      }%  
    }
    -

    -

    If it’s a short summary at the start of a section, you might also want to suppress +

    +

    If it’s a short summary at the start of a section, you might also want to suppress the glossary header and add some vertical space afterwards:

    -
    +
    \printunsrtglossary*{%  
      \renewcommand{\printunsrtglossaryhandler}[1]{%  
        \glsxtrfieldxifinlist{#1}{record.section}{\thesection} @@ -22780,64 +21916,56 @@ the glossary header and add some vertical space afterwards:  
      \appto\glossarypostamble{\glspar\medskip\glspar}%  
    }
    -

    -

    There’s a shortcut command that essentially does this: -


    \printunsrtglossaryunit 

    +

    There’s a shortcut command that essentially does this: +


    \printunsrtglossaryunit[options]{counter -namecounter name}

    -

    +

    The above example can simply be replaced with:

    -
    +
    \printunsrtglossaryunit{section}
    -

    -

    This shortcut command is actually defined to use

    +

    This shortcut command is actually defined to use \printunsrtglossary* with -


    \printunsrtglossaryunitsetup 


    \printunsrtglossaryunitsetup{counter -namecounter name}

    -

    +

    so if you want to just make some minor modifications you can do

    -
    +
    \printunsrtglossary*{\printunsrtglossaryunitsetup{section}%  
      \renewcommand*{\glossarysection}[2][]{\subsection*{Summary}}%  
    }
    -

    which will start the list with a subsection header with the title “Summary” +

    which will start the list with a subsection header with the title “Summary” (overriding the glossary’s title). -

    Note that this shortcut command is only available with the

    Note that this shortcut command is only available with the record (or + id="dx1-51044"> (or record=alsoindex) package option. -

    This temporary change in the hypertarget prefix means you need to explicitly use + id="dx1-51045">) package option. +

    This temporary change in the hypertarget prefix means you need to explicitly use \hyperlink to create a link to it as commands like \gls will try to link to the target @@ -22849,12 +21977,12 @@ the front or back matter) which can be the target for all glossary references an just use \printunsrtglossaryunit for a quick summary at the start of a section etc. -

    +

    -

    Top

    10.3 Standalone Entry Items

    -

    It may be that you don’t want a list but would rather display entry details +

    It may be that you don’t want a list but would rather display entry details throughout the document. You can simply do \glsentryname followed by \glsentrydesc. (Remember that if you don’t want a s href="#styopt.sort">sort=none to + id="dx1-52001"> to skip the construction of the sort field.) For example, in the preamble provide a + id="dx1-52002"> field.) For example, in the preamble provide a custom command:

    -
    +
    \newcommand{\displayterm}[1]{%  
     \par\medskip\par\noindent  
     Definition: \glsentryname{#1}.\par @@ -22879,43 +22007,41 @@ custom command:  
     \par\medskip  
    }
    -

    define your entries +

    define your entries

    -
    +
    \newglossaryentry{function}{name={function},  
      description={a relation or expression involving variables}  
    }
    -

    and then later in the text: +

    and then later in the text:

    -
    +
    \displayterm{function}
    -

    -

    However, if may be that you want to use

    +

    However, if may be that you want to use hyperref and have commands like and have commands like \gls link back to the place where the term is described. Instead of using \glsentryname use -


    \glsxtrglossentry 


    \glsxtrglossentry{label}

    -

    +

    where ⟨label⟩ is the entry’s label. -

    This is designed to behave much like the way the name is displayed in the +

    This is designed to behave much like the way the name is displayed in the glossary. It performs the following:

    • Defines \printglossary and may be used by style hooks. class="cmtt-10">\glsentryitem and \glssubentryitem. The value is obtained by fully expanding: -


      \GlsXtrStandaloneGlossaryType  \GlsXtrStandaloneGlossaryType -

      -

      +


      \GlsXtrStandaloneGlossaryType

      +

      which defaults to the value of the type field for the current entry. + id="dx1-52006"> field for the current entry.

    • Increments and display the entry counters if the entrycounter or or subentrycounter + id="dx1-52008"> package options are set. If the entry doesn’t have a parent, then this does -

      otherwise it does (as from v1.31)

      +

      otherwise it does (as from v1.31)

      • \GlsXtrStandaloneSubEntryItem + id="dx1-52009"> {label} if the entry has -

        This reflects the behaviour of the predefined hierarchical styles. A bug in +

        This reflects the behaviour of the predefined hierarchical styles. A bug in pre-version 1.31 used \glsentryitem for all child levels, which doesn’t match the hierarchical glossary styles. If you want to restore this behaviour, just @@ -22987,23 +22110,20 @@ class="cmtt-10">\glsentryitem for all child levels, which doesn’t m

        -
        +
        \renewcommand*{\GlsXtrStandaloneSubEntryItem}[1]{\glssubentryitem{#1}}
        -

        +

      • Sets the hyper-target if supported (using \glstarget) and displays the entry name using: -


        \GlsXtrStandaloneEntryName 


        \GlsXtrStandaloneEntryName{label} -

        -

        +class="cmtt-10">}


        +

        which uses \glstarget{label\glsnamefont or picks up the style from category attributes such as glossnamefont.

      -

      If you have used .

    +

    If you have used \nopostdesc or or \glsxtrnopostpunc in any of your description fields, + id="dx1-52013"> in any of your description fields, you can use -


    \glsxtractivatenopost 


    \glsxtractivatenopost

    -

    +

    to make these commands behave as they normally do within a glossary. This needs to be placed before

    @@ -23044,22 +22162,19 @@ class="cmtt-10">}\glspostdescription class="cmtt-10">\glsnonextpages and \glsnextpages have no effect outside of the glossary and are not intended for use in a standalone context. -

    It’s also possible to select a different field (rather than using

    It’s also possible to select a different field (rather than using name): -


    \glsxtrglossentryother  ): +


    \glsxtrglossentryother{header}{label}{field} -

    -

    +class="cmtt-10">}


    +

    The ⟨field⟩ must be given using its internal field label which may not be the same as the key used to set the field. See the key to field mappings table in the field⟩ class="cmtt-10">{⟨label}. - - -

  • Otherwise ⟨header⟩ is simply the field value.
  • -

    The

    The \glsxtrglossentryother command internally uses -


    \GlsXtrStandaloneEntryOther 


    \GlsXtrStandaloneEntryOther{label}{field} -

    -

    +class="cmtt-10">}


    +

    instead of \GlsXtrStandaloneEntryName, which uses \glossentrynameother{} instead of \glossentryname{label}. -

    If you have loaded the

    If you have loaded the glossaries-accsupp package (through the package (through the accsupp option) + id="dx1-52019"> option) then accessibility support will be provided if there’s a corresponding command

    @@ -23131,12 +22243,12 @@ class="cmtt-10">}
    (for example, \glssymbolaccessdisplay). -

    This means that my custom command can be changed to: +

    This means that my custom command can be changed to:

    -
    +
    \newcommand{\displayterm}[1]{%  
     \par\medskip\par\noindent  
     Definition: \glsxtrglossentry{#1}.\par @@ -23144,17 +22256,17 @@ class="cmtt-10">\glssymbolaccessdisplay).  
     \par\medskip  
    }
    -

    If I want numbered definitions, then I can use the package options

    If I want numbered definitions, then I can use the package options entrycounter or + id="dx1-52020"> or subentrycounter and remove the colon: + id="dx1-52021"> and remove the colon:

    -
    +
    \newcommand{\displayterm}[1]{%  
     \par\medskip\par\noindent  
     Definition \glsxtrglossentry{#1}.\par @@ -23162,28 +22274,28 @@ class="cmss-10">subentrycounter \par\medskip  
    }
    -

    The counter label uses a dot after the number by default but this can be changed to +

    The counter label uses a dot after the number by default but this can be changed to a colon:

    -
    +
    \renewcommand*{\glsentrycounterlabel}{\theglossaryentry:\space}
    -

    It’s now possible to not only use

    It’s now possible to not only use \gls to link back to the definition but also use \glsrefentry to reference the counter and \glsxtrpageref to reference the page number. -

    If I want the description to behave more like it does in a glossary in need to make +

    If I want the description to behave more like it does in a glossary in need to make the following modification:

    -
    +
    \newcommand{\displayterm}[1]{%  
     \par\medskip\par\noindent  
     Definition \glsxtrglossentry{#1}.\par @@ -23194,18 +22306,18 @@ the following modification:  
     \par\medskip  
    }
    -

    (Note the grouping to localise

    (Note the grouping to localise \glsxtractivatenopost.) -

    You can also use

    You can also use \glsxtrglossentry within section headings. For example:

    -
    +
    \section{\glsxtrglossentry{function}}
    -

    This will use

    This will use \glsentryname in PDF bookmarks (if \texorpdfstring is defined) and will use \@glsxtrnotinmark and \glsxtrrestoremarkhook.) -

    +

    -

    Top

    10.4 Entry Aliases

    -

    An entry can be made an alias of another entry using the

    An entry can be made an alias of another entry using the alias key. The + id="dx1-53001"> key. The value should be the label of the other term. There’s no check for the other’s existence when the aliased entry is defined. This is to allow the possibility of defining the other entry after the aliased entry. (For example, when used with bib2gls.) -

    If an entry ⟨

    If an entry ⟨entry-1⟩ is made an alias of ⟨entry-2⟩ then:

    • If the see field wasn’t provided when ⟨ field wasn’t provided when ⟨entry-1⟩ was defined, the alias key will + id="dx1-53004"> key will automatically trigger
      }
    • If the hyperref package has been loaded then package has been loaded then \gls{entry-1} will link to @@ -23267,7 +22379,7 @@ class="cmtt-10">} will link to class="cmti-10">entry-2⟩’s target. (Unless the targeturl attribute has been set for ⟨ attribute has been set for ⟨entry-1⟩’s category.)
    • @@ -23275,20 +22387,20 @@ class="cmti-10">entry-1⟩’s href="#styopt.record">record=off or or record=alsoindex, the , the noindex setting will automatically + id="dx1-53009"> setting will automatically be triggered when referencing ⟨entry-1⟩ with commands like \gls or \glstext. This prevents ⟨entry-1⟩ from have a location list (aside from the cross-reference added with \glssee) unless it’s been explicitly @@ -23299,96 +22411,309 @@ class="cmtt-10">noindex=false. -

      Note that with

      Note that with record=only, the location list for aliased entries is controlled + id="dx1-53011">, the location list for aliased entries is controlled with bib2gls’s settings.

    -

    The index suppression trigger is performed by -


    \glsxtrsetaliasnoindex 

    The index suppression trigger is performed by +


    \glsxtrsetaliasnoindex

    -

    +

    This is performed after the default options provided by \GlsXtrSetDefaultGlsOpts + id="dx1-53015"> have been set. With record=only, , \glsxtrsetaliasnoindex will default to do nothing. -

    Within the definition of

    Within the definition of \glsxtrsetaliasnoindex you can use -


    \glsxtrindexaliased 


    \glsxtrindexaliased

    -

    +

    to index ⟨entry-2⟩. -

    The index suppression command can be redefined to index the main term instead. +

    The index suppression command can be redefined to index the main term instead. For example:

    -
    -\renewcommand{\glsxtrsetaliasnoindex}{% - 
     \glsxtrindexaliased - 
     \setkeys{glslink}{noindex}% - 
    } +
    +\renewcommand{\glsxtrsetaliasnoindex}{% + 
     \glsxtrindexaliased + 
     \setkeys{glslink}{noindex}% + 
    } +
    +

    +

    The value of the alias field can be accessed using +


    \glsxtralias{label}

    +

    + + + +

    +

    +

    Top

    11. On-the-Fly Document Definitions

    +

    The commands described here may superficially look like ⟨word\index{word}, +but they behave rather differently. If you want to use \index then just use \index. +
    +

    +

    The glossaries package advises against defining entries in the document +environment. As mentioned in §1.2 New or Modified Package Options above, this +ability is disabled by default with glossaries-extra but can be enabled using the +docdefs package options. +

    Although this can be problematic, the glossaries-extra package provides a way of +defining and using entries within the document environment without the tricks used +with the docdefs option. There are limitations with this approach, so take care with it. +This function is disabled by default, but can be enabled using the preamble-only +command: +


    \GlsXtrEnableOnTheFly

    +

    +When used, this defines the commands described below. +

    The commands \glsxtr, \glsxtrpl, \Glsxtr and \Glsxtrpl can’t be used after +the glossaries have been displayed (through \printglossary etc). It’s best not to +mix these commands with the standard glossary commands, such as \gls or there +may be unexpected results.
    +

    +


    \glsxtr[gls-options][dfn-options]{label}

    +

    +If an entry with the label ⟨label⟩ has already been defined, this just does \gls +[gls-options]{label}. If ⟨label⟩ hasn’t been defined, this will define the entry using: +

    +
    +\newglossaryentry{label}{name={label}, +
     category=\glsxtrcat, +
     description={\nopostdesc}, +
     dfn-options} +
    +
    +

    The ⟨label⟩ must contain any non-expandable commands, such as formatting +commands or problematic characters. If the term requires any of these, they must be +omitted from the ⟨label⟩ and placed in the name key must be provided in the optional +argument ⟨dfn-options⟩.
    +

    + + + +

    The second optional argument ⟨dfn-options⟩ should be empty if the entry has +already been defined, since it’s too late for them. If it’s not empty, a warning will be +generated with +


    \GlsXtrWarning{dfn-options}{label}

    +

    +

    For example, this warning will be generated on the second instance of \glsxtr +below: + + + +

    +
    +\glsxtr[][plural=geese]{goose} + 
     ... later + 
    \glsxtr[][plural=geese]{goose}
    -

    -

    The value of the alias field can be accessed using -


    \glsxtralias  \glsxtralias{

    +

    If you are considering doing something like: + + + +

    +
    +\newcommand*{\goose}{\glsxtr[][plural=geese]{goose}} + 
    \renewcommand*{\GlsXtrWarning}[2]{} + 
     ... later + 
    \goose\ some more text here +
    +

    then don’t bother. It’s simpler and less problematic to just define the entries in the +preamble with \newglossaryentry and then use \gls in the document. +

    There are plural and case-changing alternatives to \glsxtr: +


    \glsxtrpl[gls-options][dfn-options]{label}

    +

    +This is like \glsxtr but uses \glspl instead of \gls. +


    \Glsxtr[gls-options][dfn-options]{label}

    +

    +This is like \glsxtr but uses \Gls instead of \gls. +


    \Glsxtrpl[gls-options][dfn-options]{label}

    -

    +

    +This is like \glsxtr but uses \Glspl instead of \gls. +

    If you use UTF-8 and don’t want the inconvenient of needing to use an +ASCII-only label, then it’s better to use XƎLATEX or LuaLATEX instead of +LATEX (or pdfLATEX). If you really desperately want to use UTF-8 entry labels +without switching to XƎLATEX or LuaLATEX then there is a starred version of +\GlsXtrEnableOnTheFly that allows you to use UTF-8 characters in ⟨label⟩, but it’s +experimental and may not work in some cases. +

    If you use the starred version of \GlsXtrEnableOnTheFly don’t use any +commands in the ⟨label⟩, even if they expand to just text.
    +

    -

    -

    Top

    11.

    +

    Top

    12. Supplemental Packages

    -

    The

    The glossaries bundle provides additional support packages glossaries-prefix (for + id="dx1-55001"> (for prefixing) and glossaries-accsupp (for accessibility support). These packages aren’t + id="dx1-55002"> (for accessibility support). These packages aren’t automatically loaded.

    -

    Top

    11.1

    Top

    12.1 Prefixes or Determiners

    -

    If prefixing is required, you can simply load

    If prefixing is required, you can simply load glossaries-prefix after after glossaries-extra. For example:

    -
    +
    \documentclass{article}  
    \usepackage{glossaries-extra}  
    \usepackage{glossaries-prefix} @@ -23403,40 +22728,51 @@ example:  
    \printglossaries  
    \end{document}
    -

    -

    +

    +

    -

    Top

    11.2

    Top

    12.2 Accessibility Support

    -

    The

    The glossaries-accsupp package needs to be loaded before package is still experimental and so accessibility features are +liable to change.
    +

    +

    The glossaries-accsupp package needs to be loaded before glossaries-extra or through the accsupp package option: + id="dx1-57003"> package option:

    -
    +
    \usepackage[accsupp]{glossaries-extra}
    -

    If you don’t load

    If you don’t load glossaries-accsupp or you load or you load glossaries-accsupp after after glossaries-extra the new \glsaccessxxx⟩ commands described below will simply be equivalent to the corresponding \glsentryxxx⟩ commands. -

    The following xxx⟩ commands. Other accessibility features, such as the +attributes used by \newabbreviation also won’t work if glossaries-accsupp is loaded +too late. +

    The following \glsaccessxxx⟩ commands add accessibility information wrapped around the corresponding \glsentryxxx⟩ commands. There is no check for existence of the entry nor do any of these commands add formatting, hyperlinks or indexing information. -


    \glsaccessname 


    \glsaccessname{label}

    -

    +

    This displays the value of the name field for the entry identified by ⟨ field for the entry identified by ⟨label⟩. -

    If the

    If the glossaries-accsupp package isn’t loaded, this is simply defined as: + id="dx1-57010"> package isn’t loaded, this is simply defined as:

    -
    +
    \newcommand*{\glsaccessname}[1]{\glsentryname{#1}}
    -

    otherwise it’s defined as: +

    otherwise it’s defined as:

    -
    +
    \newcommand*{\glsaccessname}[1]{%  
      \glsnameaccessdisplay  
      {% @@ -23480,38 +22814,36 @@ class="cmss-10">glossaries-accsupp  {#1}%  
    }
    -

    (

    (\glsnameaccessdisplay is defined by the is defined by the glossaries-accsupp package.) The first + id="dx1-57012"> package.) The first letter upper case version is: -


    \Glsaccessname 


    \Glsaccessname{label}

    -

    +

    Without the glossaries-accsupp package this is just defined as: + id="dx1-57014"> package this is just defined as:

    -
    +
    \newcommand*{\Glsaccessname}[1]{\Glsentryname{#1}}
    -

    With the

    With the glossaries-accsupp package this is defined as: + id="dx1-57015"> package this is defined as:

    -
    +
    \newcommand*{\Glsaccessname}[1]{%  
      \glsnameaccessdisplay  
      {% @@ -23520,299 +22852,251 @@ class="cmss-10">glossaries-accsupp  {#1}%  
    }
    -

    -

    The following commands are all defined in an analogous manner. -


    \glsaccesstext 

    +

    The following commands are all defined in an analogous manner. +


    \glsaccesstext{label}

    -

    +

    This displays the value of the text field. -


    \Glsaccesstext  field. +


    \Glsaccesstext{label}

    -

    +

    This displays the value of the text field with the first letter converted to upper + id="dx1-57019"> field with the first letter converted to upper case. -


    \glsaccessplural 


    \glsaccessplural{label}

    -

    +

    This displays the value of the plural field. -


    \Glsaccessplural  field. +


    \Glsaccessplural{label}

    -

    +

    This displays the value of the plural field with the first letter converted to upper + id="dx1-57023"> field with the first letter converted to upper case. -


    \glsaccessfirst 


    \glsaccessfirst{label}

    -

    +

    This displays the value of the first field. -


    \Glsaccessfirst  field. +


    \Glsaccessfirst{label}

    -

    +

    This displays the value of the first field with the first letter converted to upper + id="dx1-57027"> field with the first letter converted to upper case. -


    \glsaccessfirstplural 


    \glsaccessfirstplural{label}

    -

    +

    This displays the value of the firstplural field. -


    \Glsaccessfirstplural  field. +


    \Glsaccessfirstplural{label}

    -

    +

    This displays the value of the firstplural field with the first letter converted to upper + id="dx1-57031"> field with the first letter converted to upper case. -


    \glsaccesssymbol 


    \glsaccesssymbol{label}

    -

    +

    This displays the value of the symbol field. -


    \Glsaccesssymbol  field. +


    \Glsaccesssymbol{label}

    -

    +

    This displays the value of the symbol field with the first letter converted to upper + id="dx1-57035"> field with the first letter converted to upper case. -


    \glsaccesssymbolplural 


    \glsaccesssymbolplural{label}

    -

    +

    This displays the value of the symbolplural field. -


    \Glsaccesssymbolplural  field. +


    \Glsaccesssymbolplural{label}

    -

    +

    This displays the value of the symbolplural field with the first letter converted to + id="dx1-57039"> field with the first letter converted to upper case. -


    \glsaccessdesc 


    \glsaccessdesc{label}

    -

    +

    This displays the value of the description field. -


    \Glsaccessdesc  field. +


    \Glsaccessdesc{label}

    -

    +

    This displays the value of the description field with the first letter converted to upper + id="dx1-57043"> field with the first letter converted to upper case. -


    \glsaccessdescplural 


    \glsaccessdescplural{label}

    -

    +

    This displays the value of the descriptionplural field. -


    \Glsaccessdescplural  field. +


    \Glsaccessdescplural{label}

    -

    +

    This displays the value of the descriptionplural field with the first letter converted to + id="dx1-57047"> field with the first letter converted to upper case. -


    \glsaccessshort 


    \glsaccessshort{label}

    -

    +

    This displays the value of the short field. -


    \Glsaccessshort  field. +


    \Glsaccessshort{label}

    -

    +

    This displays the value of the short field with the first letter converted to upper + id="dx1-57051"> field with the first letter converted to upper case. -


    \glsaccessshortpl 


    \glsaccessshortpl{label}

    -

    +

    This displays the value of the shortplural field. -


    \Glsaccessshortpl  field. +


    \Glsaccessshortpl{label}

    -

    +

    This displays the value of the shortplural field with the first letter converted to upper + id="dx1-57055"> field with the first letter converted to upper case. -


    \glsaccesslong 


    \glsaccesslong{label}

    -

    +

    This displays the value of the long field. -


    \Glsaccesslong  field. +


    \Glsaccesslong{label}

    -

    +

    This displays the value of the long field with the first letter converted to upper + id="dx1-57059"> field with the first letter converted to upper case. -


    \glsaccesslongpl 


    \glsaccesslongpl{label}

    -

    +

    This displays the value of the longplural field. -


    \Glsaccesslongpl  field. +


    \Glsaccesslongpl{label}

    -

    +

    This displays the value of the longplural field with the first letter converted to upper + id="dx1-57063"> field with the first letter converted to upper case.

    -

    -

    Top

    12.

    +

    Top

    13. Sample Files

    -

    The following sample files are provided with this package: +

    The following sample files are provided with this package:

    sample.tex
    General abbreviations. sample-acronym.tex
    Acronyms aren’t initialisms and don’t expand on first use.
    @@ -23890,7 +23174,7 @@ class="description">Another initialisms example. sample-postlink.tex
    Automatically inserting text after the link-text produced by commands like \gls (outside of hyperlink, if present). @@ -23904,28 +23188,28 @@ class="cmbx-10">sample-autoindex.tex
    Using the dualindex and and indexname attributes to + id="dx1-58004"> attributes to automatically add glossary entries to the index (in addition to the glossary location list).
    sample-autoindex-hyp.tex
    As previous but uses hyperref. + id="dx1-58006">.
    sample-nested.tex
    Using \gls within the value of the within the value of the name key. + id="dx1-58008"> key.
    sample-entrycount.tex
    Enable entry-use counting (only index if used more than n times, see §6.1 §7.1 Entry Counting (First Use Flag)).
    sample-unitentrycount.tex
    Enable use of per-unit entry-use counting (§6.1 +class="cmsy-10">§7.1 Entry Counting (First Use Flag)).
    @@ -23948,7 +23232,7 @@ href="#sec:entrycount">Entry Counting (First Use Flag)) to only have one hyperlink per entry per page.
    @@ -23956,7 +23240,7 @@ href="#sec:entrycount">Entry Counting class="cmbx-10">sample-linkcount.tex
    Using link counting (§6.2 §7.2 Link Counting) to only have one hyperlink per entry.
    @@ -23986,7 +23270,7 @@ class="cmbx-10">sample-external.tex
    Uses the targeturl attribute to allow for entries that + id="dx1-58009"> attribute to allow for entries that should link to an external URL rather than to an internal glossary.
    \glsxtrfmt. class="cmbx-10">sample-alias.tex
    Uses the alias key. (See key. (See §10.4 Entry Aliases.) @@ -24008,29 +23292,29 @@ href="#sec:alias">Entry Aliases.) class="cmbx-10">sample-alttree.tex
    Uses the glossaries-extra-stylemods package with the package with the alttree + id="dx1-58012"> style (see §2.12.3 The §2.10.1 The glossaries-extra-stylemods Package).
    sample-alttree-sym.tex
    Another alttree example that measures the symbol + id="dx1-58013"> example that measures the symbol widths.
    sample-alttree-marginpar.tex
    Another alttree example that puts the + id="dx1-58014"> example that puts the number list in the margin.
    sample-onthefly.tex
    Using on-the-fly commands. Terms with accents must have the name key explicitly set. + id="dx1-58016"> key explicitly set.
    sample-onthefly-xetex.tex
    Using on-the-fly commands with XƎLATEX. Terms with UTF-8 characters don’t need to have the name key explicitly + id="dx1-58017"> key explicitly set. Terms that contain commands must have the name key explicitly set + id="dx1-58018"> key explicitly set with the commands removed from the label.
    Tries to emulate the previous sample file for use with LATEX through the starred version of \GlsXtrEnableOnTheFly. + id="dx1-58019">. This is a bit iffy and may not always work. Terms that contain commands must have the name key explicitly set with the commands removed from + id="dx1-58020"> key explicitly set with the commands removed from the label.
    sample-accsupp.tex
    Integrate glossaries-accsupp. + id="dx1-58021">.
    sample-prefix.tex
    Integrate glossaries-prefix. + id="dx1-58022">.
    sample-suppl-main.tex
    Uses thevalue to reference a location in the + id="dx1-58023"> to reference a location in the supplementary file sample-suppl.tex. @@ -24092,84 +23376,84 @@ class="cmbx-10">sample-suppl-main-hyp.tex
    A more complicated version to the above that uses the hyperref package to reference a location in the supplementary file + id="dx1-58024"> package to reference a location in the supplementary file sample-suppl-hyp.tex.
    -

    -

    Top

    13.

    +

    Top

    14. Multi-Lingual Support

    -

    There’s only one command provided by

    There’s only one command provided by glossaries-extra that you’re likely to want to change in your document and that’s \abbreviationsname ( (§1.2 New or Modified Package Options) if you use the abbreviations package option to + id="dx1-59002"> package option to automatically create the glossary labelled abbreviations. If this command doesn’t already exist, it will be defined to “Abbreviations” if babel hasn’t + id="dx1-59003"> hasn’t been loaded, otherwise it will be defined as \acronymname (provided by glossaries). -

    You can redefine it in the usual way. For example: +

    You can redefine it in the usual way. For example:

    -
    +
    \renewcommand*{\abbreviationsname}{List of Abbreviations}
    -

    Or using

    Or using babel or or polyglossia captions hook: + id="dx1-59005"> captions hook:

    -
    +
    \appto\captionsenglish{%  
     \renewcommand*{\abbreviationsname}{List of Abbreviations}%  
    }
    -

    -

    Alternatively you can use the

    +

    Alternatively you can use the title key when you print the list of abbreviations. + id="dx1-59006"> key when you print the list of abbreviations. For example:

    -
    +
    \printabbreviations[title={List of Abbreviations}]
    -

    or +

    or

    -
    +
    \printglossary[type=abbreviations,title={List of Abbreviations}]
    -

    -

    The other fixed text commands are the diagnostic messages, which shouldn’t +

    +

    The other fixed text commands are the diagnostic messages, which shouldn’t appear in the final draft of your document. -

    The

    The glossaries-extra package has the facility to load language modules (whose filename is in the form glossariesxtr-language.ldf) if they exist, but won’t warn if they don’t. If glossaries-extra-bib2gls is loaded via the is loaded via the record package option then the + id="dx1-59008"> package option then the check for language resource files will additionally search for an associated language script file given by glossariesxtr-Latn, associated with the given dialect. There’s no warning if the associated file isn’t found. The script file is loaded after the dialect file. -

    If you want to write your own language module, you just need to create a file +

    If you want to write your own language module, you just need to create a file called glossariesxtr-lang.ldf, where ⟨lang⟩ identifies the language or dialect (see the tracklang package). For example, package). For example, glossariesxtr-french.ldf. -

    The simplest code for this file is: +

    The simplest code for this file is:

    -
    +
    \ProvidesGlossariesExtraLang{french}[2015/12/09 v1.0]  
    \newcommand*{\glossariesxtrcaptionsfrench}{%  
     \def\abbreviationsname{Abr\'eviations}% @@ -24230,85 +23514,75 @@ class="cmtt-10">glossariesxtr-french.ldf.  
      {}%  
    }
    -

    -

    You can adapt this for other languages by replacing all instances of the language +

    +

    You can adapt this for other languages by replacing all instances of the language identifier french and the translated text Abr\’eviations as appropriate. You can also use the .ldf file to provide rule blocks for a particular language for use with bib2gls’s custom sort rule. See §9.3 The The glossaries-extra-bib2gls package for further details. -

    This

    This .ldf file then needs to be put somewhere on TEX’s path so that it can be found by glossaries-extra. You might also want to consider uploading it to CTAN so that it can be useful to others. (Please don’t send it to me. I already have more packages than I am able to maintain.) -

    If you additionally want to provide translations for the diagnostic messages used +

    If you additionally want to provide translations for the diagnostic messages used when a glossary is missing, you need to redefine the following commands: -


    \GlsXtrNoGlsWarningHead 


    \GlsXtrNoGlsWarningHead{label}{file} -

    -

    +class="cmtt-10">}


    +

    This produces the following text in English:

    -

    This document is incomplete. The external file associated with the - - - +

    This document is incomplete. The external file associated with the glossary ‘⟨label⟩’ (which should be called ⟨file⟩) hasn’t been created.

    -


    \GlsXtrNoGlsWarningEmptyStart 


    \GlsXtrNoGlsWarningEmptyStart

    -

    +

    This produces the following text in English:

    -

    This has probably happened because there are no entries defined in +

    This has probably happened because there are no entries defined in this glossary.

    -


    \GlsXtrNoGlsWarningEmptyMain 


    \GlsXtrNoGlsWarningEmptyMain

    -

    +

    This produces the following text in English:

    -

    If you don’t want this glossary, add

    If you don’t want this glossary, add nomain to your package option list when you load glossaries-extra.sty. For example:

    -


    \GlsXtrNoGlsWarningEmptyNotMain 


    \GlsXtrNoGlsWarningEmptyNotMain{label} -

    -

    +class="cmtt-10">}


    +

    This produces the following text in English:

    -

    Did you forget to use

    Did you forget to use type=label⟩ when you defined your entries? If you tried to load entries into this glossary with ] as the optional argument? If you did, check that the definitions in the file you loaded all had the type set to \glsdefaulttype.

    -


    \GlsXtrNoGlsWarningCheckFile 


    \GlsXtrNoGlsWarningCheckFile{file} -

    -

    +class="cmtt-10">}


    +

    This produces the following text in English:

    -

    Check the contents of the file ⟨

    Check the contents of the file ⟨file⟩. If it’s empty, that means you haven’t indexed any of your entries in this glossary (using commands like \gls or \glsadd) so this list can’t be generated. If the file isn’t empty, the document build process hasn’t been completed.

    -


    \GlsXtrNoGlsWarningMisMatch 


    \GlsXtrNoGlsWarningMisMatch

    -

    +

    This produces the following text in English:

    - - - -

    You need +

    You need to either replace \makenoidxglossaries with \makeglossaries or @@ -24360,17 +23626,18 @@ class="cmtt-10">\printglossaries) class="cmtt-10">\printnoidxglossary (or \printnoidxglossaries) and then rebuild this document.

    -


    \GlsXtrNoGlsWarningNoOut 


    \GlsXtrNoGlsWarningNoOut{file}

    -

    +

    This produces the following text in English:

    -

    The file ⟨

    The file ⟨file⟩ doesn’t exist. This most likely means you haven’t used \makeglossaries or you have used \nofiles. If this is just a draft version of the document, you can suppress this message using the nomissingglstext package option.

    -


    \GlsXtrNoGlsWarningTail 


    \GlsXtrNoGlsWarningTail

    -

    +

    This produces the following text in English:

    -

    This message will be removed once the problem has been fixed.

    -


    \GlsXtrNoGlsWarningBuildInfo 

    This message will be removed once the problem has been fixed.

    +


    \GlsXtrNoGlsWarningBuildInfo

    -

    -This is advice on how to generate the glossary files. See the documented code -(glossaries-extra-code.pdf) for further details. -


    \GlsXtrNoGlsWarningAutoMake 

    +This is advice on how to generate the glossary files. +


    \GlsXtrNoGlsWarningAutoMake{label} -

    -

    +class="cmtt-10">}


    +

    This is the message produced when the automake option is used, but the document -needs a rerun or the shell escape setting doesn’t permit the execution of the external -application. This command also generates a warning in the transcript file. See the -documented code for further details. + id="dx1-59021"> option is used, but the document +needs a rerun or the shell escape setting doesn’t permit the execution of the +external application. This command also generates a warning in the transcript +file. +

    See the documented code (glossaries-extra-code.pdf) for further +details. @@ -24425,21 +23686,21 @@ documented code for further details.

    Top

    Glossary

    + id="x1-6000014">Glossary
    bib2gls
    A command line Java application that selects entries from a .bib file and converts them to glossary definitions (like bibtex but also performs hierarchical sorting and collation, thus omitting the need for xindy or makeindex). Further details at: http://www.dickimaw-books.com/software/bib2gls/. entry location
    The location of the entry in the document. This defaults to the page number on which the entry appears. An entry may have multiple locations. @@ -24457,80 +23718,80 @@ class="description">The location of the entry in the document. This defaults to first use
    The first time a glossary entry is used (from the start of the document or after a reset) with one of the following commands: \gls, , \Gls, , \GLS, + id="dx1-60008">, \glspl, , \Glspl, , \GLSpl or or \glsdisp. + id="dx1-60012">.
    first use flag
    A conditional that determines whether or not the entry has been used according to the rules of first use.
    first use text
    The text that is displayed on first use, which is governed by the + id="dx1-60016">first use, which is governed by the first and and firstplural keys of keys of \newglossaryentry. (May be overridden by + id="dx1-60019">. (May be overridden by \glsdisp.) + id="dx1-60020">.)
    link-text
    The text produced by commands such as \gls. It may or may not + id="dx1-60022">. It may or may not have a hyperlink to the glossary.
    location list
    A list of entry locations. See number list.
    makeglossaries
    A custom designed Perl script interface provided with the glossaries package to run xindy or makeindex according to the document settings. @@ -24540,13 +23801,13 @@ class="cmtt-10">makeindex according to the document makeglossaries-lite
    A custom designed Lua script interface to xindy and makeindex provided with the glossaries package. This is a cut-down alternative to the Perl makeglossaries-lite.exe. makeindex
    An indexing application.
    number list
    A list of entry locations (also called a location list). The number list can be suppressed using the nonumberlist package option. + id="dx1-60036"> package option.
    xindy
    An flexible indexing application with multilingual support written in Perl.

    Index

    + id="x1-6100014">Index

    A

    abbreviation styles (deprecated):
        footnote-em  1
    +href="glossaries-extra-manual.html#dx1-30173" >1
        footnote-sc  2
    +href="glossaries-extra-manual.html#dx1-30165" >2
        footnote-sm  3
    +href="glossaries-extra-manual.html#dx1-30169" >3
        long-desc-em  4
    +href="glossaries-extra-manual.html#dx1-29078" >4
        long-desc-sc  5
    +href="glossaries-extra-manual.html#dx1-29070" >5
        long-desc-sm  6
    +href="glossaries-extra-manual.html#dx1-29074" >6
        long-em  7
    +href="glossaries-extra-manual.html#dx1-29104" >7
        long-sc  8
    +href="glossaries-extra-manual.html#dx1-29096" >8
        long-sm  9
    +href="glossaries-extra-manual.html#dx1-29100" >9
        postfootnote-em  10
    +href="glossaries-extra-manual.html#dx1-30214" >10
        postfootnote-sc  11
    +href="glossaries-extra-manual.html#dx1-30206" >11
        postfootnote-sm  12
    +href="glossaries-extra-manual.html#dx1-30210" >12
    abbreviation styles:
        footnote  13
    +href="glossaries-extra-manual.html#dx1-30160" >13
    +    footnote-desc  14
        long  14
    +href="glossaries-extra-manual.html#dx1-29090" >15
        long-desc  15
    +href="glossaries-extra-manual.html#dx1-29064" >16
        long-em-noshort-em  16, 17, 18
    +href="glossaries-extra-manual.html#dx1-28092" >17, 18, 19
        long-em-noshort-em-desc  19, 20
    +href="glossaries-extra-manual.html#dx1-29079" >20, 21
        long-em-noshort-em-desc-noreg  21
    +href="glossaries-extra-manual.html#dx1-30074" >22
        long-em-noshort-em-noreg  22, 23, 24
    +href="glossaries-extra-manual.html#dx1-28094" >23, 24, 25
        long-em-short-em  25, 26, 27, 28
    +href="glossaries-extra-manual.html#dx1-28060" >26, 27, 28, 29
        long-em-short-em-desc  29
    +href="glossaries-extra-manual.html#dx1-30071" >30
        long-hyphen-long-hyphen  30
    +href="glossaries-extra-manual.html#dx1-30266" >31
        long-hyphen-noshort-desc-noreg  31, 32
    +href="glossaries-extra-manual.html#dx1-30255" >32, 33
        long-hyphen-noshort-noreg  33, 34
    +href="glossaries-extra-manual.html#dx1-28095" >34, 35
        long-hyphen-postshort-hyphen  35, 36, 37, 38, 39, 40
    +href="glossaries-extra-manual.html#dx1-28090" >36, 37, 38, 39, 40, 41
        long-hyphen-postshort-hyphen-desc  41
    +href="glossaries-extra-manual.html#dx1-30268" >42
        long-hyphen-short-hyphen  42, 43, 44, 45, 46
    +href="glossaries-extra-manual.html#dx1-30246" >43, 44, 45, 46, 47
        long-hyphen-short-hyphen-desc  47, 48
    +href="glossaries-extra-manual.html#dx1-30256" >48, 49
        long-noshort  49, 50, 51, 52, 53, 54, 55, 56, 57
    +href="glossaries-extra-manual.html#dx1-14042" >50, 51, 52, 53, 54, 55, 56, 57, 58
        long-noshort-desc  58, 59, 60, 61, 62, 63, 64, 65, 66, 67
    -    long-noshort-desc-noreg  68
    +href="glossaries-extra-manual.html#dx1-13040" >59, 60, 61, 62, 63, 64, 65, 66, 67, 68
    +    long-noshort-desc-noreg  69
        long-noshort-em  69
    +href="glossaries-extra-manual.html#dx1-29101" >70
        long-noshort-em-desc  70
    +href="glossaries-extra-manual.html#dx1-29075" >71
        long-noshort-noreg  71
    +href="glossaries-extra-manual.html#dx1-30048" >72
        long-noshort-sc  72, 73
    +href="glossaries-extra-manual.html#dx1-28085" >73, 74
        long-noshort-sc-desc  74, 75
    +href="glossaries-extra-manual.html#dx1-29066" >75, 76
        long-noshort-sm  76
    +href="glossaries-extra-manual.html#dx1-29097" >77
        long-noshort-sm-desc  77
    +href="glossaries-extra-manual.html#dx1-29071" >78
        long-only-short-only  78, 79, 80
    +href="glossaries-extra-manual.html#dx1-28074" >79, 80, 81
        long-only-short-only-desc  81
    +href="glossaries-extra-manual.html#dx1-30024" >82
        long-postshort-user  82, 83
    +href="glossaries-extra-manual.html#dx1-30239" >83, 84
        long-postshort-user-desc  84
    +href="glossaries-extra-manual.html#dx1-30242" >85
        long-short  85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100
    +href="glossaries-extra-manual.html#dx1-13047" >86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101
        long-short-desc  101, 102, 103, 104, 105, 106, 107, 108, 109
    +href="glossaries-extra-manual.html#dx1-14028" >102, 103, 104, 105, 106, 107, 108, 109, 110
        long-short-em  110, 111, 112, 113
    +href="glossaries-extra-manual.html#dx1-28055" >111, 112, 113, 114
        long-short-em-desc  114, 115
    +href="glossaries-extra-manual.html#dx1-30068" >115, 116
        long-short-sc  116, 117, 118, 119
    +href="glossaries-extra-manual.html#dx1-14016" >117, 118, 119, 120
        long-short-sc-desc  120, 121
    +href="glossaries-extra-manual.html#dx1-14030" >121, 122
        long-short-sm  122, 123, 124
    +href="glossaries-extra-manual.html#dx1-14018" >123, 124, 125
        long-short-sm-desc  125, 126
    +href="glossaries-extra-manual.html#dx1-14032" >126, 127
        long-short-user  127, 128, 129, 130, 131, 132, 133, 134, 135
    +href="glossaries-extra-manual.html#dx1-28088" >128, 129, 130, 131, 132, 133, 134, 135, 136
        long-short-user-desc  136
    +href="glossaries-extra-manual.html#dx1-30077" >137
        nolong-short  137, 138
    +href="glossaries-extra-manual.html#dx1-29010" >138, 139
        nolong-short-em  139
    +href="glossaries-extra-manual.html#dx1-29031" >140
        nolong-short-noreg  140
    +href="glossaries-extra-manual.html#dx1-30089" >141
        nolong-short-sc  141
    +href="glossaries-extra-manual.html#dx1-29017" >142
        nolong-short-sm  142
    +href="glossaries-extra-manual.html#dx1-29024" >143
        postfootnote  143
    +href="glossaries-extra-manual.html#dx1-24006" >144, 145
    +    postfootnote-desc  146
        short  144
    +href="glossaries-extra-manual.html#dx1-29008" >147
        short-desc  145
    +href="glossaries-extra-manual.html#dx1-29040" >148
        short-em  146
    +href="glossaries-extra-manual.html#dx1-29029" >149
        short-em-desc  147
    +href="glossaries-extra-manual.html#dx1-29055" >150
        short-em-footnote  148, 149
    +href="glossaries-extra-manual.html#dx1-28106" >151, 152
        short-em-footnote-desc  150
    +href="glossaries-extra-manual.html#dx1-28105" >153, 154
        short-em-long  151, 152, 153
    +href="glossaries-extra-manual.html#dx1-28056" >155, 156, 157
        short-em-long-desc  154, 155
    +href="glossaries-extra-manual.html#dx1-30133" >158, 159
        short-em-long-em  156, 157
    +href="glossaries-extra-manual.html#dx1-28061" >160, 161
        short-em-long-em-desc  158
    +href="glossaries-extra-manual.html#dx1-30136" >162
        short-em-nolong  159, 160, 161
    +href="glossaries-extra-manual.html#dx1-29026" >163, 164, 165
        short-em-nolong-desc  162, 163
    +href="glossaries-extra-manual.html#dx1-29052" >166, 167
        short-em-postfootnote  164
    +href="glossaries-extra-manual.html#dx1-30211" >168
    +    short-em-postfootnote-desc  169
        short-footnote  165, 166, 167, 168, 169, 170, 171, 172, 173, 174
    +href="glossaries-extra-manual.html#dx1-14046" >170, 171, 172, 173, 174, 175, 176, 177, 178, 179, 180
        short-footnote-desc  175
    +href="glossaries-extra-manual.html#dx1-14052" >181, 182, 183, 184, 185, 186, 187
        short-hyphen-long-hyphen  176, 177
    +href="glossaries-extra-manual.html#dx1-30271" >188, 189
    + + +     short-hyphen-long-hyphen-desc  178
    +href="glossaries-extra-manual.html#dx1-30275" >190
        short-hyphen-postlong-hyphen  179, 180
    +href="glossaries-extra-manual.html#dx1-30278" >191, 192
        short-hyphen-postlong-hyphen-desc  181
    - - - +href="glossaries-extra-manual.html#dx1-30283" >193
        short-long  182, 183, 184, 185, 186, 187, 188, 189, 190, 191, 192
    +href="glossaries-extra-manual.html#dx1-14022" >194, 195, 196, 197, 198, 199, 200, 201, 202, 203, 204
        short-long-desc  193, 194, 195, 196, 197, 198, 199
    +href="glossaries-extra-manual.html#dx1-14036" >205, 206, 207, 208, 209, 210, 211
        short-long-user  200, 201, 202, 203, 204, 205, 206
    +href="glossaries-extra-manual.html#dx1-30038" >212, 213, 214, 215, 216, 217, 218
        short-long-user-desc  207
    +href="glossaries-extra-manual.html#dx1-30139" >219
        short-nolong  208, 209, 210, 211, 212, 213, 214, 215, 216, 217, 218, 219, 220, 221
    +href="glossaries-extra-manual.html#dx1-24021" >220, 221, 222, 223, 224, 225, 226, 227, 228, 229, 230, 231, 232, 233
        short-nolong-desc  222, 223, 224, 225, 226
    +href="glossaries-extra-manual.html#dx1-29033" >234, 235, 236, 237, 238
        short-nolong-desc-noreg  227
    +href="glossaries-extra-manual.html#dx1-30118" >239
        short-nolong-noreg  228
    +href="glossaries-extra-manual.html#dx1-30086" >240
        short-postfootnote  229, 230, 231, 232, 233, 234, 235
    +href="glossaries-extra-manual.html#dx1-9062" >241, 242, 243, 244, 245, 246, 247, 248
    +    short-postfootnote-desc  249, 250, 251, 252, 253
        short-postlong-user  236, 237, 238
    +href="glossaries-extra-manual.html#dx1-30232" >254, 255, 256
        short-postlong-user-desc  239
    +href="glossaries-extra-manual.html#dx1-30235" >257
        short-sc  240
    +href="glossaries-extra-manual.html#dx1-29015" >258
        short-sc-desc  241
    +href="glossaries-extra-manual.html#dx1-29045" >259
        short-sc-footnote  242, 243, 244
    +href="glossaries-extra-manual.html#dx1-14048" >260, 261, 262
        short-sc-footnote-desc  245
    +href="glossaries-extra-manual.html#dx1-14054" >263, 264
        short-sc-long  246, 247, 248, 249
    +href="glossaries-extra-manual.html#dx1-14024" >265, 266, 267, 268
        short-sc-long-desc  250, 251
    +href="glossaries-extra-manual.html#dx1-14038" >269, 270
        short-sc-nolong  252, 253, 254
    +href="glossaries-extra-manual.html#dx1-29012" >271, 272, 273
        short-sc-nolong-desc  255, 256
    +href="glossaries-extra-manual.html#dx1-29042" >274, 275
        short-sc-postfootnote  257, 258
    +href="glossaries-extra-manual.html#dx1-28099" >276, 277
    +    short-sc-postfootnote-desc  278
        short-sm  259
    +href="glossaries-extra-manual.html#dx1-29022" >279
        short-sm-desc  260
    +href="glossaries-extra-manual.html#dx1-29050" >280
        short-sm-footnote  261
    +href="glossaries-extra-manual.html#dx1-14050" >281
        short-sm-footnote-desc  262
    +href="glossaries-extra-manual.html#dx1-14056" >282, 283
        short-sm-long  263, 264, 265
    +href="glossaries-extra-manual.html#dx1-14026" >284, 285, 286
        short-sm-long-desc  266, 267
    +href="glossaries-extra-manual.html#dx1-14040" >287, 288
        short-sm-nolong  268, 269, 270
    +href="glossaries-extra-manual.html#dx1-29019" >289, 290, 291
        short-sm-nolong-desc  271, 272
    +href="glossaries-extra-manual.html#dx1-29047" >292, 293
        short-sm-postfootnote  273
    +href="glossaries-extra-manual.html#dx1-30207" >294
    +    short-sm-postfootnote-desc  295
    \abbreviationsname  274
    +href="glossaries-extra-manual.html#dx1-4199" >296
    \abbrvpluralsuffix  275
    +href="glossaries-extra-manual.html#dx1-31043" >297
    acronym styles (glossaries):
        dua  276
    +href="glossaries-extra-manual.html#dx1-14041" >298
        dua-desc  277
    +href="glossaries-extra-manual.html#dx1-14043" >299
        footnote  278
    +href="glossaries-extra-manual.html#dx1-14045" >300
        footnote-desc  279
    +href="glossaries-extra-manual.html#dx1-14051" >301
        footnote-sc  280
    +href="glossaries-extra-manual.html#dx1-14047" >302
        footnote-sc-desc  281
    +href="glossaries-extra-manual.html#dx1-14053" >303
        footnote-sm  282
    +href="glossaries-extra-manual.html#dx1-14049" >304
        footnote-sm-desc  283
    +href="glossaries-extra-manual.html#dx1-14055" >305
    + + +     long-sc-short  284
    +href="glossaries-extra-manual.html#dx1-14015" >306
        long-sc-short-desc  285
    +href="glossaries-extra-manual.html#dx1-14029" >307
        long-short-desc  286
    +href="glossaries-extra-manual.html#dx1-14027" >308
        long-sm-short  287
    +href="glossaries-extra-manual.html#dx1-14017" >309
        long-sm-short-desc  288
    +href="glossaries-extra-manual.html#dx1-14031" >310
        long-sp-short  289, 290
    - - - +href="glossaries-extra-manual.html#dx1-14019" >311, 312
        long-sp-short-desc  291
    +href="glossaries-extra-manual.html#dx1-14033" >313
        sc-short-long  292
    +href="glossaries-extra-manual.html#dx1-14023" >314
        sc-short-long-desc  293
    +href="glossaries-extra-manual.html#dx1-14037" >315
        short-long  294
    +href="glossaries-extra-manual.html#dx1-14021" >316
        short-long-desc  295
    +href="glossaries-extra-manual.html#dx1-14035" >317
        sm-short-long  296
    +href="glossaries-extra-manual.html#dx1-14025" >318
        sm-short-long-desc  297
    +href="glossaries-extra-manual.html#dx1-14039" >319
    amsgen package  298
    +href="glossaries-extra-manual.html#dx1-10" >320
    amsmath package  299
    +href="glossaries-extra-manual.html#dx1-4135" >321
    \apptoglossarypreamble  300
    +href="glossaries-extra-manual.html#dx1-49010" >322

    B babel package  301, 302, 303, 304, 305, 306, 307, 308, 309
    +href="glossaries-extra-manual.html#dx1-3010" >323, 324, 325, 326, 327, 328, 329, 330, 331
    bib2gls  310, 311, 312, 313, 314, 315, 316, 317, 318, 319, 320, 321, 322, 323, 324, 325, 326, 327, 328, 329, 330, 331, 332, 333, 334, 335, 336, 337, 338, 339, 340, 341, 342, 343, 344, 345, 346, 347, 348, 349, 350, 351, 352, 353, 354, 355, 356, 357, 358, 359, 360, 361, 362, 363, 364, 365, 366, 367, 368, 369, 370, 371, 372, 373, 374, 375, 376, 377, 378, 379, 380, 381, 382, 383, 384, 332, 333, 334, 335, 336, 337, 338, 339, 340, 341, 342, 343, 344, 345, 346, 347, 348, 349, 350, 351, 352, 353, 354, 355, 356, 357, 358, 359, 360, 361, 362, 363, 364, 365, 366, 367, 368, 369, 370, 371, 372, 373, 374, 375, 376, 377, 378, 379, 380, 381, 382, 383, 384, 385, 386, 387, 388, 389, 390, 391, 392, 393, 394, 395, 396, 397, 398, 399, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418, 419
    +href="glossaries-extra-manual.html#dx1-41003" >386, 387, 388, 389, 390, 391, 392, 393, 394, 395, 396, 397, 398, 399, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418, 419, 420, 421, 422, 423, 424, 425, 426, 427, 428, 429, 430, 431, 432, 433, 434, 435, 436, 437, 438, 439, 440, 441, 442, 443, 444

    C categories:
        abbreviation  420, 421, 422, 423, 424
    +href="glossaries-extra-manual.html#dx1-10004" >445, 446, 447, 448, 449
        acronym  425, 426, 427, 428, 429
    +href="glossaries-extra-manual.html#dx1-17035" >450, 451, 452, 453, 454
        general  430, 431, 432, 433, 434, 435, 436, 437
    +href="glossaries-extra-manual.html#dx1-9037" >455, 456, 457, 458, 459, 460, 461, 462
    +    glossnamefont  463
        index  438, 439
    +href="glossaries-extra-manual.html#dx1-6030" >464, 465
        number  440
    +href="glossaries-extra-manual.html#dx1-35018" >466
        symbol  441, 442
    +href="glossaries-extra-manual.html#dx1-9045" >467, 468
    category attributes:
        accessaposplural  443, 444, 445
    +href="glossaries-extra-manual.html#dx1-35138" >469, 470, 471, 472
        accessinsertdots  446
    +href="glossaries-extra-manual.html#dx1-35137" >473, 474
        accessnoshortplural  447
    +href="glossaries-extra-manual.html#dx1-35139" >475, 476
        aposplural  448, 449, 450, 451, 452, 453, 454, 455
    +href="glossaries-extra-manual.html#dx1-12036" >477, 478, 479, 480, 481, 482, 483, 484
        discardperiod  456, 457, 458, 459, 460
    +href="glossaries-extra-manual.html#dx1-9032" >485, 486, 487, 488, 489
        dualindex  461, 462, 463, 464, 465, 466, 467
    +href="glossaries-extra-manual.html#dx1-35118" >490, 491, 492, 493, 494, 495, 496
        entrycount  468, 469, 470, 471, 472, 473, 474, 475, 476, 477, 478
    +href="glossaries-extra-manual.html#dx1-10003" >497, 498, 499, 500, 501, 502, 503, 504, 505, 506, 507
        externallocation  479, 480, 481, 482
    +href="glossaries-extra-manual.html#dx1-7061" >508, 509, 510, 511
        firstshortaccess  483
    +href="glossaries-extra-manual.html#dx1-35169" >512
        glossdesc  484, 485, 486
    +href="glossaries-extra-manual.html#dx1-17005" >513, 514, 515
        glossdescfont  487, 488
    +href="glossaries-extra-manual.html#dx1-17006" >516, 517, 518
        glossname  489, 490, 491
    +href="glossaries-extra-manual.html#dx1-17003" >519, 520, 521
    + + +     glossnamefont  492, 493, 494
    +href="glossaries-extra-manual.html#dx1-17022" >522, 523, 524, 525
    +    glosssymbolfont  526, 527
        headuc  495, 496, 497, 498
    +href="glossaries-extra-manual.html#dx1-13059" >528, 529, 530, 531
        hyperoutside  499, 500
    +href="glossaries-extra-manual.html#dx1-7019" >532, 533
        indexname  501, 502, 503, 504, 505
    +href="glossaries-extra-manual.html#dx1-17027" >534, 535, 536, 537, 538
        indexonlyfirst  506, 507, 508
    +href="glossaries-extra-manual.html#dx1-7007" >539, 540, 541
        insertdots  509, 510, 511, 512
    +href="glossaries-extra-manual.html#dx1-24013" >542, 543, 544, 545
        linkcount  513, 514, 515
    - - - +href="glossaries-extra-manual.html#dx1-35090" >546, 547, 548
        linkcountmaster  516, 517
    +href="glossaries-extra-manual.html#dx1-35092" >549, 550
        markshortwords  518, 519
    +href="glossaries-extra-manual.html#dx1-35061" >551, 552
        markwords  520, 521, 522, 523, 524, 525
    +href="glossaries-extra-manual.html#dx1-30247" >553, 554, 555, 556, 557, 558
        nameshortaccess  526
    +href="glossaries-extra-manual.html#dx1-35163" >559
        nohyper  527, 528, 529
    +href="glossaries-extra-manual.html#dx1-35034" >560, 561, 562
        nohyperfirst  530, 531, 532, 533, 534
    +href="glossaries-extra-manual.html#dx1-30148" >563, 564, 565, 566, 567
        noshortplural  535, 536, 537, 538, 539, 540
    +href="glossaries-extra-manual.html#dx1-12037" >568, 569, 570, 571, 572, 573
        pluraldiscardperiod  541, 542
    +href="glossaries-extra-manual.html#dx1-35048" >574, 575
        recordcount  543, 544, 545, 546
    +href="glossaries-extra-manual.html#dx1-48015" >576, 577, 578, 579
        regular  547, 548, 549, 550, 551, 552, 553, 554, 555, 556, 557, 558, 559, 560, 561, 562, 563, 564, 565, 566, 567, 568, 569, 570, 571, 572, 573, 574, 575, 576, 577, 578
    +href="glossaries-extra-manual.html#dx1-9010" >580, 581, 582, 583, 584, 585, 586, 587, 588, 589, 590, 591, 592, 593, 594, 595, 596, 597, 598, 599, 600, 601, 602, 603, 604, 605, 606, 607, 608, 609, 610, 611
        retainfirstuseperiod  579
    +href="glossaries-extra-manual.html#dx1-35050" >612
        tagging  580, 581, 582, 583
    +href="glossaries-extra-manual.html#dx1-25002" >613, 614, 615, 616
        targetcategory  584
    +href="glossaries-extra-manual.html#dx1-35127" >617
        targetname  585, 586
    +href="glossaries-extra-manual.html#dx1-35124" >618, 619
        targeturl  587, 588, 589, 590, 591
    +href="glossaries-extra-manual.html#dx1-15002" >620, 621, 622, 623, 624
        textformat  592, 593, 594, 595, 596
    +href="glossaries-extra-manual.html#dx1-7020" >625, 626, 627, 628, 629
        textshortaccess  597
    +href="glossaries-extra-manual.html#dx1-35166" >630
        unitcount  598
    +href="glossaries-extra-manual.html#dx1-37034" >631
        wrgloss  599, 600
    +href="glossaries-extra-manual.html#dx1-7015" >632, 633
    \cGLS  601
    +href="glossaries-extra-manual.html#dx1-37015" >634
    \cGLSformat  602
    +href="glossaries-extra-manual.html#dx1-37017" >635
    \cGLSpl  603
    +href="glossaries-extra-manual.html#dx1-37016" >636
    \cGLSplformat  604
    +href="glossaries-extra-manual.html#dx1-37018" >637
    convertgls2bib  605
    +href="glossaries-extra-manual.html#dx1-40003" >638
    \csGlsXtrLetField  606
    +href="glossaries-extra-manual.html#dx1-50028" >639
    \CustomAbbreviationFields  607
    +href="glossaries-extra-manual.html#dx1-31006" >640

    D datatool package  641
    +datatool-base package  608
    +href="glossaries-extra-manual.html#dx1-9" >642, 643, 644, 645
    \dGLS  609
    +href="glossaries-extra-manual.html#dx1-47022" >646
    \dGls  610
    +href="glossaries-extra-manual.html#dx1-47020" >647
    \dgls  611
    +href="glossaries-extra-manual.html#dx1-47018" >648
    \dglsdisp  612
    +href="glossaries-extra-manual.html#dx1-47025" >649
    \dglslink  613
    +href="glossaries-extra-manual.html#dx1-47024" >650
    \dGLSpl  614
    +href="glossaries-extra-manual.html#dx1-47023" >651
    + + + \dGlspl  615
    +href="glossaries-extra-manual.html#dx1-47021" >652
    \dglspl  616
    +href="glossaries-extra-manual.html#dx1-47019" >653

    E \eglssetwidest  617
    +href="glossaries-extra-manual.html#dx1-19070" >654
    \eglsupdatewidest  618
    +href="glossaries-extra-manual.html#dx1-19074" >655
    \eGlsXtrSetField  619
    +href="glossaries-extra-manual.html#dx1-50025" >656
    entry location  620, 621, 622
    - - - +href="glossaries-extra-manual.html#dx1-60004" >657, 658, 659
    entrycounter package  623
    +href="glossaries-extra-manual.html#dx1-52020" >660
    equation (counter)  624, 625, 626, 627, 628
    +href="glossaries-extra-manual.html#dx1-4112" >661, 662, 663, 664, 665
    etoolbox package  629, 630, 631, 632, 633, 634, 635, 636, 637
    +href="glossaries-extra-manual.html#dx1-5" >666, 667, 668, 669, 670, 671, 672, 673, 674, 675, 676

    F fancyhdr package  638
    +href="glossaries-extra-manual.html#dx1-21049" >677
    +file types
    +    glg-abr  678
    +    glo-abr  679
    +    gls-abr  680
    first use  639, 640, 641, 642, 643, 644, 645, 646, 647, 648, 649, 650, 651, 652, 653, 654, 655, 656, 657, 658, 659, 660, 661, 662, 663, 664, 665, 666, 667, 668, 669, 670, 671, 672, 673, 674, 675, 676, 677, 678, 679, 680, 681, 682, 683, 684, 685, 686, 687, 688, 689, 690, 691
    +href="glossaries-extra-manual.html#dx1-7005" >681, 682, 683, 684, 685, 686, 687, 688, 689, 690, 691, 692, 693, 694, 695, 696, 697, 698, 699, 700, 701, 702, 703, 704, 705, 706, 707, 708, 709, 710, 711, 712, 713, 714, 715, 716, 717, 718, 719, 720, 721, 722, 723, 724, 725, 726, 727, 728, 729, 730, 731, 732, 733, 734
    first use flag  692, 693, 694, 695, 696, 697, 698
    +href="glossaries-extra-manual.html#dx1-9052" >735, 736, 737, 738, 739, 740, 741
    first use text  699, 700
    +href="glossaries-extra-manual.html#dx1-60015" >742, 743
    fontenc package  701
    +href="glossaries-extra-manual.html#dx1-28024" >744
    +\forallabbreviationlists  745

    G \gglssetwidest  702
    +href="glossaries-extra-manual.html#dx1-19068" >746
    \gglsupdatewidest  703
    +href="glossaries-extra-manual.html#dx1-19073" >747
    \gGlsXtrSetField  704
    +href="glossaries-extra-manual.html#dx1-50024" >748
    glossaries package  705, 706, 707, 708, 709, 710, 711, 712, 713, 714, 715, 716, 717, 718, 719, 720, 721, 722, 723, 724
    +href="glossaries-extra-manual.html#dx1-6018" >749, 750, 751, 752, 753, 754, 755, 756, 757, 758, 759, 760, 761, 762, 763, 764, 765, 766, 767
    glossaries-accsupp package  725, 726, 727, 728, 729, 730, 731, 732, 733, 734, 735, 736, 737, 738, 739, 740, 741
    +href="glossaries-extra-manual.html#dx1-4036" >768, 769, 770, 771, 772, 773, 774, 775, 776, 777, 778, 779, 780, 781, 782, 783, 784, 785, 786, 787, 788, 789
    glossaries-extra package  742, 743, 744, 745, 746, 747
    +href="glossaries-extra-manual.html#dx1-6020" >790, 791, 792, 793, 794, 795, 796
    glossaries-extra-bib2gls package  748, 749, 750, 751, 752, 753, 754, 755, 756, 757, 758, 759, 760, 761
    +href="glossaries-extra-manual.html#dx1-4080" >797, 798, 799, 800, 801, 802, 803, 804, 805, 806, 807, 808, 809, 810, 811
    glossaries-extra-stylemods package  762, 763, 764, 765, 766, 767, 768, 769, 770
    +href="glossaries-extra-manual.html#dx1-4026" >812, 813, 814, 815, 816, 817, 818, 819, 820
    glossaries-prefix package  771, 772, 773
    +href="glossaries-extra-manual.html#dx1-4034" >821, 822, 823, 824
    \glossariesextrasetup  774
    +href="glossaries-extra-manual.html#dx1-4255" >825
    glossary styles:
        altlist  775, 776
    +href="glossaries-extra-manual.html#dx1-19023" >826, 827
        alttree  777, 778, 779, 780, 781, 782, 783, 784, 785, 786, 787, 788, 789
    +href="glossaries-extra-manual.html#dx1-19057" >828, 829, 830, 831, 832, 833, 834, 835, 836, 837, 838, 839, 840
        bookindex  790, 791, 792, 793
    +href="glossaries-extra-manual.html#dx1-21002" >841, 842, 843, 844
        index  794
    +href="glossaries-extra-manual.html#dx1-19045" >845
        inline  795, 796
    +href="glossaries-extra-manual.html#dx1-19006" >846, 847
    + + +     list  797, 798, 799
    +href="glossaries-extra-manual.html#dx1-19018" >848, 849, 850
        listdotted  800, 801
    +href="glossaries-extra-manual.html#dx1-19024" >851, 852
        long  802
    +href="glossaries-extra-manual.html#dx1-19012" >853
        long-desc-name  803
    +href="glossaries-extra-manual.html#dx1-22066" >854
        long-desc-sym-name  804
    +href="glossaries-extra-manual.html#dx1-22133" >855
        long-loc-desc-name  805
    +href="glossaries-extra-manual.html#dx1-22075" >856
        long-loc-desc-sym-name  806
    +href="glossaries-extra-manual.html#dx1-22141" >857
        long-loc-sym-desc-name  807
    +href="glossaries-extra-manual.html#dx1-22125" >858
        long-name-desc  808, 809, 810
    +href="glossaries-extra-manual.html#dx1-22044" >859, 860, 861
        long-name-desc-loc  811
    +href="glossaries-extra-manual.html#dx1-22057" >862
        long-name-desc-sym  812, 813
    +href="glossaries-extra-manual.html#dx1-22083" >863, 864
        long-name-desc-sym-loc  814, 815
    +href="glossaries-extra-manual.html#dx1-22091" >865, 866
        long-name-sym-desc  816
    +href="glossaries-extra-manual.html#dx1-22099" >867
        long-name-sym-desc-loc  817
    +href="glossaries-extra-manual.html#dx1-22108" >868
        long-sym-desc-name  818
    - - - +href="glossaries-extra-manual.html#dx1-22117" >869
        long3col  819
    +href="glossaries-extra-manual.html#dx1-19004" >870
        longragged-booktabs  820, 821
    +href="glossaries-extra-manual.html#dx1-22045" >871, 872
        mcolindexgroup  822
    +href="glossaries-extra-manual.html#dx1-21003" >873
        topic  823, 824
    +href="glossaries-extra-manual.html#dx1-23006" >874, 875
        topicmcols  825
    +href="glossaries-extra-manual.html#dx1-23009" >876
        tree  826, 827, 828, 829
    +href="glossaries-extra-manual.html#dx1-19046" >877, 878, 879, 880
        treenoname  830, 831, 832
    +href="glossaries-extra-manual.html#dx1-19051" >881, 882, 883
    glossary-bookindex package  833, 834
    +href="glossaries-extra-manual.html#dx1-21001" >884, 885
    glossary-inline package  835
    +href="glossaries-extra-manual.html#dx1-19007" >886
    glossary-long package  836, 837
    +href="glossaries-extra-manual.html#dx1-22018" >887, 888
    glossary-longextra package  838, 839
    +href="glossaries-extra-manual.html#dx1-22001" >889, 890
    glossary-topic package  840
    +href="glossaries-extra-manual.html#dx1-23001" >891
    glossary-tree package  841, 842, 843, 844, 845, 846
    +href="glossaries-extra-manual.html#dx1-19034" >892, 893, 894, 895, 896, 897
    \glossentrynameother  847
    +href="glossaries-extra-manual.html#dx1-17020" >898
    \glossxtrsetpopts  848
    +href="glossaries-extra-manual.html#dx1-13058" >899
    \glsabbrvdefaultfont  849, 850
    +href="glossaries-extra-manual.html#dx1-28033" >900, 901
    \glsabbrvemfont  851
    +href="glossaries-extra-manual.html#dx1-28057" >902
    \glsabbrvfont  852
    +href="glossaries-extra-manual.html#dx1-31047" >903
    \glsabbrvhyphenfont  853
    +href="glossaries-extra-manual.html#dx1-28069" >904
    \glsabbrvonlyfont  854
    +href="glossaries-extra-manual.html#dx1-28075" >905
    \glsabbrvscfont  855
    +href="glossaries-extra-manual.html#dx1-28041" >906
    \glsabbrvsmfont  856
    +href="glossaries-extra-manual.html#dx1-28051" >907
    \glsabbrvuserfont  857, 858
    +href="glossaries-extra-manual.html#dx1-28064" >908, 909
    \Glsaccessdesc  859
    +href="glossaries-extra-manual.html#dx1-57042" >910
    \glsaccessdesc  860
    +href="glossaries-extra-manual.html#dx1-57040" >911
    \Glsaccessdescplural  861
    +href="glossaries-extra-manual.html#dx1-57046" >912
    \glsaccessdescplural  862
    +href="glossaries-extra-manual.html#dx1-57044" >913
    \Glsaccessfirst  863
    +href="glossaries-extra-manual.html#dx1-57026" >914
    \glsaccessfirst  864
    +href="glossaries-extra-manual.html#dx1-57024" >915
    \Glsaccessfirstplural  865
    +href="glossaries-extra-manual.html#dx1-57030" >916
    \glsaccessfirstplural  866
    +href="glossaries-extra-manual.html#dx1-57028" >917
    + + + \Glsaccesslong  867
    +href="glossaries-extra-manual.html#dx1-57058" >918
    \glsaccesslong  868
    +href="glossaries-extra-manual.html#dx1-57056" >919
    \Glsaccesslongpl  869
    +href="glossaries-extra-manual.html#dx1-57062" >920
    \glsaccesslongpl  870
    +href="glossaries-extra-manual.html#dx1-57060" >921
    \Glsaccessname  871
    +href="glossaries-extra-manual.html#dx1-57013" >922
    \glsaccessname  872
    +href="glossaries-extra-manual.html#dx1-57008" >923
    \Glsaccessplural  873
    +href="glossaries-extra-manual.html#dx1-57022" >924
    \glsaccessplural  874
    +href="glossaries-extra-manual.html#dx1-57020" >925
    \Glsaccessshort  875
    +href="glossaries-extra-manual.html#dx1-57050" >926
    \glsaccessshort  876
    +href="glossaries-extra-manual.html#dx1-57048" >927
    \Glsaccessshortpl  877
    +href="glossaries-extra-manual.html#dx1-57054" >928
    \glsaccessshortpl  878
    +href="glossaries-extra-manual.html#dx1-57052" >929
    \Glsaccesssymbol  879
    +href="glossaries-extra-manual.html#dx1-57034" >930
    \glsaccesssymbol  880
    +href="glossaries-extra-manual.html#dx1-57032" >931
    \Glsaccesssymbolplural  881
    - - - +href="glossaries-extra-manual.html#dx1-57038" >932
    \glsaccesssymbolplural  882
    +href="glossaries-extra-manual.html#dx1-57036" >933
    \Glsaccesstext  883
    +href="glossaries-extra-manual.html#dx1-57018" >934
    \glsaccesstext  884
    +href="glossaries-extra-manual.html#dx1-57016" >935
    \glsacspace  885
    +href="glossaries-extra-manual.html#dx1-14064" >936
    \glsacspacemax  886
    +href="glossaries-extra-manual.html#dx1-14066" >937
    \glsadd options
        format  887
    +href="glossaries-extra-manual.html#dx1-7035" >938
        theHvalue  888, 889
    +href="glossaries-extra-manual.html#dx1-7047" >939, 940
        thevalue  890, 891, 892, 893, 894
    +href="glossaries-extra-manual.html#dx1-7046" >941, 942, 943, 944, 945
    \glsaddeach  895
    +href="glossaries-extra-manual.html#dx1-7001" >946
    \glsaddpostsetkeys  896
    +href="glossaries-extra-manual.html#dx1-7042" >947
    \glsaddpresetkeys  897
    +href="glossaries-extra-manual.html#dx1-7041" >948
    \glscapturedgroup  898
    +href="glossaries-extra-manual.html#dx1-46002" >949
    \glscategory  899
    +href="glossaries-extra-manual.html#dx1-35019" >950
    \glscategorylabel  900
    +href="glossaries-extra-manual.html#dx1-31039" >951
    \glscurrententrylabel  901
    +href="glossaries-extra-manual.html#dx1-17037" >952
    \glscurrentfieldvalue  902
    +href="glossaries-extra-manual.html#dx1-50032" >953
    +\glsdefaultshortaccess  954
    \glsdefpostdesc  903
    +href="glossaries-extra-manual.html#dx1-17036" >955
    \glsdefpostlink  904
    +href="glossaries-extra-manual.html#dx1-9038" >956
    \glsdefpostname  905
    +href="glossaries-extra-manual.html#dx1-17030" >957
    \glsentrycurrcount  906
    +href="glossaries-extra-manual.html#dx1-37035" >958
    +\glsentrypdfsymbol  959
    \glsentryprevcount  907
    +href="glossaries-extra-manual.html#dx1-37036" >960
    \glsentryprevmaxcount  908
    +href="glossaries-extra-manual.html#dx1-37038" >961
    \glsentryprevtotalcount  909
    +href="glossaries-extra-manual.html#dx1-37037" >962
    \glsextrapostnamehook  910
    +href="glossaries-extra-manual.html#dx1-17031" >963
    \glsFindWidestAnyName  911
    +href="glossaries-extra-manual.html#dx1-19086" >964
    \glsFindWidestAnyNameLocation  912
    +href="glossaries-extra-manual.html#dx1-19098" >965
    \glsFindWidestAnyNameSymbol  913
    +href="glossaries-extra-manual.html#dx1-19090" >966
    \glsFindWidestAnyNameSymbolLocation  914
    +href="glossaries-extra-manual.html#dx1-19095" >967
    + + + \glsFindWidestLevelTwo  915
    +href="glossaries-extra-manual.html#dx1-19088" >968
    \glsFindWidestTopLevelName  916
    +href="glossaries-extra-manual.html#dx1-19081" >969
    \glsFindWidestUsedAnyName  917
    +href="glossaries-extra-manual.html#dx1-19084" >970
    \glsFindWidestUsedAnyNameLocation  918
    +href="glossaries-extra-manual.html#dx1-19096" >971
    \glsFindWidestUsedAnyNameSymbol  919
    +href="glossaries-extra-manual.html#dx1-19089" >972
    \glsFindWidestUsedAnyNameSymbolLocation  920
    +href="glossaries-extra-manual.html#dx1-19091" >973
    \glsFindWidestUsedLevelTwo  921
    +href="glossaries-extra-manual.html#dx1-19087" >974
    \glsFindWidestUsedTopLevelName  922
    +href="glossaries-extra-manual.html#dx1-19082" >975
    \glsfirstabbrvdefaultfont  923
    +href="glossaries-extra-manual.html#dx1-28034" >976
    \glsfirstabbrvemfont  924
    +href="glossaries-extra-manual.html#dx1-28058" >977
    \glsfirstabbrvfont  925
    +href="glossaries-extra-manual.html#dx1-31045" >978
    \glsfirstabbrvhyphenfont  926
    +href="glossaries-extra-manual.html#dx1-28070" >979
    \glsfirstabbrvonlyfont  927
    +href="glossaries-extra-manual.html#dx1-28076" >980
    \glsfirstabbrvsmfont  928
    +href="glossaries-extra-manual.html#dx1-28053" >981
    \glsfirstabbrvuserfont  929
    +href="glossaries-extra-manual.html#dx1-28065" >982
    \glsfirstlongdefaultfont  930
    +href="glossaries-extra-manual.html#dx1-28036" >983
    \glsfirstlongemfont  931
    - - - +href="glossaries-extra-manual.html#dx1-28062" >984
    \glsfirstlongfont  932
    +href="glossaries-extra-manual.html#dx1-31049" >985
    \glsfirstlongfootnotefont  933
    +href="glossaries-extra-manual.html#dx1-30155" >986
    \glsfirstlonghyphenfont  934
    +href="glossaries-extra-manual.html#dx1-28072" >987
    \glsfirstlongonlyfont  935
    +href="glossaries-extra-manual.html#dx1-28078" >988
    \glsfirstlonguserfont  936
    +href="glossaries-extra-manual.html#dx1-28067" >989
    +\GLSfmtfirst  990
    \Glsfmtfirst  937
    +href="glossaries-extra-manual.html#dx1-34043" >991
    \glsfmtfirst  938
    +href="glossaries-extra-manual.html#dx1-34042" >992
    +\GLSfmtfirstpl  993
    \Glsfmtfirstpl  939
    +href="glossaries-extra-manual.html#dx1-34046" >994
    \glsfmtfirstpl  940
    +href="glossaries-extra-manual.html#dx1-34045" >995
    +\GLSfmtfull  996
    \Glsfmtfull  941
    +href="glossaries-extra-manual.html#dx1-34026" >997
    \glsfmtfull  942
    +href="glossaries-extra-manual.html#dx1-34024" >998
    +\GLSfmtfullpl  999
    \Glsfmtfullpl  943
    +href="glossaries-extra-manual.html#dx1-34027" >1000
    \glsfmtfullpl  944
    +href="glossaries-extra-manual.html#dx1-34025" >1001
    +\GLSfmtlong  1002
    \Glsfmtlong  945
    +href="glossaries-extra-manual.html#dx1-34018" >1003
    \glsfmtlong  946
    +href="glossaries-extra-manual.html#dx1-34016" >1004
    +\GLSfmtlongpl  1005
    \Glsfmtlongpl  947
    +href="glossaries-extra-manual.html#dx1-34019" >1006
    \glsfmtlongpl  948
    +href="glossaries-extra-manual.html#dx1-34017" >1007
    +\GLSfmtname  1008
    \Glsfmtname  949
    +href="glossaries-extra-manual.html#dx1-34039" >1009
    \glsfmtname  950
    +href="glossaries-extra-manual.html#dx1-34038" >1010
    +\GLSfmtplural  1011
    \Glsfmtplural  951
    +href="glossaries-extra-manual.html#dx1-34035" >1012
    \glsfmtplural  952
    +href="glossaries-extra-manual.html#dx1-34034" >1013
    + + + +\GLSfmtshort  1014
    \Glsfmtshort  953
    +href="glossaries-extra-manual.html#dx1-34012" >1015
    \glsfmtshort  954
    +href="glossaries-extra-manual.html#dx1-34010" >1016
    \Glsfmtshortpl  955
    +href="glossaries-extra-manual.html#dx1-34013" >1017, 1018
    \glsfmtshortpl  956
    +href="glossaries-extra-manual.html#dx1-34011" >1019
    +\GLSfmttext  1020
    \Glsfmttext  957
    +href="glossaries-extra-manual.html#dx1-34032" >1021
    \glsfmttext  958
    +href="glossaries-extra-manual.html#dx1-34031" >1022
    \glsforeachwithattribute  959
    +href="glossaries-extra-manual.html#dx1-35194" >1023
    \glsgetattribute  960
    +href="glossaries-extra-manual.html#dx1-35177" >1024
    \glsgetcategoryattribute  961
    +href="glossaries-extra-manual.html#dx1-35176" >1025
    \glsgetwidestname  962
    +href="glossaries-extra-manual.html#dx1-19076" >1026
    \glsgetwidestsubname  963
    +href="glossaries-extra-manual.html#dx1-19077" >1027
    \glshasattribute  964
    +href="glossaries-extra-manual.html#dx1-35180" >1028
    \glshascategoryattribute  965
    +href="glossaries-extra-manual.html#dx1-35178" >1029
    \glshex  966
    +href="glossaries-extra-manual.html#dx1-46001" >1030
    \glsifattribute  967
    +href="glossaries-extra-manual.html#dx1-35185" >1031
    \glsifcategory  968
    +href="glossaries-extra-manual.html#dx1-35020" >1032
    \glsifcategoryattribute  969
    +href="glossaries-extra-manual.html#dx1-35181" >1033
    \glsifnotregular  970
    +href="glossaries-extra-manual.html#dx1-35192" >1034
    \glsifnotregularcategory  971
    +href="glossaries-extra-manual.html#dx1-35191" >1035
    \glsifregular  972
    +href="glossaries-extra-manual.html#dx1-35188" >1036
    \glsifregularcategory  973
    +href="glossaries-extra-manual.html#dx1-35187" >1037
    \glskeylisttok  974
    +href="glossaries-extra-manual.html#dx1-31037" >1038
    \glslabeltok  975
    +href="glossaries-extra-manual.html#dx1-31036" >1039
    \glslink options
        counter  976, 977
    - - - +href="glossaries-extra-manual.html#dx1-4117" >1040, 1041
        format  978, 979, 980, 981
    +href="glossaries-extra-manual.html#dx1-7058" >1042, 1043, 1044, 1045
        hyper  982, 983, 984
    +href="glossaries-extra-manual.html#dx1-13055" >1046, 1047, 1048
        hyper=false  985
    +href="glossaries-extra-manual.html#dx1-34005" >1049
        hyperoutside  986, 987
    +href="glossaries-extra-manual.html#dx1-7018" >1050, 1051
        noindex  988, 989, 990, 991, 992, 993, 994
    +href="glossaries-extra-manual.html#dx1-7003" >1052, 1053, 1054, 1055, 1056, 1057, 1058
        prefix  995, 996
    +href="glossaries-extra-manual.html#dx1-7025" >1059, 1060
        textformat  997, 998
    +href="glossaries-extra-manual.html#dx1-7022" >1061, 1062
        theHvalue  999, 1000
    +href="glossaries-extra-manual.html#dx1-7028" >1063, 1064
        thevalue  1001, 1002
    +href="glossaries-extra-manual.html#dx1-7027" >1065, 1066
        wrgloss  1003, 1004, 1005, 1006
    +href="glossaries-extra-manual.html#dx1-7011" >1067, 1068, 1069, 1070
    \glslinkcheckfirsthyperhook  1007
    +href="glossaries-extra-manual.html#dx1-37042" >1071
    \glslinkpresetkeys  1008
    +href="glossaries-extra-manual.html#dx1-7039" >1072
    \glslistchildpostlocation  1009
    +href="glossaries-extra-manual.html#dx1-19029" >1073
    \glslistchildprelocation  1010
    +href="glossaries-extra-manual.html#dx1-19020" >1074
    \glslistdesc  1011
    +href="glossaries-extra-manual.html#dx1-19021" >1075
    \glslistgroupskip  1012
    +href="glossaries-extra-manual.html#dx1-19032" >1076
    \glslistprelocation  1013
    +href="glossaries-extra-manual.html#dx1-19019" >1077
    \glslocalreseteach  1014
    +href="glossaries-extra-manual.html#dx1-11010" >1078
    \glslocalunseteach  1015
    +href="glossaries-extra-manual.html#dx1-11011" >1079
    + + + \glslongdefaultfont  1016
    +href="glossaries-extra-manual.html#dx1-28035" >1080
    \glslongemfont  1017
    +href="glossaries-extra-manual.html#dx1-28063" >1081
    \glslongextraDescAlign  1018
    +href="glossaries-extra-manual.html#dx1-22020" >1082
    \glslongextraDescFmt  1019
    +href="glossaries-extra-manual.html#dx1-22036" >1083
    \glslongextraDescNameHeader  1020
    +href="glossaries-extra-manual.html#dx1-22070" >1084
    \glslongextraDescNameTabularFooter  1021
    +href="glossaries-extra-manual.html#dx1-22074" >1085
    \glslongextraDescNameTabularHeader  1022
    +href="glossaries-extra-manual.html#dx1-22073" >1086
    \glslongextraDescSymNameHeader  1023
    +href="glossaries-extra-manual.html#dx1-22136" >1087
    \glslongextraDescSymNameTabularFooter  1024
    +href="glossaries-extra-manual.html#dx1-22140" >1088
    \glslongextraDescSymNameTabularHeader  1025
    +href="glossaries-extra-manual.html#dx1-22139" >1089
    \glslongextraGroupHeading  1026
    +href="glossaries-extra-manual.html#dx1-22043" >1090
    \glslongextraHeaderFmt  1027
    +href="glossaries-extra-manual.html#dx1-22010" >1091
    \glslongextraLocationAlign  1028
    +href="glossaries-extra-manual.html#dx1-22016" >1092
    \glslongextraLocationDescNameHeader  1029
    +href="glossaries-extra-manual.html#dx1-22078" >1093
    \glslongextraLocationDescNameTabularFooter  1030
    +href="glossaries-extra-manual.html#dx1-22082" >1094
    \glslongextraLocationDescNameTabularHeader  1031
    +href="glossaries-extra-manual.html#dx1-22081" >1095
    \glslongextraLocationDescSymNameHeader  1032
    +href="glossaries-extra-manual.html#dx1-22144" >1096
    \glslongextraLocationDescSymNameTabularFooter  1033
    +href="glossaries-extra-manual.html#dx1-22148" >1097
    \glslongextraLocationDescSymNameTabularHeader  1034
    +href="glossaries-extra-manual.html#dx1-22147" >1098
    \glslongextraLocationFmt  1035, 1036
    +href="glossaries-extra-manual.html#dx1-22038" >1099, 1100
    \glslongextraLocationSymDescNameHeader  1037
    +href="glossaries-extra-manual.html#dx1-22128" >1101
    \glslongextraLocationSymDescNameTabularFooter  1038
    +href="glossaries-extra-manual.html#dx1-22132" >1102
    \glslongextraLocationSymDescNameTabularHeader  1039
    +href="glossaries-extra-manual.html#dx1-22131" >1103
    \glslongextraLocSetDescWidth  1040
    +href="glossaries-extra-manual.html#dx1-22033" >1104
    \glslongextraNameAlign  1041
    +href="glossaries-extra-manual.html#dx1-22012" >1105
    \glslongextraNameDescHeader  1042
    +href="glossaries-extra-manual.html#dx1-22047" >1106
    \glslongextraNameDescLocationHeader  1043
    - - - +href="glossaries-extra-manual.html#dx1-22061" >1107
    \glslongextraNameDescLocationTabularFooter  1044
    +href="glossaries-extra-manual.html#dx1-22065" >1108
    \glslongextraNameDescLocationTabularHeader  1045
    +href="glossaries-extra-manual.html#dx1-22064" >1109
    \glslongextraNameDescSymHeader  1046
    +href="glossaries-extra-manual.html#dx1-22086" >1110
    \glslongextraNameDescSymLocationHeader  1047
    +href="glossaries-extra-manual.html#dx1-22094" >1111
    \glslongextraNameDescSymLocationTabularFooter  1048
    +href="glossaries-extra-manual.html#dx1-22098" >1112
    \glslongextraNameDescSymLocationTabularHeader  1049
    +href="glossaries-extra-manual.html#dx1-22097" >1113
    \glslongextraNameDescSymTabularFooter  1050
    +href="glossaries-extra-manual.html#dx1-22090" >1114
    \glslongextraNameDescSymTabularHeader  1051
    +href="glossaries-extra-manual.html#dx1-22089" >1115
    \glslongextraNameDescTabularFooter  1052
    +href="glossaries-extra-manual.html#dx1-22050" >1116
    \glslongextraNameDescTabularHeader  1053
    +href="glossaries-extra-manual.html#dx1-22049" >1117
    \glslongextraNameFmt  1054
    +href="glossaries-extra-manual.html#dx1-22035" >1118
    \glslongextraNameSymDescHeader  1055
    +href="glossaries-extra-manual.html#dx1-22103" >1119
    \glslongextraNameSymDescLocationHeader  1056
    +href="glossaries-extra-manual.html#dx1-22112" >1120
    \glslongextraNameSymDescLocationTabularFooter  1057
    +href="glossaries-extra-manual.html#dx1-22116" >1121
    \glslongextraNameSymDescLocationTabularHeader  1058
    +href="glossaries-extra-manual.html#dx1-22115" >1122
    \glslongextraNameSymDescTabularFooter  1059
    +href="glossaries-extra-manual.html#dx1-22107" >1123
    \glslongextraNameSymDescTabularHeader  1060
    +href="glossaries-extra-manual.html#dx1-22106" >1124
    \glslongextraSetDescWidth  1061
    +href="glossaries-extra-manual.html#dx1-22023" >1125
    \glslongextraSetWidest  1062
    +href="glossaries-extra-manual.html#dx1-22024" >1126
    + + + \glslongextraSubDescFmt  1063
    +href="glossaries-extra-manual.html#dx1-22040" >1127
    \glslongextraSubNameFmt  1064
    +href="glossaries-extra-manual.html#dx1-22039" >1128
    \glslongextraSubSymbolFmt  1065
    +href="glossaries-extra-manual.html#dx1-22041" >1129
    \glslongextraSymbolAlign  1066
    +href="glossaries-extra-manual.html#dx1-22014" >1130
    \glslongextraSymbolFmt  1067
    +href="glossaries-extra-manual.html#dx1-22037" >1131
    \glslongextraSymDescNameHeader  1068
    +href="glossaries-extra-manual.html#dx1-22120" >1132
    \glslongextraSymDescNameTabularFooter  1069
    +href="glossaries-extra-manual.html#dx1-22124" >1133
    \glslongextraSymDescNameTabularHeader  1070
    +href="glossaries-extra-manual.html#dx1-22123" >1134
    \glslongextraSymLocSetDescWidth  1071
    +href="glossaries-extra-manual.html#dx1-22034" >1135
    \glslongextraSymSetDescWidth  1072
    +href="glossaries-extra-manual.html#dx1-22032" >1136
    \glslongextraTabularVAlign  1073
    +href="glossaries-extra-manual.html#dx1-22009" >1137
    \glslongextraUpdateWidest  1074
    +href="glossaries-extra-manual.html#dx1-22025" >1138
    \glslongextraUpdateWidestChild  1075
    +href="glossaries-extra-manual.html#dx1-22031" >1139
    \GlsLongExtraUseTabulartrue  1076
    +href="glossaries-extra-manual.html#dx1-22008" >1140
    \glslongfont  1077
    +href="glossaries-extra-manual.html#dx1-31050" >1141
    \glslongfootnotefont  1078
    +href="glossaries-extra-manual.html#dx1-30157" >1142
    \glslonghyphenfont  1079
    +href="glossaries-extra-manual.html#dx1-28071" >1143
    \glslongonlyfont  1080
    +href="glossaries-extra-manual.html#dx1-28077" >1144
    \glslongpltok  1081
    +href="glossaries-extra-manual.html#dx1-31029" >1145
    \glslongtok  1082
    +href="glossaries-extra-manual.html#dx1-31028" >1146
    \glslonguserfont  1083
    +href="glossaries-extra-manual.html#dx1-28066" >1147
    \glsnoidxdisplayloc  1084
    +href="glossaries-extra-manual.html#dx1-18014" >1148
    +\glspdffmtfull  1149
    +\glspdffmtfullpl  1150
    \glsps  1085
    +href="glossaries-extra-manual.html#dx1-13053" >1151
    \glspt  1086
    +href="glossaries-extra-manual.html#dx1-13054" >1152
    \glsrenewcommand  1087
    +href="glossaries-extra-manual.html#dx1-43027" >1153
    \glsseeitemformat  1088
    +href="glossaries-extra-manual.html#dx1-8036" >1154
    \glssetattribute  1089
    - - - +href="glossaries-extra-manual.html#dx1-35175" >1155
    \glssetcategoryattribute  1090
    +href="glossaries-extra-manual.html#dx1-35172" >1156
    \glssetregularcategory  1091
    +href="glossaries-extra-manual.html#dx1-35174" >1157
    \glsshortpltok  1092
    +href="glossaries-extra-manual.html#dx1-31025" >1158
    \glsshorttok  1093
    +href="glossaries-extra-manual.html#dx1-31024" >1159
    \glstopicAssignSubIndent  1094
    +href="glossaries-extra-manual.html#dx1-23029" >1160
    \glstopicAssignWidest  1095
    +href="glossaries-extra-manual.html#dx1-23030" >1161
    \glstopicCols  1096
    +href="glossaries-extra-manual.html#dx1-23014" >1162
    \glstopicColsEnv  1097
    +href="glossaries-extra-manual.html#dx1-23013" >1163
    \glstopicDesc  1098
    +href="glossaries-extra-manual.html#dx1-23026" >1164
    \glstopicGroupHeading  1099
    +href="glossaries-extra-manual.html#dx1-23018" >1165
    \glstopicInit  1100
    +href="glossaries-extra-manual.html#dx1-23017" >1166
    \glstopicItem  1101
    +href="glossaries-extra-manual.html#dx1-23020" >1167
    \glstopicLoc  1102
    +href="glossaries-extra-manual.html#dx1-23028" >1168
    \glstopicMarker  1103
    +href="glossaries-extra-manual.html#dx1-23022" >1169
    \glstopicMidSkip  1104
    +href="glossaries-extra-manual.html#dx1-23025" >1170
    \glstopicParIndent  1105
    +href="glossaries-extra-manual.html#dx1-23015" >1171
    \glstopicPostSkip  1106
    +href="glossaries-extra-manual.html#dx1-23027" >1172
    + + + \glstopicPreSkip  1107
    +href="glossaries-extra-manual.html#dx1-23021" >1173
    \glstopicSubIndent  1108
    +href="glossaries-extra-manual.html#dx1-23016" >1174
    \glstopicSubItem  1109
    +href="glossaries-extra-manual.html#dx1-23031" >1175
    \glstopicSubItemBox  1110
    +href="glossaries-extra-manual.html#dx1-23034" >1176
    \glstopicSubItemSep  1111
    +href="glossaries-extra-manual.html#dx1-23033" >1177
    \glstopicSubLoc  1112
    +href="glossaries-extra-manual.html#dx1-23036" >1178
    \glstopicSubNameFont  1113
    +href="glossaries-extra-manual.html#dx1-23032" >1179
    \glstopicSubPreLocSep  1114
    +href="glossaries-extra-manual.html#dx1-23035" >1180
    \glstopicTitle  1115
    +href="glossaries-extra-manual.html#dx1-23023" >1181
    \glstopicTitleFont  1116
    +href="glossaries-extra-manual.html#dx1-23024" >1182
    \glstreechilddesc  1117
    +href="glossaries-extra-manual.html#dx1-19060" >1183
    \glstreeChildDescLoc  1118
    +href="glossaries-extra-manual.html#dx1-19063" >1184
    \glstreechildprelocation  1119
    +href="glossaries-extra-manual.html#dx1-19049" >1185
    \glstreechildsymbol  1120
    +href="glossaries-extra-manual.html#dx1-19061" >1186
    \glstreedefaultnamefmt  1121
    +href="glossaries-extra-manual.html#dx1-19039" >1187
    \glstreedesc  1122
    +href="glossaries-extra-manual.html#dx1-19058" >1188
    \glstreeDescLoc  1123
    +href="glossaries-extra-manual.html#dx1-19062" >1189
    \glstreegroupskip  1124
    +href="glossaries-extra-manual.html#dx1-19040" >1190
    +\glstreeheadergroupskip  1191
    +\glstreeNoDescSymbolPreLocation  1192
    \glstreenonamechilddesc  1125
    +href="glossaries-extra-manual.html#dx1-19054" >1193
    \glstreenonamedesc  1126
    +href="glossaries-extra-manual.html#dx1-19050" >1194
    \glstreenonamesymbol  1127
    +href="glossaries-extra-manual.html#dx1-19052" >1195
    \glstreePreHeader  1128
    +href="glossaries-extra-manual.html#dx1-19044" >1196
    \glstreeprelocation  1129
    +href="glossaries-extra-manual.html#dx1-19048" >1197
    \glstreesymbol  1130
    +href="glossaries-extra-manual.html#dx1-19059" >1198
    \glsupdatewidest  1131
    +href="glossaries-extra-manual.html#dx1-19072" >1199
    \glsuseabbrvfont  1132
    +href="glossaries-extra-manual.html#dx1-24036" >1200
    \glsuselongfont  1133
    +href="glossaries-extra-manual.html#dx1-24037" >1201
    \glsuserdescription  1134
    +href="glossaries-extra-manual.html#dx1-30041" >1202
    \Glsxtr  1135
    - - - +href="glossaries-extra-manual.html#dx1-54014" >1203
    \glsxtr  1136
    +href="glossaries-extra-manual.html#dx1-54009" >1204
    \glsxtrabbreviationfont  1137
    +href="glossaries-extra-manual.html#dx1-9029" >1205
    \glsxtrabbrvfootnote  1138
    +href="glossaries-extra-manual.html#dx1-30158" >1206
    \glsxtrabbrvpluralsuffix  1139, 1140
    +href="glossaries-extra-manual.html#dx1-12035" >1207, 1208
    \glsxtractivatenopost  1141
    +href="glossaries-extra-manual.html#dx1-52014" >1209
    \glsxtraddallcrossrefs  1142
    +href="glossaries-extra-manual.html#dx1-8010" >1210
    \glsxtraddlabelprefix  1143
    +href="glossaries-extra-manual.html#dx1-47014" >1211
    \glsxtralias  1144
    +href="glossaries-extra-manual.html#dx1-53019" >1212
    \glsxtrAltTreeIndent  1145
    +href="glossaries-extra-manual.html#dx1-19104" >1213
    \glsxtralttreeInit  1146
    +href="glossaries-extra-manual.html#dx1-19103" >1214
    \glsxtralttreeSubSymbolDescLocation  1147
    +href="glossaries-extra-manual.html#dx1-19101" >1215
    \glsxtralttreeSymbolDescLocation  1148
    +href="glossaries-extra-manual.html#dx1-19100" >1216
    \GlsXtrAutoAddOnFormat  1149
    +href="glossaries-extra-manual.html#dx1-7002" >1217
    \glsxtrautoindex  1150
    +href="glossaries-extra-manual.html#dx1-39024" >1218
    \glsxtrautoindexassignsort  1151
    +href="glossaries-extra-manual.html#dx1-39020" >1219
    + + + \glsxtrautoindexentry  1152
    +href="glossaries-extra-manual.html#dx1-39019" >1220
    \glsxtrautoindexesc  1153
    +href="glossaries-extra-manual.html#dx1-39022" >1221
    \glsxtrBasicDigitrules  1154
    +href="glossaries-extra-manual.html#dx1-46057" >1222
    \GlsXtrBibTeXEntryAliases  1155
    +href="glossaries-extra-manual.html#dx1-46005" >1223
    \glsxtrbookindexatendgroup  1156
    +href="glossaries-extra-manual.html#dx1-21034" >1224
    \glsxtrbookindexbetween  1157
    +href="glossaries-extra-manual.html#dx1-21029" >1225
    \glsxtrbookindexbookmark  1158
    +href="glossaries-extra-manual.html#dx1-21039" >1226
    \glsxtrbookindexcols  1159
    +href="glossaries-extra-manual.html#dx1-21010" >1227
    \glsxtrbookindexcolspread  1160
    +href="glossaries-extra-manual.html#dx1-21013" >1228
    \glsxtrbookindexfirstmark  1161
    +href="glossaries-extra-manual.html#dx1-21045" >1229
    \glsxtrbookindexfirstmarkfmt  1162
    +href="glossaries-extra-manual.html#dx1-21047" >1230
    \glsxtrbookindexformatheader  1163
    +href="glossaries-extra-manual.html#dx1-21041" >1231
    \glsxtrbookindexlastmark  1164
    +href="glossaries-extra-manual.html#dx1-21046" >1232
    \glsxtrbookindexlastmarkfmt  1165
    +href="glossaries-extra-manual.html#dx1-21048" >1233
    \glsxtrbookindexlocation  1166
    +href="glossaries-extra-manual.html#dx1-21025" >1234
    \glsxtrbookindexmarkentry  1167
    +href="glossaries-extra-manual.html#dx1-21044" >1235
    \glsxtrbookindexmulticolsenv  1168
    +href="glossaries-extra-manual.html#dx1-21018" >1236
    \glsxtrbookindexname  1169
    +href="glossaries-extra-manual.html#dx1-21019" >1237
    \glsxtrbookindexparentchildsep  1170
    +href="glossaries-extra-manual.html#dx1-21027" >1238
    \glsxtrbookindexparentsubchildsep  1171
    +href="glossaries-extra-manual.html#dx1-21028" >1239
    \glsxtrbookindexprelocation  1172
    +href="glossaries-extra-manual.html#dx1-21021" >1240
    \glsxtrbookindexsubatendgroup  1173
    +href="glossaries-extra-manual.html#dx1-21033" >1241
    \glsxtrbookindexsubbetween  1174
    +href="glossaries-extra-manual.html#dx1-21030" >1242
    \glsxtrbookindexsublocation  1175
    +href="glossaries-extra-manual.html#dx1-21026" >1243
    \glsxtrbookindexsubname  1176
    +href="glossaries-extra-manual.html#dx1-21020" >1244
    \glsxtrbookindexsubprelocation  1177
    +href="glossaries-extra-manual.html#dx1-21024" >1245
    \glsxtrbookindexsubsubatendgroup  1178
    +href="glossaries-extra-manual.html#dx1-21032" >1246
    \glsxtrbookindexsubsubbetween  1179
    +href="glossaries-extra-manual.html#dx1-21031" >1247
    \glsxtrchecknohyperfirst  1180
    +href="glossaries-extra-manual.html#dx1-35033" >1248
    \glsxtrclearlabelprefixes  1181
    +href="glossaries-extra-manual.html#dx1-47016" >1249
    \glsxtrcombiningdiacriticIIIrules  1182
    - - - +href="glossaries-extra-manual.html#dx1-46049" >1250
    \glsxtrcombiningdiacriticIIrules  1183
    +href="glossaries-extra-manual.html#dx1-46048" >1251
    \glsxtrcombiningdiacriticIrules  1184
    +href="glossaries-extra-manual.html#dx1-46047" >1252
    \glsxtrcombiningdiacriticIVrules  1185
    +href="glossaries-extra-manual.html#dx1-46050" >1253
    \glsxtrcombiningdiacriticrules  1186
    +href="glossaries-extra-manual.html#dx1-46046" >1254
    \glsxtrcontrolrules  1187
    +href="glossaries-extra-manual.html#dx1-46042" >1255
    \glsxtrcopytoglossary  1188
    +href="glossaries-extra-manual.html#dx1-49007" >1256
    \glsxtrcurrencyrules  1189
    +href="glossaries-extra-manual.html#dx1-46054" >1257
    \GlsXtrDefaultResourceOptions  1190
    +href="glossaries-extra-manual.html#dx1-47004" >1258
    \glsxtrdeffield  1191
    +href="glossaries-extra-manual.html#dx1-50020" >1259
    \glsxtrdetoklocation  1192
    +href="glossaries-extra-manual.html#dx1-48004" >1260
    \glsxtrdigitrules  1193
    +href="glossaries-extra-manual.html#dx1-46056" >1261
    +\GlsXtrDiscardUnsetBuffering  1262
    \glsxtrdisplayendloc  1194
    +href="glossaries-extra-manual.html#dx1-18017" >1263
    \glsxtrdisplayendlochook  1195
    +href="glossaries-extra-manual.html#dx1-18019" >1264
    \glsxtrdisplaylocnameref  1196
    +href="glossaries-extra-manual.html#dx1-45018" >1265
    + + + \glsxtrdisplaysingleloc  1197
    +href="glossaries-extra-manual.html#dx1-18015" >1266
    \glsxtrdisplaystartloc  1198
    +href="glossaries-extra-manual.html#dx1-18016" >1267
    \glsxtrdisplaysupploc  1199
    +href="glossaries-extra-manual.html#dx1-44001" >1268
    \glsxtrdoautoindexname  1200
    +href="glossaries-extra-manual.html#dx1-39016" >1269
    \glsxtrdowrglossaryhook  1201
    +href="glossaries-extra-manual.html#dx1-7038" >1270
    \glsxtredeffield  1202
    +href="glossaries-extra-manual.html#dx1-50023" >1271
    \glsxtremsuffix  1203
    +href="glossaries-extra-manual.html#dx1-28059" >1272
    \GlsXtrEnableEntryCounting  1204
    +href="glossaries-extra-manual.html#dx1-37027" >1273
    \GlsXtrEnableEntryUnitCounting  1205
    +href="glossaries-extra-manual.html#dx1-37030" >1274
    \GlsXtrEnableIndexFormatOverride  1206
    +href="glossaries-extra-manual.html#dx1-39033" >1275
    \GlsXtrEnableInitialTagging  1207
    +href="glossaries-extra-manual.html#dx1-25001" >1276
    \GlsXtrEnableLinkCounting  1208
    +href="glossaries-extra-manual.html#dx1-38002" >1277
    \GlsXtrEnableOnTheFly  1209
    +href="glossaries-extra-manual.html#dx1-54007" >1278
    \GlsXtrEnablePreLocationTag  1210
    +href="glossaries-extra-manual.html#dx1-18010" >1279
    \glsxtrenablerecordcount  1211
    +href="glossaries-extra-manual.html#dx1-48032" >1280
    \glsxtrendfor  1212
    +href="glossaries-extra-manual.html#dx1-50075" >1281
    \glsxtrentryfmt  1213
    +href="glossaries-extra-manual.html#dx1-50008" >1282
    \GlsXtrExpandedFmt  1214
    +href="glossaries-extra-manual.html#dx1-11019" >1283
    \glsxtrfielddolistloop  1215
    +href="glossaries-extra-manual.html#dx1-50057" >1284
    \glsxtrfieldforlistloop  1216
    +href="glossaries-extra-manual.html#dx1-50058" >1285
    +\glsxtrfieldformatcsvlist  1286
    +\glsxtrfieldformatlist  1287
    \glsxtrfieldifinlist  1217
    +href="glossaries-extra-manual.html#dx1-50067" >1288
    \glsxtrfieldlistadd  1218
    +href="glossaries-extra-manual.html#dx1-50053" >1289
    \glsxtrfieldlisteadd  1219
    +href="glossaries-extra-manual.html#dx1-50055" >1290
    \glsxtrfieldlistgadd  1220
    +href="glossaries-extra-manual.html#dx1-50054" >1291
    \glsxtrfieldlistxadd  1221
    +href="glossaries-extra-manual.html#dx1-50056" >1292
    \glsxtrfieldtitlecasecs  1222
    +href="glossaries-extra-manual.html#dx1-35099" >1293
    \glsxtrfieldxifinlist  1223
    +href="glossaries-extra-manual.html#dx1-50068" >1294
    \glsxtrfmt  1224
    +href="glossaries-extra-manual.html#dx1-50002" >1295
    \glsxtrfmt*  1225
    +href="glossaries-extra-manual.html#dx1-50004" >1296
    \GlsXtrFmtDefaultOptions  1226
    +href="glossaries-extra-manual.html#dx1-50003" >1297
    \glsxtrfmtdisplay  1227
    +href="glossaries-extra-manual.html#dx1-50005" >1298
    \glsxtrfmtexternalnameref  1228
    - - - +href="glossaries-extra-manual.html#dx1-45023" >1299
    \GlsXtrFmtField  1229
    +href="glossaries-extra-manual.html#dx1-50001" >1300
    \glsxtrfmtinternalnameref  1230
    +href="glossaries-extra-manual.html#dx1-45022" >1301
    +\glsxtrfootnotedescname  1302
    +\glsxtrfootnotedescsort  1303
    \glsxtrfootnotename  1231
    +href="glossaries-extra-manual.html#dx1-30154" >1304
    \glsxtrforcsvfield  1232
    +href="glossaries-extra-manual.html#dx1-50070" >1305
    \GlsXtrForeignText  1233
    +href="glossaries-extra-manual.html#dx1-50078" >1306
    \GlsXtrForeignTextField  1234
    +href="glossaries-extra-manual.html#dx1-50077" >1307
    \GlsXtrFormatLocationList  1235
    +href="glossaries-extra-manual.html#dx1-18002" >1308
    \GlsXtrForUnsetBufferedList  1236
    +href="glossaries-extra-manual.html#dx1-11015" >1309
    \glsxtrfractionrules  1237
    +href="glossaries-extra-manual.html#dx1-46060" >1310
    \GLSxtrfull  1238
    +href="glossaries-extra-manual.html#dx1-26025" >1311
    + + + \Glsxtrfull  1239
    +href="glossaries-extra-manual.html#dx1-26022" >1312
    \glsxtrfull  1240
    +href="glossaries-extra-manual.html#dx1-26014" >1313
    \Glsxtrfullformat  1241
    +href="glossaries-extra-manual.html#dx1-31058" >1314
    \glsxtrfullformat  1242
    +href="glossaries-extra-manual.html#dx1-31054" >1315
    \GLSxtrfullpl  1243
    +href="glossaries-extra-manual.html#dx1-26034" >1316
    \Glsxtrfullpl  1244
    +href="glossaries-extra-manual.html#dx1-26033" >1317
    \glsxtrfullpl  1245
    +href="glossaries-extra-manual.html#dx1-26032" >1318
    \Glsxtrfullplformat  1246
    +href="glossaries-extra-manual.html#dx1-31066" >1319
    \glsxtrfullplformat  1247
    +href="glossaries-extra-manual.html#dx1-31062" >1320
    \glsxtrfullsep  1248
    +href="glossaries-extra-manual.html#dx1-28082" >1321
    \glsxtrGeneralLatinIIIrules  1249
    +href="glossaries-extra-manual.html#dx1-46063" >1322
    \glsxtrGeneralLatinIIrules  1250
    +href="glossaries-extra-manual.html#dx1-46062" >1323
    \glsxtrGeneralLatinIrules  1251
    +href="glossaries-extra-manual.html#dx1-46061" >1324
    \glsxtrGeneralLatinIVrules  1252
    +href="glossaries-extra-manual.html#dx1-46064" >1325
    \glsxtrGeneralLatinVIIIrules  1253
    +href="glossaries-extra-manual.html#dx1-46068" >1326
    \glsxtrGeneralLatinVIIrules  1254
    +href="glossaries-extra-manual.html#dx1-46067" >1327
    \glsxtrGeneralLatinVIrules  1255
    +href="glossaries-extra-manual.html#dx1-46066" >1328
    \glsxtrGeneralLatinVrules  1256
    +href="glossaries-extra-manual.html#dx1-46065" >1329
    \glsxtrgeneralpuncIIrules  1257
    +href="glossaries-extra-manual.html#dx1-46055" >1330
    \glsxtrgeneralpuncIrules  1258
    +href="glossaries-extra-manual.html#dx1-46053" >1331
    \glsxtrgeneralpuncrules  1259
    +href="glossaries-extra-manual.html#dx1-46052" >1332
    \glsxtrglossentry  1260
    +href="glossaries-extra-manual.html#dx1-52004" >1333
    \glsxtrglossentryother  1261
    +href="glossaries-extra-manual.html#dx1-52016" >1334
    \glsxtrgroupfield  1262
    +href="glossaries-extra-manual.html#dx1-51013" >1335
    \GLSXTRhiername  1263
    +href="glossaries-extra-manual.html#dx1-8056" >1336
    \GLSxtrhiername  1264
    +href="glossaries-extra-manual.html#dx1-8055" >1337
    \GlsXtrhiername  1265
    +href="glossaries-extra-manual.html#dx1-8054" >1338
    \Glsxtrhiername  1266
    +href="glossaries-extra-manual.html#dx1-8053" >1339
    \glsxtrhiername  1267
    +href="glossaries-extra-manual.html#dx1-8046" >1340
    \glsxtrhiernamesep  1268
    +href="glossaries-extra-manual.html#dx1-8052" >1341
    \glsxtrhyphenrules  1269
    +href="glossaries-extra-manual.html#dx1-46051" >1342
    \glsxtrhyphensuffix  1270
    +href="glossaries-extra-manual.html#dx1-28073" >1343
    \glsxtridentifyglslike  1271
    +href="glossaries-extra-manual.html#dx1-47012" >1344
    \glsxtrifcounttrigger  1272
    +href="glossaries-extra-manual.html#dx1-37021" >1345
    \glsxtrifcustomdiscardperiod  1273
    +href="glossaries-extra-manual.html#dx1-9035" >1346
    \GlsXtrIfFieldCmpNum  1274
    - - - +href="glossaries-extra-manual.html#dx1-50045" >1347
    \GlsXtrIfFieldEqNum  1275
    +href="glossaries-extra-manual.html#dx1-50044" >1348
    \GlsXtrIfFieldEqStr  1276
    +href="glossaries-extra-manual.html#dx1-50036" >1349
    \GlsXtrIfFieldEqXpStr  1277
    +href="glossaries-extra-manual.html#dx1-50038" >1350
    \GlsXtrIfFieldNonZero  1278
    +href="glossaries-extra-manual.html#dx1-50043" >1351
    \GlsXtrIfFieldUndef  1279
    +href="glossaries-extra-manual.html#dx1-50035" >1352
    +\GlsXtrIfFieldValueInCsvList  1353
    \glsxtrifhasfield  1280
    +href="glossaries-extra-manual.html#dx1-50031" >1354
    \glsxtrifhasfield*  1281
    +href="glossaries-extra-manual.html#dx1-50033" >1355
    \GlsXtrIfHasNonZeroChildCount  1282
    +href="glossaries-extra-manual.html#dx1-46004" >1356
    \glsxtrifinlabelprefixlist  1283
    +href="glossaries-extra-manual.html#dx1-47017" >1357
    + + + \glsxtrifkeydefined  1284
    +href="glossaries-extra-manual.html#dx1-50012" >1358
    \glsxtriflabelinlist  1285
    +href="glossaries-extra-manual.html#dx1-51040" >1359
    \GlsXtrIfLinkCounterDef  1286
    +href="glossaries-extra-manual.html#dx1-38008" >1360
    \glsxtrifrecordtrigger  1287
    +href="glossaries-extra-manual.html#dx1-48018" >1361
    \GlsXtrIfUnusedOrUndefined  1288
    +href="glossaries-extra-manual.html#dx1-11007" >1362
    \glsxtrifwasfirstuse  1289
    +href="glossaries-extra-manual.html#dx1-9053" >1363
    \GlsXtrIfXpFieldEqXpStr  1290
    +href="glossaries-extra-manual.html#dx1-50039" >1364
    \glsxtrinclinkcounter  1291
    +href="glossaries-extra-manual.html#dx1-38005" >1365
    \glsxtrindexaliased  1292
    +href="glossaries-extra-manual.html#dx1-53017" >1366
    \GlsXtrIndexCounterLink  1293
    +href="glossaries-extra-manual.html#dx1-43028" >1367
    \glsxtrindexseealso  1294
    +href="glossaries-extra-manual.html#dx1-8079" >1368
    \glsxtrinitwrgloss  1295
    +href="glossaries-extra-manual.html#dx1-7013" >1369
    \Glsxtrinlinefullformat  1296
    +href="glossaries-extra-manual.html#dx1-31073" >1370
    \glsxtrinlinefullformat  1297
    +href="glossaries-extra-manual.html#dx1-31070" >1371
    \Glsxtrinlinefullplformat  1298
    +href="glossaries-extra-manual.html#dx1-31080" >1372
    \glsxtrinlinefullplformat  1299
    +href="glossaries-extra-manual.html#dx1-31077" >1373
    \glsxtrinsertinsidetrue  1300
    +href="glossaries-extra-manual.html#dx1-28080" >1374
    \glsxtrLatinA  1301
    +href="glossaries-extra-manual.html#dx1-46069" >1375
    \glsxtrLatinAA  1302
    +href="glossaries-extra-manual.html#dx1-46093" >1376
    \glsxtrLatinAELigature  1303
    +href="glossaries-extra-manual.html#dx1-46086" >1377
    \glsxtrLatinE  1304
    +href="glossaries-extra-manual.html#dx1-46070" >1378
    \glsxtrLatinEszettSs  1305
    +href="glossaries-extra-manual.html#dx1-46082" >1379
    \glsxtrLatinEszettSz  1306
    +href="glossaries-extra-manual.html#dx1-46083" >1380
    \glsxtrLatinEth  1307
    +href="glossaries-extra-manual.html#dx1-46084" >1381
    \glsxtrLatinH  1308
    +href="glossaries-extra-manual.html#dx1-46071" >1382
    \glsxtrLatinI  1309
    +href="glossaries-extra-manual.html#dx1-46073" >1383
    \glsxtrLatinInsularG  1310
    +href="glossaries-extra-manual.html#dx1-46091" >1384
    \glsxtrLatinK  1311
    +href="glossaries-extra-manual.html#dx1-46072" >1385
    \glsxtrLatinL  1312
    +href="glossaries-extra-manual.html#dx1-46074" >1386
    \glsxtrLatinLslash  1313
    +href="glossaries-extra-manual.html#dx1-46089" >1387
    \glsxtrLatinM  1314
    +href="glossaries-extra-manual.html#dx1-46075" >1388
    \glsxtrLatinN  1315
    +href="glossaries-extra-manual.html#dx1-46076" >1389
    \glsxtrLatinO  1316
    +href="glossaries-extra-manual.html#dx1-46077" >1390
    \glsxtrLatinOELigature  1317
    +href="glossaries-extra-manual.html#dx1-46087" >1391
    \glsxtrLatinOslash  1318
    +href="glossaries-extra-manual.html#dx1-46088" >1392
    \glsxtrLatinP  1319
    +href="glossaries-extra-manual.html#dx1-46078" >1393
    \glsxtrLatinS  1320
    - - - +href="glossaries-extra-manual.html#dx1-46079" >1394
    \glsxtrLatinSchwa  1321
    +href="glossaries-extra-manual.html#dx1-46092" >1395
    \glsxtrLatinT  1322
    +href="glossaries-extra-manual.html#dx1-46080" >1396
    \glsxtrLatinThorn  1323
    +href="glossaries-extra-manual.html#dx1-46085" >1397
    \glsxtrLatinWynn  1324
    +href="glossaries-extra-manual.html#dx1-46090" >1398
    \glsxtrLatinX  1325
    +href="glossaries-extra-manual.html#dx1-46081" >1399
    \GlsXtrLetField  1326
    +href="glossaries-extra-manual.html#dx1-50027" >1400
    \GlsXtrLetFieldToField  1327
    +href="glossaries-extra-manual.html#dx1-50029" >1401
    \GlsXtrLinkCounterName  1328
    +href="glossaries-extra-manual.html#dx1-38009" >1402
    \GlsXtrLinkCounterValue  1329
    +href="glossaries-extra-manual.html#dx1-38006" >1403
    + + + \GlsXtrLoadResources  1330
    +href="glossaries-extra-manual.html#dx1-40018" >1404
    \glsxtrlocalsetgrouptitle  1331
    +href="glossaries-extra-manual.html#dx1-16007" >1405
    \GlsXtrLocationField  1332
    +href="glossaries-extra-manual.html#dx1-51036" >1406
    \GlsXtrLocationRecordCount  1333
    +href="glossaries-extra-manual.html#dx1-48008" >1407
    \glsxtrlocrangefmt  1334
    +href="glossaries-extra-manual.html#dx1-18018" >1408
    \Glsxtrlong  1335, 1336
    +href="glossaries-extra-manual.html#dx1-26021" >1409, 1410
    \glsxtrlong  1337
    +href="glossaries-extra-manual.html#dx1-26012" >1411
    \glsxtrlonghyphen  1338
    +href="glossaries-extra-manual.html#dx1-30267" >1412
    \glsxtrlonghyphenshort  1339
    +href="glossaries-extra-manual.html#dx1-30248" >1413
    \glsxtrlongnoshortdescname  1340
    +href="glossaries-extra-manual.html#dx1-29062" >1414
    \glsxtrlongnoshortname  1341
    +href="glossaries-extra-manual.html#dx1-29088" >1415
    \GLSxtrlongpl  1342
    +href="glossaries-extra-manual.html#dx1-26031" >1416
    \Glsxtrlongpl  1343
    +href="glossaries-extra-manual.html#dx1-26030" >1417
    \glsxtrlongpl  1344
    +href="glossaries-extra-manual.html#dx1-26029" >1418
    \glsxtrlongshortdescname  1345
    +href="glossaries-extra-manual.html#dx1-30061" >1419
    \glsxtrlongshortdescsort  1346
    +href="glossaries-extra-manual.html#dx1-30058" >1420
    \glsxtrlongshortname  1347
    +href="glossaries-extra-manual.html#dx1-30006" >1421
    \glsxtrlongshortuserdescname  1348
    +href="glossaries-extra-manual.html#dx1-30082" >1422
    \glsxtrMathGreekIIrules  1349
    +href="glossaries-extra-manual.html#dx1-46101" >1423
    \glsxtrMathGreekIrules  1350
    +href="glossaries-extra-manual.html#dx1-46094" >1424
    \glsxtrMathItalicGreekIIrules  1351
    +href="glossaries-extra-manual.html#dx1-46116" >1425
    \glsxtrMathItalicGreekIrules  1352
    +href="glossaries-extra-manual.html#dx1-46110" >1426
    \glsxtrMathItalicLowerGreekIIrules  1353
    +href="glossaries-extra-manual.html#dx1-46130" >1427
    \glsxtrMathItalicLowerGreekIrules  1354
    +href="glossaries-extra-manual.html#dx1-46126" >1428
    \glsxtrMathItalicNabla  1355
    +href="glossaries-extra-manual.html#dx1-46134" >1429
    \glsxtrMathItalicPartial  1356
    +href="glossaries-extra-manual.html#dx1-46133" >1430
    \glsxtrMathItalicUpperGreekIIrules  1357
    +href="glossaries-extra-manual.html#dx1-46123" >1431
    \glsxtrMathItalicUpperGreekIrules  1358
    +href="glossaries-extra-manual.html#dx1-46119" >1432
    \glsxtrMathUpGreekIIrules  1359
    +href="glossaries-extra-manual.html#dx1-46107" >1433
    \glsxtrMathUpGreekIrules  1360
    +href="glossaries-extra-manual.html#dx1-46102" >1434
    \glsxtrmultisupplocation  1361
    +href="glossaries-extra-manual.html#dx1-44004" >1435
    \glsxtrnameloclink  1362
    +href="glossaries-extra-manual.html#dx1-45025" >1436
    \glsxtrnamereflink  1363
    +href="glossaries-extra-manual.html#dx1-45019" >1437
    \glsxtrnewgls  1364
    +href="glossaries-extra-manual.html#dx1-47005" >1438
    \glsxtrnewGLSlike  1365
    +href="glossaries-extra-manual.html#dx1-47007" >1439
    \glsxtrnewglslike  1366
    +href="glossaries-extra-manual.html#dx1-47006" >1440
    \glsxtrnewnumber  1367
    - - - +href="glossaries-extra-manual.html#dx1-4217" >1441
    \glsxtrnewrgls  1368
    +href="glossaries-extra-manual.html#dx1-47008" >1442
    \glsxtrnewrGLSlike  1369
    +href="glossaries-extra-manual.html#dx1-47010" >1443
    \glsxtrnewrglslike  1370
    +href="glossaries-extra-manual.html#dx1-47009" >1444
    \glsxtrnewsymbol  1371
    +href="glossaries-extra-manual.html#dx1-4211" >1445
    \GlsXtrNoGlsWarningAutoMake  1372
    +href="glossaries-extra-manual.html#dx1-59020" >1446
    \GlsXtrNoGlsWarningBuildInfo  1373
    +href="glossaries-extra-manual.html#dx1-59019" >1447
    \GlsXtrNoGlsWarningCheckFile  1374
    +href="glossaries-extra-manual.html#dx1-59015" >1448
    \GlsXtrNoGlsWarningEmptyMain  1375
    +href="glossaries-extra-manual.html#dx1-59013" >1449
    \GlsXtrNoGlsWarningEmptyNotMain  1376
    +href="glossaries-extra-manual.html#dx1-59014" >1450
    + + + \GlsXtrNoGlsWarningEmptyStart  1377
    +href="glossaries-extra-manual.html#dx1-59012" >1451
    \GlsXtrNoGlsWarningHead  1378
    +href="glossaries-extra-manual.html#dx1-59011" >1452
    \GlsXtrNoGlsWarningMisMatch  1379
    +href="glossaries-extra-manual.html#dx1-59016" >1453
    \GlsXtrNoGlsWarningNoOut  1380
    +href="glossaries-extra-manual.html#dx1-59017" >1454
    \GlsXtrNoGlsWarningTail  1381
    +href="glossaries-extra-manual.html#dx1-59018" >1455
    \glsxtrnonprintablerules  1382
    +href="glossaries-extra-manual.html#dx1-46044" >1456
    \glsxtrnopostpunc  1383
    +href="glossaries-extra-manual.html#dx1-6003" >1457
    \glsxtronlydescname  1384
    +href="glossaries-extra-manual.html#dx1-30027" >1458
    \glsxtronlyname  1385
    +href="glossaries-extra-manual.html#dx1-30023" >1459
    \glsxtronlysuffix  1386
    +href="glossaries-extra-manual.html#dx1-28079" >1460
    \glsxtrorglong  1387
    +href="glossaries-extra-manual.html#dx1-31034" >1461
    \glsxtrorgshort  1388
    +href="glossaries-extra-manual.html#dx1-31033" >1462
    \GLSxtrp  1389
    +href="glossaries-extra-manual.html#dx1-13062" >1463
    \Glsxtrp  1390
    +href="glossaries-extra-manual.html#dx1-13061" >1464
    \glsxtrp  1391
    +href="glossaries-extra-manual.html#dx1-13052" >1465
    \glsxtrpageref  1392
    +href="glossaries-extra-manual.html#dx1-49004" >1466
    \glsxtrparen  1393
    +href="glossaries-extra-manual.html#dx1-28030" >1467
    +\glsxtrpdfentryfmt  1468
    \Glsxtrpl  1394
    +href="glossaries-extra-manual.html#dx1-54015" >1469
    \glsxtrpl  1395
    +href="glossaries-extra-manual.html#dx1-54013" >1470
    \glsxtrpostdescription  1396
    +href="glossaries-extra-manual.html#dx1-17032" >1471
    \glsxtrposthyphenlong  1397
    +href="glossaries-extra-manual.html#dx1-30280" >1472
    \glsxtrposthyphenshort  1398
    +href="glossaries-extra-manual.html#dx1-30265" >1473
    \glsxtrpostlink  1399
    +href="glossaries-extra-manual.html#dx1-9033" >1474
    \glsxtrpostlinkAddDescOnFirstUse  1400
    +href="glossaries-extra-manual.html#dx1-9042" >1475
    \glsxtrpostlinkAddSymbolDescOnFirstUse  1401
    +href="glossaries-extra-manual.html#dx1-9048" >1476
    \glsxtrpostlinkAddSymbolOnFirstUse  1402
    +href="glossaries-extra-manual.html#dx1-9046" >1477
    \glsxtrpostlinkendsentence  1403
    +href="glossaries-extra-manual.html#dx1-9034" >1478
    \glsxtrpostlinkhook  1404
    +href="glossaries-extra-manual.html#dx1-9031" >1479
    \glsxtrpostlongdescription  1405
    +href="glossaries-extra-manual.html#dx1-6017" >1480
    \glsxtrpostnamehook  1406
    +href="glossaries-extra-manual.html#dx1-17026" >1481
    \GlsXtrPostNewAbbreviation  1407
    +href="glossaries-extra-manual.html#dx1-31019" >1482
    \glsxtrprelocation  1408
    +href="glossaries-extra-manual.html#dx1-19017" >1483
    \glsxtrprependlabelprefix  1409
    +href="glossaries-extra-manual.html#dx1-47015" >1484
    \GlsXtrProvideBibTeXFields  1410
    +href="glossaries-extra-manual.html#dx1-46008" >1485
    \glsxtrprovidecommand  1411
    +href="glossaries-extra-manual.html#dx1-43022" >1486
    \glsxtrprovidestoragekey  1412
    +href="glossaries-extra-manual.html#dx1-50011" >1487
    \GlsXtrRecordCount  1413
    - - - +href="glossaries-extra-manual.html#dx1-48007" >1488
    \GlsXtrRecordCounter  1414
    +href="glossaries-extra-manual.html#dx1-50085" >1489
    \glsxtrrecordtriggervalue  1415
    +href="glossaries-extra-manual.html#dx1-48020" >1490
    \glsxtrregularfont  1416
    +href="glossaries-extra-manual.html#dx1-9026" >1491
    \glsxtrresourcefile  1417
    +href="glossaries-extra-manual.html#dx1-40017" >1492
    \glsxtrresourceinit  1418
    +href="glossaries-extra-manual.html#dx1-47003" >1493
    \glsxtrrestorepostpunc  1419
    +href="glossaries-extra-manual.html#dx1-6004" >1494
    \glsxtrRevertMarks  1420
    +href="glossaries-extra-manual.html#dx1-33008" >1495
    \glsxtrRevertTocMarks  1421
    +href="glossaries-extra-manual.html#dx1-33009" >1496
    + + + \glsxtrscsuffix  1422
    +href="glossaries-extra-manual.html#dx1-28044" >1497
    \glsxtrseealsolabels  1423
    +href="glossaries-extra-manual.html#dx1-8073" >1498
    \glsxtrseelist  1424
    +href="glossaries-extra-manual.html#dx1-8077" >1499
    \GlsXtrSetActualChar  1425
    +href="glossaries-extra-manual.html#dx1-39049" >1500
    \glsxtrsetaliasnoindex  1426
    +href="glossaries-extra-manual.html#dx1-53014" >1501
    \GlsXtrSetAltModifier  1427
    +href="glossaries-extra-manual.html#dx1-7037" >1502
    \glsxtrsetcategory  1428
    +href="glossaries-extra-manual.html#dx1-35196" >1503
    \glsxtrsetcategoryforall  1429
    +href="glossaries-extra-manual.html#dx1-35198" >1504
    \GlsXtrSetDefaultGlsOpts  1430
    +href="glossaries-extra-manual.html#dx1-7031" >1505
    \GlsXtrSetEncapChar  1431
    +href="glossaries-extra-manual.html#dx1-39052" >1506
    \GlsXtrSetEscChar  1432
    +href="glossaries-extra-manual.html#dx1-39051" >1507
    \GlsXtrSetField  1433
    +href="glossaries-extra-manual.html#dx1-50016" >1508
    \glsxtrsetfieldifexists  1434
    +href="glossaries-extra-manual.html#dx1-50017" >1509
    \glsxtrsetglossarylabel  1435
    +href="glossaries-extra-manual.html#dx1-15012" >1510
    \glsxtrsetgrouptitle  1436
    +href="glossaries-extra-manual.html#dx1-16006" >1511
    \GlsXtrSetLevelChar  1437
    +href="glossaries-extra-manual.html#dx1-39050" >1512
    \glsxtrsetpopts  1438
    +href="glossaries-extra-manual.html#dx1-13057" >1513
    \GlsXtrSetRecordCountAttribute  1439
    +href="glossaries-extra-manual.html#dx1-48016" >1514
    \glsxtrSetWidest  1440
    +href="glossaries-extra-manual.html#dx1-43035" >1515
    \glsxtrSetWidestFallback  1441
    +href="glossaries-extra-manual.html#dx1-43040" >1516
    \Glsxtrshort  1442, 1443
    +href="glossaries-extra-manual.html#dx1-26020" >1517, 1518
    \glsxtrshort  1444
    +href="glossaries-extra-manual.html#dx1-26010" >1519
    \glsxtrshortdescname  1445
    +href="glossaries-extra-manual.html#dx1-29036" >1520
    \glsxtrshorthyphenlong  1446
    +href="glossaries-extra-manual.html#dx1-30273" >1521
    \glsxtrshortlongdescname  1447
    +href="glossaries-extra-manual.html#dx1-30126" >1522
    \glsxtrshortlongname  1448, 1449
    +href="glossaries-extra-manual.html#dx1-30099" >1523, 1524
    \glsxtrshortlonguserdescname  1450
    +href="glossaries-extra-manual.html#dx1-30144" >1525
    \glsxtrshortnolongname  1451
    +href="glossaries-extra-manual.html#dx1-29005" >1526
    \GLSxtrshortpl  1452
    +href="glossaries-extra-manual.html#dx1-26028" >1527
    \Glsxtrshortpl  1453
    +href="glossaries-extra-manual.html#dx1-26027" >1528
    \glsxtrshortpl  1454
    +href="glossaries-extra-manual.html#dx1-26026" >1529
    \glsxtrsmsuffix  1455
    +href="glossaries-extra-manual.html#dx1-28054" >1530
    \glsxtrspacerules  1456
    +href="glossaries-extra-manual.html#dx1-46043" >1531
    \GlsXtrStandaloneEntryName  1457
    +href="glossaries-extra-manual.html#dx1-52010" >1532
    \GlsXtrStandaloneEntryOther  1458
    +href="glossaries-extra-manual.html#dx1-52017" >1533
    \GlsXtrStandaloneGlossaryType  1459
    +href="glossaries-extra-manual.html#dx1-52005" >1534
    \GlsXtrStartUnsetBuffering  1460
    +href="glossaries-extra-manual.html#dx1-11013" >1535
    \GlsXtrStopUnsetBuffering  1461
    - - - +href="glossaries-extra-manual.html#dx1-11014" >1536
    \glsxtrSubScriptDigitrules  1462
    +href="glossaries-extra-manual.html#dx1-46058" >1537
    \Glsxtrsubsequentfmt  1463
    +href="glossaries-extra-manual.html#dx1-31083" >1538
    \glsxtrsubsequentfmt  1464
    +href="glossaries-extra-manual.html#dx1-31082" >1539
    \Glsxtrsubsequentplfmt  1465
    +href="glossaries-extra-manual.html#dx1-31085" >1540
    \glsxtrsubsequentplfmt  1466
    +href="glossaries-extra-manual.html#dx1-31084" >1541
    \glsxtrSuperScriptDigitrules  1467
    +href="glossaries-extra-manual.html#dx1-46059" >1542
    \glsxtrtagfont  1468
    +href="glossaries-extra-manual.html#dx1-25003" >1543
    \GlsXtrTheLinkCounter  1469
    +href="glossaries-extra-manual.html#dx1-38007" >1544
    + + + \GlsXtrTotalRecordCount  1470
    +href="glossaries-extra-manual.html#dx1-48006" >1545
    \glsxtrunsrtdo  1471
    +href="glossaries-extra-manual.html#dx1-51031" >1546
    \GlsXtrUseAbbrStyleFmts  1472
    +href="glossaries-extra-manual.html#dx1-31089" >1547
    \GlsXtrUseAbbrStyleSetup  1473
    +href="glossaries-extra-manual.html#dx1-31040" >1548
    +\glsxtrusealias  1549
    \GLSxtrusefield  1474
    +href="glossaries-extra-manual.html#dx1-50050" >1550
    \Glsxtrusefield  1475
    +href="glossaries-extra-manual.html#dx1-50049" >1551
    \glsxtrusefield  1476
    +href="glossaries-extra-manual.html#dx1-50047" >1552
    \glsxtruserfield  1477
    +href="glossaries-extra-manual.html#dx1-30033" >1553
    \glsxtruserparen  1478
    +href="glossaries-extra-manual.html#dx1-30036" >1554
    \glsxtrusersuffix  1479, 1480
    +href="glossaries-extra-manual.html#dx1-28068" >1555, 1556
    \glsxtrusesee  1481
    +href="glossaries-extra-manual.html#dx1-8020" >1557
    \glsxtruseseealso  1482
    +href="glossaries-extra-manual.html#dx1-8068" >1558
    \glsxtruseseeformat  1483, 1484
    +href="glossaries-extra-manual.html#dx1-8021" >1559, 1560
    \GlsXtrWarnDeprecatedAbbrStyle  1485
    +href="glossaries-extra-manual.html#dx1-28107" >1561
    \GlsXtrWarning  1486
    +href="glossaries-extra-manual.html#dx1-54011" >1562
    \glsxtrword  1487
    +href="glossaries-extra-manual.html#dx1-35057" >1563
    \glsxtrwordsep  1488
    +href="glossaries-extra-manual.html#dx1-35056" >1564
    \glsxtrwrglossmark  1489
    +class="cmti-10">1565

    H hyperref package  1490, 1491, 1492, 1493, 1494, 1495, 1496, 1497, 1498, 1499, 1500, 1501, 1502, 1503, 1504, 1505, 1506, 1507, 1508, 1509, 1510, 1511, 1512, 1513, 1514
    +href="glossaries-extra-manual.html#dx1-4092" >1566, 1567, 1568, 1569, 1570, 1571, 1572, 1573, 1574, 1575, 1576, 1577, 1578, 1579, 1580, 1581, 1582, 1583, 1584, 1585, 1586, 1587, 1588, 1589, 1590, 1591

    I -\ifglsxtrinitwrglossbefore  1515
    inputenc package  1516
    +href="glossaries-extra-manual.html#dx1-42012" >1592

    L link-text  1517, 1518, 1519, 1520, 1521, 1522, 1523, 1524, 1525, 1526, 1527, 1528, 1529, 1530, 1531, 1532, 1533, 1534, 1535, 1536
    +href="glossaries-extra-manual.html#dx1-9001" >1593, 1594, 1595, 1596, 1597, 1598, 1599, 1600, 1601, 1602, 1603, 1604, 1605, 1606, 1607, 1608, 1609, 1610, 1611, 1612
    location list  1537, 1538, 1539, 1540, 1541
    +href="glossaries-extra-manual.html#dx1-18013" >1613, 1614, 1615, 1616, 1617
    \longnewglossaryentry  1542
    +href="glossaries-extra-manual.html#dx1-6015" >1618

    M makeglossaries  1543, 1544, 1545, 1546, 1547
    +href="glossaries-extra-manual.html#dx1-3027" >1619, 1620, 1621, 1622, 1623
    \makeglossaries  1548
    - - - +href="glossaries-extra-manual.html#dx1-6032" >1624
    makeglossaries-lite  1549, 1550
    +href="glossaries-extra-manual.html#dx1-6038" >1625, 1626
    makeglossaries-lite  1551, 1552
    +href="glossaries-extra-manual.html#dx1-6039" >1627, 1628
    +makeidx package  1629
    makeindex  1553, 1554, 1555, 1556, 1557, 1558, 1559, 1560, 1561, 1562, 1563, 1564, 1565, 1566, 1567, 1568, 1569, 1570, 1571, 1572
    +href="glossaries-extra-manual.html#dx1-3022" >1630, 1631, 1632, 1633, 1634, 1635, 1636, 1637, 1638, 1639, 1640, 1641, 1642, 1643, 1644, 1645, 1646, 1647, 1648, 1649
    makeindex  1573, 1574, 1575, 1576, 1577
    +href="glossaries-extra-manual.html#dx1-7053" >1650, 1651, 1652, 1653, 1654
    memoir class  1578
    +href="glossaries-extra-manual.html#dx1-3021" >1655
    mfirstuc package  1579, 1580, 1581
    +href="glossaries-extra-manual.html#dx1-4" >1656, 1657, 1658
    + + + multicols package  1582
    +href="glossaries-extra-manual.html#dx1-23002" >1659

    N \newabbreviation  1583
    +href="glossaries-extra-manual.html#dx1-24011" >1660
    \newabbreviationstyle  1584
    +href="glossaries-extra-manual.html#dx1-31001" >1661
    \newacronym  1585
    +href="glossaries-extra-manual.html#dx1-24020" >1662
    \newglossaryentry options
        access  1586, 1587
    +href="glossaries-extra-manual.html#dx1-35164" >1663
        alias  1588, 1589, 1590, 1591, 1592, 1593
    +href="glossaries-extra-manual.html#dx1-6008" >1664, 1665, 1666, 1667, 1668, 1669, 1670
        category  1594, 1595, 1596, 1597, 1598, 1599
    +href="glossaries-extra-manual.html#dx1-6007" >1671, 1672, 1673, 1674, 1675, 1676
        counter  1600
    +href="glossaries-extra-manual.html#dx1-7044" >1677
        description  1601, 1602, 1603, 1604, 1605, 1606, 1607, 1608, 1609, 1610, 1611, 1612, 1613, 1614, 1615, 1616, 1617, 1618, 1619, 1620, 1621, 1622, 1623, 1624
    +href="glossaries-extra-manual.html#dx1-6002" >1678, 1679, 1680, 1681, 1682, 1683, 1684, 1685, 1686, 1687, 1688, 1689, 1690, 1691, 1692, 1693, 1694, 1695, 1696, 1697, 1698, 1699, 1700, 1701, 1702, 1703
        descriptionplural  1625, 1626, 1627, 1628, 1629, 1630
    +href="glossaries-extra-manual.html#dx1-6016" >1704, 1705, 1706, 1707, 1708, 1709
        first  1631, 1632, 1633, 1634, 1635, 1636, 1637, 1638, 1639, 1640, 1641, 1642, 1643
    +href="glossaries-extra-manual.html#dx1-9013" >1710, 1711, 1712, 1713, 1714, 1715, 1716, 1717, 1718, 1719, 1720, 1721, 1722
        firstaccess  1644
    +href="glossaries-extra-manual.html#dx1-35171" >1723
        firstplural  1645, 1646, 1647, 1648, 1649, 1650, 1651, 1652, 1653, 1654
    +href="glossaries-extra-manual.html#dx1-9014" >1724, 1725, 1726, 1727, 1728, 1729, 1730, 1731, 1732, 1733
        group  1655, 1656, 1657, 1658, 1659
    +href="glossaries-extra-manual.html#dx1-42011" >1734, 1735, 1736, 1737, 1738
        location  1660, 1661, 1662, 1663
    +href="glossaries-extra-manual.html#dx1-21023" >1739, 1740, 1741, 1742, 1743
        loclist  1664, 1665, 1666, 1667
    +href="glossaries-extra-manual.html#dx1-45014" >1744, 1745, 1746, 1747
        long  1668, 1669, 1670, 1671, 1672, 1673, 1674, 1675, 1676
    +href="glossaries-extra-manual.html#dx1-12026" >1748, 1749, 1750, 1751, 1752, 1753, 1754, 1755, 1756
        longplural  1677, 1678, 1679, 1680, 1681, 1682
    +href="glossaries-extra-manual.html#dx1-12010" >1757, 1758, 1759, 1760, 1761, 1762
        name  1683, 1684, 1685, 1686, 1687, 1688, 1689, 1690, 1691, 1692, 1693, 1694, 1695, 1696, 1697, 1698, 1699, 1700, 1701, 1702, 1703, 1704, 1705, 1706, 1707, 1708, 1709, 1710, 1711, 1712, 1713, 1714, 1715, 1716, 1717, 1718, 1719, 1720, 1721, 1722, 1723, 1724, 1725, 1726, 1727, 1728, 1729, 1730, 1731, 1732, 1733, 1734, 1735
    +href="glossaries-extra-manual.html#dx1-8034" >1763, 1764, 1765, 1766, 1767, 1768, 1769, 1770, 1771, 1772, 1773, 1774, 1775, 1776, 1777, 1778, 1779, 1780, 1781, 1782, 1783, 1784, 1785, 1786, 1787, 1788, 1789, 1790, 1791, 1792, 1793, 1794, 1795, 1796, 1797, 1798, 1799, 1800, 1801, 1802, 1803, 1804, 1805, 1806, 1807, 1808, 1809, 1810, 1811, 1812, 1813, 1814, 1815, 1816, 1817, 1818, 1819
        nameshortaccess  1736, 1737
    +href="glossaries-extra-manual.html#dx1-35167" >1820, 1821
        parent  1738, 1739, 1740
    +href="glossaries-extra-manual.html#dx1-19085" >1822, 1823, 1824
        plural  1741, 1742, 1743, 1744, 1745, 1746, 1747, 1748, 1749, 1750, 1751, 1752, 1753
    +href="glossaries-extra-manual.html#dx1-9017" >1825, 1826, 1827, 1828, 1829, 1830, 1831, 1832, 1833, 1834, 1835, 1836, 1837
        prefix  1754
    +href="glossaries-extra-manual.html#dx1-15009" >1838
        see  1755, 1756, 1757, 1758, 1759, 1760, 1761, 1762, 1763, 1764, 1765, 1766, 1767, 1768, 1769, 1770, 1771, 1772, 1773, 1774, 1775, 1776, 1777, 1778, 1779, 1780, 1781
    +href="glossaries-extra-manual.html#dx1-4057" >1839, 1840, 1841, 1842, 1843, 1844, 1845, 1846, 1847, 1848, 1849, 1850, 1851, 1852, 1853, 1854, 1855, 1856, 1857, 1858, 1859, 1860, 1861, 1862, 1863, 1864, 1865
        seealso  1782, 1783, 1784, 1785, 1786, 1787, 1788, 1789, 1790, 1791
    +href="glossaries-extra-manual.html#dx1-4058" >1866, 1867, 1868, 1869, 1870, 1871, 1872, 1873, 1874, 1875, 1876
        short  1792, 1793, 1794, 1795, 1796, 1797, 1798, 1799, 1800, 1801, 1802, 1803, 1804, 1805, 1806, 1807
    +href="glossaries-extra-manual.html#dx1-8051" >1877, 1878, 1879, 1880, 1881, 1882, 1883, 1884, 1885, 1886, 1887, 1888, 1889, 1890, 1891, 1892
        shortaccess  1808, 1809, 1810, 1811, 1812, 1813
    +href="glossaries-extra-manual.html#dx1-35133" >1893, 1894, 1895, 1896, 1897
        shortplural  1814, 1815, 1816, 1817, 1818, 1819, 1820, 1821, 1822, 1823, 1824, 1825, 1826, 1827, 1828
    +href="glossaries-extra-manual.html#dx1-12011" >1898, 1899, 1900, 1901, 1902, 1903, 1904, 1905, 1906, 1907, 1908, 1909, 1910, 1911, 1912
        shortpluralaccess  1829, 1830, 1831, 1832
    +href="glossaries-extra-manual.html#dx1-35150" >1913, 1914, 1915, 1916
        sort  1833, 1834, 1835, 1836, 1837, 1838, 1839, 1840, 1841, 1842, 1843, 1844, 1845, 1846, 1847, 1848, 1849, 1850, 1851, 1852
    +href="glossaries-extra-manual.html#dx1-4176" >1917, 1918, 1919, 1920, 1921, 1922, 1923, 1924, 1925, 1926, 1927, 1928, 1929, 1930, 1931, 1932, 1933, 1934, 1935, 1936, 1937, 1938, 1939
        symbol  1853, 1854, 1855, 1856
    - - - +href="glossaries-extra-manual.html#dx1-17013" >1940, 1941, 1942, 1943, 1944, 1945
    +    symbolaccess  1946
        symbolplural  1857, 1858
    +href="glossaries-extra-manual.html#dx1-57037" >1947, 1948
        text  1859, 1860, 1861, 1862, 1863, 1864, 1865, 1866, 1867, 1868, 1869, 1870, 1871, 1872
    +href="glossaries-extra-manual.html#dx1-8033" >1949, 1950, 1951, 1952, 1953, 1954, 1955, 1956, 1957, 1958, 1959, 1960, 1961, 1962, 1963
        textaccess  1873
    +href="glossaries-extra-manual.html#dx1-35168" >1964
        type  1874, 1875, 1876, 1877
    +href="glossaries-extra-manual.html#dx1-14058" >1965, 1966, 1967, 1968
        user1  1878, 1879, 1880
    +href="glossaries-extra-manual.html#dx1-17018" >1969, 1970, 1971, 1972
    number list  1881, 1882, 1883, 1884, 1885, 1886, 1887, 1888, 1889, 1890, 1891, 1892, 1893, 1894, 1895, 1896, 1897, 1898, 1899, 1900, 1901, 1902, 1903, 1904, 1905, 1906, 1907, 1908, 1909, 1910, 1911, 1912, 1913, 1914
    +href="glossaries-extra-manual.html#dx1-4027" >1973, 1974, 1975, 1976, 1977, 1978, 1979, 1980, 1981, 1982, 1983, 1984, 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006
    + + +

    P package options:
        abbreviations  1915, 1916, 1917, 1918, 1919
    +href="glossaries-extra-manual.html#dx1-4191" >2007, 2008, 2009, 2010, 2011
        accsupp  1920, 1921, 1922, 1923, 1924
    +href="glossaries-extra-manual.html#dx1-4035" >2012, 2013, 2014, 2015, 2016, 2017, 2018
        acronym  1925, 1926
    +href="glossaries-extra-manual.html#dx1-4205" >2019, 2020
        acronymlists  1927
    +href="glossaries-extra-manual.html#dx1-4209" >2021, 2022
        acronyms  1928
    +href="glossaries-extra-manual.html#dx1-4221" >2023
        automake  1929, 1930
    +href="glossaries-extra-manual.html#dx1-6040" >2024, 2025
        autoseeindex  1931, 1932
    +href="glossaries-extra-manual.html#dx1-4066" >2026, 2027
            false  1933, 1934
    +href="glossaries-extra-manual.html#dx1-4059" >2028, 2029
        counter
            chapter  1935
    +href="glossaries-extra-manual.html#dx1-4094" >2030
            equation  1936
    +href="glossaries-extra-manual.html#dx1-4097" >2031
            section  1937
    +href="glossaries-extra-manual.html#dx1-4095" >2032
            wrglossary  1938
    +href="glossaries-extra-manual.html#dx1-4130" >2033
        debug  1939
    +href="glossaries-extra-manual.html#dx1-4002" >2034
            all  1940, 1941
    +href="glossaries-extra-manual.html#dx1-4005" >2035, 2036
            showtargets  1942, 1943
    +href="glossaries-extra-manual.html#dx1-4003" >2037, 2038
            showwrgloss  1944, 1945, 1946
    +href="glossaries-extra-manual.html#dx1-4004" >2039, 2040, 2041
            true  1947
    +href="glossaries-extra-manual.html#dx1-4007" >2042
        docdef  1948, 1949, 1950, 1951
    +href="glossaries-extra-manual.html#dx1-4156" >2043, 2044, 2045, 2046
            restricted  1952, 1953, 1954, 1955
    +href="glossaries-extra-manual.html#dx1-4169" >2047, 2048, 2049, 2050
            true  1956, 1957
    +href="glossaries-extra-manual.html#dx1-4187" >2051, 2052
        docdefs  1958, 1959, 1960
    +href="glossaries-extra-manual.html#dx1-51022" >2053, 2054, 2055
            true  1961
    +href="glossaries-extra-manual.html#dx1-4168" >2056
        entrycounter  1962, 1963
    +href="glossaries-extra-manual.html#dx1-49002" >2057, 2058
        equations  1964, 1965
    +href="glossaries-extra-manual.html#dx1-4111" >2059, 2060
            true  1966
    +href="glossaries-extra-manual.html#dx1-4098" >2061
        floats  1967
    +href="glossaries-extra-manual.html#dx1-4118" >2062
        hyperfirst
            false  1968
    +href="glossaries-extra-manual.html#dx1-35030" >2063
        index  1969, 1970, 1971
    +href="glossaries-extra-manual.html#dx1-4227" >2064, 2065, 2066
        indexcounter  1972, 1973, 1974, 1975
    +href="glossaries-extra-manual.html#dx1-4093" >2067, 2068, 2069, 2070
        indexcrossrefs  1976, 1977, 1978, 1979
    +href="glossaries-extra-manual.html#dx1-4056" >2071, 2072, 2073, 2074
            false  1980
    +href="glossaries-extra-manual.html#dx1-4065" >2075
        indexonlyfirst  1981, 1982, 1983, 1984
    +href="glossaries-extra-manual.html#dx1-7004" >2076, 2077, 2078, 2079
        makeindex  1985
    - - - +href="glossaries-extra-manual.html#dx1-45016" >2080
        nogroupskip  1986, 1987, 1988, 1989, 1990, 1991
    +href="glossaries-extra-manual.html#dx1-19014" >2081, 2082, 2083, 2084, 2085
        nomain  1992
    +href="glossaries-extra-manual.html#dx1-3032" >2086
        nomissingglstext  1993
    +href="glossaries-extra-manual.html#dx1-4190" >2087
        nonumberlist  1994, 1995, 1996, 1997, 1998
    +href="glossaries-extra-manual.html#dx1-8058" >2088, 2089, 2090, 2091, 2092
        nopostdot  1999, 2000, 2001, 2002
    +href="glossaries-extra-manual.html#dx1-4022" >2093, 2094, 2095, 2096
            false  2003, 2004, 2005
    +href="glossaries-extra-manual.html#dx1-3004" >2097, 2098, 2099
    + + +         true  2006
    +href="glossaries-extra-manual.html#dx1-3003" >2100
        noredefwarn
            false  2007
    +href="glossaries-extra-manual.html#dx1-3009" >2101
            true  2008
    +href="glossaries-extra-manual.html#dx1-3006" >2102
        notree  2009
    +href="glossaries-extra-manual.html#dx1-19067" >2103
        numbers  2010, 2011, 2012
    +href="glossaries-extra-manual.html#dx1-4216" >2104, 2105, 2106
        postdot  2013, 2014, 2015
    +href="glossaries-extra-manual.html#dx1-3005" >2107, 2108, 2109
        postpunc  2016, 2017, 2018
    +href="glossaries-extra-manual.html#dx1-4018" >2110, 2111, 2112
            comma  2019
    +href="glossaries-extra-manual.html#dx1-4019" >2113
            dot  2020
    +href="glossaries-extra-manual.html#dx1-4020" >2114
            none  2021
    +href="glossaries-extra-manual.html#dx1-4021" >2115
    +    prefix  2116
        record  2022, 2023, 2024, 2025, 2026, 2027, 2028, 2029, 2030, 2031, 2032, 2033, 2034
    +href="glossaries-extra-manual.html#dx1-4064" >2117, 2118, 2119, 2120, 2121, 2122, 2123, 2124, 2125, 2126, 2127, 2128, 2129
            alsoindex  2035, 2036, 2037, 2038, 2039, 2040, 2041
    +href="glossaries-extra-manual.html#dx1-4009" >2130, 2131, 2132, 2133, 2134, 2135, 2136
            nameref  2042, 2043
    +href="glossaries-extra-manual.html#dx1-45001" >2137, 2138
            off  2044, 2045
    +href="glossaries-extra-manual.html#dx1-6035" >2139, 2140
            only  2046, 2047, 2048, 2049, 2050, 2051, 2052, 2053, 2054, 2055, 2056
    +href="glossaries-extra-manual.html#dx1-4069" >2141, 2142, 2143, 2144, 2145, 2146, 2147, 2148, 2149, 2150, 2151
    +    savenumberlist  2152
        section
            chapter  2057
    +href="glossaries-extra-manual.html#dx1-21040" >2153
        seeautonumberlist  2058
    +href="glossaries-extra-manual.html#dx1-8059" >2154
        seenoindex  2059
    +href="glossaries-extra-manual.html#dx1-8016" >2155
            ignore  2060, 2061
    +href="glossaries-extra-manual.html#dx1-8018" >2156, 2157
            warn  2062
    +href="glossaries-extra-manual.html#dx1-51020" >2158
        shortcuts  2063, 2064
    +href="glossaries-extra-manual.html#dx1-4231" >2159, 2160, 2161
            abbr  2065, 2066
    +href="glossaries-extra-manual.html#dx1-4237" >2162, 2163
            abbreviation  2067, 2068
    +href="glossaries-extra-manual.html#dx1-27005" >2164
            abbreviations  2069, 2070
    +href="glossaries-extra-manual.html#dx1-4236" >2165, 2166, 2167
            ac  2071, 2072, 2073, 2074, 2075, 2076
    +href="glossaries-extra-manual.html#dx1-4234" >2168, 2169, 2170, 2171, 2172, 2173, 2174
            acro  2077, 2078
    +href="glossaries-extra-manual.html#dx1-4233" >2175, 2176
            acronyms  2079, 2080
    +href="glossaries-extra-manual.html#dx1-4232" >2177, 2178
            all  2081, 2082
    +href="glossaries-extra-manual.html#dx1-4247" >2179, 2180
            false  2083
    +href="glossaries-extra-manual.html#dx1-4253" >2181
            none  2084
    +href="glossaries-extra-manual.html#dx1-4252" >2182
            other  2085, 2086
    +href="glossaries-extra-manual.html#dx1-4238" >2183, 2184
            true  2087
    +href="glossaries-extra-manual.html#dx1-4248" >2185
        sort
            none  2088, 2089
    +href="glossaries-extra-manual.html#dx1-4089" >2186, 2187
        stylemods  2090, 2091, 2092, 2093, 2094
    +href="glossaries-extra-manual.html#dx1-4045" >2188, 2189, 2190, 2191, 2192, 2193
            all  2095
    +href="glossaries-extra-manual.html#dx1-4048" >2194
            default  2096
    +href="glossaries-extra-manual.html#dx1-4047" >2195
        subentrycounter  2097, 2098
    - - - +href="glossaries-extra-manual.html#dx1-49003" >2196, 2197
        symbols  2099, 2100, 2101
    +href="glossaries-extra-manual.html#dx1-4210" >2198, 2199, 2200
        toc
            false  2102
    +href="glossaries-extra-manual.html#dx1-3002" >2201
            true  2103
    +href="glossaries-extra-manual.html#dx1-3001" >2202
    + + +     translate
            babel  2104
    +href="glossaries-extra-manual.html#dx1-3011" >2203
            true  2105
    +href="glossaries-extra-manual.html#dx1-3013" >2204
        undefaction  2106, 2107
    +href="glossaries-extra-manual.html#dx1-4049" >2205, 2206
            error  2108, 2109, 2110
    +href="glossaries-extra-manual.html#dx1-4050" >2207, 2208, 2209
            warn  2111, 2112, 2113, 2114, 2115, 2116, 2117, 2118, 2119
    +href="glossaries-extra-manual.html#dx1-4051" >2210, 2211, 2212, 2213, 2214, 2215, 2216, 2217, 2218
        xindy  2120, 2121
    +href="glossaries-extra-manual.html#dx1-8080" >2219, 2220
    page (counter)  2122, 2123, 2124, 2125, 2126, 2127
    +href="glossaries-extra-manual.html#dx1-4096" >2221, 2222, 2223, 2224, 2225, 2226
    polyglossia package  2128, 2129
    +href="glossaries-extra-manual.html#dx1-50083" >2227, 2228
    \pretoglossarypreamble  2130
    +href="glossaries-extra-manual.html#dx1-49011" >2229
    \printabbreviations  2131
    +href="glossaries-extra-manual.html#dx1-4195" >2230
    \printglossary options
        label  2132
    +href="glossaries-extra-manual.html#dx1-15011" >2231
        nogroupskip  2133
    +href="glossaries-extra-manual.html#dx1-19015" >2232
        prefix  2134
    +href="glossaries-extra-manual.html#dx1-15008" >2233
        target  2135, 2136
    +href="glossaries-extra-manual.html#dx1-15006" >2234, 2235
        targetnameprefix  2137
    +href="glossaries-extra-manual.html#dx1-15007" >2236
        title  2138
    +href="glossaries-extra-manual.html#dx1-59006" >2237
    \printnoidxglossary options
        sort  2139
    +href="glossaries-extra-manual.html#dx1-51023" >2238
    \printunsrtabbreviations  2140
    +href="glossaries-extra-manual.html#dx1-4197" >2239
    \printunsrtacronyms  2141
    +href="glossaries-extra-manual.html#dx1-4224" >2240
    \printunsrtglossaries  2142
    +href="glossaries-extra-manual.html#dx1-51024" >2241
    \printunsrtglossary  2143
    +href="glossaries-extra-manual.html#dx1-51001" >2242
    \printunsrtglossary*  2144
    +href="glossaries-extra-manual.html#dx1-51005" >2243
    \printunsrtglossaryentryprocesshook  2145
    +href="glossaries-extra-manual.html#dx1-51027" >2244
    \printunsrtglossaryhandler  2146
    +href="glossaries-extra-manual.html#dx1-51030" >2245
    \printunsrtglossarypredoglossary  2147
    +href="glossaries-extra-manual.html#dx1-51029" >2246
    \printunsrtglossaryskipentry  2148
    +href="glossaries-extra-manual.html#dx1-51028" >2247
    \printunsrtglossaryunit  2149
    +href="glossaries-extra-manual.html#dx1-51042" >2248
    \printunsrtglossaryunitsetup  2150
    +href="glossaries-extra-manual.html#dx1-51043" >2249
    \printunsrtindex  2151
    +href="glossaries-extra-manual.html#dx1-4229" >2250
    \printunsrtnumbers  2152
    +href="glossaries-extra-manual.html#dx1-4219" >2251
    \printunsrtsymbols  2153
    +href="glossaries-extra-manual.html#dx1-4214" >2252
    \provideignoredglossary  2154
    +href="glossaries-extra-manual.html#dx1-15003" >2253

    R relsizes package  2155
    +href="glossaries-extra-manual.html#dx1-28052" >2254
    \RestoreAcronyms  2156
    +href="glossaries-extra-manual.html#dx1-14057" >2255
    \rGLS  2157
    +href="glossaries-extra-manual.html#dx1-48013" >2256
    \rGls  2158
    - - - +href="glossaries-extra-manual.html#dx1-48011" >2257
    \rgls  2159
    +href="glossaries-extra-manual.html#dx1-48009" >2258
    \rGLSformat  2160
    +href="glossaries-extra-manual.html#dx1-48029" >2259
    \rGlsformat  2161
    +href="glossaries-extra-manual.html#dx1-48027" >2260
    \rglsformat  2162
    +href="glossaries-extra-manual.html#dx1-48025" >2261
    + + + \rGLSpl  2163
    +href="glossaries-extra-manual.html#dx1-48014" >2262
    \rGlspl  2164
    +href="glossaries-extra-manual.html#dx1-48012" >2263
    \rglspl  2165
    +href="glossaries-extra-manual.html#dx1-48010" >2264
    \rGLSplformat  2166
    +href="glossaries-extra-manual.html#dx1-48030" >2265
    \rGlsplformat  2167
    +href="glossaries-extra-manual.html#dx1-48028" >2266
    \rglsplformat  2168
    +href="glossaries-extra-manual.html#dx1-48026" >2267

    S \seealsoname  2268
    +\setabbreviationstyle  2169
    +href="glossaries-extra-manual.html#dx1-26001" >2269
    slantsc package  2170
    +href="glossaries-extra-manual.html#dx1-34009" >2270
    soul package  2171, 2172
    +href="glossaries-extra-manual.html#dx1-7024" >2271, 2272
    style package  2173
    +href="glossaries-extra-manual.html#dx1-21005" >2273
    subentrycounter package  2174
    +href="glossaries-extra-manual.html#dx1-52021" >2274

    T texindy  2175
    +href="glossaries-extra-manual.html#dx1-39007" >2275
    textcase package  2176
    +href="glossaries-extra-manual.html#dx1-7" >2276
    tracklang package  2177, 2178, 2179, 2180, 2181, 2182, 2183, 2184, 2185, 2186
    +href="glossaries-extra-manual.html#dx1-3" >2277, 2278, 2279, 2280, 2281, 2282, 2283, 2284, 2285, 2286
    translator package  2187
    +href="glossaries-extra-manual.html#dx1-3012" >2287

    U upgreek package  2188, 2189, 2190, 2191
    +href="glossaries-extra-manual.html#dx1-46029" >2288, 2289, 2290, 2291

    W wrglossary (counter)  2192, 2193, 2194, 2195, 2196
    +href="glossaries-extra-manual.html#dx1-4131" >2292, 2293, 2294, 2295, 2296

    X xfor package  2197, 2198, 2199
    +href="glossaries-extra-manual.html#dx1-8" >2297, 2298, 2299
    \xglssetwidest  2200
    +href="glossaries-extra-manual.html#dx1-19071" >2300
    \xglsupdatewidest  2201
    +href="glossaries-extra-manual.html#dx1-19075" >2301
    \xGlsXtrSetField  2202
    +href="glossaries-extra-manual.html#dx1-50026" >2302
    xindy  2203, 2204, 2205, 2206, 2207, 2208, 2209, 2210, 2211, 2212, 2213, 2214, 2215, 2216, 2217, 2218, 2219
    +href="glossaries-extra-manual.html#dx1-3023" >2303, 2304, 2305, 2306, 2307, 2308, 2309, 2310, 2311, 2312, 2313, 2314, 2315, 2316, 2317, 2318, 2319
    xindy  2220
    +href="glossaries-extra-manual.html#dx1-7056" >2320
    xkeyval package  2221
    +href="glossaries-extra-manual.html#dx1-6" >2321

    1.14.21 was originally intended as the last release of glossaries to incorporate new features, but a few new minor features slipped in with some bug fixes in v4.21.

    -

    2.1The descriptionplural key is a throwback to the base package’s original acronym mechanism before the introduction of the long and short keys, where the long form was stored in the description + id="dx1-6026"> field and the short form was stored in the symbol field.

    -

    3.1

    4.1For compatibility with earlier versions, \glsabbrvscfont is defined to \glsxtrscfont is now deprecated. Likewise for similar commands.

    -

    9.1Version 1.11 only allowed one use of \GlsXtrLoadResources per document.

    -

    9.2v1.08 assumed filename.glstex extension was enforced by version 1.11.

    -

    10.1Pre version 1.28 used \csedef#1={\protect\ttfamily#1}|main}} \DeleteShortVerb{\|} \MakeShortVerb{"} - \title{glossaries-extra.sty v1.41: + \title{glossaries-extra.sty v1.42: an extension to the glossaries package} \author{Nicola L.C. Talbot\\[10pt] Dickimaw Books\\ \url{http://www.dickimaw-books.com/}} - \date{2019-04-09} + \date{2020-02-13} \maketitle \begin{abstract} @@ -241,7 +241,7 @@ Some of the features provided by this package are only available with \styfmt{glossaries} version 4.19 (or above). This document assumes familiarity with the \styfmt{glossaries} package. -The file \texttt{example-glossaries-xr.tex} contains dummy +The file \nolinkurl{example-glossaries-xr.tex} contains dummy entries with cross-references that may be used for creating minimal working examples for testing the \styfmt{glossaries-extra} package. (The base \styfmt{glossaries} package provides additional files, @@ -611,9 +611,17 @@ missing. (With \gls{bib2gls} you can instead redefine location prefixes with \texttt{loc-prefix} which will only apply if the entry has a \gls{numberlist}.) -\item[{\pkgoptdef{accsupp}}] Load the \sty{glossaries-accsupp} +\item[{\pkgoptdef{prefix}}] Load the \sty{glossaries-prefix} package (if not already loaded). +\item[{\pkgoptdef{accsupp}}] Load the \sty{glossaries-accsupp} +package (if not already loaded). + +\begin{important} +The \sty{glossaries-accsupp} package is still experimental and so +accessibility features are liable to change. +\end{important} + If you want to define styles that can interface with the accessibility support provided by \sty{glossaries-accsupp} use the \cs{glsaccess\meta{xxx}} type of commands instead of @@ -1009,7 +1017,9 @@ file or files. be cancelled. If used, it will automatically create a new glossary with the label \texttt{abbreviations} and redefines \cs{glsxtrabbrvtype} to this -label. In addition, it defines a shortcut command +label. (The file extensions are \filetype{glg-abr}, +\filetype{gls-abr} and \filetype{glo-abr}.) +In addition, this option defines a shortcut command \begin{definition}[\DescribeMacro\printabbreviations] \cs{printabbreviations}\oarg{options} \end{definition} @@ -1180,6 +1190,8 @@ after \ics{makenoidxglossaries}. \chapter{Modifications to Existing Commands and Styles} \label{sec:modifications} +\section{Defining Entries} + The \styfmt{glossaries} package provides \ics{nopostdesc} which may be used in the \gloskey{description} to suppress the post-description hook. The \styfmt{glossaries-extra} package @@ -1202,95 +1214,10 @@ These commands have no effect outside of the glossary (except with standalone entries that use \cs{glsxtractivatenopost} and \cs{glspostdescription}, see \sectionref{sec:glossentry}). -The \styfmt{glossaries} package provides -\begin{definition}[\DescribeMacro\glsseeitemformat] -\cs{glsseeitemformat}\marg{label} -\end{definition} -to format items in a cross-reference list (identified with the -\gloskey{see} key or \cs{glssee}). This was originally defined to -use \cs{glsentryname}\marg{label} 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 \gloskey{name} field -was sanitized, which used to be the default setting, so -\styfmt{glossaries} v3.0 changed the default definition of this -command to use \cs{glsentrytext} instead. Since the \gloskey{name} -and \gloskey{text} field are quite often the same, this change -usually doesn't have a noticeable effect. However, now that the -\gloskey{name} field is no longer sanitized (following the redesign -of \styfmt{glossaries} v4.0) it makes more sense to restore this -command to its original behaviour, but to take account of -abbreviations \styfmt{glossaries-extra} redefines this as: -\begin{verbatim} -\renewcommand*{\glsseeitemformat}[1]{% - \ifglshasshort{\glslabel}{\glsaccesstext{#1}}{\glsaccessname{#1}}% -} -\end{verbatim} -If you want to restore the \styfmt{glossaries} v3.0+ definition just do: -\begin{verbatim} -\renewcommand*{\glsseeitemformat}[1]{\glsentrytext{#1}} -\end{verbatim} -The \sty{glossaries-extra} package provides \ics{glsxtrhiername} -and its case-changing variants that may be used within -the definition of \cs{glsseeitemformat} if required. These -display the hierarchy for sub-entries rather than just the name, -which may be more helpful in cross-references. See -\sectionref{sec:see} for further details. - The commands used by \styfmt{glossaries} to automatically produce an error if an entry is undefined (such as \ics{glsdoifexists}) are changed to take the \pkgopt{undefaction} option into account. -The \ics{newignoredglossary}\marg{type} command now (as from v1.11) has a starred -version that doesn't automatically switch off the hyperlinks. -This starred version may be used with the \catattr{targeturl} -attribute to create a link to an external URL. (See -\sectionref{sec:categories} for further details.) -As from v1.12 both the starred and unstarred version check -that the glossary doesn't already exist. (The \styfmt{glossaries} -package omits this check.) - -You can now provide an ignored glossary with: -\begin{definition}[\DescribeMacro\provideignoredglossary] -\cs{provideignoredglossary}\marg{type} -\end{definition} -which will only define the glossary if it doesn't already exist. -This also has a starred version that doesn't automatically switch -off hyperlinks. - -The individual glossary displaying commands \ics{printglossary}, -\ics{printnoidxglossary} and \cs{printunsrtglossary} have two extra -keys: - -\begin{itemize} -\item \gloskey[printglossary]{target}. This is a boolean key which can -be used to switch off the automatic hypertarget for each entry. -Unlike \cs{glsdisablehyper} this doesn't switch off hyperlinks, so -any cross-references within the glossary won't be affected. This is -a way of avoiding duplicate target warnings if a glossary needs to -be displayed multiple times. -\item -\gloskey[printglossary]{targetnameprefix}\texttt{=}\marg{prefix}. Another way -of avoiding duplicate target names is to set a prefix -used for the names. Unlike changing \cs{glolinkprefix} this doesn't affect -any hyperlinks (such as those created with \cs{gls}). -\item -\gloskey[printglossary]{prefix}\texttt{=}\marg{prefix}. If you do -actually want to locally change \cs{glolinkprefix}, you can use -the \gloskey{prefix} key instead. You need to use the matching -\gloskey[glslink]{prefix} key in commands like \cs{gls}. - -\item -\gloskey[printglossary]{label}\texttt{=}\marg{label}. Labels -the glossary with \texttt{\cs{label}\marg{label}} and also -defines \cs{@currentlabelname} to the glossary's TOC title -(to provide text for \cs{nameref}). You can also set the -label before the glossary using: -\begin{definition}[\DescribeMacro\glsxtrsetglossarylabel] -\cs{glsxtrsetglossarylabel}\marg{label} -\end{definition} -but take care of duplicate labels if it's not scoped. -\end{itemize} - The \cs{newglossaryentry} command has three new keys: \begin{itemize} \item \gloskey{category}, which sets the category label for the given @@ -1303,11 +1230,14 @@ entry. See \sectionref{sec:alias} for further details. allows for separate \qt{see} and \qt{see also} treatment. See \sectionref{sec:see} for further details. \end{itemize} -The test file \texttt{example-glossaries-xr.tex} contains +This apply to all entry defining commands (such as +\cs{newabbreviation}). + +The test file \nolinkurl{example-glossaries-xr.tex} contains dummy entries with a mixture of \gloskey{see}, \gloskey{alias} and \gloskey{seealso} keys for use with minimal working examples. -There are also \texttt{example-glossaries-*.bib} files that -correspond to each \texttt{example-glossaries-*.tex} file +There are also \nolinkurl{example-glossaries-*.bib} files that +correspond to each \nolinkurl{example-glossaries-*.tex} file for testing \gls{bib2gls}. The \cs{longnewglossaryentry} command now has a starred version @@ -1444,6 +1374,7 @@ equivalent to: \cs{GlsXtrAutoAddOnFormat} is not applied to \cs{glsadd} as it could cause an infinite loop. \end{important} + The \styfmt{glossaries-extra} package provides extra keys for commands like \cs{gls} and \cs{glstext}: \begin{description} @@ -1491,8 +1422,8 @@ which is defined as: } \end{verbatim} This sets the conditional -\begin{definition}[\DescribeMacro\ifglsxtrinitwrglossbefore] -\cs{ifglsxtrinitwrgloss} +\begin{definition} +\ics{ifglsxtrinitwrgloss} \end{definition} which is used to determine where to perform the indexing. @@ -1555,6 +1486,77 @@ hyperlink location (see below). \end{description} +You can set the default options used by \ics{glslink}, \ics{gls} +etc with: +\begin{definition}[\DescribeMacro\GlsXtrSetDefaultGlsOpts] +\cs{GlsXtrSetDefaultGlsOpts}\marg{options} +\end{definition} +For example, if you mostly don't want to index entries then +you can do: +\begin{verbatim} +\GlsXtrSetDefaultGlsOpts{noindex} +\end{verbatim} +and then use, for example, \verb|\gls[noindex=false]{sample}| +when you actually want the location added to the \gls{numberlist}. +These defaults may be overridden by other settings (such as +category attributes) in addition to any settings passed in the +option argument of commands like \cs{glslink} and \cs{gls}. + +Note that if you don't want \emph{any} indexing, just omit +\cs{makeglossaries} and \cs{printglossaries} (or analogous +commands). If you want to adjust the default for +\gloskey[glslink]{wrgloss}, it's better to do this by redefining +\ics{glsxtrinitwrgloss} instead. + +\begin{important} +\cs{GlsXtrSetDefaultGlsOpts} doesn't affect \cs{glsadd}. +\end{important} + +If you want to change the default value of \gloskey[glsadd]{format}, +you can instead use: +\begin{definition}[\GlsXtrSetDefaultNumberFormat] +\cs{GlsXtrSetDefaultNumberFormat}\marg{format} +\end{definition} +This has the advantage of also working for \cs{glsadd}. +For example, if you want all locations in the back matter to appear +in italic (unless explicitly overridden): +\begin{verbatim} +\backmatter +\GlsXtrSetDefaultNumberFormat{hyperit} +\end{verbatim} + +Commands like \ics{gls} have star (\texttt{*}) and plus +(\texttt{+}) modifiers as a short cut for \texttt{hyper=false} +and \texttt{hyper=true}. The \styfmt{glossaries-extra} package +provides a way to add a third modifier, if required, using +\begin{definition}[\DescribeMacro\GlsXtrSetAltModifier] +\cs{GlsXtrSetAltModifier}\marg{char}\marg{options} +\end{definition} +where \meta{char} is the character used as the modifier and +\meta{options} is the default set of options (which may be +overridden). Note that \meta{char} must be a single character +(not a UTF-8 character, unless you are using \XeLaTeX\ or +\LuaLaTeX). + +\begin{important} +When choosing the character \meta{char} take care of any +changes in category code. +\end{important} + +Example: +\begin{verbatim} +\GlsXtrSetAltModifier{!}{noindex} +\end{verbatim} +This means that \verb|\gls!{sample}| will be equivalent to +\verb|\gls[noindex]{sample}|. It's not possible to mix modifiers. +For example, if you want to do +\begin{verbatim} +\gls[noindex,hyper=false]{sample} +\end{verbatim} +you can use \verb|\gls*[noindex]{sample}| or +\verb|\gls![hyper=false]{sample}| but you can't combine the +\texttt{*} and \texttt{!} modifiers. + There is a new hook that's used each time indexing information is written to the external glossary files: \begin{definition}[\DescribeMacro\glsxtrdowrglossaryhook] @@ -1813,7 +1815,44 @@ sub-entries. For example: \renewcommand*{\glsseeitemformat}[1]{\glsxtrhiername{#1}} \end{verbatim} -The command: +The \styfmt{glossaries} package provides +\begin{definition}[\DescribeMacro\glsseeitemformat] +\cs{glsseeitemformat}\marg{label} +\end{definition} +to format items in a cross-reference list (identified with the +\gloskey{see} key or \cs{glssee}). This was originally defined to +use \cs{glsentryname}\marg{label} 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 \gloskey{name} field +was sanitized, which used to be the default setting, so +\styfmt{glossaries} v3.0 changed the default definition of this +command to use \cs{glsentrytext} instead. Since the \gloskey{name} +and \gloskey{text} field are quite often the same, this change +usually doesn't have a noticeable effect. However, now that the +\gloskey{name} field is no longer sanitized (following the redesign +of \styfmt{glossaries} v4.0) it makes more sense to restore this +command to its original behaviour, but to take account of +abbreviations \styfmt{glossaries-extra} redefines this as: +\begin{verbatim} +\renewcommand*{\glsseeitemformat}[1]{% + \ifglshasshort{\glslabel}{\glsfmttext{#1}}{\glsfmtname{#1}}% +} +\end{verbatim} +(Note that as from \styfmt{glossaries-extra} version 1.42, this now +uses \cs{glsfmttext} and \cs{glsfmtname} instead of just referencing +the \gloskey{text} and \gloskey{name} fields. This helps to ensure +that any formatting is correctly applied.) + +If you want to restore the \styfmt{glossaries} v3.0+ definition just do: +\begin{verbatim} +\renewcommand*{\glsseeitemformat}[1]{\glsentrytext{#1}} +\end{verbatim} + +The \sty{glossaries-extra} package provides \ics{glsxtrhiername} +and its case-changing variants that may be used within +the definition of \cs{glsseeitemformat} if required. These +display the hierarchy for sub-entries rather than just the name, +which may be more helpful in cross-references. \begin{definition}[\DescribeMacro\glsxtrhiername] \cs{glsxtrhiername}\marg{label} \end{definition} @@ -1824,8 +1863,8 @@ performs a recursive action: \cs{glsxtrhiernamesep} then: \item If the entry given by \meta{label} is an abbreviation (that is, it has the \gloskey{short} field set) then -the short form is displayed (using \cs{glsaccessshort}) -otherwise the name is displayed (using \cs{glsaccessname}). +the short form is displayed (using \cs{glsfmtshort}) +otherwise the name is displayed (using \cs{glsfmtname}). \end{enumerate} The first step above is skipped if the entry doesn't have a parent. Each level is separated by: @@ -1840,27 +1879,27 @@ There are some case-changing variants: \cs{Glsxtrhiername}\marg{label} \end{definition} The top-level has the first letter changed to upper case -(either \cs{Glsaccessshort} or \cs{Glsaccessname}). There's +(either \cs{Glsfmtshort} or \cs{Glsfmtname}). There's no case-change for sub-entries. \begin{definition}[\DescribeMacro\GlsXtrhiername] \cs{GlsXtrhiername}\marg{label} \end{definition} All levels have the first letter changed to upper case -(either \cs{Glsaccessshort} or \cs{Glsaccessname}). +(either \cs{Glsfmtshort} or \cs{Glsfmtname}). \begin{definition}[\DescribeMacro\GLSxtrhiername] \cs{GLSxtrhiername}\marg{label} \end{definition} The top-level is converted to upper case -(either \cs{GLSaccessshort} or \cs{GLSaccessname}). There's +(either \cs{GLSfmtshort} or \cs{GLSfmtname}). There's no case-change for sub-entries. \begin{definition}[\DescribeMacro\GLSXTRhiername] \cs{GLSXTRhiername}\marg{label} \end{definition} All levels are converted to upper case -(either \cs{GLSaccessshort} or \cs{GLSaccessname}). +(either \cs{GLSfmtshort} or \cs{GLSfmtname}). Suppose you want to suppress the \gls*{numberlist} using \pkgopt{nonumberlist}. This will automatically prevent the @@ -1912,6 +1951,13 @@ For example: } \end{verbatim} +The \gloskey{alias} key only contains a single label not a list, but +if you want to ensure consistent formatting with \cs{glsxtrusesee} +and \cs{glsxtruseseealso} you can use (from v1.42): +\begin{definition}[\DescribeMacro\glsxtrusealias] +\cs{glsxtrusealias}\marg{label} +\end{definition} + The actual unformatted comma-separated list \meta{xr-list} stored in the \gloskey{seealso} field can be accessed with: \begin{definition}[\DescribeMacro\glsxtrseealsolabels] @@ -1946,6 +1992,21 @@ unless the \pkgopt{xindy} option is used with \sty{glossaries} v4.30+, in which case a distinct \texttt{seealso} cross-reference class is used instead. +The command that produces this \qt{see also} text is +\begin{definition}[\DescribeMacro\seealsoname] +\cs{seealsoname} +\end{definition} +If \ics{alsoname} (provided by language packages) is defined then +\cs{seealsoname} will simply be defined to \cs{alsoname} otherwise +it will be defined to \texttt{see also}. + +The language-sensitive \cs{alsoname} is used by general indexing +packages, such as \sty{makeidx}, so if you redefine \cs{alsoname} +the change will apply to normal indexes as well as glossaries. If +you only want to change the text produced by the \gloskey{seealso} +key without affecting general indexing (with \cs{index}) then +redefine \cs{seealsoname} instead. + \section{Entry Display Style Modifications} \label{sec:entryfmtmods} @@ -1959,8 +2020,9 @@ depends on the command used (such as \cs{gls}) and the entry format. The default entry format (\ics{glsentryfmt}) used in the \gls{linktext} by commands like \ics{gls}, \ics{glsxtrfull}, \ics{glsxtrshort} and \ics{glsxtrlong} (but not commands like -\ics{glslink}, \ics{glsfirst} and \cs{glstext}) is changed by \styfmt{glossaries-extra} to test for -regular entries, which are determined as follows: +\ics{glslink}, \ics{glsfirst} and \cs{glstext}) is changed by +\styfmt{glossaries-extra} to test for regular entries, which are +determined as follows: \begin{itemize} \item If an entry is assigned to a category that has the @@ -2178,167 +2240,32 @@ The \abbrstyle{short-postfootnote} abbreviation style uses the post-\gls{linktext} hook to place the footnote after trailing punctuation characters. -You can set the default options used by \ics{glslink}, \ics{gls} -etc with: -\begin{definition}[\DescribeMacro\GlsXtrSetDefaultGlsOpts] -\cs{GlsXtrSetDefaultGlsOpts}\marg{options} -\end{definition} -For example, if you mostly don't want to index entries then -you can do: -\begin{verbatim} -\GlsXtrSetDefaultGlsOpts{noindex} -\end{verbatim} -and then use, for example, \verb|\gls[noindex=false]{sample}| -when you actually want the location added to the \gls{numberlist}. -These defaults may be overridden by other settings (such as -category attributes) in addition to any settings passed in the -option argument of commands like \cs{glslink} and \cs{gls}. -Note that if you don't want \emph{any} indexing, just omit -\cs{makeglossaries} and \cs{printglossaries} (or analogous -commands). If you want to adjust the default for -\gloskey[glslink]{wrgloss}, it's better to do this by redefining -\ics{glsxtrinitwrgloss} instead. +\section{Entry Counting Modifications} +\label{sec:entrycountmods} -\begin{important} -\cs{GlsXtrSetDefaultGlsOpts} doesn't affect \cs{glsadd}. -\end{important} +If you are using \gls{bib2gls} you may find it more convenient +to use the record count commands described in +\sectionref{sec:bib2gls} instead. -If you want to change the default value of \gloskey[glsadd]{format}, -you can instead use: -\begin{definition}[\GlsXtrSetDefaultNumberFormat] -\cs{GlsXtrSetDefaultNumberFormat}\marg{format} -\end{definition} -This has the advantage of also working for \cs{glsadd}. -For example, if you want all locations in the back matter to appear -in italic (unless explicitly overridden): +The \ics{glsenableentrycount} command is modified to allow +for the \catattr{entrycount} attribute. This means that +you not only need to enable entry counting with +\cs{glsenableentrycount}, but you also need +to set the appropriate attribute (see \sectionref{sec:categories}). + +For example, instead of just doing: \begin{verbatim} -\backmatter -\GlsXtrSetDefaultNumberFormat{hyperit} +\glsenableentrycount +\end{verbatim} +you now need to do: +\begin{verbatim} +\glsenableentrycount +\glssetcategoryattribute{abbreviation}{entrycount}{1} \end{verbatim} - -Commands like \ics{gls} have star (\texttt{*}) and plus -(\texttt{+}) modifiers as a short cut for \texttt{hyper=false} -and \texttt{hyper=true}. The \styfmt{glossaries-extra} package -provides a way to add a third modifier, if required, using -\begin{definition}[\DescribeMacro\GlsXtrSetAltModifier] -\cs{GlsXtrSetAltModifier}\marg{char}\marg{options} -\end{definition} -where \meta{char} is the character used as the modifier and -\meta{options} is the default set of options (which may be -overridden). Note that \meta{char} must be a single character -(not a UTF-8 character, unless you are using \XeLaTeX\ or -\LuaLaTeX). - -\begin{important} -When choosing the character \meta{char} take care of any -changes in category code. -\end{important} - -Example: -\begin{verbatim} -\GlsXtrSetAltModifier{!}{noindex} -\end{verbatim} -This means that \verb|\gls!{sample}| will be equivalent to -\verb|\gls[noindex]{sample}|. It's not possible to mix modifiers. -For example, if you want to do -\begin{verbatim} -\gls[noindex,hyper=false]{sample} -\end{verbatim} -you can use \verb|\gls*[noindex]{sample}| or -\verb|\gls![hyper=false]{sample}| but you can't combine the -\texttt{*} and \texttt{!} modifiers. - -\Glspl{locationlist} displayed with \cs{printnoidxglossary} -internally use -\begin{definition}[\DescribeMacro\glsnoidxdisplayloc] -\cs{glsnoidxdisplayloc}\marg{prefix}\marg{counter}\marg{format}\marg{location} -\end{definition} -This command is provided by \styfmt{glossaries}, but is modified by -\styfmt{glossaries-extra} to check for the start and end range -formation identifiers \verb|(| and \verb|)| which are discarded to -obtain the actual control sequence name that forms the location -formatting command. - -If the range identifiers aren't present, this just uses -\begin{definition}[\DescribeMacro\glsxtrdisplaysingleloc] -\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location} -\end{definition} -otherwise it uses -\begin{definition}[\DescribeMacro\glsxtrdisplaystartloc] -\cs{glsxtrdisplaystartloc}\marg{format}\marg{location} -\end{definition} -for the start of a range (where the identifier has been stripped -from \meta{format}) or -\begin{definition}[\DescribeMacro\glsxtrdisplayendloc] -\cs{glsxtrdisplayendloc}\marg{format}\marg{location} -\end{definition} -for the end of a range (where the identifier has been stripped -from \meta{format}). - -By default the start range command saves the format in -\begin{definition}[\DescribeMacro\glsxtrlocrangefmt] -\cs{glsxtrlocrangefmt} -\end{definition} -and does -\begin{display} -\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location} -\end{display} -(If the format is empty, it will be replaced with -\texttt{glsnumberformat}.) - -The end command checks that the format matches the start of the -range, does -\begin{definition}[\DescribeMacro\glsxtrdisplayendlochook] -\cs{glsxtrdisplayendlochook}\marg{format}\marg{location} -\end{definition} -(which does nothing by default), followed by -\begin{display} -\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location} -\end{display} -and then sets \cs{glsxtrlocrangefmt} to empty. - -This means that the list -\begin{verbatim} -\glsnoidxdisplayloc{}{page}{(textbf}{1}, -\glsnoidxdisplayloc{}{page}{textbf}{1}, -\glsnoidxdisplayloc{}{page}{)textbf}{1}. -\end{verbatim} -doesn't display any differently from -\begin{verbatim} -\glsnoidxdisplayloc{}{page}{textbf}{1}, -\glsnoidxdisplayloc{}{page}{textbf}{1}, -\glsnoidxdisplayloc{}{page}{textbf}{1}. -\end{verbatim} -but it does make it easier to define your own custom list handler -that can accommodate the ranges. - - -\section{Entry Counting Modifications} -\label{sec:entrycountmods} - -If you are using \gls{bib2gls} you may find it more convenient -to use the record count commands described in -\sectionref{sec:bib2gls} instead. - -The \ics{glsenableentrycount} command is modified to allow -for the \catattr{entrycount} attribute. This means that -you not only need to enable entry counting with -\cs{glsenableentrycount}, but you also need -to set the appropriate attribute (see \sectionref{sec:categories}). - -For example, instead of just doing: -\begin{verbatim} -\glsenableentrycount -\end{verbatim} -you now need to do: -\begin{verbatim} -\glsenableentrycount -\glssetcategoryattribute{abbreviation}{entrycount}{1} -\end{verbatim} -This will enable the entry counting for entries in the -\category{abbreviation} category, but any entries assigned to -other categories will be unchanged. +This will enable the entry counting for entries in the +\category{abbreviation} category, but any entries assigned to +other categories will be unchanged. Further information about entry counting, including the new per-unit feature, is described in \sectionref{sec:entrycount}. @@ -2457,6 +2384,12 @@ where \meta{cs} is a control sequence that takes a single argument (which is the entry label). This is best used with the starred version \cs{GlsXtrStartUnsetBuffering*} to avoid duplicates. +You can discard the buffer and restore \cs{glsunset} to its normal +behaviour with (new to v1.42): +\begin{definition}[\DescribeMacro\GlsXtrDiscardUnsetBuffering] +\cs{GlsXtrDiscardUnsetBuffering} +\end{definition} + \begin{important} Note that since the change in the first use flag now doesn't occur until \cs{GlsXtrStopUnsetBuffering}, multiple references @@ -2995,7 +2928,16 @@ The simplest way to update a document that uses \begin{verbatim} \setabbreviationstyle[acronym]{long-short} \end{verbatim} -before you define any entries. +before you define any entries. If you have used commands like +\ics{acrshort}, \ics{acrlong} and \ics{acrfull}, you need to +substitute them with \ics{glsxtrshort}, \ics{glsxtrlong} and +\ics{glsxtrfull}. (This includes plural and case-changing forms.) +Your text editor's search and replace function should help with +this. If you have used the \pkgopt{shortcuts} package option then +use \pkgopt[ac]{shortcuts} in order to continue using the shortcut +commands like \ics{ac}. With this setting, \ics{acs} will use +\ics{glsxtrshort} instead of \ics{acrshort} etc. + For example, the following document using just \styfmt{glossaries} \begin{verbatim} \documentclass{article} @@ -3129,1587 +3071,1775 @@ is redefined to use the subsequent use abbreviation font command \ics{glsabbrvfont}. This will be reset if you use \cs{RestoreAcronyms}. -\section{\styfmt{glossary-bookindex} package} -\label{sec:bookindex} +\section{Glossaries} -As from v1.21, \styfmt{glossaries-extra} has a new supplementary -package \sty{glossary-bookindex} which provides the glossary style -\glostyle{bookindex}. This is very similar to the -\glostyle{mcolindexgroup} style but is designed for indexes, so by -default only the name and location list are displayed. You can -either load this package explicitly and then set the style: -\begin{verbatim} -\usepackage{glossaries-extra} -\usepackage{glossary-bookindex} -\setglossarystyle{bookindex} -\end{verbatim} -or use both the \pkgopt{stylemods} and \sty{style} options: -\begin{verbatim} -\usepackage[stylemods=bookindex,style=bookindex]{glossaries-extra} -\end{verbatim} -The \glostyle{bookindex} style only supports a maximum -hierarchical level of 2 (top-level, level~1 and level~2). It's -primarily designed for use with \gls{bib2gls}. It may be used with -other indexing options, but some features may not be present and -UTF-8 characters may cause a problem with non-Unicode engines in -letter group headings or PDF bookmarks. (\gls{bib2gls} uses numeric -identifies by default to avoid these problems. If numbers show up in -the group headings instead of the appropriate characters, check that -you have used the \pkgopt{record} package option.) +The \ics{newignoredglossary}\marg{type} command now (as from v1.11) has a starred +version that doesn't automatically switch off the hyperlinks. +This starred version may be used with the \catattr{targeturl} +attribute to create a link to an external URL. (See +\sectionref{sec:categories} for further details.) +As from v1.12 both the starred and unstarred version check +that the glossary doesn't already exist. (The \styfmt{glossaries} +package omits this check.) -The number of columns is given by -\begin{definition}[\DescribeMacro\glsxtrbookindexcols] -\cs{glsxtrbookindexcols} +You can now provide an ignored glossary with: +\begin{definition}[\DescribeMacro\provideignoredglossary] +\cs{provideignoredglossary}\marg{type} \end{definition} -which defaults to 2. +which will only define the glossary if it doesn't already exist. +This also has a starred version that doesn't automatically switch +off hyperlinks. -This style uses the \env{multicols} environment. If -the command -\begin{definition}[\DescribeMacro\glsxtrbookindexcolspread] -\cs{glsxtrbookindexcolspread} +The individual glossary displaying commands \ics{printglossary}, +\ics{printnoidxglossary} and \cs{printunsrtglossary} have extra +keys: + +\begin{itemize} +\item \gloskey[printglossary]{target}. This is a boolean key which can +be used to switch off the automatic hypertarget for each entry. +Unlike \cs{glsdisablehyper} this doesn't switch off hyperlinks, so +any cross-references within the glossary won't be affected. This is +a way of avoiding duplicate target warnings if a glossary needs to +be displayed multiple times. +\item +\gloskey[printglossary]{targetnameprefix}\texttt{=}\marg{prefix}. Another way +of avoiding duplicate target names is to set a prefix +used for the names. Unlike changing \cs{glolinkprefix} this doesn't affect +any hyperlinks (such as those created with \cs{gls}). +\item +\gloskey[printglossary]{prefix}\texttt{=}\marg{prefix}. If you do +actually want to locally change \cs{glolinkprefix}, you can use +the \gloskey{prefix} key instead. You need to use the matching +\gloskey[glslink]{prefix} key in commands like \cs{gls}. + +\item +\gloskey[printglossary]{label}\texttt{=}\marg{label}. Labels +the glossary with \texttt{\cs{label}\marg{label}} and also +defines \cs{@currentlabelname} to the glossary's TOC title +(to provide text for \cs{nameref}). You can also set the +label before the glossary using: +\begin{definition}[\DescribeMacro\glsxtrsetglossarylabel] +\cs{glsxtrsetglossarylabel}\marg{label} \end{definition} -isn't empty then it's supplied as the optional argument -following \verb|\begin{multicols}|\marg{n}. You can switch from -\env{multicols} to \env{multicols*} by redefining -\begin{definition}[\DescribeMacro\glsxtrbookindexmulticolsenv] -\cs{glsxtrbookindexmulticolsenv} +but take care of duplicate labels if it's not scoped. +\end{itemize} + +\subsection{Glossary Style Modifications} +\label{sec:glosstylemods} + +The \sty{glossaries-extra-stylemods} package (more conveniently +loaded through the \styfmt{glossaries-extra} +\pkgopt{stylemods} option) modifies some of the predefined +styles that are provided with the \styfmt{glossaries} package. +These modifications are described in more detail in +\sectionref{sec:stylemods}. + +The \sty{glossaries} package tries to determine the group +title from its label by first checking if +\cs{}\meta{label}\texttt{groupname} exists. If it doesn't exist, +then the title is assumed to be the same as the label. +For example, when typesetting the \qt{A} letter group, +\sty{glossaries} first checks if \cs{Agroupname} exists. +This could potentially cause conflict with another package +that may have some other meaning for \cs{Agroupname}, so +\sty{glossaries-extra} first checks for the existence +of the internal command \cs{glsxtr@grouptitle@}\meta{label} +which shouldn't clash with another package. You can set the +group title using +\begin{definition}[\DescribeMacro\glsxtrsetgrouptitle] +\cs{glsxtrsetgrouptitle}\marg{label}\marg{title} \end{definition} -For example +For example: \begin{verbatim} -\renewcommand{\glsxtrbookindexmulticolsenv}{multicols*} +\glsxtrsetgrouptitle{A}{A (a)} \end{verbatim} +This uses a global assignment. If you need to scope the change +you can use +\begin{definition}[\DescribeMacro\glsxtrlocalsetgrouptitle] +\cs{glsxtrlocalsetgrouptitle}\marg{label}\marg{title} +\end{definition} -Each top-level entry is displayed using -\begin{definition}[\DescribeMacro\glsxtrbookindexname] -\cs{glsxtrbookindexname}\marg{label} +\subsubsection{Style Hooks} +\label{sec:stylehooks} + +The commands \ics{glossentryname} and \ics{glossentrydesc} are +modified to take into account the \catattr{glossname}, +\category{glossnamefont}, \catattr{glossdesc} and \catattr{glossdescfont} +attributes (see \sectionref{sec:categories}). This means you can +make simple font or case-changing modifications to the name and description +without defining a new glossary style. + +(New to version 1.42.) +The command \ics{glossentrysymbol} is modified to take into account +the \catattr{glosssymbolfont}. Note that, unlike the above, there's +no corresponding attribute to change the case as it's usually not +appropriate to change the case of a symbol (and for some symbols, +such as pictographs, there's no concept of case). If +\ics{texorpdfstring} has been defined \ics{glossentrysymbol} will +be defined to do: +\begin{alltt} +\ics{texorpdfstring}\marg{\TeX\ code}\marg{PDF} +\end{alltt} +The \meta{\TeX\ code} part is robust and deals with the actual +typesetting of the symbol. The \meta{PDF} part is simply: +\begin{definition}[\DescribeMacro\glsentrypdfsymbol] +\cs{glsentrypdfsymbol}\marg{label} \end{definition} -where the entry is identified by \meta{label}. This just -does \cs{glossentryname}\marg{label} by default. -For example, if you want the symbol to be included: +which is defined to just do \cs{glsentrysymbol}\marg{label}. The +chances are that the code in the \gloskey{symbol} key won't be valid +in the PDF bookmarks, so you can redefine \cs{glsentrypdfsymbol} to +use a more appropriate field. (If you do redefine this command, +remember that it needs to fully expand.) + +For example, if you are using \sty{glossaries-accsupp}, you could +use the \gloskey{symbolaccess} field: \begin{verbatim} -\renewcommand*{\glsxtrbookindexname}[1]{% - \glossentryname{#1}% - \ifglshassymbol{#1}{\space (\glossentrysymbol{#1})}{}% -} +\renewcommand{\glsentrypdfsymbol}[1]{\glsentrysymbolaccess{#1}} \end{verbatim} -or if you want the description (if set): +Alternatively, if you are using \gls{bib2gls} you can use the \TeX\ +parser library to interpret a copy of the \gloskey{symbol} field and +use that. For example, with the resource options: \begin{verbatim} -\renewcommand*{\glsxtrbookindexname}[1]{% - \glossentryname{#1}% - \ifglshasdesc{#1}{\space \glossentrydesc{#1}\glspostdescription}{}% -} + replicate-fields={symbol=user1}, + interpret-fields={user1} \end{verbatim} -(which picks up the post-description hook). - -Alternatively you can use the \cs{glsxtrpostname\meta{category}} -hook to append information after the name according to the entry's -category. - -Sub-entries are displayed using -\begin{definition}[\DescribeMacro\glsxtrbookindexsubname] -\cs{glsxtrbookindexsubname}\marg{label} -\end{definition} -which just defaults to \cs{glsxtrbookindexname}\marg{label}. - -The separator used before the location list for top-level -entries is given by -\begin{definition}[\DescribeMacro\glsxtrbookindexprelocation] -\cs{glsxtrbookindexprelocation}\marg{label} -\end{definition} -where \meta{label} is the entry's label. This checks if -the \texttt{location} field has been set. If it has, it -does +This stores the interpreted value of the symbol in the +\gloskey{user1} field, so you can then do: \begin{verbatim} -,\glsxtrprelocation +\renewcommand{\glsentrypdfsymbol}[1]{\glsentryuseri{#1}} \end{verbatim} -otherwise it just does \cs{glsxtrprelocation} (which defaults -to \cs{space}). If you're not using -\gls{bib2gls}, the \gloskey{location} field won't be set. +(You may need \XeLaTeX\ or \LuaLaTeX\ with this method.) This allows +\cs{glossentrysymbol} to be used in a section heading with +standalone definitions. -The separator used before the -location list for sub-entries is given by -\begin{definition}[\DescribeMacro\glsxtrbookindexsubprelocation] -\cs{glsxtrbookindexsubprelocation}\marg{label} +If you want to adapt a style to use another field instead +of \gloskey{name}, you can use +\begin{definition}[\DescribeMacro\glossentrynameother] +\cs{glossentrynameother}\marg{label}\marg{field} \end{definition} -which defaults to \cs{glsxtrbookindexprelocation}\marg{label}. +This behaves just like \cs{glossentryname} (that is, it obeys +\catattr{glossname}, \catattr{glossnamefont} or \cs{glsnamefont} and uses the post-name +hook) but it uses the given \meta{field} instead of \gloskey{name}. +The \meta{field} argument must be the internal field name +(for example \texttt{desc} rather than \texttt{description}). +See the key to field mappings table in the \styfmt{glossaries} +user manual. -The actual location list is encapsulated with: -\begin{definition}[\DescribeMacro\glsxtrbookindexlocation] -\cs{glsxtrbookindexlocation}\marg{label}\marg{location list} +There is a hook after \ics{glossentryname} and +\ics{Glossentryname}: +\begin{definition}[\DescribeMacro\glsxtrpostnamehook] +\cs{glsxtrpostnamehook}\marg{label} \end{definition} -for top-level entries and -\begin{definition}[\DescribeMacro\glsxtrbookindexsublocation] -\cs{glsxtrbookindexsublocation}\marg{label}\marg{location list} +By default this checks the \catattr{indexname} attribute. +If the attribute exists for the category to which the label belongs, +then the name is automatically indexed using +\begin{definition} +\ics{glsxtrdoautoindexname}\marg{label}\texttt{\{indexname\}} \end{definition} -for sub-entries. These both just do \meta{location list} by default. +See \sectionref{sec:autoindex} for further details. -The separator used between a top-level parent and child entry is -given by -\begin{definition}[\DescribeMacro\glsxtrbookindexparentchildsep] -\cs{glsxtrbookindexparentchildsep} +\begin{sloppypar} +As from version 1.04, the post-name hook \cs{glsxtrpostnamehook} +will also use \cs{glsxtrpostname}\meta{category} if it exists. +You can use \ics{glscurrententrylabel} to obtain the entry label +with the definition of this command. For example, suppose you are +using a glossary style the doesn't display the symbol, you can +insert the symbol after the name for a particular category, say, +the \qt{symbol} category: +\end{sloppypar} +\begin{verbatim} +\newcommand*{\glsxtrpostnamesymbol}{\space + (\glsentrysymbol{\glscurrententrylabel})} +\end{verbatim} +For convenience, as from v1.31, you can use +\begin{definition}[\DescribeMacro\glsdefpostname] +\cs{glsdefpostname}\marg{category}\marg{definition} \end{definition} -This defaults to \cs{nopagebreak}. +This is simply a shortcut for: +\begin{alltt} +\cs{csdef}\{glsxtrpostname\meta{category}\}\marg{definition} +\end{alltt} +Note that it doesn't check if the command has already been defined. -The separator used between a sub-level parent and child entry is -given by -\begin{definition}[\DescribeMacro\glsxtrbookindexparentsubchildsep] -\cs{glsxtrbookindexparentsubchildsep} +As from version 1.25, the post-name hook also does +\begin{definition}[\DescribeMacro\glsextrapostnamehook] +\cs{glsextrapostnamehook}\marg{label} \end{definition} -This defaults to \cs{glsxtrbookindexparentchildsep}. +(before \cs{glsxtrpostname}\meta{category}) +to allow for additional non-category related code. This does nothing +by default. -The separator between top-level entries is given by -\begin{definition}[\DescribeMacro\glsxtrbookindexbetween] -\cs{glsxtrbookindexbetween}\marg{label1}\marg{label2} +The post-description code used within the glossary is modified so +that it also does +\begin{definition}[\DescribeMacro\glsxtrpostdescription] +\cs{glsxtrpostdescription} \end{definition} -This comes after the entry given by \meta{label1}, if the entry -has no children, or after the last descendent otherwise, -so it always comes immediately before the entry given -by \meta{label2} unless the entry occurs at the start of -a group. This does nothing by default. +This occurs before the original \cs{glspostdescription}, so if the +\pkgopt[false]{nopostdot} option is used, it will be inserted before +the terminating full stop. -The separator between two level~1 entries is given by -\begin{definition}[\DescribeMacro\glsxtrbookindexsubbetween] -\cs{glsxtrbookindexsubbetween}\marg{label1}\marg{label2} +This new command will do \cs{glsxtrpostdesc\meta{category}} +if it exists, where \meta{category} is the category label associated +with the current entry. For example \cs{glsxtrpostdescgeneral} +for entries with the category set to \category{general} +or \cs{glsxtrpostdescacronym} for entries with the category set to +\category{acronym}. +For convenience, as from v1.31, you can use +\begin{definition}[\DescribeMacro\glsdefpostdesc] +\cs{glsdefpostdesc}\marg{category}\marg{definition} \end{definition} +This is simply a shortcut for: +\begin{alltt} +\cs{csdef}\{glsxtrpostdesc\meta{category}\}\marg{definition} +\end{alltt} +Note that it doesn't check if the command has already been defined. -The separator between two level~2 entries is given by -\begin{definition}[\DescribeMacro\glsxtrbookindexsubsubbetween] -\cs{glsxtrbookindexsubsubbetween}\marg{label1}\marg{label2} -\end{definition} -At the end of each letter group, the following hooks -are done in order: -\begin{definition}[\DescribeMacro\glsxtrbookindexsubsubatendgroup] -\cs{glsxtrbookindexsubsubatendgroup}\marg{sub-sub-label} -\end{definition} -\begin{definition}[\DescribeMacro\glsxtrbookindexsubatendgroup] -\cs{glsxtrbookindexsubatendgroup}\marg{sub-label} -\end{definition} -\begin{definition}[\DescribeMacro\glsxtrbookindexatendgroup] -\cs{glsxtrbookindexatendgroup}\marg{label} +Since both \cs{glossentry} and \cs{subglossentry} set +\begin{definition}[\DescribeMacro\glscurrententrylabel] +\cs{glscurrententrylabel} \end{definition} -where \meta{sub-sub-label} is the label of the last -level~2 entry, \meta{sub-label} is the label of the last -level~1 entry and \meta{label} is the label of the last -level~0 entry. +to the label for the current entry, you can use this within the +definition of these post-description hooks if you need to reference +the label. -For example, the resource option \texttt{seealso=omit} -instructs \gls{bib2gls} to omit the \texttt{seealso} cross-reference -from the location list. (The \texttt{see} cross-reference -will still be added unless you also have \texttt{see=omit}.) -The \texttt{seealso} cross-reference can instead be appended after -the child entries using: +For example, suppose you want to insert the plural form in brackets +after the description in the glossary, but only for entries in the +\category{general} category, then you could do: \begin{verbatim} -\renewcommand{\glsxtrbookindexatendgroup}[1]{% - \glsxtrifhasfield{seealso}{#1}{\glstreesubitem\glsxtruseseealso{#1}}{}% -} -\renewcommand{\glsxtrbookindexbetween}[2]{% - \glsxtrbookindexatendgroup{#1}% -}% +\renewcommand{\glsxtrpostdescgeneral}{\space + (plural: \glsentryplural{\glscurrententrylabel})} +\end{verbatim} +This means you don't have to define a custom glossary style, which +you may find more complicated. (It also allows more flexibility if +you decide to change the underlying glossary style.) -\renewcommand{\glsxtrbookindexsubatendgroup}[1]{% - \glsxtrifhasfield{seealso}{#1}{\glstreesubsubitem\glsxtruseseealso{#1}}{}% -} +\begin{important} +This feature can't be used for glossary styles that ignore +\cs{glspostdescription} or if you redefine +\cs{glspostdescription} without including \cs{glsxtrpostdescription}. +(For example, if you redefine \cs{glspostdescription} to do +nothing instead of using the \pkgopt{nopostdot} option to suppress +the terminating full stop.) See \sectionref{sec:stylemods} to patch +the predefined styles provided by \styfmt{glossaries} that are missing +\cs{glspostdescription}. +\end{important} -\renewcommand{\glsxtrbookindexsubbetween}[2]{% - \glsxtrbookindexsubatendgroup{#1}% -} +\subsubsection{Number List} +\label{sec:glosstylenumlist} -\renewcommand{\glsxtrbookindexsubsubatendgroup}[1]{% - \glsxtrifhasfield{seealso}{#1}% - {\glstreeitem\hspace*{40pt}\glsxtruseseealso{#1}}{}% -} +The \gls{numberlist} is now placed inside the argument of +\begin{definition}[\DescribeMacro\GlsXtrFormatLocationList] +\cs{GlsXtrFormatLocationList}\marg{number list} +\end{definition} +This is internally used by \cs{glossaryentrynumbers}. The +\pkgopt{nonumberlist} option redefines \cs{glossaryentrynumbers} so that it +doesn't display the \gls{numberlist}, but it still saves the +\gls{numberlist} in case it's required. -\renewcommand{\glsxtrbookindexsubsubbetween}[2]{% - \glsxtrbookindexsubsubatendgroup{#1}% -} -\end{verbatim} -This uses \cs{glstreesubitem} and \cs{glstreesubsubitem} -to indent the cross-reference according to the next level down, -so the cross-reference for a top-level entry is aligned with -the sub-entries, and a level~1 entry has its cross-reference -aligned with sub-sub-entries. In the event that a level~2 -entry has a cross-reference, this is indented a bit further -(but it won't be aligned with any deeper level as the -\glostyle{bookindex} style only supports a maximum of two -sub-levels). +\begin{important} +If you want to suppress the \gls{numberlist} always use the +\pkgopt{nonumberlist} option instead of redefining +\cs{glossaryentrynumbers} to do nothing. +\end{important} -The \glostyle{bookindex} style uses group headings. (If you -use \gls{bib2gls} remember to invoke it with the \verb|--group| -or \verb|-g| switch.) The heading will use -\begin{definition}[\DescribeMacro\glsxtrbookindexbookmark] -\cs{glsxtrbookindexbookmark}\marg{group title}\marg{name} -\end{definition} -If \cs{pdfbookmark} has been defined, this will -use that command to bookmark the group title. If -\pkgopt[chapter]{section} is set (default if chapters are defined) -then this uses level~1 otherwise it uses level~2. You can -redefine this command if this isn't appropriate. -If \cs{pdfbookmark} hasn't been defined, this command does nothin. +For example, to change the font for the entire +\gls{numberlist} redefine \cs{GlsXtrFormatLocationList} as +appropriate. Don't modify \cs{glossaryentrynumbers}. -The group heading is formatted according to -\begin{definition}[\DescribeMacro\glsxtrbookindexformatheader] -\cs{glsxtrbookindexformatheader}\marg{group title} +Sometimes users like to insert \qt{page} or \qt{pages} in front of +the \gls{numberlist}. This is quite fiddly to do with the base +\styfmt{glossaries} package, but \styfmt{glossaries-extra} +provides a way of doing this. First you need to enable this +option and specify the text to display using: +\begin{definition}[\DescribeMacro\GlsXtrEnablePreLocationTag] +\cs{GlsXtrEnablePreLocationTag}\marg{page}\marg{pages} \end{definition} -which is defined as +where \meta{page} is the text to display if the \gls{numberlist} only +contains a single location and \meta{pages} is the text to display +otherwise. For example: \begin{verbatim} -\newcommand*{\glsxtrbookindexformatheader}[1]{% - \par{\centering\glstreegroupheaderfmt{#1}\par}% -} +\GlsXtrEnablePreLocationTag{Page: }{Pages: } \end{verbatim} -where \cs{glstreegroupheaderfmt} is provided by the -\sty{glossary-tree} package, which is automatically loaded. -Note that the entry names aren't encapsulated with -\cs{glstreenamefmt}. +An extra run is required when using this command. -The \sty{glossary-bookindex} package provides some supplementary -commands that aren't used by default, but may be used when -adjusting the style. These commands should only be -used within one of the \cs{print\ldots glossary} commands. -(That is, they should only be used in glossary styles.) -\begin{definition}[\DescribeMacro\glsxtrbookindexmarkentry] -\cs{glsxtrbookindexmarkentry}\marg{label} +\begin{important} +Use \texttt{glsignore} not \texttt{@gobble} as the format if you +want to suppress the page number (and only index the entry once). +\end{important} + +See the accompanying sample file \texttt{sample-pages.tex}. + +Note that \gls{bib2gls} can be instructed to insert +a prefix at the start of non-empty location lists, which +can be used as an alternative to \cs{GlsXtrEnablePreLocationTag}. + +\Glspl{locationlist} displayed with \cs{printnoidxglossary} +internally use +\begin{definition}[\DescribeMacro\glsnoidxdisplayloc] +\cs{glsnoidxdisplayloc}\marg{prefix}\marg{counter}\marg{format}\marg{location} \end{definition} -This writes information to the \texttt{.aux} file that -can be read on the next run to obtain the first and last entry on -each page of the glossary. +This command is provided by \styfmt{glossaries}, but is modified by +\styfmt{glossaries-extra} to check for the start and end range +formation identifiers \verb|(| and \verb|)| which are discarded to +obtain the actual control sequence name that forms the location +formatting command. -You can display the first entry -associated with the current page using: -\begin{definition}[\DescribeMacro\glsxtrbookindexfirstmark] -\cs{glsxtrbookindexfirstmark} +If the range identifiers aren't present, this just uses +\begin{definition}[\DescribeMacro\glsxtrdisplaysingleloc] +\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location} \end{definition} -and the last entry associated with the current page -using: -\begin{definition}[\DescribeMacro\glsxtrbookindexlastmark] -\cs{glsxtrbookindexlastmark} +otherwise it uses +\begin{definition}[\DescribeMacro\glsxtrdisplaystartloc] +\cs{glsxtrdisplaystartloc}\marg{format}\marg{location} \end{definition} -These do nothing if there are no entries marked on the current page -(or if the document build isn't up to date). +for the start of a range (where the identifier has been stripped +from \meta{format}) or +\begin{definition}[\DescribeMacro\glsxtrdisplayendloc] +\cs{glsxtrdisplayendloc}\marg{format}\marg{location} +\end{definition} +for the end of a range (where the identifier has been stripped +from \meta{format}). -The entry is formatted using: -\begin{definition}[\DescribeMacro\glsxtrbookindexfirstmarkfmt] -\cs{glsxtrbookindexfirstmarkfmt}\marg{label} +By default the start range command saves the format in +\begin{definition}[\DescribeMacro\glsxtrlocrangefmt] +\cs{glsxtrlocrangefmt} \end{definition} -for the first instance and -\begin{definition}[\DescribeMacro\glsxtrbookindexlastmarkfmt] -\cs{glsxtrbookindexlastmarkfmt}\marg{label} +and does +\begin{display} +\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location} +\end{display} +(If the format is empty, it will be replaced with +\texttt{glsnumberformat}.) + +The end command checks that the format matches the start of the +range, does +\begin{definition}[\DescribeMacro\glsxtrdisplayendlochook] +\cs{glsxtrdisplayendlochook}\marg{format}\marg{location} \end{definition} -for the last. +(which does nothing by default), followed by +\begin{display} +\cs{glsxtrdisplaysingleloc}\marg{format}\marg{location} +\end{display} +and then sets \cs{glsxtrlocrangefmt} to empty. -These commands are designed for use in page headers or footers -where the page number is stable. For example, \cs{glsxtrbookindexname} -can be redefined to mark the current entry: +This means that the list \begin{verbatim} -\renewcommand{\glsxtrbookindexname}[1]{% - \glsxtrbookindexmarkentry{#1}% - \glossentryname{#1}% -} +\glsnoidxdisplayloc{}{page}{(textbf}{1}, +\glsnoidxdisplayloc{}{page}{textbf}{1}, +\glsnoidxdisplayloc{}{page}{)textbf}{1}. \end{verbatim} -If you only want to mark the top-level entries, remember -to redefine \cs{glsxtrbookindexsubname} as it defaults -to \cs{glsxtrbookindexname}: +doesn't display any differently from \begin{verbatim} -\renewcommand{\glsxtrbookindexsubname}[1]{% - \glossentryname{#1}% -} +\glsnoidxdisplayloc{}{page}{textbf}{1}, +\glsnoidxdisplayloc{}{page}{textbf}{1}, +\glsnoidxdisplayloc{}{page}{textbf}{1}. \end{verbatim} +but it does make it easier to define your own custom list handler +that can accommodate the ranges. -Then if you're using \sty{fancyhdr} you can set the page style -to show the first and last entry for the current page with: +\subsubsection{The \styfmt{glossaries-extra-stylemods} Package} +\label{sec:stylemods} + +As from v1.02, \styfmt{glossaries-extra} now includes the package +\sty{glossaries-extra-stylemods} that will redefine the predefined +styles to include the post-description hook (for those that are +missing it). You will need to make sure the styles have already +been defined before loading \styfmt{glossaries-extra}. For example: \begin{verbatim} - \pagestyle{fancy}% - \lhead{\thepage}% - \lfoot{\glsxtrbookindexfirstmark}% - \cfoot{}% - \rfoot{\glsxtrbookindexlastmark}% +\usepackage{glossaries-extra} +\usepackage{glossary-longragged} +\usepackage{glossaries-extra-stylemods} \end{verbatim} - -\section{\styfmt{glossary-longextra} package} -\label{sec:longextra} - -As from version 1.37, the \styfmt{glossaries-extra} package comes -with the supplementary package \sty{glossary-longextra} that -provides additional styles, listed below, that use the -\env{longtable} environment. If you know that your glossary won't -span more than a page and you need to use it in a context that's -incompatible with \env{longtable}, you can instead setup these styles -to use \env{tabular} instead. In order to do this you must use -\begin{definition}[\DescribeMacro\GlsLongExtraUseTabulartrue] -\cs{GlsLongExtraUseTabulartrue} -\end{definition} -\emph{before the style is set}. For example: +Alternatively you can load +\texttt{glossary-}\meta{name}\texttt{.sty} at the same time by +passing \meta{name} as a package option to +\sty{glossaries-extra-stylemods}. For example: \begin{verbatim} -\GlsLongExtraUseTabulartrue -\setglossarystyle{long-name-desc} +\usepackage{glossaries-extra} +\usepackage[longragged]{glossaries-extra-stylemods} \end{verbatim} -or +Another option is to use the \pkgopt{stylemods} key when you +load \styfmt{glossaries-extra}. You can omit a value if you only want to use +the predefined styles that are automatically loaded by +\styfmt{glossaries} (for example, the \glostyle{long3col} style): \begin{verbatim} -\GlsLongExtraUseTabulartrue -\printunsrtglossary[style={long-name-desc}] +\usepackage[style=long3col,stylemods]{glossaries-extra} +\end{verbatim} +Or the value of \pkgopt{stylemods} may be a comma-separated list +of the style package identifiers. For example: +\begin{verbatim} +\usepackage[style=mcoltree,stylemods=mcols]{glossaries-extra} +\end{verbatim} +Remember to group the value if it contains any commas: +\begin{verbatim} +\usepackage[stylemods={mcols,longbooktabs}]{glossaries-extra} \end{verbatim} -If you use this setting, you can change the default vertical -alignment with: -\begin{definition}[\DescribeMacro\glslongextraTabularVAlign] -\cs{glslongextraTabularVAlign} -\end{definition} -The default definition is \texttt{c}. - -The column titles are formatted according to: -\begin{definition}[\DescribeMacro\glslongextraHeaderFmt] -\cs{glslongextraHeaderFmt}\marg{text} -\end{definition} -which simply does \cs{textbf}\marg{text} by default. -The name column has the title given by \ics{entryname} and -the column alignment is given by: -\begin{definition}[\DescribeMacro\glslongextraNameAlign] -\cs{glslongextraNameAlign} -\end{definition} -which expands to \texttt{l} (left) by default. +Note that the \glostyle{inline} style is dealt with slightly +differently. The original definition provided by the +\sty{glossary-inline} package uses \cs{glspostdescription} at the +end of the glossary (not after each entry description) within the +definition of \cs{glspostinline}. The style modification changes +this so that \cs{glspostinline} just does a full stop followed by +space factor adjustment, and the description +\cs{glsinlinedescformat} and sub-entry description formats +\cs{glsinlinesubdescformat} are redefined to include +\cs{glsxtrpostdescription} (not \cs{glspostdescription}). This means +that the modified \glostyle{inline} style isn't affected by the +\pkgopt{nopostdot} option, but the post-description category hook +can still be used. -The symbol column (where applicable) has the title given by -\ics{symbolname} and the column alignment is given by: -\begin{definition}[\DescribeMacro\glslongextraSymbolAlign] -\cs{glslongextraSymbolAlign} -\end{definition} -which expands to \texttt{c} (centred) by default. +The \env{tabular}-like styles, such as \glostyle{long} are +adjusted so that the \ics{ifglsnogroupskip} conditional (set with +\pkgopt{nogroupskip}) is moved outside of the definition of +\cs{glsgroupskip} to avoid problems that cause an \qt{Incomplete +\cs{iftrue}} error with \cs{printunsrtglossary} and +\cs{printnoidxglossary}. This means that if you want to change this +conditional using \cs{setupglossaries} or using the +\gloskey[printglossary]{nogroupskip} option in \cs{printglossary}, +\cs{printnoidxglossary} or \cs{printunsrtglossary}, you must also +reset the glossary style. -The location list column (where applicable) has the title given by -\ics{pagelistname} and the column alignment is given by: -\begin{definition}[\DescribeMacro\glslongextraLocationAlign] -\cs{glslongextraLocationAlign} +As from version 1.21, the hard-coded \cs{space} before the +\gls{numberlist} in many of the predefined styles is replaced +with +\begin{definition}[\DescribeMacro\glsxtrprelocation] +\cs{glsxtrprelocation} \end{definition} -which expands to +This just defaults to \cs{space} but may be redefined as required. +For example: \begin{verbatim} ->{\raggedright}p{\glspagelistwidth} +\renewcommand{\glsxtrprelocation}{\dotfill} \end{verbatim} -by default. (Ragged-right paragraph, \ics{glspagelistwidth} is -defined in \sty{glossary-long}, which is automatically loaded.) -The description column has the title given by \ics{descriptionname} -and the column alignment is given by: -\begin{definition}[\DescribeMacro\glslongextraDescAlign] -\cs{glslongextraDescAlign} +The \glostyle{list} styles use +\begin{definition}[\DescribeMacro\glslistprelocation] +\cs{glslistprelocation} \end{definition} -which expands to -\begin{verbatim} ->{\raggedright}p{\glsdescwidth} -\end{verbatim} -by default. (Ragged-right paragraph, \ics{glsdescwidth} is -defined in \sty{glossary-long}, which is automatically loaded.) +(which defaults to \cs{glsxtrprelocation}) for top-level items and +\begin{definition}[\DescribeMacro\glslistchildprelocation] +\cs{glslistchildprelocation} +\end{definition} +(which defaults to \cs{glslistprelocation}) for child items. -Unlike the long styles provided by the base \styfmt{glossaries} -package, these new styles try to determine the value of -\cs{glsdescwidth} at the start of the glossary according to the -number of columns provided by the style. The calculations are -performed by the following commands: -\begin{definition}[\DescribeMacro\glslongextraSetDescWidth] -\cs{glslongextraSetDescWidth} +As from v1.31, the description (including the post-description hook) +is governed by: +\begin{definition}[\DescribeMacro\glslistdesc] +\cs{glslistdesc}\marg{label} \end{definition} -This is used by the styles that have a name and description -column. The value of \cs{glsdescwidth} is computed as: -\[ - \cs{glsdescwidth} = \cs{linewidth} - 4\cs{tabcolsep} - W -\] -where $W$ is a guess at the width of the name column. This is first -set to the width of the name column header: -\begin{alltt} -\cs{settowidth}\marg{width}\{\cs{glslongextraHeaderFmt}\cs{entryname}\} -\end{alltt} -If any names in that column are larger than this, then you need -to specify the widest name using: -\begin{definition}[\DescribeMacro\glslongextraSetWidest] -\cs{glslongextraSetWidest}\marg{widest name} +for the \glostyle{list} and \glostyle{altlist} styles (but not the +\glostyle{listdotted} variations). + +For just the \glostyle{list} style and its letter group variations +(not the \glostyle{altlist} or \glostyle{listdotted} variations) the +\gls{numberlist} for child entries is followed by +\begin{definition}[\DescribeMacro\glslistchildpostlocation] +\cs{glslistchildpostlocation} \end{definition} -or -\begin{definition}[\DescribeMacro\glslongextraUpdateWidest] -\cs{glslongextraUpdateWidest}\marg{text} +which defaults to a full stop. + +The default value of \ics{glslistdottedwidth} is changed so that +it's set at the start of the document (if it hasn't been changed in +the preamble). This should take into account situations where +\cs{hsize} isn't set until the start of the document. + +The separator between groups (if not \pkgopt{nogroupskip}) is now +given by: +\begin{definition}[\DescribeMacro\glslistgroupskip] +\cs{glslistgroupskip} \end{definition} -These work like the analogous commands \cs{glssetwidest} and -\cs{glsupdatewidest} provided with the \glostyle{alttree} style, but -in this case there's no hierarchy. The default widest name -is obtained from the \glostyle{alttree} top-level name if set, -otherwise it's empty, so you can use \gls{bib2gls}['s] -\texttt{set-widest} option. If you have the entry counter enabled, -you will need to include this with the name for the extra material to -be taken into account. +This defaults to \cs{indexspace} with penalties to deter page +breaks. +This command isn't used if \pkgopt{nogroupskip} is set. -The name isn't shown for child entries by default, but if -you change this and you want to use \gls{bib2gls}['s] -\texttt{set-widest} option (for \gls{bib2gls} v1.8+) then you need to -redefine: -\begin{definition}[\DescribeMacro\glslongextraUpdateWidestChild] -\cs{glslongextraUpdateWidestChild}\marg{level}\marg{text} +The \sty{glossary-tree} package introduced new commands in +v4.22, \ics{glstreegroupheaderfmt} +and \ics{glstreenavigationfmt}, which are used to format +the letter group headings and the navigation elements for the +appropriate styles. These two new commands are defined in terms of +\ics{glstreenamefmt} since that was the command originally used +for the group headings and navigation. This now allows these +different elements to be defined independently, but the most common +redefinition is for \cs{glstreenamefmt} to remove the bold in the +name. If the bold is still required for the group heading and navigation +elements, then both other commands also need redefining. To simplify +matters, if \cs{glstreenamefmt} has been defined, as from v1.31 +\sty{glossaries-extra-stylemods} defines: +\begin{definition}[\DescribeMacro\glstreedefaultnamefmt] +\cs{glstreedefaultnamefmt}\marg{text} \end{definition} -This does nothing by default, but if you are including the child -names then you need to redefine this command: -\begin{verbatim} -\renewcommand{\glslongextraUpdateWidestChild}[2]{% - \glslongextraUpdateWidest{#2}% -} -\end{verbatim} +which simply does \cs{textbf}\marg{text} and redefines +\cs{glstreenamefmt}, \cs{glstreegroupheaderfmt} and +\cs{glstreenavigationfmt} all in terms of +\cs{glstreedefaultnamefmt}. -If you prefer to set an explicit width for the description -column then you need to redefine \cs{glslongextraSetDescWidth}. For -example: -\begin{verbatim} -\renewcommand{\glslongextraSetDescWidth}{% - \setlength{\glsdescwidth}{0.6\linewidth}% -} -\end{verbatim} +This means that if you want to change +all three to use a particular style you only need to redefine +\cs{glstreedefaultnamefmt}, but if you only want to redefine +\cs{glstreenamefmt} without affecting the other two commands, then +you now can. -The styles that have a name, symbol and description, -\cs{glsdescwidth} is set with: -\begin{definition}[\DescribeMacro\glslongextraSymSetDescWidth] -\cs{glslongextraSymSetDescWidth} +The separator between groups without headers is given by: +\begin{definition}[\DescribeMacro\glstreegroupskip] +\cs{glstreegroupskip} \end{definition} -This first uses \cs{glslongextraSetDescWidth} and then subtracts -2\cs{tabcolsep} and the width of the symbol column header from -\cs{glsdescwidth}. This assumes that the symbol column header -is larger than any of the symbols. If this isn't appropriate -then you can redefine this command. For example: -\begin{verbatim} -\renewcommand{\glslongextraSymSetDescWidth}{% - \glslongextraSetDescWidth - \addtolength{\glsdescwidth}{-3cm}% -} -\end{verbatim} -or +This defaults to just \ics{indexspace} without penalties. This +command isn't used if \pkgopt{nogroupskip} is set. (The penalties +introduced in v1.41 were moved to \cs{glstreeheadergroupskip} in +v1.42 as they are inappropriate when there's no header.) + +The separator between groups with headers is now given by (as from v1.42): +\begin{definition}[\DescribeMacro\glstreeheadergroupskip] +\cs{glstreegroupheaderskip} +\end{definition} +This defaults to \cs{glstreegroupskip} with penalties to deter page +breaks after the group heading. + +The styles that display the group titles now use: +\begin{definition}[\DescribeMacro\glstreePreHeader] +\cs{glstreePreHeader}\marg{label}\marg{title} +\end{definition} +where \meta{label} is the group label and \meta{title} is the group +title. This does nothing by default +and is inserted before the group title. You can redefine it to add +the group title to the PDF bookmarks. For example, if the +glossary title uses \cs{chapter} then: \begin{verbatim} -\renewcommand{\glslongextraSymSetDescWidth}{% - \setlength{\glsdescwidth}{.5\linewidth}% +\renewcommand{\glstreePreHeader}[2]{% + \pdfbookmark[1]{#2}{\currentglossary.#1}% } \end{verbatim} +will insert section-level bookmarks. The use of \cs{currentglossary} +helps to provide unique bookmark labels in the event of multiple +glossaries. -For the styles that have a name, description and location column, -\cs{glsdescwidth} is set using: -\begin{definition}[\DescribeMacro\glslongextraLocSetDescWidth] -\cs{glslongextraLocSetDescWidth} +The \glostyle{index}-like and \glostyle{tree}-like styles +insert the pre-\gls{numberlist} space with +\begin{definition}[\DescribeMacro\glstreeprelocation] +\cs{glstreeprelocation} \end{definition} -This uses \cs{glslongextraSetDescWidth} and then subtracts -2\cs{tabcolsep} and \cs{glspagelistwidth} from \cs{glsdescwidth}. -You can redefine this command to set both \cs{glsdescwidth} and -\cs{glspagelistwidth} if appropriate. - -For the styles that have a name, description, symbol and location -column, \cs{glsdescwidth} is set using: -\begin{definition}[\DescribeMacro\glslongextraSymLocSetDescWidth] -\cs{glslongextraSymLocSetDescWidth} +(which defaults to \cs{glsxtrprelocation}) for top-level items and +\begin{definition}[\DescribeMacro\glstreechildprelocation] +\cs{glstreechildprelocation} \end{definition} -This uses \cs{glslongextraSymSetDescWidth} and then subtracts -2\cs{tabcolsep} and \cs{glspagelistwidth} from -\cs{glsdescwidth}. Again, you can redefine this command -to explicitly set both lengths. +(which defaults to \cs{glstreeprelocation}) for child items. -In all cases, the top-level name is formatted according to: -\begin{definition}[\DescribeMacro\glslongextraNameFmt] -\cs{glslongextraNameFmt}\marg{label} +As from version 1.31, the \styfmt{glossaries-extra-stylemods} +package also provides: +\begin{definition}[\DescribeMacro\glstreenonamedesc] +\cs{glstreenonamedesc}\marg{label} \end{definition} -This does -\begin{alltt} -\cs{glsentryitem}\marg{label}\cs{glstarget}\marg{label}\{\cs{glossentryname}\marg{label}\} -\end{alltt} -which includes the entry counter (if enabled), the target and the post-name link. - -The top-level description is formatted according to: -\begin{definition}[\DescribeMacro\glslongextraDescFmt] -\cs{glslongextraDescFmt}\marg{label} +which is used by the \glostyle{treenoname} styles to display the +pre-description separator, the description and the post-description +hook. Similarly for the symbol: +\begin{definition}[\DescribeMacro\glstreenonamesymbol] +\cs{glstreenonamesymbol}\marg{label} \end{definition} -This does \cs{glossentrydesc}\marg{label} followed by the -post-description hook. - -The styles that have a symbol column format the symbol using: -\begin{definition}[\DescribeMacro\glslongextraSymbolFmt] -\cs{glslongextraSymbolFmt}\marg{label} +The above are just used for top-level entries. Child entries don't +have the name or symbol displayed for the \glostyle{treenoname} +styles, so there's only a command for the child description: +\begin{definition}[\DescribeMacro\glstreenonamechilddesc] +\cs{glstreenonamechilddesc}\marg{label} \end{definition} -This just does \cs{glossentrysymbol}\marg{label}. -The styles that have a location list column format the list using: -\begin{definition}[\DescribeMacro\glslongextraLocationFmt] -\cs{glslongextraLocationFmt}\marg{label}\marg{locations} +For the \glostyle{tree} styles (but not the \glostyle{treenoname} or +\glostyle{alttree} styles), the description is displayed using: +\begin{definition}[\DescribeMacro\glstreedesc] +\cs{glstreedesc}\marg{label} \end{definition} -This just does \meta{locations} and ignores the label. - -The child entries have their name formatted according to: -\begin{definition}[\DescribeMacro\glslongextraSubNameFmt] -\cs{glslongextraSubNameFmt}\marg{level}\marg{label} +and the symbol with: +\begin{definition}[\DescribeMacro\glstreesymbol] +\cs{glstreesymbol}\marg{label} \end{definition} -where \meta{level} is the hierarchical level. This defaults to: -\begin{alltt} -\cs{glssubentryitem}\marg{label}\cs{glstarget}\marg{label}\{\cs{strut}\} -\end{alltt} -This includes the sub-entry counter (if enabled) and the target -but doesn't show the name. The child description is formatted according to: -\begin{definition}[\DescribeMacro\glslongextraSubDescFmt] -\cs{glslongextraSubDescFmt}\marg{level}\marg{label} +Again the above two commands are just for top-level entries. The +child entries use: +\begin{definition}[\DescribeMacro\glstreechilddesc] +\cs{glstreechilddesc}\marg{label} \end{definition} -which defaults to just \cs{glslongextraDescFmt}\marg{label} - -The child symbol is formatted (where appropriate) according to: -\begin{definition}[\DescribeMacro\glslongextraSubSymbolFmt] -\cs{glslongextraSubSymbolFmt}\marg{level}\marg{label} +for the description and +\begin{definition}[\DescribeMacro\glstreechildsymbol] +\cs{glstreechildsymbol}\marg{label} \end{definition} -This just does \cs{glslongextraSymbolFmt}\marg{label} by default. - -The styles that have a location list column format the list for -child entries using: -\begin{definition}[\DescribeMacro\glslongextraLocationFmt] -\cs{glslongextraSubLocationFmt}\meta{level}\marg{label}\marg{locations} +for the symbol. +As from version 1.41, there are now wrapper commands for +\cs{glstreedesc} and \cs{glstreechilddesc} that check for +the description and symbol to determine what separator to use +before the page list. These are: +\begin{definition}[\DescribeMacro\glstreeDescLoc] +\cs{glstreeDescLoc}\marg{label}\marg{location} \end{definition} -This just does \meta{locations} and ignores the level and label. +for top-level entries and +\begin{definition}[\DescribeMacro\glstreeChildDescLoc] +\cs{glstreeChildDescLoc}\marg{label}\marg{location} +\end{definition} +for sub-entries. -The letter group headings are formatted according to: -\begin{definition}[\DescribeMacro\glslongextraGroupHeading] -\cs{glslongextraGroupHeading}\marg{n}\marg{label} +If either the symbol or description is present these will use +\cs{glstreeprelocation} or \cs{glstreechildprelocation}, +respectively. Otherwise, both will use (from v1.42): +\begin{definition}[\DescribeMacro\glstreeNoDescSymbolPreLocation] +\cs{glstreeNoDescSymbolPreLocation} \end{definition} -which does nothing by default. The first argument \meta{n} is the -number of columns in the table. The second argument \meta{label} -is the group label (not the title, although they may happen -to be the same). +The default is a space. This means that you could have, say, a +comma followed by a space for terms that are simply an alias, but +just have a space for terms that have a description that ends with a +full stop (or that just have a symbol without a description) where +the comma would be inappropriate. -This can be redefined to show the group heading. For example: -\begin{verbatim} -\renewcommand*{\glslongextraGroupHeading}[2]{% - \glsxtrgetgrouptitle{#2}{\thisgrptitle}% - \glslongextraHeaderFmt{\thisgrptitle}% - \tabularnewline - \noalign{\vskip\normalbaselineskip}% -} -\end{verbatim} -This ignores the first argument and just puts the group -title in the first column formatted according to -\cs{glslongextraHeaderFmt} (to match the column header). +Note that version 1.42 has corrected an error that was introduced to +v1.41 that caused the name to run into the location list if there +was no symbol and no description. -Remember that you can also adjust the styles through category -attributes. The name column's title is given by -\cs{entryname}, the description column's title is given by -\cs{descriptionname} and (where present) the symbol column's -title is given by \cs{symbolname}, as for the other long styles -that have headers. - -\begin{description} -\item{\glostyle{long-name-desc}} This is like the -\glostyle{longragged-booktabs} style but doesn't show the location -list (regardless of the \pkgopt{nonumberlist} option). The name is -shown in the first column and the description in the second. +As from version 1.05, the \styfmt{glossaries-extra-stylemods} +package provides some additional commands for use with the +\glostyle{alttree} style to make it easier to modify. +These commands are only defined if the +\sty{glossary-tree} package has already been loaded, which is +typically the case unless the \pkgopt{notree} option has been used +when loading \styfmt{glossaries}. -The symbol is not displayed. The header -row is produced with: -\begin{definition}[\DescribeMacro\glslongextraNameDescHeader] -\cs{glslongextraNameDescHeader} -\end{definition} -This essentially uses the same code as for \glostyle{longragged-booktabs} -but makes it easier to adjust the header without having to define a -new style. This is defined as: -\begin{verbatim} -\glslongextraNameDescTabularHeader\endhead -\glslongextraNameDescTabularFooter\endfoot -\end{verbatim} -where: -\begin{definition}[\DescribeMacro\glslongextraNameDescTabularHeader] -\cs{glslongextraNameDescTabularHeader} -\end{definition} -sets up the header and -\begin{definition}[\DescribeMacro\glslongextraNameDescTabularFooter] -\cs{glslongextraNameDescTabularFooter} +\begin{definition}[\DescribeMacro\gglssetwidest] +\cs{gglssetwidest}\oarg{level}\marg{name} \end{definition} -sets up the footer. If you have setup the \env{tabular} version -of this style then the above two commands are used at the -start and end of the \env{tabular} environment (and -\cs{glslongextraNameDescHeader} isn't used). - -For example, to simply remove the header and footer (for the default -\env{longtable} version of the style): -\begin{verbatim} -\renewcommand{\glslongextraNameDescHeader}{} -\end{verbatim} -Or to change the name alignment to centred: -\begin{verbatim} -\renewcommand{\glslongextraNameAlign}{c} -\end{verbatim} +(New to version 1.21.) +This is like \cs{glssetwidest} (provided by \sty{glossary-tree}) +but performs a global assignment. -\item{\glostyle{long-name-desc-loc}} This is like the -\glostyle{long-name-desc} style but has a third column for the -location list. The \env{longtable} header is given by: -\begin{definition}[\DescribeMacro\glslongextraNameDescLocationHeader] -\cs{glslongextraNameDescLocationHeader} +\begin{definition}[\DescribeMacro\eglssetwidest] +\cs{eglssetwidest}\oarg{level}\marg{name} \end{definition} -which similarly defined in terms of the commands used for the -\env{tabular} version: -\begin{definition}[\DescribeMacro\glslongextraNameDescLocationTabularHeader] -\cs{glslongextraNameDescLocationTabularHeader} +This is like \cs{glssetwidest} +but performs a protected expansion on \meta{name}. This has +a localised effect. For a global setting, use +\begin{definition}[\DescribeMacro\xglssetwidest] +\cs{xglssetwidest}\oarg{level}\marg{name} \end{definition} -and -\begin{definition}[\DescribeMacro\glslongextraNameDescLocationTabularFooter] -\cs{glslongextraNameDescLocationTabularFooter} +The following only set the value if \meta{name} is wider than the +current value (new to version 1.23). Local update: +\begin{definition}[\DescribeMacro\glsupdatewidest] +\cs{glsupdatewidest}\oarg{level}\marg{name} \end{definition} - -\item{\glostyle{long-desc-name}} This is like the -\glostyle{long-name-desc} style but swaps the columns. Note that -if the entry counter is displayed it will appear at the start -of the second column by default. The \env{longtable} header is formatted according -to: -\begin{definition}[\DescribeMacro\glslongextraDescNameHeader] -\cs{glslongextraDescNameHeader} +Global update: +\begin{definition}[\DescribeMacro\gglsupdatewidest] +\cs{gglsupdatewidest}\oarg{level}\marg{name} \end{definition} -which similarly defined in terms of the commands used for the -\env{tabular} version: -\begin{definition}[\DescribeMacro\glslongextraDescNameTabularHeader] -\cs{glslongextraDescNameTabularHeader} +Locale update (expands \meta{name}): +\begin{definition}[\DescribeMacro\eglsupdatewidest] +\cs{eglsupdatewidest}\oarg{level}\marg{name} \end{definition} -and -\begin{definition}[\DescribeMacro\glslongextraDescNameTabularFooter] -\cs{glslongextraDescNameTabularFooter} +Global update (expands \meta{name}): +\begin{definition}[\DescribeMacro\xglsupdatewidest] +\cs{xglsupdatewidest}\oarg{level}\marg{name} \end{definition} -\item{\glostyle{long-loc-desc-name}} This has three columns -containing the location list, description and name. The -\env{longtable} header -is formatted according to: -\begin{definition}[\DescribeMacro\glslongextraLocationDescNameHeader] -\cs{glslongextraLocationDescNameHeader} -\end{definition} -which similarly defined in terms of the commands used for the -\env{tabular} version: -\begin{definition}[\DescribeMacro\glslongextraLocationDescNameTabularHeader] -\cs{glslongextraLocationDescNameTabularHeader} + +The widest entry value can later be retrieved using +\begin{definition}[\DescribeMacro\glsgetwidestname] +\cs{glsgetwidestname} \end{definition} -and -\begin{definition}[\DescribeMacro\glslongextraLocationDescNameTabularFooter] -\cs{glslongextraLocationDescNameTabularFooter} +for the top-level entries and +\begin{definition}[\DescribeMacro\glsgetwidestsubname] +\cs{glsgetwidestsubname}\marg{level} \end{definition} +for sub-entries, where \meta{level} is the level number. -\item{\glostyle{long-name-desc-sym}} This is has three columns, with -the name in the first, the description in the second and the symbol -in the third. +Note that if you are using \gls{bib2gls}, you can use the +resource option \texttt{set-widest} which will try to determine the +widest name of all the selected entries. This isn't guaranteed +to work as it may depend on fonts or commands that \gls{bib2gls} +can't replicate, but it should be suitable for names that just +consist of text, and can be more efficient than iterating over all +the defined entries using \TeX. -The \env{longtable} header row is produced with: -\begin{definition}[\DescribeMacro\glslongextraNameDescSymHeader] -\cs{glslongextraNameDescSymHeader} -\end{definition} -which similarly defined in terms of the commands used for the -\env{tabular} version: -\begin{definition}[\DescribeMacro\glslongextraNameDescSymTabularHeader] -\cs{glslongextraNameDescSymTabularHeader} +The command \cs{glsfindwidesttoplevelname} provided by +\sty{glossary-tree} has a CamelCase synonym: +\begin{definition}[\DescribeMacro\glsFindWidestTopLevelName] +\cs{glsFindWidestTopLevelName}\oarg{glossary list} \end{definition} -and -\begin{definition}[\DescribeMacro\glslongextraNameDescSymTabularFooter] -\cs{glslongextraNameDescSymTabularFooter} +Similar commands are also provided: +\begin{definition}[\DescribeMacro\glsFindWidestUsedTopLevelName] +\cs{glsFindWidestUsedTopLevelName}\oarg{glossary list} \end{definition} +This has an additional check that the entry has been used. +Naturally this is only useful if the glossaries that use +the \glostyle{alttree} style occur at the end of the document. +This command should be placed just before the start of the glossary. +(Alternatively, place it at the end of the document and save +the value in the auxiliary file for the next run.) -\item{\glostyle{long-name-desc-sym-loc}} This is has four columns, with -the name in the first, the description in the second, the symbol -in the third and the location list in the fourth. +\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyName] +\cs{glsFindWidestUsedAnyName}\oarg{glossary list} +\end{definition} +This is like the previous command but if doesn't check the +\gloskey{parent} key. This is useful if all levels should have the +same width for the name. -The \env{longtable} header row is produced with: -\begin{definition}[\DescribeMacro\glslongextraNameDescSymLocationHeader] -\cs{glslongextraNameDescSymLocationHeader} +\begin{definition}[\DescribeMacro\glsFindWidestAnyName] +\cs{glsFindWidestAnyName}\oarg{glossary list} \end{definition} -which similarly defined in terms of the commands used for the -\env{tabular} version: -\begin{definition}[\DescribeMacro\glslongextraNameDescSymLocationTabularHeader] -\cs{glslongextraNameDescSymLocationTabularHeader} +This is like the previous command but doesn't check if the entry +has been used. + +\begin{definition}[\DescribeMacro\glsFindWidestUsedLevelTwo] +\cs{glsFindWidestUsedLevelTwo}\oarg{glossary list} \end{definition} -and -\begin{definition}[\DescribeMacro\glslongextraNameDescSymLocationTabularFooter] -\cs{glslongextraNameDescSymLocationTabularFooter} +This is like \cs{glsFindWidestUsedTopLevelName} but also sets +the first two sub-levels as well. Any entry that has a +great-grandparent is ignored. + +\begin{definition}[\DescribeMacro\glsFindWidestLevelTwo] +\cs{glsFindWidestLevelTwo}\oarg{glossary list} \end{definition} +This is like the previous command but doesn't check if the entry has +been used. -\item{\glostyle{long-name-sym-desc}} This is like the -\glostyle{long-name-desc-sym} but the second and third column are -swapped. The \env{longtable} header row is given by: -\begin{definition}[\DescribeMacro\glslongextraNameSymDescHeader] -\cs{glslongextraNameSymDescHeader} +\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyNameSymbol] +\cs{glsFindWidestUsedAnyNameSymbol}\oarg{glossary +list}\marg{register} \end{definition} -which similarly defined in terms of the commands used for the -\env{tabular} version: -\begin{definition}[\DescribeMacro\glslongextraNameSymDescTabularHeader] -\cs{glslongextraNameSymDescTabularHeader} +This is like \cs{glsFindWidestUsedAnyName} but also measures the +symbol. The length of the widest symbol is stored in +\meta{register}. + +\begin{definition}[\DescribeMacro\glsFindWidestAnyNameSymbol] +\cs{glsFindWidestAnyNameSymbol}\oarg{glossary list}\marg{register} \end{definition} -and -\begin{definition}[\DescribeMacro\glslongextraNameSymDescTabularFooter] -\cs{glslongextraNameSymDescTabularFooter} +This is like the previous command but it doesn't check if the entry +has been used. + +\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyNameSymbolLocation] +\cs{glsFindWidestUsedAnyNameSymbolLocation}\oarg{glossary +list}\marg{symbol register}\marg{location register} \end{definition} +This is like \cs{glsFindWidestUsedAnyNameSymbol} but also +measures the \gls{numberlist}. This requires +\ics{glsentrynumberlist} (see the \styfmt{glossaries} user manual). +The length of the widest symbol is stored in \meta{symbol register} +and the length of the widest \gls*{numberlist} is stored in +\meta{location register}. -\item{\glostyle{long-name-sym-desc-loc}} This is like the -\glostyle{long-name-desc-sym-loc} but the second and third column are -swapped. The \env{longtable} header row is given by: -\begin{definition}[\DescribeMacro\glslongextraNameSymDescLocationHeader] -\cs{glslongextraNameSymDescLocationHeader} +\begin{definition}[\DescribeMacro\glsFindWidestAnyNameSymbolLocation] +\cs{glsFindWidestAnyNameSymbolLocation}\oarg{glossary +list}\marg{symbol register}\marg{location register} \end{definition} -which similarly defined in terms of the commands used for the -\env{tabular} version: -\begin{definition}[\DescribeMacro\glslongextraNameSymDescLocationTabularHeader] -\cs{glslongextraNameSymDescLocationTabularHeader} +This is like the previous command but it doesn't check if the entry +has been used. + +\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyNameLocation] +\cs{glsFindWidestUsedAnyNameLocation}\oarg{glossary +list}\marg{register} \end{definition} -and -\begin{definition}[\DescribeMacro\glslongextraNameSymDescLocationTabularFooter] -\cs{glslongextraNameSymDescLocationTabularFooter} +This is like \cs{glsFindWidestUsedAnyNameSymbolLocation} but doesn't +measure the symbol. The length of the widest \gls{numberlist} +is stored in \meta{register}. + +\begin{definition}[\DescribeMacro\glsFindWidestAnyNameLocation] +\cs{glsFindWidestAnyNameLocation}\oarg{glossary +list}\marg{register} \end{definition} +This is like the previous command but doesn't check if the entry has +been used. -\item{\glostyle{long-sym-desc-name}} This has the symbol in the -first column, the description in the second and the name in the -third. The \env{longtable} header row is given by: -\begin{definition}[\DescribeMacro\glslongextraSymDescNameHeader] -\cs{glslongextraSymDescNameHeader} -\end{definition} -which similarly defined in terms of the commands used for the -\env{tabular} version: -\begin{definition}[\DescribeMacro\glslongextraSymDescNameTabularHeader] -\cs{glslongextraSymDescNameTabularHeader} +The layout of the symbol, description and \gls{numberlist} +is governed by +\begin{definition}[\DescribeMacro\glsxtralttreeSymbolDescLocation] +\cs{glsxtralttreeSymbolDescLocation}\marg{label}\marg{number list} \end{definition} -and -\begin{definition}[\DescribeMacro\glslongextraSymDescNameTabularFooter] -\cs{glslongextraSymDescNameTabularFooter} +for top-level entries and +\begin{definition}[\DescribeMacro\glsxtralttreeSubSymbolDescLocation] +\cs{glsxtralttreeSubSymbolDescLocation}\marg{label}\marg{number list} \end{definition} +for sub-entries. -\item{\glostyle{long-loc-sym-desc-name}} This has the location list -in the first column, symbol in the -second column, the description in the third and the name in the -fourth. The \env{longtable} header row is given by: -\begin{definition}[\DescribeMacro\glslongextraLocationSymDescNameHeader] -\cs{glslongextraLocationSymDescNameHeader} -\end{definition} -which similarly defined in terms of the commands used for the -\env{tabular} version: -\begin{definition}[\DescribeMacro\glslongextraLocationSymDescNameTabularHeader] -\cs{glslongextraLocationSymDescNameTabularHeader} -\end{definition} -and -\begin{definition}[\DescribeMacro\glslongextraLocationSymDescNameTabularFooter] -\cs{glslongextraLocationSymDescNameTabularFooter} +There is now a user level command that performs the initialisation +for the \glostyle{alttree} style: +\begin{definition}[\DescribeMacro\glsxtralttreeInit] +\cs{glsxtralttreeInit} \end{definition} -\item{\glostyle{long-desc-sym-name}} This has the description in the -first column, the symbol in the second and the name in the -third. The \env{longtable} header row is given by: -\begin{definition}[\DescribeMacro\glslongextraDescSymNameHeader] -\cs{glslongextraDescSymNameHeader} -\end{definition} -which similarly defined in terms of the commands used for the -\env{tabular} version: -\begin{definition}[\DescribeMacro\glslongextraDescSymNameTabularHeader] -\cs{glslongextraDescSymNameTabularHeader} -\end{definition} -and -\begin{definition}[\DescribeMacro\glslongextraDescSymNameTabularFooter] -\cs{glslongextraDescSymNameTabularFooter} +The paragraph indent for subsequent paragraphs in multi-paragraph +descriptions is provided by the length +\begin{definition}[\DescribeMacro\glsxtrAltTreeIndent] +\cs{glsxtrAltTreeIndent} \end{definition} -\item{\glostyle{long-loc-desc-sym-name}} This has the location list -in the first column, the description in the -second column, the symbol in the third and the name in the -fourth. The \env{longtable} header row is given by: -\begin{definition}[\DescribeMacro\glslongextraLocationDescSymNameHeader] -\cs{glslongextraLocationDescSymNameHeader} -\end{definition} -which similarly defined in terms of the commands used for the -\env{tabular} version: -\begin{definition}[\DescribeMacro\glslongextraLocationDescSymNameTabularHeader] -\cs{glslongextraLocationDescSymNameTabularHeader} -\end{definition} -and -\begin{definition}[\DescribeMacro\glslongextraLocationDescSymNameTabularFooter] -\cs{glslongextraLocationDescSymNameTabularFooter} -\end{definition} +For additional commands that are available with the +\glostyle{alttree} style, see the documented code +(\nolinkurl{glossaries-extra-code.pdf}). See also +the accompanying sample files \nolinkurl{sample-alttree.tex}, +\nolinkurl{sample-alttree-sym.tex} and +\nolinkurl{sample-alttree-marginpar.tex}. -\end{description} +\chapter{New Glossary Styles} -\section{\styfmt{glossary-topic} package} -\label{sec:topic} +The \styfmt{glossaries-extra} package comes with some new styles. +The associated style package needs to be loaded. This can be done +with \cs{usepackage} but it's simpler to use the \pkgopt{stylemods} +option. -As from version 1.40, the \styfmt{glossaries-extra} package comes -with the supplementary package \sty{glossary-topic} that -provides glossary styles designed for hierarchical glossaries -where the top-level entries are topic titles. This package -automatically loads the \sty{multicols} package. If the -\sty{glossary-tree} package is also loaded then commands like -\cs{glssetwidest} can be used on these styles in much the same way -as for the \glostyle{alttree} style. If a widest value isn't set -then these styles behave more like the \glostyle{tree} style. -\begin{description} -\item[\glostyle{topic}] This style is similar to the \glostyle{tree} -style but the indentation doesn't start until the second -sub-item level. The top-level entries have the name displayed -in a larger font with the description following in a new paragraph. -This style doesn't support the \pkgopt{nogroupskip} setting. +\section{\styfmt{glossary-bookindex} package} +\label{sec:bookindex} -\item[\glostyle{topicmcols}] This style is like the \glostyle{topic} -style but the sub-entries are placed inside a \env{multicols} -environment. The environment name is supplied in the value of -the command: -\begin{definition}[\DescribeMacro\glstopicColsEnv] -\cs{glstopicColsEnv} -\end{definition} -You can change this to the starred form. For example: +As from v1.21, \styfmt{glossaries-extra} has a new supplementary +package \sty{glossary-bookindex} which provides the glossary style +\glostyle{bookindex}. This is very similar to the +\glostyle{mcolindexgroup} style but is designed for indexes, so by +default only the name and location list are displayed. You can +either load this package explicitly and then set the style: \begin{verbatim} -\renewcommand{\glstopicColsEnv}{multicols*} +\usepackage{glossaries-extra} +\usepackage{glossary-bookindex} +\setglossarystyle{bookindex} \end{verbatim} -The number of columns is given by the command: -\begin{definition}[\DescribeMacro\glstopicCols] -\cs{glstopicCols} -\end{definition} -The default value is 2. -\end{description} -Both styles use the following commands. -\begin{definition}[\DescribeMacro\glstopicParIndent] -\cs{glstopicParIndent} -\end{definition} -This command is a length that's used for the paragraph indentation -in any multi-paragraph description for top-level entries, but not -for the first paragraph (at the start of the description) which -isn't indented. +or use both the \pkgopt{stylemods} and \sty{style} options: +\begin{verbatim} +\usepackage[stylemods=bookindex,style=bookindex]{glossaries-extra} +\end{verbatim} +The \glostyle{bookindex} style only supports a maximum +hierarchical level of 2 (top-level, level~1 and level~2). It's +primarily designed for use with \gls{bib2gls}. It may be used with +other indexing options, but some features may not be present and +UTF-8 characters may cause a problem with non-Unicode engines in +letter group headings or PDF bookmarks. (\gls{bib2gls} uses numeric +identifies by default to avoid these problems. If numbers show up in +the group headings instead of the appropriate characters, check that +you have used the \pkgopt{record} package option.) -\begin{definition}[\DescribeMacro\glstopicSubIndent] -\cs{glstopicSubIndent} +The number of columns is given by +\begin{definition}[\DescribeMacro\glsxtrbookindexcols] +\cs{glsxtrbookindexcols} \end{definition} -This command is a length that's used to calculate the hanging -indentation for sub-entries. The level~1 sub-entries don't indent -the name. Level~$n$ sub-entries have the name indented by -$(n-1)\times$\cs{glstopicSubIndent}. The hanging indent depends -on whether or not a widest name has been set for the level. +which defaults to 2. -\begin{definition}[\DescribeMacro\glstopicInit] -\cs{glstopicInit} +This style uses the \env{multicols} environment. If +the command +\begin{definition}[\DescribeMacro\glsxtrbookindexcolspread] +\cs{glsxtrbookindexcolspread} \end{definition} -Hook used at the start of the glossary. Does nothing by default. +isn't empty then it's supplied as the optional argument +following \verb|\begin{multicols}|\marg{n}. You can switch from +\env{multicols} to \env{multicols*} by redefining +\begin{definition}[\DescribeMacro\glsxtrbookindexmulticolsenv] +\cs{glsxtrbookindexmulticolsenv} +\end{definition} +For example +\begin{verbatim} +\renewcommand{\glsxtrbookindexmulticolsenv}{multicols*} +\end{verbatim} -Although the styles don't support letter groups by default, if you -have many topics (top-level entries) and you feel that it would help -the reader to divide them up into headed letter groups, you can -redefine: -\begin{definition}[\DescribeMacro\glstopicGroupHeading] -\cs{glstopicGroupHeading}\marg{group label} +Each top-level entry is displayed using +\begin{definition}[\DescribeMacro\glsxtrbookindexname] +\cs{glsxtrbookindexname}\marg{label} \end{definition} -This does nothing by default. If you want to redefine it, you can -fetch the title corresponding to the group label with -\cs{glsxtrgetgrouptitle}. For example: +where the entry is identified by \meta{label}. This just +does \cs{glossentryname}\marg{label} by default. +For example, if you want the symbol to be included: \begin{verbatim} -\renewcommand*{\glstopicGroupHeading}[1]{% - \glsxtrgetgrouptitle{#1}{\thisgrptitle}% - \section*{\thisgrptitle}% +\renewcommand*{\glsxtrbookindexname}[1]{% + \glossentryname{#1}% + \ifglshassymbol{#1}{\space (\glossentrysymbol{#1})}{}% } \end{verbatim} -Remember that if you use \gls{bib2gls}, you will need the -\verb|--group| (or \verb|-g|) switch to support this. +or if you want the description (if set): +\begin{verbatim} +\renewcommand*{\glsxtrbookindexname}[1]{% + \glossentryname{#1}% + \ifglshasdesc{#1}{\space \glossentrydesc{#1}\glspostdescription}{}% +} +\end{verbatim} +(which picks up the post-description hook). -\begin{definition}[\DescribeMacro\glstopicItem] -\cs{glstopicItem}\marg{label}\marg{location list} +Alternatively you can use the \cs{glsxtrpostname\meta{category}} +hook to append information after the name according to the entry's +category. + +Sub-entries are displayed using +\begin{definition}[\DescribeMacro\glsxtrbookindexsubname] +\cs{glsxtrbookindexsubname}\marg{label} \end{definition} -Used to format the name, symbol, description and location list -for the top-level entries. This starts with a paragraph break -followed by: -\begin{definition}[\DescribeMacro\glstopicPreSkip] -\cs{glstopicPreSkip} +which just defaults to \cs{glsxtrbookindexname}\marg{label}. + +The separator used before the location list for top-level +entries is given by +\begin{definition}[\DescribeMacro\glsxtrbookindexprelocation] +\cs{glsxtrbookindexprelocation}\marg{label} \end{definition} -which defaults to \cs{medskip}. There is then a hook: -\begin{definition}[\DescribeMacro\glstopicMarker] -\cs{glstopicMarker}\marg{label} +where \meta{label} is the entry's label. This checks if +the \texttt{location} field has been set. If it has, it +does +\begin{verbatim} +,\glsxtrprelocation +\end{verbatim} +otherwise it just does \cs{glsxtrprelocation} (which defaults +to \cs{space}). If you're not using +\gls{bib2gls}, the \gloskey{location} field won't be set. + +The separator used before the +location list for sub-entries is given by +\begin{definition}[\DescribeMacro\glsxtrbookindexsubprelocation] +\cs{glsxtrbookindexsubprelocation}\marg{label} \end{definition} -which does nothing by default, but may be redefined. For example, -to add a line to the table of contents. -The name and symbol are set in the -form of a title using: -\begin{definition}[\DescribeMacro\glstopicTitle] -\cs{glstopicTitle}\marg{label} +which defaults to \cs{glsxtrbookindexprelocation}\marg{label}. + +The actual location list is encapsulated with: +\begin{definition}[\DescribeMacro\glsxtrbookindexlocation] +\cs{glsxtrbookindexlocation}\marg{label}\marg{location list} \end{definition} -This uses \cs{Glossentryname} which converts the first letter to -upper case. If there's a symbol, this is added in parentheses. -Both name and symbol (if present) are encapsulated by -\begin{definition}[\DescribeMacro\glstopicTitleFont] -\cs{glstopicTitleFont}\marg{text} +for top-level entries and +\begin{definition}[\DescribeMacro\glsxtrbookindexsublocation] +\cs{glsxtrbookindexsublocation}\marg{label}\marg{location list} \end{definition} -This uses a bold, large font by default. +for sub-entries. These both just do \meta{location list} by default. -If the entry has the description key set (tested with -\cs{ifglshasdesc}) then a paragraph break is inserted followed by: -\begin{definition}[\DescribeMacro\glstopicMidSkip] -\cs{glstopicMidSkip} -\end{definition} -which defaults to \cs{smallskip}. This is followed by the -description which is formatted according to: -\begin{definition}[\DescribeMacro\glstopicDesc] -\cs{glstopicDesc}\marg{label} +The separator used between a top-level parent and child entry is +given by +\begin{definition}[\DescribeMacro\glsxtrbookindexparentchildsep] +\cs{glsxtrbookindexparentchildsep} \end{definition} -This just does \cs{Glossentrydesc}\marg{label} followed -by the post-description hook. +This defaults to \cs{nopagebreak}. -A paragraph break followed by: -\begin{definition}[\DescribeMacro\glstopicPostSkip] -\cs{glstopicPostSkip} -\end{definition} -comes next regardless of whether or not the description was -displayed. This defaults to \cs{smallskip}. This is then followed -by: -\begin{definition}[\DescribeMacro\glstopicLoc] -\cs{glstopicLoc}\marg{label}\marg{location list} +The separator used between a sub-level parent and child entry is +given by +\begin{definition}[\DescribeMacro\glsxtrbookindexparentsubchildsep] +\cs{glsxtrbookindexparentsubchildsep} \end{definition} -which may be used to display the location list, but does nothing by -default. +This defaults to \cs{glsxtrbookindexparentchildsep}. -The sub-entries first set up the paragraph and hanging indentations -using: -\begin{definition}[\DescribeMacro\glstopicAssignSubIndent] -\cs{glstopicAssignSubIndent}\marg{level} +The separator between top-level entries is given by +\begin{definition}[\DescribeMacro\glsxtrbookindexbetween] +\cs{glsxtrbookindexbetween}\marg{label1}\marg{label2} \end{definition} -This uses: -\begin{definition}[\DescribeMacro\glstopicAssignWidest] -\cs{glstopicAssignWidest}\marg{level} +This comes after the entry given by \meta{label1}, if the entry +has no children, or after the last descendent otherwise, +so it always comes immediately before the entry given +by \meta{label2} unless the entry occurs at the start of +a group. This does nothing by default. + +The separator between two level~1 entries is given by +\begin{definition}[\DescribeMacro\glsxtrbookindexsubbetween] +\cs{glsxtrbookindexsubbetween}\marg{label1}\marg{label2} \end{definition} -to determine if a widest name has been set for the given level. -The sub-entry has its information displayed using: -\begin{definition}[\DescribeMacro\glstopicSubItem] -\cs{glstopicSubItem}\marg{level}\marg{label}\marg{location} +The separator between two level~2 entries is given by +\begin{definition}[\DescribeMacro\glsxtrbookindexsubsubbetween] +\cs{glsxtrbookindexsubsubbetween}\marg{label1}\marg{label2} \end{definition} -This encapsulates the name with: -\begin{definition}[\DescribeMacro\glstopicSubNameFont] -\cs{glstopicSubNameFont}\marg{text} +At the end of each letter group, the following hooks +are done in order: +\begin{definition}[\DescribeMacro\glsxtrbookindexsubsubatendgroup] +\cs{glsxtrbookindexsubsubatendgroup}\marg{sub-sub-label} \end{definition} -By default this just uses \cs{textbf}. This is followed by: -\begin{definition}[\DescribeMacro\glstopicSubItemSep] -\cs{glstopicSubItemSep} +\begin{definition}[\DescribeMacro\glsxtrbookindexsubatendgroup] +\cs{glsxtrbookindexsubatendgroup}\marg{sub-label} \end{definition} -which defaults to \cs{quad}. The name and separator are -passed in the \meta{text} argument of: -\begin{definition}[\DescribeMacro\glstopicSubItemBox] -\cs{glstopicSubItemBox}\marg{level}\marg{text} +\begin{definition}[\DescribeMacro\glsxtrbookindexatendgroup] +\cs{glsxtrbookindexatendgroup}\marg{label} \end{definition} -If a widest name was set for the given level, this will -put \meta{text} inside a box of that width otherwise it just does -\meta{text}. +where \meta{sub-sub-label} is the label of the last +level~2 entry, \meta{sub-label} is the label of the last +level~1 entry and \meta{label} is the label of the last +level~0 entry. -This is followed by the symbol in parentheses if set. Then, if the -description is set, the description and post-description hook are -displayed followed by: -\begin{definition}[\DescribeMacro\glstopicSubPreLocSep] -\cs{glstopicSubPreLocSep} -\end{definition} -(This command isn't used if the description isn't set.) +For example, the resource option \texttt{seealso=omit} +instructs \gls{bib2gls} to omit the \texttt{seealso} cross-reference +from the location list. (The \texttt{see} cross-reference +will still be added unless you also have \texttt{see=omit}.) +The \texttt{seealso} cross-reference can instead be appended after +the child entries using: +\begin{verbatim} +\renewcommand{\glsxtrbookindexatendgroup}[1]{% + \glsxtrifhasfield{seealso}{#1}{\glstreesubitem\glsxtruseseealso{#1}}{}% +} +\renewcommand{\glsxtrbookindexbetween}[2]{% + \glsxtrbookindexatendgroup{#1}% +}% -Finally the location list is displayed using: -\begin{definition}[\DescribeMacro\glstopicSubLoc] -\cs{glstopicSubLoc}\marg{label}\marg{location} -\end{definition} -which just does \meta{location} by default. +\renewcommand{\glsxtrbookindexsubatendgroup}[1]{% + \glsxtrifhasfield{seealso}{#1}{\glstreesubsubitem\glsxtruseseealso{#1}}{}% +} -\section{Glossary Style Modifications} -\label{sec:glosstylemods} +\renewcommand{\glsxtrbookindexsubbetween}[2]{% + \glsxtrbookindexsubatendgroup{#1}% +} -The \sty{glossaries-extra-stylemods} package (more conveniently -loaded through the \styfmt{glossaries-extra} -\pkgopt{stylemods} option) modifies some of the predefined -styles that are provided with the \styfmt{glossaries} package. -These modifications are described in more detail in -\sectionref{sec:stylemods}. +\renewcommand{\glsxtrbookindexsubsubatendgroup}[1]{% + \glsxtrifhasfield{seealso}{#1}% + {\glstreeitem\hspace*{40pt}\glsxtruseseealso{#1}}{}% +} -The \sty{glossaries} package tries to determine the group -title from its label by first checking if -\cs{}\meta{label}\texttt{groupname} exists. If it doesn't exist, -then the title is assumed to be the same as the label. -For example, when typesetting the \qt{A} letter group, -\sty{glossaries} first checks if \cs{Agroupname} exists. -This could potentially cause conflict with another package -that may have some other meaning for \cs{Agroupname}, so -\sty{glossaries-extra} first checks for the existence -of the internal command \cs{glsxtr@grouptitle@}\meta{label} -which shouldn't clash with another package. You can set the -group title using -\begin{definition}[\DescribeMacro\glsxtrsetgrouptitle] -\cs{glsxtrsetgrouptitle}\marg{label}\marg{title} -\end{definition} -For example: -\begin{verbatim} -\glsxtrsetgrouptitle{A}{A (a)} +\renewcommand{\glsxtrbookindexsubsubbetween}[2]{% + \glsxtrbookindexsubsubatendgroup{#1}% +} \end{verbatim} -This uses a global assignment. If you need to scope the change -you can use -\begin{definition}[\DescribeMacro\glsxtrlocalsetgrouptitle] -\cs{glsxtrlocalsetgrouptitle}\marg{label}\marg{title} +This uses \cs{glstreesubitem} and \cs{glstreesubsubitem} +to indent the cross-reference according to the next level down, +so the cross-reference for a top-level entry is aligned with +the sub-entries, and a level~1 entry has its cross-reference +aligned with sub-sub-entries. In the event that a level~2 +entry has a cross-reference, this is indented a bit further +(but it won't be aligned with any deeper level as the +\glostyle{bookindex} style only supports a maximum of two +sub-levels). + +The \glostyle{bookindex} style uses group headings. (If you +use \gls{bib2gls} remember to invoke it with the \verb|--group| +or \verb|-g| switch.) The heading will use +\begin{definition}[\DescribeMacro\glsxtrbookindexbookmark] +\cs{glsxtrbookindexbookmark}\marg{group title}\marg{name} \end{definition} +If \cs{pdfbookmark} has been defined, this will +use that command to bookmark the group title. If +\pkgopt[chapter]{section} is set (default if chapters are defined) +then this uses level~1 otherwise it uses level~2. You can +redefine this command if this isn't appropriate. +If \cs{pdfbookmark} hasn't been defined, this command does nothin. -\subsection{Style Hooks} -\label{sec:stylehooks} +The group heading is formatted according to +\begin{definition}[\DescribeMacro\glsxtrbookindexformatheader] +\cs{glsxtrbookindexformatheader}\marg{group title} +\end{definition} +which is defined as +\begin{verbatim} +\newcommand*{\glsxtrbookindexformatheader}[1]{% + \par{\centering\glstreegroupheaderfmt{#1}\par}% +} +\end{verbatim} +where \cs{glstreegroupheaderfmt} is provided by the +\sty{glossary-tree} package, which is automatically loaded. +Note that the entry names aren't encapsulated with +\cs{glstreenamefmt}. -The commands \ics{glossentryname} and \ics{glossentrydesc} are -modified to take into account the \catattr{glossname}, -\catattr{glossdesc} and \catattr{glossdescfont} attributes (see \sectionref{sec:categories}). -This means you can make simple case-changing modifications to -the name and description without defining a new glossary style. +The \sty{glossary-bookindex} package provides some supplementary +commands that aren't used by default, but may be used when +adjusting the style. These commands should only be +used within one of the \cs{print\ldots glossary} commands. +(That is, they should only be used in glossary styles.) +\begin{definition}[\DescribeMacro\glsxtrbookindexmarkentry] +\cs{glsxtrbookindexmarkentry}\marg{label} +\end{definition} +This writes information to the \texttt{.aux} file that +can be read on the next run to obtain the first and last entry on +each page of the glossary. -If you want to adapt a style to use another field instead -of \gloskey{name}, you can use -\begin{definition}[\DescribeMacro\glossentrynameother] -\cs{glossentrynameother}\marg{label}\marg{field} +You can display the first entry +associated with the current page using: +\begin{definition}[\DescribeMacro\glsxtrbookindexfirstmark] +\cs{glsxtrbookindexfirstmark} \end{definition} -This behaves just like \cs{glossentryname} (that is, it obeys -\catattr{glossname}, \catattr{glossnamefont} or \cs{glsnamefont} and uses the post-name -hook) but it uses the given \meta{field} instead of \gloskey{name}. -The \meta{field} argument must be the internal field name -(for example \texttt{desc} rather than \texttt{description}). -See the key to field mappings table in the \styfmt{glossaries} -user manual. +and the last entry associated with the current page +using: +\begin{definition}[\DescribeMacro\glsxtrbookindexlastmark] +\cs{glsxtrbookindexlastmark} +\end{definition} +These do nothing if there are no entries marked on the current page +(or if the document build isn't up to date). -There is a hook after \ics{glossentryname} and -\ics{Glossentryname}: -\begin{definition}[\DescribeMacro\glsxtrpostnamehook] -\cs{glsxtrpostnamehook}\marg{label} +The entry is formatted using: +\begin{definition}[\DescribeMacro\glsxtrbookindexfirstmarkfmt] +\cs{glsxtrbookindexfirstmarkfmt}\marg{label} \end{definition} -By default this checks the \catattr{indexname} attribute. -If the attribute exists for the category to which the label belongs, -then the name is automatically indexed using -\begin{definition} -\ics{glsxtrdoautoindexname}\marg{label}\texttt{\{indexname\}} +for the first instance and +\begin{definition}[\DescribeMacro\glsxtrbookindexlastmarkfmt] +\cs{glsxtrbookindexlastmarkfmt}\marg{label} \end{definition} -See \sectionref{sec:autoindex} for further details. +for the last. -\begin{sloppypar} -As from version 1.04, the post-name hook \cs{glsxtrpostnamehook} -will also use \cs{glsxtrpostname}\meta{category} if it exists. -You can use \ics{glscurrententrylabel} to obtain the entry label -with the definition of this command. For example, suppose you are -using a glossary style the doesn't display the symbol, you can -insert the symbol after the name for a particular category, say, -the \qt{symbol} category: -\end{sloppypar} +These commands are designed for use in page headers or footers +where the page number is stable. For example, \cs{glsxtrbookindexname} +can be redefined to mark the current entry: \begin{verbatim} -\newcommand*{\glsxtrpostnamesymbol}{\space - (\glsentrysymbol{\glscurrententrylabel})} +\renewcommand{\glsxtrbookindexname}[1]{% + \glsxtrbookindexmarkentry{#1}% + \glossentryname{#1}% +} \end{verbatim} -For convenience, as from v1.31, you can use -\begin{definition}[\DescribeMacro\glsdefpostname] -\cs{glsdefpostname}\marg{category}\marg{definition} +If you only want to mark the top-level entries, remember +to redefine \cs{glsxtrbookindexsubname} as it defaults +to \cs{glsxtrbookindexname}: +\begin{verbatim} +\renewcommand{\glsxtrbookindexsubname}[1]{% + \glossentryname{#1}% +} +\end{verbatim} + +Then if you're using \sty{fancyhdr} you can set the page style +to show the first and last entry for the current page with: +\begin{verbatim} + \pagestyle{fancy}% + \lhead{\thepage}% + \lfoot{\glsxtrbookindexfirstmark}% + \cfoot{}% + \rfoot{\glsxtrbookindexlastmark}% +\end{verbatim} + +\section{\styfmt{glossary-longextra} package} +\label{sec:longextra} + +As from version 1.37, the \styfmt{glossaries-extra} package comes +with the supplementary package \sty{glossary-longextra} that +provides additional styles, listed below, that use the +\env{longtable} environment. If you know that your glossary won't +span more than a page and you need to use it in a context that's +incompatible with \env{longtable}, you can instead setup these styles +to use \env{tabular} instead. In order to do this you must use +\begin{definition}[\DescribeMacro\GlsLongExtraUseTabulartrue] +\cs{GlsLongExtraUseTabulartrue} \end{definition} -This is simply a shortcut for: -\begin{alltt} -\cs{csdef}\{glsxtrpostname\meta{category}\}\marg{definition} -\end{alltt} -Note that it doesn't check if the command has already been defined. +\emph{before the style is set}. For example: +\begin{verbatim} +\GlsLongExtraUseTabulartrue +\setglossarystyle{long-name-desc} +\end{verbatim} +or +\begin{verbatim} +\GlsLongExtraUseTabulartrue +\printunsrtglossary[style={long-name-desc}] +\end{verbatim} +If you use this setting, you can change the default vertical +alignment with: +\begin{definition}[\DescribeMacro\glslongextraTabularVAlign] +\cs{glslongextraTabularVAlign} +\end{definition} +The default definition is \texttt{c}. -As from version 1.25, the post-name hook also does -\begin{definition}[\DescribeMacro\glsextrapostnamehook] -\cs{glsextrapostnamehook}\marg{label} +The column titles are formatted according to: +\begin{definition}[\DescribeMacro\glslongextraHeaderFmt] +\cs{glslongextraHeaderFmt}\marg{text} \end{definition} -(before \cs{glsxtrpostname}\meta{category}) -to allow for additional non-category related code. This does nothing -by default. +which simply does \cs{textbf}\marg{text} by default. -The post-description code used within the glossary is modified so -that it also does -\begin{definition}[\DescribeMacro\glsxtrpostdescription] -\cs{glsxtrpostdescription} +The name column has the title given by \ics{entryname} and +the column alignment is given by: +\begin{definition}[\DescribeMacro\glslongextraNameAlign] +\cs{glslongextraNameAlign} \end{definition} -This occurs before the original \cs{glspostdescription}, so if the -\pkgopt[false]{nopostdot} option is used, it will be inserted before -the terminating full stop. +which expands to \texttt{l} (left) by default. -This new command will do \cs{glsxtrpostdesc\meta{category}} -if it exists, where \meta{category} is the category label associated -with the current entry. For example \cs{glsxtrpostdescgeneral} -for entries with the category set to \category{general} -or \cs{glsxtrpostdescacronym} for entries with the category set to -\category{acronym}. -For convenience, as from v1.31, you can use -\begin{definition}[\DescribeMacro\glsdefpostdesc] -\cs{glsdefpostdesc}\marg{category}\marg{definition} +The symbol column (where applicable) has the title given by +\ics{symbolname} and the column alignment is given by: +\begin{definition}[\DescribeMacro\glslongextraSymbolAlign] +\cs{glslongextraSymbolAlign} \end{definition} -This is simply a shortcut for: +which expands to \texttt{c} (centred) by default. + +The location list column (where applicable) has the title given by +\ics{pagelistname} and the column alignment is given by: +\begin{definition}[\DescribeMacro\glslongextraLocationAlign] +\cs{glslongextraLocationAlign} +\end{definition} +which expands to +\begin{verbatim} +>{\raggedright}p{\glspagelistwidth} +\end{verbatim} +by default. (Ragged-right paragraph, \ics{glspagelistwidth} is +defined in \sty{glossary-long}, which is automatically loaded.) + +The description column has the title given by \ics{descriptionname} +and the column alignment is given by: +\begin{definition}[\DescribeMacro\glslongextraDescAlign] +\cs{glslongextraDescAlign} +\end{definition} +which expands to +\begin{verbatim} +>{\raggedright}p{\glsdescwidth} +\end{verbatim} +by default. (Ragged-right paragraph, \ics{glsdescwidth} is +defined in \sty{glossary-long}, which is automatically loaded.) + +Unlike the long styles provided by the base \styfmt{glossaries} +package, these new styles try to determine the value of +\cs{glsdescwidth} at the start of the glossary according to the +number of columns provided by the style. The calculations are +performed by the following commands: +\begin{definition}[\DescribeMacro\glslongextraSetDescWidth] +\cs{glslongextraSetDescWidth} +\end{definition} +This is used by the styles that have a name and description +column. The value of \cs{glsdescwidth} is computed as: +\[ + \cs{glsdescwidth} = \cs{linewidth} - 4\cs{tabcolsep} - W +\] +where $W$ is a guess at the width of the name column. This is first +set to the width of the name column header: \begin{alltt} -\cs{csdef}\{glsxtrpostdesc\meta{category}\}\marg{definition} +\cs{settowidth}\marg{width}\{\cs{glslongextraHeaderFmt}\cs{entryname}\} \end{alltt} -Note that it doesn't check if the command has already been defined. +If any names in that column are larger than this, then you need +to specify the widest name using: +\begin{definition}[\DescribeMacro\glslongextraSetWidest] +\cs{glslongextraSetWidest}\marg{widest name} +\end{definition} +or +\begin{definition}[\DescribeMacro\glslongextraUpdateWidest] +\cs{glslongextraUpdateWidest}\marg{text} +\end{definition} +These work like the analogous commands \cs{glssetwidest} and +\cs{glsupdatewidest} provided with the \glostyle{alttree} style, but +in this case there's no hierarchy. The default widest name +is obtained from the \glostyle{alttree} top-level name if set, +otherwise it's empty, so you can use \gls{bib2gls}['s] +\texttt{set-widest} option. If you have the entry counter enabled, +you will need to include this with the name for the extra material to +be taken into account. -Since both \cs{glossentry} and \cs{subglossentry} set -\begin{definition}[\DescribeMacro\glscurrententrylabel] -\cs{glscurrententrylabel} +The name isn't shown for child entries by default, but if +you change this and you want to use \gls{bib2gls}['s] +\texttt{set-widest} option (for \gls{bib2gls} v1.8+) then you need to +redefine: +\begin{definition}[\DescribeMacro\glslongextraUpdateWidestChild] +\cs{glslongextraUpdateWidestChild}\marg{level}\marg{text} \end{definition} -to the label for the current entry, you can use this within the -definition of these post-description hooks if you need to reference -the label. +This does nothing by default, but if you are including the child +names then you need to redefine this command: +\begin{verbatim} +\renewcommand{\glslongextraUpdateWidestChild}[2]{% + \glslongextraUpdateWidest{#2}% +} +\end{verbatim} -For example, suppose you want to insert the plural form in brackets -after the description in the glossary, but only for entries in the -\category{general} category, then you could do: +If you prefer to set an explicit width for the description +column then you need to redefine \cs{glslongextraSetDescWidth}. For +example: \begin{verbatim} -\renewcommand{\glsxtrpostdescgeneral}{\space - (plural: \glsentryplural{\glscurrententrylabel})} +\renewcommand{\glslongextraSetDescWidth}{% + \setlength{\glsdescwidth}{0.6\linewidth}% +} \end{verbatim} -This means you don't have to define a custom glossary style, which -you may find more complicated. (It also allows more flexibility if -you decide to change the underlying glossary style.) -\begin{important} -This feature can't be used for glossary styles that ignore -\cs{glspostdescription} or if you redefine -\cs{glspostdescription} without including \cs{glsxtrpostdescription}. -(For example, if you redefine \cs{glspostdescription} to do -nothing instead of using the \pkgopt{nopostdot} option to suppress -the terminating full stop.) See \sectionref{sec:stylemods} to patch -the predefined styles provided by \styfmt{glossaries} that are missing -\cs{glspostdescription}. -\end{important} +The styles that have a name, symbol and description, +\cs{glsdescwidth} is set with: +\begin{definition}[\DescribeMacro\glslongextraSymSetDescWidth] +\cs{glslongextraSymSetDescWidth} +\end{definition} +This first uses \cs{glslongextraSetDescWidth} and then subtracts +2\cs{tabcolsep} and the width of the symbol column header from +\cs{glsdescwidth}. This assumes that the symbol column header +is larger than any of the symbols. If this isn't appropriate +then you can redefine this command. For example: +\begin{verbatim} +\renewcommand{\glslongextraSymSetDescWidth}{% + \glslongextraSetDescWidth + \addtolength{\glsdescwidth}{-3cm}% +} +\end{verbatim} +or +\begin{verbatim} +\renewcommand{\glslongextraSymSetDescWidth}{% + \setlength{\glsdescwidth}{.5\linewidth}% +} +\end{verbatim} -\subsection{Number List} -\label{sec:glosstylenumlist} +For the styles that have a name, description and location column, +\cs{glsdescwidth} is set using: +\begin{definition}[\DescribeMacro\glslongextraLocSetDescWidth] +\cs{glslongextraLocSetDescWidth} +\end{definition} +This uses \cs{glslongextraSetDescWidth} and then subtracts +2\cs{tabcolsep} and \cs{glspagelistwidth} from \cs{glsdescwidth}. +You can redefine this command to set both \cs{glsdescwidth} and +\cs{glspagelistwidth} if appropriate. -The \gls{numberlist} is now placed inside the argument of -\begin{definition}[\DescribeMacro\GlsXtrFormatLocationList] -\cs{GlsXtrFormatLocationList}\marg{number list} +For the styles that have a name, description, symbol and location +column, \cs{glsdescwidth} is set using: +\begin{definition}[\DescribeMacro\glslongextraSymLocSetDescWidth] +\cs{glslongextraSymLocSetDescWidth} \end{definition} -This is internally used by \cs{glossaryentrynumbers}. The -\pkgopt{nonumberlist} option redefines \cs{glossaryentrynumbers} so that it -doesn't display the \gls{numberlist}, but it still saves the -\gls{numberlist} in case it's required. +This uses \cs{glslongextraSymSetDescWidth} and then subtracts +2\cs{tabcolsep} and \cs{glspagelistwidth} from +\cs{glsdescwidth}. Again, you can redefine this command +to explicitly set both lengths. -\begin{important} -If you want to suppress the \gls{numberlist} always use the -\pkgopt{nonumberlist} option instead of redefining -\cs{glossaryentrynumbers} to do nothing. -\end{important} +In all cases, the top-level name is formatted according to: +\begin{definition}[\DescribeMacro\glslongextraNameFmt] +\cs{glslongextraNameFmt}\marg{label} +\end{definition} +This does +\begin{alltt} +\cs{glsentryitem}\marg{label}\cs{glstarget}\marg{label}\{\cs{glossentryname}\marg{label}\} +\end{alltt} +which includes the entry counter (if enabled), the target and the post-name link. -If you want to, for example, change the font for the entire -\gls{numberlist} then redefine \cs{GlsXtrFormatLocationList} as -appropriate. Don't modify \cs{glossaryentrynumbers}. +The top-level description is formatted according to: +\begin{definition}[\DescribeMacro\glslongextraDescFmt] +\cs{glslongextraDescFmt}\marg{label} +\end{definition} +This does \cs{glossentrydesc}\marg{label} followed by the +post-description hook. -Sometimes users like to insert \qt{page} or \qt{pages} in front of -the \gls{numberlist}. This is quite fiddly to do with the base -\styfmt{glossaries} package, but \styfmt{glossaries-extra} -provides a way of doing this. First you need to enable this -option and specify the text to display using: -\begin{definition}[\DescribeMacro\GlsXtrEnablePreLocationTag] -\cs{GlsXtrEnablePreLocationTag}\marg{page}\marg{pages} +The styles that have a symbol column format the symbol using: +\begin{definition}[\DescribeMacro\glslongextraSymbolFmt] +\cs{glslongextraSymbolFmt}\marg{label} \end{definition} -where \meta{page} is the text to display if the \gls{numberlist} only -contains a single location and \meta{pages} is the text to display -otherwise. For example: -\begin{verbatim} -\GlsXtrEnablePreLocationTag{Page: }{Pages: } -\end{verbatim} -An extra run is required when using this command. +This just does \cs{glossentrysymbol}\marg{label}. -\begin{important} -Use \texttt{glsignore} not \texttt{@gobble} as the format if you -want to suppress the page number (and only index the entry once). -\end{important} +The styles that have a location list column format the list using: +\begin{definition}[\DescribeMacro\glslongextraLocationFmt] +\cs{glslongextraLocationFmt}\marg{label}\marg{locations} +\end{definition} +This just does \meta{locations} and ignores the label. -See the accompanying sample file \texttt{sample-pages.tex}. +The child entries have their name formatted according to: +\begin{definition}[\DescribeMacro\glslongextraSubNameFmt] +\cs{glslongextraSubNameFmt}\marg{level}\marg{label} +\end{definition} +where \meta{level} is the hierarchical level. This defaults to: +\begin{alltt} +\cs{glssubentryitem}\marg{label}\cs{glstarget}\marg{label}\{\cs{strut}\} +\end{alltt} +This includes the sub-entry counter (if enabled) and the target +but doesn't show the name. The child description is formatted according to: +\begin{definition}[\DescribeMacro\glslongextraSubDescFmt] +\cs{glslongextraSubDescFmt}\marg{level}\marg{label} +\end{definition} +which defaults to just \cs{glslongextraDescFmt}\marg{label} -Note that \gls{bib2gls} can be instructed to insert -a prefix at the start of non-empty location lists, which -can be used as an alternative to \cs{GlsXtrEnablePreLocationTag}. +The child symbol is formatted (where appropriate) according to: +\begin{definition}[\DescribeMacro\glslongextraSubSymbolFmt] +\cs{glslongextraSubSymbolFmt}\marg{level}\marg{label} +\end{definition} +This just does \cs{glslongextraSymbolFmt}\marg{label} by default. -\subsection{The \styfmt{glossaries-extra-stylemods} Package} -\label{sec:stylemods} +The styles that have a location list column format the list for +child entries using: +\begin{definition}[\DescribeMacro\glslongextraLocationFmt] +\cs{glslongextraSubLocationFmt}\meta{level}\marg{label}\marg{locations} +\end{definition} +This just does \meta{locations} and ignores the level and label. -As from v1.02, \styfmt{glossaries-extra} now includes the package -\sty{glossaries-extra-stylemods} that will redefine the predefined -styles to include the post-description hook (for those that are -missing it). You will need to make sure the styles have already -been defined before loading \styfmt{glossaries-extra}. For example: -\begin{verbatim} -\usepackage{glossaries-extra} -\usepackage{glossary-longragged} -\usepackage{glossaries-extra-stylemods} -\end{verbatim} -Alternatively you can load -\texttt{glossary-}\meta{name}\texttt{.sty} at the same time by -passing \meta{name} as a package option to -\sty{glossaries-extra-stylemods}. For example: -\begin{verbatim} -\usepackage{glossaries-extra} -\usepackage[longragged]{glossaries-extra-stylemods} -\end{verbatim} -Another option is to use the \pkgopt{stylemods} key when you -load \styfmt{glossaries-extra}. You can omit a value if you only want to use -the predefined styles that are automatically loaded by -\styfmt{glossaries} (for example, the \glostyle{long3col} style): -\begin{verbatim} -\usepackage[style=long3col,stylemods]{glossaries-extra} -\end{verbatim} -Or the value of \pkgopt{stylemods} may be a comma-separated list -of the style package identifiers. For example: -\begin{verbatim} -\usepackage[style=mcoltree,stylemods=mcols]{glossaries-extra} -\end{verbatim} -Remember to group the value if it contains any commas: +The letter group headings are formatted according to: +\begin{definition}[\DescribeMacro\glslongextraGroupHeading] +\cs{glslongextraGroupHeading}\marg{n}\marg{label} +\end{definition} +which does nothing by default. The first argument \meta{n} is the +number of columns in the table. The second argument \meta{label} +is the group label (not the title, although they may happen +to be the same). + +This can be redefined to show the group heading. For example: \begin{verbatim} -\usepackage[stylemods={mcols,longbooktabs}]{glossaries-extra} +\renewcommand*{\glslongextraGroupHeading}[2]{% + \glsxtrgetgrouptitle{#2}{\thisgrptitle}% + \glslongextraHeaderFmt{\thisgrptitle}% + \tabularnewline + \noalign{\vskip\normalbaselineskip}% +} \end{verbatim} +This ignores the first argument and just puts the group +title in the first column formatted according to +\cs{glslongextraHeaderFmt} (to match the column header). -Note that the \glostyle{inline} style is dealt with slightly -differently. The original definition provided by the -\sty{glossary-inline} package uses \cs{glspostdescription} at the -end of the glossary (not after each entry description) within the -definition of \cs{glspostinline}. The style modification changes -this so that \cs{glspostinline} just does a full stop followed by -space factor adjustment, and the description -\cs{glsinlinedescformat} and sub-entry description formats -\cs{glsinlinesubdescformat} are redefined to include -\cs{glsxtrpostdescription} (not \cs{glspostdescription}). This means -that the modified \glostyle{inline} style isn't affected by the -\pkgopt{nopostdot} option, but the post-description category hook -can still be used. +Remember that you can also adjust the styles through category +attributes. The name column's title is given by +\cs{entryname}, the description column's title is given by +\cs{descriptionname} and (where present) the symbol column's +title is given by \cs{symbolname}, as for the other long styles +that have headers. -The \env{tabular}-like styles, such as \glostyle{long} are -adjusted so that the \ics{ifglsnogroupskip} conditional (set with -\pkgopt{nogroupskip}) is moved outside of the definition of -\cs{glsgroupskip} to avoid problems that cause an \qt{Incomplete -\cs{iftrue}} error with \cs{printunsrtglossary} and -\cs{printnoidxglossary}. This means that if you want to change this -conditional using \cs{setupglossaries} or using the -\gloskey[printglossary]{nogroupskip} option in \cs{printglossary}, -\cs{printnoidxglossary} or \cs{printunsrtglossary}, you must also -reset the glossary style. +\begin{description} +\item{\glostyle{long-name-desc}} This is like the +\glostyle{longragged-booktabs} style but doesn't show the location +list (regardless of the \pkgopt{nonumberlist} option). The name is +shown in the first column and the description in the second. -As from version 1.21, the hard-coded \cs{space} before the -\gls{numberlist} in many of the predefined styles is replaced -with -\begin{definition}[\DescribeMacro\glsxtrprelocation] -\cs{glsxtrprelocation} +The symbol is not displayed. The header +row is produced with: +\begin{definition}[\DescribeMacro\glslongextraNameDescHeader] +\cs{glslongextraNameDescHeader} \end{definition} -This just defaults to \cs{space} but may be redefined as required. -For example: +This essentially uses the same code as for \glostyle{longragged-booktabs} +but makes it easier to adjust the header without having to define a +new style. This is defined as: \begin{verbatim} -\renewcommand{\glsxtrprelocation}{\dotfill} +\glslongextraNameDescTabularHeader\endhead +\glslongextraNameDescTabularFooter\endfoot \end{verbatim} +where: +\begin{definition}[\DescribeMacro\glslongextraNameDescTabularHeader] +\cs{glslongextraNameDescTabularHeader} +\end{definition} +sets up the header and +\begin{definition}[\DescribeMacro\glslongextraNameDescTabularFooter] +\cs{glslongextraNameDescTabularFooter} +\end{definition} +sets up the footer. If you have setup the \env{tabular} version +of this style then the above two commands are used at the +start and end of the \env{tabular} environment (and +\cs{glslongextraNameDescHeader} isn't used). -The \glostyle{list} styles use -\begin{definition}[\DescribeMacro\glslistprelocation] -\cs{glslistprelocation} +For example, to simply remove the header and footer (for the default +\env{longtable} version of the style): +\begin{verbatim} +\renewcommand{\glslongextraNameDescHeader}{} +\end{verbatim} +Or to change the name alignment to centred: +\begin{verbatim} +\renewcommand{\glslongextraNameAlign}{c} +\end{verbatim} + +\item{\glostyle{long-name-desc-loc}} This is like the +\glostyle{long-name-desc} style but has a third column for the +location list. The \env{longtable} header is given by: +\begin{definition}[\DescribeMacro\glslongextraNameDescLocationHeader] +\cs{glslongextraNameDescLocationHeader} \end{definition} -(which defaults to \cs{glsxtrprelocation}) for top-level items and -\begin{definition}[\DescribeMacro\glslistchildprelocation] -\cs{glslistchildprelocation} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraNameDescLocationTabularHeader] +\cs{glslongextraNameDescLocationTabularHeader} +\end{definition} +and +\begin{definition}[\DescribeMacro\glslongextraNameDescLocationTabularFooter] +\cs{glslongextraNameDescLocationTabularFooter} \end{definition} -(which defaults to \cs{glslistprelocation}) for child items. -As from v1.31, the description (including the post-description hook) -is governed by: -\begin{definition}[\DescribeMacro\glslistdesc] -\cs{glslistdesc}\marg{label} +\item{\glostyle{long-desc-name}} This is like the +\glostyle{long-name-desc} style but swaps the columns. Note that +if the entry counter is displayed it will appear at the start +of the second column by default. The \env{longtable} header is formatted according +to: +\begin{definition}[\DescribeMacro\glslongextraDescNameHeader] +\cs{glslongextraDescNameHeader} +\end{definition} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraDescNameTabularHeader] +\cs{glslongextraDescNameTabularHeader} +\end{definition} +and +\begin{definition}[\DescribeMacro\glslongextraDescNameTabularFooter] +\cs{glslongextraDescNameTabularFooter} \end{definition} -for the \glostyle{list} and \glostyle{altlist} styles (but not the -\glostyle{listdotted} variations). -For just the \glostyle{list} style and its letter group variations -(not the \glostyle{altlist} or \glostyle{listdotted} variations) the -\gls{numberlist} for child entries is followed by -\begin{definition}[\DescribeMacro\glslistchildpostlocation] -\cs{glslistchildpostlocation} +\item{\glostyle{long-loc-desc-name}} This has three columns +containing the location list, description and name. The +\env{longtable} header +is formatted according to: +\begin{definition}[\DescribeMacro\glslongextraLocationDescNameHeader] +\cs{glslongextraLocationDescNameHeader} +\end{definition} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraLocationDescNameTabularHeader] +\cs{glslongextraLocationDescNameTabularHeader} +\end{definition} +and +\begin{definition}[\DescribeMacro\glslongextraLocationDescNameTabularFooter] +\cs{glslongextraLocationDescNameTabularFooter} \end{definition} -which defaults to a full stop. -The default value of \ics{glslistdottedwidth} is changed so that -it's set at the start of the document (if it hasn't been changed in -the preamble). This should take into account situations where -\cs{hsize} isn't set until the start of the document. +\item{\glostyle{long-name-desc-sym}} This is has three columns, with +the name in the first, the description in the second and the symbol +in the third. -The separator between groups (if not \pkgopt{nogroupskip}) is now -given by: -\begin{definition}[\DescribeMacro\glslistgroupskip] -\cs{glslistgroupskip} +The \env{longtable} header row is produced with: +\begin{definition}[\DescribeMacro\glslongextraNameDescSymHeader] +\cs{glslongextraNameDescSymHeader} \end{definition} -This defaults to \cs{indexspace} with penalties to deter page -breaks. -This command isn't used if \pkgopt{nogroupskip} is set. - -The \sty{glossary-tree} package introduced two new commands in -\sty{glossaries} version 4.22, \ics{glstreegroupheaderfmt} -and \ics{glstreenavigationfmt}, which are used to format -the letter group headings and the navigation elements for the -appropriate styles. These two new commands are defined in terms of -\ics{glstreenamefmt} since that was the command originally used -for the group headings and navigation. This now allows these -different elements to be defined independently, but the most common -redefinition is for \cs{glstreenamefmt} to remove the bold in the -name. If the bold is still required for the group heading and navigation -elements, then both other commands also need redefining. To simplify -matters, if \cs{glstreenamefmt} has been defined, as from v1.31 -\sty{glossaries-extra-stylemods} defines: -\begin{definition}[\DescribeMacro\glstreedefaultnamefmt] -\cs{glstreedefaultnamefmt}\marg{text} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraNameDescSymTabularHeader] +\cs{glslongextraNameDescSymTabularHeader} \end{definition} -which simply does \cs{textbf}\marg{text} and redefines -\cs{glstreenamefmt}, \cs{glstreegroupheaderfmt} and -\cs{glstreenavigationfmt} all in terms of -\cs{glstreedefaultnamefmt}. This means that if you want to change -all three to use a particular style you only need to redefine -\cs{glstreedefaultnamefmt}, but if you only want to redefine -\cs{glstreenamefmt} without affecting the other two commands, then -you now can. - -The separator between groups (if not \pkgopt{nogroupskip}) is now -given by: -\begin{definition}[\DescribeMacro\glstreegroupskip] -\cs{glstreegroupskip} +and +\begin{definition}[\DescribeMacro\glslongextraNameDescSymTabularFooter] +\cs{glslongextraNameDescSymTabularFooter} \end{definition} -This defaults to \cs{indexspace} with penalties to deter page -breaks. -This command isn't used if \pkgopt{nogroupskip} is set (except for -the styles that display the group titles). -The styles that display the group titles now use: -\begin{definition}[\DescribeMacro\glstreePreHeader] -\cs{glstreePreHeader}\marg{label}\marg{title} -\end{definition} -where \meta{label} is the group label and \meta{title} is the group -title. This does nothing by default -and is inserted before the group title. You can redefine it to add -the group title to the PDF bookmarks. For example, if the -glossary title uses \cs{chapter} then: -\begin{verbatim} -\renewcommand{\glstreePreHeader}[2]{% - \pdfbookmark[1]{#2}{\currentglossary.#1}% -} -\end{verbatim} -will insert section-level bookmarks. The use of \cs{currentglossary} -helps to provide unique bookmark labels in the event of multiple -glossaries. +\item{\glostyle{long-name-desc-sym-loc}} This is has four columns, with +the name in the first, the description in the second, the symbol +in the third and the location list in the fourth. -The \glostyle{index}-like and \glostyle{tree}-like styles -insert the pre-\gls{numberlist} space with -\begin{definition}[\DescribeMacro\glstreeprelocation] -\cs{glstreeprelocation} +The \env{longtable} header row is produced with: +\begin{definition}[\DescribeMacro\glslongextraNameDescSymLocationHeader] +\cs{glslongextraNameDescSymLocationHeader} \end{definition} -(which defaults to \cs{glsxtrprelocation}) for top-level items and -\begin{definition}[\DescribeMacro\glstreechildprelocation] -\cs{glstreechildprelocation} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraNameDescSymLocationTabularHeader] +\cs{glslongextraNameDescSymLocationTabularHeader} +\end{definition} +and +\begin{definition}[\DescribeMacro\glslongextraNameDescSymLocationTabularFooter] +\cs{glslongextraNameDescSymLocationTabularFooter} \end{definition} -(which defaults to \cs{glstreeprelocation}) for child items. -As from version 1.31, the \styfmt{glossaries-extra-stylemods} -package also provides: -\begin{definition}[\DescribeMacro\glstreenonamedesc] -\cs{glstreenonamedesc}\marg{label} +\item{\glostyle{long-name-sym-desc}} This is like the +\glostyle{long-name-desc-sym} but the second and third column are +swapped. The \env{longtable} header row is given by: +\begin{definition}[\DescribeMacro\glslongextraNameSymDescHeader] +\cs{glslongextraNameSymDescHeader} \end{definition} -which is used by the \glostyle{treenoname} styles to display the -pre-description separator, the description and the post-description -hook. Similarly for the symbol: -\begin{definition}[\DescribeMacro\glstreenonamesymbol] -\cs{glstreenonamesymbol}\marg{label} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraNameSymDescTabularHeader] +\cs{glslongextraNameSymDescTabularHeader} \end{definition} -The above are just used for top-level entries. Child entries don't -have the name or symbol displayed for the \glostyle{treenoname} -styles, so there's only a command for the child description: -\begin{definition}[\DescribeMacro\glstreenonamechilddesc] -\cs{glstreenonamechilddesc}\marg{label} +and +\begin{definition}[\DescribeMacro\glslongextraNameSymDescTabularFooter] +\cs{glslongextraNameSymDescTabularFooter} \end{definition} -For the \glostyle{tree} styles (but not the \glostyle{treenoname} or -\glostyle{alttree} styles), the description is displayed using: -\begin{definition}[\DescribeMacro\glstreedesc] -\cs{glstreedesc}\marg{label} -\end{definition} -and the symbol with: -\begin{definition}[\DescribeMacro\glstreesymbol] -\cs{glstreesymbol}\marg{label} +\item{\glostyle{long-name-sym-desc-loc}} This is like the +\glostyle{long-name-desc-sym-loc} but the second and third column are +swapped. The \env{longtable} header row is given by: +\begin{definition}[\DescribeMacro\glslongextraNameSymDescLocationHeader] +\cs{glslongextraNameSymDescLocationHeader} \end{definition} -Again the above two commands are just for top-level entries. The -child entries use: -\begin{definition}[\DescribeMacro\glstreechilddesc] -\cs{glstreechilddesc}\marg{label} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraNameSymDescLocationTabularHeader] +\cs{glslongextraNameSymDescLocationTabularHeader} \end{definition} -for the description and -\begin{definition}[\DescribeMacro\glstreechildsymbol] -\cs{glstreechildsymbol}\marg{label} +and +\begin{definition}[\DescribeMacro\glslongextraNameSymDescLocationTabularFooter] +\cs{glslongextraNameSymDescLocationTabularFooter} \end{definition} -for the symbol. -As from version 1.41, there are now wrapper commands for -\cs{glstreedesc} and \cs{glstreechilddesc} that check for -the description and symbol to determine whether or not to insert a -space (\cs{glstreeprelocation} or \cs{glstreechildprelocation}) -before the page list. These are: -\begin{definition}[\DescribeMacro\glstreeDescLoc] -\cs{glstreeDescLoc}\marg{label}\marg{location} +\item{\glostyle{long-sym-desc-name}} This has the symbol in the +first column, the description in the second and the name in the +third. The \env{longtable} header row is given by: +\begin{definition}[\DescribeMacro\glslongextraSymDescNameHeader] +\cs{glslongextraSymDescNameHeader} \end{definition} -for top-level entries and -\begin{definition}[\DescribeMacro\glstreeChildDescLoc] -\cs{glstreeChildDescLoc}\marg{label}\marg{location} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraSymDescNameTabularHeader] +\cs{glslongextraSymDescNameTabularHeader} \end{definition} -for sub-entries. This prevents a spurious space for terms that don't -have a symbol or description but do have a location list (for -example, aliases). - -As from version 1.05, the \styfmt{glossaries-extra-stylemods} -package provides some additional commands for use with the -\glostyle{alttree} style to make it easier to modify. -These commands are only defined if the -\sty{glossary-tree} package has already been loaded, which is -typically the case unless the \pkgopt{notree} option has been used -when loading \styfmt{glossaries}. - -\begin{definition}[\DescribeMacro\gglssetwidest] -\cs{gglssetwidest}\oarg{level}\marg{name} +and +\begin{definition}[\DescribeMacro\glslongextraSymDescNameTabularFooter] +\cs{glslongextraSymDescNameTabularFooter} \end{definition} -(New to version 1.21.) -This is like \cs{glssetwidest} (provided by \sty{glossary-tree}) -but performs a global assignment. -\begin{definition}[\DescribeMacro\eglssetwidest] -\cs{eglssetwidest}\oarg{level}\marg{name} +\item{\glostyle{long-loc-sym-desc-name}} This has the location list +in the first column, symbol in the +second column, the description in the third and the name in the +fourth. The \env{longtable} header row is given by: +\begin{definition}[\DescribeMacro\glslongextraLocationSymDescNameHeader] +\cs{glslongextraLocationSymDescNameHeader} \end{definition} -This is like \cs{glssetwidest} -but performs a protected expansion on \meta{name}. This has -a localised effect. For a global setting, use -\begin{definition}[\DescribeMacro\xglssetwidest] -\cs{xglssetwidest}\oarg{level}\marg{name} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraLocationSymDescNameTabularHeader] +\cs{glslongextraLocationSymDescNameTabularHeader} \end{definition} -The following only set the value if \meta{name} is wider than the -current value (new to version 1.23). Local update: -\begin{definition}[\DescribeMacro\glsupdatewidest] -\cs{glsupdatewidest}\oarg{level}\marg{name} +and +\begin{definition}[\DescribeMacro\glslongextraLocationSymDescNameTabularFooter] +\cs{glslongextraLocationSymDescNameTabularFooter} \end{definition} -Global update: -\begin{definition}[\DescribeMacro\gglsupdatewidest] -\cs{gglsupdatewidest}\oarg{level}\marg{name} + +\item{\glostyle{long-desc-sym-name}} This has the description in the +first column, the symbol in the second and the name in the +third. The \env{longtable} header row is given by: +\begin{definition}[\DescribeMacro\glslongextraDescSymNameHeader] +\cs{glslongextraDescSymNameHeader} \end{definition} -Locale update (expands \meta{name}): -\begin{definition}[\DescribeMacro\eglsupdatewidest] -\cs{eglsupdatewidest}\oarg{level}\marg{name} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraDescSymNameTabularHeader] +\cs{glslongextraDescSymNameTabularHeader} \end{definition} -Global update (expands \meta{name}): -\begin{definition}[\DescribeMacro\xglsupdatewidest] -\cs{xglsupdatewidest}\oarg{level}\marg{name} +and +\begin{definition}[\DescribeMacro\glslongextraDescSymNameTabularFooter] +\cs{glslongextraDescSymNameTabularFooter} \end{definition} - -The widest entry value can later be retrieved using -\begin{definition}[\DescribeMacro\glsgetwidestname] -\cs{glsgetwidestname} +\item{\glostyle{long-loc-desc-sym-name}} This has the location list +in the first column, the description in the +second column, the symbol in the third and the name in the +fourth. The \env{longtable} header row is given by: +\begin{definition}[\DescribeMacro\glslongextraLocationDescSymNameHeader] +\cs{glslongextraLocationDescSymNameHeader} \end{definition} -for the top-level entries and -\begin{definition}[\DescribeMacro\glsgetwidestsubname] -\cs{glsgetwidestsubname}\marg{level} +which similarly defined in terms of the commands used for the +\env{tabular} version: +\begin{definition}[\DescribeMacro\glslongextraLocationDescSymNameTabularHeader] +\cs{glslongextraLocationDescSymNameTabularHeader} +\end{definition} +and +\begin{definition}[\DescribeMacro\glslongextraLocationDescSymNameTabularFooter] +\cs{glslongextraLocationDescSymNameTabularFooter} \end{definition} -for sub-entries, where \meta{level} is the level number. -Note that if you are using \gls{bib2gls}, you can use the -resource option \texttt{set-widest} which will try to determine the -widest name of all the selected entries. This isn't guaranteed -to work as it may depend on fonts or commands that \gls{bib2gls} -can't replicate, but it should be suitable for names that just -consist of text, and can be more efficient than iterating over all -the defined entries using \TeX. +\end{description} -The command \cs{glsfindwidesttoplevelname} provided by -\sty{glossary-tree} has a CamelCase synonym: -\begin{definition}[\DescribeMacro\glsFindWidestTopLevelName] -\cs{glsFindWidestTopLevelName}\oarg{glossary list} +\section{\styfmt{glossary-topic} package} +\label{sec:topic} + +As from version 1.40, the \styfmt{glossaries-extra} package comes +with the supplementary package \sty{glossary-topic} that +provides glossary styles designed for hierarchical glossaries +where the top-level entries are topic titles. This package +automatically loads the \sty{multicols} package. If the +\sty{glossary-tree} package is also loaded then commands like +\cs{glssetwidest} can be used on these styles in much the same way +as for the \glostyle{alttree} style. If a widest value isn't set +then these styles behave more like the \glostyle{tree} style. +\begin{description} +\item[\glostyle{topic}] This style is similar to the \glostyle{tree} +style but the indentation doesn't start until the second +sub-item level. The top-level entries have the name displayed +in a larger font with the description following in a new paragraph. +This style doesn't support the \pkgopt{nogroupskip} setting. + +\item[\glostyle{topicmcols}] This style is like the \glostyle{topic} +style but the sub-entries are placed inside a \env{multicols} +environment. The environment name is supplied in the value of +the command: +\begin{definition}[\DescribeMacro\glstopicColsEnv] +\cs{glstopicColsEnv} \end{definition} -Similar commands are also provided: -\begin{definition}[\DescribeMacro\glsFindWidestUsedTopLevelName] -\cs{glsFindWidestUsedTopLevelName}\oarg{glossary list} +You can change this to the starred form. For example: +\begin{verbatim} +\renewcommand{\glstopicColsEnv}{multicols*} +\end{verbatim} +The number of columns is given by the command: +\begin{definition}[\DescribeMacro\glstopicCols] +\cs{glstopicCols} \end{definition} -This has an additional check that the entry has been used. -Naturally this is only useful if the glossaries that use -the \glostyle{alttree} style occur at the end of the document. -This command should be placed just before the start of the glossary. -(Alternatively, place it at the end of the document and save -the value in the auxiliary file for the next run.) +The default value is 2. +\end{description} +Both styles use the following commands. +\begin{definition}[\DescribeMacro\glstopicParIndent] +\cs{glstopicParIndent} +\end{definition} +This command is a length that's used for the paragraph indentation +in any multi-paragraph description for top-level entries, but not +for the first paragraph (at the start of the description) which +isn't indented. -\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyName] -\cs{glsFindWidestUsedAnyName}\oarg{glossary list} +\begin{definition}[\DescribeMacro\glstopicSubIndent] +\cs{glstopicSubIndent} \end{definition} -This is like the previous command but if doesn't check the -\gloskey{parent} key. This is useful if all levels should have the -same width for the name. +This command is a length that's used to calculate the hanging +indentation for sub-entries. The level~1 sub-entries don't indent +the name. Level~$n$ sub-entries have the name indented by +$(n-1)\times$\cs{glstopicSubIndent}. The hanging indent depends +on whether or not a widest name has been set for the level. -\begin{definition}[\DescribeMacro\glsFindWidestAnyName] -\cs{glsFindWidestAnyName}\oarg{glossary list} +\begin{definition}[\DescribeMacro\glstopicInit] +\cs{glstopicInit} \end{definition} -This is like the previous command but doesn't check if the entry -has been used. +Hook used at the start of the glossary. Does nothing by default. -\begin{definition}[\DescribeMacro\glsFindWidestUsedLevelTwo] -\cs{glsFindWidestUsedLevelTwo}\oarg{glossary list} +Although the styles don't support letter groups by default, if you +have many topics (top-level entries) and you feel that it would help +the reader to divide them up into headed letter groups, you can +redefine: +\begin{definition}[\DescribeMacro\glstopicGroupHeading] +\cs{glstopicGroupHeading}\marg{group label} \end{definition} -This is like \cs{glsFindWidestUsedTopLevelName} but also sets -the first two sub-levels as well. Any entry that has a -great-grandparent is ignored. +This does nothing by default. If you want to redefine it, you can +fetch the title corresponding to the group label with +\cs{glsxtrgetgrouptitle}. For example: +\begin{verbatim} +\renewcommand*{\glstopicGroupHeading}[1]{% + \glsxtrgetgrouptitle{#1}{\thisgrptitle}% + \section*{\thisgrptitle}% +} +\end{verbatim} +Remember that if you use \gls{bib2gls}, you will need the +\verb|--group| (or \verb|-g|) switch to support this. -\begin{definition}[\DescribeMacro\glsFindWidestLevelTwo] -\cs{glsFindWidestLevelTwo}\oarg{glossary list} +\begin{definition}[\DescribeMacro\glstopicItem] +\cs{glstopicItem}\marg{label}\marg{location list} \end{definition} -This is like the previous command but doesn't check if the entry has -been used. +Used to format the name, symbol, description and location list +for the top-level entries. This starts with a paragraph break +followed by: +\begin{definition}[\DescribeMacro\glstopicPreSkip] +\cs{glstopicPreSkip} +\end{definition} +which defaults to \cs{medskip}. There is then a hook: +\begin{definition}[\DescribeMacro\glstopicMarker] +\cs{glstopicMarker}\marg{label} +\end{definition} +which does nothing by default, but may be redefined. For example, +to add a line to the table of contents. +The name and symbol are set in the +form of a title using: +\begin{definition}[\DescribeMacro\glstopicTitle] +\cs{glstopicTitle}\marg{label} +\end{definition} +This uses \cs{Glossentryname} which converts the first letter to +upper case. If there's a symbol, this is added in parentheses. +Both name and symbol (if present) are encapsulated by +\begin{definition}[\DescribeMacro\glstopicTitleFont] +\cs{glstopicTitleFont}\marg{text} +\end{definition} +This uses a bold, large font by default. -\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyNameSymbol] -\cs{glsFindWidestUsedAnyNameSymbol}\oarg{glossary -list}\marg{register} +If the entry has the description key set (tested with +\cs{ifglshasdesc}) then a paragraph break is inserted followed by: +\begin{definition}[\DescribeMacro\glstopicMidSkip] +\cs{glstopicMidSkip} +\end{definition} +which defaults to \cs{smallskip}. This is followed by the +description which is formatted according to: +\begin{definition}[\DescribeMacro\glstopicDesc] +\cs{glstopicDesc}\marg{label} \end{definition} -This is like \cs{glsFindWidestUsedAnyName} but also measures the -symbol. The length of the widest symbol is stored in -\meta{register}. +This just does \cs{Glossentrydesc}\marg{label} followed +by the post-description hook. -\begin{definition}[\DescribeMacro\glsFindWidestAnyNameSymbol] -\cs{glsFindWidestAnyNameSymbol}\oarg{glossary list}\marg{register} +A paragraph break followed by: +\begin{definition}[\DescribeMacro\glstopicPostSkip] +\cs{glstopicPostSkip} \end{definition} -This is like the previous command but it doesn't check if the entry -has been used. - -\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyNameSymbolLocation] -\cs{glsFindWidestUsedAnyNameSymbolLocation}\oarg{glossary -list}\marg{symbol register}\marg{location register} +comes next regardless of whether or not the description was +displayed. This defaults to \cs{smallskip}. This is then followed +by: +\begin{definition}[\DescribeMacro\glstopicLoc] +\cs{glstopicLoc}\marg{label}\marg{location list} \end{definition} -This is like \cs{glsFindWidestUsedAnyNameSymbol} but also -measures the \gls{numberlist}. This requires -\ics{glsentrynumberlist} (see the \styfmt{glossaries} user manual). -The length of the widest symbol is stored in \meta{symbol register} -and the length of the widest \gls*{numberlist} is stored in -\meta{location register}. +which may be used to display the location list, but does nothing by +default. -\begin{definition}[\DescribeMacro\glsFindWidestAnyNameSymbolLocation] -\cs{glsFindWidestAnyNameSymbolLocation}\oarg{glossary -list}\marg{symbol register}\marg{location register} +The sub-entries first set up the paragraph and hanging indentations +using: +\begin{definition}[\DescribeMacro\glstopicAssignSubIndent] +\cs{glstopicAssignSubIndent}\marg{level} \end{definition} -This is like the previous command but it doesn't check if the entry -has been used. - -\begin{definition}[\DescribeMacro\glsFindWidestUsedAnyNameLocation] -\cs{glsFindWidestUsedAnyNameLocation}\oarg{glossary -list}\marg{register} +This uses: +\begin{definition}[\DescribeMacro\glstopicAssignWidest] +\cs{glstopicAssignWidest}\marg{level} \end{definition} -This is like \cs{glsFindWidestUsedAnyNameSymbolLocation} but doesn't -measure the symbol. The length of the widest \gls{numberlist} -is stored in \meta{register}. +to determine if a widest name has been set for the given level. -\begin{definition}[\DescribeMacro\glsFindWidestAnyNameLocation] -\cs{glsFindWidestAnyNameLocation}\oarg{glossary -list}\marg{register} +The sub-entry has its information displayed using: +\begin{definition}[\DescribeMacro\glstopicSubItem] +\cs{glstopicSubItem}\marg{level}\marg{label}\marg{location} \end{definition} -This is like the previous command but doesn't check if the entry has -been used. - -The layout of the symbol, description and \gls{numberlist} -is governed by -\begin{definition}[\DescribeMacro\glsxtralttreeSymbolDescLocation] -\cs{glsxtralttreeSymbolDescLocation}\marg{label}\marg{number list} +This encapsulates the name with: +\begin{definition}[\DescribeMacro\glstopicSubNameFont] +\cs{glstopicSubNameFont}\marg{text} \end{definition} -for top-level entries and -\begin{definition}[\DescribeMacro\glsxtralttreeSubSymbolDescLocation] -\cs{glsxtralttreeSubSymbolDescLocation}\marg{label}\marg{number list} +By default this just uses \cs{textbf}. This is followed by: +\begin{definition}[\DescribeMacro\glstopicSubItemSep] +\cs{glstopicSubItemSep} \end{definition} -for sub-entries. - -There is now a user level command that performs the initialisation -for the \glostyle{alttree} style: -\begin{definition}[\DescribeMacro\glsxtralttreeInit] -\cs{glsxtralttreeInit} +which defaults to \cs{quad}. The name and separator are +passed in the \meta{text} argument of: +\begin{definition}[\DescribeMacro\glstopicSubItemBox] +\cs{glstopicSubItemBox}\marg{level}\marg{text} \end{definition} +If a widest name was set for the given level, this will +put \meta{text} inside a box of that width otherwise it just does +\meta{text}. -The paragraph indent for subsequent paragraphs in multi-paragraph -descriptions is provided by the length -\begin{definition}[\DescribeMacro\glsxtrAltTreeIndent] -\cs{glsxtrAltTreeIndent} +This is followed by the symbol in parentheses if set. Then, if the +description is set, the description and post-description hook are +displayed followed by: +\begin{definition}[\DescribeMacro\glstopicSubPreLocSep] +\cs{glstopicSubPreLocSep} \end{definition} +(This command isn't used if the description isn't set.) -For additional commands that are available with the -\glostyle{alttree} style, see the documented code -(\texttt{glossaries-extra-code.pdf}). For examples, see -the accompanying sample files \texttt{sample-alttree.tex}, -\texttt{sample-alttree-sym.tex} and -\texttt{sample-alttree-marginpar.tex}. +Finally the location list is displayed using: +\begin{definition}[\DescribeMacro\glstopicSubLoc] +\cs{glstopicSubLoc}\marg{label}\marg{location} +\end{definition} +which just does \meta{location} by default. \chapter{Abbreviations} \label{sec:abbreviations} @@ -4722,17 +4852,50 @@ package modifies the underlying formatting used by abbreviations can have their formatting dealt with by the style. You therefore need to select an abbreviation style that ensures that \cs{gls} (and its variants) displays the desired output. +See the file +\href{http://mirrors.ctan.org/macros/latex/contrib/glossaries-extra/samples/sample-abbr-styles.pdf}{sample-abbr-styles.pdf} +for samples of all provided abbreviation styles. \begin{important} -Don't use commands like \cs{glstext} or \cs{glsfirst} with +Don't use \ics{glsfirst}, \ics{Glsfirst} or \ics{GLSfirst} with abbreviations as they aren't flexible enough to handle some -abbreviation styles and unexpected results may occur. Use commands -like \cs{glsfmtshort} or \cs{glsfmtlong} in section headings or +abbreviation styles and unexpected results may occur. (To a lesser +degree, this also applies to \ics{glstext} etc.) Use commands +like \cs{glsfmttext}, \cs{glsfmtshort} or \cs{glsfmtlong} in section headings or captions instead of \cs{gls}. If you don't want the full form to show on first use of \cs{gls} use one of the \qt{nolong} or \qt{noshort} styles. \end{important} +This lack of flexibility in \cs{glsfirst} can be demonstrated with +the following document: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries-extra} +\setabbreviationstyle{footnote} +\newabbreviation{ex}{EX}{Example} + +\begin{document} +Compare \gls{ex}['s] with \glsfirst{ex}['s]. +\end{document} +\end{verbatim} +The \gls{firstuse} \cs{gls} has the footnote marker after the +inserted material \qt{EX's\textsuperscript{1}} but \cs{glsfirst} has +it before the inserted material \qt{EX\textsuperscript{1}'s} which +is inappropriate. Note that if the style is changed to +\abbrstyle{postfootnote}, the footnote marker appears after the +inserted material as \ics{footnote} is in the post-link hook. + +There are some instances where \cs{glstext} can be useful. It's used +internally by \ics{glsfmttext}, which in turn is used by +\ics{glsseelistformat} if the entry has a short form. If +\cs{glsfmtshort} is used, this enforces the short form, but if +\cs{glsfmttext} is used, then the long form will be used for the +\qt{noshort} styles, which is more appropriate. In this particular +situation, there's no need to worry about inserted material as the +final optional argument isn't supported by \cs{glsfmttext}. + Abbreviations include acronyms (words formed from initial letters, such as \qt{laser}), initialisms (initial letters of a phrase, such as \qt{html}, that @@ -4826,6 +4989,17 @@ use by the long form: \cs{glsuselongfont}\marg{text}\marg{category} \end{definition} +You can't use the acronym commands provided by the base package with +the new abbreviations provided by the \styfmt{glossaries-extra} +package. The style commands that replace \cs{setacronymstyle}, +\cs{acrshort} etc are described in \sectionref{sec:abbrstyle}. +The \pkgopt{acronymlists} package option and associated commands +aren't supported. The \ics{forallacronyms} command, which iterates +over all acronym lists, should be replaced with: +\begin{definition}[\DescribeMacro\forallabbreviationlists] +\cs{forallabbreviationlists}\marg{cs}\marg{body} +\end{definition} + \section{Tagging Initials} \label{sec:tagging} @@ -4866,7 +5040,7 @@ You can later set this attribute for other categories (see \sectionref{sec:categories}) but this must be done before the glossary is displayed. -The accompanying sample file \texttt{sample-mixtures.tex} +The accompanying sample file \nolinkurl{sample-mixtures.tex} uses initial tagging for both the \category{acronym} and \category{abbreviation} categories: \begin{verbatim} @@ -5047,7 +5221,7 @@ entry was defined. If you have mixed styles, you'll need to use \label{sec:abbrshortcuts} The abbreviation shortcut commands can be enabled using -the package option \pkgopt[abbreviation]{shortcuts} +the \pkgopt[abbreviations]{shortcuts} package option (or \pkgopt[abbr]{shortcuts}) or \pkgopt[ac]{shortcuts}. (You can use both settings at the same time.) The provided shortcut commands listed in @@ -5120,7 +5294,7 @@ In both cases, the \gls{firstuse} of \ics{gls} may not match the text produced by \ics{glsfirst} (and likewise for the plural and case-changing versions). -The sample file \texttt{sample-abbr-styles.tex} demonstrates all +The sample file \nolinkurl{sample-abbr-styles.tex} demonstrates all predefined styles described here. \begin{important} @@ -5131,6 +5305,15 @@ recommend that you at least use the \sty{fontenc} package with the \pkgoptfmt{T1} option or something similar. \end{important} +Many of the styles have helper commands in the form +\cs{glsxtr...name} and \cs{glsxtr...sort} that are expanded within the +\gloskey{name} and \gloskey{sort} fields when the abbreviation is defined. +These commands may use the helper token registers available within +\cs{newabbreviation}, such as \ics{glsshorttok}. The contents of a +register can be accessed with \ics{the}\meta{register}. It's essential that +these expand when the abbreviation is defined so don't hide them behind no-expandable content if you +redefine these helper commands. + The parenthetical styles, such as \abbrstyle{long-short}, use \begin{definition}[\DescribeMacro\glsxtrparen] @@ -6059,7 +6242,7 @@ marker may be, if the \sty{hyperref} package is used). The inline full form uses the \meta{short} (\meta{long}) style. The \gloskey{name} is set to the short form. The \gloskey{description} is set to the long form. The -\gloskey{name} key is obtained by expanding +\gloskey{name} key is obtained by expanding: \begin{definition}[\DescribeMacro\glsxtrfootnotename] \cs{glsxtrfootnotename} \end{definition} @@ -6126,6 +6309,44 @@ use \ics{glsabbrvemfont}. 1.04, but original name retained as a deprecated synonym for backward-compatibility.) +\item[\abbrstyledef{short-footnote-desc}] +(New to v1.42.) +This is similar to \abbrstyle{short-footnote}, but the +\gloskey{description} must be supplied by the user. +The \gloskey{name} field is obtained from: +\begin{definition}[\DescribeMacro\glsxtrfootnotedescname] +\cs{glsxtrfootnotedescname} +\end{definition} +which defaults to \meta{short} followed by \meta{long} in +parentheses, and the \gloskey{sort} field is obtained from: +\begin{definition}[\DescribeMacro\glsxtrfootnotedescsort] +\cs{glsxtrfootnotedescsort} +\end{definition} +which defaults to just the short form. (Similarly for other +\texttt{short}\meta{modifier}\texttt{-[post]footnote}\texttt{-desc} +styles, unless indicated otherwise.) + +Any redefinition of these commands must come before the abbreviations +are defined as it expands on definition. Make sure you protect +any commands that shouldn't be expanded. The long form can be +referenced with \cs{the}\cs{glslongtok} and the short form +can be referenced with \cs{the}\cs{glsshorttok}. + +\item[\abbrstyledef{footnote-desc}] +A synonym for \abbrstyle{short-footnote-desc}. + +\item[\abbrstyledef{short-sc-footnote-desc}] +Like \abbrstyle{short-footnote-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvscfont}. + +\item[\abbrstyledef{short-sm-footnote-desc}] +Like \abbrstyle{short-footnote-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvsmfont}. + +\item[\abbrstyledef{short-em-footnote-desc}] +Like \abbrstyle{short-footnote-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvemfont}. + \item[\abbrstyledef{short-postfootnote}] This is similar to the \abbrstyle{short-footnote} style but doesn't modify the category attribute. Instead it changes \postlinkcat\ to @@ -6165,6 +6386,28 @@ use \ics{glsabbrvemfont}. 1.04, but original name retained as a deprecated synonym for backward-compatibility.) +\item[\abbrstyledef{short-postfootnote-desc}] +(New to v1.42.) +This is similar to \abbrstyle{short-postfootnote}, but the +\gloskey{description} must be supplied by the user. The +\gloskey{name} and \gloskey{sort} are set as for +\abbrstyle{short-footnote-desc}. + +\item[\abbrstyledef{postfootnote-desc}] +A synonym for \abbrstyle{short-postfootnote-desc}. + +\item[\abbrstyledef{short-sc-postfootnote-desc}] +Like \abbrstyle{short-postfootnote-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvscfont}. + +\item[\abbrstyledef{short-sm-postfootnote-desc}] +Like \abbrstyle{short-postfootnote-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvsmfont}. + +\item[\abbrstyledef{short-em-postfootnote-desc}] +Like \abbrstyle{short-postfootnote-desc} but redefines \cs{glsabbrvfont} to +use \ics{glsabbrvemfont}. + \item[\abbrstyledef{short-postlong-user}] This style was introduced in version 1.12. It's like the \abbrstyle{short-long-user} style but defers the parenthetical @@ -6771,7 +7014,7 @@ use the more generic \cs{glsabbrvfont} etc which makes them easier to adapt than the modified styles. For further details, see the \qt{Abbreviations} section in the documented code -(\texttt{glossaries-extra-code.pdf}). +(\nolinkurl{glossaries-extra-code.pdf}). \chapter{Entries in Sectioning Titles, Headers, Captions and Contents} \label{sec:headtitle} @@ -6800,6 +7043,8 @@ in the table of contents. Similar problems can also occur with captions (except for the page header and bookmark issues). +\section{Simplistic Approach} + To get around all these problems, the \styfmt{glossaries} user manual recommends using the expandable non-hyperlink commands, such as \ics{glsentrytext} (for regular entries) or \ics{glsentryshort} @@ -6859,14 +7104,22 @@ the argument of sectioning commands. You can still use them even if the mark commands have been reverted, but only where they don't conflict with the page style. -The commands listed below all use \ics{texorpdfstring} if -\sty{hyperref} has been loaded so that the expandable non-formatted -version is added to the PDF bookmarks. Note that since the commands -that convert the first letter to upper case aren't expandable, the -non-case-changing version is used for the bookmarks. +\section{New Commands Designed for Chapter/Section Headings} + +The commands listed below are designed for use in chapter or section +headings. There are still limitations, but they provide a better +solution. They all use \ics{texorpdfstring} if \sty{hyperref} has +been loaded so that the expandable non-formatted version is added to +the PDF bookmarks. Note that since the commands that convert the +first letter to upper case aren't expandable, the non-case-changing +version is used for the bookmarks. If the required field contains +non-expandable (robust or fragile) commands that cause a problem for +the bookmarks then \ics{texorpdfstring} will be needed as +appropriate in that field. (Take care if the field has its value +expanded before being assigned.) These commands essentially behave as though you have used -\cs{glsxtrshort} (or equivalent) with the options +\cs{glsxtrshort}, \cs{glstext} etc with the options \gloskey[glslink]{noindex} and \gloskey[glslink]{hyper\eq false}. The text produced won't be converted to upper case in the page headings by default. If you want the text converted to upper case @@ -6908,6 +7161,18 @@ First letter upper case plural short form: \end{definition} (No case-change applied to PDF bookmarks.) +All caps singular short form: +\begin{definition}[\DescribeMacro\GLSfmtshort] +\cs{GLSfmtshort}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + +All caps plural short form: +\begin{definition}[\DescribeMacro\Glsfmtshortpl] +\cs{Glsfmtshortpl}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + Display the long form: \begin{definition}[\DescribeMacro\glsfmtlong] \cs{glsfmtlong}\marg{label} @@ -6930,9 +7195,32 @@ First letter upper case plural long form: \end{definition} (No case-change applied to PDF bookmarks.) +All caps singular long form: +\begin{definition}[\DescribeMacro\GLSfmtlong] +\cs{GLSfmtlong}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + +All caps plural long form: +\begin{definition}[\DescribeMacro\GLSfmtlongpl] +\cs{GLSfmtlongpl}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + There are similar commands for the full form, but note that these use the \emph{inline} full form, which may be different from the -full form used by \cs{gls}. +full form used by \cs{gls}. The PDF version has to be a simple +fully expandable command, so one of two commands that are unrelated to the style +is used instead: +\begin{definition}[\DescribeMacro\glspdffmtfull] +\cs{glspdffmtfull}\marg{label} +\end{definition} +for the singular form or: +\begin{definition}[\DescribeMacro\glspdffmtfullpl] +\cs{glspdffmtfullpl}\marg{label} +\end{definition} +for the full form. These simply do the long form followed by the +short form in parentheses. Display the full form: \begin{definition}[\DescribeMacro\glsfmtfull] @@ -6956,6 +7244,18 @@ First letter upper case plural full form: \end{definition} (No case-change applied to PDF bookmarks.) +All caps singular full form: +\begin{definition}[\DescribeMacro\GLSfmtfull] +\cs{GLSfmtfull}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + +All caps plural full form: +\begin{definition}[\DescribeMacro\GLSfmtfullpl] +\cs{GLSfmtfullpl}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + There are also equivalent commands for the value of the \gloskey{text} field: \begin{definition}[\DescribeMacro\glsfmttext] @@ -6968,14 +7268,24 @@ First letter converted to upper case: \end{definition} (No case-change applied to PDF bookmarks.) +All caps: +\begin{definition}[\DescribeMacro\GLSfmttext] +\cs{GLSfmttext}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + The plural equivalents: \begin{definition}[\DescribeMacro\glsfmtplural] \cs{glsfmtplural}\marg{label} \end{definition} -and +First letter upper case: \begin{definition}[\DescribeMacro\Glsfmtplural] \cs{Glsfmtplural}\marg{label} \end{definition} +and all caps: +\begin{definition}[\DescribeMacro\GLSfmtplural] +\cs{GLSfmtplural}\marg{label} +\end{definition} Likewise for the value of the \gloskey{name} field: @@ -6989,6 +7299,12 @@ First letter converted to upper case: \end{definition} (No case-change applied to PDF bookmarks.) +All caps: +\begin{definition}[\DescribeMacro\GLSfmtname] +\cs{GLSfmtname}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + Similarly for the value of the \gloskey{first} field: \begin{definition}[\DescribeMacro\glsfmtfirst] @@ -7001,14 +7317,24 @@ First letter converted to upper case: \end{definition} (No case-change applied to PDF bookmarks.) +All caps: +\begin{definition}[\DescribeMacro\GLSfmtfirst] +\cs{GLSfmtfirst}\marg{label} +\end{definition} +(No case-change applied to PDF bookmarks.) + The plural equivalents: \begin{definition}[\DescribeMacro\glsfmtfirstpl] \cs{glsfmtfirstpl}\marg{label} \end{definition} -and +First letter upper case: \begin{definition}[\DescribeMacro\Glsfmtfirstpl] \cs{Glsfmtfirstpl}\marg{label} \end{definition} +and all caps: +\begin{definition}[\DescribeMacro\GLSfmtfirstpl] +\cs{GLSfmtfirstpl}\marg{label} +\end{definition} \chapter{Categories} \label{sec:categories} @@ -7254,61 +7580,6 @@ overridden. \emph{This setting is incompatible with \catattr{aposplural}.} This defined using \cs{newabbreviation} (or \cs{newacronym} if it's using \cs{newabbreviation}.) -\item[\catattrdef{accessinsertdots}] If this attribute is set to -\qt{true} and the \sty{glossaries-accsupp} package has been loaded -(with the \pkgopt{accsupp} option), then this behaves like -\catattr{insertdots} but for the \gloskey{shortaccess} field instead -of the \gloskey{short} field. This can be used to assist the -screen reader for initialisms that should be read out letter by -letter rather than as a word. For example: -\begin{verbatim} -\glssetcategoryattribute{initialism}{accessinsertdots}{true} - -\newabbreviation[category=initialism]{pi}{PI}{Private Investigator} -\end{verbatim} -This setting will be overridden by an explicit use of -the \gloskey{shortaccess} key in the optional argument -of \cs{newabbreviation} (or \cs{newacronym}). This attribute is only applicable to entries -defined using \cs{newabbreviation} (or \cs{newacronym} if it's using -\cs{newabbreviation}.) - -\item[\catattrdef{nameshortaccess}] If this attribute is set to -\qt{true}, the \gloskey{access} field (used for the \gloskey{name} -field's accessibility support) is set to the \gloskey{shortaccess} -value. This attribute has no effect if there's no accessibility -support or if the \gloskey{shortaccess} field hasn't been assigned -or if the \gloskey{access} field is used explicitly. This attribute is only applicable to entries -defined using \cs{newabbreviation} (or \cs{newacronym} if it's using -\cs{newabbreviation}.) - -\item[\catattrdef{textshortaccess}] Like \gloskey{nameshortaccess} -but applies to the \gloskey{textaccess} field (for use with -regular abbreviations). - -\item[\catattrdef{firstshortaccess}] Like \gloskey{nameshortaccess} -but applies to the \gloskey{firstaccess} field (for use with -regular abbreviations). - -\item[\catattrdef{accessaposplural}] This boolean attribute overrides -\catattr{aposplural} for the \gloskey{shortpluralaccess} key. -Has no effect if there's no accessibility support or if -the \gloskey{shortaccess} key hasn't been set or if the -\gloskey{shortpluralaccess} key is explicitly set. If -the \catattr{aposplural} is set and this attribute isn't set -and the \gloskey{shortaccess} key is set, then the -\catattr{aposplural} setting governs the default -\gloskey{shortpluralaccess} setting. If you want -\catattr{aposplural} but don't want it applied to the accessibility -support, set the \catattr{accessaposplural} attribute to \qt{false}. This attribute is only applicable to entries -defined using \cs{newabbreviation} (or \cs{newacronym} if it's using -\cs{newabbreviation}.) - -\item[\catattrdef{accessnoshortplural}] This boolean attribute overrides -\catattr{noshortplural} for the \gloskey{shortpluralaccess} key. -The same conditions apply as for \catattr{accessaposplural}. This attribute is only applicable to entries -defined using \cs{newabbreviation} (or \cs{newacronym} if it's using -\cs{newabbreviation}.) - \item[\catattrdef{headuc}] If this attribute is set to \qt{true}, commands like \ics{glsfmtshort} will use the upper case version in the page headers. @@ -7408,6 +7679,10 @@ Remember that glossary styles may additionally apply a font change, such as the list styles which put the name in the optional argument of \cs{item}. +\item[\catattrdef{glosssymbolfont}] (New to version 1.42.) +This is similar to \catattr{glossnamefont} and +\catattr{glossdescfont} but is used by \ics{glossentrysymbol}. + \item[\catattrdef{textformat}] (New to version 1.21.) Commands like \cs{gls} and \cs{glstext} have the link text encapsulated in the argument of \cs{glstextformat} by default. If @@ -7490,11 +7765,75 @@ for the external list. For example: description={external example}} \end{verbatim} -\item[\catattrdef{externallocation}] The value should be the -file name of the target document when manually indexing an -external location (see \sectionref{sec:wrglossary}). In general, -it's better to use \gls{bib2gls} v1.7+ which can handle multiple -external sources and doesn't require this attribute. +\item[\catattrdef{externallocation}] The value should be the +file name of the target document when manually indexing an +external location (see \sectionref{sec:wrglossary}). In general, +it's better to use \gls{bib2gls} v1.7+ which can handle multiple +external sources and doesn't require this attribute. + +\end{description} + +If a term is defined using \ics{newabbreviation} and accessibility +support has been supplied via the \pkgopt{accsupp} package option +then the following attributes are also available. If +\gloskey{shortaccess} isn't set its value will be obtained from: +\begin{definition}[\DescribeMacro\glsdefaultshortaccess] +\cs{glsdefaultshortaccess}\marg{short}\marg{long} +\end{definition} +This is defined by \sty{glossaries-accsupp} to just do \meta{long} +but \sty{glossaries-extra} redefines it to do \meta{long} +(\meta{short}). The \catattr{accessinsertdots}, +\catattr{accessaposplural} and \catattr{accessnoshortplural} +attributes below refer to the \meta{short} form that's passed to +this command. + +The following attributes are only applicable to entries +defined using \cs{newabbreviation} (or \cs{newacronym} if it's using +\cs{newabbreviation}). They have no effect if the \pkgopt{accsupp} +package option hasn't been used. + +\begin{description} +\item[\catattrdef{accessinsertdots}] If this attribute is set to +\qt{true} and the \sty{glossaries-accsupp} package has been loaded +(with the \pkgopt{accsupp} option), then this behaves like +\catattr{insertdots} but for the \meta{short} part used in the \gloskey{shortaccess} field instead +of the \gloskey{short} field. +This setting will be overridden by an explicit use of +the \gloskey{shortaccess} key in the optional argument +of \cs{newabbreviation} (or \cs{newacronym}). + +\item[\catattrdef{accessaposplural}] This boolean attribute overrides +\catattr{aposplural} for the \gloskey{shortpluralaccess} key. +Has no effect if there's no accessibility support or if +the \gloskey{shortaccess} key hasn't been set or if the +\gloskey{shortpluralaccess} key is explicitly set. If +the \catattr{aposplural} is set and this attribute isn't set +and the \gloskey{shortaccess} key is set, then the +\catattr{aposplural} setting governs the default +\gloskey{shortpluralaccess} setting. If you want +\catattr{aposplural} but don't want it applied to the accessibility +support, set the \catattr{accessaposplural} attribute to \qt{false}. This attribute is only applicable to entries +defined using \cs{newabbreviation} (or \cs{newacronym} if it's using +\cs{newabbreviation}.) + +\item[\catattrdef{accessnoshortplural}] This boolean attribute overrides +\catattr{noshortplural} for the \gloskey{shortpluralaccess} key. +The same conditions apply as for \catattr{accessaposplural}. This attribute is only applicable to entries +defined using \cs{newabbreviation} (or \cs{newacronym} if it's using +\cs{newabbreviation}.) + +\item[\catattrdef{nameshortaccess}] If this attribute is set to +\qt{true}, the \gloskey{access} field (used for the \gloskey{name} +field's accessibility support) automatically assigned if it's not +provided. + +\item[\catattrdef{textshortaccess}] Like \gloskey{nameshortaccess} +but applies to the \gloskey{textaccess} field automatically assigned if it's not +provided. + +\item[\catattrdef{firstshortaccess}] Like \gloskey{nameshortaccess} +but applies to the \gloskey{firstaccess} field automatically assigned if it's not +provided. \end{description} @@ -8374,120 +8713,6 @@ Set the escape (quote) character to \meta{char}. \end{definition} Set the encap character to \meta{char}. -\chapter{On-the-Fly Document Definitions} -\label{sec:onthefly} - -\begin{important} -The commands described here may superficially look like -\meta{word}\cs{index}\marg{word}, but they behave rather -differently. If you want to use \cs{index} then just use -\cs{index}. -\end{important} - -The \styfmt{glossaries} package advises against defining entries -in the \env{document} environment. As mentioned in -\sectionref{sec:pkgopts} above, this ability is disabled by -default with \styfmt{glossaries-extra} but can be enabled using -the \pkgopt{docdefs} package options. - -Although this can be problematic, the \styfmt{glossaries-extra} -package provides a way of defining and using entries within -the \env{document} environment without the tricks used with the -\pkgopt{docdefs} option. \emph{There are limitations with this -approach, so take care with it.} This function is disabled by -default, but can be enabled using the preamble-only command: -\begin{definition}[\DescribeMacro\GlsXtrEnableOnTheFly] -\cs{GlsXtrEnableOnTheFly} -\end{definition} -When used, this defines the commands described below. - -\begin{important} -The commands \cs{glsxtr}, \cs{glsxtrpl}, \cs{Glsxtr} -and \cs{Glsxtrpl} can't be used after the glossaries have been -displayed (through \ics{printglossary} etc). It's best not to mix -these commands with the standard glossary commands, such -as \cs{gls} or there may be unexpected results. -\end{important} - -\begin{definition}[\DescribeMacro\glsxtr] -\cs{glsxtr}\oarg{gls-options}\oarg{dfn-options}\marg{label} -\end{definition} -If an entry with the label \meta{label} has already been defined, -this just does \cs{gls}\oarg{gls-options}\marg{label}. If -\meta{label} hasn't been defined, this will define the entry -using: -\begin{alltt} -\cs{newglossaryentry}\marg{label}\{name=\marg{label}, - category=\cs{glsxtrcat}, - description=\{\cs{nopostdesc}\}, - \meta{dfn-options}\} -\end{alltt} - -\begin{important} -The \meta{label} must contain any non-expandable commands, such as -formatting commands or problematic characters. -If the term requires any of these, they must be omitted from the -\meta{label} and placed in the \gloskey{name} key must be provided -in the optional argument \meta{dfn-options}. -\end{important} - -The second optional argument \meta{dfn-options} should be empty -if the entry has already been defined, since it's too late for -them. If it's not empty, a~warning will be generated with -\begin{definition}[\DescribeMacro\GlsXtrWarning] -\cs{GlsXtrWarning}\marg{dfn-options}\marg{label} -\end{definition} - -For example, this warning will be generated on the second instance -of \cs{glsxtr} below: -\begin{verbatim} -\glsxtr[][plural=geese]{goose} -% ... later -\glsxtr[][plural=geese]{goose} -\end{verbatim} - -If you are considering doing something like: -\begin{verbatim} -\newcommand*{\goose}{\glsxtr[][plural=geese]{goose}} -\renewcommand*{\GlsXtrWarning}[2]{} -% ... later -\goose\ some more text here -\end{verbatim} -then don't bother. It's simpler and less problematic to just -define the entries in the preamble with \ics{newglossaryentry} -and then use \cs{gls} in the document. - -There are plural and case-changing alternatives to \cs{glsxtr}: -\begin{definition}[\DescribeMacro\glsxtrpl] -\cs{glsxtrpl}\oarg{gls-options}\oarg{dfn-options}\marg{label} -\end{definition} -This is like \cs{glsxtr} but uses \cs{glspl} instead of \cs{gls}. - -\begin{definition}[\DescribeMacro\Glsxtr] -\cs{Glsxtr}\oarg{gls-options}\oarg{dfn-options}\marg{label} -\end{definition} -This is like \cs{glsxtr} but uses \cs{Gls} instead of \cs{gls}. - -\begin{definition}[\DescribeMacro\Glsxtrpl] -\cs{Glsxtrpl}\oarg{gls-options}\oarg{dfn-options}\marg{label} -\end{definition} -This is like \cs{glsxtr} but uses \cs{Glspl} instead of \cs{gls}. - -If you use UTF-8 and don't want the inconvenient of needing -to use an ASCII-only label, then it's better to use -\XeLaTeX\ or \LuaLaTeX\ instead of \LaTeX\ (or \pdfLaTeX). -If you really desperately want to use UTF-8 entry labels without -switching to \XeLaTeX\ or \LuaLaTeX\ then there is a starred -version of \cs{GlsXtrEnableOnTheFly} that allows you to -use UTF-8 characters in \meta{label}, but it's experimental and -may not work in some cases. - -\begin{important} -If you use the starred version of \cs{GlsXtrEnableOnTheFly} -don't use any commands in the \meta{label}, even if they expand -to just text. -\end{important} - \chapter{\appfmt{bib2gls}: Managing Reference Databases} \label{sec:bib2gls} @@ -8922,6 +9147,11 @@ the associated glossary: \ics{printunsrtabbreviations}, \ics{printunsrtacronyms}, \ics{printunsrtsymbols}, \ics{printunsrtnumbers} and \ics{printunsrtindex}. +The \pkgopt{savenumberlist} package option doesn't have any effect +with \gls{bib2gls}. The location lists are saved by default, so +\sty{glossaries-extra-bib2gls} patches \ics{glsentrynumberlist} and +\ics{glsdisplaynumberlist} to work with the \gloskey{location} field + \begin{definition}[\DescribeMacro\glsxtrprovidecommand] \cs{glsxtrprovidecommand}\marg{cs}\oarg{n}\oarg{default}\marg{definition} \end{definition} @@ -10612,10 +10842,15 @@ you can use \begin{definition}[\DescribeMacro\glsxtrentryfmt] \cs{glsxtrentryfmt}\marg{label}\marg{text} \end{definition} -This uses \cs{texorpdfstring} and will simply expand to \meta{text} +If \sty{hyperref} is used, this uses \cs{texorpdfstring} and will expand to +\begin{definition}[\DescribeMacro\glsxtrpdfentryfmt] +\cs{glsxtrpdfentryfmt}\marg{label}\marg{text} +\end{definition} within the PDF bookmarks, but in the document it will do \meta{cs}\marg{text} if a control sequence name has been provided -or just \meta{text} otherwise. +or just \meta{text} otherwise. The PDF bookmark version simply does +\meta{text}. It may be redefined, but remember that it needs to +expand fully. The \styfmt{glossaries} package provides \cs{glsaddstoragekey} to add new keys. This command will cause an error if the key has @@ -10801,6 +11036,30 @@ use: Again, version 1.39 introduced a starred form of these commands, which use the starred form of \cs{glsxtrifhasfield}. +As from v1.42, you can test if the field value is contained in a +comma-separated list with: +\begin{definition}[\DescribeMacro\GlsXtrIfFieldValueInCsvList] +\cs{GlsXtrIfFieldValueInCsvList}\marg{label}\marg{field}\marg{list}\marg{true}\marg{false} +\end{definition} +The unstarred version uses the unstarred form of +\cs{glsxtrifhasfield} (which adds grouping so \meta{true} and +\meta{false} will be localised). The starred version uses +\cs{glsxtrifhasfield*}. If the field value (without expansion) is +contained in \meta{list} then \meta{true} is done otherwise +\meta{false} is done. If the field hasn't been set \meta{false} is +done. This internally uses \cs{DTLifinlist} provided by +\sty{datatool-base} which performs a one level expansion on +\meta{list}. See the \sty{datatool} documentation for further +details. + +This command is intended for fields that contain a label. For +example, to test if the category is one of a set of labels: +\begin{verbatim} +\GlsXtrIfFieldValueInCsvList{examplelabel}{category}% + {abbreviation,acronym}% set of labels + {true part}{false part} +\end{verbatim} + As from v1.31, if a field represents a numeric (integer) value, you can use the following two numeric tests. If the field is set, it must expand to an integer. You may use \cs{glscurrentfieldvalue} @@ -10883,7 +11142,36 @@ or \cs{glsxtrfieldforlistloop}\marg{label}\marg{field}\marg{handler} \end{definition} that internally use \cs{dolistcsloop} and \cs{forlistloop}, -respectively. +respectively. You can use \ics{listbreak} to break out of the loop +(see the \sty{etoolbox} manual for further details). + +For fields that contain comma-separated lists use +\cs{glsxtrforcsvfield} instead. + +New to v1.42: +\begin{definition}[\DescribeMacro\glsxtrfieldformatlist] +\cs{glsxtrfieldformatlist}\marg{label}\marg{field} +\end{definition} +Like \sty{datatool-base}'s \ics{DTLformatlist}, this iterates over +an (\sty{etoolbox}) internal list and formats each item. Uses all +the same helper commands as \cs{DTLformatlist} (the same list handler +macro is used). Unlike the \sty{datatool-base} command, this command +has no starred version. Grouping is automatically applied. + +For example, with \gls{bib2gls}['s] \texttt{save-child-count} +resource option: +\begin{verbatim} +\newcommand*{\listchildren}[1]{% + \GlsXtrIfFieldNonZero{childcount}{#1}% + {child count: \glscurrentfieldvalue; children: + \let\DTLlistformatitem\glsfmtname + \glsxtrfieldformatlist{#1}{childlist}% + }% + {no children}% +} +\end{verbatim} +For fields that contain a comma-separated list use \cs{glsxtrfieldformatcsvlist} +instead. There are also commands that use \cs{ifinlistcs}: \begin{definition}[\DescribeMacro\glsxtrfieldifinlist] @@ -10920,6 +11208,13 @@ which is just a synonym for \cs{@endfortrue}. The loop is performed within the true part of \cs{glsxtrifhasfield} so scoping is automatically applied. +New to v1.42: +\begin{definition}[\DescribeMacro\glsxtrfieldformatcsvlist] +\cs{glsxtrfieldformatcsvlist}\marg{label}\marg{field} +\end{definition} +Like \cs{glsxtrfieldformatcsvlist} but for fields that contain +comma-separated lists. + As from version 1.32, if the field given by \begin{definition}[\DescribeMacro\GlsXtrForeignTextField] \cs{GlsXtrForeignTextField} @@ -11572,6 +11867,120 @@ The value of the \gloskey{alias} field can be accessed using \cs{glsxtralias}\marg{label} \end{definition} +\chapter{On-the-Fly Document Definitions} +\label{sec:onthefly} + +\begin{important} +The commands described here may superficially look like +\meta{word}\cs{index}\marg{word}, but they behave rather +differently. If you want to use \cs{index} then just use +\cs{index}. +\end{important} + +The \styfmt{glossaries} package advises against defining entries +in the \env{document} environment. As mentioned in +\sectionref{sec:pkgopts} above, this ability is disabled by +default with \styfmt{glossaries-extra} but can be enabled using +the \pkgopt{docdefs} package options. + +Although this can be problematic, the \styfmt{glossaries-extra} +package provides a way of defining and using entries within +the \env{document} environment without the tricks used with the +\pkgopt{docdefs} option. \emph{There are limitations with this +approach, so take care with it.} This function is disabled by +default, but can be enabled using the preamble-only command: +\begin{definition}[\DescribeMacro\GlsXtrEnableOnTheFly] +\cs{GlsXtrEnableOnTheFly} +\end{definition} +When used, this defines the commands described below. + +\begin{important} +The commands \cs{glsxtr}, \cs{glsxtrpl}, \cs{Glsxtr} +and \cs{Glsxtrpl} can't be used after the glossaries have been +displayed (through \ics{printglossary} etc). It's best not to mix +these commands with the standard glossary commands, such +as \cs{gls} or there may be unexpected results. +\end{important} + +\begin{definition}[\DescribeMacro\glsxtr] +\cs{glsxtr}\oarg{gls-options}\oarg{dfn-options}\marg{label} +\end{definition} +If an entry with the label \meta{label} has already been defined, +this just does \cs{gls}\oarg{gls-options}\marg{label}. If +\meta{label} hasn't been defined, this will define the entry +using: +\begin{alltt} +\cs{newglossaryentry}\marg{label}\{name=\marg{label}, + category=\cs{glsxtrcat}, + description=\{\cs{nopostdesc}\}, + \meta{dfn-options}\} +\end{alltt} + +\begin{important} +The \meta{label} must contain any non-expandable commands, such as +formatting commands or problematic characters. +If the term requires any of these, they must be omitted from the +\meta{label} and placed in the \gloskey{name} key must be provided +in the optional argument \meta{dfn-options}. +\end{important} + +The second optional argument \meta{dfn-options} should be empty +if the entry has already been defined, since it's too late for +them. If it's not empty, a~warning will be generated with +\begin{definition}[\DescribeMacro\GlsXtrWarning] +\cs{GlsXtrWarning}\marg{dfn-options}\marg{label} +\end{definition} + +For example, this warning will be generated on the second instance +of \cs{glsxtr} below: +\begin{verbatim} +\glsxtr[][plural=geese]{goose} +% ... later +\glsxtr[][plural=geese]{goose} +\end{verbatim} + +If you are considering doing something like: +\begin{verbatim} +\newcommand*{\goose}{\glsxtr[][plural=geese]{goose}} +\renewcommand*{\GlsXtrWarning}[2]{} +% ... later +\goose\ some more text here +\end{verbatim} +then don't bother. It's simpler and less problematic to just +define the entries in the preamble with \ics{newglossaryentry} +and then use \cs{gls} in the document. + +There are plural and case-changing alternatives to \cs{glsxtr}: +\begin{definition}[\DescribeMacro\glsxtrpl] +\cs{glsxtrpl}\oarg{gls-options}\oarg{dfn-options}\marg{label} +\end{definition} +This is like \cs{glsxtr} but uses \cs{glspl} instead of \cs{gls}. + +\begin{definition}[\DescribeMacro\Glsxtr] +\cs{Glsxtr}\oarg{gls-options}\oarg{dfn-options}\marg{label} +\end{definition} +This is like \cs{glsxtr} but uses \cs{Gls} instead of \cs{gls}. + +\begin{definition}[\DescribeMacro\Glsxtrpl] +\cs{Glsxtrpl}\oarg{gls-options}\oarg{dfn-options}\marg{label} +\end{definition} +This is like \cs{glsxtr} but uses \cs{Glspl} instead of \cs{gls}. + +If you use UTF-8 and don't want the inconvenient of needing +to use an ASCII-only label, then it's better to use +\XeLaTeX\ or \LuaLaTeX\ instead of \LaTeX\ (or \pdfLaTeX). +If you really desperately want to use UTF-8 entry labels without +switching to \XeLaTeX\ or \LuaLaTeX\ then there is a starred +version of \cs{GlsXtrEnableOnTheFly} that allows you to +use UTF-8 characters in \meta{label}, but it's experimental and +may not work in some cases. + +\begin{important} +If you use the starred version of \cs{GlsXtrEnableOnTheFly} +don't use any commands in the \meta{label}, even if they expand +to just text. +\end{important} + \chapter{Supplemental Packages} \label{sec:supplemental} @@ -11611,6 +12020,11 @@ Next use: \pgls{svm}. \section{Accessibility Support} \label{sec:accsupp} +\begin{important} +The \sty{glossaries-accsupp} package is still experimental and so +accessibility features are liable to change. +\end{important} + The \sty{glossaries-accsupp} package needs to be loaded before \styfmt{glossaries-extra} or through the \pkgopt{accsupp} package option: @@ -11621,7 +12035,9 @@ If you don't load \sty{glossaries-accsupp} or you load \sty{glossaries-accsupp} after \styfmt{glossaries-extra} the new \cs{glsaccess}\meta{xxx} commands described below will simply be equivalent to the corresponding \cs{glsentry}\meta{xxx} -commands. +commands. Other accessibility features, such as the attributes used +by \ics{newabbreviation} also won't work if \sty{glossaries-accsupp} +is loaded too late. The following \cs{glsaccess}\meta{xxx} commands add accessibility information wrapped around the corresponding \cs{glsentry}\meta{xxx} commands. There is @@ -11978,7 +12394,7 @@ shouldn't appear in the final draft of your document. The \styfmt{glossaries-extra} package has the facility to load language modules (whose filename is in the form -\texttt{glossariesxtr-}\meta{language}\texttt{.ldf}) if they exist, +\texttt{glossariesxtr\dhyphen}\meta{language}\texttt{.ldf}) if they exist, but won't warn if they don't. If \sty{glossaries-extra-bib2gls} is loaded via the \pkgopt{record} package option then the check for language resource files will additionally search for an associated @@ -11991,9 +12407,9 @@ dialect file. If you want to write your own language module, you just need to create a file called -\texttt{glossariesxtr-}\meta{lang}\texttt{.ldf}, where \meta{lang} +\texttt{glossariesxtr\dhyphen}\meta{lang}\texttt{.ldf}, where \meta{lang} identifies the language or dialect (see the \sty{tracklang} -package). For example, \texttt{glossariesxtr-french.ldf}. +package). For example, \nolinkurl{glossariesxtr-french.ldf}. The simplest code for this file is: \begin{verbatim} @@ -12107,8 +12523,6 @@ This produces the following text in English: \cs{GlsXtrNoGlsWarningBuildInfo} \end{definition} This is advice on how to generate the glossary files. -See the documented code (\texttt{glossaries-extra-code.pdf}) -for further details. \begin{definition}[\DescribeMacro\GlsXtrNoGlsWarningAutoMake] \cs{GlsXtrNoGlsWarningAutoMake}\marg{label} @@ -12117,7 +12531,9 @@ This is the message produced when the \pkgopt{automake} option is used, but the document needs a rerun or the shell escape setting doesn't permit the execution of the external application. This command also generates a warning in the transcript file. -See the documented code for further details. + +See the documented code (\nolinkurl{glossaries-extra-code.pdf}) +for further details. \printglossaries \PrintIndex diff --git a/macros/latex/contrib/glossaries-extra/glossaries-extra.dtx b/macros/latex/contrib/glossaries-extra/glossaries-extra.dtx index 3d37899d9b..d16bcf9bae 100644 --- a/macros/latex/contrib/glossaries-extra/glossaries-extra.dtx +++ b/macros/latex/contrib/glossaries-extra/glossaries-extra.dtx @@ -1,6 +1,14 @@ %\iffalse % glossaries-extra.dtx generated using makedtx version 1.2 (c) Nicola Talbot % Command line args: +% -codetitle "Main Package Code (\\styfmt{glossaries-extra.sty})" +% -section "chapter" +% -macrocode ".*\.tex" +% -macrocode ".*\.bib" +% -setambles ".*\.bib=>\nopreamble\nopostamble" +% -comment ".*\.tex" +% -comment ".*\.bib" +% -author "Nicola Talbot" % -src "glossaries-extra.sty\Z=>glossaries-extra.sty" % -src "glossaries-extra-bib2gls.sty\Z=>glossaries-extra-bib2gls.sty" % -src "glossaries-extra-stylemods.sty\Z=>glossaries-extra-stylemods.sty" @@ -9,17 +17,9 @@ % -src "glossary-topic.sty\Z=>glossary-topic.sty" % -src "(example-glossaries-.+\.tex)\Z=>\1" % -src "(example-glossaries-.+\.bib)\Z=>\1" -% -author "Nicola Talbot" % -doc "glossaries-extra-codedoc.tex" -% -macrocode ".*\.tex" -% -macrocode ".*\.bib" -% -section "chapter" -% -setambles ".*\.bib=>\nopreamble\nopostamble" -% -comment ".*\.tex" -% -comment ".*\.bib" -% -codetitle "Main Package Code (\\styfmt{glossaries-extra.sty})" % glossaries-extra -% Created on 2019/4/9 21:59 +% Created on 2020/2/13 22:19 %\fi %\iffalse %<*package> @@ -42,7 +42,7 @@ %\fi % \iffalse % Doc-Source file to use with LaTeX2e -% Copyright (C) 2019 Nicola Talbot, all rights reserved. +% Copyright (C) 2020 Nicola Talbot, all rights reserved. % \fi % \iffalse %<*driver> @@ -142,7 +142,7 @@ governed by the \gloskey{first} and \gloskey{firstplural} keys of \setcounter{IndexColumns}{2} -\CheckSum{25503} +\CheckSum{26913} \newcommand*{\ifirstuse}{\iterm{first use}} \newcommand*{\firstuse}{\gls{firstuse}} @@ -152,9 +152,9 @@ governed by the \gloskey{first} and \gloskey{firstplural} keys of \newcommand*{\ifirstuseflag}{\iterm{first use>flag}} \newcommand*{\ifirstusetext}{\iterm{first use>text}} -\newcommand*{\istkey}[1]{\appfmt{#1}\index{makeindex=\appfmt{makeindex}>#1=\texttt{#1}|hyperpage}} +\newcommand*{\istkey}[1]{\appfmt{#1}\index{makeindex=\appfmt{makeindex}>#1=\texttt{#1}}} \newcommand*{\locfmt}[1]{\texttt{#1}\SpecialMainIndex{#1}} -\newcommand*{\mkidxspch}{\index{makeindex=\appfmt{makeindex}>special characters|hyperpage}} +\newcommand*{\mkidxspch}{\index{makeindex=\appfmt{makeindex}>special characters}} \newcommand*{\igloskey}[2][newglossaryentry]{\icsopt{#1}{#2}} \newcommand*{\gloskey}[2][newglossaryentry]{\csopt{#1}{#2}} @@ -182,13 +182,13 @@ governed by the \gloskey{first} and \gloskey{firstplural} keys of \raggedright } -\title{glossaries-extra.sty v1.41: +\title{glossaries-extra.sty v1.42: documented code} \author{Nicola L.C. Talbot\\[10pt] Dickimaw Books\\ \url{http://www.dickimaw-books.com/}} -\date{2019-04-09} +\date{2020-02-13} \begin{document} \DocInput{glossaries-extra.dtx} @@ -233,7 +233,7 @@ Dickimaw Books\\ %\section{Package Initialisation and Options} % \begin{macrocode} \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{glossaries-extra}[2019/04/09 v1.41 (NLCT)] +\ProvidesPackage{glossaries-extra}[2020/02/13 v1.42 (NLCT)] % \end{macrocode} % Requires \sty{xkeyval} to define package options. % \begin{macrocode} @@ -511,15 +511,17 @@ Dickimaw Books\\ %(\texttt{glslink} in most cases, \texttt{glossadd} for \cs{glsadd}). % \begin{macrocode} \newcommand*{\@@glsxtr@record}[3]{% +% \end{macrocode} +%Save the label in case it's needed. This needs to be outside the +%existence check to allow the post-link hook to reference it. +%\changes{1.42}{2020-02-03}{moved label definition outside of conditional} +% \begin{macrocode} + \edef\@gls@label{\glsdetoklabel{#2}}% + \let\glslabel\@gls@label \ifglsentryexists{#2}{}% {% \@@glsxtrwrglossmark \begingroup -% \end{macrocode} -%Save the label in case it's needed. -% \begin{macrocode} - \edef\@gls@label{\glsdetoklabel{#2}}% - \let\glslabel\@gls@label \let\@glsnumberformat\@glsxtr@defaultnumberformat \def\@glsxtr@thevalue{}% \def\@glsxtr@theHvalue{\@glsxtr@thevalue}% @@ -1577,6 +1579,10 @@ Dickimaw Books\\ % \end{macrocode} %\end{macro} % +%\sty{glossaries-accsupp} can't be loaded after +%\styfmt{glossaries-extra}. \sty{glossaries-accsupp} v4.29+ checks +%\cs{@glsxtr@doaccsupp} to determine if it's been loaded too late. +% %\begin{option}{accsupp} % If \pkgopt{accsupp}, load \sty{glossaries-accsupp} package. % \begin{macrocode} @@ -1585,6 +1591,22 @@ Dickimaw Books\\ % \end{macrocode} %\end{option} % +%\begin{macro}{\@glsxtr@doloadprefix} +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newcommand*{\@glsxtr@doloadprefix}{} +% \end{macrocode} +%\end{macro} +% +%\begin{option}{prefix} +%\changes{1.42}{2020-02-03}{new} +% If \pkgopt{prefix}, load \sty{glossaries-prefix} package. +% \begin{macrocode} +\@glsxtr@declareoption{prefix}{% + \renewcommand*{\@glsxtr@doloadprefix}{\RequirePackage{glossaries-prefix}}} +% \end{macrocode} +%\end{option} +% %\begin{macro}{\glsxtrNoGlossaryWarning} %\changes{0.3}{2015-12-02}{new} %\changes{1.34}{2018-07-29}{added package warning} @@ -1805,10 +1827,11 @@ Dickimaw Books\\ %\begin{option}{debug} %\changes{1.21}{2017-11-03}{new} % Provide extra debug options. +%\changes{1.42}{2020-02-03}{add support for debug=showaccsupp} % \begin{macrocode} \define@choicekey{glossaries-extra.sty}{debug} [\@glsxtr@debugval\@glsxtr@debugnr]% - {true,false,showtargets,showwrgloss,all}[true]{% + {true,false,showtargets,showwrgloss,all,showaccsupp}[true]{% \ifcase\@glsxtr@debugnr\relax % true \glsxtr@dooption{debug=true}% \renewcommand*{\@glsxtrwrglossmark}{}% @@ -1821,8 +1844,10 @@ Dickimaw Books\\ \glsxtr@dooption{debug=true}% \renewcommand*{\@glsxtrwrglossmark}{\glsxtrwrglossmark}% \or % all - \glsxtr@dooption{debug=showtargets}% + \glsxtr@dooption{debug=showtargets,debug=showaccsupp}% \renewcommand*{\@glsxtrwrglossmark}{\glsxtrwrglossmark}% + \or % showaccsupp + \glsxtr@dooption{debug=showaccsupp}% \fi } % \end{macrocode} @@ -1845,6 +1870,10 @@ Dickimaw Books\\ % \begin{macrocode} \@glsxtr@doaccsupp % \end{macrocode} +% Load the \sty{glossaries-prefix} package if required. +% \begin{macrocode} +\@glsxtr@doloadprefix +% \end{macrocode} % Redefine \cs{glspostdescription} if required. % \begin{macrocode} \@glsxtr@defpostpunc @@ -1853,23 +1882,50 @@ Dickimaw Books\\ %\begin{macro}{\glsshowtarget} %This command was introduced to \sty{glossaries} v4.32 so it may not %be defined. Therefore it's defined here using \cs{def}. +%\cs{glsshowtargetouter} was introduced in \sty{glossaries} v4.45, +%so that also may not be defined. %\changes{1.21}{2017-11-03}{new} +%\changes{1.42}{2020-02-03}{added check for \cs{glsshowtargetouter}} % \begin{macrocode} -\def\glsshowtarget#1{% - \glsxtrtitleorpdforheading - {% - \ifmmode - \texttt{\small [#1]}% - \else - \ifinner +\ifdef\glsshowtargetouter +{ + \renewcommand*{\glsshowtarget}[1]{% + \glsxtrtitleorpdforheading + {% + \ifmmode + \nfss@text{\glsshowtargetfont [#1]}% + \else + \ifinner + {\glsshowtargetfont [#1]}% + \else + \glsshowtargetouter{#1}% + \fi + \fi + }% + {[#1]}% + {{\protect\glsshowtargetfont [#1]}}% + } +} +{ +% \end{macrocode} +%Old definition. +% \begin{macrocode} + \def\glsshowtarget#1{% + \glsxtrtitleorpdforheading + {% + \ifmmode \texttt{\small [#1]}% \else - \marginpar{\texttt{\small #1}}% + \ifinner + \texttt{\small [#1]}% + \else + \marginpar{\texttt{\small #1}}% + \fi \fi - \fi - }% - {[#1]}% - {\texttt{\small [#1]}}% + }% + {[#1]}% + {\texttt{\small [#1]}}% + } } % \end{macrocode} %\end{macro} @@ -1977,18 +2033,24 @@ Dickimaw Books\\ % \begin{macrocode} \renewcommand{\glsxtr@dooption}[1]{\setupglossaries{#1}}% % \end{macrocode} +% Disable options that can only be used when the package is loaded: +% \begin{macrocode} +\disable@keys{glossaries-extra.sty}{accsupp} +% \end{macrocode} % Now define the user command: % \begin{macrocode} \newcommand*{\glossariesextrasetup}[1]{% \let\glsxtr@setup@record\relax \let\@glsxtr@setupshortcuts\relax \let\@glsxtr@redef@forglsentries\relax + \let\@glsxtr@doloadprefix\relax \setkeys{glossaries-extra.sty}{#1}% \@glsxtr@abbreviationsdef \let\@glsxtr@abbreviationsdef\relax \@glsxtr@setupshortcuts \glsxtr@setup@record \@glsxtr@redef@forglsentries + \@glsxtr@doloadprefix } % \end{macrocode} %\end{macro} @@ -2335,7 +2397,7 @@ Dickimaw Books\\ \ifdef\texorpdfstring { \newcommand*{\glsxtrentryfmt}[2]{% - \texorpdfstring{\@glsxtrentryfmt{#1}{#2}}{#2}% + \texorpdfstring{\@glsxtrentryfmt{#1}{#2}}{\glsxtrpdfentryfmt{#1}{#2}}% } } { @@ -2344,20 +2406,36 @@ Dickimaw Books\\ % \end{macrocode} %\end{macro} % +%\begin{macro}{\glsxtrpdfentryfmt} +%\changes{1.42}{2020-02-03}{new} +%Use for the PDF bookmarks. +% \begin{macrocode} +\newcommand*{\glsxtrpdfentryfmt}[2]{#2} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\@glsxtrentryfmt} %\changes{1.12}{2017-02-03}{new} %\changes{1.23}{2017-11-12}{fixed missing label argument} % \begin{macrocode} \newrobustcmd*{\@glsxtrentryfmt}[2]{% - \glsdoifexistsordo{#1}% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{added \cs{glslabel} and scope} +%Locally define \cs{glslabel} in case the helper command needs to access the +%label. +% \begin{macrocode} {% - \ifglshasfield{\GlsXtrFmtField}{#1}% + \def\glslabel{#1}% + \glsdoifexistsordo{#1}% {% - \csuse{\glscurrentfieldvalue}{#2}% + \ifglshasfield{\GlsXtrFmtField}{#1}% + {% + \csuse{\glscurrentfieldvalue}{#2}% + }% + {#2}% }% {#2}% }% - {#2}% } % \end{macrocode} %\end{macro} @@ -2426,6 +2504,22 @@ Dickimaw Books\\ % \end{macrocode} %\end{macro} % +%\begin{macro}{\glsxtrfieldformatlist} +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newrobustcmd*{\glsxtrfieldformatlist}[2]{% + \begingroup + \def\@dtl@formatlist@itemsep{}% + \def\@dtl@formatlist@lastitem{}% + \def\@dtl@formatlist@prelastitem{}% + \def\@dtl@formatlist@prelastitemsep{}% + \forlistcsloop{\@dtl@formatlist@handler}{glo@\glsdetoklabel{#1}@#2}% + \@dtl@formatlist@prelastitem\@dtl@formatlist@lastitem + \endgroup +} +% \end{macrocode} +%\end{macro} +% %List element tests: %\begin{macro}{\glsxtrfieldifinlist} %\changes{1.12}{2017-02-03}{new} @@ -2465,6 +2559,62 @@ Dickimaw Books\\ % \end{macrocode} %\end{macro} % +%\begin{macro}{\glsxtrfieldformatcsvlist} +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newrobustcmd*{\glsxtrfieldformatcsvlist}[2]{% + \@glsxtrifhasfield{#2}{#1}% + {\@dtlformatlist\glscurrentfieldvalue}% + {}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\GlsXtrIfFieldValueInCsvList} +%\changes{1.42}{2020-02-03}{new} +%\begin{definition} +%\cs{GlsXtrIfFieldValueInCsvList}\marg{label}\marg{field}\marg{list}\marg{true}\marg{false} +%\end{definition} +% \begin{macrocode} +\newcommand*{\GlsXtrIfFieldValueInCsvList}{% + \@ifstar\s@GlsXtrIfFieldValueInCsvList\@GlsXtrIfFieldValueInCsvList +} +% \end{macrocode} +%\end{macro} +% +%Note \cs{DTLifinlist} performs one level on the list but not the +%element. +%\begin{macro}{\@GlsXtrIfFieldValueInCsvList} +%\changes{1.42}{2020-02-03}{new} +%Unstarred version. +% \begin{macrocode} +\newcommand*{\@GlsXtrIfFieldValueInCsvList}[5]{% + \@glsxtrifhasfield{#2}{#1}% + {% + \expandafter\DTLifinlist\expandafter{\glscurrentfieldvalue}% + {#3}{#4}{#5}% + }% + {#5}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\s@GlsXtrIfFieldValueInCsvList} +%\changes{1.42}{2020-02-03}{new} +%Starred version. +% \begin{macrocode} +\newcommand*{\s@GlsXtrIfFieldValueInCsvList}[5]{% + \s@glsxtrifhasfield{#2}{#1}% + {% + \expandafter\DTLifinlist\expandafter{\glscurrentfieldvalue}% + {#3}{#4}{#5}% + }% + {#5}% +} +% \end{macrocode} +%\end{macro} +% +% %\begin{macro}{\glsxtrifhasfield} %\changes{1.19}{2017-09-09}{new} %A simpler alternative to \cs{ifglshasfield} that doesn't complain @@ -3119,6 +3269,30 @@ Dickimaw Books\\ % Some of the commands provided by \styfmt{glossaries} are modified % to take into account new options or to change default behaviour. % +% The original \cs{@gls@entry@field} causes a problem for undefined +% entries when used in section headings or captions. Since entries +% must be defined with just the base package this isn't a +% significant issue, but it will cause a problem with \gls{bib2gls} +% where no entries are defined on the first \LaTeX\ call, so +% redefine \cs{@gls@entry@field} to use \cs{csuse} instead of +% \cs{csname}. +%\begin{macro}{\@gls@entry@field} +%\changes{1.42}{2020-02-03}{redefined} +%\begin{definition} +%\cs{@gls@entry@field}\marg{label}\marg{field} +%\end{definition} +%This command was introduced to \sty{glossaries} version 4.03 but +%older versions are likely to be incompatible with +%\sty{glossaries-extra}. +% \begin{macrocode} +\ifdef\@gls@entry@field +{ + \renewcommand*{\@gls@entry@field}[2]{\csuse{glo@\glsdetoklabel{#1}@#2}} +} +{} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\ifglsused} %\begin{definition} %\cs{ifglsused}\marg{label}\marg{true part}\marg{false part} @@ -3581,29 +3755,38 @@ Dickimaw Books\\ %\changes{1.21}{2017-11-03}{new} %\changes{1.22}{2017-11-08}{switched check from regular to short} %\changes{1.37}{2018-11-30}{removed reference to \cs{glslabel}} +%\changes{1.42}{2020-02-03}{switched to using \cs{glsfmttext} and +%\cs{glsfmtname}} %\styfmt{glossaries} originally defined \cs{glsseeitemformat} %to use \cs{glsentryname} but in v3.0 this was switched to %use \cs{glsentrytext} due to problems occurring with the %\gloskey{name} field being sanitized. Since this is no longer a -%problem, \styfmt{glossaries-extra} restores the original +%problem, \styfmt{glossaries-extra} restored the original %definition as it makes more sense to use the \gloskey{name} -%in the cross-reference list. This still uses \cs{glsaccesstext} -%for abbreviations. +%in the cross-reference list. Unfortunately this doesn't take style +%changes into account, so as from v1.42, this now uses +%\cs{glsfmttext} and \cs{glsfmtname} instead. (The \gloskey{text} +%field is chosen rather than the \gloskey{short} field to allow for +%the \qt{noshort} styles.) % \begin{macrocode} \renewcommand*{\glsseeitemformat}[1]{% - \ifglshasshort{#1}{\glsaccesstext{#1}}{\glsaccessname{#1}}% + \ifglshasshort{#1}{\glsfmttext{#1}}{\glsfmtname{#1}}% } % \end{macrocode} %\end{macro} % %\begin{macro}{\glsxtrhiername} %\changes{1.37}{2018-11-30}{new} +%\changes{1.42}{2020-02-03}{switched to using \cs{glsfmttext} and +%\cs{glsfmtname}} %\begin{definition} %\cs{glsxtrhiername}\marg{label} %\end{definition} %Displays the hierarchical name for the given entry. The %cross-reference format \cs{glsseeitemformat} may be redefined to -%use this command to show the hierarchy, if required. +%use this command to show the hierarchy, if required. This now uses +%\cs{glsfmttext} and \cs{glsfmtname} instead of \cs{glsaccessshort} +%and \cs{glsaccessname} to allow for style formatting. % \begin{macrocode} \newcommand*{\glsxtrhiername}[1]{% \glsdoifexists{#1}% @@ -3611,7 +3794,7 @@ Dickimaw Books\\ \glsxtrifhasfield{parent}{#1}% {\glsxtrhiername{\glscurrentfieldvalue}\glsxtrhiernamesep}% {}% - \ifglshasshort{#1}{\glsaccessshort{#1}}{\glsaccessname{#1}}% + \ifglshasshort{#1}{\glsfmttext{#1}}{\glsfmtname{#1}}% }% } % \end{macrocode} @@ -3619,6 +3802,8 @@ Dickimaw Books\\ % %\begin{macro}{\Glsxtrhiername} %\changes{1.37}{2018-11-30}{new} +%\changes{1.42}{2020-02-03}{switched to using \cs{glsfmttext} and +%\cs{glsfmtname}} %\begin{definition} %\cs{Glsxtrhiername}\marg{label} %\end{definition} @@ -3630,9 +3815,9 @@ Dickimaw Books\\ \glsxtrifhasfield{parent}{#1}% {% \Glsxtrhiername{\glscurrentfieldvalue}\glsxtrhiernamesep - \ifglshasshort{#1}{\glsaccessshort{#1}}{\glsaccessname{#1}}% + \ifglshasshort{#1}{\glsfmttext{#1}}{\glsfmtname{#1}}% }% - {\ifglshasshort{#1}{\Glsaccessshort{#1}}{\Glsaccessname{#1}}}% + {\ifglshasshort{#1}{\Glsfmttext{#1}}{\Glsfmtname{#1}}}% }% } % \end{macrocode} @@ -3640,10 +3825,14 @@ Dickimaw Books\\ % %\begin{macro}{\GlsXtrhiername} %\changes{1.37}{2018-11-30}{new} +%\changes{1.42}{2020-02-03}{switched to using \cs{Glsfmttext} and +%\cs{Glsfmtname}} %\begin{definition} %\cs{GlsXtrhiername}\marg{label} %\end{definition} %As above but converts the first letter of each name to a capital. +%(Note that this isn't applying title case, just capitalising the +%start of each hierarchical element.) % \begin{macrocode} \newcommand*{\GlsXtrhiername}[1]{% \glsdoifexists{#1}% @@ -3651,7 +3840,7 @@ Dickimaw Books\\ \glsxtrifhasfield{parent}{#1}% {\GlsXtrhiername{\glscurrentfieldvalue}\glsxtrhiernamesep}% {}% - \ifglshasshort{#1}{\Glsaccessshort{#1}}{\Glsaccessname{#1}}% + \ifglshasshort{#1}{\Glsfmttext{#1}}{\Glsfmtname{#1}}% }% } % \end{macrocode} @@ -3659,6 +3848,8 @@ Dickimaw Books\\ % %\begin{macro}{\GLSxtrhiername} %\changes{1.37}{2018-11-30}{new} +%\changes{1.42}{2020-02-03}{switched to using \cs{glsfmttext}, +%\cs{glsfmtname}, \cs{GLSfmttext} and \cs{GLSfmtname}} %\begin{definition} %\cs{GLSxtrhiername}\marg{label} %\end{definition} @@ -3670,9 +3861,9 @@ Dickimaw Books\\ \glsxtrifhasfield{parent}{#1}% {% \GLSxtrhiername{\glscurrentfieldvalue}\glsxtrhiernamesep - \ifglshasshort{#1}{\glsaccessshort{#1}}{\glsaccessname{#1}}% + \ifglshasshort{#1}{\glsfmttext{#1}}{\glsfmtname{#1}}% }% - {\ifglshasshort{#1}{\GLSaccessshort{#1}}{\GLSaccessname{#1}}}% + {\ifglshasshort{#1}{\GLSfmttext{#1}}{\GLSfmtname{#1}}}% }% } % \end{macrocode} @@ -3680,6 +3871,8 @@ Dickimaw Books\\ % %\begin{macro}{\GLSXTRhiername} %\changes{1.37}{2018-11-30}{new} +%\changes{1.42}{2020-02-03}{switched to using \cs{GLSfmttext} and +%\cs{GLSfmtname}} %\begin{definition} %\cs{GLSXTRhiername}\marg{label} %\end{definition} @@ -3691,7 +3884,7 @@ Dickimaw Books\\ \glsxtrifhasfield{parent}{#1}% {\GLSXTRhiername{\glscurrentfieldvalue}\glsxtrhiernamesep}% {} - \ifglshasshort{#1}{\GLSaccessshort{#1}}{\GLSaccessname{#1}}% + \ifglshasshort{#1}{\GLSfmttext{#1}}{\GLSfmtname{#1}}% }% } % \end{macrocode} @@ -3724,6 +3917,30 @@ Dickimaw Books\\ % \end{macrocode} %\end{macro} % +%\begin{macro}{\glsxtrusealias} +%\changes{1.42}{2020-02-03}{new} +%Apply \cs{glsseeformat} to the \gloskey{alias} key if not empty. +%There's no optional tag to worry about here. The value also isn't a +%comma-separated list, but use the same interface. +% \begin{macrocode} +\newcommand*{\glsxtrusealias}[1]{% + \glsdoifexists{#1}% + {% + \letcs{\@glo@see}{glo@\glsdetoklabel{#1}@alias}% + \ifdefempty\@glo@see + {}% + {% +% \end{macrocode} +%Expansion isn't necessary because the value is a single label not a +%list. +% \begin{macrocode} + \glsxtruseseeformat{\seename}{\@glo@see}% + }% + }% +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\glsxtruseseealsoformat} %\changes{1.16}{2017-06-15}{new} %The format used by \cs{glsxtruseseealso}. The argument is the comma-separated @@ -3749,10 +3966,13 @@ Dickimaw Books\\ % %\begin{macro}{\seealsoname} %\changes{1.16}{2017-06-15}{new} -%In case this command hasn't been defined. (Should be provided by -%language packages.) +%\changes{1.42}{2020-02-03}{add check for \cs{alsoname}} +%In case this command hasn't been defined. Languages packages +%actually provide \ics{alsoname} so use that if it's defined. % \begin{macrocode} -\providecommand{\seealsoname}{see also} +\ifdef\alsoname +{\providecommand{\seealsoname}{\alsoname}} +{\providecommand{\seealsoname}{see also}} % \end{macrocode} %\end{macro} % @@ -4102,9 +4322,12 @@ Dickimaw Books\\ %sets \pkgopt[false]{docdef} (unless the restricted setting is on) %and disables the \pkgopt{docdef} key. %This command isn't allowed with the \pkgopt{record} option. +%\changes{1.42}{2020-02-03}{added \cs{@domakeglossaries}} % \begin{macrocode} \let\glsxtr@orgmakenoidxglossaries\makenoidxglossaries \renewcommand{\makenoidxglossaries}{% + \@domakeglossaries + {% \ifdefequal\@glsxtr@record@setting\@glsxtr@record@setting@off {% \glsxtr@orgmakenoidxglossaries @@ -4157,6 +4380,7 @@ Dickimaw Books\\ {You may only use \string\makenoidxglossaries\ space with the record=off option}% }% + }% } % \end{macrocode} %\end{macro} @@ -6028,13 +6252,36 @@ Dickimaw Books\\ %\end{macro} % %Commands like \cs{acrshort} already set \cs{glsifplural}, but they -%don't set \cs{glsxtrifwasfirstuse} so they need adjusting. +%don't set \cs{glsxtrifwasfirstuse} so they need adjusting. These +%commands shouldn't be used with \cs{newabbreviation}, but the +%redefinitions below allow for users reverting \cs{newacronym} back +%to its base definition. +% +%\begin{macro}{\@@glsxtr@base@acrcmd@warn} +% Warn user that they need to use to new abbreviation commands. +% \begin{macrocode} +\newcommand*{\@@glsxtr@base@acrcmd@warn}[2]{% + \GlossariesExtraWarning{Base acronym command \string#1\space + should not be used with new abbreviation definitions. Use + \string#2\space instead}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@glsxtr@base@acrcmd} +%\changes{1.42}{2020-02-03}{new} +% Warn user that they need to use to new abbreviation commands. +% \begin{macrocode} +\let\@glsxtr@base@acrcmd\@@glsxtr@base@acrcmd@warn +% \end{macrocode} +%\end{macro} % %\begin{macro}{\@acrshort} %\changes{0.3}{2015-12-02}{added redefinition} % No case change. % \begin{macrocode} \def\@acrshort#1#2[#3]{% + \@glsxtr@base@acrcmd\acrshort\glsxtrshort \glsdoifexists{#2}% {% \let\do@gls@link@checkfirsthyper\@gls@link@nocheckfirsthyper @@ -6057,6 +6304,7 @@ Dickimaw Books\\ % First letter uppercase. % \begin{macrocode} \def\@Acrshort#1#2[#3]{% + \@glsxtr@base@acrcmd\Acrshort\Glsxtrshort \glsdoifexists{#2}% {% \let\do@gls@link@checkfirsthyper\@gls@link@nocheckfirsthyper @@ -6079,6 +6327,7 @@ Dickimaw Books\\ % All uppercase. % \begin{macrocode} \def\@ACRshort#1#2[#3]{% + \@glsxtr@base@acrcmd\ACRshort\GLSxtrshort \glsdoifexists{#2}% {% \let\do@gls@link@checkfirsthyper\@gls@link@nocheckfirsthyper @@ -6101,6 +6350,7 @@ Dickimaw Books\\ % No case change. % \begin{macrocode} \def\@acrshortpl#1#2[#3]{% + \@glsxtr@base@acrcmd\acrshortpl\glsxtrshortpl \glsdoifexists{#2}% {% \let\do@gls@link@checkfirsthyper\@gls@link@nocheckfirsthyper @@ -6123,6 +6373,7 @@ Dickimaw Books\\ % First letter uppercase. % \begin{macrocode} \def\@Acrshortpl#1#2[#3]{% + \@glsxtr@base@acrcmd\Acrshortpl\Glsxtrshortpl \glsdoifexists{#2}% {% \let\do@gls@link@checkfirsthyper\@gls@link@nocheckfirsthyper @@ -6145,6 +6396,7 @@ Dickimaw Books\\ % All uppercase. % \begin{macrocode} \def\@ACRshortpl#1#2[#3]{% + \@glsxtr@base@acrcmd\ACRshortpl\GLSxtrshortpl \glsdoifexists{#2}% {% \let\do@gls@link@checkfirsthyper\@gls@link@nocheckfirsthyper @@ -6167,6 +6419,7 @@ Dickimaw Books\\ % No case change. % \begin{macrocode} \def\@acrlong#1#2[#3]{% + \@glsxtr@base@acrcmd\acrlong\glsxtrlong \glsdoifexists{#2}% {% \let\do@gls@link@checkfirsthyper\@gls@link@nocheckfirsthyper @@ -6189,6 +6442,7 @@ Dickimaw Books\\ % First letter uppercase. % \begin{macrocode} \def\@Acrlong#1#2[#3]{% + \@glsxtr@base@acrcmd\Acrlong\Glsxtrlong \glsdoifexists{#2}% {% \let\do@gls@link@checkfirsthyper\@gls@link@nocheckfirsthyper @@ -6211,6 +6465,7 @@ Dickimaw Books\\ % All uppercase. % \begin{macrocode} \def\@ACRlong#1#2[#3]{% + \@glsxtr@base@acrcmd\ACRlong\GLSxtrlong \glsdoifexists{#2}% {% \let\do@gls@link@checkfirsthyper\@gls@link@nocheckfirsthyper @@ -6233,6 +6488,7 @@ Dickimaw Books\\ % No case change. % \begin{macrocode} \def\@acrlongpl#1#2[#3]{% + \@glsxtr@base@acrcmd\acrlongpl\glsxtrlongpl \glsdoifexists{#2}% {% \let\do@gls@link@checkfirsthyper\@gls@link@nocheckfirsthyper @@ -6255,6 +6511,7 @@ Dickimaw Books\\ % First letter uppercase. % \begin{macrocode} \def\@Acrlongpl#1#2[#3]{% + \@glsxtr@base@acrcmd\Acrlongpl\Glsxtrlongpl \glsdoifexists{#2}% {% \let\do@gls@link@checkfirsthyper\@gls@link@nocheckfirsthyper @@ -6277,6 +6534,7 @@ Dickimaw Books\\ % All uppercase. % \begin{macrocode} \def\@ACRlongpl#1#2[#3]{% + \@glsxtr@base@acrcmd\ACRlongpl\GLSxtrlongpl \glsdoifexists{#2}% {% \let\do@gls@link@checkfirsthyper\@gls@link@nocheckfirsthyper @@ -6294,6 +6552,73 @@ Dickimaw Books\\ % \end{macrocode} %\end{macro} % +%The full formats use the internal long and short commands (such as +%\cs{@acrshort} and \cs{@acrlong}). Therefore they don't need +%adjustments, but they do need clearer warnings. This means three +%warnings per use (once for the full command and once each for the +%short and long commands), but at least this way the most important +%warning (replace \cs{acrfull} with \cs{glsxtrfull} etc) is present. +% +%\begin{macro}{\@acrfull} +%\changes{1.42}{2020-02-03}{added redefinition} +% \begin{macrocode} +\def\@acrfull#1#2[#3]{% + \@glsxtr@base@acrcmd\acrfull\glsxtrfull + \acrfullfmt{#1}{#2}{#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@Acrfull} +%\changes{1.42}{2020-02-03}{added redefinition} +% \begin{macrocode} +\def\@Acrfull#1#2[#3]{% + \@glsxtr@base@acrcmd\Acrfull\Glsxtrfull + \Acrfullfmt{#1}{#2}{#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@ACRfull} +%\changes{1.42}{2020-02-03}{added redefinition} +% \begin{macrocode} +\def\@ACRfull#1#2[#3]{% + \@glsxtr@base@acrcmd\ACRfull\GLSxtrfull + \ACRfullfmt{#1}{#2}{#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@acrfullpl} +%\changes{1.42}{2020-02-03}{added redefinition} +% \begin{macrocode} +\def\@acrfullpl#1#2[#3]{% + \@glsxtr@base@acrcmd\acrfullpl\glsxtrfullpl + \acrfullplfmt{#1}{#2}{#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@Acrfullpl} +%\changes{1.42}{2020-02-03}{added redefinition} +% \begin{macrocode} +\def\@Acrfullpl#1#2[#3]{% + \@glsxtr@base@acrcmd\Acrfullpl\Glsxtrfullpl + \Acrfullplfmt{#1}{#2}{#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@ACRfullpl} +%\changes{1.42}{2020-02-03}{added redefinition} +% \begin{macrocode} +\def\@ACRfullpl#1#2[#3]{% + \@glsxtr@base@acrcmd\ACRfullpl\GLSxtrfullpl + \ACRfullplfmt{#1}{#2}{#3}% +} +% \end{macrocode} +%\end{macro} +% %Modify \cs{@glsaddkey} so additional keys provided by the user can %be treated in a similar way. %\begin{macro}{\@glsaddkey} @@ -6691,6 +7016,19 @@ Dickimaw Books\\ % \begin{macrocode} \newcommand*{\GlsXtrSetAltModifier}[2]{% \let\@gls@hyp@opt\@gls@alt@hyp@opt +% \end{macrocode} +%\changes{1.42}{2020-02-03}{added check} +%Check that the supplied character isn't "+" or "*" +% \begin{macrocode} + \ifstrequal{#1}{+}% + {\PackageError{glossaries-extra}% + {Can't use '#1' as modifier (it's already in use)}{}}% + {% + \ifstrequal{#1}{*}% + {\PackageError{glossaries-extra}% + {Can't use '#1' as modifier (it's already in use)}{}}% + {}% + }% \def\@gls@alt@hyp@opt@char{#1}% \def\@gls@alt@hyp@opt@keys{#2}% \ifdefequal\@glsxtr@record@setting\@glsxtr@record@setting@off @@ -6716,11 +7054,10 @@ Dickimaw Books\\ % %\begin{macro}{\glsnavhyperlink} %\changes{1.21}{2017-11-03}{patched} -%Now that \cs{glsdohyperlink} (used by \cs{@glslink}) references -%\cs{glslabel} it's necessary to patch \cs{glsnavhyperlink} to -%avoid using it (since \cs{glslabel} won't be defined). This means -%temporarily redefining \cs{glsdohyperlink} to its original -%definition. +%Since \ics{glsnavhyperlink} uses \cs{@glslink}, it's necessary to +%patch it uses \cs{glsdohyperlink} instead of \cs{glsxtrdohyperlink}. +%The simplest way to achieve this is to locally let +%\cs{glsxtrdohyperlink} to \cs{glsdohyperlink}. % %This command is provided by \sty{glossary-hypernav} so it may not %exist. @@ -6733,7 +7070,7 @@ Dickimaw Books\\ %Scope: % \begin{macrocode} {% - \let\glsdohyperlink\glsxtr@org@dohyperlink + \let\glsxtrdohyperlink\glsxtr@org@dohyperlink \@glslink{\glsnavhyperlinkname{#1}{#2}}{#3}% }% }% @@ -6742,7 +7079,11 @@ Dickimaw Books\\ % \end{macrocode} %\end{macro} % -%\begin{macro}{\glsdohyperlink} +% +%The redefinition of \cs{glsdohyperlink} has been causing problems +%so introduce a new command instead. +% +%\begin{macro}{\glsxtrdohyperlink} % Unpleasant complications can occur if the \gloskey{text} or % \gloskey{first} key etc contains \cs{gls}, particularly if there % are hyperlinks. To get around this problem, patch @@ -6755,8 +7096,10 @@ Dickimaw Books\\ % long form commands like \cs{acrlong} and \cs{glsxtrlong} to use % \cs{glsentrylong}. Added attribute check. %\changes{0.5.4}{2015-12-15}{added} +%\changes{1.42}{2020-02-03}{new (was former redefinition of +%\cs{glsdohyperlink})} % \begin{macrocode} -\renewcommand*{\glsdohyperlink}[2]{% +\newcommand*{\glsxtrdohyperlink}[2]{% \glshasattribute{\glslabel}{targeturl}% {% \glshasattribute{\glslabel}{targetname}% @@ -6860,10 +7203,12 @@ Dickimaw Books\\ %\changes{1.21}{2017-11-03}{changed to use \cs{def} rather than \cs{let}} %This now uses \cs{def} rather than \cs{let} to allow for %redefinitions of \cs{glsdohypertarget} and \cs{glsdohyperlink}. +%\changes{1.42}{2020-02-03}{switched from \cs{glsdohyperlink} to +%\cs{glsxtrdohyperlink}} % \begin{macrocode} \renewcommand{\glsenablehyper}{% \KV@glslink@hypertrue - \def\@glslink{\glsdohyperlink}% + \def\@glslink{\glsxtrdohyperlink}% \def\@glstarget{\glsdohypertarget}% } % \end{macrocode} @@ -6885,13 +7230,15 @@ Dickimaw Books\\ %\begin{macro}{\@glslink} % Reset \cs{@glslink} with patched versions: %\changes{1.21}{2017-11-03}{changed \cs{let} to \cs{def}} +%\changes{1.42}{2020-02-03}{switched from \cs{glsdohyperlink} to +%\cs{glsxtrdohyperlink}} % \begin{macrocode} \ifcsundef{hyperlink}% {% \def\@glslink{\glsdonohyperlink} }% {% - \def\@glslink{\glsdohyperlink} + \def\@glslink{\glsxtrdohyperlink} } % \end{macrocode} %\end{macro} @@ -7636,6 +7983,17 @@ Dickimaw Books\\ % \end{macrocode} %\end{macro} % +%\begin{macro}{\GlsXtrDiscardUnsetBuffering} +%\changes{1.42}{2020-02-03}{new} +%Discards pending buffer and restores \cs{glsunset}. +% \begin{macrocode} +\newcommand*{\GlsXtrDiscardUnsetBuffering}{% + \let\@glsunset\@glsxtr@unset + \let\@glsxtr@unset@buffer\@glsxtr@org@unset@buffer +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\GlsXtrForUnsetBufferedList} %\changes{1.31}{2018-05-09}{new} %Iterate over labels stored in the current buffer. @@ -8548,7 +8906,20 @@ Dickimaw Books\\ %\begin{macro}{\SetGenericNewAcronym} % \begin{macrocode} \renewcommand*{\SetGenericNewAcronym}{% +% \end{macrocode} +% Make sure \cs{RestoreAcronyms} has been used. +% \begin{macrocode} + \ifdefequal\@addtoacronymlists\@glsxtr@org@addtoacronynlists + {}% + {% + \GlossariesWarning{\string\SetGenericNewAcronym\space used + without restoring base acronym functions with + \string\RestoreAcronyms}% + }% \let\@Gls@entryname\@Gls@acrentryname +% \end{macrocode} +%Redefine \cs{newacronym}: +% \begin{macrocode} \renewcommand{\newacronym}[4][]{% \ifdefempty{\@glsacronymlists}% {% @@ -8612,6 +8983,75 @@ Dickimaw Books\\ \let\@glsxtr@org@newacronymstyle\newacronymstyle % \end{macrocode} % +%Save the list of acronyms in case they are required. +%\begin{macro}{\@glsxtr@acronymlists} +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\let\@glsxtr@acronymlists\@glsacronymlists +% \end{macrocode} +%\end{macro} +%\begin{macro}{\@glsxtr@org@addtoacronynlists} +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\let\@glsxtr@org@addtoacronynlists\@addtoacronymlists +% \end{macrocode} +%\end{macro} +%\begin{macro}{\@glsxtr@org@setacronymlists} +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\let\@glsxtr@org@setacronymlists\SetAcronymLists +% \end{macrocode} +%\end{macro} +% +%Need to provide a replacement for \ics{forallacronyms} since +%\cs{@glsacronymlists} isn't available. +% +%\begin{macro}{\@glsxtr@abbrlists} +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newcommand{\@glsxtr@abbrlists}{} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\forallabbreviationlists} +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newcommand*{\forallabbreviationlists}[2]{% + \@for#1:=\@glsxtr@abbrlists\do{\ifdefempty{#1}{}{#2}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@glsxtr@addabbreviationlist} +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newcommand*{\@glsxtr@addabbreviationlist}[1]{% + \edef\@glo@type{#1}% + \ifdefempty\@glsxtr@abbrlists + {\let\@glsxtr@abbrlists\@glo@type}% + {% + \ifdefequal\@glsxtr@abbrlists\@glo@type + {}% + {% + \expandafter\DTLifinlist\expandafter{\@glo@type}{\@glsxtr@abbrlists}{}% + {\eappto\@glsxtr@abbrlists{,\@glo@type}}% + }% + }% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\forallacronyms} +%\changes{1.42}{2020-02-03}{new} +%Modify to add warning. +% \begin{macrocode} +\renewcommand*{\forallacronyms}[2]{% + \@glsxtr@base@acrcmd\forallacronyms\forallabbreviationlists + \@for#1:=\@glsacronymlists\do{\ifx#1\@empty\else#2\fi}% +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\MakeAcronymsAbbreviations} % Make acronyms use the same interface as abbreviations. % Note that \cs{newacronymstyle} has a different implementation to @@ -8621,6 +9061,27 @@ Dickimaw Books\\ %\changes{0.5.4}{2015-12-15}{now disables \cs{setacronymstyle}} % \begin{macrocode} \newcommand*{\MakeAcronymsAbbreviations}{% +% \end{macrocode} +%Undo acronym display style: +% \begin{macrocode} + \@for\@gls@type:=\@glsacronymlists\do{% + \csgdef{gls@\@gls@type @entryfmt}{\glsentryfmt}% + }% +% \end{macrocode} +% Save and clear acronym list. +% \begin{macrocode} + \let\@glsxtr@acronymlists\@glsacronymlists + \let\@glsacronymlists\@empty + \let\@addtoacronymlists\@gobble + \let\SetAcronymLists\@gobble +% \end{macrocode} +% Warn if \cs{acrshort} etc are used. +% \begin{macrocode} + \let\@glsxtr@base@acrcmd\@@glsxtr@base@acrcmd@warn +% \end{macrocode} +% Redefine \cs{newacronym} to use same interface as +% \cs{newabbreviation}. +% \begin{macrocode} \renewcommand*{\newacronym}[4][]{% \glsxtr@newabbreviation{type=\acronymtype,category=acronym,##1}{##2}{##3}{##4}% }% @@ -8629,7 +9090,7 @@ Dickimaw Books\\ \renewcommand*{\setacronymstyle}[1]{% \PackageError{glossaries-extra}{\string\setacronymstyle{##1} unavailable. - Use \string\setabbreviationstyle\space instead. + Use \string\setabbreviationstyle[acronym]\space instead. The original acronym interface can be restored with \string\RestoreAcronyms}{}% }% @@ -8652,6 +9113,26 @@ Dickimaw Books\\ % Restore acronyms to \styfmt{glossaries} interface. % \begin{macrocode} \newcommand*{\RestoreAcronyms}{% +% \end{macrocode} +% Restore acronym list. +% \begin{macrocode} + \let\@glsacronymlists\@glsxtr@acronymlists + \let\@addtoacronymlists\@glsxtr@org@addtoacronynlists + \let\SetAcronymLists\@glsxtr@org@setacronymlists +% \end{macrocode} +% Suppress warnings if \cs{acrshort} etc are used. +% \begin{macrocode} + \let\@glsxtr@base@acrcmd\@gobbletwo +% \end{macrocode} +%Restore acronym display style: +%\changes{1.42}{2020-02-03}{added display style} +% \begin{macrocode} + \@for\@gls@type:=\@glsacronymlists\do{% + \SetDefaultAcronymDisplayStyle{\@gls@type}% + }% +% \end{macrocode} +%Switch to the generic acronym mechanism. +% \begin{macrocode} \SetGenericNewAcronym \renewcommand{\firstacronymfont}[1]{\acronymfont{##1}}% \renewcommand{\acronymfont}[1]{##1}% @@ -8713,6 +9194,16 @@ Dickimaw Books\\ \let\@glsxtr@org@makeglossaries\makeglossaries % \end{macrocode} % +%\begin{macro}{\@domakeglossaries} +%\changes{1.42}{2020-02-03}{provided definition for \cs{@domakeglossaries}} +% \sty{glossaries} v4.45 introduced \cs{@domakeglossaries} to +% provide a way of disabling \cs{makeglossaries}. If it hasn't been +% defined, define here to do its argument: +% \begin{macrocode} +\providecommand{\@domakeglossaries}[1]{#1} +% \end{macrocode} +%\end{macro} +% % Redefine \cs{makeglossaries} to take an optional argument. % This should be empty for the usual behaviour (all glossaries % need processing with an indexing application) or a comma-separated @@ -8721,211 +9212,221 @@ Dickimaw Books\\ % version shouldn't be used with \pkgopt{record}. %\begin{macro}{\makeglossaries} %\changes{1.0}{2016-01-24}{new} +%\changes{1.42}{2020-02-03}{added \cs{@domakeglossaries}} % \begin{macrocode} \renewcommand*{\makeglossaries}[1][]{% - \@glsxtr@if@record@only - {% - \PackageError{glossaries-extra}{\string\makeglossaries\space - not permitted\MessageBreak with record=\@glsxtr@record@setting\space - package option}% - {You may only use \string\makeglossaries\space with - record=off or record=alsoindex options}% - }% + \@domakeglossaries {% - \ifblank{#1}% - {\@glsxtr@org@makeglossaries}% + \@glsxtr@if@record@only {% - \ifx\@glsxtr@record@setting\@glsxtr@record@setting@alsoindex - \PackageError{glossaries-extra}{\string\makeglossaries[#1]\space - not permitted\MessageBreak with record=alsoindex package option}% - {You may only use the hybrid \string\makeglossaries[...]\space with - record=off option}% - \else -% \end{macrocode} -%\cs{@gls@@automake@immediate} was introduced to \sty{glossaries} -%v4.42 so it may not be defined. + \PackageError{glossaries-extra}{\string\makeglossaries\space + not permitted\MessageBreak with record=\@glsxtr@record@setting\space + package option}% + {You may only use \string\makeglossaries\space with + record=off or record=alsoindex options}% + }% + {% + \ifblank{#1}% + {\@glsxtr@org@makeglossaries}% + {% + \ifx\@glsxtr@record@setting\@glsxtr@record@setting@alsoindex + \PackageError{glossaries-extra}{\string\makeglossaries[#1]\space + not permitted\MessageBreak with record=alsoindex package option}% + {You may only use the hybrid \string\makeglossaries[...]\space with + record=off option}% + \else +% \end{macrocode} +%\cs{@gls@@automake@immediate} was introduced to \sty{glossaries} +%v4.42 so it may not be defined. % \begin{macrocode} - \ifdef\@gls@@automake@immediate{\@gls@@automake@immediate}{}% - \edef\@glsxtr@reg@glosslist{#1}% - \ifundef{\glswrite}{\newwrite\glswrite}{}% - \protected@write\@auxout{}{\string\providecommand - \string\@glsorder[1]{}} - \protected@write\@auxout{}{\string\providecommand - \string\@istfilename[1]{}} - \protected@write\@auxout{}{\string\@istfilename{\istfilename}}% - \protected@write\@auxout{}{\string\@glsorder{\glsorder}} - \protected@write\@auxout{}{\string\glsxtr@makeglossaries{#1}} - \write\@auxout{\string\providecommand\string\@gls@reference[3]{}}% + \ifdef\@gls@@automake@immediate{\@gls@@automake@immediate}{}% + \edef\@glsxtr@reg@glosslist{#1}% + \ifundef{\glswrite}{\newwrite\glswrite}{}% + \protected@write\@auxout{}{\string\providecommand + \string\@glsorder[1]{}} + \protected@write\@auxout{}{\string\providecommand + \string\@istfilename[1]{}} + \protected@write\@auxout{}{\string\@istfilename{\istfilename}}% + \protected@write\@auxout{}{\string\@glsorder{\glsorder}} + \protected@write\@auxout{}{\string\glsxtr@makeglossaries{#1}} + \write\@auxout{\string\providecommand\string\@gls@reference[3]{}}% % \end{macrocode} % Iterate through each supplied glossary type and activate it. % \begin{macrocode} - \@for\@glo@type:=#1\do{% - \ifdefempty{\@glo@type}{}{\@makeglossary{\@glo@type}}% - }% + \@for\@glo@type:=#1\do{% + \ifdefempty{\@glo@type}{}{\@makeglossary{\@glo@type}}% + }% % \end{macrocode} % New glossaries must be created before \cs{makeglossaries}: % \begin{macrocode} - \renewcommand*\newglossary[4][]{% - \PackageError{glossaries}{New glossaries - must be created before \string\makeglossaries}{You need - to move \string\makeglossaries\space after all your - \string\newglossary\space commands}}% + \renewcommand*\newglossary[4][]{% + \PackageError{glossaries}{New glossaries + must be created before \string\makeglossaries}{You need + to move \string\makeglossaries\space after all your + \string\newglossary\space commands}}% +% \end{macrocode} +% Any subsequence instances of this command should have no effect. +%\changes{1.42}{2020-02-03}{let \cs{@makeglossary} to \cs{@gobble} +%instead of \cs{relax}} +% \begin{macrocode} + \let\@makeglossary\@gobble % \end{macrocode} -% Any subsequence instances of this command should have no effect +%\changes{1.42}{2020-02-03}{removed redefinition of \cs{makeglossary}} +%Version 1.42 removed letting \cs{makeglossary} to \cs{relax} +%(no kernel redefs may be in effect). % \begin{macrocode} - \let\@makeglossary\relax - \let\makeglossary\relax - \renewcommand\makeglossaries[1][]{}% + \renewcommand\makeglossaries[1][]{}% % \end{macrocode} % Disable all commands that have no effect after \cs{makeglossaries} % \begin{macrocode} - \@disable@onlypremakeg + \@disable@onlypremakeg % \end{macrocode} % Allow \gloskey{see} key: % \begin{macrocode} - \let\gls@checkseeallowed\relax + \let\gls@checkseeallowed\relax % \end{macrocode} %Adjust \cs{@do@seeglossary}. This needs to check for the entry's %existence but don't increment associated counter. % \begin{macrocode} - \renewcommand*{\@do@seeglossary}[2]{% - \glsdoifexists{##1}% - {% - \edef\@gls@label{\glsdetoklabel{##1}}% - \edef\@gls@type{\csname glo@\@gls@label @type\endcsname}% - \expandafter\DTLifinlist\expandafter{\@gls@type}{\@glsxtr@reg@glosslist}% - {\@glsxtr@org@doseeglossary{##1}{##2}}% + \renewcommand*{\@do@seeglossary}[2]{% + \glsdoifexists{##1}% {% - \@@glsxtrwrglossmark - \protected@write\@auxout{}{% - \string\@gls@reference - {\gls@type}{\@gls@label}{\string\glsseeformat##2{}}% + \edef\@gls@label{\glsdetoklabel{##1}}% + \edef\@gls@type{\csname glo@\@gls@label @type\endcsname}% + \expandafter\DTLifinlist\expandafter{\@gls@type}{\@glsxtr@reg@glosslist}% + {\@glsxtr@org@doseeglossary{##1}{##2}}% + {% + \@@glsxtrwrglossmark + \protected@write\@auxout{}{% + \string\@gls@reference + {\gls@type}{\@gls@label}{\string\glsseeformat##2{}}% + }% }% }% }% - }% % \end{macrocode} % Adjust \cs{@@do@@wrglossary} % \begin{macrocode} - \let\@glsxtr@@do@@wrglossary\@@do@@wrglossary - \def\@@do@@wrglossary{% - \edef\@gls@type{\csname glo@\@gls@label @type\endcsname}% - \expandafter\DTLifinlist\expandafter{\@gls@type}{\@glsxtr@reg@glosslist}% - {\@glsxtr@@do@@wrglossary}% - {\gls@noidxglossary}% - }% + \let\@glsxtr@@do@@wrglossary\@@do@@wrglossary + \def\@@do@@wrglossary{% + \edef\@gls@type{\csname glo@\@gls@label @type\endcsname}% + \expandafter\DTLifinlist\expandafter{\@gls@type}{\@glsxtr@reg@glosslist}% + {\@glsxtr@@do@@wrglossary}% + {\gls@noidxglossary}% + }% % \end{macrocode} % Suppress warning about no \cs{makeglossaries} % \begin{macrocode} - \let\warn@nomakeglossaries\relax - \def\warn@noprintglossary{% - \GlossariesWarningNoLine{No \string\printglossary\space - or \string\printglossaries\space - found.^^J(Remove \string\makeglossaries\space if you don't want - any glossaries.)^^JThis document will not have a glossary}% - }% + \let\warn@nomakeglossaries\relax + \def\warn@noprintglossary{% + \GlossariesWarningNoLine{No \string\printglossary\space + or \string\printglossaries\space + found.^^J(Remove \string\makeglossaries\space if you don't want + any glossaries.)^^JThis document will not have a glossary}% + }% % \end{macrocode} % Only warn for glossaries not listed. % \begin{macrocode} - \renewcommand{\@gls@noref@warn}[1]{% - \edef\@gls@type{##1}% - \expandafter\DTLifinlist\expandafter{\@gls@type}{\@glsxtr@reg@glosslist}% - {% - \GlossariesExtraWarning{Can't use - \string\printnoidxglossary[type={\@gls@type}] - when `\@gls@type' is listed in the optional argument of - \string\makeglossaries}% - }% - {% - \GlossariesWarning{Empty glossary for - \string\printnoidxglossary[type={##1}]. - Rerun may be required (or you may have forgotten to use - commands like \string\gls)}% + \renewcommand{\@gls@noref@warn}[1]{% + \edef\@gls@type{##1}% + \expandafter\DTLifinlist\expandafter{\@gls@type}{\@glsxtr@reg@glosslist}% + {% + \GlossariesExtraWarning{Can't use + \string\printnoidxglossary[type={\@gls@type}] + when `\@gls@type' is listed in the optional argument of + \string\makeglossaries}% + }% + {% + \GlossariesWarning{Empty glossary for + \string\printnoidxglossary[type={##1}]. + Rerun may be required (or you may have forgotten to use + commands like \string\gls)}% + }% }% - }% % \end{macrocode} % Adjust display number list to check for type: % \begin{macrocode} - \renewcommand*{\glsdisplaynumberlist}[1]{% - \expandafter\DTLifinlist\expandafter{##1}{\@glsxtr@reg@glosslist}% - {\@glsxtr@idx@displaynumberlist{##1}}% - {\@glsxtr@noidx@displaynumberlist{##1}}% - }% + \renewcommand*{\glsdisplaynumberlist}[1]{% + \expandafter\DTLifinlist\expandafter{##1}{\@glsxtr@reg@glosslist}% + {\@glsxtr@idx@displaynumberlist{##1}}% + {\@glsxtr@noidx@displaynumberlist{##1}}% + }% % \end{macrocode} % Adjust entry list: % \begin{macrocode} - \renewcommand*{\glsentrynumberlist}[1]{% - \expandafter\DTLifinlist\expandafter{##1}{\@glsxtr@reg@glosslist}% - {\@glsxtr@idx@entrynumberlist{##1}}% - {\@glsxtr@noidx@entrynumberlist{##1}}% - }% + \renewcommand*{\glsentrynumberlist}[1]{% + \expandafter\DTLifinlist\expandafter{##1}{\@glsxtr@reg@glosslist}% + {\@glsxtr@idx@entrynumberlist{##1}}% + {\@glsxtr@noidx@entrynumberlist{##1}}% + }% % \end{macrocode} % Adjust number list loop % \begin{macrocode} - \renewcommand*{\glsnumberlistloop}[2]{% - \expandafter\DTLifinlist\expandafter{##1}{\@glsxtr@reg@glosslist}% - {% - \PackageError{glossaries-extra}{\string\glsnumberlistloop\space - not available for glossary `##1'}{}% + \renewcommand*{\glsnumberlistloop}[2]{% + \expandafter\DTLifinlist\expandafter{##1}{\@glsxtr@reg@glosslist}% + {% + \PackageError{glossaries-extra}{\string\glsnumberlistloop\space + not available for glossary `##1'}{}% + }% + {\@glsxtr@noidx@numberlistloop{##1}{##2}}% }% - {\@glsxtr@noidx@numberlistloop{##1}{##2}}% - }% % \end{macrocode} % Only sanitize sort for normal indexing glossaries. % \begin{macrocode} - \renewcommand*{\glsprestandardsort}[3]{% - \expandafter\DTLifinlist\expandafter{##2}{\@glsxtr@reg@glosslist}% - {% - \glsdosanitizesort - }% - {% - \ifglssanitizesort - \@gls@noidx@sanitizesort - \else - \@gls@noidx@nosanitizesort - \fi + \renewcommand*{\glsprestandardsort}[3]{% + \expandafter\DTLifinlist\expandafter{##2}{\@glsxtr@reg@glosslist}% + {% + \glsdosanitizesort + }% + {% + \ifglssanitizesort + \@gls@noidx@sanitizesort + \else + \@gls@noidx@nosanitizesort + \fi + }% }% - }% % \end{macrocode} % Unlike \cs{makenoidxglossaries} we can't automatically set % sanitizesort=false. All entries must be defined in the preamble. % \begin{macrocode} - \renewcommand*\new@glossaryentry[2]{% - \PackageError{glossaries-extra}{Glossary entries must be defined - in the preamble\MessageBreak when you use the optional argument - of \string\makeglossaries}{Either move your definitions to the - preamble or don't use the optional argument of - \string\makeglossaries}% - }% + \renewcommand*\new@glossaryentry[2]{% + \PackageError{glossaries-extra}{Glossary entries must be defined + in the preamble\MessageBreak when you use the optional argument + of \string\makeglossaries}{Either move your definitions to the + preamble or don't use the optional argument of + \string\makeglossaries}% + }% % \end{macrocode} % Only activate sort key for glossaries that aren't listed in % \verb|#1| (glossary label is stored in \cs{@glo@type} but this % defaults to \cs{glsdefaulttype} so some expansion is required). % \begin{macrocode} - \let\@glo@assign@sortkey\@glsxtr@mixed@assign@sortkey - \renewcommand*{\@printgloss@setsort}{% + \let\@glo@assign@sortkey\@glsxtr@mixed@assign@sortkey + \renewcommand*{\@printgloss@setsort}{% % \end{macrocode} % Need to extract just the \gloskey[printglossary]{type} value. % \begin{macrocode} - \expandafter\@glsxtr@gettype\expandafter,\@glsxtr@printglossopts,% - type=\glsdefaulttype,\@end@glsxtr@gettype - \def\@glo@sorttype{\@glo@default@sorttype}% - }% + \expandafter\@glsxtr@gettype\expandafter,\@glsxtr@printglossopts,% + type=\glsdefaulttype,\@end@glsxtr@gettype + \def\@glo@sorttype{\@glo@default@sorttype}% + }% % \end{macrocode} % Check \pkgopt{automake} setting: % \begin{macrocode} - \ifglsautomake - \renewcommand*{\@gls@doautomake}{% - \@for\@gls@type:=\@glsxtr@reg@glosslist\do{% - \ifdefempty{\@gls@type}{}{\@gls@automake{\@gls@type}}% + \ifglsautomake + \renewcommand*{\@gls@doautomake}{% + \@for\@gls@type:=\@glsxtr@reg@glosslist\do{% + \ifdefempty{\@gls@type}{}{\@gls@automake{\@gls@type}}% + }% }% - }% - \fi + \fi % \end{macrocode} % Check the sort setting (\sty{glossaries} v4.30 onwards): % \begin{macrocode} - \ifdef\@glo@check@sortallowed{\@glo@check@sortallowed\makeglossaries}{}% - \fi + \ifdef\@glo@check@sortallowed{\@glo@check@sortallowed\makeglossaries}{}% + \fi + }% }% }% } @@ -10198,6 +10699,19 @@ Dickimaw Books\\ \let\@gls@doautomake\relax \fi \fi +% \end{macrocode} +% Check if \pkgopt[letter]{order} has been used by mistake (but not +% if \pkgopt[alsoindex]{record} has been used). +%\changes{1.42}{2020-02-03}{added check for order\protect\dequals letter} +% \begin{macrocode} + \@glsxtr@if@record@only + {\ifdefstring{\glsorder}{letter}% + {\GlossariesExtraWarningNoLine{Package option `order=letter' isn't + supported with `record=\@glsxtr@record@setting'. Use `break-at=none' + resource option instead}}% + {}% + }% + {}% } % \end{macrocode} %\end{macro} @@ -12079,12 +12593,24 @@ defined}{}% } % \end{macrocode} % +% \begin{macrocode} + \define@key{glsxtrabbrv}{pluralaccess}{% + \def\@gls@pluralaccess{#1}% + } +% \end{macrocode} +% % \begin{macrocode} \define@key{glsxtrabbrv}{firstaccess}{% \def\@gls@firstaccess{#1}% } % \end{macrocode} % +% \begin{macrocode} + \define@key{glsxtrabbrv}{firstpluralaccess}{% + \def\@gls@firstpluralaccess{#1}% + } +% \end{macrocode} +% % \begin{macrocode} \define@key{glsxtrabbrv}{shortaccess}{% \def\@gls@shortaccess{#1}% @@ -12096,15 +12622,31 @@ defined}{}% \def\@gls@shortaccesspl{#1}% } % \end{macrocode} +% +% \begin{macrocode} + \define@key{glsxtrabbrv}{longaccess}{% + \def\@gls@longaccess{#1}% + } +% \end{macrocode} +% +% \begin{macrocode} + \define@key{glsxtrabbrv}{shortlonglaccess}{% + \def\@gls@longaccesspl{#1}% + } +% \end{macrocode} %\begin{macro}{\@gls@initaccesskeys} %\changes{1.31}{2018-05-09}{new} % \begin{macrocode} \newcommand*{\@gls@initaccesskeys}{% \def\@gls@nameaccess{}% \def\@gls@textaccess{}% + \def\@gls@pluralaccess{}% \def\@gls@firstaccess{}% + \def\@gls@firstpluralaccess{}% \def\@gls@shortaccess{}% \def\@gls@shortaccesspl{}% + \def\@gls@longaccess{}% + \def\@gls@longaccesspl{}% } % \end{macrocode} %\end{macro} @@ -12131,40 +12673,124 @@ defined}{}% % \end{macrocode} %\end{macro} % +%As from \sty{glossaries} v4.45, the replacement text support has +%been corrected so that the accessibility support for abbreviations +%use the \qt{E} (expanded value) element. This should actually +%contain the long form since it's supposed to explain the +%abbreviation. This is a bit redundant on first use for styles like +%\abbrstyle{long-short}. +% +%\begin{macro}{\glsdefaultshortaccess} +%\changes{1.42}{2020-02-03}{new} +%\begin{definition} +%\cs{glsdefaultshortaccess}\marg{long}\marg{short} +%\end{definition} +%This command was only introduced to \sty{glossaries-accsupp} 1.42 +%so it may not be defined. +% \begin{macrocode} + \def\glsdefaultshortaccess#1#2{#1 (#2)} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\glsxtrassignactualsetup} +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} + \newcommand{\glsxtrassignactualsetup}{% + \let\@\empty + \let\emph\@firstofone + \let\textbf\@firstofone + \let\textmd\@firstofone + \let\textit\@firstofone + \let\textsl\@firstofone + \let\textsc\@firstofone + \let\textrm\@firstofone + \let\textsf\@firstofone + \let\texttt\@firstofone + } +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@gls@assign@actual} +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} + \ifdef\pdfstringdef + { + \newcommand{\@gls@assign@actual}{% + \begingroup + \glsxtrassignactualsetup + \pdfstringdef\@gls@actualshort{\glsxtrorgshort}% + \pdfstringdef\@gls@actuallong{\glsxtrorglong}% + \pdfstringdef\@gls@actualshortpl{\@gls@shortpl}% + \pdfstringdef\@gls@actuallongpl{\@gls@longpl}% + \protected@edef\@gls@tmp{\endgroup + \def\noexpand\@gls@actualshort{\expandonce\@gls@actualshort}% + \def\noexpand\@gls@actuallong{\expandonce\@gls@actuallong}% + \def\noexpand\@gls@actualshortpl{\expandonce\@gls@actualshortpl}% + \def\noexpand\@gls@actuallongpl{\expandonce\@gls@actuallongpl}% + }% + \@gls@tmp + } + } + { + \newcommand{\@gls@assign@actual}{% + \begingroup + \glsxtrassignactualsetup + \protected@edef\@gls@tmp{\endgroup + \def\noexpand\@gls@actualshort{\glsxtrorgshort}% + \def\noexpand\@gls@actuallong{\glsxtrorglong}% + \def\noexpand\@gls@actualshortpl{\@gls@shortpl}% + \def\noexpand\@gls@actuallongpl{\@gls@longpl}% + }% + \@gls@tmp + } + } +% \end{macrocode} +%\end{macro} %\begin{macro}{\@gls@setup@default@short@access} %\changes{1.31}{2018-05-09}{new} +%\changes{1.42}{2020-02-03}{renamed to \cs{@gls@setup@default@access}} +%Renamed \cs{@gls@setup@default@access} and removed argument since +%it can be obtained from \cs{glsxtrorgshort}. +%\end{macro} +%\begin{macro}{\@gls@setup@default@access} +%\changes{1.42}{2020-02-03}{added \cs{glsdefaultshortaccess}} %Assign the default value of the \gloskey{shortaccess} key. The %argument is the short value passed to \cs{newabbreviation}. +%The \gloskey{shortaccess} value should explain the abbreviation. % \begin{macrocode} - \newcommand{\@gls@setup@default@short@access}[1]{% + \newcommand{\@gls@setup@default@access}{% + \@gls@assign@actual + \ifdefempty\@gls@shortaccess + {% % \end{macrocode} %Check if the \catattr{accessinsertdots} attribute has been set but %only if \gloskey{shortaccess} hasn't been set. % \begin{macrocode} - \ifdefempty\@gls@shortaccess - {% - \glsifcategoryattribute{\glscategorylabel}{accessinsertdots}{true}% + \@gls@ifaccessattribute@set{insertdots}% {% - \@glsxtr@insertdots\@gls@shortaccess{#1}% - \eappto\ExtraCustomAbbreviationFields{% - shortaccess={\expandonce\@gls@shortaccess},}% + \expandafter\@glsxtr@insertdots\expandafter\@gls@actualshort\expandafter + {\@gls@actualshort}% }% {}% - }% - {}% + \ifdefempty\@gls@longaccess + {% + \edef\@gls@shortaccess{\glsdefaultshortaccess + {\expandonce\@gls@actuallong}{\expandonce\@gls@actualshort}}% + }% + {% + \edef\@gls@shortaccess{\glsdefaultshortaccess + {\expandonce\@gls@longaccess}{\expandonce\@gls@actualshort}}% + }% + \eappto\ExtraCustomAbbreviationFields{shortaccess={\@gls@shortaccess},}% % \end{macrocode} -%If the \gloskey{shortaccess} field has been set but -%\gloskey{shortaccessplural} hasn't been set, assign plural form. +%If \gloskey{shortaccessplural} hasn't been set, assign plural form. % \begin{macrocode} - \ifdefempty\@gls@shortaccess - {}% - {% \ifdefempty\@gls@shortaccesspl {% \@gls@ifaccessattribute@set{aposplural}% {% \expandafter\def\expandafter\@gls@shortaccesspl\expandafter{% - \@gls@shortaccess'\abbrvpluralsuffix}% + \@gls@actualshort'\glsxtrabbrvpluralsuffix}% }% {% \@gls@ifaccessattribute@set{noshortplural}% @@ -12172,13 +12798,25 @@ defined}{}% \let\@gls@shortaccesspl\@gls@shortaccess }% {% - \expandafter\def\expandafter\@gls@shortaccesspl\expandafter{% - \@gls@shortaccess\abbrvpluralsuffix}% + \let\@gls@shortaccesspl\@gls@actualshortpl }% }% - \eappto\ExtraCustomAbbreviationFields{% - shortpluralaccess={\expandonce\@gls@shortaccesspl},}% + \ifdefempty\@gls@longaccesspl + {% + \edef\@gls@shortaccesspl{\glsdefaultshortaccess + {\expandonce\@gls@actuallongpl}{\expandonce\@gls@actualshortpl}}% }% + {% + \edef\@gls@shortaccesspl{\glsdefaultshortaccess + {\expandonce\@gls@longaccesspl}{\expandonce\@gls@actualshort}}% + }% + \eappto\ExtraCustomAbbreviationFields{shortpluralaccess={\@gls@shortaccesspl},}% + }% + {}% + }% + {% + \ifdefempty\@gls@shortaccesspl + {\let\@gls@shortaccesspl\@gls@shortaccess}% {}% }% % \end{macrocode} @@ -12189,16 +12827,7 @@ defined}{}% {% \glsifcategoryattribute{\glscategorylabel}{nameshortaccess}{true}% {% -% \end{macrocode} -%Do nothing if the \gloskey{shortaccess} key hasn't been set. -% \begin{macrocode} - \ifdefempty\@gls@shortaccess - {}% - {% - \eappto\ExtraCustomAbbreviationFields{% - access={\expandonce\@gls@shortaccess},% - }% - }% + \eappto\ExtraCustomAbbreviationFields{access={\@gls@shortaccess},}% }% {}% }% @@ -12211,15 +12840,17 @@ defined}{}% {% \glsifcategoryattribute{\glscategorylabel}{textshortaccess}{true}% {% -% \end{macrocode} -%Do nothing if the \gloskey{shortaccess} key hasn't been set. -% \begin{macrocode} - \ifdefempty\@gls@shortaccess - {}% - {% - \eappto\ExtraCustomAbbreviationFields{% - textaccess={\expandonce\@gls@shortaccess},% - }% + \eappto\ExtraCustomAbbreviationFields{textaccess={\@gls@shortaccess},}% + }% + {}% + }% + {}% + \ifdefempty\@gls@pluralaccess + {% + \glsifcategoryattribute{\glscategorylabel}{textshortaccess}{true}% + {% + \eappto\ExtraCustomAbbreviationFields{% + pluralaccess={\@gls@shortaccesspl},% }% }% {}% @@ -12233,15 +12864,17 @@ defined}{}% {% \glsifcategoryattribute{\glscategorylabel}{firstshortaccess}{true}% {% -% \end{macrocode} -%Do nothing if the \gloskey{shortaccess} key hasn't been set. -% \begin{macrocode} - \ifdefempty\@gls@shortaccess - {}% - {% - \eappto\ExtraCustomAbbreviationFields{% - firstaccess={\expandonce\@gls@shortaccess},% - }% + \eappto\ExtraCustomAbbreviationFields{firstaccess={\@gls@shortaccess},}% + }% + {}% + }% + {}% + \ifdefempty\@gls@firstpluralaccess + {% + \glsifcategoryattribute{\glscategorylabel}{firstshortaccess}{true}% + {% + \eappto\ExtraCustomAbbreviationFields{% + firstpluralaccess={\@gls@shortaccesspl},% }% }% {}% @@ -12250,6 +12883,100 @@ defined}{}% } % \end{macrocode} %\end{macro} +% +% Provide hooks for \cs{setabbreviationstyle} that automatically set +% the attributes appropriate for the style. +% If the name is just the short form and the +% description contains the long form, then it may not be necessary +% to set \catattr{nameshortaccess} but it would depend on the glossary style. +% +% Need to provide \cs{glsxtr\meta{category}\meta{field}accsupp} if +% not already defined. +%\begin{macro}{\glsxtrprovideaccsuppcmd} +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} + \newcommand*{\glsxtrprovideaccsuppcmd}[2]{% + \ifcsundef{glsxtr#1#2accsupp}% + {\csdef{glsxtr#1#2accsupp}{\glsshortaccsupp}}% + {}% + } +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\glsxtrAccSuppAbbrSetNoLongAttrs} +%\changes{1.42}{2020-02-03}{new} +%For styles where the name, first and text are just the +%abbreviation. +% \begin{macrocode} + \newcommand*{\glsxtrAccSuppAbbrSetNoLongAttrs}[1]{% + \glssetcategoryattribute{#1}{nameshortaccess}{true}% + \glssetcategoryattribute{#1}{firstshortaccess}{true}% + \glssetcategoryattribute{#1}{textshortaccess}{true}% + \glsxtrprovideaccsuppcmd{#1}{name}% + \glsxtrprovideaccsuppcmd{#1}{first}% + \glsxtrprovideaccsuppcmd{#1}{firstpl}% + \glsxtrprovideaccsuppcmd{#1}{text}% + \glsxtrprovideaccsuppcmd{#1}{plural}% + } +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glsxtrAccSuppAbbrSetFirstLongAttrs} +%\changes{1.42}{2020-02-03}{new} +%For styles where the name and text are just the +%abbreviation. The first form may just be long or may be short and +%long. +% \begin{macrocode} + \newcommand*{\glsxtrAccSuppAbbrSetFirstLongAttrs}[1]{% + \glssetcategoryattribute{#1}{nameshortaccess}{true}% + \glssetcategoryattribute{#1}{textshortaccess}{true}% + \glsxtrprovideaccsuppcmd{#1}{name}% + \glsxtrprovideaccsuppcmd{#1}{text}% + \glsxtrprovideaccsuppcmd{#1}{plural}% + } +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glsxtrAccSuppAbbrSetTextShortAttrs} +%\changes{1.42}{2020-02-03}{new} +%For styles where only the text is just the abbreviation. The name +%and first form may just be long or may be short and +%long. The name may also be short but followed by the long form in +%the description. +% \begin{macrocode} + \newcommand*{\glsxtrAccSuppAbbrSetTextShortAttrs}[1]{% + \glssetcategoryattribute{#1}{textshortaccess}{true}% + \glsxtrprovideaccsuppcmd{#1}{text}% + \glsxtrprovideaccsuppcmd{#1}{plural}% + } +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glsxtrAccSuppAbbrSetNameShortAttrs} +%\changes{1.42}{2020-02-03}{new} +%For styles where only the name is just the abbreviation. The +%first and subsequent form may just be long or may be short and +%long. +% \begin{macrocode} + \newcommand*{\glsxtrAccSuppAbbrSetNameShortAttrs}[1]{% + \glssetcategoryattribute{#1}{nameshortaccess}{true}% + \glsxtrprovideaccsuppcmd{#1}{name}% + } +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glsxtrAccSuppAbbrSetNameLongAttrs} +%\changes{1.42}{2020-02-03}{new} +%For styles where the first and text are just the +%abbreviation. The name may just be long or may be short and +%long or the name may be short. +% \begin{macrocode} + \newcommand*{\glsxtrAccSuppAbbrSetNameLongAttrs}[1]{% + \glssetcategoryattribute{#1}{firstshortaccess}{true}% + \glssetcategoryattribute{#1}{textshortaccess}{true}% + \glsxtrprovideaccsuppcmd{#1}{first}% + \glsxtrprovideaccsuppcmd{#1}{firstpl}% + \glsxtrprovideaccsuppcmd{#1}{text}% + \glsxtrprovideaccsuppcmd{#1}{plural}% + } +% \end{macrocode} +%\end{macro} % End of if accsupp part % \begin{macrocode} } @@ -12588,11 +13315,45 @@ defined}{}% % \end{macrocode} %\end{macro} % -%\begin{macro}{\@gls@setup@default@short@access} -%\changes{1.31}{2018-05-09}{new} +%\begin{macro}{\@gls@setup@default@access} +%This does nothing if there's no accessibility support. +% \begin{macrocode} + \newcommand{\@gls@setup@default@access}{} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glsxtrAccSuppAbbrSetNoLongAttrs} +%\changes{1.42}{2020-02-03}{new} +%This does nothing if there's no accessibility support. +% \begin{macrocode} + \newcommand*{\glsxtrAccSuppAbbrSetNoLongAttrs}[1]{} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glsxtrAccSuppAbbrSetFirstLongAttrs} +%\changes{1.42}{2020-02-03}{new} +%This does nothing if there's no accessibility support. +% \begin{macrocode} + \newcommand*{\glsxtrAccSuppAbbrSetFirstLongAttrs}[1]{} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glsxtrAccSuppAbbrSetTextShortAttrs} +%\changes{1.42}{2020-02-03}{new} +%This does nothing if there's no accessibility support. +% \begin{macrocode} + \newcommand*{\glsxtrAccSuppAbbrSetTextShortAttrs}[1]{} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glsxtrAccSuppAbbrSetNameShortAttrs} +%\changes{1.42}{2020-02-03}{new} +%This does nothing if there's no accessibility support. +% \begin{macrocode} + \newcommand*{\glsxtrAccSuppAbbrSetNameShortAttrs}[1]{} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glsxtrAccSuppAbbrSetNameLongAttrs} +%\changes{1.42}{2020-02-03}{new} %This does nothing if there's no accessibility support. % \begin{macrocode} - \newcommand{\@gls@setup@default@short@access}[1]{}% + \newcommand*{\glsxtrAccSuppAbbrSetNameLongAttrs}[1]{} % \end{macrocode} % End of else part % \begin{macrocode} @@ -13810,14 +14571,59 @@ defined}{}% %\end{macro} % %\begin{macro}{\glossentrysymbol} -% Redefine to set the abbreviation format and accessibility support. +% Redefine to set the format and accessibility support. Allow for +% the possibility of being used in a section heading for standalone +% entry definitions. %\changes{0.5.2}{2015-12-08}{added} % \begin{macrocode} -\renewcommand*{\glossentrysymbol}[1]{% +\ifdef\texorpdfstring +{ + \renewcommand*{\glossentrysymbol}[1]{% + \texorpdfstring{\@glossentrysymbol{#1}}{\glsentrypdfsymbol{#1}}% + } +} +{ + \renewcommand*{\glossentrysymbol}[1]{\@glossentrysymbol{#1}} +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\glsentrypdfsymbol} +%\changes{1.4.2}{??}{new} +%May be redefined to a field that expands to a value that's more +%suitable for PDF bookmarks. +% \begin{macrocode} +\newcommand{\glsentrypdfsymbol}[1]{\glsentrysymbol{#1}} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@glossentrysymbol} +%\changes{1.4.2}{??}{new} +%There are no case-changing attributes as it's less usual for +%symbols. +% \begin{macrocode} +\newrobustcmd*{\@glossentrysymbol}[1]{% \glsdoifexistsorwarn{#1}% {% - \glssetabbrvfmt{\glscategory{#1}}% - \glsaccesssymbol{#1}% + \begingroup + \glssetabbrvfmt{\glscategory{#1}}% + \glshasattribute{#1}{glosssymbolfont}% + {% + \edef\@glsxtr@attrval{\glsgetattribute{#1}{glosssymbolfont}}% + \ifcsdef{\@glsxtr@attrval}% + {% + \letcs{\@glsxtr@glosssymbolfont}{\@glsxtr@attrval}% + }% + {% + \GlossariesExtraWarning{Unknown control sequence name + `\@glsxtr@attrval' supplied in glosssymbolfont attribute + for entry `#1'. Ignoring}% + \let\@glsxtr@glosssymbolfont\@firstofone + }% + }% + {\let\@glsxtr@glosssymbolfont\@firstofone}% + \@glsxtr@glosssymbolfont{\glsaccesssymbol{#1}}% + \endgroup }% } % \end{macrocode} @@ -14384,21 +15190,11 @@ defined}{}% % commands for abbreviations that have a similar, but not identical, % underlying mechanism to acronyms. % -% If there's a style for the given category, apply it. +% If there's a style for the given category, it needs to be applied +% by \cs{newabbreviation}. % \begin{macrocode} \define@key{glsxtrabbrv}{category}{% \edef\glscategorylabel{#1}% - \ifcsdef{@glsabbrv@current@#1}% - {% -% \end{macrocode} -% Warning should already have been issued. -% \begin{macrocode} - \let\@glsxtr@orgwarndep\GlsXtrWarnDeprecatedAbbrStyle - \let\GlsXtrWarnDeprecatedAbbrStyle\@gobbletwo - \glsxtr@applyabbrvstyle{\csname @glsabbrv@current@#1\endcsname}% - \let\GlsXtrWarnDeprecatedAbbrStyle\@glsxtr@orgwarndep - }% - {}% } % \end{macrocode} % Save the short plural form. This may be needed before the entry is @@ -14547,14 +15343,35 @@ defined}{}% % \end{macrocode} % Get the category. %\changes{0.3}{2015-12-02}{fixed family name in \cs{setkeys}} +%\changes{1.42}{2020-02-03}{moved apply abbreviation style to after category +%key has been obtained} % \begin{macrocode} \def\glscategorylabel{abbreviation}% - \glsxtr@applyabbrvstyle{\@glsabbrv@current@abbreviation}% % \end{macrocode} % Ignore the shortplural and longplural keys. % \begin{macrocode} \setkeys*{glsxtrabbrv}[shortplural,longplural]{#1}% % \end{macrocode} +% Set the abbreviation style. +% \begin{macrocode} + \ifcsdef{@glsabbrv@current@\glscategorylabel}% + {% +% \end{macrocode} +% Warning should already have been issued. +% \begin{macrocode} + \let\@glsxtr@orgwarndep\GlsXtrWarnDeprecatedAbbrStyle + \let\GlsXtrWarnDeprecatedAbbrStyle\@gobbletwo + \glsxtr@applyabbrvstyle{\csname @glsabbrv@current@\glscategorylabel\endcsname}% + \let\GlsXtrWarnDeprecatedAbbrStyle\@glsxtr@orgwarndep + }% + {% +% \end{macrocode} +%If no style has been associated with this category, fallback on the style +%for the \category{abbreviation} category. +% \begin{macrocode} + \glsxtr@applyabbrvstyle{\@glsabbrv@current@abbreviation}% + }% +% \end{macrocode} % Set the default long plural % \begin{macrocode} \def\@gls@longpl{#4\glspluralsuffix}% @@ -14589,7 +15406,12 @@ defined}{}% \glsifcategoryattribute{\glscategorylabel}{insertdots}{true}% {% \@glsxtr@insertdots\@gls@short{#3}% - \expandafter\glsshorttok\expandafter{\@gls@short\spacefactor1000 \relax}% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{relax} and updated \cs{@gls@short} +%instead of \cs{glsshorttok}} +%\changes{1.42}{2020-02-03}{replaced explicit \cs{spacefactor} with \cs{@}} +% \begin{macrocode} + \appto\@gls@short{\@}% }% {\def\@gls@short{#3}}% }% @@ -14630,6 +15452,11 @@ defined}{}% % \begin{macrocode} \setkeys*{glsxtrabbrv}[category]{#1}% % \end{macrocode} +% Save in case required. +% \begin{macrocode} + \let\@gls@org@longpl\@gls@longpl + \let\@gls@org@shortpl\@gls@shortpl +% \end{macrocode} % Has the plural been explicitly set? % \begin{macrocode} \ifx\@gls@default@longpl\@gls@longpl @@ -14654,7 +15481,7 @@ defined}{}% % Hook for accessibility support (does nothing if % \sty{glossaries-accsupp} hasn't been loaded). % \begin{macrocode} - \@gls@setup@default@short@access{#3}% + \@gls@setup@default@access % \end{macrocode} % Do any extra setup provided by hook: % \begin{macrocode} @@ -14686,6 +15513,10 @@ defined}{}% }% }% \@do@newglossaryentry +% \end{macrocode} +% Obtain the type and add it to the list of abbreviations. +% \begin{macrocode} + \@glsxtr@addabbreviationlist{\glsentrytype{\the\glslabeltok}}% \GlsXtrPostNewAbbreviation } % \end{macrocode} @@ -14855,6 +15686,7 @@ defined}{}% % %\begin{macro}{\glsabbrvfont} % Font changing command used for the abbreviation on subsequent use. +% This is redefined by the abbreviation styles, as appropriate. % \begin{macrocode} \newcommand*{\glsabbrvfont}[1]{\glsabbrvdefaultfont{#1}} % \end{macrocode} @@ -15881,6 +16713,7 @@ defined}{}% % Set up the style for the given category. % \begin{macrocode} \csdef{@glsabbrv@current@#1}{#2}% + \edef\glscategorylabel{#1}% \glsxtr@applyabbrvstyle{#2}% }% }% @@ -16086,6 +16919,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{long-short}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetFirstLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongshortname}, sort={\the\glsshorttok}, @@ -16097,8 +16937,10 @@ defined}{}% \glsxtrparen{\protect\glsfirstabbrvfont{\the\glsshortpltok}}},% % \end{macrocode} %\changes{1.15}{2017-05-10}{fixed spelling of \cs{glsabbrvfont}} +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} plural={\protect\glsabbrvfont{\the\glsshortpltok}},% + text={\protect\glsabbrvfont{\the\glsshorttok}},% description={\the\glslongtok}}% % \end{macrocode} %\changes{0.5.1}{2015-12-07}{switch off regular attribute if set} @@ -16181,6 +17023,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{long-short-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetTextShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongshortdescname}, sort={\glsxtrlongshortdescsort},% @@ -16232,6 +17081,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{short-long}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetFirstLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortlongname}, sort={\the\glsshorttok}, @@ -16244,7 +17100,9 @@ defined}{}% \glsxtrparen{\protect\glsfirstlongfont{\the\glslongpltok}}},% % \end{macrocode} %\changes{1.15}{2017-05-10}{fixed spelling of \cs{glsabbrvfont}} +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} + text={\protect\glsabbrvfont{\the\glsshorttok}},% plural={\protect\glsabbrvfont{\the\glsshortpltok}}}% % \end{macrocode} %\changes{0.5.1}{2015-12-07}{switch off regular attribute if set} @@ -16321,6 +17179,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{short-long-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetTextShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortlongdescname}, sort={\glsxtrshortlongdescsort}, @@ -16403,6 +17268,15 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{footnote}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. (Add +% \catattr{firstshortaccess} since long form is hidden in a +% footnote on first use.) +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNoLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrfootnotename}, sort={\the\glsshorttok}, @@ -16419,7 +17293,9 @@ defined}{}% {\protect\glsfirstlongfootnotefont{\the\glslongpltok}}},% % \end{macrocode} %\changes{1.15}{2017-05-10}{fixed spelling of \cs{glsabbrvfont}} +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} + text={\protect\glsabbrvfont{\the\glsshorttok}},% plural={\protect\glsabbrvfont{\the\glsshortpltok}}}% % \end{macrocode} % Switch off hyperlinks on first use to prevent nested hyperlinks, @@ -16507,8 +17383,77 @@ defined}{}% % \end{macrocode} %\end{abbrvstyle} % +%\begin{macro}{\glsxtrfootnotedescname} +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newcommand*{\glsxtrfootnotedescname}{% + \protect\glsabbrvfont{\the\glsshorttok}% + \protect\glsxtrfullsep{\the\glslabeltok}% + \protect\glsxtrparen{\protect\glslongfont{\the\glslongtok}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\glsxtrfootnotedescsort} +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newcommand*{\glsxtrfootnotedescsort}{\the\glsshorttok} +% \end{macrocode} +%\end{macro} +% +%\begin{abbrvstyle}{short-footnote-desc} +% Like \abbrstyle{short-footnote} but with user supplied description. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newabbreviationstyle{short-footnote-desc}% +{% +% \end{macrocode} +% Set accessibility attributes if enabled +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNameLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} + \renewcommand*{\CustomAbbreviationFields}{% + name={\glsxtrfootnotedescname}, + sort={\glsxtrfootnotedescsort}, + first={\protect\glsfirstabbrvfont{\the\glsshorttok}% + \protect\glsxtrabbrvfootnote{\the\glslabeltok}% + {\protect\glsfirstlongfootnotefont{\the\glslongtok}}},% + firstplural={\protect\glsfirstabbrvfont{\the\glsshortpltok}% + \protect\glsxtrabbrvfootnote{\the\glslabeltok}% + {\protect\glsfirstlongfootnotefont{\the\glslongpltok}}},% + text={\protect\glsabbrvfont{\the\glsshorttok}},% + plural={\protect\glsabbrvfont{\the\glsshortpltok}}}% +% \end{macrocode} +% Switch off hyperlinks on first use to prevent nested hyperlinks, +% and unset the \catattr{regular} attribute if it has been set. +% \begin{macrocode} + \renewcommand*{\GlsXtrPostNewAbbreviation}{% + \glssetattribute{\the\glslabeltok}{nohyperfirst}{true}% + \glshasattribute{\the\glslabeltok}{regular}% + {% + \glssetattribute{\the\glslabeltok}{regular}{false}% + }% + {}% + }% +}% +{% + \GlsXtrUseAbbrStyleFmts{footnote}% +} +% \end{macrocode} +%\end{abbrvstyle} +% +%\begin{abbrvstyle}{footnote-desc} +%\changes{1.42}{2020-02-03}{new} +%Synonym. +% \begin{macrocode} +\letabbreviationstyle{footnote-desc}{short-footnote-desc} +% \end{macrocode} +%\end{abbrvstyle} +% %\begin{abbrvstyle}{postfootnote} -% Similar to the above but the footnote is placed afterwards, +% Similar to \abbrstyle{footnote} but the footnote is placed afterwards, % outside the link. This avoids nested links and can also move the % footnote marker after any following punctuation mark. % Pre v1.07 included \cs{footnote} in the first keys, which was @@ -16517,6 +17462,15 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{postfootnote}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. (Add +% \catattr{firstshortaccess} since long form is hidden in a +% footnote on first use.) +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNoLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrfootnotename}, sort={\the\glsshorttok}, @@ -16525,7 +17479,9 @@ defined}{}% firstplural={\protect\glsfirstabbrvfont{\the\glsshortpltok}},% % \end{macrocode} %\changes{1.15}{2017-05-10}{fixed spelling of \cs{glsabbrvfont}} +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} + text={\protect\glsabbrvfont{\the\glsshorttok}},% plural={\protect\glsabbrvfont{\the\glsshortpltok}}}% % \end{macrocode} % Make this category insert a footnote after the link if this was @@ -16628,6 +17584,77 @@ defined}{}% % \end{macrocode} %\end{abbrvstyle} % +%\begin{abbrvstyle}{short-postfootnote-desc} +%\changes{1.42}{2020-02-03}{new} +% Like \abbrstyle{short-postfootnote} but with user supplied description. +% \begin{macrocode} +\newabbreviationstyle{short-postfootnote-desc}% +{% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNameLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} + \renewcommand*{\CustomAbbreviationFields}{% + name={\glsxtrfootnotedescname}, + sort={\glsxtrfootnotedescsort}, + first={\protect\glsfirstabbrvfont{\the\glsshorttok}},% + firstplural={\protect\glsfirstabbrvfont{\the\glsshortpltok}},% +% \end{macrocode} +%\changes{1.15}{2017-05-10}{fixed spelling of \cs{glsabbrvfont}} +%\changes{1.42}{2020-02-03}{added missing text key} +% \begin{macrocode} + text={\protect\glsabbrvfont{\the\glsshorttok}},% + plural={\protect\glsabbrvfont{\the\glsshortpltok}}}% +% \end{macrocode} +% Make this category insert a footnote after the link if this was +% the first use, and +% unset the \catattr{regular} attribute if it has been set. +%\changes{0.5.1}{2015-12-07}{switch off regular attribute if set} +% \begin{macrocode} + \renewcommand*{\GlsXtrPostNewAbbreviation}{% + \csdef{glsxtrpostlink\glscategorylabel}{% + \glsxtrifwasfirstuse + {% +% \end{macrocode} +% Needs the specific font command here as the style may have been +% lost by the time the footnote occurs. +% \begin{macrocode} + \glsxtrdopostpunc{\protect\glsxtrabbrvfootnote{\glslabel}% + {\glsfirstlongfootnotefont{\glsentrylong{\glslabel}}}}% + }% + {}% + }% + \glshasattribute{\the\glslabeltok}{regular}% + {% + \glssetattribute{\the\glslabeltok}{regular}{false}% + }% + {}% + }% +% \end{macrocode} +%\changes{1.02}{2016-04-25}{added redef of \cs{glsxtrsetupfulldefs}} +% The footnote needs to be suppressed in the inline form, so +% \cs{glsxtrfull} must set the first use switch off. +% \begin{macrocode} + \renewcommand*{\glsxtrsetupfulldefs}{% + \let\glsxtrifwasfirstuse\@secondoftwo + }% +}% +{% + \GlsXtrUseAbbrStyleFmts{postfootnote}% +} +% \end{macrocode} +%\end{abbrvstyle} +% +%\begin{abbrvstyle}{postfootnote-desc} +%\changes{1.42}{?}{new} +% \begin{macrocode} +\letabbreviationstyle{postfootnote-desc}{short-postfootnote-desc} +% \end{macrocode} +%\end{abbrvstyle} +% %\begin{macro}{\glsxtrshortnolongname} %\changes{1.25}{2017-11-24}{new} % \begin{macrocode} @@ -16647,6 +17674,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{short}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNoLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortnolongname}, sort={\the\glsshorttok}, @@ -16781,6 +17815,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{short-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNoLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortdescname}, sort={\the\glsshorttok}, @@ -16960,7 +18001,7 @@ defined}{}% % but the long and short form can be displayed with the \qt{full} % commands that use the inline format. The predefined glossary styles % won't show the short form. The user must supply a description for -% this style. +% this style. The accessibility attributes don't need setting here. % \begin{macrocode} \newabbreviationstyle{long-desc}% {% @@ -17102,6 +18143,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{long}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNameShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongnoshortname}, sort={\the\glsshorttok}, @@ -17185,15 +18233,26 @@ defined}{}% % and for the default short form suffix: %\begin{macro}{\glsxtrscsuffix} %\changes{0.5}{2015-12-07}{new} +%\changes{1.42}{2020-02-03}{added \cs{protect}} +%\cs{protect} needs to come inside \cs{\glsxtrscsuffix} to avoid +%interfering with all caps. % \begin{macrocode} -\newcommand*{\glsxtrscsuffix}{\glstextup{\glsxtrabbrvpluralsuffix}} +\newcommand*{\glsxtrscsuffix}{\protect\glstextup{\glsxtrabbrvpluralsuffix}} % \end{macrocode} %\end{macro} % %\begin{abbrvstyle}{long-short-sc} +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} \newabbreviationstyle{long-short-sc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetFirstLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongshortname}, sort={\the\glsshorttok}, @@ -17203,6 +18262,7 @@ defined}{}% firstplural={\protect\glsfirstlongdefaultfont{\the\glslongpltok}% \protect\glsxtrfullsep{\the\glslabeltok}% \glsxtrparen{\protect\glsfirstabbrvscfont{\the\glsshortpltok}}},% + text={\protect\glsabbrvscfont{\the\glsshorttok}},% plural={\protect\glsabbrvscfont{\the\glsshortpltok}},% description={\the\glslongtok}}% \renewcommand*{\GlsXtrPostNewAbbreviation}{% @@ -17216,8 +18276,9 @@ defined}{}% {% % \end{macrocode} % Use smallcaps and adjust the plural suffix to revert to upright. +%\changes{1.42}{2020-02-03}{moved \cs{protect} inside \cs{glsxtrscsuffix}} % \begin{macrocode} - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrscsuffix}% + \renewcommand*{\abbrvpluralsuffix}{\glsxtrscsuffix}% \renewcommand*\glsabbrvfont[1]{\glsabbrvscfont{##1}}% \renewcommand*\glsfirstabbrvfont[1]{\glsfirstabbrvscfont{##1}}% % \end{macrocode} @@ -17252,11 +18313,19 @@ defined}{}% }% } % \end{macrocode} +%\end{abbrvstyle} % %\begin{abbrvstyle}{long-short-sc-desc} % \begin{macrocode} \newabbreviationstyle{long-short-sc-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetTextShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongshortdescname}, sort={\glsxtrlongshortdescsort},% @@ -17288,11 +18357,21 @@ defined}{}% \GlsXtrUseAbbrStyleFmts{long-short-sc}% } % \end{macrocode} +%\end{abbrvstyle} % +%\begin{abbrvstyle}{short-sc-long} % Now the short (long) version +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} \newabbreviationstyle{short-sc-long}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetFirstLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortlongname}, sort={\the\glsshorttok}, @@ -17303,6 +18382,7 @@ defined}{}% firstplural={\protect\glsfirstabbrvscfont{\the\glsshortpltok}% \protect\glsxtrfullsep{\the\glslabeltok}% \glsxtrparen{\protect\glsfirstlongdefaultfont{\the\glslongpltok}}},% + text={\protect\glsabbrvscfont{\the\glsshorttok}},% plural={\protect\glsabbrvscfont{\the\glsshortpltok}}}% % \end{macrocode} % Unset the \catattr{regular} attribute if it has been set. @@ -17318,8 +18398,9 @@ defined}{}% {% % \end{macrocode} % Use smallcaps and adjust the plural suffix to revert to upright. +%\changes{1.42}{2020-02-03}{moved \cs{protect} inside \cs{glsxtrscsuffix}} % \begin{macrocode} - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrscsuffix}% + \renewcommand*{\abbrvpluralsuffix}{\glsxtrscsuffix}% \renewcommand*\glsabbrvfont[1]{\glsabbrvscfont{##1}}% \renewcommand*\glsfirstabbrvfont[1]{\glsfirstabbrvscfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongdefaultfont{##1}}% @@ -17354,10 +18435,18 @@ defined}{}% % \end{macrocode} %\end{abbrvstyle} % +%\begin{abbrvstyle}{short-sc-long-desc} % As before but user provides description % \begin{macrocode} \newabbreviationstyle{short-sc-long-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetTextShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortlongdescname}, sort={\glsxtrshortlongdescsort}, @@ -17394,6 +18483,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{short-sc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNoLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortnolongname}, sort={\the\glsshorttok}, @@ -17408,8 +18504,9 @@ defined}{}% {% % \end{macrocode} % Use smallcaps and adjust the plural suffix to revert to upright. +%\changes{1.42}{2020-02-03}{moved \cs{protect} inside \cs{glsxtrscsuffix}} % \begin{macrocode} - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrscsuffix}% + \renewcommand*{\abbrvpluralsuffix}{\glsxtrscsuffix}% \renewcommand*\glsabbrvfont[1]{\glsabbrvscfont{##1}}% \renewcommand*\glsfirstabbrvfont[1]{\glsfirstabbrvscfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongdefaultfont{##1}}% @@ -17482,6 +18579,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{short-sc-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNameLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortdescname}, sort={\the\glsshorttok}, @@ -17495,8 +18599,9 @@ defined}{}% {% % \end{macrocode} % Use smallcaps and adjust the plural suffix to revert to upright. +%\changes{1.42}{2020-02-03}{moved \cs{protect} inside \cs{glsxtrscsuffix}} % \begin{macrocode} - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrscsuffix}% + \renewcommand*{\abbrvpluralsuffix}{\glsxtrscsuffix}% \renewcommand*\glsabbrvfont[1]{\glsabbrvscfont{##1}}% \renewcommand*\glsfirstabbrvfont[1]{\glsfirstabbrvscfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongdefaultfont{##1}}% @@ -17600,7 +18705,7 @@ defined}{}% %\changes{1.04}{2016-05-02}{renamed from \qt{long-sc}} % The smallcaps font will only be used if % the short form is explicitly invoked through commands like -% \cs{glsxtrshort}. +% \cs{glsxtrshort}. No accessibility attributes needed here. % \begin{macrocode} \newabbreviationstyle{long-noshort-sc}% {% @@ -17619,8 +18724,9 @@ defined}{}% {% % \end{macrocode} % Use smallcaps and adjust the plural suffix to revert to upright. +%\changes{1.42}{2020-02-03}{moved \cs{protect} inside \cs{glsxtrscsuffix}} % \begin{macrocode} - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrscsuffix}% + \renewcommand*{\abbrvpluralsuffix}{\glsxtrscsuffix}% \renewcommand*\glsabbrvfont[1]{\glsabbrvscfont{##1}}% \renewcommand*\glsfirstabbrvfont[1]{\glsfirstabbrvscfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongdefaultfont{##1}}% @@ -17712,8 +18818,9 @@ defined}{}% {% % \end{macrocode} % Use smallcaps and adjust the plural suffix to revert to upright. +%\changes{1.42}{2020-02-03}{moved \cs{protect} inside \cs{glsxtrscsuffix}} % \begin{macrocode} - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrscsuffix}% + \renewcommand*{\abbrvpluralsuffix}{\glsxtrscsuffix}% \renewcommand*\glsabbrvfont[1]{\glsabbrvscfont{##1}}% \renewcommand*\glsfirstabbrvfont[1]{\glsfirstabbrvscfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongdefaultfont{##1}}% @@ -17795,9 +18902,17 @@ defined}{}% %\begin{abbrvstyle}{short-sc-footnote} %\changes{0.5}{2015-12-07}{new} %\changes{1.04}{2016-05-02}{renamed from \qt{footnote-sc}} +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} \newabbreviationstyle{short-sc-footnote}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNoLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrfootnotename}, sort={\the\glsshorttok}, @@ -17808,6 +18923,7 @@ defined}{}% firstplural={\protect\glsfirstabbrvscfont{\the\glsshortpltok}% \protect\glsxtrabbrvfootnote{\the\glslabeltok}% {\protect\glsfirstlongfootnotefont{\the\glslongpltok}}},% + text={\protect\glsabbrvscfont{\the\glsshorttok}},% plural={\protect\glsabbrvscfont{\the\glsshortpltok}}}% % \end{macrocode} % Switch off hyperlinks on first use to prevent nested hyperlinks, @@ -17826,8 +18942,9 @@ defined}{}% {% % \end{macrocode} % Use smallcaps and adjust the plural suffix to revert to upright. +%\changes{1.42}{2020-02-03}{moved \cs{protect} inside \cs{glsxtrscsuffix}} % \begin{macrocode} - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrscsuffix}% + \renewcommand*{\abbrvpluralsuffix}{\glsxtrscsuffix}% \renewcommand*\glsabbrvfont[1]{\glsabbrvscfont{##1}}% \renewcommand*\glsfirstabbrvfont[1]{\glsfirstabbrvscfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongfootnotefont{##1}}% @@ -17894,18 +19011,71 @@ defined}{}% % \end{macrocode} %\end{abbrvstyle} % +%\begin{abbrvstyle}{short-sc-footnote-desc} +% Like \abbrstyle{short-sc-footnote} but with user supplied description. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newabbreviationstyle{short-sc-footnote-desc}% +{% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNameLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} + \renewcommand*{\CustomAbbreviationFields}{% + name={\glsxtrfootnotedescname}, + sort={\glsxtrfootnotedescsort}, + first={\protect\glsfirstabbrvscfont{\the\glsshorttok}% + \protect\glsxtrabbrvfootnote{\the\glslabeltok}% + {\protect\glsfirstlongfootnotefont{\the\glslongtok}}},% + firstplural={\protect\glsfirstabbrvscfont{\the\glsshortpltok}% + \protect\glsxtrabbrvfootnote{\the\glslabeltok}% + {\protect\glsfirstlongfootnotefont{\the\glslongpltok}}},% + text={\protect\glsabbrvscfont{\the\glsshorttok}},% + plural={\protect\glsabbrvscfont{\the\glsshortpltok}}}% +% \end{macrocode} +% Switch off hyperlinks on first use to prevent nested hyperlinks, +% and unset the \catattr{regular} attribute if it has been set. +%\changes{0.5.1}{2015-12-07}{switch off regular attribute if set} +% \begin{macrocode} + \renewcommand*{\GlsXtrPostNewAbbreviation}{% + \glssetattribute{\the\glslabeltok}{nohyperfirst}{true}% + \glshasattribute{\the\glslabeltok}{regular}% + {% + \glssetattribute{\the\glslabeltok}{regular}{false}% + }% + {}% + }% +}% +{% + \GlsXtrUseAbbrStyleFmts{short-sc-footnote}% +} +% \end{macrocode} +%\end{abbrvstyle} +% %\begin{abbrvstyle}{short-sc-postfootnote} %\changes{0.5}{2015-12-07}{new} %\changes{1.04}{2016-05-02}{renamed from \qt{postfootnote-sc}} +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} \newabbreviationstyle{short-sc-postfootnote}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNoLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrfootnotename}, sort={\the\glsshorttok}, description={\the\glslongtok},% first={\protect\glsfirstabbrvscfont{\the\glsshorttok}},% firstplural={\protect\glsfirstabbrvscfont{\the\glsshortpltok}},% + text={\protect\glsabbrvscfont{\the\glsshorttok}},% plural={\protect\glsabbrvscfont{\the\glsshortpltok}}}% % \end{macrocode} % Make this category insert a footnote after the link if this was @@ -17942,8 +19112,9 @@ defined}{}% {% % \end{macrocode} % Use smallcaps and adjust the plural suffix to revert to upright. +%\changes{1.42}{2020-02-03}{moved \cs{protect} inside \cs{glsxtrscsuffix}} % \begin{macrocode} - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrscsuffix}% + \renewcommand*{\abbrvpluralsuffix}{\glsxtrscsuffix}% \renewcommand*\glsabbrvfont[1]{\glsabbrvscfont{##1}}% \renewcommand*\glsfirstabbrvfont[1]{\glsfirstabbrvscfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongfootnotefont{##1}}% @@ -18002,35 +19173,93 @@ defined}{}% % \end{macrocode} %\end{abbrvstyle} % -%\subsection{Predefined Styles (Fake Small Capitals)} -% These styles require the \sty{relsize} package, which must be -% loaded by the user. These styles all use: -%\begin{macro}{\glsxtrsmfont} -%\changes{0.5}{2015-12-07}{new} -%Maintained for backward compatibility. +%\begin{abbrvstyle}{short-sc-postfootnote-desc} +% Like \abbrstyle{short-sc-footnote} but with user supplied description. +%\changes{1.42}{2020-02-03}{new} % \begin{macrocode} -\newcommand*{\glsxtrsmfont}[1]{\textsmaller{#1}} +\newabbreviationstyle{short-sc-postfootnote-desc}% +{% % \end{macrocode} -%\end{macro} -%\begin{macro}{\glsabbrvsmfont} -%\changes{1.17}{2017-08-09}{new} -%Added for consistent naming. +% Set accessibility attributes if enabled. % \begin{macrocode} -\newcommand*{\glsabbrvsmfont}{\glsxtrsmfont} + \glsxtrAccSuppAbbrSetNameLongAttrs\glscategorylabel % \end{macrocode} -%\end{macro} -%\begin{macro}{\glsxtrfirstsmfont} -%\changes{1.04}{2016-05-02}{new} -%Maintained for backward compatibility. +% Setup the default fields. % \begin{macrocode} -\newcommand*{\glsxtrfirstsmfont}[1]{\glsabbrvsmfont{#1}} + \renewcommand*{\CustomAbbreviationFields}{% + name={\glsxtrfootnotedescname}, + sort={\glsxtrfootnotedescsort}, + first={\protect\glsfirstabbrvscfont{\the\glsshorttok}},% + firstplural={\protect\glsfirstabbrvscfont{\the\glsshortpltok}},% + text={\protect\glsabbrvscfont{\the\glsshorttok}},% + plural={\protect\glsabbrvscfont{\the\glsshortpltok}}}% % \end{macrocode} -%\end{macro} -%\begin{macro}{\glsfirstabbrvsmfont} -%\changes{1.17}{2017-08-09}{new} -%Added for consistent naming. +% Make this category insert a footnote after the link if this was +% the first use, and +% unset the \catattr{regular} attribute if it has been set. % \begin{macrocode} -\newcommand*{\glsfirstabbrvsmfont}{\glsxtrfirstsmfont} + \renewcommand*{\GlsXtrPostNewAbbreviation}{% + \csdef{glsxtrpostlink\glscategorylabel}{% + \glsxtrifwasfirstuse + {% +% \end{macrocode} +% Needs the specific font command here as the style may have been +% lost by the time the footnote occurs. +% \begin{macrocode} + \glsxtrdopostpunc{\protect\glsxtrabbrvfootnote{\glslabel}% + {\glsfirstlongfootnotefont{\glsentrylong{\glslabel}}}}% + }% + {}% + }% + \glshasattribute{\the\glslabeltok}{regular}% + {% + \glssetattribute{\the\glslabeltok}{regular}{false}% + }% + {}% + }% +% \end{macrocode} +% The footnote needs to be suppressed in the inline form, so +% \cs{glsxtrfull} must set the first use switch off. +% \begin{macrocode} + \renewcommand*{\glsxtrsetupfulldefs}{% + \let\glsxtrifwasfirstuse\@secondoftwo + }% +}% +{% + \GlsXtrUseAbbrStyleFmts{short-sc-postfootnote}% +} +% \end{macrocode} +%\end{abbrvstyle} +% +%\subsection{Predefined Styles (Fake Small Capitals)} +% These styles require the \sty{relsize} package, which must be +% loaded by the user. These styles all use: +%\begin{macro}{\glsxtrsmfont} +%\changes{0.5}{2015-12-07}{new} +%Maintained for backward compatibility. +% \begin{macrocode} +\newcommand*{\glsxtrsmfont}[1]{\textsmaller{#1}} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glsabbrvsmfont} +%\changes{1.17}{2017-08-09}{new} +%Added for consistent naming. +% \begin{macrocode} +\newcommand*{\glsabbrvsmfont}{\glsxtrsmfont} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glsxtrfirstsmfont} +%\changes{1.04}{2016-05-02}{new} +%Maintained for backward compatibility. +% \begin{macrocode} +\newcommand*{\glsxtrfirstsmfont}[1]{\glsabbrvsmfont{#1}} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glsfirstabbrvsmfont} +%\changes{1.17}{2017-08-09}{new} +%Added for consistent naming. +% \begin{macrocode} +\newcommand*{\glsfirstabbrvsmfont}{\glsxtrfirstsmfont} % \end{macrocode} %\end{macro} % and for the default short form suffix: @@ -18043,9 +19272,17 @@ defined}{}% % %\begin{abbrvstyle}{long-short-sm} %\changes{0.5}{2015-12-07}{new} +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} \newabbreviationstyle{long-short-sm}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetFirstLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongshortname}, sort={\the\glsshorttok}, @@ -18055,6 +19292,7 @@ defined}{}% firstplural={\protect\glsfirstlongdefaultfont{\the\glslongpltok}% \protect\glsxtrfullsep{\the\glslabeltok}% \glsxtrparen{\protect\glsfirstabbrvsmfont{\the\glsshortpltok}}},% + text={\protect\glsabbrvsmfont{\the\glsshorttok}},% plural={\protect\glsabbrvsmfont{\the\glsshortpltok}},% description={\the\glslongtok}}% \renewcommand*{\GlsXtrPostNewAbbreviation}{% @@ -18066,9 +19304,12 @@ defined}{}% }% }% {% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtrsmsuffix}} +% \begin{macrocode} \renewcommand*\glsabbrvfont[1]{\glsabbrvsmfont{##1}}% \renewcommand*\glsfirstabbrvfont[1]{\glsfirstabbrvsmfont{##1}}% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrsmsuffix}% + \renewcommand*{\abbrvpluralsuffix}{\glsxtrsmsuffix}% % \end{macrocode} % Use the default long fonts. % \begin{macrocode} @@ -18108,6 +19349,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{long-short-sm-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetTextShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongshortdescname}, sort={\glsxtrlongshortdescsort},% @@ -18143,9 +19391,17 @@ defined}{}% %\begin{abbrvstyle}{short-sm-long} % Now the short (long) version %\changes{0.5}{2015-12-07}{new} +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} \newabbreviationstyle{short-sm-long}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetFirstLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortlongname}, sort={\the\glsshorttok}, @@ -18156,6 +19412,7 @@ defined}{}% firstplural={\protect\glsfirstabbrvsmfont{\the\glsshortpltok}% \protect\glsxtrfullsep{\the\glslabeltok}% \glsxtrparen{\protect\glsfirstlongdefaultfont{\the\glslongpltok}}},% + text={\protect\glsabbrvsmfont{\the\glsshorttok}},% plural={\protect\glsabbrvsmfont{\the\glsshortpltok}}}% % \end{macrocode} % Unset the \catattr{regular} attribute if it has been set. @@ -18169,9 +19426,12 @@ defined}{}% }% }% {% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtrsmsuffix}} +% \begin{macrocode} \renewcommand*\glsabbrvfont[1]{\glsabbrvsmfont{##1}}% \renewcommand*\glsfirstabbrvfont[1]{\glsfirstabbrvsmfont{##1}}% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrsmsuffix}% + \renewcommand*{\abbrvpluralsuffix}{\glsxtrsmsuffix}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongdefaultfont{##1}}% \renewcommand*{\glslongfont}[1]{\glslongdefaultfont{##1}}% % \end{macrocode} @@ -18210,6 +19470,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{short-sm-long-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetTextShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortlongdescname}, sort={\glsxtrshortlongdescsort}, @@ -18247,6 +19514,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{short-sm}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNameLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortnolongname}, sort={\the\glsshorttok}, @@ -18259,9 +19533,12 @@ defined}{}% \glssetattribute{\the\glslabeltok}{regular}{true}}% }% {% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtrsmsuffix}} +% \begin{macrocode} \renewcommand*\glsabbrvfont[1]{\glsabbrvsmfont{##1}}% \renewcommand*\glsfirstabbrvfont[1]{\glsfirstabbrvsmfont{##1}}% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrsmsuffix}% + \renewcommand*{\abbrvpluralsuffix}{\glsxtrsmsuffix}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongdefaultfont{##1}}% \renewcommand*{\glslongfont}[1]{\glslongdefaultfont{##1}}% % \end{macrocode} @@ -18333,6 +19610,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{short-sm-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNoLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortdescname}, sort={\the\glsshorttok}, @@ -18344,9 +19628,12 @@ defined}{}% \glssetattribute{\the\glslabeltok}{regular}{true}}% }% {% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtrsmsuffix}} +% \begin{macrocode} \renewcommand*\glsabbrvfont[1]{\glsabbrvsmfont{##1}}% \renewcommand*\glsfirstabbrvfont[1]{\glsfirstabbrvsmfont{##1}}% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrsmsuffix}% + \renewcommand*{\abbrvpluralsuffix}{\glsxtrsmsuffix}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongdefaultfont{##1}}% \renewcommand*{\glslongfont}[1]{\glslongdefaultfont{##1}}% % \end{macrocode} @@ -18453,6 +19740,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{long-noshort-sm}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNameShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongnoshortname}, sort={\the\glsshorttok}, @@ -18466,9 +19760,12 @@ defined}{}% \glssetattribute{\the\glslabeltok}{regular}{true}}% }% {% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtrsmsuffix}} +% \begin{macrocode} \renewcommand*\glsabbrvfont[1]{\glsabbrvsmfont{##1}}% \renewcommand*\glsfirstabbrvfont[1]{\glsfirstabbrvsmfont{##1}}% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrsmsuffix}% + \renewcommand*{\abbrvpluralsuffix}{\glsxtrsmsuffix}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongdefaultfont{##1}}% \renewcommand*{\glslongfont}[1]{\glslongdefaultfont{##1}}% % \end{macrocode} @@ -18557,9 +19854,12 @@ defined}{}% \GlsXtrUseAbbrStyleSetup{long-noshort-desc}% }% {% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtrsmsuffix}} +% \begin{macrocode} \renewcommand*\glsabbrvfont[1]{\glsabbrvsmfont{##1}}% \renewcommand*\glsfirstabbrvfont[1]{\glsfirstabbrvsmfont{##1}}% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrsmsuffix}% + \renewcommand*{\abbrvpluralsuffix}{\glsxtrsmsuffix}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongdefaultfont{##1}}% \renewcommand*{\glslongfont}[1]{\glslongdefaultfont{##1}}% % \end{macrocode} @@ -18639,9 +19939,17 @@ defined}{}% %\begin{abbrvstyle}{short-sm-footnote} %\changes{0.5}{2015-12-07}{new} %\changes{1.04}{2016-05-02}{renamed from \qt{footnote-sm}} +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} \newabbreviationstyle{short-sm-footnote}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNoLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrfootnotename}, sort={\the\glsshorttok}, @@ -18652,6 +19960,7 @@ defined}{}% firstplural={\protect\glsfirstabbrvsmfont{\the\glsshortpltok}% \protect\glsxtrabbrvfootnote{\the\glslabeltok}% {\protect\glsfirstlongfootnotefont{\the\glslongpltok}}},% + text={\protect\glsabbrvsmfont{\the\glsshorttok}},% plural={\protect\glsabbrvsmfont{\the\glsshortpltok}}}% % \end{macrocode} % Switch off hyperlinks on first use to prevent nested hyperlinks, @@ -18668,9 +19977,12 @@ defined}{}% }% }% {% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtrsmsuffix}} +% \begin{macrocode} \renewcommand*\glsabbrvfont[1]{\glsabbrvsmfont{##1}}% \renewcommand*\glsfirstabbrvfont[1]{\glsfirstabbrvsmfont{##1}}% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrsmsuffix}% + \renewcommand*{\abbrvpluralsuffix}{\glsxtrsmsuffix}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongfootnotefont{##1}}% \renewcommand*{\glslongfont}[1]{\glslongfootnotefont{##1}}% % \end{macrocode} @@ -18735,18 +20047,71 @@ defined}{}% % \end{macrocode} %\end{abbrvstyle} % +%\begin{abbrvstyle}{short-sm-footnote-desc} +% Like \abbrstyle{short-footnote} but with user supplied description. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newabbreviationstyle{short-sm-footnote-desc}% +{% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNameLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} + \renewcommand*{\CustomAbbreviationFields}{% + name={\glsxtrfootnotedescname}, + sort={\glsxtrfootnotedescsort}, + first={\protect\glsfirstabbrvsmfont{\the\glsshorttok}% + \protect\glsxtrabbrvfootnote{\the\glslabeltok}% + {\protect\glsfirstlongfootnotefont{\the\glslongtok}}},% + firstplural={\protect\glsfirstabbrvsmfont{\the\glsshortpltok}% + \protect\glsxtrabbrvfootnote{\the\glslabeltok}% + {\protect\glsfirstlongfootnotefont{\the\glslongpltok}}},% + text={\protect\glsabbrvsmfont{\the\glsshorttok}},% + plural={\protect\glsabbrvsmfont{\the\glsshortpltok}}}% +% \end{macrocode} +% Switch off hyperlinks on first use to prevent nested hyperlinks, +% and unset the \catattr{regular} attribute if it has been set. +%\changes{0.5.1}{2015-12-07}{switch off regular attribute if set} +% \begin{macrocode} + \renewcommand*{\GlsXtrPostNewAbbreviation}{% + \glssetattribute{\the\glslabeltok}{nohyperfirst}{true}% + \glshasattribute{\the\glslabeltok}{regular}% + {% + \glssetattribute{\the\glslabeltok}{regular}{false}% + }% + {}% + }% +}% +{% + \GlsXtrUseAbbrStyleFmts{short-sm-footnote}% +} +% \end{macrocode} +%\end{abbrvstyle} +% %\begin{abbrvstyle}{short-sm-postfootnote} %\changes{0.5}{2015-12-07}{new} %\changes{1.04}{2016-05-02}{renamed from \qt{postfootnote-sm}} +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} \newabbreviationstyle{short-sm-postfootnote}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNoLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrfootnotename}, sort={\the\glsshorttok}, description={\the\glslongtok},% first={\protect\glsfirstabbrvsmfont{\the\glsshorttok}},% firstplural={\protect\glsfirstabbrvsmfont{\the\glsshortpltok}},% + text={\protect\glsabbrvsmfont{\the\glsshorttok}},% plural={\protect\glsabbrvsmfont{\the\glsshortpltok}}}% % \end{macrocode} % Make this category insert a footnote after the link if this was @@ -18781,9 +20146,12 @@ defined}{}% }% }% {% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtrsmsuffix}} +% \begin{macrocode} \renewcommand*\glsabbrvfont[1]{\glsabbrvsmfont{##1}}% \renewcommand*\glsfirstabbrvfont[1]{\glsfirstabbrvsmfont{##1}}% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrsmsuffix}% + \renewcommand*{\abbrvpluralsuffix}{\glsxtrsmsuffix}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongfootnotefont{##1}}% \renewcommand*{\glslongfont}[1]{\glslongfootnotefont{##1}}% % \end{macrocode} @@ -18840,6 +20208,64 @@ defined}{}% % \end{macrocode} %\end{abbrvstyle} % +%\begin{abbrvstyle}{short-sm-postfootnote-desc} +% Like \abbrstyle{short-sm-postfootnote} but with user supplied description. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newabbreviationstyle{short-sm-postfootnote-desc}% +{% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNameLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} + \renewcommand*{\CustomAbbreviationFields}{% + name={\glsxtrfootnotedescname}, + sort={\glsxtrfootnotedescsort}, + first={\protect\glsfirstabbrvsmfont{\the\glsshorttok}},% + firstplural={\protect\glsfirstabbrvsmfont{\the\glsshortpltok}},% + text={\protect\glsabbrvsmfont{\the\glsshorttok}},% + plural={\protect\glsabbrvsmfont{\the\glsshortpltok}}}% +% \end{macrocode} +% Make this category insert a footnote after the link if this was +% the first use, and +% unset the \catattr{regular} attribute if it has been set. +% \begin{macrocode} + \renewcommand*{\GlsXtrPostNewAbbreviation}{% + \csdef{glsxtrpostlink\glscategorylabel}{% + \glsxtrifwasfirstuse + {% +% \end{macrocode} +% Needs the specific font command here as the style may have been +% lost by the time the footnote occurs. +% \begin{macrocode} + \glsxtrdopostpunc{\protect\glsxtrabbrvfootnote{\glslabel}% + {\glsfirstlongfootnotefont{\glsentrylong{\glslabel}}}}% + }% + {}% + }% + \glshasattribute{\the\glslabeltok}{regular}% + {% + \glssetattribute{\the\glslabeltok}{regular}{false}% + }% + {}% + }% +% \end{macrocode} +% The footnote needs to be suppressed in the inline form, so +% \cs{glsxtrfull} must set the first use switch off. +% \begin{macrocode} + \renewcommand*{\glsxtrsetupfulldefs}{% + \let\glsxtrifwasfirstuse\@secondoftwo + }% +}% +{% + \GlsXtrUseAbbrStyleFmts{short-sm-postfootnote}% +} +% \end{macrocode} +%\end{abbrvstyle} +% %\subsection{Predefined Styles (Emphasized)} % These styles use \ics{emph} for the short form. %\begin{macro}{\glsabbrvemfont} @@ -18880,9 +20306,17 @@ defined}{}% %\begin{abbrvstyle}{long-short-em} %\changes{0.5}{2015-12-07}{new} % The long form is just set in the default long font. +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} \newabbreviationstyle{long-short-em}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetFirstLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongshortname}, sort={\the\glsshorttok}, @@ -18892,6 +20326,7 @@ defined}{}% firstplural={\protect\glsfirstlongdefaultfont{\the\glslongpltok}% \protect\glsxtrfullsep{\the\glslabeltok}% \glsxtrparen{\protect\glsfirstabbrvemfont{\the\glsshortpltok}}},% + text={\protect\glsabbrvemfont{\the\glsshorttok}},% plural={\protect\glsabbrvemfont{\the\glsshortpltok}},% description={\the\glslongtok}}% \renewcommand*{\GlsXtrPostNewAbbreviation}{% @@ -18903,9 +20338,12 @@ defined}{}% }% }% {% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtremsuffix}} +% \begin{macrocode} \renewcommand*\glsabbrvfont[1]{\glsabbrvemfont{##1}}% \renewcommand*\glsfirstabbrvfont[1]{\glsfirstabbrvemfont{##1}}% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtremsuffix}% + \renewcommand*{\abbrvpluralsuffix}{\glsxtremsuffix}% % \end{macrocode} % Use the default long fonts. % \begin{macrocode} @@ -18945,6 +20383,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{long-short-em-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetTextShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongshortdescname}, sort={\glsxtrlongshortdescsort},% @@ -18979,10 +20424,16 @@ defined}{}% % %\begin{abbrvstyle}{long-em-short-em} %\changes{1.04}{2016-05-02}{new} +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} \newabbreviationstyle{long-em-short-em}% {% % \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetFirstLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. %\cs{glslongemfont} is used in the description since \cs{glsdesc} %doesn't set the style. % \begin{macrocode} @@ -18998,6 +20449,7 @@ defined}{}% % \end{macrocode} %\changes{1.15}{2017-05-10}{fixed spelling of \cs{glsabbrvfont}} % \begin{macrocode} + text={\protect\glsabbrvemfont{\the\glsshorttok}},% plural={\protect\glsabbrvemfont{\the\glsshortpltok}},% description={\protect\glslongemfont{\the\glslongtok}}}% % \end{macrocode} @@ -19012,7 +20464,10 @@ defined}{}% }% }% {% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtremsuffix}% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtremsuffix}} +% \begin{macrocode} + \renewcommand*{\abbrvpluralsuffix}{\glsxtremsuffix}% \renewcommand*{\glsabbrvfont}[1]{\glsabbrvemfont{##1}}% \renewcommand*{\glsfirstabbrvfont}[1]{\glsfirstabbrvemfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongemfont{##1}}% @@ -19051,6 +20506,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{long-em-short-em-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetTextShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongshortdescname}, sort={\glsxtrlongshortdescsort},% @@ -19083,9 +20545,17 @@ defined}{}% %\begin{abbrvstyle}{short-em-long} % Now the short (long) version %\changes{0.5}{2015-12-07}{new} +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} \newabbreviationstyle{short-em-long}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetFirstLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortlongname}, sort={\the\glsshorttok}, @@ -19096,6 +20566,7 @@ defined}{}% firstplural={\protect\glsfirstabbrvemfont{\the\glsshortpltok}% \protect\glsxtrfullsep{\the\glslabeltok}% \glsxtrparen{\protect\glsfirstlongdefaultfont{\the\glslongpltok}}},% + text={\protect\glsabbrvemfont{\the\glsshorttok}},% plural={\protect\glsabbrvemfont{\the\glsshortpltok}}}% % \end{macrocode} % Unset the \catattr{regular} attribute if it has been set. @@ -19112,8 +20583,9 @@ defined}{}% % \end{macrocode} % Mostly as short-long style: %\changes{1.05}{2016-06-10}{fixed incorrect font used by long form} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtremsuffix}} % \begin{macrocode} - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtremsuffix}% + \renewcommand*{\abbrvpluralsuffix}{\glsxtremsuffix}% \renewcommand*\glsabbrvfont[1]{\glsabbrvemfont{##1}}% \renewcommand*\glsfirstabbrvfont[1]{\glsfirstabbrvemfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongdefaultfont{##1}}% @@ -19154,6 +20626,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{short-em-long-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetTextShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortlongdescname}, sort={\glsxtrshortlongdescsort}, @@ -19185,10 +20664,16 @@ defined}{}% % %\begin{abbrvstyle}{short-em-long-em} %\changes{1.04}{2016-05-02}{new} +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} \newabbreviationstyle{short-em-long-em}% {% % \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetFirstLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. %\cs{glslongemfont} is used in the description since \cs{glsdesc} %doesn't set the style. % \begin{macrocode} @@ -19205,6 +20690,7 @@ defined}{}% % \end{macrocode} %\changes{1.15}{2017-05-10}{fixed spelling of \cs{glsabbrvfont}} % \begin{macrocode} + text={\protect\glsabbrvemfont{\the\glsshorttok}},% plural={\protect\glsabbrvemfont{\the\glsshortpltok}}}% % \end{macrocode} % Unset the \catattr{regular} attribute if it has been set. @@ -19218,7 +20704,10 @@ defined}{}% }% }% {% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtremsuffix}% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtremsuffix}} +% \begin{macrocode} + \renewcommand*{\abbrvpluralsuffix}{\glsxtremsuffix}% \renewcommand*{\glsabbrvfont}[1]{\glsabbrvemfont{##1}}% \renewcommand*{\glsfirstabbrvfont}[1]{\glsfirstabbrvemfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongemfont{##1}}% @@ -19258,6 +20747,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{short-em-long-em-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetTextShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortlongdescname},% sort={\glsxtrshortlongdescsort},% @@ -19292,6 +20788,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{short-em}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNoLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortnolongname}, sort={\the\glsshorttok}, @@ -19304,7 +20807,10 @@ defined}{}% \glssetattribute{\the\glslabeltok}{regular}{true}}% }% {% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtremsuffix}% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtremsuffix}} +% \begin{macrocode} + \renewcommand*{\abbrvpluralsuffix}{\glsxtremsuffix}% \renewcommand*\glsabbrvfont[1]{\glsabbrvemfont{##1}}% \renewcommand*{\glsfirstabbrvfont}[1]{\glsfirstabbrvemfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongdefaultfont{##1}}% @@ -19378,6 +20884,16 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{short-em-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. The default name includes +% the long form but \cs{glsxtrshortdescname} could be modified to +% omit the long form, so include the \category{nameshortaccess} +% attribute. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNoLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortdescname}, sort={\the\glsshorttok}, @@ -19389,7 +20905,10 @@ defined}{}% \glssetattribute{\the\glslabeltok}{regular}{true}}% }% {% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtremsuffix}% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtremsuffix}} +% \begin{macrocode} + \renewcommand*{\abbrvpluralsuffix}{\glsxtremsuffix}% \renewcommand*\glsabbrvfont[1]{\glsabbrvemfont{##1}}% \renewcommand*{\glsfirstabbrvfont}[1]{\glsfirstabbrvemfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongdefaultfont{##1}}% @@ -19497,6 +21016,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{long-noshort-em}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNameShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongnoshortname}, sort={\the\glsshorttok}, @@ -19510,7 +21036,10 @@ defined}{}% \glssetattribute{\the\glslabeltok}{regular}{true}}% }% {% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtremsuffix}% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtremsuffix}} +% \begin{macrocode} + \renewcommand*{\abbrvpluralsuffix}{\glsxtremsuffix}% \renewcommand*\glsabbrvfont[1]{\glsabbrvemfont{##1}}% \renewcommand*{\glsfirstabbrvfont}[1]{\glsfirstabbrvemfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongdefaultfont{##1}}% @@ -19596,6 +21125,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{long-em-noshort-em}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNameShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongnoshortname}, sort={\the\glsshorttok}, @@ -19609,7 +21145,10 @@ defined}{}% \glssetattribute{\the\glslabeltok}{regular}{true}}% }% {% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtremsuffix}% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtremsuffix}} +% \begin{macrocode} + \renewcommand*{\abbrvpluralsuffix}{\glsxtremsuffix}% \renewcommand*\glsabbrvfont[1]{\glsabbrvemfont{##1}}% \renewcommand*{\glsfirstabbrvfont}[1]{\glsfirstabbrvemfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongemfont{##1}}% @@ -19688,6 +21227,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{long-em-noshort-em-noreg}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNameShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \GlsXtrUseAbbrStyleSetup{long-em-noshort-em}% % \end{macrocode} % Unset the \catattr{regular} attribute if it has been set. @@ -19718,7 +21264,10 @@ defined}{}% \GlsXtrUseAbbrStyleSetup{long-noshort-desc}% }% {% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtremsuffix}% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtremsuffix}} +% \begin{macrocode} + \renewcommand*{\abbrvpluralsuffix}{\glsxtremsuffix}% \renewcommand*\glsabbrvfont[1]{\glsabbrvemfont{##1}}% \renewcommand*{\glsfirstabbrvfont}[1]{\glsfirstabbrvemfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongdefaultfont{##1}}% @@ -19800,7 +21349,8 @@ defined}{}% %\begin{abbrvstyle}{long-em-noshort-em-desc} %\changes{1.04}{2016-05-02}{new} % The short form is explicitly invoked through commands like -% \cs{glsxtrshort}. The long form is emphasized. +% \cs{glsxtrshort}. The long form is emphasized. No accessibility +% attributes need to be set. % \begin{macrocode} \newabbreviationstyle{long-em-noshort-em-desc}% {% @@ -19816,7 +21366,10 @@ defined}{}% \glssetattribute{\the\glslabeltok}{regular}{true}}% }% {% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtremsuffix}% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtremsuffix}} +% \begin{macrocode} + \renewcommand*{\abbrvpluralsuffix}{\glsxtremsuffix}% \renewcommand*\glsabbrvfont[1]{\glsabbrvemfont{##1}}% \renewcommand*{\glsfirstabbrvfont}[1]{\glsfirstabbrvemfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongemfont{##1}}% @@ -19916,9 +21469,17 @@ defined}{}% %\begin{abbrvstyle}{short-em-footnote} %\changes{0.5}{2015-12-07}{new} %\changes{1.04}{2015-04-30}{renamed from \qt{footnote-em}} +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} \newabbreviationstyle{short-em-footnote}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNoLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrfootnotename}, sort={\the\glsshorttok}, @@ -19929,6 +21490,7 @@ defined}{}% firstplural={\protect\glsfirstabbrvemfont{\the\glsshortpltok}% \protect\glsxtrabbrvfootnote{\the\glslabeltok}% {\protect\glsfirstlongfootnotefont{\the\glslongpltok}}},% + text={\protect\glsabbrvemfont{\the\glsshorttok}},% plural={\protect\glsabbrvemfont{\the\glsshortpltok}}}% % \end{macrocode} % Switch off hyperlinks on first use to prevent nested hyperlinks, @@ -19945,7 +21507,10 @@ defined}{}% }% }% {% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtremsuffix}% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtremsuffix}} +% \begin{macrocode} + \renewcommand*{\abbrvpluralsuffix}{\glsxtremsuffix}% \renewcommand*\glsabbrvfont[1]{\glsabbrvemfont{##1}}% \renewcommand*{\glsfirstabbrvfont}[1]{\glsfirstabbrvemfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongfootnotefont{##1}}% @@ -20012,18 +21577,71 @@ defined}{}% % \end{macrocode} %\end{abbrvstyle} % +%\begin{abbrvstyle}{short-em-footnote-desc} +% Like \abbrstyle{short-em-footnote} but with user supplied description. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newabbreviationstyle{short-em-footnote-desc}% +{% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNameLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} + \renewcommand*{\CustomAbbreviationFields}{% + name={\glsxtrfootnotedescname}, + sort={\glsxtrfootnotedescsort}, + first={\protect\glsfirstabbrvemfont{\the\glsshorttok}% + \protect\glsxtrabbrvfootnote{\the\glslabeltok}% + {\protect\glsfirstlongfootnotefont{\the\glslongtok}}},% + firstplural={\protect\glsfirstabbrvemfont{\the\glsshortpltok}% + \protect\glsxtrabbrvfootnote{\the\glslabeltok}% + {\protect\glsfirstlongfootnotefont{\the\glslongpltok}}},% + text={\protect\glsabbrvemfont{\the\glsshorttok}},% + plural={\protect\glsabbrvemfont{\the\glsshortpltok}}}% +% \end{macrocode} +% Switch off hyperlinks on first use to prevent nested hyperlinks, +% and unset the \catattr{regular} attribute if it has been set. +%\changes{0.5.1}{2015-12-07}{switch off regular attribute if set} +% \begin{macrocode} + \renewcommand*{\GlsXtrPostNewAbbreviation}{% + \glssetattribute{\the\glslabeltok}{nohyperfirst}{true}% + \glshasattribute{\the\glslabeltok}{regular}% + {% + \glssetattribute{\the\glslabeltok}{regular}{false}% + }% + {}% + }% +}% +{% + \GlsXtrUseAbbrStyleFmts{short-em-footnote}% +} +% \end{macrocode} +%\end{abbrvstyle} +% %\begin{abbrvstyle}{short-em-postfootnote} %\changes{0.5}{2015-12-07}{new} %\changes{1.04}{2016-05-02}{renamed from \qt{postfootnote-em}} +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} \newabbreviationstyle{short-em-postfootnote}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNoLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrfootnotename}, sort={\the\glsshorttok}, description={\the\glslongtok},% first={\protect\glsfirstabbrvemfont{\the\glsshorttok}},% firstplural={\protect\glsfirstabbrvemfont{\the\glsshortpltok}},% + text={\protect\glsabbrvemfont{\the\glsshorttok}},% plural={\protect\glsabbrvemfont{\the\glsshortpltok}}}% % \end{macrocode} % Make this category insert a footnote after the link if this was @@ -20058,7 +21676,10 @@ defined}{}% }% }% {% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtremsuffix}% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtremsuffix}} +% \begin{macrocode} + \renewcommand*{\abbrvpluralsuffix}{\glsxtremsuffix}% \renewcommand*\glsabbrvfont[1]{\glsabbrvemfont{##1}}% \renewcommand*{\glsfirstabbrvfont}[1]{\glsfirstabbrvemfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongfootnotefont{##1}}% @@ -20117,6 +21738,64 @@ defined}{}% % \end{macrocode} %\end{abbrvstyle} % +%\begin{abbrvstyle}{short-em-postfootnote-desc} +% Like \abbrstyle{short-em-postfootnote} but with user supplied description. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newabbreviationstyle{short-em-postfootnote-desc}% +{% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNameLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} + \renewcommand*{\CustomAbbreviationFields}{% + name={\glsxtrfootnotedescname}, + sort={\glsxtrfootnotedescsort}, + first={\protect\glsfirstabbrvemfont{\the\glsshorttok}},% + firstplural={\protect\glsfirstabbrvemfont{\the\glsshortpltok}},% + text={\protect\glsabbrvemfont{\the\glsshorttok}},% + plural={\protect\glsabbrvemfont{\the\glsshortpltok}}}% +% \end{macrocode} +% Make this category insert a footnote after the link if this was +% the first use, and +% unset the \catattr{regular} attribute if it has been set. +% \begin{macrocode} + \renewcommand*{\GlsXtrPostNewAbbreviation}{% + \csdef{glsxtrpostlink\glscategorylabel}{% + \glsxtrifwasfirstuse + {% +% \end{macrocode} +% Needs the specific font command here as the style may have been +% lost by the time the footnote occurs. +% \begin{macrocode} + \glsxtrdopostpunc{\protect\glsxtrabbrvfootnote{\glslabel}% + {\glsfirstlongfootnotefont{\glsentrylong{\glslabel}}}}% + }% + {}% + }% + \glshasattribute{\the\glslabeltok}{regular}% + {% + \glssetattribute{\the\glslabeltok}{regular}{false}% + }% + {}% + }% +% \end{macrocode} +% The footnote needs to be suppressed in the inline form, so +% \cs{glsxtrfull} must set the first use switch off. +% \begin{macrocode} + \renewcommand*{\glsxtrsetupfulldefs}{% + \let\glsxtrifwasfirstuse\@secondoftwo + }% +}% +{% + \GlsXtrUseAbbrStyleFmts{short-em-postfootnote}% +} +% \end{macrocode} +%\end{abbrvstyle} +% %\subsection{Predefined Styles (User Parentheses Hook)} % These styles allow the user to adjust the parenthetical forms. % These styles all test for the existence of the @@ -20204,9 +21883,17 @@ defined}{}% % %\begin{abbrvstyle}{long-short-user} %\changes{1.04}{2016-05-02}{new} +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} \newabbreviationstyle{long-short-user}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetFirstLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongshortname}, sort={\the\glsshorttok}, @@ -20219,6 +21906,7 @@ defined}{}% % \end{macrocode} %\changes{1.15}{2017-05-10}{fixed spelling of \cs{glsabbrvfont}} % \begin{macrocode} + text={\protect\glsabbrvuserfont{\the\glsshorttok}},% plural={\protect\glsabbrvuserfont{\the\glsshortpltok}},% description={\protect\glsuserdescription{\the\glslongtok}% {\the\glslabeltok}}}% @@ -20273,11 +21961,19 @@ defined}{}% % %\begin{abbrvstyle}{long-postshort-user} %\changes{1.12}{2017-02-03}{new} +%\changes{1.42}{2020-02-03}{added missing text key} %Like \abbrstyle{long-short-user} but defers the parenthetical %matter to after the link. % \begin{macrocode} \newabbreviationstyle{long-postshort-user}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetFirstLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongshortname}, sort={\the\glsshorttok}, @@ -20286,6 +21982,7 @@ defined}{}% % \end{macrocode} %\changes{1.15}{2017-05-10}{fixed spelling of \cs{glsabbrvfont}} % \begin{macrocode} + text={\protect\glsabbrvuserfont{\the\glsshorttok}},% plural={\protect\glsabbrvuserfont{\the\glsshortpltok}},% description={\protect\glsuserdescription{\the\glslongtok}% {\the\glslabeltok}}}% @@ -20380,6 +22077,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{long-postshort-user-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetTextShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongshortuserdescname}, sort={\the\glslongtok}, @@ -20416,11 +22120,19 @@ defined}{}% % %\begin{abbrvstyle}{short-postlong-user} %\changes{1.12}{2017-02-03}{new} +%\changes{1.42}{2020-02-03}{added missing text key} %Like \abbrstyle{short-long-user} but defers the parenthetical %matter to after the link. % \begin{macrocode} \newabbreviationstyle{short-postlong-user}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetFirstLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortlongname}, sort={\the\glsshorttok}, @@ -20429,6 +22141,7 @@ defined}{}% % \end{macrocode} %\changes{1.15}{2017-05-10}{fixed spelling of \cs{glsabbrvfont}} % \begin{macrocode} + text={\protect\glsabbrvuserfont{\the\glsshorttok}},% plural={\protect\glsabbrvuserfont{\the\glsshortpltok}},% description={\protect\glsuserdescription{\the\glslongtok}% {\the\glslabeltok}}}% @@ -20524,6 +22237,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{short-postlong-user-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetTextShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortlonguserdescname}, sort={\the\glsshorttok}, @@ -20563,6 +22283,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{long-short-user-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetTextShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongshortuserdescname}, sort={\glsxtrlongshortdescsort},% @@ -20597,10 +22324,18 @@ defined}{}% % %\begin{abbrvstyle}{short-long-user} %\changes{1.04}{2016-05-02}{new} +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} \newabbreviationstyle{short-long-user}% {% % \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetFirstLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} +% \end{macrocode} %\cs{glslonguserfont} is used in the description since \cs{glsdesc} %doesn't set the style. (Now in \cs{glsuserdescription}.) % \begin{macrocode} @@ -20618,6 +22353,7 @@ defined}{}% % \end{macrocode} %\changes{1.15}{2017-05-10}{fixed spelling of \cs{glsabbrvfont}} % \begin{macrocode} + text={\protect\glsabbrvuserfont{\the\glsshorttok}},% plural={\protect\glsabbrvuserfont{\the\glsshortpltok}}}% % \end{macrocode} % Unset the \catattr{regular} attribute if it has been set. @@ -20673,6 +22409,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{short-long-user-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetTextShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortlonguserdescname}, sort={\glsxtrshortlongdescsort},% @@ -20803,10 +22546,18 @@ defined}{}% % %\begin{abbrvstyle}{long-hyphen-short-hyphen} %\changes{1.17}{2017-08-09}{new} +%\changes{1.42}{2020-02-03}{added missing text key} %Designed for use with the \catattr{markwords} attribute. % \begin{macrocode} \newabbreviationstyle{long-hyphen-short-hyphen}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetFirstLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongshortname}, sort={\the\glsshorttok}, @@ -20816,6 +22567,7 @@ defined}{}% firstplural={\protect\glsfirstlonghyphenfont{\the\glslongpltok}% \protect\glsxtrfullsep{\the\glslabeltok}% \glsxtrparen{\protect\glsfirstabbrvhyphenfont{\the\glsshortpltok}}},% + text={\protect\glsabbrvhyphenfont{\the\glsshorttok}},% plural={\protect\glsabbrvhyphenfont{\the\glsshortpltok}},% description={\protect\glslonghyphenfont{\the\glslongtok}}}% % \end{macrocode} @@ -20864,6 +22616,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{long-hyphen-short-hyphen-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetTextShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongshortdescname}, sort={\glsxtrlongshortdescsort}, @@ -20921,11 +22680,13 @@ defined}{}% % %\begin{abbrvstyle}{long-hyphen-noshort-desc-noreg} %\changes{1.17}{2017-08-09}{new} +%\changes{1.42}{2020-02-03}{added missing text key} %This version doesn't show the short form (except %explicitly with \cs{glsxtrshort}). Since \cs{glsxtrshort} doesn't %support the hyphen switch, the short form just uses the default %short-form font command. This style won't work with the %\catattr{regular} as the regular form isn't flexible enough. +%No accessibility attributes need to be set. % \begin{macrocode} \newabbreviationstyle{long-hyphen-noshort-desc-noreg}% {% @@ -20934,6 +22695,7 @@ defined}{}% sort={\expandonce\glsxtrorglong}, first={\protect\glsfirstlonghyphenfont{\the\glslongtok}},% firstplural={\protect\glsfirstlonghyphenfont{\the\glslongpltok}},% + text={\protect\glslonghyphenfont{\the\glslongtok}},% plural={\protect\glslonghyphenfont{\the\glslongpltok}}% }% % \end{macrocode} @@ -21027,6 +22789,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{long-hyphen-noshort-noreg}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetNameShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongnoshortname}, sort={\the\glsshorttok}, @@ -21118,16 +22887,25 @@ defined}{}% % %\begin{abbrvstyle}{long-hyphen-postshort-hyphen} %\changes{1.17}{2017-08-09}{new} +%\changes{1.42}{2020-02-03}{added missing text key} %Like \abbrstyle{long-hyphen-short-hyphen} but shifts the insert %and parenthetical material to the post-link hook. % \begin{macrocode} \newabbreviationstyle{long-hyphen-postshort-hyphen}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetFirstLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongshortname}, sort={\the\glsshorttok}, first={\protect\glsfirstlonghyphenfont{\the\glslongtok}},% firstplural={\protect\glsfirstlonghyphenfont{\the\glslongpltok}},% + text={\protect\glsabbrvhyphenfont{\the\glsshorttok}},% plural={\protect\glsabbrvhyphenfont{\the\glsshortpltok}},% description={\protect\glslonghyphenfont{\the\glslongtok}}}% \renewcommand*{\GlsXtrPostNewAbbreviation}{% @@ -21224,6 +23002,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{long-hyphen-postshort-hyphen-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetTextShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrlongshortdescname}, sort={\glsxtrlongshortdescsort},% @@ -21290,10 +23075,18 @@ defined}{}% % %\begin{abbrvstyle}{short-hyphen-long-hyphen} %\changes{1.17}{2017-08-09}{new} +%\changes{1.42}{2020-02-03}{added missing text key} %Designed for use with the \catattr{markwords} attribute. % \begin{macrocode} \newabbreviationstyle{short-hyphen-long-hyphen}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetFirstLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortlongname}, sort={\the\glsshorttok}, @@ -21303,6 +23096,7 @@ defined}{}% firstplural={\protect\glsfirstabbrvhyphenfont{\the\glsshortpltok}% \protect\glsxtrfullsep{\the\glslabeltok}% \glsxtrparen{\protect\glsfirstlonghyphenfont{\the\glslongpltok}}},% + text={\protect\glsabbrvhyphenfont{\the\glsshorttok}},% plural={\protect\glsabbrvhyphenfont{\the\glsshortpltok}},% description={\protect\glslonghyphenfont{\the\glslongtok}}}% % \end{macrocode} @@ -21351,6 +23145,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{short-hyphen-long-hyphen-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetTextShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortlongdescname}, sort={\glsxtrshortlongdescsort}, @@ -21427,16 +23228,25 @@ defined}{}% % %\begin{abbrvstyle}{short-hyphen-postlong-hyphen} %\changes{1.17}{2017-08-09}{new} +%\changes{1.42}{2020-02-03}{added missing text key} %Like \abbrstyle{short-hyphen-long-hyphen} but shifts the insert %and parenthetical material to the post-link hook. % \begin{macrocode} \newabbreviationstyle{short-hyphen-postlong-hyphen}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetFirstLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortlongname}, sort={\the\glsshorttok}, first={\protect\glsfirstabbrvhyphenfont{\the\glsshorttok}},% firstplural={\protect\glsfirstabbrvhyphenfont{\the\glsshortpltok}},% + text={\protect\glsabbrvhyphenfont{\the\glsshorttok}},% plural={\protect\glsabbrvhyphenfont{\the\glsshortpltok}},% description={\protect\glslonghyphenfont{\the\glslongtok}}}% \renewcommand*{\GlsXtrPostNewAbbreviation}{% @@ -21535,6 +23345,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{short-hyphen-postlong-hyphen-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetTextShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtrshortlongdescname}, sort={\glsxtrshortlongdescsort},% @@ -21616,14 +23433,23 @@ defined}{}% % %\begin{abbrvstyle}{long-only-short-only} %\changes{1.17}{2017-08-09}{new} +%\changes{1.42}{2020-02-03}{added missing text key} % \begin{macrocode} \newabbreviationstyle{long-only-short-only}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetFirstLongAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtronlyname}, sort={\the\glsshorttok}, first={\protect\glsfirstlongonlyfont{\the\glslongtok}},% firstplural={\protect\glsfirstlongonlyfont{\the\glslongpltok}},% + text={\protect\glsabbrvonlyfont{\the\glsshorttok}},% plural={\protect\glsabbrvonlyfont{\the\glsshortpltok}},% description={\protect\glslongonlyfont{\the\glslongtok}}}% % \end{macrocode} @@ -21638,7 +23464,10 @@ defined}{}% }% }% {% - \renewcommand*{\abbrvpluralsuffix}{\protect\glsxtronlysuffix}% +% \end{macrocode} +%\changes{1.42}{2020-02-03}{removed \cs{protect} from \cs{glsxtronlysuffix}} +% \begin{macrocode} + \renewcommand*{\abbrvpluralsuffix}{\glsxtronlysuffix}% \renewcommand*{\glsabbrvfont}[1]{\glsabbrvonlyfont{##1}}% \renewcommand*{\glsfirstabbrvfont}[1]{\glsfirstabbrvonlyfont{##1}}% \renewcommand*{\glsfirstlongfont}[1]{\glsfirstlongonlyfont{##1}}% @@ -21714,6 +23543,13 @@ defined}{}% % \begin{macrocode} \newabbreviationstyle{long-only-short-only-desc}% {% +% \end{macrocode} +% Set accessibility attributes if enabled. +% \begin{macrocode} + \glsxtrAccSuppAbbrSetTextShortAttrs\glscategorylabel +% \end{macrocode} +% Setup the default fields. +% \begin{macrocode} \renewcommand*{\CustomAbbreviationFields}{% name={\glsxtronlydescname}, sort={\glsxtronlydescsort},% @@ -22087,6 +23923,17 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSxtrtitleshort} +%\changes{1.42}{2020-02-03}{new} +% Command to display short form of abbreviation in section title and +% table of contents in all upper case. +% \begin{macrocode} +\newrobustcmd*{\GLSxtrtitleshort}[1]{% + \GLSxtrshort[noindex,hyper=false]{#1}[]% +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\Glsxtrheadshortpl} % Command used to display plural short form in the page header with the % first letter converted to upper case. @@ -22117,6 +23964,17 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSxtrtitleshortpl} +%\changes{1.42}{2020-02-03}{new} +% Command to display plural short form of abbreviation in section title and +% table of contents in all upper case. +% \begin{macrocode} +\newrobustcmd*{\GLSxtrtitleshortpl}[1]{% + \GLSxtrshortpl[noindex,hyper=false]{#1}[]% +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\glsxtrheadname} % As above but for the \gloskey{name} value. %\changes{1.21}{2017-11-03}{new} @@ -22169,14 +24027,25 @@ defined}{}% %\begin{macro}{\Glsxtrtitlename} % Command to display \gloskey{name} value in section title and % table of contents with the first letter changed to upper case. -% \begin{macrocode} %\changes{1.21}{2017-11-03}{new} +% \begin{macrocode} \newrobustcmd*{\Glsxtrtitlename}[1]{% \Glsname[noindex,hyper=false]{#1}[]% } % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSxtrtitlename} +% Command to display \gloskey{name} value in section title and +% table of contents in all upper case. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newrobustcmd*{\GLSxtrtitlename}[1]{% + \GLSname[noindex,hyper=false]{#1}[]% +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\glsxtrheadtext} % As above but for the \gloskey{text} value. %\changes{0.5.1}{2015-12-07}{now uses headuc attribute} @@ -22236,6 +24105,17 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSxtrtitletext} +% Command to display \gloskey{text} value in section title and +% table of contents in all upper case. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newrobustcmd*{\GLSxtrtitletext}[1]{% + \GLStext[noindex,hyper=false]{#1}[]% +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\glsxtrheadplural} % As above but for the \gloskey{plural} value. %\changes{0.5.1}{2015-12-07}{now uses headuc attribute} @@ -22294,6 +24174,17 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSxtrtitleplural} +%\changes{1.42}{2020-02-03}{new} +% Command to display \gloskey{plural} value in section title and +% table of contents in all upper case. +% \begin{macrocode} +\newrobustcmd*{\GLSxtrtitleplural}[1]{% + \GLSplural[noindex,hyper=false]{#1}[]% +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\glsxtrheadfirst} % As above but for the \gloskey{first} value. %\changes{0.5.1}{2015-12-07}{now uses headuc attribute} @@ -22352,6 +24243,17 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSxtrtitlefirst} +%\changes{1.42}{2020-02-03}{new} +% Command to display \gloskey{first} value in section title and +% table of contents in all upper case. +% \begin{macrocode} +\newrobustcmd*{\GLSxtrtitlefirst}[1]{% + \GLSfirst[noindex,hyper=false]{#1}[]% +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\glsxtrheadfirstplural} % As above but for the \gloskey{firstplural} value. %\changes{0.5.1}{2015-12-07}{now uses headuc attribute} @@ -22410,6 +24312,17 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSxtrtitlefirstplural} +%\changes{1.42}{2020-02-03}{new} +% Command to display \gloskey{first} value in section title and +% table of contents in all upper case. +% \begin{macrocode} +\newrobustcmd*{\GLSxtrtitlefirstplural}[1]{% + \GLSfirstplural[noindex,hyper=false]{#1}[]% +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\glsxtrheadlong} % Command used to display long form in the page header. %\changes{1.02}{2016-04-25}{new} @@ -22506,6 +24419,17 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSxtrtitlelong} +% Command to display long form of abbreviation in section title and +% table of contents in all upper case. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newrobustcmd*{\GLSxtrtitlelong}[1]{% + \GLSxtrlong[noindex,hyper=false]{#1}[]% +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\Glsxtrheadlongpl} % Command used to display plural long form in the page header with the % first letter converted to upper case. @@ -22537,6 +24461,17 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSxtrtitlelongpl} +% Command to display plural long form of abbreviation in section title and +% table of contents in all upper case. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newrobustcmd*{\GLSxtrtitlelongpl}[1]{% + \GLSxtrlongpl[noindex,hyper=false]{#1}[]% +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\glsxtrheadfull} % Command used to display full form in the page header. %\changes{1.02}{2016-04-25}{new} @@ -22631,6 +24566,17 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSxtrtitlefull} +% Command to display full form of abbreviation in section title and +% table of contents in all upper case. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newrobustcmd*{\GLSxtrtitlefull}[1]{% + \GLSxtrfull[noindex,hyper=false]{#1}[]% +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\Glsxtrheadfullpl} % Command used to display plural full form in the page header with the % first letter converted to upper case. @@ -22662,6 +24608,17 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSxtrtitlefullpl} +% Command to display plural full form of abbreviation in section title and +% table of contents in all upper case. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\newrobustcmd*{\GLSxtrtitlefullpl}[1]{% + \GLSxtrfullpl[noindex,hyper=false]{#1}[]% +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\glsfmtshort} % Provide a way of using the formatted short form in section % headings. If \sty{hyperref} has been loaded, use @@ -22789,6 +24746,25 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSfmtname} +%All upper case. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\ifdef\texorpdfstring +{ + \newcommand*{\GLSfmtname}[1]{% + \texorpdfstring + {\GLSxtrtitlename{#1}}% + {\glsentryname{#1}}% + } +} +{ + \newcommand*{\GLSfmtname}[1]{% + \GLSxtrtitlename{#1}} +} +% \end{macrocode} +%\end{macro} +% % %\begin{macro}{\glsfmttext} %As above but for the \gloskey{text} value. @@ -22828,6 +24804,25 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSfmttext} +%All upper case. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\ifdef\texorpdfstring +{ + \newcommand*{\GLSfmttext}[1]{% + \texorpdfstring + {\GLSxtrtitletext{#1}}% + {\glsentrytext{#1}}% + } +} +{ + \newcommand*{\GLSfmttext}[1]{% + \GLSxtrtitletext{#1}} +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\glsfmtplural} %As above but for the \gloskey{plural} value. %\changes{0.5}{2015-12-07}{new} @@ -22866,6 +24861,25 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSfmtplural} +%All upper case. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\ifdef\texorpdfstring +{ + \newcommand*{\GLSfmtplural}[1]{% + \texorpdfstring + {\GLSxtrtitleplural{#1}}% + {\glsentryplural{#1}}% + } +} +{ + \newcommand*{\GLSfmtplural}[1]{% + \GLSxtrtitleplural{#1}} +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\glsfmtfirst} %As above but for the \gloskey{first} value. %\changes{0.5}{2015-12-07}{new} @@ -22904,6 +24918,25 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSfmtfirst} +%All upper case. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\ifdef\texorpdfstring +{ + \newcommand*{\GLSfmtfirst}[1]{% + \texorpdfstring + {\GLSxtrtitlefirst{#1}}% + {\glsentryfirst{#1}}% + } +} +{ + \newcommand*{\GLSfmtfirst}[1]{% + \Glsxtrtitlefirst{#1}} +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\glsfmtfirstpl} %As above but for the \gloskey{firstplural} value. %\changes{0.5}{2015-12-07}{new} @@ -22942,6 +24975,25 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSfmtfirstpl} +%All upper case. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\ifdef\texorpdfstring +{ + \newcommand*{\GLSfmtfirstpl}[1]{% + \texorpdfstring + {\GLSxtrtitlefirstplural{#1}}% + {\glsentryfirstplural{#1}}% + } +} +{ + \newcommand*{\GLSfmtfirstpl}[1]{% + \GLSxtrtitlefirstplural{#1}} +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\glsfmtlong} %As above but for the \gloskey{long} value. %\changes{1.02}{2016-04-25}{new} @@ -22980,6 +25032,25 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSfmtlong} +%All upper case. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\ifdef\texorpdfstring +{ + \newcommand*{\GLSfmtlong}[1]{% + \texorpdfstring + {\GLSxtrtitlelong{#1}}% + {\glsentrylong{#1}}% + } +} +{ + \newcommand*{\GLSfmtlong}[1]{% + \GLSxtrtitlelong{#1}} +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\glsfmtlongpl} %As above but for the \gloskey{longplural} value. %\changes{1.02}{2016-04-25}{new} @@ -23018,16 +25089,52 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSfmtlongpl} +%All upper case. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\ifdef\texorpdfstring +{ + \newcommand*{\GLSfmtlongpl}[1]{% + \texorpdfstring + {\GLSxtrtitlelongpl{#1}}% + {\glsentrylongpl{#1}}% + } +} +{ + \newcommand*{\GLSfmtlongpl}[1]{% + \GLSxtrtitlelongpl{#1}} +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\glspdffmtfull} +%\changes{1.42}{2020-02-03}{new} +%Can't use \cs{glsxtrinlinefullformat} in PDF bookmarks as it's not +%fully expandable. This command is for the PDF part of +%\cs{texorpdfstring} for the full form. +% \begin{macrocode} +\newcommand*{\glspdffmtfull}[1]{\glsentrylong{#1} (\glsentryshort{#1})}% +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glspdffmtfullpl} +%\changes{1.42}{2020-02-03}{new} +%Likewise for plural. +% \begin{macrocode} +\newcommand*{\glspdffmtfullpl}[1]{\glsentrylongpl{#1} (\glsentryshortpl{#1})}% +% \end{macrocode} +%\end{macro} %\begin{macro}{\glsfmtfull} %In-line full format. %\changes{1.02}{2016-04-25}{new} +%\changes{1.42}{2020-02-03}{switched pdf case to use \cs{glspdffmtfull}} % \begin{macrocode} \ifdef\texorpdfstring { \newcommand*{\glsfmtfull}[1]{% \texorpdfstring {\glsxtrtitlefull{#1}}% - {\glsxtrinlinefullformat{#1}{}}% + {\glspdffmtfull{#1}}% } } { @@ -23040,13 +25147,14 @@ defined}{}% %\begin{macro}{\Glsfmtfull} %First letter converted to upper case. %\changes{1.02}{2016-04-25}{new} +%\changes{1.42}{2020-02-03}{switched pdf case to use \cs{glspdffmtfull}} % \begin{macrocode} \ifdef\texorpdfstring { \newcommand*{\Glsfmtfull}[1]{% \texorpdfstring {\Glsxtrtitlefull{#1}}% - {\Glsxtrinlinefullformat{#1}{}}% + {\glspdffmtfull{#1}{}}% } } { @@ -23056,16 +25164,36 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSfmtfull} +%All upper case. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\ifdef\texorpdfstring +{ + \newcommand*{\GLSfmtfull}[1]{% + \texorpdfstring + {\GLSxtrtitlefull{#1}}% + {\glspdffmtfull{#1}}% + } +} +{ + \newcommand*{\GLSfmtfull}[1]{% + \GLSxtrtitlefull{#1}} +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\glsfmtfullpl} %In-line full plural format. %\changes{1.02}{2016-04-25}{new} +%\changes{1.42}{2020-02-03}{switched pdf case to use \cs{glspdffmtfullpl}} % \begin{macrocode} \ifdef\texorpdfstring { \newcommand*{\glsfmtfullpl}[1]{% \texorpdfstring {\glsxtrtitlefullpl{#1}}% - {\glsxtrinlinefullplformat{#1}{}}% + {\glspdffmtfullpl{#1}}% } } { @@ -23078,13 +25206,14 @@ defined}{}% %\begin{macro}{\Glsfmtfullpl} %First letter converted to upper case. %\changes{1.02}{2016-04-25}{new} +%\changes{1.42}{2020-02-03}{switched pdf case to use \cs{glspdffmtfullpl}} % \begin{macrocode} \ifdef\texorpdfstring { \newcommand*{\Glsfmtfullpl}[1]{% \texorpdfstring {\Glsxtrtitlefullpl{#1}}% - {\Glsxtrinlinefullplformat{#1}{}}% + {\glspdffmtfullpl{#1}{}}% } } { @@ -23094,6 +25223,25 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\GLSfmtfullpl} +%All upper case. +%\changes{1.42}{2020-02-03}{new} +% \begin{macrocode} +\ifdef\texorpdfstring +{ + \newcommand*{\GLSfmtfullpl}[1]{% + \texorpdfstring + {\GLSxtrtitlefullpl{#1}}% + {\glspdffmtfullpl{#1}{}}% + } +} +{ + \newcommand*{\GLSfmtfullpl}[1]{% + \GLSxtrtitlefullpl{#1}} +} +% \end{macrocode} +%\end{macro} +% %\section{Multi-Lingual Support} % Add the facility to load language modules, if they are installed, % but none are provided with this package. @@ -23180,7 +25328,7 @@ defined}{}% %automatically loaded by the record option. % \begin{macrocode} \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{glossaries-extra-bib2gls}[2019/04/09 v1.41 (NLCT)] +\ProvidesPackage{glossaries-extra-bib2gls}[2020/02/13 v1.42 (NLCT)] % \end{macrocode} %Provide convenient shortcut commands for predefined glossary types. %\begin{macro}{\printunsrtacronyms} @@ -23237,6 +25385,30 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\glsdisplaynumberlist} +%\changes{1.42}{2020-02-03}{added} +%Allow \cs{glsdisplaynumberlist} and make it robust. +% \begin{macrocode} +\renewcommand*{\glsdisplaynumberlist}[1]{% + \glsdoifexists{#1}% + {% + {\let\bibglsdelimN\glsnumlistsep + \let\bibglslastDelimN\glsnumlistlastsep + \glsxtrusefield{#1}{location}% + }% + }% +} +\robustify\glsdisplaynumberlist +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\glsentrynumberlist} +%\changes{1.42}{2020-02-03}{added} +% \begin{macrocode} +\renewcommand*{\glsentrynumberlist}[1]{\glsxtrusefield{#1}{location}} +% \end{macrocode} +%\end{macro} +% %These are some convenient macros for use with custom rules. %\begin{macro}{\glshex} %\changes{1.21}{2017-11-03}{new} @@ -23461,11 +25633,14 @@ defined}{}% { % \end{macrocode} % Default action uses \meta{hcounter}. Equations and pages typically don't -% have a title, so check the counter name. +% have a title, so check the counter name (otherwise the title may +% section or chapter title, which may be confusing). As from v1.42, +% this now checks if the control sequence +% \cs{glsxtr\meta{counter}locfmt} is defined. % \begin{macrocode} \newcommand*{\glsxtrdisplaylocnameref}[8]{% - \ifstrequal{#2}{equation}% - {\glsxtrnamereflink{#3}{(#4)}{#2.#7}{#8}}% + \ifcsdef{glsxtr#2locfmt}% + {\glsxtrnamereflink{#3}{\csuse{glsxtr#2locfmt}{#4}{#5}}{#2.#7}{#8}}% {% \ifstrempty{#5}% {% @@ -23485,6 +25660,16 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\glsxtrequationlocfmt} +%\changes{1.42}{2020-02-03}{new} +%\begin{definition} +%\cs{glsxtrequationlocfmt}\marg{location}\marg{title} +%\end{definition} +% \begin{macrocode} +\newcommand*{\glsxtrequationlocfmt}[2]{(#1)} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\glsxtrnamereflink} %\changes{1.37}{2018-11-30}{new} %\begin{definition} @@ -23571,6 +25756,7 @@ defined}{}% %\begin{definition} %\cs{glsxtrfmtinternalnameloc}\marg{target}\marg{format}\marg{title} %\end{definition} +% % \begin{macrocode} \newcommand*{\glsxtrfmtinternalnameref}[3]{% \csuse{#2}{\glsdohyperlink{#1}{#3}}% @@ -26227,7 +28413,7 @@ defined}{}% % First identify package: % \begin{macrocode} \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{glossaries-extra-stylemods}[2019/04/09 v1.41 (NLCT)] +\ProvidesPackage{glossaries-extra-stylemods}[2020/02/13 v1.42 (NLCT)] % \end{macrocode} % Provide package options to automatically load required predefined % styles. The simplest method is to just test for the existence of @@ -27017,10 +29203,20 @@ defined}{}% \newcommand*{\glstreechildprelocation}{\glstreeprelocation} % \end{macrocode} %\end{macro} +%Don't prohibit a page break at the start of a new group if there's +%no header. %\begin{macro}{\glstreegroupskip} %\changes{1.41}{2019-04-09}{new} % \begin{macrocode} - \newcommand{\glstreegroupskip}{\nopagebreak\indexspace\nobreak} + \newcommand{\glstreegroupskip}{\indexspace} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glstreegroupheaderskip} +%\changes{1.42}{2020-02-03}{new} +%This doesn't include \cs{@afterheading} as it can cause +%interference with some styles. +% \begin{macrocode} + \newcommand{\glstreegroupheaderskip}{\nopagebreak\glstreegroupskip\nobreak} % \end{macrocode} %\end{macro} %Modify the \glostyle{index} style. @@ -27074,7 +29270,7 @@ defined}{}% \glsxtrgetgrouptitle{##1}{\glsxtr@grptitle}% \glstreePreHeader{##1}{\glsxtr@grptitle}% \item\glstreegroupheaderfmt{\glsxtr@grptitle}% - \glstreegroupskip\@afterheading + \glstreegroupheaderskip\@afterheading }% } } @@ -27091,13 +29287,13 @@ defined}{}% \setglossarystyle{index}% \renewcommand*{\glossaryheader}{% \item\glstreenavigationfmt{\glsnavigation}% - \glstreegroupskip\@afterheading}% + \glstreegroupheaderskip\@afterheading}% \renewcommand*{\glsgroupheading}[1]{% \glsxtrgetgrouptitle{##1}{\glsxtr@grptitle}% \glstreePreHeader{##1}{\glsxtr@grptitle}% \item\glstreegroupheaderfmt {\glsnavhypertarget{##1}{\glsxtr@grptitle}}% - \glstreegroupskip\@afterheading}% + \glstreegroupheaderskip\@afterheading}% }% } {} @@ -27126,17 +29322,27 @@ defined}{}% %\cs{glstreeDescLoc}\marg{label}\marg{location} %\end{definition} %This checks for the description and symbol. If both are missing, -%don't want a space at the start of the location list. (For example, -%the entry may just have a cross-reference.) +%a different separator may be required. For example, a comma and +%space if there's no description or symbol but just a space if +%either of those fields are present. % \begin{macrocode} \newcommand{\glstreeDescLoc}[2]{% \ifglshasdesc{#1}% {\glstreedesc{#1}\glstreeprelocation}% - {\ifglshassymbol{#1}{\glstreeprelocation}{}}% + {\ifglshassymbol{#1}{\glstreeprelocation}{\glstreeNoDescSymbolPreLocation}}% #2% } % \end{macrocode} %\end{macro} +%\begin{macro}{\glstreeNoDescSymbolPreLocation} +%\changes{1.42}{2020-02-03}{new} +%\begin{definition} +%\cs{glstreeNoDescSymbolPreLocation} +%\end{definition} +% \begin{macrocode} + \newcommand{\glstreeNoDescSymbolPreLocation}{\space} +% \end{macrocode} +%\end{macro} %Similarly for the symbol. %\begin{macro}{\glstreesymbol} %\changes{1.31}{2018-05-09}{new} @@ -27157,11 +29363,14 @@ defined}{}% %\end{macro} %\begin{macro}{\glstreeChildDescLoc} %\changes{1.41}{2019-04-09}{new} +%\changes{1.42}{2020-02-03}{added \cs{glstreeNoDescSymbolPreLocation}} % \begin{macrocode} \newcommand{\glstreeChildDescLoc}[2]{% \ifglshasdesc{#1}% {\glstreechilddesc{#1}\glstreechildprelocation}% - {\ifglshassymbol{#1}{\glstreechildprelocation}{}}% + {\ifglshassymbol{#1}{\glstreechildprelocation}% + {\glstreeNoDescSymbolPreLocation}% + }% #2% }% % \end{macrocode} @@ -27219,7 +29428,7 @@ defined}{}% \glsxtrgetgrouptitle{##1}{\glsxtr@grptitle}% \glstreePreHeader{##1}{\glsxtr@grptitle}% \par\noindent\glstreegroupheaderfmt{\glsxtr@grptitle}% - \glstreegroupskip\@afterheading}% + \glstreegroupheaderskip\@afterheading}% } } {} @@ -27235,14 +29444,14 @@ defined}{}% \setglossarystyle{tree}% \renewcommand*{\glossaryheader}{% \par\noindent\glstreenavigationfmt{\glsnavigation}% - \glstreegroupskip\@afterheading}% + \glstreegroupheaderskip\@afterheading}% \renewcommand*{\glsgroupheading}[1]{% \glsxtrgetgrouptitle{##1}{\glsxtr@grptitle}% \glstreePreHeader{##1}{\glsxtr@grptitle}% \par\noindent \glstreegroupheaderfmt {\glsnavhypertarget{##1}{\glsxtr@grptitle}}% - \glstreegroupskip\@afterheading}% + \glstreegroupheaderskip\@afterheading}% } } {} @@ -27298,7 +29507,7 @@ defined}{}% \glsentryitem{##1}\glstreenamefmt{\glstarget{##1}{\glossentryname{##1}}}% \glstreenonamesymbol{##1}% \glstreenonamedesc{##1}% - \glstreeprelocation##2\par + \glstreeDescLoc{##1}{##2}\par }% \renewcommand{\subglossentry}[3]{% \hangindent##1\glstreeindent\relax @@ -27329,7 +29538,7 @@ defined}{}% \glsxtrgetgrouptitle{##1}{\glsxtr@grptitle}% \glstreePreHeader{##1}{\glsxtr@grptitle}% \par\noindent\glstreegroupheaderfmt{\glsxtr@grptitle}% - \glstreegroupskip\@afterheading + \glstreegroupheaderskip\@afterheading }% } } @@ -27346,13 +29555,13 @@ defined}{}% \setglossarystyle{treenoname}% \renewcommand*{\glossaryheader}{% \par\noindent\glstreenavigationfmt{\glsnavigation}% - \glstreegroupskip\@afterheading}% + \glstreegroupheaderskip\@afterheading}% \renewcommand*{\glsgroupheading}[1]{% \glsxtrgetgrouptitle{##1}{\glsxtr@grptitle}% \glstreePreHeader{##1}{\glsxtr@grptitle}% \par\noindent \glstreegroupheaderfmt{\glsnavhypertarget{##1}{\glsxtr@grptitle}}% - \glstreegroupskip\@afterheading}% + \glstreegroupheaderskip\@afterheading}% } } {} @@ -27380,10 +29589,10 @@ defined}{}% \ifglshassymbol{#1}{(\glossentrysymbol{#1})\space}{}% % \end{macrocode} %\changes{1.41}{2019-04-09}{added check for description} +%\changes{1.42}{2020-02-03}{switched to using \cs{glstreeDescLoc}} % \begin{macrocode} - \ifglshasdesc{#1}% - {\glossentrydesc{#1}\glspostdescription\glstreeprelocation}{}% - #2\par + \ifglshasdesc{#1}{\glossentrydesc{#1}\glspostdescription}{}% + \glstreeDescLoc{#1}{#2}\par }% } % \end{macrocode} @@ -28102,8 +30311,6 @@ defined}{}% %after group headings. %\changes{1.21}{2017-11-03}{redefined \texttt{alttreegroup} to discourage %breaks after group headings} -%Can't use \cs{@afterheading} here as it messes with the first item -%of the group. % \begin{macrocode} \ifdef{\@glsstyle@alttreegroup} {% @@ -28116,7 +30323,11 @@ defined}{}% \glsxtrgetgrouptitle{##1}{\glsxtr@grptitle}% \glstreePreHeader{##1}{\glsxtr@grptitle}% \glstreegroupheaderfmt{\glsxtr@grptitle}% - \glstreegroupskip +% \end{macrocode} +%Can't use \cs{@afterheading} here as it messes with the first item +%of the group. +% \begin{macrocode} + \glstreegroupheaderskip }% }% }% @@ -28137,7 +30348,11 @@ defined}{}% \hangindent0pt\relax \parindent0pt\relax \glstreenavigationfmt{\glsnavigation}% - \glstreegroupskip +% \end{macrocode} +%Can't use \cs{@afterheading} here as it messes with the first item +%of the group. +% \begin{macrocode} + \glstreegroupheaderskip }% \renewcommand*{\glsgroupheading}[1]{% \glsxtrgetgrouptitle{##1}{\glsxtr@grptitle}% @@ -28147,7 +30362,11 @@ defined}{}% \hangindent0pt\relax \parindent0pt\relax \glstreegroupheaderfmt{\glsnavhypertarget{##1}{\glsxtr@grptitle}}% - \glstreegroupskip +% \end{macrocode} +%Can't use \cs{@afterheading} here as it messes with the first item +%of the group. +% \begin{macrocode} + \glstreegroupheaderskip }% } }% @@ -28169,7 +30388,7 @@ defined}{}% \glsxtrgetgrouptitle{##1}{\glsxtr@grptitle}% \glstreePreHeader{##1}{\glsxtr@grptitle}% \item\glstreegroupheaderfmt{\glsxtr@grptitle}% - \glstreegroupskip\@afterheading + \glstreegroupheaderskip\@afterheading }% } }% @@ -28186,14 +30405,17 @@ defined}{}% \setglossarystyle{mcolindex}% \renewcommand*{\glossaryheader}{% \item\glstreenavigationfmt{\glsnavigation}% - \glstreegroupskip +% \end{macrocode} +%\changes{1.42}{2020-02-03}{added \cs{@afterheading}} +% \begin{macrocode} + \glstreegroupheaderskip\@afterheading }% \renewcommand*{\glsgroupheading}[1]{% \glsxtrgetgrouptitle{##1}{\glsxtr@grptitle}% \glstreePreHeader{##1}{\glsxtr@grptitle}% \item\glstreegroupheaderfmt {\glsnavhypertarget{##1}{\glsxtr@grptitle}}% - \glstreegroupskip\@afterheading + \glstreegroupheaderskip\@afterheading }% } }% @@ -28220,7 +30442,7 @@ defined}{}% \glstreePreHeader{##1}{\glsxtr@grptitle}% \item\glstreegroupheaderfmt {\glsnavhypertarget{##1}{\glsxtr@grptitle}}% - \glstreegroupskip\@afterheading + \glstreegroupheaderskip\@afterheading }% } }% @@ -28239,7 +30461,7 @@ defined}{}% \glsxtrgetgrouptitle{##1}{\glsxtr@grptitle}% \glstreePreHeader{##1}{\glsxtr@grptitle}% \par\noindent\glstreegroupheaderfmt{\glsxtr@grptitle}% - \glstreegroupskip\@afterheading + \glstreegroupheaderskip\@afterheading }% } }% @@ -28256,14 +30478,14 @@ defined}{}% \setglossarystyle{mcoltree}% \renewcommand*{\glossaryheader}{% \par\noindent\glstreenavigationfmt{\glsnavigation}% - \glstreegroupskip + \glstreegroupheaderskip }% \renewcommand*{\glsgroupheading}[1]{% \glsxtrgetgrouptitle{##1}{\glsxtr@grptitle}% \glstreePreHeader{##1}{\glsxtr@grptitle}% \par\noindent \glstreegroupheaderfmt{\glsnavhypertarget{##1}{\glsxtr@grptitle}}% - \glstreegroupskip\@afterheading + \glstreegroupheaderskip\@afterheading }% } }% @@ -28291,7 +30513,7 @@ defined}{}% \glstreePreHeader{##1}{\glsxtr@grptitle}% \par\noindent \glstreegroupheaderfmt{\glsnavhypertarget{##1}{\glsxtr@grptitle}}% - \glstreegroupskip\@afterheading + \glstreegroupheaderskip\@afterheading }% } }% @@ -28310,7 +30532,7 @@ defined}{}% \glsxtrgetgrouptitle{##1}{\glsxtr@grptitle}% \glstreePreHeader{##1}{\glsxtr@grptitle}% \par\noindent\glstreegroupheaderfmt{\glsxtr@grptitle}% - \glstreegroupskip\@afterheading + \glstreegroupheaderskip\@afterheading }% } }% @@ -28327,14 +30549,14 @@ defined}{}% \setglossarystyle{mcoltreenoname}% \renewcommand*{\glossaryheader}{% \par\noindent\glstreenavigationfmt{\glsnavigation}% - \glstreegroupskip + \glstreegroupheaderskip }% \renewcommand*{\glsgroupheading}[1]{% \glsxtrgetgrouptitle{##1}{\glsxtr@grptitle}% \glstreePreHeader{##1}{\glsxtr@grptitle}% \par\noindent \glstreegroupheaderfmt{\glsnavhypertarget{##1}{\glsxtr@grptitle}}% - \glstreegroupskip\@afterheading}% + \glstreegroupheaderskip\@afterheading}% } }% {% @@ -28361,7 +30583,7 @@ defined}{}% \glstreePreHeader{##1}{\glsxtr@grptitle}% \par\noindent \glstreegroupheaderfmt{\glsnavhypertarget{##1}{\glsxtr@grptitle}}% - \glstreegroupskip\@afterheading}% + \glstreegroupheaderskip\@afterheading}% } }% {% @@ -28405,7 +30627,7 @@ defined}{}% \hangindent0pt\relax \parindent0pt\relax \glstreegroupheaderfmt{\glsxtr@grptitle}% - \glstreegroupskip + \glstreegroupheaderskip }% } }% @@ -28426,7 +30648,7 @@ defined}{}% \hangindent0pt\relax \parindent0pt\relax \glstreenavigationfmt{\glsnavigation}% - \glstreegroupskip + \glstreegroupheaderskip }% \renewcommand*{\glsgroupheading}[1]{% \glsxtrgetgrouptitle{##1}{\glsxtr@grptitle}% @@ -28436,7 +30658,7 @@ defined}{}% \hangindent0pt\relax \parindent0pt\relax \glstreegroupheaderfmt{\glsnavhypertarget{##1}{\glsxtr@grptitle}}% - \glstreegroupskip + \glstreegroupheaderskip }% } }% @@ -28467,7 +30689,7 @@ defined}{}% \hangindent0pt\relax \parindent0pt\relax \glstreegroupheaderfmt{\glsnavhypertarget{##1}{\glsxtr@grptitle}}% - \glstreegroupskip + \glstreegroupheaderskip }% } }% @@ -28497,7 +30719,7 @@ defined}{}% %\section{Package Initialisation and Options} % \begin{macrocode} \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{glossary-bookindex}[2019/04/09 v1.41 (NLCT)] +\ProvidesPackage{glossary-bookindex}[2020/02/13 v1.42 (NLCT)] % \end{macrocode} %Load required packages. % \begin{macrocode} @@ -28681,6 +30903,15 @@ defined}{}% % \end{macrocode} %\end{macro} % +%\begin{macro}{\glsxtrbookindexbookmarkprefix} +%\changes{1.42}{2020-02-03}{new} +%Make the bookmark label prefix used for letter groups depend on the glossary label +%(instead of original hardcoded ``index.''). +% \begin{macrocode} +\newcommand*{\glsxtrbookindexbookmarkprefix}{\currentglossary.} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\glsxtrbookindexcolspread} %\changes{1.21}{2017-11-03}{new} % \begin{macrocode} @@ -28877,7 +31108,7 @@ defined}{}% % \end{macrocode} % Do the PDF bookmark if supported. % \begin{macrocode} - \glsxtrbookindexbookmark{\glsxtrcurrentgrptitle}{index.##1}% + \glsxtrbookindexbookmark{\glsxtrcurrentgrptitle}{\glsxtrbookindexbookmarkprefix##1}% % \end{macrocode} % Format the group title. % \begin{macrocode} @@ -28984,7 +31215,7 @@ defined}{}% %Provides additional long styles. % \begin{macrocode} \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{glossary-longextra}[2019/04/09 v1.41 (NLCT)] +\ProvidesPackage{glossary-longextra}[2020/02/13 v1.42 (NLCT)] % \end{macrocode} %Load required packages. % \begin{macrocode} @@ -30413,7 +32644,7 @@ defined}{}% %topic. % \begin{macrocode} \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{glossary-topic}[2019/04/09 v1.41 (NLCT)] +\ProvidesPackage{glossary-topic}[2020/02/13 v1.42 (NLCT)] % \end{macrocode} %Load required package. % \begin{macrocode} @@ -30676,6 +32907,7 @@ defined}{}% \newcommand*{\glstopicSubNameFont}[1]{\textbf{#1}} % \end{macrocode} %\end{macro} +%\begin{macro}{\glstopicSubPreLocSep} %\changes{1.41}{2019-04-09}{new} % \begin{macrocode} \newcommand*{\glstopicSubPreLocSep}{\space} diff --git a/macros/latex/contrib/glossaries-extra/glossaries-extra.ins b/macros/latex/contrib/glossaries-extra/glossaries-extra.ins index e8bd0d99db..15c23359bc 100644 --- a/macros/latex/contrib/glossaries-extra/glossaries-extra.ins +++ b/macros/latex/contrib/glossaries-extra/glossaries-extra.ins @@ -1,10 +1,10 @@ -% glossaries-extra.ins generated using makedtx version 1.2 2019/4/9 21:59 +% glossaries-extra.ins generated using makedtx version 1.2 2020/2/13 22:19 \input docstrip \preamble glossaries-extra.dtx - Copyright 2019 Nicola Talbot + Copyright 2020 Nicola Talbot This work may be distributed and/or modified under the conditions of the LaTeX Project Public License, either version 1.3 diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-abbr-styles.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-abbr-styles.pdf index 7d04e01e7a..46ac6633fb 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-abbr-styles.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-abbr-styles.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-abbr-styles.tex b/macros/latex/contrib/glossaries-extra/samples/sample-abbr-styles.tex index e123813d21..a5caad77b6 100644 --- a/macros/latex/contrib/glossaries-extra/samples/sample-abbr-styles.tex +++ b/macros/latex/contrib/glossaries-extra/samples/sample-abbr-styles.tex @@ -141,6 +141,10 @@ \testdescstyle{long-short-desc} \testdescstyle{short-long-desc} +%\teststyle{footnote-desc}% synonym: short-footnote-desc +\testdescstyle{short-footnote-desc} +%\teststyle{postfootnote-desc}% synonym: short-postfootnote-desc +\testdescstyle{short-postfootnote-desc} %\testdescstyle{short-desc}% synonym: short-nolong-desc \testdescstyle{short-nolong-desc} \testdescstyle{short-nolong-desc-noreg} @@ -154,12 +158,16 @@ \testdescstyle{short-sc-nolong-desc} \testdescstyle{long-noshort-sc-desc} %\testdescstyle{long-desc-sc}% deprecated synonym of long-noshort-sc-desc +\testdescstyle{short-sc-footnote-desc} +\testdescstyle{short-sc-postfootnote-desc} \testdescstyle{long-short-sm-desc} \testdescstyle{short-sm-long-desc} %\testdescstyle{short-sm-desc}% synonym: short-sm-nolong-desc \testdescstyle{short-sm-nolong-desc} \testdescstyle{long-noshort-sm-desc} %\testdescstyle{long-desc-sm}% deprecated synonym of long-noshort-sm-desc +\testdescstyle{short-sm-footnote-desc} +\testdescstyle{short-sm-postfootnote-desc} \testdescstyle{long-short-em-desc} \testdescstyle{long-em-short-em-desc} \testdescstyle{short-em-long-desc} @@ -168,6 +176,8 @@ \testdescstyle{short-em-nolong-desc} \testdescstyle{long-noshort-em-desc} %\testdescstyle{long-desc-em}% deprecated synonym of long-noshort-em-desc +\testdescstyle{short-em-footnote-desc} +\testdescstyle{short-em-postfootnote-desc} \testdescstyle{long-em-noshort-em-desc} \testdescstyle{long-em-noshort-em-desc-noreg} \testdescstyle{long-short-user-desc} diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-abbrv.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-abbrv.pdf index e85508041d..105622c5b3 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-abbrv.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-abbrv.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-accsupp.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-accsupp.pdf index 51d427f7ca..59d56201f1 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-accsupp.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-accsupp.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-acronym-desc.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-acronym-desc.pdf index a792bef02b..fde058b22a 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-acronym-desc.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-acronym-desc.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-acronym.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-acronym.pdf index 748c73c9cb..834fd8a21c 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-acronym.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-acronym.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-alias.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-alias.pdf index 7254b52a70..0e67a7e656 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-alias.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-alias.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-altmodifier.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-altmodifier.pdf index e0776db2de..6af97621c1 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-altmodifier.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-altmodifier.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-alttree-marginpar.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-alttree-marginpar.pdf index ab853285b4..05e98dd8fd 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-alttree-marginpar.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-alttree-marginpar.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-alttree-sym.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-alttree-sym.pdf index 56d3b3e27d..7872159833 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-alttree-sym.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-alttree-sym.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-alttree.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-alttree.pdf index 36df4991dd..2886317c20 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-alttree.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-alttree.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-autoindex-hyp.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-autoindex-hyp.pdf index 59a5978d4f..a9a5d2ef07 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-autoindex-hyp.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-autoindex-hyp.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-autoindex.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-autoindex.pdf index 93a8d36a55..fe70ab034e 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-autoindex.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-autoindex.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-crossref.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-crossref.pdf index 8429430c25..101f2177b9 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-crossref.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-crossref.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-crossref2.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-crossref2.pdf index be4f0703ab..8d3b894677 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-crossref2.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-crossref2.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-docdef.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-docdef.pdf index 418419a652..f347c9d1ac 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-docdef.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-docdef.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-entrycount.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-entrycount.pdf index 0b032a464c..b98a44c348 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-entrycount.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-entrycount.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-external.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-external.pdf index b598bbe672..111ffbd425 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-external.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-external.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-fmt.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-fmt.pdf index 44b0b88aba..6a80f79529 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-fmt.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-fmt.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-footnote.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-footnote.pdf index ddd2da6376..635649c794 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-footnote.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-footnote.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-header.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-header.pdf index d14b7ac990..989f2abff3 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-header.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-header.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-indexhook.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-indexhook.pdf index 6862cdf5af..661eb97698 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-indexhook.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-indexhook.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-initialisms.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-initialisms.pdf index 70a828f297..529b736db5 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-initialisms.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-initialisms.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-linkcount.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-linkcount.pdf index 6ecfa45889..97f55c724a 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-linkcount.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-linkcount.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-mixed-abbrv-styles.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-mixed-abbrv-styles.pdf index ed38e87d42..2bb22efbc4 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-mixed-abbrv-styles.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-mixed-abbrv-styles.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-mixedsort.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-mixedsort.pdf index 47a2626b99..38618c77ff 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-mixedsort.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-mixedsort.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-mixture.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-mixture.pdf index 3c9208ba08..dc9949c10f 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-mixture.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-mixture.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-name-font.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-name-font.pdf index 83b5b168d8..58b22ff3ec 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-name-font.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-name-font.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-nested.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-nested.pdf index da7a9f2d44..129318d42f 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-nested.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-nested.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-noidx-restricteddocdefs.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-noidx-restricteddocdefs.pdf index d2a571a233..66fef87fc1 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-noidx-restricteddocdefs.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-noidx-restricteddocdefs.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-onelink.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-onelink.pdf index 80898cefa1..dc37111458 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-onelink.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-onelink.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-onthefly-utf8.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-onthefly-utf8.pdf index 1daeb9987c..2f84f3cfac 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-onthefly-utf8.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-onthefly-utf8.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-onthefly-xetex.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-onthefly-xetex.pdf index 98df08cb26..42de4b8284 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-onthefly-xetex.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-onthefly-xetex.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-onthefly.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-onthefly.pdf index 1d60fe8175..69edc38f55 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-onthefly.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-onthefly.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-pages.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-pages.pdf index 97cb891003..f58924d327 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-pages.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-pages.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-postdot.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-postdot.pdf index 5193bfe0bd..eb72d3c9ca 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-postdot.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-postdot.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-postlink.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-postlink.pdf index 7e7448c361..37e3373e60 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-postlink.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-postlink.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-prefix.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-prefix.pdf index 196eeb389b..ccd41032a1 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-prefix.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-prefix.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-record-nameref.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-record-nameref.pdf index 23daf02f3c..06c0982167 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-record-nameref.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-record-nameref.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-record.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-record.pdf index 338bc55bb1..0aa072d73a 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-record.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-record.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-restricteddocdefs.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-restricteddocdefs.pdf index 0662789138..f2eee1be1d 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-restricteddocdefs.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-restricteddocdefs.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-suppl-hyp.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-suppl-hyp.pdf index 67862dfd86..118ce6594c 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-suppl-hyp.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-suppl-hyp.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-suppl-main-hyp.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-suppl-main-hyp.pdf index fd234df18b..95a34c9e53 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-suppl-main-hyp.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-suppl-main-hyp.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-suppl-main.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-suppl-main.pdf index 5ca8b571c0..5aa05dbffd 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-suppl-main.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-suppl-main.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-suppl.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-suppl.pdf index a78c307b62..c5fba24811 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-suppl.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-suppl.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-trans.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-trans.pdf index c7a5afbce6..4a92c2ab8c 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-trans.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-trans.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-undef.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-undef.pdf index f5ce99c373..2bf1f97dd8 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-undef.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-undef.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample-unitentrycount.pdf b/macros/latex/contrib/glossaries-extra/samples/sample-unitentrycount.pdf index 4c397377f0..0c0dda6159 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample-unitentrycount.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample-unitentrycount.pdf differ diff --git a/macros/latex/contrib/glossaries-extra/samples/sample.pdf b/macros/latex/contrib/glossaries-extra/samples/sample.pdf index c5fb78f8f9..4ac0e58c85 100644 Binary files a/macros/latex/contrib/glossaries-extra/samples/sample.pdf and b/macros/latex/contrib/glossaries-extra/samples/sample.pdf differ diff --git a/macros/latex/contrib/glossaries/CHANGES b/macros/latex/contrib/glossaries/CHANGES index b669941078..3149706a90 100644 --- a/macros/latex/contrib/glossaries/CHANGES +++ b/macros/latex/contrib/glossaries/CHANGES @@ -1,5 +1,52 @@ glossaries change log: +v4.45 (2020-02-13): + + * glossaries-accsupp.sty: + + - new associated accessibility keys for the user fields + + - new commands: \glsaccessibility, \glsfieldaccsupp, \xglsfieldaccsupp, + \glsshortaccsupp, \glsshortplaccsupp (determine Alt/ActualText/E + according to the field) + + - added accessibility support to \glstext, \glsplural, \glsfirst, + \glsfirstplural, \glssymbol, \glsname, \glsdesc, + \glsdescplural, \glsuseri, \glsuserii, \glsuseriii, \glsuseriv, + \glsuserv, \glsuservi and their case variants + + - bug fixes: + + - added field existence checks for \gls...accessdisplay commands + + - removed symbol use backward compatibility as it causes + interference + + * glossaries-prefix.sty: + + - new command \glsprefixsep + + * glossaries.sty: + + - new package options: + + disablemakegloss + restoremakegloss + writeglslabels + + - package option debug now also accepts value 'showaccsupp' + + - detokenize label before passing to \glsshowtarget + + - new commands: \glsentryparent, \glsshowtargetouter and \glsshowtargetfont + + - made robust: \ifglshaschildren, \ifglshassymbol, \ifglshaslong, + \ifglshasshort, \ifglshasfield + + - Bug fix: + + - added existence check to \glsentrytitlecase + v4.44 (2019-12-06): * glossaries-prefix.sty: diff --git a/macros/latex/contrib/glossaries/INSTALL b/macros/latex/contrib/glossaries/INSTALL index e9ba724de8..f966ec2d29 100644 --- a/macros/latex/contrib/glossaries/INSTALL +++ b/macros/latex/contrib/glossaries/INSTALL @@ -1,8 +1,8 @@ INSTALLATION -The best method of installing is through your TeX package -manager, but if you need to use the manual method for some -reason, follow the instructions below. +The best (and recommended) method of installing is through your TeX package +manager (for example, `tlmgr install glossaries`), but if you need to use +the manual method for some reason, follow the instructions below. If you have downloaded the glossaries package using the TeX Directory Structure (TDS), that is you have downloaded the archive diff --git a/macros/latex/contrib/glossaries/README b/macros/latex/contrib/glossaries/README deleted file mode 100644 index cbf39bc988..0000000000 --- a/macros/latex/contrib/glossaries/README +++ /dev/null @@ -1,81 +0,0 @@ -LaTeX Package : glossaries v4.44 - -Last Modified : 2019-12-06 - -Author : Nicola Talbot - -Package FAQ : http://www.dickimaw-books.com/faqs/glossariesfaq.html - -This package is provided to assist generating glossaries. -The package supports abbreviations and multiple glossaries. -New entries are defined to have a name and description (and -optionally an associated symbol). Plural forms can also be -specified. New glossary styles can be defined, and preambles -and postambles can be specified. There is provision for loading -a database of terms, only terms used in the text will be added -to the relevant glossary. - -*This package replaces the glossary package which is now obsolete.* - -glossaries-accsupp.sty is an experimental package that uses the -accsupp package to provide accessibility support for the -glossaries package. - -The glossaries package may be extended with the -separately-distributed glossaries-extra package -(https://ctan.org/pkg/glossaries-extra), which provides -more options and improved abbreviation handling. - -The mfirstuc package is now a separate bundle -(https://ctan.org/pkg/mfirstuc). - -INSTALLATION - -See INSTALL file for installation instructions. - -REQUIREMENTS - -mfirstuc -ifthen -xkeyval *at least version 2.5f (2006/11/18)* -xfor -amsgen -etoolbox -longtable (unless you use the nolong or nostyles package options) -datatool-base -textcase -tracklang (to determine if any language modules need to be loaded) - -If the supertabular package is installed, it will also be loaded -unless the nosuper or nostyles package options are used. If the -supertabular package isn't installed, you can still use the -glossaries package, but you won't be able to use any of the styles -defined in glossaries-super.sty. If you want to use -glossary-longragged.sty or glossary-superragged.sty you will also -need the array package. If you want to use glossary-mcols you will -also need the multicol package. - -Note that the current version of the glossaries package doesn't -load xspace. - -If you want to use the experimental glossaries-accsupp.sty -you will also need the accsupp package. - -LaTeX2HTML - -This package comes with a LaTeX2HTML style file glossaries.perl -which should be placed in the relevant LaTeX2HTML -styles directory, but note that these styles only supply a sub-set -of the commands provided by glossaries.sty, so some -commands may not be implemented or may be implemented in a different -way. This file has not be tested with recent versions of -LaTeX2HTML and may no longer be compatible. - -LICENCE - -This material is subject to the LaTeX Project Public License. -See http://www.ctan.org/license/lppl1.3 -for the details of that license. - -Author's home page: http://www.dickimaw-books.com/ - diff --git a/macros/latex/contrib/glossaries/README.md b/macros/latex/contrib/glossaries/README.md new file mode 100644 index 0000000000..ccb9d83969 --- /dev/null +++ b/macros/latex/contrib/glossaries/README.md @@ -0,0 +1,128 @@ +# glossaries v4.45 (2020-02-13) + +Author: Nicola Talbot ([contact](http://www.dickimaw-books.com/contact)) + +## LICENCE + +This material is subject to the LaTeX Project Public License. +See http://www.ctan.org/license/lppl1.3 +for the details of that license. + +Copyright 2007-2020 Nicola Talbot + +## DESCRIPTION + +This package is provided to assist generating glossaries. +The package supports abbreviations and multiple glossaries. +New entries are defined to have a name and description (and +optionally an associated symbol). Plural forms can also be +specified. New glossary styles can be defined, and preambles +and postambles can be specified. There is provision for loading +a database of terms where only terms used in the text will be added +to the relevant glossary. + +*This package replaces the glossary package which is now obsolete.* + +### Included supplementary files: + + - glossaries-prefix.sty: allows for the inclusion of a prefix (such + as a determiner) before terms. + + - glossaries-accsupp.sty: an experimental package that uses the + [accsupp](https://ctan.org/pkg/accsupp) package to + provide accessibility support for the glossaries package. + + - glossary style packages (such as glossary-list.sty and + glossary-index.sty). Note that the list styles may be incompatible with + classes or packages that redefine the `description` environment. + + - a set of files containing lorem ipsum dummy entries for testing + and debugging. + +### Excluded supplementary packages (separate installation required): + + - language support packages, + e.g. [glossaries-english.sty](https://ctan.org/pkg/glossaries-english). + + - [glossaries-extra.sty](https://ctan.org/pkg/glossaries-extra) extends + glossaries.sty, providing more options and better abbreviation handling. + + - [bib2gls](https://ctan.org/pkg/bib2gls) alternative indexing + application designed specifically for use with glossaries-extra.sty + +## RELATED MATERIAL + + - [Package FAQ](http://www.dickimaw-books.com/faqs/glossariesfaq.html) + + - [Bug tracker](https://www.dickimaw-books.com/bugtracker.php?category=glossaries) + + - [Gallery](https://www.dickimaw-books.com/gallery/#glossaries) + + - [Document Build Advice](https://www.dickimaw-books.com/latex/buildglossaries/) + +## INSTALLATION + +The best and recommended method is through your TeX package manager, +otherwise see INSTALL file for installation instructions. + +To test your installation, compile `minimalgls.tex` which is provided +with the sample files: + +```bash +pdflatex minimalgls +makeglossaries minimalgls +pdflatex minimalgls +``` +or (if you don't have Perl installed): + +```bash +pdflatex minimalgls +makeglossaries-lite minimalgls +pdflatex minimalgls +``` + +## REQUIREMENTS + + - amsgen + - datatool-base + - etoolbox + - ifthen + - mfirstuc + - textcase + - tracklang + - xfor + - xkeyval *at least version 2.5f (2006/11/18)* + +If you want to use glossaries-accsupp.sty you will also need the accsupp package. + +Some of the glossary styles require additional packages, which are +automatically loaded by the corresponding `glossary-`*name*`.sty` +package. + + - The `long` styles require longtable.sty. + + - The `super` styles require supertabular.sty. + + - The `ragged` styles required array.sty. + + - The `mcols` styles require multicol.sty. + + - The `booktab` styles require booktabs.sty. + +If you want to use the `sm` acronym styles you will also need +relsizes.sty. This needs to be explicitly loaded in your document if +required. + +If you want to use `\oldacronym` with `\xspace` you will also need +xspace.sty. This needs to be explicitly loaded in your document if +required. (Not recommended.) + +## LaTeX2HTML + +This package comes with a LaTeX2HTML style file glossaries.perl +which should be placed in the relevant LaTeX2HTML +styles directory, but note that this style only supplies a sub-set +of the commands provided by glossaries.sty, so some +commands may not be implemented or may be implemented in a different +way. This file has not be tested with recent versions of +LaTeX2HTML and may no longer be compatible. diff --git a/macros/latex/contrib/glossaries/glossaries-code.pdf b/macros/latex/contrib/glossaries/glossaries-code.pdf index 6cadc9faf1..b6168ca4e4 100644 Binary files a/macros/latex/contrib/glossaries/glossaries-code.pdf and b/macros/latex/contrib/glossaries/glossaries-code.pdf differ diff --git a/macros/latex/contrib/glossaries/glossaries-user.html b/macros/latex/contrib/glossaries/glossaries-user.html index 66646c2c86..abe7f89e46 100644 --- a/macros/latex/contrib/glossaries/glossaries-user.html +++ b/macros/latex/contrib/glossaries/glossaries-user.html @@ -45,17 +45,11 @@ .cmssbx-10{ font-family: sans-serif; font-weight: bold;} .cmssbx-10{ font-family: sans-serif; font-weight: bold;} .cmr-9{font-size:90%;} -.tcrm-0800{font-size:80%;} .cmtt-8{font-size:80%;font-family: monospace;} .cmtt-8{font-family: monospace;} .cmtt-8{font-family: monospace;} .cmtt-8{font-family: monospace;} .cmtt-8{font-family: monospace;} -.cmss-8{font-size:80%; font-family: sans-serif;} -.cmss-8{ font-family: sans-serif;} -.cmss-8{ font-family: sans-serif;} -.cmss-8{ font-family: sans-serif;} -.cmss-8{ font-family: sans-serif;} .cmtt-9{font-size:90%;font-family: monospace;} .cmtt-9{font-family: monospace;} .cmtt-9{font-family: monospace;} @@ -70,20 +64,28 @@ .cmmi-9{font-size:90%;font-style: italic;} .msam-10x-x-90{font-size:90%;} .pzdr-x-x-90{font-size:90%;} +.cmss-8{font-size:80%; font-family: sans-serif;} +.cmss-8{ font-family: sans-serif;} +.cmss-8{ font-family: sans-serif;} +.cmss-8{ font-family: sans-serif;} +.cmss-8{ font-family: sans-serif;} .cmbx-12{font-size:120%; font-weight: bold;} .cmbx-12{ font-weight: bold;} +.tctt-1000{font-family: monospace;} +.cmti-8{font-size:80%; font-style: italic;} .cmitt-10{font-family: monospace; font-style: italic;} +.cmssi-10{ font-family: sans-serif; font-style: oblique;} +.cmssi-10{ font-family: sans-serif; font-style: oblique;} +.cmssi-10{ font-family: sans-serif; font-style: oblique;} +.cmssi-10{ font-family: sans-serif; font-style: oblique;} +.cmssi-10{ font-family: sans-serif; font-style: oblique;} .cmbxti-10{ font-weight: bold; font-style: italic;} -.cmssbx-10x-x-120{font-size:120%; font-family: sans-serif; font-weight: bold;} -.cmssbx-10x-x-120{ font-family: sans-serif; font-weight: bold;} -.cmssbx-10x-x-120{ font-family: sans-serif; font-weight: bold;} -.cmssbx-10x-x-120{ font-family: sans-serif; font-weight: bold;} -.cmssbx-10x-x-120{ font-family: sans-serif; font-weight: bold;} .small-caps{font-variant: small-caps; } -p.noindent { text-indent: 0em } -td p.noindent { text-indent: 0em; margin-top:0em; } -p.nopar { text-indent: 0em; } -p.indent{ text-indent: 1.5em } +p{margin-top:0;margin-bottom:0} +p.indent{text-indent:0;} +p + p{margin-top:1em;} +p + div, p + pre {margin-top:1em;} +div + p, pre + p {margin-top:1em;} @media print {div.crosslinks {visibility:hidden;}} a img { border-top: 0; border-left: 0; border-right: 0; } center { margin-top:1em; margin-bottom:1em; } @@ -106,7 +108,7 @@ div.obeylines-v p { margin-top:0; margin-bottom:0; } td.displaylines {text-align:center; white-space:nowrap;} .centerline {text-align:center;} .rightline {text-align:right;} -div.verbatim {font-family: monospace; white-space: nowrap; text-align:left; clear:both; } +div.verbatim {font-family: monospace,monospace; white-space: nowrap; text-align:left; clear:both; } .fbox {padding-left:3.0pt; padding-right:3.0pt; text-indent:0pt; border:solid black 0.4pt; } div.fbox {display:table} div.center div.fbox {text-align:center; clear:both; padding-left:3.0pt; padding-right:3.0pt; text-indent:0pt; border:solid black 0.4pt; } @@ -231,70 +233,1063 @@ table[rules] {border-left:solid black 0.4pt; border-right:solid black 0.4pt; } div.longtable{text-align:center;} table.longtable{margin-left:auto; margin-right: auto;} .supertabular {text-align:center} +pre.prompt {color: white; background: black; font-weight: bold; padding-bottom: 2ex; padding-left: 1em; padding-right: 1em;} +.warningsymbol { color: red; font-weight: bold;} div.important { border : solid red; } div.verbatim { font-family: monospace; white-space: nowrap; text-align:left; clear:both; padding-top: 2ex; padding-bottom: 2ex;} -span#textcolor1{color:#00FF00} -span#textcolor2{color:#00FF00} -span#textcolor3{color:#00FF00} -span#textcolor4{color:#FF0000} -span#textcolor5{color:#FF0000} -span#textcolor6{color:#00FF00} -span#textcolor7{color:#FF0000} -span#textcolor8{color:#FF0000} -span#textcolor9{color:#FF0000} -span#textcolor10{color:#00FF00} -span#textcolor11{color:#00FF00} -span#textcolor12{color:#00FF00} -span#textcolor13{color:#FF0000} -span#textcolor14{color:#00FF00} -span#textcolor15{color:#00FF00} +span#textcolor1{color:#008080} +span#textcolor2{color:#008080} +span#textcolor4{color:#008080} +span#textcolor5{color:#008080} +span#textcolor6{color:#008080} +span#textcolor7{color:#008080} +span#textcolor8{color:#008080} +span#textcolor9{color:#008080} +span#textcolor10{color:#008080} +span#textcolor11{color:#008080} +span#textcolor12{color:#008080} +span#textcolor13{color:#008080} +span#textcolor14{color:#008080} +span#textcolor15{color:#008080} span#textcolor16{color:#00FF00} span#textcolor17{color:#00FF00} span#textcolor18{color:#00FF00} span#textcolor19{color:#FF0000} -span#textcolor20{color:#00FF00} -span#textcolor21{color:#FF0000} +span#textcolor20{color:#FF0000} +span#textcolor21{color:#00FF00} span#textcolor22{color:#FF0000} -span#textcolor23{color:#00FF00} -span#textcolor24{color:#00FF00} -span#textcolor25{color:#FF0000} +span#textcolor23{color:#FF0000} +span#textcolor24{color:#FF0000} +span#textcolor25{color:#00FF00} span#textcolor26{color:#00FF00} span#textcolor27{color:#00FF00} -span#textcolor28{color:#00FF00} +span#textcolor28{color:#FF0000} span#textcolor29{color:#00FF00} -span#textcolor30{color:#FF0000} -span#textcolor31{color:#FF0000} +span#textcolor30{color:#00FF00} +span#textcolor31{color:#00FF00} span#textcolor32{color:#00FF00} -span#textcolor33{color:#FF0000} +span#textcolor33{color:#00FF00} span#textcolor34{color:#FF0000} -span#textcolor35{color:#FF0000} -span#textcolor36{color:#00FF00} -span#textcolor37{color:#00FF00} +span#textcolor35{color:#00FF00} +span#textcolor36{color:#FF0000} +span#textcolor37{color:#FF0000} span#textcolor38{color:#00FF00} span#textcolor39{color:#00FF00} span#textcolor40{color:#FF0000} span#textcolor41{color:#00FF00} span#textcolor42{color:#00FF00} -span#textcolor43{color:#FF0000} +span#textcolor43{color:#00FF00} span#textcolor44{color:#00FF00} -span#textcolor45{color:#00FF00} -span#textcolor46{color:#00FF00} -span#textcolor47{color:#FF0000} -span#textcolor48{color:#00FF00} +span#textcolor45{color:#FF0000} +span#textcolor46{color:#FF0000} +span#textcolor47{color:#00FF00} +span#textcolor48{color:#FF0000} span#textcolor49{color:#FF0000} -span#textcolor50{color:#00FF00} +span#textcolor50{color:#FF0000} span#textcolor51{color:#00FF00} span#textcolor52{color:#00FF00} span#textcolor53{color:#00FF00} -span#textcolor54{color:#FF0000} +span#textcolor54{color:#00FF00} span#textcolor55{color:#FF0000} span#textcolor56{color:#00FF00} -span#textcolor57{color:#FF0000} -span#textcolor58{color:#00FF00} -span#textcolor59{color:#FF0000} -span#textcolor60{color:#FF0000} +span#textcolor57{color:#00FF00} +span#textcolor58{color:#FF0000} +span#textcolor59{color:#00FF00} +span#textcolor60{color:#00FF00} span#textcolor61{color:#00FF00} -span#textcolor62{color:#00FF00} +span#textcolor62{color:#FF0000} +span#textcolor63{color:#00FF00} +span#textcolor64{color:#FF0000} +span#textcolor65{color:#00FF00} +span#textcolor66{color:#00FF00} +span#textcolor67{color:#00FF00} +span#textcolor68{color:#00FF00} +span#textcolor69{color:#FF0000} +span#textcolor70{color:#FF0000} +span#textcolor71{color:#00FF00} +span#textcolor72{color:#FF0000} +span#textcolor73{color:#00FF00} +span#textcolor74{color:#FF0000} +span#textcolor75{color:#FF0000} +span#textcolor76{color:#00FF00} +span#textcolor77{color:#00FF00} +span#textcolor78{color:#008080} +span#textcolor79{color:#008080} +span#textcolor80{color:#008080} +span#textcolor81{color:#008080} +span#textcolor82{color:#008080} +span#textcolor83{color:#008080} +span#textcolor84{color:#008080} +span#textcolor85{color:#008080} +span#textcolor86{color:#008080} +span#textcolor87{color:#008080} +span#textcolor88{color:#008080} +span#textcolor89{color:#008080} +span#textcolor90{color:#008080} +span#textcolor91{color:#008080} +span#textcolor92{color:#008080} +span#textcolor93{color:#008080} +span#textcolor94{color:#008080} +span#textcolor95{color:#008080} +span#textcolor96{color:#008080} +span#textcolor97{color:#008080} +span#textcolor98{color:#008080} +span#textcolor99{color:#008080} +span#textcolor100{color:#008080} +span#textcolor101{color:#008080} +span#textcolor102{color:#008080} +span#textcolor103{color:#008080} +span#textcolor104{color:#008080} +span#textcolor105{color:#008080} +span#textcolor106{color:#008080} +span#textcolor107{color:#008080} +span#textcolor108{color:#008080} +span#textcolor109{color:#008080} +span#textcolor110{color:#008080} +span#textcolor111{color:#008080} +span#textcolor112{color:#008080} +span#textcolor113{color:#008080} +span#textcolor114{color:#008080} +span#textcolor115{color:#008080} +span#textcolor116{color:#008080} +span#textcolor117{color:#008080} +span#textcolor118{color:#008080} +span#textcolor119{color:#008080} +span#textcolor120{color:#008080} +span#textcolor121{color:#008080} +span#textcolor122{color:#008080} +span#textcolor123{color:#008080} +span#textcolor124{color:#008080} +span#textcolor125{color:#008080} +span#textcolor126{color:#008080} +span#textcolor127{color:#008080} +span#textcolor128{color:#008080} +span#textcolor129{color:#008080} +span#textcolor130{color:#008080} +span#textcolor131{color:#008080} +span#textcolor132{color:#008080} +span#textcolor133{color:#008080} +span#textcolor134{color:#008080} +span#textcolor135{color:#008080} +span#textcolor136{color:#008080} +span#textcolor137{color:#008080} +span#textcolor138{color:#008080} +span#textcolor139{color:#008080} +span#textcolor140{color:#008080} +span#textcolor141{color:#008080} +span#textcolor142{color:#008080} +span#textcolor143{color:#008080} +span#textcolor144{color:#008080} +span#textcolor145{color:#008080} +span#textcolor146{color:#008080} +span#textcolor147{color:#008080} +span#textcolor148{color:#008080} +span#textcolor149{color:#008080} +span#textcolor150{color:#008080} +span#textcolor151{color:#008080} +span#textcolor152{color:#008080} +span#textcolor153{color:#008080} +span#textcolor154{color:#008080} +span#textcolor155{color:#008080} +span#textcolor156{color:#008080} +span#textcolor157{color:#008080} +span#textcolor158{color:#008080} +span#textcolor159{color:#008080} +span#textcolor160{color:#008080} +span#textcolor161{color:#008080} +span#textcolor162{color:#008080} +span#textcolor163{color:#008080} +span#textcolor164{color:#008080} +span#textcolor165{color:#008080} +span#textcolor166{color:#008080} +span#textcolor167{color:#008080} +span#textcolor168{color:#008080} +span#textcolor169{color:#008080} +span#textcolor170{color:#008080} +span#textcolor171{color:#008080} +span#textcolor172{color:#008080} +span#textcolor173{color:#008080} +span#textcolor174{color:#008080} +span#textcolor175{color:#008080} +span#textcolor176{color:#008080} +span#textcolor177{color:#008080} +span#textcolor178{color:#008080} +span#textcolor179{color:#008080} +span#textcolor180{color:#008080} +span#textcolor181{color:#008080} +span#textcolor182{color:#008080} +span#textcolor183{color:#008080} +span#textcolor184{color:#008080} +span#textcolor185{color:#008080} +span#textcolor186{color:#008080} +span#textcolor187{color:#008080} +span#textcolor188{color:#008080} +span#textcolor189{color:#008080} +span#textcolor190{color:#008080} +span#textcolor191{color:#008080} +span#textcolor192{color:#008080} +span#textcolor193{color:#008080} +span#textcolor194{color:#008080} +span#textcolor195{color:#008080} +span#textcolor196{color:#008080} +span#textcolor197{color:#008080} +span#textcolor198{color:#008080} +span#textcolor199{color:#008080} +span#textcolor200{color:#008080} +span#textcolor201{color:#008080} +span#textcolor202{color:#008080} +span#textcolor203{color:#008080} +span#textcolor204{color:#008080} +span#textcolor205{color:#008080} +span#textcolor206{color:#008080} +span#textcolor207{color:#008080} +span#textcolor208{color:#008080} +span#textcolor209{color:#008080} +span#textcolor210{color:#008080} +span#textcolor211{color:#008080} +span#textcolor212{color:#008080} +span#textcolor213{color:#008080} +span#textcolor214{color:#008080} +span#textcolor215{color:#008080} +span#textcolor216{color:#008080} +span#textcolor217{color:#008080} +span#textcolor218{color:#008080} +span#textcolor219{color:#008080} +span#textcolor220{color:#008080} +span#textcolor221{color:#008080} +span#textcolor222{color:#008080} +span#textcolor223{color:#008080} +span#textcolor224{color:#008080} +span#textcolor225{color:#008080} +span#textcolor226{color:#008080} +span#textcolor227{color:#008080} +span#textcolor228{color:#008080} +span#textcolor229{color:#008080} +span#textcolor230{color:#008080} +span#textcolor231{color:#008080} +span#textcolor232{color:#008080} +span#textcolor233{color:#008080} +span#textcolor234{color:#008080} +span#textcolor235{color:#008080} +span#textcolor236{color:#008080} +span#textcolor237{color:#008080} +span#textcolor238{color:#008080} +span#textcolor239{color:#008080} +span#textcolor240{color:#008080} +span#textcolor241{color:#008080} +span#textcolor242{color:#008080} +span#textcolor243{color:#008080} +span#textcolor244{color:#008080} +span#textcolor245{color:#008080} +span#textcolor246{color:#008080} +span#textcolor247{color:#008080} +span#textcolor248{color:#008080} +span#textcolor249{color:#008080} +span#textcolor250{color:#008080} +span#textcolor251{color:#008080} +span#textcolor252{color:#008080} +span#textcolor253{color:#008080} +span#textcolor254{color:#008080} +span#textcolor255{color:#008080} +span#textcolor256{color:#008080} +span#textcolor257{color:#008080} +span#textcolor258{color:#008080} +span#textcolor259{color:#008080} +span#textcolor260{color:#008080} +span#textcolor261{color:#008080} +span#textcolor262{color:#008080} +span#textcolor263{color:#008080} +span#textcolor264{color:#008080} +span#textcolor265{color:#008080} +span#textcolor266{color:#008080} +span#textcolor267{color:#008080} +span#textcolor268{color:#008080} +span#textcolor269{color:#008080} +span#textcolor270{color:#008080} +span#textcolor271{color:#008080} +span#textcolor272{color:#008080} +span#textcolor273{color:#008080} +span#textcolor274{color:#008080} +span#textcolor275{color:#008080} +span#textcolor276{color:#008080} +span#textcolor277{color:#008080} +span#textcolor278{color:#008080} +span#textcolor279{color:#008080} +span#textcolor280{color:#008080} +span#textcolor281{color:#008080} +span#textcolor282{color:#008080} +span#textcolor283{color:#008080} +span#textcolor284{color:#008080} +span#textcolor285{color:#008080} +span#textcolor286{color:#008080} +span#textcolor287{color:#008080} +span#textcolor288{color:#008080} +span#textcolor289{color:#008080} +span#textcolor290{color:#008080} +span#textcolor291{color:#008080} +span#textcolor292{color:#008080} +span#textcolor293{color:#008080} +span#textcolor294{color:#008080} +span#textcolor295{color:#008080} +span#textcolor296{color:#008080} +span#textcolor297{color:#008080} +span#textcolor298{color:#008080} +span#textcolor299{color:#008080} +span#textcolor300{color:#008080} +span#textcolor301{color:#008080} +span#textcolor302{color:#008080} +span#textcolor303{color:#008080} +span#textcolor304{color:#008080} +span#textcolor305{color:#008080} +span#textcolor306{color:#008080} +span#textcolor307{color:#008080} +span#textcolor308{color:#008080} +span#textcolor309{color:#008080} +span#textcolor310{color:#008080} +span#textcolor311{color:#008080} +span#textcolor312{color:#008080} +span#textcolor313{color:#008080} +span#textcolor314{color:#008080} +span#textcolor315{color:#008080} +span#textcolor316{color:#008080} +span#textcolor317{color:#008080} +span#textcolor318{color:#008080} +span#textcolor319{color:#008080} +span#textcolor320{color:#008080} +span#textcolor321{color:#008080} +span#textcolor322{color:#008080} +span#textcolor323{color:#008080} +span#textcolor324{color:#008080} +span#textcolor325{color:#008080} +span#textcolor326{color:#008080} +span#textcolor327{color:#008080} +span#textcolor328{color:#008080} +span#textcolor329{color:#008080} +span#textcolor330{color:#008080} +span#textcolor331{color:#008080} +span#textcolor332{color:#008080} +span#textcolor333{color:#008080} +span#textcolor334{color:#008080} +span#textcolor335{color:#008080} +span#textcolor336{color:#008080} +span#textcolor337{color:#008080} +span#textcolor338{color:#008080} +span#textcolor339{color:#008080} +span#textcolor340{color:#008080} +span#textcolor341{color:#008080} +span#textcolor342{color:#008080} +span#textcolor343{color:#008080} +span#textcolor344{color:#008080} +span#textcolor345{color:#008080} +span#textcolor346{color:#008080} +span#textcolor347{color:#008080} +span#textcolor348{color:#008080} +span#textcolor349{color:#008080} +span#textcolor350{color:#008080} +span#textcolor351{color:#008080} +span#textcolor352{color:#008080} +span#textcolor353{color:#008080} +span#textcolor354{color:#008080} +span#textcolor355{color:#008080} +span#textcolor356{color:#008080} +span#textcolor357{color:#008080} +span#textcolor358{color:#008080} +span#textcolor359{color:#008080} +span#textcolor360{color:#008080} +span#textcolor361{color:#008080} +span#textcolor362{color:#008080} +span#textcolor363{color:#008080} +span#textcolor364{color:#008080} +span#textcolor365{color:#008080} +span#textcolor366{color:#008080} +span#textcolor367{color:#008080} +span#textcolor368{color:#008080} +span#textcolor369{color:#008080} +span#textcolor370{color:#008080} +span#textcolor371{color:#008080} +span#textcolor372{color:#008080} +span#textcolor373{color:#008080} +span#textcolor374{color:#008080} +span#textcolor375{color:#008080} +span#textcolor376{color:#008080} +span#textcolor377{color:#008080} +span#textcolor378{color:#008080} +span#textcolor379{color:#008080} +span#textcolor380{color:#008080} +span#textcolor381{color:#008080} +span#textcolor382{color:#008080} +span#textcolor383{color:#008080} +span#textcolor384{color:#008080} +span#textcolor385{color:#008080} +span#textcolor386{color:#008080} +span#textcolor387{color:#008080} +span#textcolor388{color:#008080} +span#textcolor389{color:#008080} +span#textcolor390{color:#008080} +span#textcolor391{color:#008080} +span#textcolor392{color:#008080} +span#textcolor393{color:#008080} +span#textcolor394{color:#008080} +span#textcolor395{color:#008080} +span#textcolor396{color:#008080} +span#textcolor397{color:#008080} +span#textcolor398{color:#008080} +span#textcolor399{color:#008080} +span#textcolor400{color:#008080} +span#textcolor401{color:#008080} +span#textcolor402{color:#008080} +span#textcolor403{color:#008080} +span#textcolor404{color:#008080} +span#textcolor405{color:#008080} +span#textcolor406{color:#008080} +span#textcolor407{color:#008080} +span#textcolor408{color:#008080} +span#textcolor409{color:#008080} +span#textcolor410{color:#008080} +span#textcolor411{color:#008080} +span#textcolor412{color:#008080} +span#textcolor413{color:#008080} +span#textcolor414{color:#008080} +span#textcolor415{color:#008080} +span#textcolor416{color:#008080} +span#textcolor417{color:#008080} +span#textcolor418{color:#008080} +span#textcolor419{color:#008080} +span#textcolor420{color:#008080} +span#textcolor421{color:#008080} +span#textcolor422{color:#008080} +span#textcolor423{color:#008080} +span#textcolor424{color:#008080} +span#textcolor425{color:#008080} +span#textcolor426{color:#008080} +span#textcolor427{color:#008080} +span#textcolor428{color:#008080} +span#textcolor429{color:#008080} +span#textcolor430{color:#008080} +span#textcolor431{color:#008080} +span#textcolor432{color:#008080} +span#textcolor433{color:#008080} +span#textcolor434{color:#008080} +span#textcolor435{color:#008080} +span#textcolor436{color:#008080} +span#textcolor437{color:#008080} +span#textcolor438{color:#008080} +span#textcolor439{color:#008080} +span#textcolor440{color:#008080} +span#textcolor441{color:#008080} +span#textcolor442{color:#008080} +span#textcolor443{color:#008080} +span#textcolor444{color:#008080} +span#textcolor445{color:#008080} +span#textcolor446{color:#008080} +span#textcolor447{color:#008080} +span#textcolor448{color:#008080} +span#textcolor449{color:#008080} +span#textcolor450{color:#008080} +span#textcolor451{color:#008080} +span#textcolor452{color:#008080} +span#textcolor453{color:#008080} +span#textcolor454{color:#008080} +span#textcolor455{color:#008080} +span#textcolor456{color:#008080} +span#textcolor457{color:#008080} +span#textcolor458{color:#008080} +span#textcolor459{color:#008080} +span#textcolor460{color:#008080} +span#textcolor461{color:#008080} +span#textcolor462{color:#008080} +span#textcolor463{color:#008080} +span#textcolor464{color:#008080} +span#textcolor465{color:#008080} +span#textcolor466{color:#008080} +span#textcolor467{color:#008080} +span#textcolor468{color:#008080} +span#textcolor469{color:#008080} +span#textcolor470{color:#008080} +span#textcolor471{color:#008080} +span#textcolor472{color:#008080} +span#textcolor473{color:#008080} +span#textcolor474{color:#008080} +span#textcolor475{color:#008080} +span#textcolor476{color:#008080} +span#textcolor477{color:#008080} +span#textcolor478{color:#008080} +span#textcolor479{color:#008080} +span#textcolor480{color:#008080} +span#textcolor481{color:#008080} +span#textcolor482{color:#008080} +span#textcolor483{color:#008080} +span#textcolor484{color:#008080} +span#textcolor485{color:#008080} +span#textcolor486{color:#008080} +span#textcolor487{color:#008080} +span#textcolor488{color:#008080} +span#textcolor489{color:#008080} +span#textcolor490{color:#008080} +span#textcolor491{color:#008080} +span#textcolor492{color:#008080} +span#textcolor493{color:#008080} +span#textcolor494{color:#008080} +span#textcolor495{color:#008080} +span#textcolor496{color:#008080} +span#textcolor497{color:#008080} +span#textcolor498{color:#008080} +span#textcolor499{color:#008080} +span#textcolor500{color:#008080} +span#textcolor501{color:#008080} +span#textcolor502{color:#008080} +span#textcolor503{color:#008080} +span#textcolor504{color:#008080} +span#textcolor505{color:#008080} +span#textcolor506{color:#008080} +span#textcolor507{color:#008080} +span#textcolor508{color:#008080} +span#textcolor509{color:#008080} +span#textcolor510{color:#008080} +span#textcolor511{color:#008080} +span#textcolor512{color:#008080} +span#textcolor513{color:#008080} +span#textcolor514{color:#008080} +span#textcolor515{color:#008080} +span#textcolor516{color:#008080} +span#textcolor517{color:#008080} +span#textcolor518{color:#008080} +span#textcolor519{color:#008080} +span#textcolor520{color:#008080} +span#textcolor521{color:#008080} +span#textcolor522{color:#008080} +span#textcolor523{color:#008080} +span#textcolor524{color:#008080} +span#textcolor525{color:#008080} +span#textcolor526{color:#008080} +span#textcolor527{color:#008080} +span#textcolor528{color:#008080} +span#textcolor529{color:#008080} +span#textcolor530{color:#008080} +span#textcolor531{color:#008080} +span#textcolor532{color:#008080} +span#textcolor533{color:#008080} +span#textcolor534{color:#008080} +span#textcolor535{color:#008080} +span#textcolor536{color:#008080} +span#textcolor537{color:#008080} +span#textcolor538{color:#008080} +span#textcolor539{color:#008080} +span#textcolor540{color:#008080} +span#textcolor541{color:#008080} +span#textcolor542{color:#008080} +span#textcolor543{color:#008080} +span#textcolor544{color:#008080} +span#textcolor545{color:#008080} +span#textcolor546{color:#008080} +span#textcolor547{color:#008080} +span#textcolor548{color:#008080} +span#textcolor549{color:#008080} +span#textcolor550{color:#008080} +span#textcolor551{color:#008080} +span#textcolor552{color:#008080} +span#textcolor553{color:#008080} +span#textcolor554{color:#008080} +span#textcolor555{color:#008080} +span#textcolor556{color:#008080} +span#textcolor557{color:#008080} +span#textcolor558{color:#008080} +span#textcolor559{color:#008080} +span#textcolor560{color:#008080} +span#textcolor561{color:#008080} +span#textcolor562{color:#008080} +span#textcolor563{color:#008080} +span#textcolor564{color:#008080} +span#textcolor565{color:#008080} +span#textcolor566{color:#008080} +span#textcolor567{color:#008080} +span#textcolor568{color:#008080} +span#textcolor569{color:#008080} +span#textcolor570{color:#008080} +span#textcolor571{color:#008080} +span#textcolor572{color:#008080} +span#textcolor573{color:#008080} +span#textcolor574{color:#008080} +span#textcolor575{color:#008080} +span#textcolor576{color:#008080} +span#textcolor577{color:#008080} +span#textcolor578{color:#008080} +span#textcolor579{color:#008080} +span#textcolor580{color:#008080} +span#textcolor581{color:#008080} +span#textcolor582{color:#008080} +span#textcolor583{color:#008080} +span#textcolor584{color:#008080} +span#textcolor585{color:#008080} +span#textcolor586{color:#008080} +span#textcolor587{color:#008080} +span#textcolor588{color:#008080} +span#textcolor589{color:#008080} +span#textcolor590{color:#008080} +span#textcolor591{color:#008080} +span#textcolor592{color:#008080} +span#textcolor593{color:#008080} +span#textcolor594{color:#008080} +span#textcolor595{color:#008080} +span#textcolor596{color:#008080} +span#textcolor597{color:#008080} +span#textcolor598{color:#008080} +span#textcolor599{color:#008080} +span#textcolor600{color:#008080} +span#textcolor601{color:#008080} +span#textcolor602{color:#008080} +span#textcolor603{color:#008080} +span#textcolor604{color:#008080} +span#textcolor605{color:#008080} +span#textcolor606{color:#008080} +span#textcolor607{color:#008080} +span#textcolor608{color:#008080} +span#textcolor609{color:#008080} +span#textcolor610{color:#008080} +span#textcolor611{color:#008080} +span#textcolor612{color:#008080} +span#textcolor613{color:#008080} +span#textcolor614{color:#008080} +span#textcolor615{color:#008080} +span#textcolor616{color:#008080} +span#textcolor617{color:#008080} +span#textcolor618{color:#008080} +span#textcolor619{color:#008080} +span#textcolor620{color:#008080} +span#textcolor621{color:#008080} +span#textcolor622{color:#008080} +span#textcolor623{color:#008080} +span#textcolor624{color:#008080} +span#textcolor625{color:#008080} +span#textcolor626{color:#008080} +span#textcolor627{color:#008080} +span#textcolor628{color:#008080} +span#textcolor629{color:#008080} +span#textcolor630{color:#008080} +span#textcolor631{color:#008080} +span#textcolor632{color:#008080} +span#textcolor633{color:#008080} +span#textcolor634{color:#008080} +span#textcolor635{color:#008080} +span#textcolor636{color:#008080} +span#textcolor637{color:#008080} +span#textcolor638{color:#008080} +span#textcolor639{color:#008080} +span#textcolor640{color:#008080} +span#textcolor641{color:#008080} +span#textcolor642{color:#008080} +span#textcolor643{color:#008080} +span#textcolor644{color:#008080} +span#textcolor645{color:#008080} +span#textcolor646{color:#008080} +span#textcolor647{color:#008080} +span#textcolor648{color:#008080} +span#textcolor649{color:#008080} +span#textcolor650{color:#008080} +span#textcolor651{color:#008080} +span#textcolor652{color:#008080} +span#textcolor653{color:#008080} +span#textcolor654{color:#008080} +span#textcolor655{color:#008080} +span#textcolor656{color:#008080} +span#textcolor657{color:#008080} +span#textcolor658{color:#008080} +span#textcolor659{color:#008080} +span#textcolor660{color:#008080} +span#textcolor661{color:#008080} +span#textcolor662{color:#008080} +span#textcolor663{color:#008080} +span#textcolor664{color:#008080} +span#textcolor665{color:#008080} +span#textcolor666{color:#008080} +span#textcolor667{color:#008080} +span#textcolor668{color:#008080} +span#textcolor669{color:#008080} +span#textcolor670{color:#008080} +span#textcolor671{color:#008080} +span#textcolor672{color:#008080} +span#textcolor673{color:#008080} +span#textcolor674{color:#008080} +span#textcolor675{color:#008080} +span#textcolor676{color:#008080} +span#textcolor677{color:#008080} +span#textcolor678{color:#008080} +span#textcolor679{color:#008080} +span#textcolor680{color:#008080} +span#textcolor681{color:#008080} +span#textcolor682{color:#008080} +span#textcolor683{color:#008080} +span#textcolor684{color:#008080} +span#textcolor685{color:#008080} +span#textcolor686{color:#008080} +span#textcolor687{color:#008080} +span#textcolor688{color:#008080} +span#textcolor689{color:#008080} +span#textcolor690{color:#008080} +span#textcolor691{color:#008080} +span#textcolor692{color:#008080} +span#textcolor693{color:#008080} +span#textcolor694{color:#008080} +span#textcolor695{color:#008080} +span#textcolor696{color:#008080} +span#textcolor697{color:#008080} +span#textcolor698{color:#008080} +span#textcolor699{color:#008080} +span#textcolor700{color:#008080} +span#textcolor701{color:#008080} +span#textcolor702{color:#008080} +span#textcolor703{color:#008080} +span#textcolor704{color:#008080} +span#textcolor705{color:#008080} +span#textcolor706{color:#008080} +span#textcolor707{color:#008080} +span#textcolor708{color:#008080} +span#textcolor709{color:#008080} +span#textcolor710{color:#008080} +span#textcolor711{color:#008080} +span#textcolor712{color:#008080} +span#textcolor713{color:#008080} +span#textcolor714{color:#008080} +span#textcolor715{color:#008080} +span#textcolor716{color:#008080} +span#textcolor717{color:#008080} +span#textcolor718{color:#008080} +span#textcolor719{color:#008080} +span#textcolor720{color:#008080} +span#textcolor721{color:#008080} +span#textcolor722{color:#008080} +span#textcolor723{color:#008080} +span#textcolor724{color:#008080} +span#textcolor725{color:#008080} +span#textcolor726{color:#008080} +span#textcolor727{color:#008080} +span#textcolor728{color:#008080} +span#textcolor729{color:#008080} +span#textcolor730{color:#008080} +span#textcolor731{color:#008080} +span#textcolor732{color:#008080} +span#textcolor733{color:#008080} +span#textcolor734{color:#008080} +span#textcolor735{color:#008080} +span#textcolor736{color:#008080} +span#textcolor737{color:#008080} +span#textcolor738{color:#008080} +span#textcolor739{color:#008080} +span#textcolor740{color:#008080} +span#textcolor741{color:#008080} +span#textcolor742{color:#008080} +span#textcolor743{color:#008080} +span#textcolor744{color:#008080} +span#textcolor745{color:#008080} +span#textcolor746{color:#008080} +span#textcolor747{color:#008080} +span#textcolor748{color:#008080} +span#textcolor749{color:#008080} +span#textcolor750{color:#008080} +span#textcolor751{color:#008080} +span#textcolor752{color:#008080} +span#textcolor753{color:#008080} +span#textcolor754{color:#008080} +span#textcolor755{color:#008080} +span#textcolor756{color:#008080} +span#textcolor757{color:#008080} +span#textcolor758{color:#008080} +span#textcolor759{color:#008080} +span#textcolor760{color:#008080} +span#textcolor761{color:#008080} +span#textcolor762{color:#008080} +span#textcolor763{color:#008080} +span#textcolor764{color:#008080} +span#textcolor765{color:#008080} +span#textcolor766{color:#008080} +span#textcolor767{color:#008080} +span#textcolor768{color:#008080} +span#textcolor769{color:#008080} +span#textcolor770{color:#008080} +span#textcolor771{color:#008080} +span#textcolor772{color:#008080} +span#textcolor773{color:#008080} +span#textcolor774{color:#008080} +span#textcolor775{color:#008080} +span#textcolor776{color:#008080} +span#textcolor777{color:#008080} +span#textcolor778{color:#008080} +span#textcolor779{color:#008080} +span#textcolor780{color:#008080} +span#textcolor781{color:#008080} +span#textcolor782{color:#008080} +span#textcolor783{color:#008080} +span#textcolor784{color:#008080} +span#textcolor785{color:#008080} +span#textcolor786{color:#008080} +span#textcolor787{color:#008080} +span#textcolor788{color:#008080} +span#textcolor789{color:#008080} +span#textcolor790{color:#008080} +span#textcolor791{color:#008080} +span#textcolor792{color:#008080} +span#textcolor793{color:#008080} +span#textcolor794{color:#008080} +span#textcolor795{color:#008080} +span#textcolor796{color:#008080} +span#textcolor797{color:#008080} +span#textcolor798{color:#008080} +span#textcolor799{color:#008080} +span#textcolor800{color:#008080} +span#textcolor801{color:#008080} +span#textcolor802{color:#008080} +span#textcolor803{color:#008080} +span#textcolor804{color:#008080} +span#textcolor805{color:#008080} +span#textcolor806{color:#008080} +span#textcolor807{color:#008080} +span#textcolor808{color:#008080} +span#textcolor809{color:#008080} +span#textcolor810{color:#008080} +span#textcolor811{color:#008080} +span#textcolor812{color:#008080} +span#textcolor813{color:#008080} +span#textcolor814{color:#008080} +span#textcolor815{color:#008080} +span#textcolor816{color:#008080} +span#textcolor817{color:#008080} +span#textcolor818{color:#008080} +span#textcolor819{color:#008080} +span#textcolor820{color:#008080} +span#textcolor821{color:#008080} +span#textcolor822{color:#008080} +span#textcolor823{color:#008080} +span#textcolor824{color:#008080} +span#textcolor825{color:#008080} +span#textcolor826{color:#008080} +span#textcolor827{color:#008080} +span#textcolor828{color:#008080} +span#textcolor829{color:#008080} +span#textcolor830{color:#008080} +span#textcolor831{color:#008080} +span#textcolor832{color:#008080} +span#textcolor833{color:#008080} +span#textcolor834{color:#008080} +span#textcolor835{color:#008080} +span#textcolor836{color:#008080} +span#textcolor837{color:#008080} +span#textcolor838{color:#008080} +span#textcolor839{color:#008080} +span#textcolor840{color:#008080} +span#textcolor841{color:#008080} +span#textcolor842{color:#008080} +span#textcolor843{color:#008080} +span#textcolor844{color:#008080} +span#textcolor845{color:#008080} +span#textcolor846{color:#008080} +span#textcolor847{color:#008080} +span#textcolor848{color:#008080} +span#textcolor849{color:#008080} +span#textcolor850{color:#008080} +span#textcolor851{color:#008080} +span#textcolor852{color:#008080} +span#textcolor853{color:#008080} +span#textcolor854{color:#008080} +span#textcolor855{color:#008080} +span#textcolor856{color:#008080} +span#textcolor857{color:#008080} +span#textcolor858{color:#008080} +span#textcolor859{color:#008080} +span#textcolor860{color:#008080} +span#textcolor861{color:#008080} +span#textcolor862{color:#008080} +span#textcolor863{color:#008080} +span#textcolor864{color:#008080} +span#textcolor865{color:#008080} +span#textcolor866{color:#008080} +span#textcolor867{color:#008080} +span#textcolor868{color:#008080} +span#textcolor869{color:#008080} +span#textcolor870{color:#008080} +span#textcolor871{color:#008080} +span#textcolor872{color:#008080} +span#textcolor873{color:#008080} +span#textcolor874{color:#008080} +span#textcolor875{color:#008080} +span#textcolor876{color:#008080} +span#textcolor877{color:#008080} +span#textcolor878{color:#008080} +span#textcolor879{color:#008080} +span#textcolor880{color:#008080} +span#textcolor881{color:#008080} +span#textcolor882{color:#008080} +span#textcolor883{color:#008080} +span#textcolor884{color:#008080} +span#textcolor885{color:#008080} +span#textcolor886{color:#008080} +span#textcolor887{color:#008080} +span#textcolor888{color:#008080} +span#textcolor889{color:#008080} +span#textcolor890{color:#008080} +span#textcolor891{color:#008080} +span#textcolor892{color:#008080} +span#textcolor893{color:#008080} +span#textcolor894{color:#008080} +span#textcolor895{color:#008080} +span#textcolor896{color:#008080} +span#textcolor897{color:#008080} +span#textcolor898{color:#008080} +span#textcolor899{color:#008080} +span#textcolor900{color:#008080} +span#textcolor901{color:#008080} +span#textcolor902{color:#008080} +span#textcolor903{color:#008080} +span#textcolor904{color:#008080} +span#textcolor905{color:#008080} +span#textcolor906{color:#008080} +span#textcolor907{color:#008080} +span#textcolor908{color:#008080} +span#textcolor909{color:#008080} +span#textcolor910{color:#008080} +span#textcolor911{color:#008080} +span#textcolor912{color:#008080} +span#textcolor913{color:#008080} +span#textcolor914{color:#008080} +span#textcolor915{color:#008080} +span#textcolor916{color:#008080} +span#textcolor917{color:#008080} +span#textcolor918{color:#008080} +span#textcolor919{color:#008080} +span#textcolor920{color:#008080} +span#textcolor921{color:#008080} +span#textcolor922{color:#008080} +span#textcolor923{color:#008080} +span#textcolor924{color:#008080} +span#textcolor925{color:#008080} +span#textcolor926{color:#008080} +span#textcolor927{color:#008080} +span#textcolor928{color:#008080} +span#textcolor929{color:#008080} +span#textcolor930{color:#008080} +span#textcolor931{color:#008080} +span#textcolor932{color:#008080} +span#textcolor933{color:#008080} +span#textcolor934{color:#008080} +span#textcolor935{color:#008080} +span#textcolor936{color:#008080} +span#textcolor937{color:#008080} +span#textcolor938{color:#008080} +span#textcolor939{color:#008080} +span#textcolor940{color:#008080} +span#textcolor941{color:#008080} +span#textcolor942{color:#008080} +span#textcolor943{color:#008080} +span#textcolor944{color:#008080} +span#textcolor945{color:#008080} +span#textcolor946{color:#008080} +span#textcolor947{color:#008080} +span#textcolor948{color:#008080} +span#textcolor949{color:#008080} +span#textcolor950{color:#008080} +span#textcolor951{color:#008080} +span#textcolor952{color:#008080} +span#textcolor953{color:#008080} +span#textcolor954{color:#008080} +span#textcolor955{color:#008080} +span#textcolor956{color:#008080} +span#textcolor957{color:#008080} +span#textcolor958{color:#008080} +span#textcolor959{color:#008080} +span#textcolor960{color:#008080} +span#textcolor961{color:#008080} +span#textcolor962{color:#008080} +span#textcolor963{color:#008080} +span#textcolor964{color:#008080} +span#textcolor965{color:#008080} +span#textcolor966{color:#008080} +span#textcolor967{color:#008080} +span#textcolor968{color:#008080} +span#textcolor969{color:#008080} +span#textcolor970{color:#008080} +span#textcolor971{color:#008080} +span#textcolor972{color:#008080} +span#textcolor973{color:#008080} +span#textcolor974{color:#008080} +span#textcolor975{color:#008080} +span#textcolor976{color:#008080} +span#textcolor977{color:#008080} +span#textcolor978{color:#008080} +span#textcolor979{color:#008080} +span#textcolor980{color:#008080} +span#textcolor981{color:#008080} +span#textcolor982{color:#008080} +span#textcolor983{color:#008080} +span#textcolor984{color:#008080} +span#textcolor985{color:#008080} +span#textcolor986{color:#008080} +span#textcolor987{color:#008080} +span#textcolor988{color:#008080} +span#textcolor989{color:#008080} +span#textcolor990{color:#008080} +span#textcolor991{color:#008080} +span#textcolor992{color:#008080} +span#textcolor993{color:#008080} +span#textcolor994{color:#008080} +span#textcolor995{color:#008080} +span#textcolor996{color:#008080} +span#textcolor997{color:#008080} +span#textcolor998{color:#008080} +span#textcolor999{color:#008080} +span#textcolor1000{color:#008080} +span#textcolor1001{color:#008080} +span#textcolor1002{color:#008080} +span#textcolor1003{color:#008080} +span#textcolor1004{color:#008080} +span#textcolor1005{color:#008080} +span#textcolor1006{color:#008080} +span#textcolor1007{color:#008080} +span#textcolor1008{color:#008080} +span#textcolor1009{color:#008080} +span#textcolor1010{color:#008080} +span#textcolor1011{color:#008080} +span#textcolor1012{color:#008080} +span#textcolor1013{color:#008080} +span#textcolor1014{color:#008080} +span#textcolor1015{color:#008080} +span#textcolor1016{color:#008080} +span#textcolor1017{color:#008080} +span#textcolor1018{color:#008080} +span#textcolor1019{color:#008080} +span#textcolor1020{color:#008080} +span#textcolor1021{color:#008080} +span#textcolor1022{color:#008080} +span#textcolor1023{color:#008080} +span#textcolor1024{color:#008080} +span#textcolor1025{color:#008080} +span#textcolor1026{color:#008080} +span#textcolor1027{color:#008080} +span#textcolor1028{color:#008080} +span#textcolor1029{color:#008080} +span#textcolor1030{color:#008080} +span#textcolor1031{color:#008080} +span#textcolor1032{color:#008080} +span#textcolor1033{color:#008080} +span#textcolor1034{color:#008080} +span#textcolor1035{color:#008080} +span#textcolor1036{color:#008080} +span#textcolor1037{color:#008080} +span#textcolor1038{color:#008080} +span#textcolor1039{color:#008080} +span#textcolor1040{color:#008080} +span#textcolor1041{color:#008080} +span#textcolor1042{color:#008080} +span#textcolor1043{color:#008080} +span#textcolor1044{color:#008080} +span#textcolor1045{color:#008080} +span#textcolor1046{color:#008080} +span#textcolor1047{color:#008080} +span#textcolor1048{color:#008080} +span#textcolor1049{color:#008080} +span#textcolor1050{color:#008080} +span#textcolor1051{color:#008080} +span#textcolor1052{color:#008080} +span#textcolor1053{color:#008080} +span#textcolor3{color:#008080} /* end css.sty */ @@ -302,193 +1297,191 @@ span#textcolor62{color:#00FF00} -

    -

    - - -

    - - +

    + + +

    + +

    -

    -

    User Manual for glossaries.sty v4.44 +

    +

    User Manual for glossaries.sty v4.45

    +class="td11"> Nicola L.C. Talbot
    Nicola L.C. Talbot
    http://www.dickimaw-books.com/
    +href="http://www.dickimaw-books.com/contact" >dickimaw-books.com/contact
    -

    2019-12-06

    +

    2020-02-13

    -

    - - +

    + +

    -

    -

    +

    Abstract

    -

    The glossaries package provides a means to define terms or abbreviations or symbols that can be -referenced within your document. Sorted lists with collated locations can be generated either -using TEX or using a supplementary indexing application. -

    Additional features not provided here may be available through the extension package -

    The glossaries package provides a means to define terms or abbreviations or symbols that can be referenced within +your document. Sorted lists with collated locations can be generated either using TEX or using a +supplementary indexing application. Sample documents are provided with the glossaries package. These are +listed in §19 Sample Documents. +

    + + +

    +
    +

    Additional features not provided here may be available through the extension package glossaries-extra which, if required, needs to be installed separately. New features will be added -to glossaries-extra. Versions of the glossaries package after v4.21 will mostly be just bug fixes. -Note that glossaries-extra which, +if required, needs to be installed separately. New features will be added to glossaries-extra. Versions of the +glossaries package after v4.21 will mostly be just bug fixes or minor maintenance. Note that glossaries-extra provides an extra indexing option (glossaries-extra +provides an extra indexing option (bib2gls) which isn’t available -with just the base glossaries package. -

    - - -

    -
    -

    If you require multilingual support you must also separately install the relevant language -module. Each language module is distributed under the name ) which isn’t available with just the base glossaries package. +

    +

    +

    If you require multilingual support you must also separately install the relevant language module. Each +language module is distributed under the name glossaries-language⟩, -where ⟨language⟩ is the root language name. For example, glossaries-french or -language⟩, where ⟨language⟩ is the root language +name. For example, glossaries-french or glossaries-german. If a language module is required, the glossaries package will -automatically try to load it and will give a warning if the module isn’t found. See §1.4 -Multi-Lingual Support for further details. If there isn’t any support available for your -language, use the glossaries +package will automatically try to load it and will give a warning if the module isn’t found. See §1.3 Multi-Lingual +Support for further details. If there isn’t any support available for your language, use the nolangwarn package option to suppress the warning and provide your own -translations. (For example, use the title key in \printglossary.) -

    The glossaries package requires a number of other packages including, but not limited to, + id="dx1-3"> package +option to suppress the warning and provide your own translations. (For example, use the title key in \printglossary.) +

    The glossaries package requires a number of other packages including, but not limited to, tracklang, , mfirstuc, , +etoolbox, , xkeyval (at least version dated 2006/11/18), (at least version dated 2006/11/18), textcase, , xfor, -, datatool-base (part of the (part of the datatool bundle) and bundle) +and amsgen. These packages are all available in the -latest T. These packages are all available in the latest TEX Live and MikTEX distributions. If any of them are missing, please update your -TEX distribution using your update manager. For help on this see, for example, -EX distributions. If any of them +are missing, please update your TEX distribution using your update manager. For help on this +see, for example, How do I update my TEX distribution? or (for Linux users) Updating TEX on Linux. -

    Note that occasionally you may find that certain packages need to be loaded after -packages that are required by

    Note that occasionally you may find that certain packages need to be loaded after packages that are required +by glossaries. For example, a package ⟨X⟩ might need to be loaded -after X⟩ might need to be loaded after amsgen. In which case, load the required package first (for example, . In which case, load the required +package first (for example, amsgen), then ⟨X⟩, -and finally load ), then ⟨X⟩, and finally load glossaries. -

    Documents have wide-ranging styles when it comes to presenting glossaries or lists of -terms or notation. People have their own preferences and to a large extent this -is determined by the kind of information that needs to go in the glossary. They -may just have symbols with terse descriptions or they may have long technical -words with complicated descriptions. The glossaries package is flexible enough to -accommodate such varied requirements, but this flexibility comes at a price: a big +

    Documents have wide-ranging styles when it comes to presenting glossaries or lists of terms or +notation. People have their own preferences and to a large extent this is determined by the kind of +information that needs to go in the glossary. They may just have symbols with terse descriptions +or they may have long technical words with complicated descriptions. The glossaries package is +flexible enough to accommodate such varied requirements, but this flexibility comes at a price: a big manual. -

    😱 If you’re freaking out at the size of this manual, start with glossariesbegin.pdf (“The -glossaries package: a guide for beginnners”). You should find it in the same directory as this -document or try texdoc glossariesbegin.pdf. Once you’ve got to grips with -the basics, then come back to this manual to find out how to adjust the settings. -

    -

    -

    The

    😱 If you’re freaking out at the size of this manual, start with glossariesbegin.pdf (“The glossaries package: +a guide for beginnners”). You should find it in the same directory as this document or try texdoc +glossariesbegin.pdf. Once you’ve got to grips with the basics, then come back to this manual to find out how +to adjust the settings.

    +

    +

    The glossaries bundle comes with the following documentation:

    glossariesbegin.pdf
    If you are a complete beginner, start with “The glossaries - package: a guide for beginners”. +class="description">If you are a complete beginner, start with “The glossaries package: a guide for + beginners”.
    glossary2glossaries.pdf
    If you are moving over from the obsolete glossary package, - read “Upgrading from the glossary package to the glossaries package”. + id="dx1-16"> package, read “Upgrading + from the glossary package to the glossaries package”. + +
    glossaries-user.pdf
    This document is the main user guide for the glossaries package. - -
    glossaries-code.pdf
    Advanced users wishing to know more about the inner workings - of all the packages provided in the glossaries bundle should read “Documented - Code for glossaries v4.44”. +class="description">Advanced users wishing to know more about the inner workings of all the + packages provided in the glossaries bundle should read “Documented Code for glossaries v4.45”.
    INSTALL
    CHANGES
    Change log.
    README
    README.md
    Package summary.
    -

    Related resources:

    +

    Related resources:

    -

    If you use

    If you use hyperref and and glossaries, you must load hyperref first. Similarly the first (although hyperref should be loaded after +most other packages). Similarly the doc package -must also be loaded before package must also be loaded before glossaries. (If doc is loaded, the file extensions for the default main -glossary are changed to is loaded, the file +extensions for the default main glossary are changed to gls2, , glo2 and .glg2 to avoid conflict with and glg2 to avoid conflict with doc’s changes + id="dx1-25">’s changes glossary.) - - -

    If you are using

    If you are using hyperref, it’s best to use , it’s best to use pdflatex rather than rather than latex (DVI format) as -pdflatex deals with hyperlinks much better. If you use the DVI format, you will encounter -problems where you have long hyperlinks or hyperlinks in subscripts or superscripts. This is -an issue with the DVI format not with glossaries. If you really need to use the DVI format and -have a problem with hyperlinks in maths mode, I recommend you use (DVI format) as pdflatex deals with +hyperlinks much better. If you use the DVI format, you will encounter problems where you have long hyperlinks +or hyperlinks in subscripts or superscripts. This is an issue with the DVI format not with glossaries. If you really +need to use the DVI format and have a problem with hyperlinks in maths mode, I recommend you use +glossaries-extra with the -hyperoutside and textformat attributes set to appropriate values for problematic entries. -

    -

    - - - - +class="cmss-10">glossaries-extra with the hyperoutside and textformat attributes set to appropriate values for problematic entries. +

    +

    +

    The glossaries package replaces the glossary package which is now obsolete. Please see the document +“Upgrading from the glossary package to the glossaries package” for assistance in upgrading. + + + +

    Contents

    @@ -606,187 +1606,219 @@ href="#sec:intro" id="QQ2-1-5">Introduction

     1.1 Indexing Options
     1.2 Sample Documents -
     1.3 Dummy Entries for Testing -
     1.4  1.3 Multi-Lingual Support -
      1.4.1   1.3.1 Changing the Fixed Names -
     1.5  1.4 Generating the Associated Glossary Files -
      1.5.1   1.4.1 Using the makeglossaries Perl Script -
      1.5.2   1.4.2 Using the makeglossaries-lite Lua Script -
      1.5.3   1.4.3 Using xindy explicitly (Option 3) -
      1.5.4   1.4.4 Using makeindex explicitly (Option 2) -
      1.5.5  1.5 Note to Front-End and Script Developers +
      1.5.1 MakeIndex and Xindy +
      1.5.2 Entry Labels +
      1.5.3 Bib2Gls
    2 Package Options +href="#sec:pkgopts" id="QQ2-1-29">Package Options
     2.1 General Options +href="#sec:pkgopts-general" id="QQ2-1-30">General Options
     2.2 Sectioning, Headings and TOC Options +href="#sec:pkgopts-sec" id="QQ2-1-42">Sectioning, Headings and TOC Options
     2.3 Glossary Appearance Options +href="#sec:pkgopts-printglos" id="QQ2-1-48">Glossary Appearance Options
     2.4 Sorting Options +href="#sec:pkgopts-indexing" id="QQ2-1-65">Indexing Options
     2.5 Acronym Options -
      2.5.1 Deprecated Acronym Style Options +href="#sec:pkgopts-sort" id="QQ2-1-75">Sorting Options
     2.6 Other Options +href="#sec:pkgopts-type" id="QQ2-1-86">Glossary Type Options
     2.7 Setting Options After the Package is Loaded +href="#sec:pkgopts-acronym" id="QQ2-1-93">Acronym and Abbreviation Options +
      2.7.1 Deprecated Acronym Style Options +
     2.8 Other Options +
     2.9 Setting Options After the Package is Loaded
    3 Setting Up +href="#sec:setup" id="QQ2-1-113">Setting Up
     3.1 Option 1 +href="#sec:setupopt1" id="QQ2-1-114">Option 1
     3.2 Options 2 and 3 +href="#sec:setupopt23" id="QQ2-1-115">Options 2 and 3
    4 Defining Glossary Entries +href="#sec:newglosentry" id="QQ2-1-116">Defining Glossary Entries
     4.1 Plurals +href="#sec:plurals" id="QQ2-1-117">Plurals
     4.2 Other Grammatical Constructs +href="#sec:grammar" id="QQ2-1-118">Other Grammatical Constructs
     4.3 Additional Keys +href="#sec:addkey" id="QQ2-1-119">Additional Keys
      4.3.1 Document Keys +href="#sec:glsaddkey" id="QQ2-1-120">Document Keys
      4.3.2 Storage Keys +href="#sec:glsaddstoragekey" id="QQ2-1-121">Storage Keys + +
     4.4 Expansion +href="#sec:expansion" id="QQ2-1-122">Expansion
     4.5 Sub-Entries +href="#sec:subentries" id="QQ2-1-124">Sub-Entries
      4.5.1 Hierarchical Categories +href="#sec:hierarchical" id="QQ2-1-125">Hierarchical Categories
      4.5.2 Homographs - - +href="#sec:homographs" id="QQ2-1-126">Homographs
     4.6 Loading Entries From a File +href="#sec:loadglsentries" id="QQ2-1-127">Loading Entries From a File
     4.7 Moving Entries to Another Glossary +href="#sec:moveentry" id="QQ2-1-128">Moving Entries to Another Glossary
     4.8 Drawbacks With Defining Entries in the Document Environment +href="#sec:docdefs" id="QQ2-1-129">Drawbacks With Defining Entries in the Document Environment
      4.8.1 Technical Issues +href="#sec:techissues" id="QQ2-1-130">Technical Issues
      4.8.2 Good Practice Issues +href="#sec:goodpractice" id="QQ2-1-131">Good Practice Issues
    5 Number lists +href="#sec:numberlists" id="QQ2-1-132">Number lists
     5.1 Encap Values +href="#sec:encap" id="QQ2-1-133">Encap Values
     5.2 Locations +href="#sec:locationsyntax" id="QQ2-1-134">Locations
     5.3 Range Formations +href="#sec:ranges" id="QQ2-1-135">Range Formations
     5.4 Style Hook +href="#sec:isthook" id="QQ2-1-136">Style Hook
    6 Links to Glossary Entries +href="#sec:glslink" id="QQ2-1-137">Links to Glossary Entries
     6.1 The The \gls-Like Commands (First Use Flag Queried)
     6.2 The The \glstext-Like Commands (First Use Flag Not Queried)
     6.3 Changing the format of the link text +href="#sec:glsdisplay" id="QQ2-1-141">Changing the format of the link text
     6.4 Enabling and disabling hyperlinks to glossary entries +href="#sec:disablehyperlinks" id="QQ2-1-142">Enabling and disabling hyperlinks to glossary entries
    7 Adding an Entry to the Glossary Without Generating Text +href="#sec:glsadd" id="QQ2-1-143">Adding an Entry to the Glossary Without Generating Text
    8 Cross-Referencing Entries +href="#sec:crossref" id="QQ2-1-144">Cross-Referencing Entries
     8.1 Customising Cross-reference Text +href="#sec:customxr" id="QQ2-1-145">Customising Cross-reference Text
    9 Using Glossary Terms Without Links +href="#sec:glsnolink" id="QQ2-1-146">Using Glossary Terms Without Links
    10 Displaying a glossary +href="#sec:printglossary" id="QQ2-1-147">Displaying a glossary
    11 Xindy (Option 3) +href="#sec:xindy" id="QQ2-1-148">Xindy (Option 3)
     11.1 Language and Encodings +href="#sec:langenc" id="QQ2-1-149">Language and Encodings
     11.2 Locations and Number lists +href="#sec:xindyloc" id="QQ2-1-150">Locations and Number lists
     11.3 Glossary Groups +href="#sec:groups" id="QQ2-1-151">Glossary Groups
    12 Defining New Glossaries +href="#sec:newglossary" id="QQ2-1-152">Defining New Glossaries
    13 Acronyms and Other Abbreviations +href="#sec:acronyms" id="QQ2-1-153">Acronyms and Other Abbreviations
     13.1 Changing the Abbreviation Style +href="#sec:setacronymstyle" id="QQ2-1-155">Changing the Abbreviation Style
      13.1.1 Predefined Acronym Styles +href="#sec:predefinedacrstyles" id="QQ2-1-156">Predefined Acronym Styles
      13.1.2 Defining A Custom Acronym Style +href="#sec:customacronym" id="QQ2-1-157">Defining A Custom Acronym Style
     13.2 Displaying the List of Acronyms +href="#sec:disploa" id="QQ2-1-158">Displaying the List of Acronyms
     13.3 Upgrading From the glossary Package +href="#sec:oldacronym" id="QQ2-1-159">Upgrading From the glossary Package
    14 Unsetting and Resetting Entry Flags +href="#sec:glsunset" id="QQ2-1-161">Unsetting and Resetting Entry Flags
     14.1 Counting the Number of Times an Entry has been Used (First Use Flag Unset) +href="#sec:enableentrycount" id="QQ2-1-162">Counting the Number of Times an Entry has been Used (First Use Flag Unset)
    15 Glossary Styles +href="#sec:styles" id="QQ2-1-163">Glossary Styles
     15.1 Predefined Styles +href="#sec:predefinedstyles" id="QQ2-1-164">Predefined Styles
      15.1.1 List Styles +href="#sec:liststyles" id="QQ2-1-166">List Styles
      15.1.2 Longtable Styles +href="#sec:longstyles" id="QQ2-1-167">Longtable Styles
      15.1.3 Longtable Styles (Ragged Right) +href="#sec:longraggedstyles" id="QQ2-1-168">Longtable Styles (Ragged Right)
      15.1.4 Longtable Styles (Longtable Styles (booktabs)
      15.1.5 Supertabular Styles +href="#sec:superstyles" id="QQ2-1-170">Supertabular Styles
      15.1.6 Supertabular Styles (Ragged Right) +href="#sec:superraggedstyles" id="QQ2-1-171">Supertabular Styles (Ragged Right)
      15.1.7 Tree-Like Styles +href="#sec:treestyles" id="QQ2-1-172">Tree-Like Styles + +
      15.1.8 Multicols Style +href="#sec:mcolstyles" id="QQ2-1-173">Multicols Style
      15.1.9 In-Line Style +href="#sec:inline" id="QQ2-1-175">In-Line Style
     15.2 Defining your own glossary style +href="#sec:newglossarystyle" id="QQ2-1-176">Defining your own glossary style
    16 Utilities - - +href="#sec:utilities" id="QQ2-1-177">Utilities
     16.1 Loops +href="#sec:loops" id="QQ2-1-178">Loops
     16.2 Conditionals +href="#sec:conditionals" id="QQ2-1-179">Conditionals
     16.3 Fetching and Updating the Value of a Field +href="#sec:fetchset" id="QQ2-1-180">Fetching and Updating the Value of a Field
    17 Prefixes or Determiners +href="#sec:prefix" id="QQ2-1-181">Prefixes or Determiners
    18 Accessibility Support +href="#sec:accsupp" id="QQ2-1-182">Accessibility Support
    19 Troubleshooting +href="#sec:samples" id="QQ2-1-183">Sample Documents +
     19.1 Basic +
     19.2 Acronyms and First Use +
     19.3 Non-Page Locations +
     19.4 Multiple Glossaries +
     19.5 Sorting +
     19.6 Child Entries +
     19.7 Cross-Referencing +
     19.8 Custom Keys +
     19.9 Xindy (Option 3) +
     19.10 No Indexing Application (Option 1) +
     19.11 Other +
    20 Troubleshooting
    - - - - - - + + + + + +

    List of Tables

    - - - - + + + +

    - - + +

    Glossary

    @@ -828,35 +1860,35 @@ class="cmtt-10">\usepackage[
    xindy, -

    nonumberlist,
    -

    toc,
    -

    nopostdot,
    -

    style=altlist,
    -

    bib2gls

    An indexing application that combines two functions in one: (1) fetches entry - definition from a .bib file based on information provided in the .aux file (similar - to bibtex); (2) hierarchically sorts and collates location lists (similar to makeindex - and xindy). This application is designed for use with glossaries-extra and can’t be - used with just the base glossaries package.
    indexing application that combines two functions in one: (1) fetches entry definition from a bib + file based on information provided in the aux file (similar to bibtex); (2) hierarchically sorts and + collates location lists (similar to makeindex and xindy). This application is designed for use with + glossaries-extra and can’t be used with just the base glossaries package. See Option 4.
    Command Line Interface (CLI)

    An application that doesn’t have a graphical user interface. That is, an application - that doesn’t have any windows, buttons or menus and can be run in a command - prompt or terminal.
    An application that doesn’t have a graphical user interface. That is, an application that doesn’t + have any windows, buttons or menus and can be run in a command prompt or terminal.
    +
    +convertgls2bib

    An application provided with bib2gls that converts tex files containing entry definitions to bib + files suitable for use with bib2gls. This application is designed for files that just contain entry + definitions, but it can work on a complete document file. However, there will be a lot of “undefined + command” warnings as convertgls2bib only has a limited set of known commands. You can limit + it so that it only parses the preamble with the --preamble-only switch (requires at least bib2gls + v2.0).
    Entry location

    The location of the entry in the document. This defaults to the page number on - which the entry appears. An entry may have multiple locations.
    The location of the entry in the document. This defaults to the page number on which the entry + appears. An entry may have multiple locations.
    Extended Latin Alphabet

    An alphabet consisting of Latin characters and s and extended Latin characters.
    s.
    - -
    Extended Latin Character

    A character that’s created by combining Latin characters to form ligatures (e.g. æ) - or by applying diacritical marks to a Latin character or characters (e.g. á or ø). - See also s to form ligatures (e.g. æ) or by applying + diacritical marks to a Latin character or characters (e.g. á). See also non-Latin character.
    .
    First use

    The first time a glossary entry is used (from the start of the document or after - a reset) with one of the following commands: The first time a glossary entry is used (from the start of the document or after a reset) with one + of the following commands: \gls, , \Gls, , \GLS, , \glspl, , \Glspl, - , \GLSpl or or \glsdisp. (See first use flag & . (See first use + flag & first use text.)
    First use flag

    A conditional that determines whether or not the entry has been used according - to the rules of first use. Commands to unset or reset this conditional are described - in §14 Unsetting and Resetting Entry Flags.
    A conditional that determines whether or not the entry has been used according to the rules of + first use. Commands to unset or reset this conditional are described in §14 Unsetting and Resetting + Entry Flags.
    First use text

    The text that is displayed on first use, which is governed by the first and +class="newline" />The text that is displayed on first use, which is governed by the first and firstplural keys of firstplural keys of \newglossaryentry. (May be overridden by . (May be overridden by \glsdisp or by - or by \defglsentry.)
    .)
    class="cmssbx-10">glossaries-extra

    A separate package that extends the glossaries package, providing new features - or improving existing features. If you want to use glossaries-extra, you must have - both the glossaries package and the glossaries package, providing new features or improving existing + features. If you want to use glossaries-extra, you must have both the glossaries package and the + glossaries-extra package installed.
    @@ -1016,38 +2079,37 @@ class="cmbx-10">Indexing application

    An application (piece of software) separate from TEX/LATEX that collates and - sorts information that has an associated page reference. Generally the information - is an index entry but in this case the information is a glossary entry. There are - two main indexing applications that are used with TEX that collates and sorts information + that has an associated page reference. Generally the information is an index entry but in this case + the information is a glossary entry. There are two main indexing applications that are used with + TEX:
    makeindex and and xindy. - These are both . These are both command line interface (CLI) applications.
    + +
    Latin Alphabet

    The alphabet consisting of Latin characters. See also s. See also extended Latin alphabet.
    - -
    Latin Character

    One of the letters a, …, z, A, …, Z. See also extended Latin character.
    .
    Link text

    The text produced by commands such as \gls. It may or may not be a hyperlink - to the glossary.
    . It may or may not be a hyperlink to the glossary. +
    makeglossaries

    A custom designed Perl script interface to A custom designed Perl script interface to xindy and and makeindex provided - with the glossaries package. TEX distributions on Windows convert the original - makeglossaries script into an executable makeglossaries.exe for convenience - (but Perl is still required).
    provided with the glossaries + package. TEX distributions on Windows convert the original makeglossaries script into an + executable makeglossaries.exe for convenience (but Perl is still required).
    makeglossariesgui

    A Java GUI alternative to makeglossaries that also provides diagnostic tools. - Available separately on that also provides diagnostic tools. Available separately + on CTAN.
    makeglossaries-lite

    A custom designed Lua script interface to A custom designed Lua script interface to xindy and and makeindex provided with - the glossaries package. This is a cut-down alternative to the Perl makeglossaries - script. If you have Perl installed, use the Perl script instead. This script is actually - distributed with the file name provided with the glossaries + package. This is a cut-down alternative to the Perl makeglossaries script. If you have Perl + installed, use the Perl script instead. This script is actually distributed with the file name + makeglossaries-lite.lua, but TEX Live (on - Unix-like systems) creates a symbolic link called makeglossaries-lite (without - the .lua extension) to the actual makeglossaries-lite.lua script.
    E
    X Live (on Unix-like systems) creates a symbolic link called + makeglossaries-lite (without the .lua extension) to the actual makeglossaries-lite.lua + script.
    makeindex

    An indexing application.
    indexing application. See Option 2.
    Non-Latin Alphabet

    An alphabet consisting of non-Latin characters.
    s.
    + +
    Non-Latin Character

    An extended Latin character or a character that isn’t a  or a character that isn’t a Latin character.
    .
    - -
    Number list

    A list of entry locations (also called a location list). The number list can be - suppressed using the entry locations (also called a location list). The number list can be suppressed using the + nonumberlist package option.
    package option.
    Sanitize

    Converts command names into character sequences. That is, a command called, - say, \foo, is converted into the sequence of characters: Converts command names into character sequences. That is, a command called, say, \foo, is + converted into the sequence of characters: \, f, o, o. Depending on - the font, the backslash character may appear as a dash when used in the main - document text, so o. Depending on the font, the backslash character + may appear as a dash when used in the main document text, so \foo will appear as: —foo. -

    Earlier versions of glossaries used this technique to write information to the files - used by the indexing applications to prevent problems caused by fragile commands. - Now, this is only used for the sort key.

    Earlier versions of glossaries used this technique to write information to the files used by the indexing + applications to prevent problems caused by fragile commands. Now, this is only used for the sort + key.

    +Small caps

    Small capitals. The LATEX kernel provides \textsc{text} to produce small capitals. This uses + a font where lowercase letters have a small capital design. Uppercase letters have the standard + height and there’s no noticeable difference with uppercase characters in corresponding non-small + caps fonts. This means that for a small caps appearance, you need to use lowercase letters in the + ⟨text⟩ argument. The package provides \textsmaller{text} which simulates small caps by reducing + the size of the font, so in this case the contents of ⟨text⟩ should be uppercase (otherwise the effect + is simply smaller lowercase letters). Some fonts don’t support small caps combined with bold or + slanted properties. In this case, there will be a font substitution warning and one of the properties + (such as small caps or slanted) will be dropped.
    +
    Standard EX Extended Latin Character

    An extended Latin character that can be created by a core LATEX command, - such as \o (ø) or \’e (é). That is, the character can be produced without the - need to load a particular package.
    that can be created by a core LATEX command, such as \o (ø) or + \’e (é). That is, the character can be produced without the need to load a particular package.
    xindy

    A flexible indexing application with multilingual support written in Perl.
    indexing application with multilingual support written in Perl. See Option 3.
    - - -

    1.

    1. Introduction

    -

    The glossaries package is provided to assist generating lists of terms, symbols or -abbreviations. (For convenience, these lists are all referred to as glossaries in this manual.) -The package has a certain amount of flexibility, allowing the user to customize -the format of the glossary and define multiple glossaries. It also supports glossary -styles that include symbols (in addition to a name and description) for glossary -entries. There is provision for loading a database of glossary terms. Only those terms +

    The glossaries package is provided to assist generating lists of terms, symbols or abbreviations. (For +convenience, these lists are all referred to as glossaries in this manual. The terms, symbols and abbreviations are +collectively referred to as entries.) The package has a certain amount of flexibility, allowing the user +to customize the format of the glossary and define multiple glossaries. It also supports glossary +styles that include an associated symbol (in addition to a name and description) for each glossary +entry. +

    There is provision for loading a database of glossary entries. Only those entries indexed1.1 in -the document will be added to the glossary. -

    The glossaries-extra package, which is distributed as a separated bundle, extends the -capabilities of the glossaries package. The simplest document can be created with -glossaries-extra (which internally loads the glossaries package): - - +the document will be displayed in the glossary. (Unless you use Option 5, which doesn’t use any indexing but +will instead list all defined entries in order of definition.) +

    It’s not necessary to actually have a glossary in the document. You may be interested in using this package +just as means to consistently format certain types of terms, such as abbreviations, or you may prefer to have +descriptions scattered about the document and be able to easily link to the relevant description +(Option 6). +

    The simplest document is one without a glossary: + +

    \documentclass{article}  
    \usepackage[ - 
     sort=none,% no sorting or indexing required - 
     abbreviations,% create list of abbreviations - 
     symbols,% create list of symbols - 
     postdot % append a full stop after the descriptions - 
    ]{glossaries-extra} - 
    \newglossaryentry % provided by glossaries.sty + 
      sort=none % no sorting or indexing required + 
    ] + 
    {glossaries} + 
    \newglossaryentry  
     {cafe}% label  
     {% definition:  
       name={caf\'e},  
       description={small restaurant selling refreshments}  
     } - 
    \newabbreviation % provided by glossaries-extra.sty + 
    \setacronymstyle{long-short} + 
    \newacronym  
     {html}% label  
     {HTML}% short form  
     {hypertext markup language}% long form - 
    \glsxtrnewsymbol % provided by glossaries-extra.sty 'symbols' option - 
     [description={Archimedes' constant}]% options + 
    \newglossaryentry  
     {pi}% label - 
     {\ensuremath{\pi}}% symbol + 
     {% definition: + 
       name={\ensuremath{\pi}}, + 
       description={Archimedes' Constant} + 
     } + 
    \newglossaryentry + 
     {distance}% label + 
     {% definition: + 
       name={distance}, + 
       description={the length between two points}, + 
       symbol={m} + 
     }  
    \begin{document}  
    First use: \gls{cafe}, \gls{html}, \gls{pi}.  
    Next use: \gls{cafe}, \gls{html}, \gls{pi}. - 
    \printunsrtglossaries % list all defined entries + 
    \Gls{distance} (\glsentrydesc{distance}) is measured in + 
    \glssymbol{distance}.  
    \end{document}
    -

    -

    The glossaries package replaces the glossary package which is now obsolete. -Please see the document “Upgrading from the glossary package to the glossaries package” for -assistance in upgrading. -

    One of the strengths of this package is its flexibility, however the drawback of this is the -necessity of having a large manual that covers all the various settings. If you are -daunted by the size of the manual, try starting off with the much shorter guide for -beginners. -

    There’s a common misconception that you have to have Perl installed in order to use -the glossaries package. Perl is not a requirement but it does increase the available -options, particularly if you use an

    (This is a trivial example. For a real document I recommend you use siunitx for units.) +


    glossaries-extraThe glossaries-extra package, which is distributed as a separate bundle, extends the capabilities +of the glossaries package. The simplest document with a glossary can be created with glossaries-extra (which + + +internally loads the glossaries package): + + +

    +
    +\documentclass{article} +
    +

    +
    +\usepackage[ +
     sort=none,% no sorting or indexing required +
     abbreviations,% create list of abbreviations +
     symbols,% create list of symbols +
     postdot, % append a full stop after the descriptions +
     stylemods,style=index % set the default glossary style +
    ]{glossaries-extra} +
    +
    + + +
    +\newglossaryentry % provided by glossaries.sty + 
     {cafe}% label + 
     {% definition: + 
       name={caf\'e}, + 
       description={small restaurant selling refreshments} + 
     } +
    +

    +
    +% provided by glossaries-extra.sty: +
    \setabbreviationstyle{long-short} +
    +
    \newabbreviation % provided by glossaries-extra.sty +
     {html}% label +
     {HTML}% short form +
     {hypertext markup language}% long form +
    +
    % provided by glossaries-extra.sty 'symbols' option: +
    \glsxtrnewsymbol +
     [description={Archimedes' constant}]% options +
     {pi}% label +
     {\ensuremath{\pi}}% symbol +
    +
    + + +
    +\newglossaryentry % provided by glossaries.sty + 
     {distance}% label + 
     {% definition: + 
       name={distance}, + 
       description={the length between two points}, + 
       symbol={m} + 
     } + 
    \begin{document} + 
    First use: \gls{cafe}, \gls{html}, \gls{pi}. + 
    Next use: \gls{cafe}, \gls{html}, \gls{pi}. + 
    \Gls{distance} is measured in \glssymbol{distance}. +
    +

    +
    +\printunsrtglossaries % list all defined entries +
    \end{document} +
    +
    Note the difference in the way the abbreviation (HTML) and symbol (π) are defined in the two above +examples. The abbreviations, postdot and stylemods options are specific to glossaries-extra. Other options are +passed to the base glossaries package. +

    In this document, commands and options displayed in teal, such as \newabbreviation and stylemods, are +only available with the glossaries-extra package. There are also some commands and options (such as +\makeglossaries and symbols) that are provided by the base glossaries package but are redefined by the +glossaries-extra package. See the glossaries-extra user manual for further details of those commands. +
    +

    +

    One of the strengths of the glossaries package is its flexibility, however the drawback of this is the necessity of +having a large manual that covers all the various settings. If you are daunted by the size of the manual, try +starting off with the much shorter guide for beginners. +

    There’s a common misconception that you have to have Perl installed in order to use the glossaries +package. Perl is not a requirement (as demonstrated by the above examples) but it does increase the +available options, particularly if you use an extended Latin alphabet or a non-Latin alphabet.
    - - -

    -

    This document uses the glossaries package. For example, when viewing the PDF version of -this document in a hyperlinked-enabled PDF viewer (such as Adobe Reader or -Okular) if you click on the word “

    +

    This document uses the glossaries package. For example, when viewing the PDF version of this document in +a hyperlinked-enabled PDF viewer (such as Adobe Reader or Okular) if you click on the word “xindy” you’ll be taken to the entry in the glossary -where there’s a brief description of the term “” you’ll be +taken to the entry in the glossary where there’s a brief description of the term “xindy”. This is the way the glossaries -mechanism works. An indexing application is used to generated the sorted list of -terms. The indexing applications are command line interface (CLI) tools, which -means they can be run directly from a command prompt or terminal, or can be -integrated into some text editors, or you can use a build tool such as ”. This is the way the +glossaries mechanism works. An indexing application is used to generated the sorted list of terms. The indexing +applications are command line interface (CLI) tools, which means they can be run directly from a command + + +prompt or terminal, or can be integrated into some text editors, or you can use a build tool such as arara to run -them. -

    The remainder of this introductory section covers the following:

    + id="dx1-4018"> to +run them. +

    Neither of the above two examples require an indexing application. The first is just using the glossaries +package for consistent formatting, and there is no list. The second has lists but they are unsorted (see +Option 5). +

    The remainder of this introductory section covers the following:

    -

    Top

    1.1 Indexing Options

    -

    The basic idea behind the glossaries package is that you first define your entries (terms, -symbols or abbreviations). Then you can reference these within your document (like \cite or -\ref). You can also, optionally, display a list of the entries you have referenced in your -document (the glossary). This last part, displaying the glossary, is the part that most new -users find difficult. There are three options available with the base glossaries package and two -further options with the extension package glossaries-extra. An overview of these options is -given in table 1.1. -

    If you are developing a class or package that loads glossaries, I recommend that you -don’t force the user into a particular indexing method by adding an unconditional -\makeglossaries into your class or package code. Aside from forcing the user into a -particular indexing method, it means that they’re unable to use any commands that must -come before \makeglossaries (such as \newglossary) and they can’t switch off the indexing -whilst working on a draft document. -

    For a comparison of the various methods when used with large entry sets or when used -with symbols such as \alpha, see the glossaries performance page. - - +

    The basic idea behind the glossaries package is that you first define your entries (terms, symbols or +abbreviations). Then you can reference these within your document (like \cite or \ref). You can also, +optionally, display a list of the entries you have referenced in your document (the glossary). This last part, +displaying the glossary, is the part that most new users find difficult. There are three options available with the +base glossaries package (Options 13). The glossaries-extra extension package provides two extra options for lists +(Options 4 and 5) as well as an option for standalone descriptions within the document body +(Option 6). +

    An overview of Options 15 is given in table 1.1. Option 6 is omitted from the table as it doesn’t +produce a list. For a more detailed comparison of the various methods, see the glossaries performance +page. +

    If you are developing a class or package that loads glossaries, I recommend that you don’t +force the user into a particular indexing method by adding an unconditional \makeglossaries +into your class or package code. Aside from forcing the user into a particular indexing method, it +means that they’re unable to use any commands that must come before \makeglossaries (such +as \newglossary) and they can’t switch off the indexing whilst working on a draft document. +
    +

    +

    Strictly speaking, Options 5 and 6 aren’t actually indexing options as no indexing is performed. In the +case of Option 5, all defined entries are listed in order of definition. In the case of Option 6, the +entry hypertargets and descriptions are manually inserted at appropriate points in the document. + + +These two options are included here for completeness and for comparison with the actual indexing +options.

    - - -


    - - + +
    Table 1.1: Glossary Options: Pros and Cons
    - - + +
    -

    OptionOption 5

    Requires glossaries-extra?

    ?

    Requires an external application?

    application?

    Requires Perl?

    Perl?

    Requires Java?

    Java?

    Can sort @@ -1530,37 +2837,37 @@ href="#glo:nonlatinalph">non-Latin alphabets?

    ?

    * N/A

    Efficient sort algorithm?

    algorithm?

    N/A

    Can use @@ -1577,42 +2884,42 @@ class="cmr-9">for each glossary?

    glossary?

    N/A

    Any problematic sort values?

    values?

    Are entries @@ -1633,21 +2940,21 @@ class="cmr-9">separate unique entries?

    entries?

    §

    Can automatically @@ -1662,20 +2969,20 @@ class="cmr-9">the location lists?

    lists?

    Can have @@ -1690,29 +2997,29 @@ class="cmr-9">the location lists?

    lists?

    Maximum hierarchical depth (style-dependent)

    (style-dependent)

    #

    \glsdisplaynumberlist reliable?

    reliable?

    \newglossaryentry environment? (Not recommended.)

    recommended.)

    Requires additional write registers?

    registers?

    Default value @@ -1805,7 +3112,7 @@ class="cmss-9">sanitizesortpackage option

    option

    false true
    - +

    +
    -

    ________________________________________________________________________ -

    ______________________________________________________________________________________ +

    * Strips standard LTEX commands) so, for -example,  commands) so, for example, \AA is treated the same as A. -

    is treated +the same as A. +

    Only with the hybrid method provided with glossaries-extraOnly with the hybrid method provided with glossaries-extra. -

    Provided sort=none sort=none is used. -

    § Entries with the same sort value are merged. -

    Requires some setting up. -

    The locations must be set explicitly through the custom location The locations must be set explicitly through the custom location field provided by glossaries-extra. -

    # Unlimited but unreliable. -

    Entries are defined in .bib bib format. \newglossaryentry should not be used explicitly. -

    Provided docdefs=true or docdefs=restricted

    Provided docdef=true or docdef=restricted but not recommended. -

    Provided docdefs=false or docdefs=restricted

    Provided docdef=false or docdef=restricted. -

    Irrelevant with sort=none. (The record=only sort=none. (The record=only option automatically switches this on.) - - + +


    + id="x1-5017r1">

    🔗Option 1 (TEX)

    -

    This option doesn’t require an external indexing application but, with the default -alphabetic sorting, it’s very slow with severe limitations. If you want a sorted list, it -doesn’t work well for extended Latin alphabets or non-Latin alphabets. However, if -you use the sanitizesort=false package option (the default for Option 1) then the +

    Example Document: + + +

    +
    +\documentclass{article} + 
    \usepackage{glossaries} +
    +

    +
    +\makenoidxglossaries % use TeX to sort +
    +
    + + +
    +\newglossaryentry{sample}{name={sample}, + 
      description={an example}} + 
    \begin{document} + 
    \gls{sample}. +
    +

    +
    +\printnoidxglossary +
    \end{document} +
    +
    You can place all your entry definitions in a separate file and load it in the preamble with \loadglsentries +(after \makenoidxglossaries). +

    This option doesn’t require an external indexing application but, with the default alphabetic sorting, it’s +very slow with severe limitations. If you want a sorted list, it doesn’t work well for extended Latin alphabets or non-Latin alphabets. However, if you use the sanitizesort=false package option (the default for Option 1) then +the standard LATEX accent commands will be ignored, so if an entry’s name is set to -{\’e}lite then the sort value will default to EX accent commands will be ignored, so if an entry’s name is set to {\’e}lite then the sort +value will default to elite if sanitizesort=false is used and -will default to sanitizesort=false is used and will default to \’elite if sanitizesort=true is used. If you have any other kinds of -commands that don’t expand to ASCII characters, such as \alpha or \si, then you -must use sanitizesort=true or change the sort method (sort=use or sort=def) in the +class="cmss-10">sanitizesort=true is used. If +you have any other kinds of commands that don’t expand to ASCII characters, such as \alpha or +\si, then you must use sanitizesort=true or change the sort method (sort=use or sort=def) in the package options or explicitly set the sort key when you define the relevant entries. For -example: - - -

    -
    -\newglossaryentry{alpha}{name={\ensuremath{\alpha}}, - 
     sort={alpha},description={...}} -
    -

    -

    This option works best with the sort=def or sort=use setting. For any other setting, be -prepared for a long document build time, especially if you have a lot of entries defined. This -option is intended as a last resort for alphabetical sorting. This option allows a -mixture of sort methods. (For example, sorting by word order for one glossary and order of -use for another.) This option is not suitable for hierarchical glossaries and does not form +class="cmtt-10">sort key when you define the relevant entries. For example: +

    +
    +\newglossaryentry{alpha}{name={\ensuremath{\alpha}}, +
     sort={alpha},description={...}} +
    +
    +

    The glossaries-extra package has a modified symbols package option that provides \glsxtrnewsymbol, which +automatically sets the sort key to the entry label (instead of the name).
    +

    +

    This option works best with the sort=def or sort=use setting. For any other setting, be prepared for a long +document build time, especially if you have a lot of entries defined. This option is intended as a last resort for +alphabetical sorting. This option allows a mixture of sort methods. (For example, sorting by word order for one +glossary and order of use for another.) This option is not suitable for hierarchical glossaries and does not form ranges in the number lists. If you really can’t use an indexing application consider using -Option 5 instead. -

    + id="dx1-6019">s. If you really can’t use an indexing application consider using Option 5 +instead. +

    1. Add - - -
      + class="enumerate" id="x1-6021x1">Add + + +
      \makenoidxglossaries
      -

      to your preamble (before you start defining your entries, as described in §4 Defining - Glossary Entries). +

      to your preamble (before you start defining your entries, as described in §4 Defining Glossary + Entries).

    2. Put - - -
      + class="enumerate" id="x1-6023x2">Put + + +
      \printnoidxglossary
      -

      where you want your list of entries to appear (described in §10 Displaying a glossary). - Alternatively, to display all glossaries use the iterative command: - - +

      where you want your list of entries to appear (described in §10 Displaying a glossary). Alternatively, to + display all glossaries use the iterative command: + +

      -
      +
      \printnoidxglossaries
      -

      +

    3. Run LATEX twice on your document. (As you would do to make a table of contents - appear.) For example, click twice on the “typeset” or “build” or “PDFLATEX” button - in your editor.
    -

    Complete example: - - + class="enumerate" id="x1-6025x3">Run LATEX twice on your document. (As you would do to make a table of contents appear.) For + example, click twice on the “typeset” or “build” or “PDFLATEX” button in your editor. + +

    -
    +

    🔗Option 2 (makeindex)

    +

    Example document: + + +

    +
    \documentclass{article}  
    \usepackage{glossaries} - 
    \makenoidxglossaries % use TeX to sort - 
    \newglossaryentry{sample}{name={sample}, - 
      description={an example}} +
    +

    +
    +\makeglossaries % open glossary files +
    +
    + + +
    +\newglossaryentry{sample}{name={sample}, + 
     description={an example}}  
    \begin{document}  
    \gls{sample}. - 
    \printnoidxglossary - 
    \end{document}
    -

    - -

    -

    -

    Option 2 (makeindex)

    -

    This option uses a 

    +
    +\printglossary +
    \end{document} +
    +
    You can place all your entry definitions in a separate file and load it in the preamble with \loadglsentries +(after \makeglossaries). +

    This option uses a CLI application called makeindex to sort the entries. This application -comes with all modern T to sort the entries. This application comes with all +modern TEX distributions, but it’s hard-coded for the non-extended Latin -alphabet. It can’t correctly sort accent commands (such as Latin alphabet. It can’t correctly sort +accent commands (such as \’ or \c) and fails with UTF-8 -characters, especially for any sort values that start with a UTF-8 character (as it separates -the octets resulting in an invalid file encoding). This process involves making LATEX write -the glossary information to a temporary file which \c) and fails with UTF-8 characters, especially for any sort values that start +with a UTF-8 character (as it separates the octets resulting in an invalid file encoding). This process involves +making LATEX write the glossary information to a temporary file which makeindex reads. Then reads. Then makeindex writes -a new file containing the code to typeset the glossary. Then \printglossary reads this file in -on the next run. -

    This option works best if you want to sort entries according to the English alphabet and -you don’t want to install Perl (or Java or you don’t want to use glossaries-extra). This method -can also work with the restricted shell escape since +writes a new file containing the code to typeset the glossary. Then \printglossary reads this file in on the +next run. +

    This option works best if you want to sort entries according to the English alphabet and you don’t want to +install Perl or Java. This method can also work with the restricted shell escape since makeindex is considered a trusted -application. (So you should be able to use the is considered a +trusted application. (So you should be able to use the automake package option provided the shell -escape hasn’t been completely disabled.) -

    This method can form ranges in the package option provided the shell escape hasn’t +been completely disabled.) +

    This method can form ranges in the number list but only accepts limited number formats: - but only accepts limited number formats: \arabic, \roman, \roman, +\Roman, \alph and \Alph. -

    This option does not allow a mixture of sort methods. All glossaries must be sorted -according to the same method: word/letter ordering or order of use or order of definition. If -you need word ordering for one glossary and letter ordering for another you’ll have to -explicitly call

    This option does not allow a mixture of sort methods. All glossaries must be sorted according to the same +method: word/letter ordering or order of use or order of definition. If you need word ordering for one +glossary and letter ordering for another you’ll have to explicitly call makeindex for each glossary type. (The glossaries-extra package allows a hybrid -mix of Options  for each glossary +type. +

    The glossaries-extra package allows a hybrid mix of Options 1 and 2 to provide word/letter ordering with Option 2 and order of -use/definition with Option 1. See the glossaries-extra documentation for further -details.) -

    +href="#option2">2 to provide word/letter ordering +with Option 2 and order of use/definition with Option 1. See the glossaries-extra documentation +for further details. See also the glossaries-extra alternative to sampleSort.tex in §19.5 Sorting. +

    +

    +

    1. If you want to use If you want to use makeindex’s ’s -g option you must change the quote character using - - - option you must change the quote character using \GlsSetQuote. For example: - - -
      + id="dx1-7017">. For + example: + + +
      \GlsSetQuote{+}
      -

      This must be used before

      This must be used before \makeglossaries. Note that if you are using babel, the - shorthands aren’t enabled until the start of the document, so you won’t be able to use - the shorthands in definitions made in the preamble. + id="dx1-7018">, the shorthands aren’t + enabled until the start of the document, so you won’t be able to use the shorthands in definitions made in + the preamble.

    2. Add - - -
      + class="enumerate" id="x1-7020x2">Add + + +
      \makeglossaries
      -

      to your preamble (before you start defining your entries, as described in §4 Defining - Glossary Entries). +

      to your preamble (before you start defining your entries, as described in §4 Defining Glossary + Entries).

    3. Put - - -
      + class="enumerate" id="x1-7022x3">Put + + +
      \printglossary
      -

      where you want your list of entries to appear (described in §10 Displaying a glossary). - Alternatively, to display all glossaries use the iterative command: - - +

      where you want your list of entries to appear (described in §10 Displaying a glossary). Alternatively, to + display all glossaries use the iterative command: + +

      -
      +
      \printglossaries
      -

      +

    4. Run LATRun LATEX on your document. This creates files with the extensions .glo and .ist - (for example, if your LATglo and ist (for example, if your + LATEX document is called myDoc.tex, then you’ll have two - extra files called myDoc.glo and myDoc.ist). If you look at your document - at this point, you won’t see the glossary as it hasn’t been created yet. (If - you use glossaries-extra you’ll see the section heading and some boilerplate +class="cmtt-10">myDoc.tex, then you’ll have two extra files called myDoc.glo and + myDoc.ist). If you look at your document at this point, you won’t see the glossary as it hasn’t been + created yet. (If you use glossaries-extra you’ll see the section heading and some boilerplate text.) -
    5. +

      If you have used package options such as symbols there will also be other sets of files corresponding to the + extra glossaries that were created by those options. +

    6. Run 🔗 Run makeindex with the with the .glo file as the input file and the .ist file as the style so - that it creates an output file with the extension .gls. If you have access to a - terminal or a command prompt (for example, the MSDOS command prompt for - Windows users or the bash console for Unix-like users) then you need to run the - command: - - -
      - makeindex -s myDoc.ist -o myDoc.gls myDoc.glo -
      -

      (Replace .ist file as the style so that it creates an + output file with the extension .gls. If you have access to a terminal or a command prompt (for example, + the MSDOS command prompt for Windows users or the bash console for Unix-like users) then you need to + run the command: +

      
      +     
      makeindex -s myDoc.ist -o myDoc.gls myDoc.glo +
      +
      + (Replace myDoc with the base name of your LATEX document file. Avoid spaces in the - file name if possible.) If you don’t know how to use the command prompt, - then you can probably access EX document file. Avoid spaces in the file name if + possible. The $ symbol indicates the command prompt and should be omitted.) +

      The file extensions vary according to the glossary type. See §1.4.4 Using makeindex via your text editor, but each editor - has a different method of doing this, so I can’t give a general description. - You will have to check your editor’s manual. The simplest approach is to use - explicitly (Option 2) + for further details. makeindex must be called for each set of files.
      +

      +

      If you don’t know how to use the command prompt, then you can probably access makeindex via your + text editor, but each editor has a different method of doing this. See Incorporating makeglossaries or + makeglossaries-lite or bib2gls into the document build for some examples. +

      Alternatively, run makeindex indirectly via the makeglossaries script: +

      
      +     
      makeglossaries myDoc +
      + + +
      + Note that the file extension isn’t supplied in this case. (Replace makeglossaries with + makeglossaries-lite if you don’t have Perl installed.) This will pick up all the file extensions + from the aux file and run makeindex the appropriate number of times with all the necessary + switches. +

      The simplest approach is to use arara and add the following comment lines to the start of your document: + id="dx1-7041"> and add the following comment lines to the start of your document:

       pdflatex
      (Replace makeglossaries with makeglossaries-lite if you don’t have Perl - installed.) -

      The default sort is word order (“sea lion” comes before “seal”). If you want letter - ordering you need to add the makeglossarieslite in the second line above if you don’t have Perl + installed. Note that there’s no hyphen in this case.) +

      The default sort is word order (“sea lion” comes before “seal”). If you want letter ordering you need to + add the -l switch: - - -

      -
      - makeindex -l -s myDoc.ist -o myDoc.gls myDoc.glo -
      -

      (See §1.5.4 switch: +

      
      +     
      makeindex -l -s myDoc.ist -o myDoc.gls myDoc.glo +
      +
      + (See §1.4.4 Using makeindex explicitly (Option 2) for further details on using - explicitly (Option 2) for further details on using makeindex explicitly.) If you use explicitly.) If you + use makeglossaries or or makeglossaries-lite - then use the order=letter package option and the then use the order=letter package option and the -l option will be added - automatically. + id="dx1-7048"> option + will be added automatically.

    7. Once you have successfully completed the previous step, you can now run LATEX on - your document again. You’ll need to repeat the process if you have used the 🔗 Once you have successfully completed the previous step, you can now run LATEX on your document + again.
    +

    You’ll need to repeat the last step if you have used the toc option - (unless you’re using glossaries-extra) to ensure the section heading is added - to the table of contents. You’ll also need to repeat the process if you have - any cross-references which can’t be indexed until the glossary file has been - created. -

    Complete example: - - -

    -
    -\documentclass{article} - 
    \usepackage{glossaries} - 
    \makeglossaries % open glossary files - 
    \newglossaryentry{sample}{name={sample}, - 
     description={an example}} - 
    \begin{document} - 
    \gls{sample}. - 
    \printglossary - 
    \end{document} -
    -

    + id="dx1-7051"> option (unless you’re using glossaries-extra) to ensure the +section heading is added to the table of contents. You’ll also need to repeat steps 5 and 6 if you have any +cross-references which can’t be indexed until the glossary file has been created. -

    + id="x1-7052r3"> +

    🔗Option 3 (xindy)

    -

    This option uses a 

    Example document:

    + + +
    +\newglossaryentry{sample}{name={sample}, + 
     description={an example}} + 
    \begin{document} + 
    \gls{sample}. +
    +

    +
    +\printglossary +
    \end{document} +
    +
    You can place all your entry definitions in a separate file and load it in the preamble with \loadglsentries +(after \makeglossaries). +

    This option uses a CLI application called xindy to sort the entries. This application is more -flexible than to sort the entries. This application is more flexible than +makeindex and is able to sort extended Latin alphabets or non-Latin alphabets, -however it does still have some limitations. -

    The non-Latin alphabets, however it does still have some +limitations. +

    The xindy application comes with both T application comes with both TEX Live and MiKTEX, but since xindy is a -Perl script, you will also need to install Perl, if you don’t already have it. In a similar way to -Option 2, this option involves making LATEX write the glossary information to -a temporary file which is a Perl script, you will +also need to install Perl, if you don’t already have it. In a similar way to Option 2, this option involves making +LATEX write the glossary information to a temporary file which xindy reads. Then reads. Then xindy writes a new file containing the -code to typeset the glossary. Then writes a new file +containing the code to typeset the glossary. Then \printglossary reads this file in on the next run. -

    This is the best option with just the base glossaries package if you want to sort according -to a language other than English or if you want non-standard location lists, but it can require -some setting up (see §11 Xindy (Option 3)). There are some problems with certain sort -values:

    +

    This is the best option with just the base glossaries package if you want to sort according to a language +other than English or if you want non-standard location lists, but it can require some setting up (see §11 Xindy +(Option 3)). There are some problems with certain sort values:

    • entries with the same sort value are merged by xindy into a single glossary line - so you must make sure that each entry has a unique sort value; + id="dx1-8010"> into a single glossary line so you must make + sure that each entry has a unique sort value;
    • xindy forbids empty sort values; + id="dx1-8011"> forbids empty sort values;
    • xindy automatically strips control sequences, the math-shift character $ and - braces {} from the sort value, which is usually desired but this can cause the sort - value to collapse to an empty string which automatically strips control sequences, the math-shift character $ and braces {} from the + sort value, which is usually desired but this can cause the sort value to collapse to an empty string + which xindy forbids.
    -

    In these problematic cases, you must set the sort field explicitly. For example: - - -

    -
    -\newglossaryentry{alpha}{name={\ensuremath{\alpha}}, - 
     sort={alpha},description={...}} -
    -

    -

    All glossaries must be sorted according to the same method (word/letter ordering, order -of use, or order of definition). (The glossaries-extra package allows a hybrid mix -of Options  forbids. +

    In these problematic cases, you must set the sort field explicitly. For example:

    +
    +\newglossaryentry{alpha}{name={\ensuremath{\alpha}}, +
     sort={alpha},description={...}} + + +
    +
    +

    The glossaries-extra package has a modified symbols package option that provides \glsxtrnewsymbol, which +automatically sets the sort key to the entry label (instead of the name).
    +

    +

    All glossaries must be sorted according to the same method (word/letter ordering, order of use, or order of +definition). +

    The glossaries-extra package allows a hybrid mix of Options 1 and 3 to provide word/letter ordering with Option 3 and order of -use/definition with Option 1. See the glossaries-extra documentation for further -details.) -

    +href="#option3">3 to provide word/letter ordering with +Option 3 and order of use/definition with Option 1. See the glossaries-extra documentation for further details. +

    +

    +

    1. Add the Add the xindy option to the option to the glossaries package option list: - - -
      + + +
      \usepackage[xindy]{glossaries}
      -

      If you are using a non-Latin script you’ll also need to either switch off the creation of - the number group: - - +

      If you are using a non-Latin script you’ll also need to either switch off the creation of the number + group: + +

      -
      +
      \usepackage[xindy={glsnumbers=false}]{glossaries}
      -

      or use either

      or use either \GlsSetXdyFirstLetterAfterDigits{letter} or \GlsSetXdyNumberGroupOrder - {} (to indicate the first letter group to follow the + digits) or \GlsSetXdyNumberGroupOrder{spec} to indicate where the number group should be placed (see §11 Xindy (Option - 3)). +class="cmtt-10">} to indicate where the number group should be placed (see + §11 Xindy (Option 3)).

    2. Add \makeglossaries to your preamble (before you start defining your entries, as - described in §4 Defining Glossary Entries). + class="enumerate" id="x1-8023x2">Add \makeglossaries to your preamble (before you start defining your entries, as described in §4 Defining + Glossary Entries).
    3. Run LATRun LATEX on your document. This creates files with the extensions .glo and .xdy - (for example, if your LATglo and xdy (for example, if your + LATEX document is called myDoc.tex, then you’ll have two extra - files called myDoc.tex, then you’ll have two extra files called myDoc.glo and myDoc.xdy). If you look at your document at this point, you - won’t see the glossary as it hasn’t been created yet. (If you’re using the extension - package glossaries-extra, you’ll see the section header and some boilerplate +class="cmtt-10">myDoc.xdy). + If you look at your document at this point, you won’t see the glossary as it hasn’t been created yet. (If + you’re using the glossaries-extra extension package, you’ll see the section header and some boilerplate text.) -
    4. +

      If you have used package options such as symbols there will also be other sets of files corresponding to the + extra glossaries that were created by those options. +

    5. Run Run xindy with the with the .glo file as the input file and the .xdy file as a module so that it - creates an output file with the extension .gls. You also need to set the language name - and input encoding. If you have access to a terminal or a command prompt - (for example, the MSDOS command prompt for Windows users or the bash - console for Unix-like users) then you need to run the command (all on one +class="cmtt-10">.xdy file as a module so that it creates an output + file with the extension .gls. You also need to set the language name and input encoding. If you have + access to a terminal or a command prompt (for example, the MSDOS command prompt for Windows + users or the bash console for Unix-like users) then you need to run the command (all on one line): - - -
      - xindy -L english -C utf8 -I xindy -M myDoc -  
      -t myDoc.glg -o myDoc.gls myDoc.glo -
      -

      (Replace

      
      +     
      xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.glg -o myDoc.gls myDoc.glo +
      +
      + (Replace myDoc with the base name of your LATEX document file. Avoid spaces in the - file name. If necessary, also replace EX document file. Avoid spaces in the file name. If + necessary, also replace english with the name of your language and utf8 - with your input encoding, for example, utf8 with your input encoding, for + example, -L german -C din5007-utf8.) Note that it’s - much simpler to use makeglossaries instead: - - -

      -
      - makeglossaries myDoc -
      -

      (Remember that din5007-utf8.) +

      The file extensions vary according to the glossary type. See §1.4.3 Using xindy is a Perl script so if you can use explicitly (Option 3) for + further details. xindy then you can also use - must be called for each set of files.
      +

      +

      It’s much simpler to use makeglossaries, and if you don’t want to use makeglossaries because you don’t want - to install Perl, then you can’t use instead: +

      
      +     
      makeglossaries myDoc + + +
      +
      + Note that the file extension isn’t supplied in this case. This will pick up all the file extensions from the aux + file and run xindy either.) -

      If you don’t know how to use the command prompt, then you can probably - access the appropriate number of times with all the necessary switches. +

      There’s no benefit in using makeglossaries-lite with xindy. (Remember that xindy is a Perl + script so if you can use xindy or then you can also use makeglossaries via your text editor, but each editor has a - different method of doing this, so I can’t give a general description. You - will have to check your editor’s manual. Again, a convenient method is to - use arara and add the follow comment lines to the start of your document: -

      + id="dx1-8044">, and if you don’t want + to use makeglossaries because you don’t want to install Perl, then you can’t use xindy + either.) +

      If you don’t know how to use the command prompt, then you can probably access xindy or + makeglossaries via your text editor, but each editor has a different method of doing this. See + Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build for some + examples. +

      Again, a convenient method is to use arara and add the follow comment lines to the start of your + document:

      % arara: pdflatex
      -

      The default sort is word order (“sea lion” comes before “seal”). If you want letter - ordering you need to add the order=letter package option: - - +

      The default sort is word order (“sea lion” comes before “seal”). If you want letter ordering you need to + add the order=letter package option: + +

      \usepackage[xindy,order=letter]{glossaries}
      -

      (and return to the previous step). This option is picked up by

      (and return to the previous step). This option is picked up by makeglossaries. If you - are explicitly using . If you are explicitly using + xindy then you’ll need to add -M ord/letorder to the options list. - See §1.5.3 then you’ll need to add -M ord/letorder to the options list. See §1.4.3 Using xindy explicitly (Option 3) for further details on using explicitly + (Option 3) for further details on using xindy - explicitly. + id="dx1-8053"> explicitly.

    6. Once you have successfully completed the previous step, you can now run - LATEX on your document again. As with the previous option, you may need to - repeat the process to ensure the table of contents and cross-references are - resolved. + class="enumerate" id="x1-8055x5">Once you have successfully completed the previous step, you can now run LATEX on your document + again. As with makeindex (Option 2), you may need to repeat the previous step and this step to ensure + the table of contents and cross-references are resolved.
    -

    Complete example: - - -

    -
    -\documentclass{article} - 
    \usepackage[xindy]{glossaries} - 
    \makeglossaries % open glossary files - 
    \newglossaryentry{sample}{name={sample}, - 
     description={an example}} - 
    \begin{document} - 
    \gls{sample}. - 
    \printglossary - 
    \end{document} -
    -

    -

    + id="x1-8057r4"> +

    🔗Option 4 (bib2gls)

    -

    This option is only available with the extension package


    glossaries-extraThis option is only available with the glossaries-extra. This method uses +class="cmss-10">glossaries-extra extension package. This method uses bib2gls to both fetch entry definitions from .bib files and to hierarchically sort and -collate. -

    All entries must be provided in one or more .bib files. (See the bib files and to hierarchically sort and collate. +

    Example document:

    +
    +\documentclass{article} +
    \usepackage[record=nameref]{glossaries-extra} +
    \GlsXtrLoadResources[src={entries}] +
    \begin{document} +
    \gls{sample}, \gls{alpha}, \gls{html}. +
    \printunsrtglossary +
    \end{document} +
    +
    where the file entries.bib contains:
    +
    +@entry{sample, +
      name={sample}, +
      description={an example} +
    } + + +
    @symbol{alpha, +
      name={\ensuremath{\alpha}}, +
      description={...} +
    } +
    @abbreviation{html, +
      short={HTML}, +
      long={hypertext markup language} +
    } +
    +
    +

    All entries must be provided in one or more bib files. See the bib2gls user manual for -the required format.) The glossaries-extra package needs to be loaded with the record package -option - - -

    -
    -\usepackage[record]{glossaries-extra} + id="dx1-9010"> user manual for the required +format. +

    Note that the sort key should not be used. Each entry type (@entry, @symbol, @abbreviation) +has a particular field that’s used for the sort value by default (name, the label, short). You will +break this mechanism if you explicitly use the sort key. See bib2gls gallery: sorting for examples. +
    +

    +

    The glossaries-extra package needs to be loaded with the record package option:

    +
    +\usepackage[record]{glossaries-extra}
    -

    or (equivalently) - - -

    -
    -\usepackage[record=only]{glossaries-extra} +
    or (equivalently)
    +
    +\usepackage[record=only]{glossaries-extra} +
    +
    or (with at least glossaries-extra v1.37 and bib2gls v1.8):
    +
    +\usepackage[record=nameref]{glossaries-extra}
    -

    (It’s possible to use a hybrid of this method and Options  The record=nameref option is the best method. +

    (It’s possible to use a hybrid of this method and Options 2 or 3 with record=alsoindex but in -general there is little need for this and it complicates the build process.) -

    Each resource set is loaded with \GlsXtrLoadResources[3 with record=alsoindex but in general there is +little need for this and it complicates the build process.) +

    Each resource set is loaded with \GlsXtrLoadResources[options]. For example: - - -

    -
    -\GlsXtrLoadResources - 
    [% definitions in entries1.bib and entries2.bib: - 
     src={entries1,entries2}, - 
     sort={de-CH-1996}% sort according to this locale - 
    ] -
    -

    You can have multiple resource commands. -

    The glossary is displayed using - - -

    -
    -\printunsrtglossary -
    -

    Alternatively all glossaries can be displayed using the iterative command: - - -

    -
    -\printunsrtglossaries -
    -

    The document is build using: - - -

    -
    -pdflatex myDoc - 
    bib2gls myDoc - 
    pdflatex myDoc +class="cmtt-10">]. For example:

    +
    +\GlsXtrLoadResources +
    [% definitions in entries1.bib and entries2.bib: + + +
     src={entries1,entries2}, +
     sort={de-CH-1996}% sort according to this locale +
    ]
    -

    If letter groups are required, you need the --group switch: - - -

    -
    -bib2gls --group myDoc +
    The bib files are identified as a comma-separated list in the value of the src key. The sort option identifies the +sorting method. This may be a locale identifier for alphabetic sorting, but there are other sort methods +available, such as character code or numeric. One resource set may cover multiple glossaries or one glossary may +be split across multiple resource sets, forming logical sub-blocks. +

    If you want to ensure that all entries are selected, even if they haven’t been referenced in the document, then +add the option selection=all. (There are also ways of filtering the selection or you can even have a +random selection by shuffling and truncating the list. See the bib2gls user manual for further +details.) +

    The glossary is displayed using:

    +
    +\printunsrtglossary
    -

    Unlike Options  Alternatively all glossaries can be displayed using the iterative command:

    The document is built using: +

    
    +   
    pdflatex myDoc +
    bib2gls myDoc +
    pdflatex myDoc +
    +
    +If letter groups are required, you need the --group switch: +

    
    +   
    bib2gls --group myDoc +
    +
    +or with arara:

    +
    +% arara: bib2gls: { group: on } +
    +
    (You will also need an appropriate glossary style.) +

    Unlike Options 2 and 3, this method doesn’t create a file containing the typeset glossary but -simply determines which entries are needed for the document, their associated locations and -(if required) their associated letter group. This option allows a mixture of sort methods. -(For example, sorting by word order for one glossary and order of use for another -or even sorting one block of the glossary differently to another block in the same -glossary.) -

    This method supports Unicode and (with at least Java 8) uses the Common -Locale Data Repository, which provides more extensive language support than -3, this method doesn’t create a file containing the typeset glossary but simply +determines which entries are needed for the document, their associated locations and (if required) their +associated letter group. This option allows a mixture of sort methods. For example, sorting by word order for + + +one glossary and order of use for another or even sorting one block of the glossary differently to another block in +the same glossary. See bib2gls gallery: sorting. +

    This method supports Unicode and uses the Common Locale Data Repository, which provides more extensive language support +than xindy..1.2 The + id="x1-9036f2"> The locations in the number list may be in any format. If may be in any format. If bib2gls can deduce a numerical value it -will attempt to form ranges otherwise it will simply list the locations. -

    Complete example: - - -

    -
    -\documentclass{article} - 
    \usepackage[record]{glossaries-extra} - 
    \GlsXtrLoadResources[src={entries}] - 
    \begin{document} - 
    \gls{sample}. - 
    \printunsrtglossary - 
    \end{document} -
    -

    where entries.bib contains - - -

    -
    -@entry{sample, - 
     name={sample}, - 
     description={an example} - 
    } -
    -

    See the can deduce a numerical value it will attempt to +form ranges otherwise it will simply list the locations. +

    See glossaries-extra and bib2gls: An Introductory Guide or the bib2gls user manual for further details. + id="dx1-9040"> user manual for further details of +this method, and also Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document +build. -

    + id="x1-9041r5"> +

    🔗Option 5 (no sorting)

    -

    This option is only available with the extension package


    glossaries-extraThis option is only available with the extension package glossaries-extra. No indexing -application is required. This method is best used with the package option sort=none. - - +href="#glo:indexingapp">indexing application +is required. +

    Example document: + +

    -
    -\usepackage[sort=none]{glossaries-extra} +
    +\documentclass{article} + 
    \usepackage[sort=none]{glossaries-extra} + 
    \newglossaryentry{sample}{name={sample}, + 
     description={an example}} + 
    \newglossaryentry{alpha}{name={\ensuremath{\alpha}}, + 
     description={...}} + 
    \begin{document} + 
    \gls{sample}. +
    +

    +
    +\printunsrtglossary +
    \end{document}
    -

    There’s no “activation” command (such as +

    This method is best used with the package option sort=none (as shown above). There’s no “activation” +command (such as \makeglossaries for Options 2 and 3). -

    All entries must be defined before the glossary is displayed (preferably in the preamble) in -the required order, and child entries must be defined immediately after their parent entry if -they must be kept together in the glossary -

    The glossary is displayed using - - -

    -
    -\printunsrtglossary -
    -

    Alternatively all glossaries can be displayed using the iterative command: - - -

    -
    -\printunsrtglossaries -
    -

    This will display all defined entries, regardless of whether or not they have been used in the -document. The

    All entries must be defined before the glossary is displayed (preferably in the preamble) in the +required order, and child entries must be defined immediately after their parent entry if they must be +kept together in the glossary. (Some glossary styles indent entries that have a parent but it’s the +indexing application that ensures the child entries are listed immediately after the parent. If you’re +opting to use this manual approach then it’s your responsibility to define the entries in the correct +order.) You can place all your entry definitions in a separate file and load it in the preamble with +\loadglsentries. +

    The glossary is displayed using:

    +
    +\printunsrtglossary +
    +
    Alternatively all glossaries can be displayed using the iterative command:
    +
    +\printunsrtglossaries +
    +
    This will display all defined entries, regardless of whether or not they have been used in the document. The +number lists have to be set explicitly otherwise they won’t appear. Note -that this uses the same command for displaying the glossary as Option 4. This is -because s have to be set explicitly otherwise they won’t appear. Note that this uses the same command for +displaying the glossary as Option 4. This is because bib2gls takes advantage of this method by defining the wanted entries -in the required order and setting the locations (and letter group information, if + id="dx1-10007"> takes advantage of this method by defining the +wanted entries in the required order and setting the locations (and letter group information, if required). -

    This just requires a single LATEX call - - -

    -
    -pdflatex myDoc -
    -

    unless the glossary needs to appear in the table of contents, in which case a second run is -required. - - + + +

    Therefore, the above example document has a glossary containing the entries: sample and α (in +that order). Note that the alpha entry has been included even though it wasn’t referenced in the +document. +

    This just requires a single LATEX call: +

    
    +   
    pdflatex myDoc +
    +
    +unless the glossary needs to appear in the table of contents, in which case a second run is required: +

    
    +   
    pdflatex myDoc +
    pdflatex myDoc +
    +
    +(Naturally if the document also contains citations, and so on, then additional steps are required. Similarly for all +the other options above.) +

    See the glossaries-extra documentation for further details of this method. + +

    -
    -pdflatex myDoc - 
    pdflatex myDoc -
    -

    (Naturally if the document also contains citations, and so on, then additional steps are -required. Similarly for all the other options above.) -

    Complete example: - - +

    🔗Option 6 (standalone)

    +


    glossaries-extraThis option is only available with the glossaries-extra extension +package.1.3 +Instead of creating a list, this has standalone definitions throughout the document. The entry name may or may +not be in a section heading. +

    You can either define entries in the document preamble (or in an external file loaded with \loadglsentries), as +with Option 5, for example: + +

    -
    +
    \documentclass{article} - 
    \usepackage[sort=none]{glossaries-extra} - 
    \newglossaryentry{sample}{name={sample}, - 
     description={an example}} - 
    \begin{document} - 
    \gls{sample}. - 
    \printunsrtglossary + 
    \usepackage[colorlinks]{hyperref} + 
    \usepackage[sort=none, + 
       nostyles% <- no glossary styles are required + 
     ]{glossaries-extra} + 
    \newglossaryentry{set}{name={set}, + 
      description={a collection of any kind of objects}, + 
      symbol={\ensuremath{\mathcal{S}}} + 
    } + 
    \newglossaryentry{function}{name={function}, + 
      description={a rule that assigns every element in the + 
      domain \gls{set} to an element in the range \gls{set}}, + 
      symbol={\ensuremath{f(x)}} + 
    } +
    +

    +
    +\newcommand*{\termdef}[1]{% +
      \section{\glsxtrglossentry{#1} \glsentrysymbol{#1}}% +
      \begin{quote}\em\Glsentrydesc{#1}.\end{quote}% +
    } +
    +
    + + +
    +\begin{document} + 
    \tableofcontents + 
    \section{Introduction} + 
    Sample document about \glspl{function} and \glspl{set}. + 
    \termdef{set} + 
    More detailed information about \glspl{set} with examples. + 
    \termdef{function} + 
    More detailed information about \glspl{function} with examples.  
    \end{document}
    -

    See the glossaries-extra documentation for further details. -

    -

    -

    Top

    1.2 Sample Documents

    -

    The glossaries package is provided with some sample documents that illustrate the -various functions. These should be located in the samples subdirectory (folder) -of the glossaries documentation directory. This location varies according to your -operating system and TEX distribution. You can use texdoc to locate the main -glossaries documentation. For example, in a terminal or command prompt, type: - -
    texdoc -l glossaries
    -

    -This should display a list of all the files in the glossaries documentation directory with -their full pathnames. (The GUI version of texdoc may also provide you with the -information.) -

    If you can’t find the sample files on your computer, they are also available from your nearest -CTAN mirror at http://mirror.ctan.org/macros/latex/contrib/glossaries/samples/. -

    The sample documents are listed -below1.3 If -you prefer to use UTF-8 aware engines (xelatex or lualatex) remember that you’ll need to -switch from fontenc & inputenc to fontspec where appropriate. The

    Or you can use bib2gls if you want to manage a large database of terms. For example (requires glossaries-extra package -provides some additional sample files. -

    -minimalgls.tex
    This document is a minimal working example. You can test your - installation using this file. To create the complete document you will need to do the - following steps: -
      -
    1. Run minimalgls.tex through LATEX either by typing -
      latex minimalgls
      - - -

      - in a terminal or by using the relevant button or menu item in your text editor or - front-end. This will create the required associated files but you will not see the - glossary. If you use PDFLATEX you will also get warnings about non-existent - references that look something like: - - -

      -
      - pdfTeX warning (dest): name{glo:aca} has been -  
      referenced but does not exist, -  
      replaced by a fixed one -
      -

      These warnings may be ignored on the first run. -

      If you get a Missing \begin{document} error, then it’s most likely that - your version of xkeyval is out of date. Check the log file for a warning - of that nature. If this is the case, you will need to update the xkeyval - package. -

    2. -
    3. If you have Perl installed, run makeglossaries on the document (§1.5 Generating - the Associated Glossary Files). This can be done on a terminal by typing - -
      makeglossaries minimalgls
      -

      - otherwise do -
      makeglossaries-lite minimalgls
      -

      - If for some reason you want to call makeindex explicitly, you can do this in a - terminal by typing (all on one line): -
      makeindex -s minimalgls.ist -t minimalgls.glg -o minimalgls.gls - minimalgls.glo
      -

      - (See §1.5.4 Using makeindex explicitly (Option 2) for further details on using - makeindex explicitly.) -

      Note that if the file name contains spaces, you will need to use the double-quote - character to delimit the name. -

    4. -
    5. Run minimalgls.tex through LATEX again (as step 1)
    -

    You should now have a complete document. The number following each entry in the - glossary is the location number. By default, this is the page number where the entry - was referenced. -

    There are three other files that can be used as a minimal working example: - mwe-gls.tex, mwe-acr.tex and mwe-acr-desc.tex. -

    -sample-noidxapp.tex
    This document illustrates how to use the glossaries package without - an external indexing application (Option 1). To create the complete document, you - need to do: -
    latex sample-noidxapp - - -
    latex sample-noidxapp
    -

    -

    -sample-noidxapp-utf8.tex
    As the previous example, except that it uses the inputenc - package. To create the complete document, you need to do: -
    latex sample-noidxapp-utf8 -
    latex sample-noidxapp-utf8
    -

    -

    -sample4col.tex
    This document illustrates a four column glossary where the entries have a - symbol in addition to the name and description. To create the complete document, you - need to do: -
    latex sample4col -
    makeglossaries sample4col -
    latex sample4col
    -

    - or -
    latex sample4col -
    makeglossaries-lite sample4col -
    latex sample4col
    -

    - The vertical gap between entries is the gap created at the start of each group. This can - be suppressed using the nogroupskip package option. -

    -sampleAcr.tex
    This document has some sample abbreviations. It also adds the glossary to - the table of contents, so an extra run through LATEX is required to ensure the - document is up to date: -
    latex sampleAcr -
    makeglossaries sampleAcr -
    latex sampleAcr -
    latex sampleAcr
    -

    - (or use makeglossaries-lite). -

    -sampleAcrDesc.tex
    This is similar to the previous example, except that the abbreviations - have an associated description. As with the previous example, the glossary is - - - added to the table of contents, so an extra run through LATEX is required: - -
    latex sampleAcrDesc -
    makeglossaries sampleAcrDesc -
    latex sampleAcrDesc -
    latex sampleAcrDesc
    -

    -

    +class="cmss-10">glossaries-extra +v1.42, see below):

    +
    sampleDesc.tex
    This is similar to the previous example, except that it defines the - abbreviations using \newglossaryentry instead of \newacronym. As with the previous - example, the glossary is added to the table of contents, so an extra run through - LATEX is required: -
    latex sampleDesc -
    makeglossaries sampleDesc -
    latex sampleDesc -
    latex sampleDesc
    -

    -

    +class="cmtt-10">\documentclass{article} +
    +
    \usepackage[colorlinks]{hyperref} +
    \usepackage[record, +
       nostyles% <- no glossary styles are required +
      ]{glossaries-extra} +
    +
    \GlsXtrLoadResources[src=terms,sort=none,save-locations=false] +
    +
    \newcommand*{\termdef}[1]{% +
      \section{\glsxtrglossentry{#1} \glossentrysymbol{#1}}% +
      \glsadd{#1}% <- index this entry +
      \begin{quote}\em\Glsentrydesc{#1}.\end{quote}% +
    } +
    +
    + + +
    +\begin{document} + 
    \tableofcontents + 
    \section{Introduction} + 
    Sample document about \glspl{function} and \glspl{set}. + 
    \termdef{set} + 
    More detailed information about \glspl{set} with examples. + 
    \termdef{function} + 
    More detailed information about \glspl{function} with examples. + 
    \end{document} +
    +

    Where the file terms.bib contains:

    +
    +@entry{set, +
      name={set}, +
      description={a collection of any kind of objects}, +
      symbol={\ensuremath{\mathcal{S}}} +
    } +
    @entry{function, +
      name={function}, +
      description={a rule that assigns every element in the domain +
      \gls{set} to an element in the range \gls{set}}, +
      symbol={\ensuremath{f(x)}} +
    } +
    +
    The advantage in this approach (with \loadglsentries or bib2gls) is that you can use an existing database +of entries shared across multiple documents, ensuring consistent notation for all of them. +

    In both cases, there’s no need to load all the glossary styles packages, as they’re not required, so I’ve used +the nostyles package option to prevent them from being loaded. +

    In the first case, you need the sort=none package option (as in Option 5) and then define the terms in the +preamble. No external tool is required. Just run LATEX as normal. (Twice to ensure that the table of contents +is up to date.) +

    
    +   
    pdflatex myDoc +
    pdflatex myDoc +
    + + +
    +

    In the second case, you need the record package option (as in Option 4) since bib2gls is needed to select the +required entries, but you don’t need a sorted list:

    +
    +\GlsXtrLoadResources[src={terms},sort=none] +
    +
    This will ensure that any entries indexed in the document (through commands like \gls or \glsadd) will be +selected by bib2gls, but it will skip the sorting step. (The chances are you probably also won’t need location +lists either. If so, you can add the option save-locations=false.) +

    Remember that for this second case you need to run bib2gls as per Option 4: +

    
    +   
    pdflatex myDoc +
    bib2gls myDoc +
    pdflatex myDoc +
    pdflatex myDoc +
    +
    +

    For both cases (with or without bib2gls), instead of listing all the entries using \printunsrtglossary, you +use \glsxtrglossentry{label} where you want the name (and anchor with hyperref) to appear in the +document. This will allow the link text created by commands like \gls to link to that point in the document. +The description can simply be displayed with \glsentrydesc{label} or \Glsentrydesc{label}, as in the above +examples. In both examples, I’ve defined a custom command \termdef to simplify the code and ensure +consistency. Extra styling, such as placing the description in a coloured frame, can be added to this custom +definition as required. +

    (Instead of using \glsentrydesc or \Glsentrydesc, you can use \glossentrydesc{label}, which +will obey attributes such as glossdesc and glossdescfont. See the glossaries-extra manual for further +details.) +

    The symbol (if required) can be displayed with either \glsentrysymbol{label} or \glossentrysymbol sampleCustomAcr.tex

    This document has some sample abbreviations with a custom - acronym style. It also adds the glossary to the table of contents, so an extra run through - LATEX is required: -
    latex sampleCustomAcr -
    makeglossaries sampleCustomAcr -
    latex sampleCustomAcr -
    latex sampleCustomAcr
    -

    -

    +class="cmtt-10">{⟨label}. In the first example, I’ve used \glsentrysymbol. In the second I’ve used \glossentrysymbol. The +latter is necessary with bib2gls if the symbol needs to go in a section title as the entries aren’t defined on the +first LATEX run. +

    In normal document text, \glsentrysymbol will silently do nothing if the entry hasn’t been defined, but +when used in a section heading it will expand to an undefined internal command when written to the aux file, +which triggers an error. +

    The \glossentrysymbol command performs an existence check, which triggers a warning if the entry is undefined. +(All entries will be undefined before the first bib2gls call.) You need at least glossaries-extra v1.42 to use this command in +a section title.1.4 +If hyperref has been loaded, this will use \texorpdfstring to allow a simple expansion for the PDF bookmarks +(see the glossaries-extra user manual for further details). +

    If you want to test if the symbol field has been set, you need to use \ifglshassymbol outside of the section +title. For example:

    + + +
    sampleFnAcrDesc.tex
    This is similar to sampleAcrDesc.tex, except that it uses the - footnote-sc-desc style. As with the previous example, the glossary is added to the table - of contents, so an extra run through LATEX is required: -
    latex sampleFnAcrDesc -
    makeglossaries sampleFnAcrDesc -
    latex sampleFnAcrDesc -
    latex sampleFnAcrDesc
    -

    - - -

    +class="cmtt-10">\ifglshassymbol{#1}% +
    {\section{\glsxtrglossentry{#1} \glossentrysymbol{#1}}} +
    {\section{\glsxtrglossentry{#1}}} +
    +
    +

    In both of the above examples, the section titles start with a lowercase character (because the name value is +all lowercase in entry definitions). You can apply automatic case-change with the glossname attribute. For +example:

    +
    +\glssetcategoryattribute{general}{glossname}{firstuc} +
    +
    or (for title-case)
    +
    +\glssetcategoryattribute{general}{glossname}{title} +
    +
    However, this won’t apply the case-change in the table of contents or bookmarks. +

    In the second example, you can instead use bib2gls to apply a case-change:

    +
    sample-FnDesc.tex
    This example defines a custom display format that puts the description - in a footnote on first use. -
    latex sample-FnDesc -
    makeglossaries sample-FnDesc -
    latex sample-FnDesc
    -

    -

    +class="cmtt-10">\GlsXtrLoadResources[src=terms, +
     sort=none,save-locations=false, +
     replicate-fields={name=text}, +
     name-case-change=firstuc
    +
    ] +
    +
    (Or name-case-change=title for title-case.) This copies the name value to the text field and +then applies a case-change to the name field (leaving the text field unchanged). The name in the +section titles now starts with a capital but the link text produced by commands like \gls is still +lowercase. +

    In the first example (without bib2gls) you need to do this manually. For example:

    +
    sample-custom-acronym.tex
    This document illustrates how to define your own acronym - style if the predefined styles don’t suit your requirements. -
    latex sample-custom-acronym -
    makeglossaries sample-custom-acronym -
    latex sample-custom-acronym
    -

    +class="cmtt-10">\newglossaryentry{set}{name={Set},text={set}, +
      description={a collection of any kind of objects}, +
      symbol={\ensuremath{\mathcal{S}}} +
    } + + +

    +
    +

    Note that if you use the default save-locations=true with bib2gls, it’s possible to combine Options 4 +and 6 to have both standalone definitions and an index. Now I do need a glossary style. In this case I’m going +to use bookindex, which is provided in the glossary-bookindex package (bundled with glossaries-extra). I don’t +need any of the other style packages, so I can still keep the nostyles option and just load glossary-bookindex: +

    +
    +\usepackage[record=nameref,% <- using bib2gls +
     nostyles,% <- don't load default style packages +
     stylemods=bookindex,% <- load glossary-bookindex.sty +
     style=bookindex% <- set the default style to 'bookindex' +
    ]{glossaries-extra} +
    +
    I also need to sort the entries, so the resource command is now:
    +
    +\GlsXtrLoadResources[src=terms,% definitions in terms.bib +
     sort=en-GB,% sort by this locale +
     replicate-fields={name=text}, +
     name-case-change={firstuc} +
    ] +
    +
    At the end of the document, I can add the glossary:
    +
    +\printunsrtglossary[title=Index,target=false] +
    +
    Note that I’ve had to switch off the hypertargets with target=false (otherwise there would be duplicate +targets). If you want letter group headings you need to use the --group switch: +

    
    +   
    bib2gls --group myDoc +
    +
    +or if you are using arara:

    +
    +% arara: bib2gls: { group: on } +
    +
    + + +

    The bookindex style doesn’t show the description, so only the name and location is displayed. Remember +that the name has had a case-conversion so it now starts with an initial capital. If you feel this is inappropriate +for the index, you can adjust the bookindex style so that it uses the text field instead. For example: +

    +
    +\renewcommand*{\glsxtrbookindexname}[1]{% +
      \glossentrynameother{#1}{text}} +
    +
    See the glossaries-extra user manual for further details about this style. +

    Note that on the first LATEX run none of the entries will be defined. Once they are defined, the page +numbers may shift due to the increased amount of document text. You may therefore need to repeat the +document build to ensure the page numbers are correct. +

    If there are extra terms that need to be included in the index that don’t have a description, you can define +them with @index in the bib file. For example:

    +
    +@index{element} +
    @index{member,alias={element}} +
    +
    They can be used in the document as usual: + + +
    +The objects that make up a set are the \glspl{element} + 
    or \glspl{member}. +
    +

    See glossaries-extra and bib2gls: An Introductory Guide or the bib2gls user manual for further +details. +

    The glossaries package comes with a number of sample documents that illustrate the various functions. These +are listed in §19 Sample Documents. +

    +

    +

    Top

    1.2 Dummy Entries for Testing

    +

    In addition to the sample files described above, glossaries also provides some files containing lorum +ipsum dummy entries. These are provided for testing purposes and are on TEX’s path (in +tex/latex/glossaries/test-entries) so they can be included via \input or \loadglsentries. The +glossaries-extra package provides bib versions of all these files for use with bib2gls. The files are as +follows: +

    +example-glossaries-brief.tex
    These entries all have brief descriptions. For example: + + +
    + \newglossaryentry{lorem}{name={lorem},description={ipsum}} +
    +

    sample-crossref.tex
    This document illustrates how to cross-reference entries in the - glossary. -
    latex sample-crossref -
    makeglossaries sample-crossref -
    latex sample-crossref
    -

    +class="cmbx-10">example-glossaries-long.tex

    These entries all have long descriptions. For example: + + +
    + \newglossaryentry{loremipsum}{name={lorem ipsum}, +  
    description={dolor sit amet, consectetuer adipiscing +  
    elit. Ut purus elit, vestibulum ut, placerat ac, +  
    adipiscing vitae, felis. Curabitur dictum gravida +  
    mauris.}} +
    +

    sample-dot-abbr.tex
    This document illustrates how to use the post link hook to adjust the - space factor after abbreviations. -
    latex sample-dot-abbr -
    makeglossaries sampledot-abbrf -
    latex sample-dot-abbr
    -

    +class="cmbx-10">example-glossaries-multipar.tex

    These entries all have multi-paragraph descriptions. For example: + + +
    + \longnewglossaryentry{loremi-ii}{name={lorem 1--2}}% +  
    {% +  
    Lorem ipsum ... +  
    Nam dui ligula... +  
    } +
    +

    sampleDB.tex
    This document illustrates how to load external files containing the glossary - definitions. It also illustrates how to define a new glossary type. This document has the - number list suppressed and uses \glsaddall to add all the entries to the - glossaries without referencing each one explicitly. To create the document do: - - - -
    latex sampleDB -
    makeglossaries sampleDB -
    latex sampleDB
    -

    - or -
    latex sampleDB -
    makeglossaries-lite sampleDB -
    latex sampleDB
    -

    - The glossary definitions are stored in the accompanying files database1.tex and - database2.tex. If for some reason you want to call makeindex explicitly you must have - a separate call for each glossary: -

      -
    1. - Create - the - main - glossary - (all - on - one - line): - -
      makeindex - -s - sampleDB.ist - -t - sampleDB.glg - -o - sampleDB.gls - sampleDB.glo
      -

      -

    2. -
    3. - Create - the - secondary - glossary - (all - on - - - one - line): - -
      makeindex - -s - sampleDB.ist - -t - sampleDB.nlg - -o - sampleDB.not - sampleDB.ntn
      -

      - Note that both makeglossaries and makeglossaries-lite do this all in one call, - so they not only make it easier because you don’t need to supply all the switches - and remember all the extensions but they also call makeindex the appropriate - number of times.

    -
    -sampleEq.tex
    This document illustrates how to change the location to something other - than the page number. In this case, the equation counter is used since all glossary - entries appear inside an equation environment. To create the document do: - -
    latex sampleEq -
    makeglossaries sampleEq -
    latex sampleEq
    -

    +class="cmbx-10">example-glossaries-symbols.tex

    These entries all use the symbol key. For example: + + +
    + \newglossaryentry{alpha}{name={alpha}, +  
    symbol={\ensuremath{\alpha}}, +  
    description={Quisque ullamcorper placerat ipsum.}} +
    +

    sampleEqPg.tex
    This is similar to the previous example, but the number lists - are a mixture of page numbers and equation numbers. This example adds - the glossary to the table of contents, so an extra LATEX run is required: - -
    latex sampleEqPg -
    makeglossaries sampleEqPg -
    latex sampleEqPg -
    latex sampleEqPg
    -

    +class="cmbx-10">example-glossaries-symbolnames.tex

    Similar to the previous file but the symbol key isn’t used. Instead the + symbol is stored in the name key. For example: + + +
    + \newglossaryentry{sym.alpha}{sort={alpha}, +  
    name={\ensuremath{\alpha}}, +  
    description={Quisque ullamcorper placerat ipsum.}} +
    +

    sampleSec.tex
    This document also illustrates how to change the location to something - other than the page number. In this case, the section counter is used. This example - adds the glossary to the table of contents, so an extra LATEX run is required: - - - -
    latex sampleSec -
    makeglossaries sampleSec -
    latex sampleSec -
    latex sampleSec
    -

    +class="cmbx-10">example-glossaries-images.tex

    These entries use the user1 key to store the name of an image file. (The + images are provided by the mwe package and should be on TEX’s path.) One entry doesn’t have an + associated image to help test for a missing key. The descriptions are long to allow for tests with the text + wrapping around the image. For example: + + +
    + \longnewglossaryentry{sedfeugiat}{name={sed feugiat}, +  
    user1={example-image}}% +  
    {% +  
    Cum sociis natoque... +  
    Etiam... +  
    } +
    +

    sampleNtn.tex
    This document illustrates how to create an additional glossary type. This - example adds the glossary to the table of contents, so an extra LATEX run is required: - -
    latex sampleNtn -
    makeglossaries sampleNtn -
    latex sampleNtn -
    latex sampleNtn
    -

    - Note that if you want to call makeindex explicitly instead of using makeglossaries or - makeglossaries-lite then you need to call makeindex twice: -

      -
    1. - Create - the - main - glossary - (all - on - one - line): - -
      makeindex - -s - sampleNtn.ist - -t - sampleNtn.glg - -o - sampleNtn.gls - sampleNtn.glo
      -

      -

    2. - - -
    3. - Create - the - secondary - glossary - (all - on - one - line): - -
      makeindex - -s - sampleNtn.ist - -t - sampleNtn.nlg - -o - sampleNtn.not - sampleNtn.ntn
      -

      -

    -
    +class="cmbx-10">example-glossaries-acronym.tex
    These entries are all abbreviations. For example: + + +
    + \newacronym[type=\glsdefaulttype]{lid}{LID}{lorem ipsum +  
    dolor} +
    +

    +

    If you use the glossaries-extra extension package, then \newacronym is redefined to use \newabbreviation + with the category key set to acronym (rather than the default abbreviation). This means that you need + to set the abbreviation style for the acronym category. For example: + + +

    +
    + \setabbreviationstyle[acronym]{long-short} +
    +

    +

    +

    sample.tex
    This document illustrates some of the basics, including how to create child - entries that use the same name as the parent entry. This example adds the glossary to - the table of contents and it also uses \glsrefentry, so an extra LATEX run is - required: -
    latex sample -
    makeglossaries sample -
    latex sample -
    latex sample
    -

    - You can see the difference between word and letter ordering if you substitute +class="cmbx-10">example-glossaries-acronym-desc.tex

    This file contains entries that are all abbreviations that use the order=word with order=letter. (Note that this will only have an effect if you use - makeglossaries or makeglossaries-lite. If you use makeindex explicitly, you will - need to use the -l switch to indicate letter ordering.) +class="cmtt-10">description key. For example: + + +
    + \newacronym[type=\glsdefaulttype, +  
      description={fringilla a, euismod sodales, +  
      sollicitudin vel, wisi}]{ndl}{NDL}{nam dui ligula} +
    +

    +

    If you use the glossaries-extra extension package, then \newacronym is redefined to use \newabbreviation + with the category key set to acronym (rather than the default abbreviation). This means that you need + to set the abbreviation style for the acronym category. For example: + + +

    +
    + \setabbreviationstyle[acronym]{long-short-desc} +
    +

    +

    sample-inline.tex
    This document is like sample.tex, above, but uses the inline glossary - style to put the glossary in a footnote. -
    +class="cmbx-10">example-glossaries-acronyms-lang.tex
    These entries are all abbreviations, where some of them have + a translation supplied in the user1 key. For example: + + +
    + \newacronym[type=\glsdefaulttype,user1={love itself}] +  
     {li}{LI}{lorem ipsum} +
    +

    +

    If you use the glossaries-extra extension package, then \newacronym is redefined to use \newabbreviation + with the category key set to acronym (rather than the default abbreviation). This means that you need + to set the abbreviation style for the acronym category. For example: + + +

    +
    + \setabbreviationstyle[acronym]{long-short-user} +
    +

    +

    +

    sampletree.tex
    This document illustrates a hierarchical glossary structure where child - entries have different names to their corresponding parent entry. To create the - document do: -
    latex sampletree - - -
    makeglossaries sampletree -
    latex sampletree
    -

    +class="cmbx-10">example-glossaries-parent.tex

    These are hierarchical entries where the child entries use the name key. For + example: + + +
    + \newglossaryentry{sedmattis}{name={sed mattis}, +  
    description={erat sit amet} +  
    \newglossaryentry{gravida}{parent={sedmattis}, +  
      name={gravida},description={malesuada}} +
    +

    sample-dual.tex
    This document illustrates how to define an entry that both appears in - the list of acronyms and in the main glossary. To create the document do: - -
    latex sample-dual -
    makeglossaries sample-dual -
    latex sample-dual
    -

    +class="cmbx-10">example-glossaries-childnoname.tex

    These are hierarchical entries where the child entries don’t use the + name key. For example: + + +
    + \newglossaryentry{scelerisque}{name={scelerisque}, +  
      description={at}} +  
    \newglossaryentry{vestibulum}{parent={scelerisque}, +  
      description={eu, nulla}} +
    +

    sample-langdict.tex
    This document illustrates how to use the glossaries package to create - English to French and French to English dictionaries. To create the document do: - -
    latex sample-langdict -
    makeglossaries sample-langdict -
    latex sample-langdict
    -

    +class="cmbx-10">example-glossaries-cite.tex

    These entries use the user1 key to store a citation key (or comma-separated list + of citation keys). The citations are defined in xampl.bib, which should be available on all modern + TEX distributions. One entry doesn’t have an associated citation to help test for a missing key. For + example: + + +
    + \newglossaryentry{fusce}{name={fusce}, +  
    description={suscipit cursus sem},user1={article-minimal}} +
    +

    samplexdy.tex
    This document illustrates how to use the glossaries package with example-glossaries-url.tex
    These entries use the user1 key to store an URL associated with the entry. For + example: + + +
    + \newglossaryentry{aenean-url}{name={aenean}, +  
     description={adipiscing auctor est}, +  
     user1={http://uk.tug.org/}} +
    +

    +

    The sample file glossary-lipsum-examples.tex in the doc/latex/glossaries/samples directory uses all +these files. See also https://www.dickimaw-books.com/gallery/#glossaries. +


    glossaries-extraThe glossaries-extra package provides the additional test file: +

    +example-glossaries-xr.tex
    These entries use the see key provided by the base glossaries package and also the + alias and seealso keys that require glossaries-extra. For example: + + +
    + \newglossaryentry{alias-lorem}{name={alias-lorem}, +  
     description={ipsum},alias={lorem}} +  
    \newglossaryentry{amet}{name={amet},description={consectetuer}, +  
     see={dolor}} +  
    \newglossaryentry{arcu}{name={arcu},description={libero}, +  
     seealso={placerat,vitae,curabitur}} +
    +

    +

    +

    +

    Top

    1.3 Multi-Lingual Support

    +

    The glossaries package uses the tracklang package to determine the document languages. Unfortunately, because +there isn’t a standard language identification framework provided with LATEX, tracklang isn’t always able to +detect the selected languages either as a result of using an unknown interface or where the interface doesn’t +provide a way of detecting the language. See Localisation with tracklang.tex for further details. +
    +

    +

    As from version 1.17, the glossaries package can be used with xindy - instead of as well as makeindex. The document uses UTF8 encoding (with the . If you are writing in a +language that uses an extended Latin alphabet or non-Latin alphabet it’s best to use Option 3 (xindy) or +Option 4 (bib2gls) as makeindex (Option 2) is hard-coded for the non-extended Latin alphabet and Option 1 +can only perform limited ASCII comparisons. +

    This means that with Options 3 or 4 you are not restricted to the A, …, Z letter groups. If you want to use +xindy, remember to use the xindy package option. For example: + + +

    +
    +\documentclass[frenchb]{article} + 
    \usepackage[utf8]{inputenc} + 
    \usepackage[T1]{fontenc} + 
    \usepackage{babel} + 
    \usepackage[xindy]{glossaries} +
    +

    If you want to use bib2gls, you need to use the record option with glossaries-extra and supply the definitions in +bib files. (See the bib2gls user manual for further details.) +

    Note that although a non-Latin character, such as é, looks like a plain character in your tex file, with +standard LATEX it’s actually a macro and can therefore cause expansion problems. You may need to switch +off the field expansions with \glsnoexpandfields. This issue doesn’t occur with XeLaTeX or LuaLATEX. +
    +

    +

    With inputenc package). - The encoding is picked up by makeglossaries. By default, this document will - create a , if you use a non-Latin character (or other expandable) character at the start of an entry +name, you must place it in a group, or it will cause a problem for commands that convert the first letter to +upper case (e.g. \Gls). For example:

    +
    +\newglossaryentry{elite}{name={{é}lite}, +
    description={select group or class}} +
    +
    For further details, see the “UTF-8” section in the mfirstuc user manual. +

    If you are using xindy style file called samplexdy.xdy, but if you uncomment the - lines - - -

    - \setStyleFile{samplexdy-mc} -  
    \noist -  
    \GlsSetXdyLanguage{} -
    -

    it will set the style file to samplexdy-mc.xdy instead. This provides an additional letter - group for entries starting with “Mc” or “Mac”. If you use makeglossaries or - makeglossaries-lite, you don’t need to supply any additional information. If you - don’t use makeglossaries, you will need to specify the required information. Note that - if you set the style file to samplexdy-mc.xdy you must also specify \noist, otherwise - the glossaries package will overwrite samplexdy-mc.xdy and you will lose the “Mc” - letter group. -

    To create the document do: -
    latex samplexdy -
    makeglossaries samplexdy -
    latex samplexdy
    -

    - If you don’t have Perl installed then you can’t use or bib2gls, the application needs to know the encoding of the tex file. This +information is added to the aux file and can be picked up by makeglossaries, but you also can’t - use xindy! However, if for some reason you want to call and bib2gls. If you use xindy explicitly instead of using - +explicitly instead of via makeglossaries (or makeglossaries-lite):

    -
      -
    • - if - you - are - using - the - default - style - file - samplexdy.xdy, - then - do - (no - line - breaks): - -
      xindy - -L - english - - - -C - utf8 - -I - xindy - -M - samplexdy - -t - samplexdy.glg - -o - samplexdy.gls - samplexdy.glo
      -

      -

    • -
    • - if - you - are - using - samplexdy-mc.xdy, - then - do - (no - line - breaks): - -
      xindy - -I - xindy - -M - samplexdy-mc - -t - samplexdy.glg - -o - samplexdy.gls - samplexdy.glo
      -

      -

    -
    + id="dx1-13026">, you may need to specify the encoding using the -C option. Read the samplexdy2.tex
    This document illustrates how to use the glossaries package where the - location numbers don’t follow a standard format. This example will only work with - xindy. To create the document do: -
    pdflatex samplexdy2 - - -
    makeglossaries samplexdy2 -
    pdflatex samplexdy2
    -

    - The - explicit - xindy - call - is: - -
    xindy - -L - english - -C - utf8 - -I - xindy - -M - samplexdy2 - -t - samplexdy2.glg - -o - samplexdy2.gls - samplexdy2.glo
    -

    - See §11.2 Locations and Number lists for further details. -

    -samplexdy3.tex
    This document is like samplexdy.tex but uses the command - \Numberstring from the fmtcount package to format the page numbers. -
    -sampleutf8.tex
    This is another example that uses xindy. Unlike manual for further details of this option. +

    As from v4.24, if you are writing in German (for example, using the ngerman +package1.5 +or babel with the ngerman package option), and you want to use makeindex, xindy can - cope with non-Latin characters. This document uses UTF8 encoding. To create the - document do: -
    latex sampleutf8 -
    makeglossaries sampleutf8 -
    latex sampleutf8
    -

    - The - explicit - xindy - call - - - is - (no - line - breaks): - -
    xindy - -L - english - -C - utf8 - -I - xindy - -M - sampleutf8 - -t - sampleutf8.glg - -o - sampleutf8.gls - sampleutf8.glo
    -

    -

    If you remove the xindy option from sampleutf8.tex and do: -
    latex sampleutf8 -
    makeglossaries sampleutf8 -
    latex sampleutf8
    -

    - or -
    latex sampleutf8 -
    makeglossaries-lite sampleutf8 -
    latex sampleutf8
    -

    - you - will - see - that - the - entries - that - start - with - an - extended - - - Latin - character - now - appear - in - the - symbols - group, - and - the - word - “manœuvre” - is - now - after - “manor” - instead - of - before - it. - If - you - want - to - explicitly - call - ’s -g option, you’ll need to change +makeindex - (no - line - breaks): - -
    makeindex - -s - sampleutf8.ist - -t - sampleutf8.glg - -o - sampleutf8.gls - sampleutf8.glo
    -

    -

    -sample-index.tex
    This document uses the glossaries package to create both a glossary and - an index. This requires two ’s quote character using: +


    \GlsSetQuote{character}

    +

    +Note that ⟨character⟩ may not be one of ? (question mark), | (pipe) or ! (exclamation mark). For +example: + + +

    +
    +\GlsSetQuote{+} +
    +

    This must be done before \makeglossaries and any entry definitions. It’s only applicable for makeindex. This +option in conjunction with ngerman will also cause makeglossaries (or makeglossaries-lite) calls to ensure - the document is up to date: - - -
    latex sample-index -
    makeglossaries sample-index -
    latex sample-index -
    makeglossaries sample-index -
    latex sample-index
    -

    -

    -sample-newkeys.tex
    This document illustrates how add custom keys (using \glsaddkey). -
    -sample-storage-abbr.tex
    This document illustrates how add custom storage keys (using - \glsaddstoragekey). -
    -sample-storage-abbr-desc.tex
    An extension of the previous example where the user - needs to provide a description. -
    -sample-chap-hyperfirst.tex
    This document illustrates how to add a custom key using - \glsaddstoragekey and hook into the \gls-like and \glstext-like mechanism used to - determine whether or not to hyperlink an entry. -
    -sample-font-abbr.tex
    This document illustrates how to different fonts for abbreviations - within the style. -
    -sample-numberlist.tex
    This document illustrates how to reference the number list in the - document text. This requires an additional LATEX run: -
    latex sample-numberlist -
    makeglossaries sample-numberlist -
    latex sample-numberlist -
    latex sample-numberlist
    -

    -

    -samplePeople.tex
    This document illustrates how you can hook into the standard sort - mechanism to adjust the way the sort key is set. This requires an additional run to - ensure the table of contents is up-to-date: -
    latex samplePeople -
    makeglossaries samplePeople -
    latex samplePeople - - -
    latex samplePeople
    -

    -

    -sampleSort.tex
    This is another document that illustrates how to hook into the standard - sort mechanism. An additional run is required to ensure the table of contents is - up-to-date: -
    latex sampleSort -
    makeglossaries sampleSort -
    latex sampleSort -
    latex sampleSort
    -

    -

    -sample-nomathhyper.tex
    This document illustrates how to selectively enable and disable - entry hyperlinks in \glsentryfmt. -
    -sample-entryfmt.tex
    This document illustrates how to change the way an entry is - displayed in the text. -
    -sample-prefix.tex
    This document illustrates the use of the glossaries-prefix package. - An additional run is required to ensure the table of contents is up-to-date: - -
    latex sample-prefix -
    makeglossaries sample-prefix -
    latex sample-prefix -
    latex sample-prefix
    -

    -

    + id="dx1-13039"> to use the -g switch when invoking sampleaccsupp.tex
    This document uses the experimental glossaries-accsupp package. The - symbol is set to the replacement text. Note that some PDF viewers don’t use the - accessibility support. Information about the glossaries-accsupp package can be found in - §18 Accessibility Support. -
    +class="cmtt-10">makeindex. +

    Be careful of babel’s shorthands. These aren’t switched on until the start of the document, so any entries +defined in the preamble won’t be able to use those shorthands. However, if you define the entries in the +document and any of those shorthands happen to be special characters for makeindex or xindy (such as the +double-quote) then this will interfere with code that tries to escape any of those characters that occur in the sample-ignored.tex
    This document defines an ignored glossary for common terms that - don’t need a definition. - - -
    +class="cmtt-10">sort key.
    +

    +

    In general, it’s best not to use babel’s shorthands in entry definitions. For example: + + +

    +
    +\documentclass{article} + 
    \usepackage[ngerman]{babel} + 
    \usepackage{glossaries} + 
    \GlsSetQuote{+} + 
    \makeglossaries + 
    \newglossaryentry{rna}{name={ribonukleins\"aure}, + 
      sort={ribonukleins"aure}, + 
      description={eine Nukleins\"aure}} + 
    \begin{document} + 
    \gls{rna} + 
    \printglossaries + 
    \end{document} +
    +

    +

    The ngerman package has the shorthands on in the preamble, so they can be used in definitions if sample-entrycount.tex

    This document uses \glsenableentrycount and \cgls (described - in §14.1 Counting the Number of Times an Entry has been Used (First Use - Flag Unset)) so that acronyms only used once don’t appear in the list of - acronyms.
    -

    -

    -

    Top

    1.3 Dummy Entries for Testing

    -

    In addition to the sample files described above, \GlsSetQuote has been used to change the makeindex quote character. Example: + + +

    +
    +\documentclass{article} + 
    \usepackage[ngerman]{babel} + 
    \usepackage{glossaries} + 
    \GlsSetQuote{+} + 
    \makeglossaries + 
    \newglossaryentry{rna}{name={ribonukleins"aure}, + 
      description={eine Nukleins"aure}} + 
    \begin{document} + 
    \gls{rna} + 
    \printglossaries + 
    \end{document} +
    +

    +

    +

    +

    Top

    1.3.1 Changing the Fixed Names

    +

    The fixed names are produced using the commands listed in table 1.2. If you aren’t using a language package +such as babel or polyglossia that uses caption hooks, you can just redefine these commands as appropriate. If +you are using babel or polyglossia, you need to use their caption hooks to change the defaults. +See changing the words babel uses or read the babel or polyglossia documentation. If you have +loaded babel, then glossaries also provides some files containing -lorum ipsum dummy entries. These are provided for testing purposes and are on TEX’s path -(in tex/latex/glossaries/test-entries) so they can be included via \input or + id="dx1-14008"> will attempt to load translator, unless you have used the notranslate, \loadglsentries. The files are as follows: -

    +class="cmss-10">translate=false or translate=babel package options. If the translator package is loaded, the translations +are provided by dictionary files (for example, glossaries-dictionary-English.dict). See the example-glossaries-brief.tex
    These entries all have brief descriptions. For example: - - -
    - \newglossaryentry{lorem}{name={lorem},description={ipsum}} -
    -

    -

    +class="cmss-10">translator package for advice on changing translations provided by translator dictionaries. If you +can’t work out how to modify these dictionary definitions, try switching to babel’s interface using example-glossaries-long.tex
    These entries all have long descriptions. For example: - - -
    - \newglossaryentry{loremipsum}{name={lorem ipsum}, -  
    description={dolor sit amet, consectetuer adipiscing -  
    elit. Ut purus elit, vestibulum ut, placerat ac, -  
    adipiscing vitae, felis. Curabitur dictum gravida -  
    mauris.}} +class="cmss-10">translate=babel: + + +

    +
    +\documentclass[english,french]{article} + 
    \usepackage{babel} + 
    \usepackage[translate=babel]{glossaries}
    -

    -

    -example-glossaries-multipar.tex
    These entries all have multi-paragraph descriptions. -
    -example-glossaries-symbols.tex
    These entries all use the symbol key. For example: - - -
    - \newglossaryentry{alpha}{name={alpha}, -  
    symbol={\ensuremath{\alpha}}, -  
    description={Quisque ullamcorper placerat ipsum.}} -
    -

    -

    -example-glossaries-symbolnames.tex
    Similar to the previous file but the symbol key isn’t - used. Instead the symbol is stored in the name key. For example: - - -
    - \newglossaryentry{sym.alpha}{sort={alpha}, -  
    name={\ensuremath{\alpha}}, -  
    description={Quisque ullamcorper placerat ipsum.}} -
    -

    -

    -example-glossaries-images.tex
    These entries use the user1 key to store the name of an - image file. (The images are provided by the mwe package and should be on TEX’s - path.) One entry doesn’t have an associated image to help test for a missing - key. -
    -example-glossaries-acronym.tex
    These entries are all abbreviations. For example: - - -
    - \newacronym[type=\glsdefaulttype]{lid}{LID}{lorem ipsum -  
    dolor} -
    -

    -

    -example-glossaries-acronym-desc.tex
    These entries are all abbreviations that use the - description key. For example: - - -
    - \newacronym[type=\glsdefaulttype, -  
      description={fringilla a, euismod sodales, -  
      sollicitudin vel, wisi}]{ndl}{NDL}{nam dui ligula} -
    -

    -

    -example-glossaries-acronyms-lang.tex
    These entries are all abbreviations, where some of - them have a translation supplied in the user1 key. For example: - - -
    - \newacronym[type=\glsdefaulttype,user1={love itself}] -  
     {li}{LI}{lorem ipsum} -
    -

    -

    -example-glossaries-parent.tex
    These are hierarchical entries where the child entries use - the name key. For example: - - -
    - \newglossaryentry{sedmattis}{name={sed mattis}, -  
    description={erat sit amet} -  
    \newglossaryentry{gravida}{parent={sedmattis}, -  
      name={gravida},description={malesuada}} -
    -

    -

    -example-glossaries-childnoname.tex
    These are hierarchical entries where the child - entries don’t use the name key. For example: - - -
    - \newglossaryentry{scelerisque}{name={scelerisque}, -  
      description={at}} -
    -

    -

    -example-glossaries-cite.tex
    These entries use the user1 key to store a citation - key (or comma-separated list of citation keys). The citations are defined in - xampl.bib, which should be available on all modern TEX distributions. One - entry doesn’t have an associated citation to help test for a missing key. For - example: - - -
    - \newglossaryentry{fusce}{name={fusce}, -  
    description={suscipit cursus sem},user1={article-minimal}} -
    -

    -

    -example-glossaries-url.tex
    These entries use the user1 key to store an URL associated - with the entry. For example: - - -
    - \newglossaryentry{aenean-url}{name={aenean}, -  
     description={adipiscing auctor est}, -  
     user1={http://uk.tug.org/}} -
    -

    -

    The sample file glossary-lipsum-examples.tex in the doc/latex/glossaries/samples -directory uses all these files. See also http://www.dickimaw-books.com/gallery/#glossaries. -The glossaries-extra package provides additional test files. -

    -

    -

    Top

    1.4 Multi-Lingual Support

    -

    As from version 1.17, the glossaries package can be used with xindy as well as makeindex. If -you are writing in a language that uses an extended Latin alphabet or non-Latin alphabet it’s -best to use Option 3 (xindy) or Option 4 (bib2gls) as makeindex (Option 2) is hard-coded -for the non-extended Latin alphabet and Option 1 can performed limited ASCII -comparisons. -

    This means that with Options 3 or 4 you are not restricted to the A, …, Z letter -groups. If you want to use xindy, remember to use the xindy package option. For -example: - - -

    -
    -\documentclass[frenchb]{article} - 
    \usepackage[utf8]{inputenc} - 
    \usepackage[T1]{fontenc} - 
    \usepackage{babel} - 
    \usepackage[xindy]{glossaries} -
    -

    If you want to use bib2gls, you need to use the record option with glossaries-extra -and supply the definitions in .bib files. (See the bib2gls user manual for further -details.) -

    Note that although a non-Latin character, such as é, looks like a plain character -in your .tex file, with standard LATEX it’s actually a macro and can therefore -cause expansion problems. You may need to switch off the field expansions with -\glsnoexpandfields. This issue doesn’t occur with XeLaTeX or LuaLATEX. -
    -

    -

    With inputenc, if you use a non-Latin character (or other expandable) character at the -start of an entry name, you must place it in a group, or it will cause a problem for -commands that convert the first letter to upper case (e.g. \Gls). For example: -

    -
    -\newglossaryentry}{elite}{name={{é}lite}, -
    description={select group or class}} -
    -
    (With newer versions of mfirstuc and datatool-base you may be able to omit this grouping.) -For further details, see the “UTF-8” section in the mfirstuc user manual. -

    If you are using xindy or bib2gls, the application needs to know the encoding of the -.tex file. This information is added to the .aux file and can be picked up by makeglossaries -and bib2gls. If you use xindy explicitly instead of via makeglossaries, you may need to -specify the encoding using the -C option. Read the xindy manual for further details of this -option. -

    As from v4.24, if you are writing in German (for example, using the ngerman -package1.4 -or babel with the ngerman package option), and you want to use makeindex’s -g option, you’ll -need to change makeindex’s quote character using: -


    \GlsSetQuote  \GlsSetQuote{character}

    -

    -Note that ⟨character⟩ may not be one of ? (question mark), | (pipe) or ! (exclamation mark). -For example: - - -

    -
    -\GlsSetQuote{+} -
    -

    This must be done before \makeglossaries and any entry definitions. It’s only applicable -for makeindex. This option in conjunction with ngerman will also cause makeglossaries to -use the -g switch when invoking makeindex. -

    Be careful of babel’s shorthands. These aren’t switched on until the start of the -document, so any entries defined in the preamble won’t be able to use those shorthands. -However, if you define the entries in the document and any of those shorthands happen to be -special characters for makeindex or xindy (such as the double-quote) then this will interfere -with code that tries to escape any of those characters that occur in the sort key. -
    -

    -

    In general, it’s best not to use babel’s shorthands in entry definitions. For example: - - -

    -
    -\documentclass{article} - 
    \usepackage[ngerman]{babel} - 
    \usepackage{glossaries} - 
    \GlsSetQuote{+} - 
    \makeglossaries - 
    \newglossaryentry{rna}{name={ribonukleins\"aure}, - 
      sort={ribonukleins"aure}, - 
      description={eine Nukleins\"aure}} - 
    \begin{document} - 
    \gls{rna} - 
    \printglossaries - 
    \end{document} -
    -

    -

    The ngerman package has the shorthands on in the preamble, so they can be used if -\GlsSetQuote has changed the makeindex quote character. Example: - - -

    -
    -\documentclass{article} - 
    \usepackage[ngerman]{babel} - 
    \usepackage{glossaries} - 
    \GlsSetQuote{+} - 
    \makeglossaries - 
    \newglossaryentry{rna}{name={ribonukleins"aure}, - 
      description={eine Nukleins"aure}} - 
    \begin{document} - 
    \gls{rna} - 
    \printglossaries - 
    \end{document} -
    -

    -

    -

    -

    Top

    1.4.1 Changing the Fixed Names

    -

    The fixed names are produced using the commands listed in table 1.2. If you aren’t using a -language package such as babel or polyglossia that uses caption hooks, you can just redefine -these commands as appropriate. If you are using babel or polyglossia, you need to use their -caption hooks to change the defaults. See changing the words babel uses or read the

    and then use babel or -polyglossia documentation. If you have loaded ’s caption hook mechanism. Note that if you pass the language options directly to babel, then glossaries will attempt to load -translator, unless you have used the notranslate, translate=false or translate=babel package -options. If the +rather that using the document class options or otherwise passing the same options to translator package is loaded, the translations are provided by dictionary files -(for example, glossaries-dictionary-English.dict). See the translator package for advice -on changing translations provided by , then translator dictionaries. If you can’t work out -how to modify these dictionary definitions, try switching to +won’t pick up the language and no dictionaries will be loaded and babel’s interface using -translate=babel: - - -

    -
    -\documentclass[english,french]{article} - 
    \usepackage{babel} - 
    \usepackage[translate=babel]{glossaries} -
    -

    and then use babel’s caption hook mechanism. Note that if you pass the language options -directly to babel rather that using the document class options or otherwise passing the same -options to translator, then translator won’t pick up the language and no dictionaries will be -loaded and babel’s caption hooks will be used instead. + id="dx1-14022">’s caption hooks will be used +instead.

    - - -


    - - + +
    Table 1.2: Customised Text
    - - + +
    +class="cmbx-10">Word

    + glossary.

    + id="dx1-14026">).

    + headers).

    + headers).

    + option.

    + option.

    + option.

    -
    Command Name

    Translator Key Word

    Purpose

    Purpose

    \glossaryname

    Glossary

    Title +class="td11">

    Glossary

    Title of the main - glossary.

    \acronymname

    Acronyms

    Title +class="td11">

    Acronyms

    Title of the list @@ -4681,17 +5924,17 @@ class="td10">

    Title option acronym).

    \entryname

    Notation (glossaries)

    Header +class="cmtt-10">(glossaries)

    Header for first column @@ -4707,17 +5950,17 @@ class="td10">

    Header glossaries that support - headers).

    \descriptionname

    Description (glossaries)

    Header +class="cmtt-10">(glossaries)

    Header for second column @@ -4733,17 +5976,17 @@ class="td10">

    Header glossaries that support - headers).

    \symbolname

    Symbol (glossaries)

    Header +class="cmtt-10">(glossaries)

    Header for symbol column @@ -4756,19 +5999,19 @@ class="td10">

    Header that support this - option.

    \pagelistname

    Page List (glossaries)

    Header +class="cmtt-10">(glossaries)

    Header for page list @@ -4781,17 +6024,17 @@ class="td10">

    Header that support this - option.

    \glssymbolsgroupname

    Symbols (glossaries)

    Header +class="cmtt-10">(glossaries)

    Header for symbols section @@ -4804,17 +6047,17 @@ class="td10">

    Header that support this - option.

    \glsnumbersgroupname

    Numbers (glossaries)

    Header +class="cmtt-10">(glossaries)

    Header for numbers section @@ -4827,153 +6070,162 @@ class="td10">

    Header that support this - option.

    - + option.

    + +
    - - + +

    -

    As from version 4.12, multilingual support is provided by separate language modules that -need to be installed in addition to installing the glossaries package. You only need to install -the modules for the languages that you require. If the language module has an -unmaintained status, you can volunteer to take over the maintenance by contacting me at -

    As from version 4.12, multilingual support is provided by separate language modules that need to be +installed in addition to installing the glossaries package. You only need to install the modules for the languages +that you require. If the language module has an unmaintained status, you can volunteer to take over the +maintenance by contacting me at http://www.dickimaw-books.com/contact.html. The translator dictionary files for glossaries -are now provided by the appropriate language module. For further details about -information specific to a given language, please see the documentation for that language + id="dx1-14033"> +dictionary files for glossaries are now provided by the appropriate language module. For further details +about information specific to a given language, please see the documentation for that language module. -

    Examples of use:

    +

    Examples of use:

    • Using babel and translator: - - -
      + + +
      \documentclass[english,french]{article}  
      \usepackage{babel}  
      \usepackage{glossaries}
      -

      (

      (translator is automatically loaded).

    • Using babel: - - -
      + + +
      \documentclass[english,french]{article}  
      \usepackage{babel}  
      \usepackage[translate=babel]{glossaries}
      -

      (

      (translator isn’t loaded). + id="dx1-14038"> isn’t loaded). The glossaries-extra package has translate=babel as the default if babel has been + loaded.

    • Using polyglossia: - - -
      + id="dx1-14041">: + + +
      \documentclass{article}  
      \usepackage{polyglossia}  
      \setmainlanguage{english}  
      \usepackage{glossaries}
      -

      +

    -

    Due to the varied nature of glossaries, it’s likely that the predefined translations may not -be appropriate. If you are using the

    Due to the varied nature of glossaries, it’s likely that the predefined translations may not be +appropriate. If you are using the babel package and the glossaries package option + id="dx1-14042"> package and the glossaries package option translate=babel, you +need to be familiar with the advice given in changing the words babel uses. If you are using the translate=babel, you need to be familiar with the advice given in changing the words -babel uses. If you are using the translator package, then you can provide your own -dictionary with the necessary modifications (using \deftranslation) and load it using -\usedictionary. If you simply want to change the title of a glossary, you can use the + id="dx1-14044"> package, then you can provide your own dictionary with the necessary modifications (using title key in commands like \deftranslation) and load it using \usedictionary. If you simply want to change the title of a glossary, you +can use the title key in commands like \printglossary (but not the iterative commands like \printglossaries). -

    Note that the

    Note that the translator dictionaries are loaded at the beginning of the document, so it -won’t have any effect if you put \deftranslation in the preamble. It should be put in your -personal dictionary instead (as in the example below). See the dictionaries are loaded at the beginning of the document, so it won’t have any effect +if you put \deftranslation in the preamble. It should be put in your personal dictionary instead (as in the +example below). See the translator documentation for -further details. (Now with documentation for further details. (Now with beamer documentation.)
    -

    -

    Your custom dictionary doesn’t have to be just a translation from English to another -language. You may prefer to have a dictionary for a particular type of document. For -example, suppose your institution’s in-house reports have to have the glossary labelled as -“Nomenclature” and the page list should be labelled “Location”, then you can create a file -called, say, - - + id="dx1-14048"> documentation.) +

    +

    +

    Your custom dictionary doesn’t have to be just a translation from English to another language. You may +prefer to have a dictionary for a particular type of document. For example, suppose your institution’s in-house +reports have to have the glossary labelled as “Nomenclature” and the page list should be labelled “Location”, +then you can create a file called, say, + +

    -
    +
    myinstitute-glossaries-dictionary-English.dict
    -

    that contains the following: - - +

    that contains the following: + +

    -
    +
    \ProvidesDictionary{myinstitute-glossaries-dictionary}{English}  
    \deftranslation{Glossary}{Nomenclature}  
    \deftranslation{Page List (glossaries)}{Location}
    -

    You can now load it using: - - +

    You can now load it using: + +

    -
    +
    \usedictionary{myinstitute-glossaries-dictionary}
    -

    (Make sure that myinstitute-glossaries-dictionary-English.dict can be -found by TEX.) If you want to share your custom dictionary, you can upload it to -

    (Make sure that myinstitute-glossaries-dictionary-English.dict can be found by TEX.) If you want to +share your custom dictionary, you can upload it to CTAN. -

    If you are using

    If you are using babel and don’t want to use the and don’t want to use the translator interface, you can use the -package option translate=babel. For example: - - + id="dx1-14050"> interface, you can use the package option +translate=babel. For example: + +

    -
    +
    \documentclass[british]{article}  
    \usepackage{babel}  
    \usepackage[translate=babel]{glossaries} @@ -4982,66 +6234,66 @@ class="cmss-10">translate=babel    \renewcommand*{\acronymname}{List of Acronyms}%  
    }
    -

    -

    Note that

    +

    Note that xindy and and bib2gls provide much better multi-lingual support than provide much better multi-lingual support than makeindex, -so I recommend that you use Options , so I recommend +that you use Options 3 or 4 if you have glossary entries that contain -4 if you have glossary entries that contain non-Latin characters. See §11 Xindy (Option 3) for further details on s. See §11 Xindy +(Option 3) for further details on xindy, and see the -, and see the bib2gls user manual for further details of that application. + id="dx1-14057"> user manual for further details of that +application.

    Creating a New Language Module
    -

    The

    The glossaries package now uses the tracklang package to determine which language modules -need to be loaded. If you want to create a new language module, you should first read the - package to determine which language modules need +to be loaded. If you want to create a new language module, you should first read the tracklang documentation. -

    To create a new language module, you need to at least create two files: +documentation. +

    To create a new language module, you need to at least create two files called: glossaries-lang.ldf -and .ldf and +glossaries-dictionary-Lang.dict where ⟨lang⟩ is the root language name (for -example, .dict where ⟨lang⟩ is the root language name (for example, english) and ⟨Lang⟩ is the language name used by Lang⟩ is +the language name used by translator (for example, - (for example, English). -

    Here’s an example of

    Here’s an example of glossaries-dictionary-English.dict: - - + +

    -
    +
    \ProvidesDictionary{glossaries-dictionary}{English}  
    \providetranslation{Glossary}{Glossary}  
    \providetranslation{Acronyms}{Acronyms} @@ -5052,23 +6304,22 @@ class="cmtt-10">glossaries-dictionary-English.dict:  
    \providetranslation{Symbols (glossaries)}{Symbols}  
    \providetranslation{Numbers (glossaries)}{Numbers}
    -

    You can use this as a template for your dictionary file. Change

    You can use this as a template for your dictionary file. Change English to the translator name -for your language (so that it matches the file name name for your +language (so that it matches the file name glossaries-dictionary-Lang.dict) -and, for each \providetranslation, change the second argument to the appropriate -translation. -

    Here’s an example of .dict) and, for each +\providetranslation, change the second argument to the appropriate translation. +

    Here’s an example of glossaries-english.ldf: - - + +

    -
    +
    \ProvidesGlossariesLang{english}  
    \glsifusedtranslatordict{English}  
    {% @@ -5114,8 +6365,8 @@ class="cmtt-10">glossaries-english.ldf:  
          \csappto{captions\CurrentTrackedLanguage}%  
          {%  
            \glossariescaptionsenglish - - + +  
          }%  
        }%  
        {% @@ -5127,64 +6378,59 @@ class="cmtt-10">glossaries-english.ldf:  
    \renewcommand*{\glsacrpluralsuffix}{\glspluralsuffix}  
    \renewcommand*{\glsupacrpluralsuffix}{\glstextup{\glspluralsuffix}}
    -

    This is a somewhat longer file, but again you can use it as a template. Replace English with -the

    This is a somewhat longer file, but again you can use it as a template. Replace English with the translator language label ⟨ +language label ⟨Lang⟩ used for the dictionary file and replace english with the -root language name ⟨lang⟩. Within the definition of english with the root language name ⟨lang⟩. Within +the definition of \glossariescaptionslang⟩, replace the -English text (such as “Glossaries”) with the appropriate translation. -

    Note: the suffixes used to generate the plural forms when the plural hasn’t been specified -are given by \glspluralsuffix (for general entries) and \glsupacrpluralsuffix for -acronyms where the suffix needs to be set using \glstextup to counteract the effects of -\textsc and \glsacrpluralsuffix for other acronym styles. There’s no guarantee when -these commands will be expanded. They may be expanded on definition or they may be -expanded on use, depending on the glossaries configuration. -

    Therefore these plural suffix command definitions aren’t included in the caption -mechanism as that’s typically not switched on until the start of the document. This means -that the suffix in effect will be for the last loaded language that redefined these -commands. It’s best to initialise these commands to the most common suffix required in -your document and use the plural, longplural, shortplural etc keys to override exceptions. -
    -

    -

    If you want to add a regional variation, create a file called lang⟩, replace the English text (such as “Glossaries”) with the +appropriate translation. +

    The suffixes used to generate the plural forms when the plural hasn’t been specified are given by +\glspluralsuffix (for general entries). For abbreviations defined with \newacronym, \glsupacrpluralsuffix +is used for acronyms where the suffix needs to be set using \glstextup to counteract the effects of \textsc and +\glsacrpluralsuffix for other acronym styles. There’s no guarantee when these commands will be expanded. +They may be expanded on definition or they may be expanded on use, depending on the glossaries +configuration. +

    Therefore these plural suffix command definitions aren’t included in the caption mechanism as that’s +typically not switched on until the start of the document. This means that the suffix in effect will be for the last +loaded language that redefined these commands. It’s best to initialise these commands to the most common +suffix required in your document and use the plural, longplural, shortplural etc keys to override exceptions. +
    +

    +

    If you want to add a regional variation, create a file called glossaries-iso lang-iso -country.ldf, where ⟨iso country.ldf, +where ⟨iso lang⟩ is the ISO language code and ⟨iso country⟩ is the ISO country -code. For example, glossaries-en-GB.ldf. This file can load the root language file and -make the appropriate changes, for example: - - +class="cmti-10">iso country⟩ is the ISO country code. For example, +glossaries-en-GB.ldf. This file can load the root language file and make the appropriate changes, for +example: + +

    -
    +
     \ProvidesGlossariesLang{en-GB}  
     \RequireGlossariesLang{english}  
     \glsifusedtranslatordict{British} @@ -5204,20 +6450,19 @@ make the appropriate changes, for example:  
       }%  
     }
    -

    -

    If the translations includes

    +

    If the translations includes non-Latin characters, it’s necessary to provide code that’s -independent of the input encoding. Remember that while some users may use UTF-8, others -may use Latin-1 or any other supported encoding, but while users won’t appreciate -you enforcing your preference on them, it’s useful to provide a UTF-8 version for -XeLaTeX users. -

    The s, it’s necessary to provide code that’s independent of the +input encoding. Remember that while some users may use UTF-8, others may use Latin-1 or any other +supported encoding, but while users won’t appreciate you enforcing your preference on them, it’s useful to +provide a UTF-8 version for XeLaTeX users. +

    The glossaries-irish.ldf file provides this as follows: - - + +

    -
    +
    \ProvidesGlossariesLang{irish}  
    \glsifusedtranslatordict{Irish}  
    {% @@ -5253,24 +6498,24 @@ class="cmtt-10">glossaries-irish.ldf file provides this as follows:  
      \glossariescaptionsirish  
    }
    -

    (Again you can use this as a template. Replace irish with your root language label and +

    (Again you can use this as a template. Replace irish with your root language label and Irish with the Irish with the translator dictionary label.) -

    There are now two extra files: glossaries-irish-noenc.ldf and glossaries-irish-utf8.ldf. -

    These both define dictionary label.) +

    There are now two extra files: glossaries-irish-noenc.ldf (no encoding information) and +glossaries-irish-utf8.ldf (UTF-8). +

    These both define \glossariescaptionsirish but the *-noenc.ldf uses LATEX accent -commands: - - +class="E">EX accent commands: + +

    -
    +
    \@ifpackageloaded{polyglossia}%  
    {%  
      \newcommand*{\glossariescaptionsirish}{% @@ -5297,110 +6542,107 @@ commands:  
      }%  
    }
    -

    whereas the *-utf8.ldf replaces the accent commands with the appropriate UTF-8 -characters. -

    +

    whereas the *-utf8.ldf replaces the accent commands with the appropriate UTF-8 characters. +

    -

    Top

    1.5

    Top

    1.4 Generating the Associated Glossary Files

    -

    This section is only applicable if you have chosen Options 

    This section is only applicable if you have chosen Options 2 or 3. You can ignore this section -if you have chosen any of the other options. If you want to alphabetically sort your entries -always remember to use the sort3. You can ignore this section if you have +chosen any of the other options. If you want to alphabetically sort your entries always remember to +use the sort key if the namename contains any LATEX commands. +class="E">EX commands (except if you’re using bib2gls).
    -

    -

    If this section seriously confuses you, and you can’t work out how to run external -tools like

    +

    If this section seriously confuses you, and you can’t work out how to run external tools like makeglossaries or or +makeindex, you can try using the , you can try using the automake package -option, described in §2.4 Sorting Options, but you will need TEX’s shell escape -enabled. - - -

    In order to generate a sorted glossary with compact package option, described in §2.5 Sorting Options, but you will need +TEX’s shell escape enabled. See also Incorporating makeglossaries or makeglossaries-lite or bib2gls into the +document build. +

    In order to generate a sorted glossary with compact number lists, it is necessary to use an -external indexing application as an intermediate step (unless you have chosen Option 1, -which uses TEX to do the sorting or Option 5, which doesn’t perform any sorting). It is this -application that creates the file containing the code required to typeset the glossary. If this -step is omitted, the glossaries will not appear in your document. The two -indexing applications that are most commonly used with LATs, it is necessary to use an external indexing + + +application as an intermediate step (unless you have chosen Option 1, which uses TEX to do the +sorting or Option 5, which doesn’t perform any sorting). It is this application that creates the file +containing the code required to typeset the glossary. If this step is omitted, the glossaries will +not appear in your document. The two indexing applications that are most commonly used with +LATEX are makeindex and - and xindy. As from version 1.17, the glossaries package can be used with either of these -applications. Previous versions were designed to be used with . As from version 1.17, the glossaries package can be used with either of +these applications. Previous versions were designed to be used with makeindex only. With -the glossaries-extra package, you can also use only. With the +glossaries-extra package, you can also use bib2gls as the indexing application. -(See the glossaries-extra and as the indexing application. (See the glossaries-extra +and bib2gls user manuals for further details.) Note that - user manuals for further details.) Note that xindy and and bib2gls have much better multi-lingual support than have much better +multi-lingual support than makeindex, so -, so xindy or or bib2gls are recommended if you’re not writing in English. Commands -that only have an effect when are recommended if you’re not writing in +English. Commands that only have an effect when xindy is used are described in §11 is used are described in §11 Xindy (Option 3). -

    This is a multi-stage process, but there are methods of automating document compilation -using applications such as

    This is a multi-stage process, but there are methods of automating document compilation using applications +such as latexmk and and arara. With . With arara you can just add special -comments to your document source:

    + id="dx1-16021"> you can just add special comments to your document source: +

    % pdflatex
    With latexmk you need to set up the required dependencies.
    -

    -

    The you need to set up the required dependencies.

    +

    +

    The glossaries package comes with the Perl script makeglossaries which will run - which will run makeindex or or xindy on all the glossary files using a customized style file (which is created by - on all +the glossary files using a customized style file (which is created by \makeglossaries). See §1.5.1 Using the makeglossaries Perl Script for further details. Perl is -stable, cross-platform, open source software that is used by a number of TEX-related -applications (including ). See §1.4.1 +Using the makeglossaries Perl Script for further details. Perl is stable, cross-platform, open source +software that is used by a number of TEX-related applications (including xindy and and latexmk). Most Unix-like operating systems come with -a Perl interpreter. TEX Live also comes with a Perl interpreter. MiKTEX doesn’t come -with a Perl interpreter so if you are a Windows MiKTEX user you will need to install Perl if -you want to use ). +Most Unix-like operating systems come with a Perl interpreter. TEX Live also comes with a Perl +interpreter. MiKTEX doesn’t come with a Perl interpreter so if you are a Windows MiKTEX user +you will need to install Perl if you want to use makeglossaries or or xindy. Further information is available at -. Further information is +available at http://www.perl.org/about.html and MiKTeX and Perl scripts (and one Python script). -

    The advantages of using

    The advantages of using makeglossaries:

    + id="dx1-16031">:

    • It automatically detects whether to use makeindex or or xindy and sets the relevant - application switches. + id="dx1-16033"> and sets the relevant application + switches.
    • One call of makeglossaries will run will run makeindex//xindy for each glossary type. + id="dx1-16036"> for each glossary type.
    • - -
    • If things go wrong, makeglossaries will scan the messages from will scan the messages from makeindex or - or xindy and attempt to diagnose the problem in relation to the glossaries package. - This will hopefully provide more helpful messages in some cases. If it can’t diagnose - the problem, you will have to read the relevant transcript file and see if you can - work it out from the and attempt + to diagnose the problem in relation to the glossaries package. This will hopefully provide more + helpful messages in some cases. If it can’t diagnose the problem, you will have to read the relevant + transcript file and see if you can work it out from the makeindex or or xindy messages. + id="dx1-16041"> messages. + +
    • If makeindex warns about multiple encap values, warns about multiple encap values, makeglossaries will detect this - and attempt to correct the problem.1.5 + id="dx1-16043"> will detect this and attempt to + correct the problem.1.6 This correction is only provided by makeglossaries when when makeindex is used since - is used since xindy uses the order of the attributes list to determine which format should take - precedence. (See \GlsAddXdyAttribute in §11.2 Locations and Number lists.) + id="dx1-16048"> uses the + order of the attributes list to determine which format should take precedence. (see §11.2 Locations + and Number lists.)
    -

    As from version 4.16, the glossaries package also comes with a Lua script called -

    As from version 4.16, the glossaries package also comes with a Lua script called makeglossaries-lite. This is a . This +is a trimmed-down alternative to the makeglossaries Perl -script. It doesn’t have some of the options that the Perl version has and it doesn’t attempt to -diagnose any problems, but since modern TEX distributions come with LuaTEX (and -therefore have a Lua interpreter) you don’t need to install anything else in order to use - Perl script. It doesn’t have some of the options that the +Perl version has and it doesn’t attempt to diagnose any problems, but since modern TEX distributions come +with LuaTEX (and therefore have a Lua interpreter) you don’t need to install anything else in order to +use makeglossaries-lite so it’s an alternative to Option 2 href="#glo:makeindex">makeindex). -

    If things go wrong and you can’t work out why your glossaries aren’t being generated -correctly, you can use

    If things go wrong and you can’t work out why your glossaries aren’t being generated correctly, you can use +makeglossariesgui as a diagnostic tool. Once you’ve fixed the -problem, you can then go back to using as a diagnostic tool. Once you’ve fixed the problem, you can then go back to using +makeglossaries or makeglossaries-lite. -

    Whilst I strongly recommended that you use the

    Whilst I strongly recommended that you use the makeglossaries Perl script or -the Perl script or the makeglossaries-lite Lua script, it is possible to use the glossaries package -without using those applications. However, note that some commands and package -options have no effect if you explicitly run +Lua script, it is possible to use the glossaries package without using those applications. However, note that some +commands and package options have no effect if you explicitly run makeindex/xindy. These are listed in table 1.3. -

    If you are choosing not to use

    If you are choosing not to use makeglossaries because you don’t want to install Perl, -you will only be able to use because you don’t want to install Perl, you will only be able +to use makeindex as xindy also requires Perl. (Other useful Perl -scripts include also requires Perl. (Other useful Perl scripts include epstopdf and latexmk, so it’s well-worth the effort to install Perl.) -
    -

    -

    Note that if any of your entries use an entry that is not referenced outside -the glossary, you will need to do an additional latexmk, so it’s +well-worth the effort to install Perl.)

    +

    +

    Note that if any of your entries use an entry that is not referenced outside the glossary, you will need to do an +additional makeglossaries, makeindex or - or xindy run, as appropriate. For example, suppose you have defined the following entries:1.6 - - +href="#fn7x1" id="fn7x1-bk">1.7 + +

    -
    +
    \newglossaryentry{citrusfruit}{name={citrus fruit},  
    description={fruit of any citrus tree. (See also  
    \gls{orange})}}  
    \newglossaryentry{orange}{name={orange},  
    description={an orange coloured fruit.}}
    -

    and suppose you have \gls{citrusfruit} in your document but don’t reference -the orange entry, then the orange entry won’t appear in your glossary until you -first create the glossary and then do another run of

    and suppose you have \gls{citrusfruit} in your document but don’t reference the orange entry, then the +orange entry won’t appear in your glossary until you first create the glossary and then do another run of +makeglossaries, makeindex -or or xindy. For example, if the document is called myDoc.tex, then you must do: - -
    latex myDoc -
    makeglossaries myDoc -
    latex myDoc -
    makeglossaries myDoc -
    latex myDoc
    -

    -(Note that if you use glossaries-extra, this will be done automatically for you if -the indexcrossrefs feature is enabled. See the glossaries-extra user guide for further -details.) -

    Likewise, an additional myDoc.tex, then you must +do: +

    
    +   
    pdflatex myDoc +
    makeglossaries myDoc +
    pdflatex myDoc +
    makeglossaries myDoc +
    pdflatex myDoc +
    +
    +(In the case of
    Option 4, bib2gls will scan the description for instances of commands like \gls to ensure they +are selected but an extra bib2gls call is required to ensure the locations are included, if locations lists are +required. See the and bib2gls manual for further details.) +

    Likewise, an additional makeglossaries and LATEX run may be required if the -document pages shift with re-runs. For example, if the page numbering is not reset after the -table of contents, the insertion of the table of contents on the second LATEX run may push -glossary entries across page boundaries, which means that the and LATEX run may be required if the document pages shift with +re-runs. For example, if the page numbering is not reset after the table of contents, the insertion of the table of +contents on the second LATEX run may push glossary entries across page boundaries, which means that the +number lists in the glossary -may need updating. -

    The examples in this document assume that you are accessing s in the glossary may need updating. +

    The examples in this document assume that you are accessing makeglossaries, , xindy or - or makeindex via a terminal. Windows users can use the MSDOS Prompt which is usually -accessed via the via a +terminal. Windows users can use the MSDOS Prompt which is usually accessed via the Start->All Programs menu or All Programs +menu or Start->All Programs->Accessories -menu. -

    Alternatively, your text editor may have the facility to create a function that will call the -required application. See Incorporating makeglossaries or makeglossaries-lite or bib2gls into -the document build. -

    If any problems occur, remember to check the transcript files (e.g. .glg or .alg) for -messages. +class="cmss-10">Accessories menu. +

    Alternatively, your text editor may have the facility to create a function that will call the required +application. See Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document +build. +

    If any problems occur, remember to check the transcript files (e.g. glg or alg) for messages.

    - - -


    - - + +
    Table 1.3: Commands and package options that have no effect when using xindy or - or makeindex explicitly
    + id="dx1-16085"> explicitly
    Command or Package Option + id="dx1-16087">
    makeindex xindy
    order=letter order=letter use -l use -M ord/letorder
    order=word order=word default default
    xindy=={language=lang} N/A use -Llang-Ccode
    \GlsSetXdyLanguage{lang} N/A use -Llang
    \GlsSetXdyCodePage{code} N/A use -Ccode
    - - + +

    -

    Top

    1.5.1

    Top

    1.4.1 Using the makeglossaries Perl Script

    -

    The

    The makeglossaries script picks up the relevant information from the auxiliary (.aux) file -and will either call aux) file and will either call +xindy or makeindex, depending on the supplied information. Therefore, -you only need to pass the document’s name without the extension to , depending on the supplied information. Therefore, you only need to pass the document’s +name without the extension to makeglossaries. For -example, if your document is called myDoc.tex, type the following in your terminal: - -
    latex myDoc -
    makeglossaries myDoc -
    latex myDoc
    -

    + id="dx1-17005">. For example, if your document is called myDoc.tex, type the +following in your terminal: +

    
    +   
    pdflatex myDoc +
    makeglossaries myDoc +
    pdflatex myDoc +
    +
    You may need to explicitly load makeglossaries into Perl: -
    perl makeglossaries myDoc
    -

    -

    Windows users: T into Perl: +

    
    +   
    perl makeglossaries myDoc +
    +
    +

    Windows users: TEX Live on Windows has its own internal Perl interpreter and provides makeglossaries.exe as a convenient wrapper for the makeglossaries.exe but doesn’t provide a Per required even if you run MiKTeX’s makeglossaries.exe, so with MiKTeX you’ll need to install Perl.1.7 +href="#fn8x1" id="fn8x1-bk">1.8 There’s more information about this at http://tex.stackexchange.com/q/158796/19862 -on the TeX.SX site. -

    The http://tex.stackexchange.com/q/158796/19862 on the TeX.SX +site. +

    The makeglossaries script attempts to fork the makeindex/xindy process -using open() on the piped redirection process using open() on the piped +redirection 2>&1 | and parses the processor output to -help diagnose problems. If this method fails  | and parses the processor output to help diagnose problems. If this method fails +makeglossaries will print an “Unable -to fork” warning and will retry without redirection. If you run will print an “Unable to fork” warning and will retry without redirection. If you run +makeglossaries -on an operating system that doesn’t support this form of redirection, then you -can use the on an operating system that doesn’t support this form of redirection, then you can use the -Q switch to suppress this warning or you can use the +switch to suppress this warning or you can use the -k switch to -make switch to make makeglossaries automatically use the fallback method without attempting -the redirection. Without this redirection, the automatically use the +fallback method without attempting the redirection. Without this redirection, the -q (quiet) switch doesn’t work as -well. -

    You can specify in which directory the .aux (quiet) switch doesn’t +work as well. +

    You can specify in which directory the aux, .gloglo etc files are located using the -d switch. -For example: -
    pdflatex -output-directory myTmpDir myDoc -
    makeglossaries -d myTmpDir myDoc
    -

    +class="cmtt-10">-d switch. For +example: +

    
    +   
    pdflatex -output-directory myTmpDir myDoc +
    makeglossaries -d myTmpDir myDoc +
    +
    Note that makeglossaries assumes by default that makeindex/xindy is on your operating -system’s path. If this isn’t the case, you can specify the full pathname using is on your operating system’s path. If +this isn’t the case, you can specify the full pathname using -m -⟨path/to/makeindex⟩ for makeindex or -x +⟨path/to/xindy⟩ for xindy. -

    As from

    As from makeglossaries v2.18, if you are using makeindex, there’s a check for -, there’s a check for makeindex’s multiple encap warning. This is where different encap values (location formats) -are used on the same location for the same entry. For example: - - + id="dx1-17029">’s multiple encap +warning. This is where different encap values (location formats) are used on the same location for the same +entry. For example: + +

    -
    +
    \documentclass{article}  
    \usepackage{glossaries}  
    \makeglossaries @@ -5954,382 +7190,369 @@ are used on the same location for the same entry. For example:  
    \printglossaries  
    \end{document}
    -

    If you explicitly use

    If you explicitly use makeindex, this will cause a warning and the location list -will be “1, 1”. That is, the page number will be repeated with each format. As -from v2.18, , this will cause a warning and the location list will be “1, 1”. That is, the page +number will be repeated with each format. As from v2.18, makeglossaries will check for this warning and, if found, will attempt -to correct the problem by removing duplicate locations and retrying. There’s no -similar check for will check for this warning +and, if found, will attempt to correct the problem by removing duplicate locations and retrying. +There’s no similar check for xindy as xindy won’t produce any warning and will simply discard duplicates. -

    The makeglossaries script contains POD (Plain Old Documentation). If you want, you -can create a man page for makeglossaries using pod2man and move the resulting file onto -the man path. Alternatively do makeglossaries --help for a list of all options or -makeglossaries --version for the version number. -

    When upgrading the glossaries package, make sure you also upgrade your version of -

    For a complete list of options do makeglossaries --help. +

    -

    -

    + id="dx1-17034">. The +current version is 4.45.

    +

    +

    -

    Top

    1.5.2

    Top

    1.4.2 Using the makeglossaries-lite Lua Script

    -

    The Lua alternative to the

    The Lua alternative to the makeglossaries Perl script requires a Lua interpreter, which -should already be available if you have a modern T Perl script requires a Lua interpreter, which should already be +available if you have a modern TEX distribution that includes LuaTEX. -Lua is a light-weight, cross-platform scripting language, but because it’s light-weight it -doesn’t have the full-functionality of heavy-weight scripting languages, such as Perl. The -EX. Lua is a light-weight, cross-platform +scripting language, but because it’s light-weight it doesn’t have the full-functionality of heavy-weight scripting +languages, such as Perl. The makeglossaries-lite script is therefore limited by this and some of the options -available to the script is therefore limited by this and some of the +options available to the makeglossaries Perl script aren’t available here. (In particular the -d option.) -

    Note that TEX Live on Unix-like systems creates a symbolic link called -makeglossaries-lite (without the .lua extension) to the actual makeglossaries-lite.lua -script, so you may not need to supply the extension.
    -

    - - -

    The

    Note that TEX Live on Unix-like systems creates a symbolic link called makeglossaries-lite (without +the lua extension) to the actual makeglossaries-lite.lua script, so you may not need to supply the +extension.
    +

    +

    The makeglossaries-lite script can be invoked in the same way as script can be invoked in the same way as makeglossaries. -For example, if your document is called myDoc.tex, then do -
    makeglossaries-lite.lua myDoc
    -

    -or -
    makeglossaries-lite myDoc
    -

    -

    Some of the options available with . For example, if your +document is called myDoc.tex, then do +

    
    +   
    makeglossaries-lite.lua myDoc +
    + + +
    +or +

    
    +   
    makeglossaries-lite myDoc +
    +
    +

    Some of the options available with the Perl makeglossaries are also available with + id="dx1-18008"> script are also available with the Lua makeglossaries-lite. For a complete list of available options, do -
    makeglossaries-lite.lua --help
    -

    -

    -

    -

    Top

    1.5.3 script. For a complete list of available options, do +

    
    +   
    makeglossaries-lite.lua --help +
    +
    +

    +

    +

    Top

    1.4.3 Using xindy explicitly (Option 3)

    -

    Xindy comes with TEX Live. It has also been added to MikTEX, but if you don’t have it -installed, see How to use Xindy with MikTeX on EX, but if you don’t have it installed, see How to +use Xindy with MikTeX on TEX on StackExchange. -

    If you want to use

    If you want to use xindy to process the glossary files, you must make sure you have used -the to process the glossary files, you must make sure you have used the xindy package option: - - + id="dx1-19003"> package +option: + +

    -
    +
    \usepackage[xindy]{glossaries}
    -

    This is required regardless of whether you use

    This is required regardless of whether you use xindy explicitly or whether it’s -called implicitly via applications such as explicitly or whether it’s called implicitly via applications +such as makeglossaries. This causes the glossary -entries to be written in raw . This causes the glossary entries to be written in raw xindy format, so you need to use format, so you need to use +-I xindy not -I - tex. -

    To run

    To run xindy type the following in your terminal (all on one line): -
    xindy -L language-C encoding-I xindy -M style-t base.glg -o base.gls -⟨base.glo
    -

    + id="dx1-19009"> type the following in your terminal (all on one line): +

    
    +   
    xindy -L ⟨language⟩ -C ⟨encoding⟩ -I xindy -M ⟨style⟩ -t ⟨base⟩.glg -o ⟨base⟩.gls ⟨base⟩.glo +
    +
    where ⟨language⟩ is the required language name, ⟨encoding⟩ is the encoding, ⟨base⟩ is the name of -the document without the .texbase⟩ is the name of the document +without the tex extension and ⟨style⟩ is the name of the xindy style file -without the .xdy extension. The default name for this style file is ⟨ style file without the xdy extension. The default +name for this style file is ⟨base.xdy but can be -changed via xdy but can be changed via \setStyleFile{style}. You may need to specify the full path name depending -on the current working directory. If any of the file names contain spaces, you must delimit -them using double-quotes. -

    For example, if your document is called myDoc.tex and you are using UTF8 encoding in -English, then type the following in your terminal: -
    xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.glg -o myDoc.gls -myDoc.glo
    -

    -

    Note that this just creates the main glossary. You need to do the same for each of -the other glossaries (including the list of acronyms if you have used the }. You may need to specify the +full path name depending on the current working directory. If any of the file names contain spaces, you must +delimit them using double-quotes. +

    For example, if your document is called myDoc.tex and you are using UTF8 encoding in English, then type +the following in your terminal: +

    
    +   
    xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.glg -o myDoc.gls myDoc.glo +
    +
    +

    Note that this just creates the main glossary. You need to do the same for each of the other glossaries +(including the list of acronyms if you have used the acronym -package option), substituting .glg package option), substituting glg, .glsgls and .glo with the relevant extensions. For -example, if you have used the glo +with the relevant extensions. For example, if you have used the acronym package option, then you would need to do: - -
    xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.alg -o myDoc.acr + id="dx1-19019"> package option, then you would need to +do: +

    
    +   
    xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.alg -o myDoc.acr myDoc.acn +
    +
    +For additional glossaries, the extensions are those supplied when you created the glossary with myDoc.acn -

    -For additional glossaries, the extensions are those supplied when you created the glossary -with \newglossary. -

    Note that if you use

    Note that if you use makeglossaries instead, you can replace all those calls to xindy -with just one call to with just one call to +makeglossaries: -
    makeglossaries myDoc
    -

    + id="dx1-19023">: +

    
    +   
    makeglossaries myDoc +
    +
    Note also that some commands and package options have no effect if you use xindy explicitly -instead of using explicitly instead of using +makeglossaries. These are listed in table 1.3. -

    + + +

    - - -

    Top

    1.5.4

    Top

    1.4.4 Using makeindex explicitly (Option 2)

    -

    If you want to use

    If you want to use makeindex explicitly, you must make sure that you haven’t used the xindy -package option or the glossary entries will be written in the wrong format. To run package option or +the glossary entries will be written in the wrong format. To run makeindex, -type the following in your terminal: -
    makeindex -s style.ist -t base.glg -o base.gls base.glo
    -

    + id="dx1-20003">, type the following in your +terminal: +

    
    +   
    makeindex -s ⟨style⟩.ist -t ⟨base⟩.glg -o ⟨base⟩.gls ⟨base⟩.glo +
    +
    where ⟨base⟩ is the name of your document without the .textex extension and ⟨style.ist is the -name of the ist is the name of the +makeindex style file. By default, this is ⟨base.ist, but may be changed via -ist, but may be changed via \setStyleFile{style}. Note that there are other options, such as }. Note +that there are other options, such as -l (letter ordering). See -the (letter ordering). See the makeindex manual for further details. -

    For example, if your document is called myDoc.tex, then type the following at the -terminal: -
    makeindex -s myDoc.ist -t myDoc.glg -o myDoc.gls myDoc.glo
    -

    -Note that this only creates the main glossary. If you have additional glossaries (for example, if -you have used the manual for further +details. +

    For example, if your document is called myDoc.tex, then type the following at the terminal: +

    
    +   
    makeindex -s myDoc.ist -t myDoc.glg -o myDoc.gls myDoc.glo +
    +
    +Note that this only creates the main glossary. If you have additional glossaries (for example, if you have used the +acronym package option) then you must call makeindex for each glossary, -substituting .glg for each glossary, substituting glg, .glsgls and .glo with the relevant extensions. For example, if you have used -the glo with +the relevant extensions. For example, if you have used the acronym package option, then you need to type the following in your terminal: - -
    makeindex -s myDoc.ist -t myDoc.alg -o myDoc.acr myDoc.acn
    -

    -For additional glossaries, the extensions are those supplied when you created the glossary -with package option, then you need to type the +following in your terminal: +

    
    +   
    makeindex -s myDoc.ist -t myDoc.alg -o myDoc.acr myDoc.acn +
    +
    +For additional glossaries, the extensions are those supplied when you created the glossary with +\newglossary. -

    Note that if you use

    Note that if you use makeglossaries instead, you can replace all those calls to makeindex -with just one call to with just one call +to makeglossaries: -
    makeglossaries myDoc
    -

    + id="dx1-20020">: +

    
    +   
    makeglossaries myDoc +
    +
    Note also that some commands and package options have no effect if you use makeindex -explicitly instead of using explicitly instead of +using makeglossaries. These are listed in table 1.3. -

    +

    -

    Top

    1.5.5 Note to Front-End and Script Developers

    -

    The information needed to determine whether to use

    Top

    1.5 Note to Front-End and Script Developers

    +

    The information needed to determine whether to use xindy or , makeindex and the -information needed to call those applications is stored in the auxiliary file. This -information can be gathered by a front-end, editor or script to make the glossaries where -appropriate. This section describes how the information is stored in the auxiliary -file. -

    The file extensions used by each defined glossary are given by -


    \@newglossary  or bib2gls is stored in the aux file. +This information can be gathered by a front-end, editor or script to make the glossaries where appropriate. This +section describes how the information is stored in the auxiliary file. + + +

    +

    +

    Top

    1.5.1 MakeIndex and Xindy

    +

    The file extensions used by each defined (but not ignored) glossary are given by +


    \@newglossary{label}{out-ext}{in-ext}

    -

    +

    where ⟨in-ext⟩ is the extension of the indexing application’s input file (the output file from the -glossaries package’s point of view), ⟨indexing application’s input file (the output file from the glossaries package’s +point of view), ⟨out-ext⟩ is the extension of the indexing application’s -output file (the input file from the glossaries package’s point of view) and ⟨log⟩ is the -extension of the indexing application’s transcript file. The label for the glossary - - -is also given for information purposes only, but is not required by the indexing -applications. For example, the information for the default main glossary is written +class="cmti-10">indexing application’s output file (the input file from the glossaries +package’s point of view) and ⟨log⟩ is the extension of the indexing application’s transcript file. The label for the +glossary is also given. This isn’t required with makeindex, but with xindy it’s needed to pick up the associated +language and encoding (see below). For example, the information for the default main glossary is written as: - - + +

    -
    +
    \@newglossary{main}{glg}{gls}{glo}
    -

    -

    The

    If glossaries-extra’s hybrid method has been used (with \makeglossaries[sub-list]), then the sub-list of +glossaries that need to be processed will be identified with:

    +
    +\glsxtr@makeglossaries{list} +
    +
    +

    The indexing application’s style file is specified by -


    \@istfilename 


    \@istfilename{filename}

    -

    +

    The file extension indicates whether to use makeindex (.ist) or (ist) or xindy (xdy). Note that the glossary information +is formatted differently depending on which indexing application is supposed to be used, so it’s important to call +the correct one. +

    For example, with arara you can easily determine whether to run makeglossaries:

    +
    +% arara: makeglossaries if found("aux", "@istfilename") +
    +
    It’s more complicated if you want to explicitly run makeindex or xindy +

    Note that if you choose to explicitly call makeindex or xindy (.xdy). -Note that the glossary information is formatted differently depending on which -indexing application is supposed to be used, so it’s important to call the correct -one. -

    Word or letter ordering is specified by: -


    \@glsorder  then the user will miss out on the diagnostic +information and the encap-clash fix that makeglossaries also provides.
    +

    +

    Word or letter ordering is specified by: +


    \@glsorder{order}

    -

    +

    where ⟨order⟩ can be either word or letter. -

    If

    If xindy should be used, the language and code page for each glossary is specified -by -


    \@xdylanguage \@gls@codepage  should be used, the language and code page for each glossary is specified by +


    \@xdylanguage{label}{label}{code}

    -

    +

    where ⟨label⟩ identifies the glossary, ⟨language⟩ is the root language (e.g. english) and ⟨code⟩ is -the encoding (e.g. code⟩ is the encoding +(e.g. utf8). These commands are omitted if makeindex should be -used. -

    If should be used. +

    If Option 1 has been used, the .aux file will contain -


    aux file will contain +


    \@gls@reference{type}{label}{location}

    -

    -for every time an entry has been referenced. If

    +for every time an entry has been referenced. + + +

    +

    +

    Top

    1.5.2 Entry Labels

    +

    If you need to gather labels for auto-completion, the writeglslabels package option will create a file containing the +labels of all defined entries (regardless of whether or not the entry has been used in the document). The +glossaries-extra package also provides docdef=atom, which will create the glsdefs file but will act like +docdef=restricted. +

    +

    +

    Top

    1.5.3 Bib2Gls

    +

    bib2glsIf Option 4 has been used, the .aux file will -contain one or more instances of -


    \glsxtr@resource{aux file will contain one or more instances of

    +
    +\glsxtr@resource{options}{basename}

    -

    - - -

    -

    -

    Top

    2. Package Options

    -

    This section describes the available glossaries package options. You may omit the +class="cmtt-10">} +

    +
    where ⟨basename⟩ is the basename of the glstex file that needs to be created by bib2gls. If src= =true for boolean options. (For example, acronym is equivalent to acronym=true). -The glossaries-extra package has additional options described in the glossaries-extra -manual. -

    Note that ⟨key⟩=⟨value⟩ package options can’t be passed via the document class options. -(This includes options where the ⟨{bib list} isn’t present in ⟨options⟩ then ⟨basename⟩ also indicates the name of the associated bib +file. +

    For example, with arara you can easily determine whether or not to run bib2gls:

    +
    +% arara: bib2gls if found("aux", "glsxtr@resource") +
    +
    (It gets more complicated if both \glsxtr@resource and \@istfilename are present as that indicates the +hybrid record=alsoindex option.) +

    Remember that with bib2gls, the entries will never be defined on the first LATEX call (because their +definitions are contained in the glstex file created by bib2gls). You can also pick up labels from the records in +aux file, which will be in the form:

    +
    +\glsxtr@record{label}{h-prefix}{counter}{format}{loc} +
    +
    or (with record=nameref)
    +
    +\glsxtr@record@nameref{label}{href prefix}{counter}{format}{location}{title} +{href anchor}{href value} +
    +
    or (with \glssee)
    + + +
    +\glsxtr@recordsee{label}{xr list} +
    +
    You can also pick up the commands defined with \glsxtrnewglslike, which are added to the aux file for +bib2gls’s benefit:
    +
    +\@glsxtr@newglslike{label-prefix}{cs} +
    +
    If \GlsXtrSetAltModifier is used, then the modifier is identified with:
    +
    +\@glsxtr@altmodifier{character} +
    +
    Label prefixes (for the \dgls set of commands) are identified with:
    +
    +\@glsxtr@prefixlabellist{list} +
    +
    + + +

    +

    Top

    2. Package Options

    +

    This section describes the available glossaries package options. You may omit the =true for boolean options. +(For example, acronym is equivalent to acronym=true). +

    The glossaries-extra package has additional options described in the glossaries-extra manual. The extension +package also has some different default settings to the base package. Those that are available at the time of +writing are included here. Future versions of glossaries-extra may have additional package options or new values +for existing settings that aren’t listed here.
    +

    +

    Note that ⟨key⟩=⟨value⟩ package options can’t be passed via the document class options. (This includes options +where the ⟨value⟩ part may be omitted, such as acronym.) -This is a general limitation not restricted to the glossaries package. Options that -aren’t ⟨.) This is a general limitation not restricted to the +glossaries package. Options that aren’t ⟨key⟩=⟨value⟩ (such as makeindex) may be passed via the document class options. -
    -

    + id="dx1-25004">) may be passed via the document class +options.

    +

    -

    Top

    2.1 General Options

    -
    -

    +

    +

    nowarn

    This suppresses all warnings generated by the glossaries package. Don’t use this - option if you’re new to using glossaries as the warnings are designed to help detect - common mistakes (such as forgetting to use nowarn

    +

    This suppresses all warnings generated by the glossaries package. Don’t use this option if you’re new to using +glossaries as the warnings are designed to help detect common mistakes (such as forgetting to use +\makeglossaries). Note that the - debug=true and debug=showtargets will override this option. -

    -). Note that if you use debug with any value other than false it will override this +option. +

    +

    +

    nolangwarn

    This suppresses the warning generated by a missing language module. -
    -nolangwarn +

    This suppresses the warning generated by a missing language module. +

    +

    +

    noredefwarn

    If you load glossaries with a class or another package that already defines - glossary related commands, by default glossaries will warn you that it’s redefining - those commands. If you are aware of the consequences of using glossaries with that - class or package and you don’t want to be warned about it, use this option to - suppress those warnings. Other warnings will still be issued unless you use the - noredefwarn +

    If you load glossaries with a class or another package that already defines glossary related commands, by default +glossaries will warn you that it’s redefining those commands. If you are aware of the consequences of using +glossaries with that class or package and you don’t want to be warned about it, use this option to suppress those +warnings. Other warnings will still be issued unless you use the nowarn option described above. -

    - option described above. (This option is +automatically switched on by glossaries-extra.) + + +

    +

    +

    debug

    Introduced in version 4.24. The default setting is debug=false. This was a - boolean option but as from v4.32 it now accepts the values: debug={value} +

    Introduced in version 4.24. The default setting is debug=false. The following values are available: false, true and - showtargets. If no value is given, debug=true is assumed. Both debug=true - and debug=showtargets switch on the debug mode (and will automatically - cancel the true, +showtargets (v4.32+) and showaccsupp (v4.45+). If no value is given, debug=true is assumed. +

    The glossaries-extra package provides extra values showwrgloss, that may be used to show where the indexing +is occurring, and all, which switches on all debugging options. See the glossaries-extra manual for further details. +
    +

    +

    All values other than debug=false switch on the debug mode (and will automatically cancel the nowarn option). The debug=showtargets option will additionally - use -


    \glsshowtarget  +option). The debug=showtargets option will additionally use: +


    \glsshowtarget{target name}

    -

    - to show the hypertarget or hyperlink name in the margin when \glsdohypertarget is - used by commands like

    +to show the hypertarget or hyperlink name when \glsdohypertarget is used by commands like +\glstarget and when \glsdohyperlink is used by commands - - - like \gls. This puts the information in the margin using \marginpar unless math mode - or inner mode are detected, in which case it puts the information in line enclosed by - square brackets. The glossaries-extra package provides an additional setting that may be - used to show where the indexing is occurring. See the glossaries-extra manual for further - details. -

    The purpose of the debug mode can be demonstrated with the following example - document: - - +class="cmtt-10">\glsdohyperlink is used by commands like \gls. In math mode or inner +mode, this puts the target name in square brackets just before the link or anchor. In outer mode it +uses: +


    \glsshowtargetouter{label}

    +

    +which by default places the target name in the margin. The font is given by: +


    \glsshowtargetfont

    +

    +The default definition is \ttfamily\small. This command is included in the definition of +\glsshowtargetouter, so if you want to redefine that command remember to include the font. For +example: + +

    -
    - \documentclass{article} -  
    \usepackage{glossaries} -  
    \newglossaryentry{sample1}{name={sample1}, -  
      description={example}} -  
    \newglossaryentry{sample2}{name={sample2}, -  
      description={example}} -  
    \glsadd{sample2} -  
    \makeglossaries -  
    \begin{document} -  
    \gls{sample1}. -  
    \printglossaries -  
    \end{document} +
    +\renewcommand*{\glsshowtargetouter}[1]{% + 
     {\glsshowtargetfont [#1]}} +
    +

    +

    Similarly, the debug=showaccsupp will add the accessibility support information using: +


    \glsshowaccsupp{options}{tag}{replacement text}

    +

    +This internally uses \glsshowtarget. This option is provided for use with glossaries-accsupp. +

    The purpose of the debug mode can be demonstrated with the following example document: +

    +
    +\documentclass{article} +
    \usepackage{glossaries} +
    \newglossaryentry{sample1}{name={sample1},description={example}} +
    \newglossaryentry{sample2}{name={sample2},description={example}} +
    \glsadd{sample2}% <- does nothing here +
    \makeglossaries +
    \begin{document} +
    \gls{sample1}. +
    \printglossaries +
    \end{document}
    -

    In this case, only the In this case, only the sample1 entry has been indexed, even though \glsadd{sample2} - appears in the source code. This is because \glsadd{sample2} has been used before the - associated file is opened by \glsadd{sample2} appears in the source +code. This is because \glsadd{sample2} has been used before the associated file is opened by +\makeglossaries. Since the file isn’t open yet, the - information can’t be written to it, which is why the sample2 entry doesn’t appear in - the glossary. -

    This situation doesn’t cause any errors or warnings as it’s perfectly legitimate for a user - to want to use glossaries to format the entries (e.g. abbreviation expansion) but not - display any lists of terms, abbreviations, symbols etc. Without \makeglossaries the - indexing is suppressed but, other than that, commands like \gls behave as - usual. It’s also possible that the user may want to temporarily comment out - . Since the file isn’t open yet, the information can’t be written to it, which is why the sample2 +entry doesn’t appear in the glossary. +

    Without \makeglossaries the indexing is suppressed with Options 2 and 3 but, other than that, +commands like \gls behave as usual. +

    This situation doesn’t cause any errors or warnings as it’s perfectly legitimate for a user to want to use +glossaries to format the entries (e.g. abbreviation expansion) but not display any lists of terms, abbreviations, +symbols etc (or the user may prefer to use the unsorted Options 5 or 6). It’s also possible that the user may +want to temporarily comment out \makeglossaries in order to suppress the indexing while working on a draft - version to speed compilation. Therefore \makeglossaries can’t be used to - enable \newglossaryentry and \glsadd. They must be enabled by default. (It - does, however, enable the see key as that’s a more common problem. See - below.) -

    The debug mode, enabled with the 1 or 4 for indexing, which don’t use +\makeglossaries. +

    Therefore \makeglossaries can’t be used to enable \newglossaryentry and commands like \gls and +\glsadd. These commands must be enabled by default. (It does, however, enable the see key as that’s a more +common problem. See below.) +

    The debug mode, enabled with the debug option, - - + id="dx1-30019"> option, + +

    -
    - \usepackage[debug]{glossaries} +
    +\usepackage[debug]{glossaries}
    -

    will write information to the log file when the indexing can’t occur because the - associated file isn’t open. The message is written in the form -

    -

    Package glossaries Info: wrglossary(⟨

    will write information to the log file when the indexing can’t occur because the associated file isn’t open. The +message is written in the form +

    +

    Package glossaries Info: wrglossary(⟨type⟩)(⟨text⟩) on input line ⟨line - number⟩.

    -

    where ⟨text⟩) on input line ⟨line number⟩.

    +

    where ⟨type⟩ is the glossary label and ⟨text⟩ is the line of text that would’ve been written to - the associated file if it had been open. So if any entries haven’t appeared in the glossary - but you’re sure you used commands like \glsadd or \glsaddall, try switching - on the text⟩ is the line of text that would’ve been written to the associated file if it had +been open. So if any entries haven’t appeared in the glossary but you’re sure you used commands like \glsadd +or \glsaddall, try switching on the debug option and see if any information has been written to the log - file. -

    -seenoindex
    Introduced in version 4.24, this option may take one of three values: error, warn or - ignore. The see key automatically indexes the cross-referenced entry using \glsadd. This - means that it suffers from the same problem as the above. If used before - the relevant glossary file has been opened, the indexing can’t be performed. - Since this is easy to miss, the glossaries package by default issues an error - message if the see key is used before \makeglossaries. This option allows - you to change the error into just a warning (seenoindex=warn) or ignore it - (seenoindex=ignore) if, for example, you want to temporarily comment out - \makeglossaries to speed up the compilation of a draft document by omitting the - indexing. -
    -nomain
    This suppresses the creation of the main glossary and associated .glo file, if - unrequired. Note that if you use this option, you must create another glossary in which - to put all your entries (either via the acronym (or acronyms) package option described in - §2.5 Acronym Options or via the symbols, numbers or index options described - in §2.6 Other Options or via \newglossary described in §12 Defining New - Glossaries). -

    If you don’t use the main glossary and you don’t use this option, makeglossaries will - produce a warning.
    -

    -

    - - -
    - Warning: File 'filename.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. -
    -
    If you did actually want to use the main glossary and you see this warning, check - that you have referenced the entries in that glossary via commands such as - \gls. -
    -sanitizesort
    This is a boolean option that determines whether or not to sanitize the sort - value when writing to the external glossary file. For example, suppose you define an - entry as follows: - - -
    - \newglossaryentry{hash}{name={\#},sort={#}, -  
     description={hash symbol}} -
    -

    The sort value (#) must be sanitized before writing it to the glossary file, otherwise - LATEX will try to interpret it as a parameter reference. If, on the other hand, you - want the sort value expanded, you need to switch off the sanitization. For example, - suppose you do: - - -

    -
    - \newcommand{\mysortvalue}{AAA} -  
    \newglossaryentry{sample}{% -  
      name={sample}, -  
      sort={\mysortvalue}, -  
      description={an example}} -
    -

    and you actually want \mysortvalue expanded, so that the entry is sorted according - to AAA, then use the package option sanitizesort=false. -

    The default for Options  option and see if any information has been written to the log +file. +

    +

    +

    savewrites={boolean}

    +

    This is a boolean option to minimise the number of write registers used by the glossaries package. The default is +savewrites=false. With Options 2 and 3 is sanitizesort=true, and the default for Option 1 is - sanitizesort=false. -

    +href="#option3">3, one write register is required per (non-ignored) glossary and one for the +style file. +

    With all options except Options 1 and 4, another write register is required if the docdefs file is needed to +save document definitions. With both Options 1 and 4, no write registers are required (document definitions +aren’t permitted and indexing information is written to the aux file). If you really need document definitions +but you want to minimise the number of write registers then consider using docdef=restricted with esclocations

    This is a boolean option. (The default is esclocations=true, but - \makenoidxglossaries changes it to esclocations=false.) Both glossaries-extra. +

    There are only a limited number of write registers, and if you have a large number of glossaries +or if you are using a class or other packages that create a lot of external files, you may exceed +the maximum number of available registers. If savewrites is set, the glossary information will be +stored in token registers until the end of the document when they will be written to the external +files. +

    This option can significantly slow document compilation and may cause the indexing to fail. Page numbers +in the number list will be incorrect on page boundaries due to TEX’s asynchronous output routine. As an +alternative, you can use the scrwfile package (part of the KOMA-Script bundle) and not use this option. +
    +

    +

    By way of comparison, sample-multi2.tex provided with bib2gls has a total of +15 glossaries. With Options 2 or 3, this would require 46 associated files and 16 write +registers.2.1 +With bib2gls, no write registers are required and there are only 10 associated files for that particular document +(9 resource files and 1 transcript file). + + +

    If you want to use TEX’s \write18 mechanism to call makeindex and or xindy - are fussy about the location formats ( from your document and use +savewrites, you must create the external files with \glswritefiles before you call makeindex more so than /xindy) so the glossaries - package tries to ensure that special characters are escaped and allows for the location to - be substituted for a format that’s more acceptable to the indexing application. This - requires a bit of trickery to circumvent the problem posed by TEX’s asynchronous - output routine, which can go wrong and also adds to the complexity of the document - build. -

    If you’re sure that your locations will always expand to an acceptable format (or you’re - prepared to post-process the glossary file before passing it to the relevant indexing - application) then use esclocations=false to avoid the complex escaping of location values. - (See “Writing information to associated files” in the documented code for further - details.) -

    -savewrites
    This is a boolean option to minimise the number of write registers used by the - glossaries package. (Default is savewrites=false.) There are only a limited number of - write registers, and if you have a large number of glossaries or if you are using a class or - other packages that create a lot of external files, you may exceed the maximum number - of available registers. If savewrites is set, the glossary information will be stored in token - registers until the end of the document when they will be written to the external - files. -

    This option can significantly slow document compilation and may cause the indexing to - fail. Page numbers in the number list will be incorrect on page boundaries due - to TEX’s asynchronous output routine. As an alternative, you can use the - scrwfile package (part of the KOMA-Script bundle) and not use this option. -
    -

    - - -

    You can also reduce the number of write registers by using Options 1 or 4 or by - ensuring you define all your glossary entries in the preamble. -

    If you want to use TEX’s \write18 mechanism to call makeindex or xindy from - your document and use savewrites, you must create the external files with - \glswritefiles before you call makeindex/xindy. Also set \glswritefiles to - nothing or . Also set +\glswritefiles to nothing or \relax before the end of the document to avoid rewriting the files. For - example: - - -

    -
    - \glswritefiles -  
    \write18{makeindex -s \istfilename\space -  
    -t \jobname.glg -o \jobname.gls \jobname} -  
    \let\glswritefiles\relax -
    -

    -

    - In general, this package option is best avoided. -

    - +
    +\glswritefiles + 
    \write18{makeindex -s \istfilename\space + 
    -t \jobname.glg -o \jobname.gls \jobname} + 
    \let\glswritefiles\relax +
    +

    +

    In general, this package option is best avoided. +

    +

    +

    translate

    This can take the following values: -
    - translate=true
    translate={value} +

    This can take the following values: +

    +true
    If babel has been loaded and the has been loaded and the translator package is installed, - package is installed, translator will be loaded and the translations will be provided by the will be loaded and the + translations will be provided by the translator - package interface. You can modify the translations by providing your own - dictionary. If the package interface. You can modify the translations + by providing your own dictionary. If the translator package isn’t installed and package isn’t installed and babel is loaded, the - is loaded, + the glossaries-babel package will be loaded and the translations will be provided - using babel’s package will be loaded and the translations will be provided using babel’s + \addto\captionlanguage⟩ mechanism. If language⟩ mechanism. If polyglossia has been - loaded, has been loaded, glossaries-polyglossia will be loaded. -
    - translate=false
    will be + loaded. +
    +false
    Don’t provide translations, even if babel or or polyglossia has been - loaded. (Note that has been loaded. (Note that babel provides the command provides + the command \glossaryname so that will - still be translated if you have loaded so that will still be translated if you have loaded babel.) -
    - translate=babel
    .) +
    +babel
    Don’t load the translator package. Instead load package. Instead load glossaries-babel. -

    I recommend you use translate=babel if you have any problems with the - translations or with PDF bookmarks, but to maintain backward compatibility, if - . +

    I recommend you use translate=babel if you have any problems with the translations or with PDF + bookmarks, but to maintain backward compatibility, if babel has been loaded the default is translate=true.
    -

    + id="dx1-32021"> has been loaded the default is translate=true. +

    +

    -
    -

    If

    +

    If translate is specified without a value, translate=true is assumed. If is specified without a value, translate=true is assumed. If translate isn’t - specified, translate=true is assumed if isn’t specified, +translate=true is assumed if babel, , polyglossia or or translator have been loaded. - Otherwise translate=false is assumed. -

    See §1.4.1 have been loaded. Otherwise translate=false is +assumed. +

    With glossaries-extra, if babel is detected then translate=babel is automatically passed to the base glossaries +package.
    + + +

    +

    See §1.3.1 Changing the Fixed Names for further details. - - -

    -

    +

    +

    notranslate

    This is equivalent to translate=false and may be passed via the document class - options. -
    -nohypertypes
    Use this option if you have multiple glossaries and you want to suppress the - entry hyperlinks for a particular glossary or glossaries. The value of this option should - be a comma-separated list of glossary types where \gls etc shouldn’t have hyperlinks - by default. Make sure you enclose the value in braces if it contains any commas. - Example: - - -
    - \usepackage[acronym,nohypertypes={acronym,notation}] -  
      {glossaries} -  
    \newglossary[nlg]{notation}{not}{ntn}{Notation} -
    -

    The values must be fully expanded, so don’t try nohypertypes=\acronymtype. You - may also use -


    \GlsDeclareNoHyperList{list}

    -

    - instead or additionally. See §6 Links to Glossary Entries for further details. -

    -notranslate +

    This is equivalent to translate=false and may be passed via the document class options. +

    +

    +

    hyperfirst

    This is a boolean option that specifies whether each term has a hyperlink on first - use. The default is hyperfirst=true (terms on first use have a hyperlink, unless - explicitly suppressed using starred versions of commands such as hyperfirst={boolean} +

    This is a boolean option that specifies whether each term has a hyperlink on first use. The default is +hyperfirst=true (terms on first use have a hyperlink, unless explicitly suppressed using starred versions of +commands such as \gls* or - by identifying the glossary with or by identifying the glossary with nohypertypes, described above). Note that - , described above). Note that +nohypertypes overrides hyperfirst=true. This option only affects commands that - check the first use flag, such as the overrides hyperfirst=true. This option only affects commands that check the first use flag, such as +the \gls-like commands (for example, \gls or - or \glsdisp), but not the ), but not the \glstext-like commands (for example, \glstext-like commands (for example, +\glslink or - or \glstext). -

    The ). +

    The hyperfirst setting applies to all glossary types (unless identified by setting applies to all glossary types (unless identified by nohypertypes or - defined with or defined +with \newignoredglossary). It can be overridden on an individual basis by - explicitly setting the hyper key when referencing an entry (or by using the plus or - starred version of the referencing command). -

    It may be that you only want to apply this to just the acronyms (where the first use - explains the meaning of the acronym) but not for ordinary glossary entries (where the - first use is identical to subsequent uses). In this case, you can use hyperfirst=false - and apply ). It can be overridden on an individual basis by explicitly setting the +hyper key when referencing an entry (or by using the plus or starred version of the referencing +command). +

    It may be that you only want to apply this to just the acronyms (where the first use explains the meaning of +the acronym) but not for ordinary glossary entries (where the first use is identical to subsequent uses). In this +case, you can use hyperfirst=false and apply \glsunsetall to all the regular (non-acronym) glossaries. For - example: - - +example: + +

    -
    -  \usepackage[acronym,hyperfirst=false]{glossaries} -  
     % acronym and glossary entry definitions -  
     % at the end of the preamble -  
     \glsunsetall[main] -
    -

    -

    Alternatively you can redefine the hook -


    \glslinkcheckfirsthyperhook  + \usepackage[acronym,hyperfirst=false]{glossaries} + 
     % acronym and glossary entry definitions + 
     % at the end of the preamble + 
     \glsunsetall[main] +
    +

    +

    Alternatively you can redefine the hook +


    \glslinkcheckfirsthyperhook

    -

    - which is used by the commands that check the

    +which is used by the commands that check the first use flag, such as \gls. Within the - definition of this command, you can use . Within the definition of this +command, you can use \glslabel to reference the entry label and - to reference the entry label and \glstype to reference the glossary type. You can also use to reference the glossary type. You +can also use \ifglsused to determine if - the entry has been used. You can test if an entry is an acronym by checking if it has the - long key set using to determine if the entry has been used. You can test if an entry is an acronym by +checking if it has the long key set using \ifglshaslong. For example, to switch off the hyperlink on first use - just for acronyms: - - + id="dx1-34021">. For example, to switch off the hyperlink on first use +just for acronyms: + +

    -
    - \renewcommand*{\glslinkcheckfirsthyperhook}{% -  
     \ifglsused{\glslabel}{}% -  
     {% -  
       \ifglshaslong{\glslabel}{\setkeys{glslink}{hyper=false}}{}% -  
     }% -  
    } +
    +\renewcommand*{\glslinkcheckfirsthyperhook}{% + 
     \ifglsused{\glslabel}{}% + 
     {% + 
       \ifglshaslong{\glslabel}{\setkeys{glslink}{hyper=false}}{}% + 
     }% + 
    }
    -

    -

    Note that this hook isn’t used by the commands that don’t check the first use flag, such - as

    +

    Note that this hook isn’t used by the commands that don’t check the first use flag, such as +\glstext. (You can, instead, redefine . (You can, instead, redefine \glslinkpostsetkeys, which is used by both - the , which is used by both the \gls-like and \glstext-like commands.) -

    +class="cmtt-10">\gls-like and indexonlyfirst
    This is a boolean option that specifies whether to only add information to the - external glossary file on first use. The default is indexonlyfirst=false, which will add a - line to the file every time one of the \gls-like or \glstext-like commands are - used. Note that \glsadd will always add information to the external glossary - file2.1 (since - that’s the purpose of that command). -

    You can customise this by redefining -


    \glswriteentry  \glswriteentry{label}{wr-code}

    -

    - where ⟨label⟩ is the entry’s label and ⟨wr-code⟩ is the code that writes the entry’s - information to the external file. The default definition of \glswriteentry - is: - - -

    -
    - \newcommand*{\glswriteentry}[2]{% -  
      \ifglsindexonlyfirst -  
        \ifglsused{#1}{}{#2}% -  
      \else -  
        #2% -  
      \fi -  
    } -
    -

    This checks the indexonlyfirst package option (using \ifglsindexonlyfirst) and does - ⟨wr-code⟩ if this is false otherwise it only does ⟨wr-code⟩ of the entry hasn’t been - used. -

    For example, suppose you only want to index the first use for entries in the \glstext-like commands.) +

    The glossaries-extra package provides a method of disabling the first use hyperlink according to the entry’s +associated category. For example, if you only to switch off the first use hyperlink for abbreviations and +acronyms then you simply need to set the nohyperfirst attribute for the abbreviation and acronym - glossary and not in the main (or any other) glossary: - - +categories. (Instead of using the nohyperfirst package option.) See the glossaries-extra manual for further +details. +

    -
    - \renewcommand*{\glswriteentry}[2]{% -  
     \ifthenelse{\equal{\glsentrytype{#1}}{acronym}} -  
     {\ifglsused{#1}{}{#2}}% -  
     {#2}% -  
    } +

    writeglslabels

    +

    This is a valueless option that will create a file called \jobname.glslabels at the end of the document. This file +simply contains a list of all defined entry labels (including those in any ignored glossaries). It’s provided for the +benefit of text editors that need to know labels for auto-completion. (See also glossaries-extra’s docdef=atom +package option.) +

    Note that with bib2gls the file will only contain the entries that bib2gls has selected from the bib files.
    -

    Here I’ve used \ifthenelse to ensure the arguments of \equal are fully expanded - before the comparison is made. -

    -savenumberlist
    This is a boolean option that specifies whether or not to gather and - store the number list for each entry. The default is savenumberlist=false. (See +

    +

    +

    +

    undefaction={value} (glossaries-extra.sty)

    +

    The value may be one of: +

    +error
    generate an error if a referenced entry is undefined (default, and only available setting with just \glsentrynumberlist and \glsdisplaynumberlist in §9 Using Glossary Terms - Without Links.) This is always true if you use Option 1. -
    -

    +class="cmss-10">glossaries); +

    +warn
    only warn if a referenced entry is undefined (automatically activated with Option 4).
    + + +

    +

    +

    docdef={value} (glossaries-extra.sty)

    +

    This option governs the use of \newglossaryentry. Available values: +

    +false
    \newglossaryentry is not permitted in the document environment (default with glossaries-extra + and for Option 1 with just the base glossaries package); +
    +restricted
    \newglossaryentry is only permitted in the document environment if it occurs before + \printglossary (not available for some indexing options); +
    +atom
    as restricted but creates the docdefs file for use by atom (without the limitations of docdef=true); +
    +true
    \newglossaryentry is permitted in the document environment where it would normally be + permitted by the base glossaries package. This will create the docdefs file if \newglossaryentry + is found in the document environment.
    +

    -

    Top

    2.2 Sectioning, Headings and TOC Options

    -
    -

    +

    +

    toc

    Add the glossaries to the table of contents. Note that an extra LATEX run is - required with this option. Alternatively, you can switch this function on and off - using -


    \glstoctrue  toc={boolean} +

    Add the glossaries to the table of contents. Note that an extra LATEX run is required with this option. +Alternatively, you can switch this function on and off using +


    \glstoctrue

    -

    - and -


    \glstocfalse 

    +and +


    \glstocfalse

    -

    -

    -

    +The default value is toc=false for the base glossaries package and toc=true for glossaries-extra. +

    +

    +

    numberline

    When used with toc, this will add numberline={boolean} + + +

    When used with the above toc=true option, this will add \numberline{} in the final argument of - \addcontentsline. This will align the table of contents entry with the numbered - section titles. Note that this option has no effect if the . This will align the table of contents entry with the numbered section titles. Note that this +option has no effect if the toc option is omitted. If option is omitted. If toc is - used without is used without numberline, the title will be aligned with the section numbers rather than - the section titles. - - -

    -, the title will be aligned with +the section numbers rather than the section titles. +

    +

    +

    section

    This is a ⟨key⟩=⟨value⟩ option. Its value should be the name of a sectional unit - (e.g. chapter). This will make the glossaries appear in the named sectional unit, - otherwise each glossary will appear in a chapter, if chapters exist, otherwise in a section. - Unnumbered sectional units will be used by default. Example: - - -
    - \usepackage[section=subsection]{glossaries} +class="cmss-10">section={value} +

    This option indicates the sectional unit to use for the glossary. The value should be the control +sequence name without the leading backslash or following star (e.g. just chapter not \chapter or +chapter*). +

    The default behaviour is for the glossary heading to use \chapter, if that command exists, or \section +otherwise. The starred or unstarred form is determined by the numberedsection option. +

    Example: + + +

    +
    +\usepackage[section=subsection]{glossaries}
    -

    You can omit the value if you want to use sections, i.e.  - - +

    You can omit the value if you want to use \section, i.e.  + +

    -
    - \usepackage[section]{glossaries} +
    +\usepackage[section]{glossaries}
    -

    is equivalent to - - +

    is equivalent to + +

    -
    - \usepackage[section=section]{glossaries} +
    +\usepackage[section=section]{glossaries}
    -

    You can change this value later in the document using -


    \setglossarysection 

    You can change this value later in the document using +


    \setglossarysection{name}

    -

    - where ⟨

    +where ⟨name⟩ is the sectional unit. -

    The start of each glossary adds information to the page header via -


    \glsglossarymark 

    The start of each glossary adds information to the page header via +


    \glsglossarymark{glossary title}

    -

    - By default this uses

    +By default this uses \@mkboth2.2 - but you may need to redefine it. For example, to only change the right header: - - + id="x1-41004f2"> +but you may need to redefine it. For example, to only change the right header: + +

    -
    - \renewcommand{\glsglossarymark}[1]{\markright{#1}} +
    +\renewcommand{\glsglossarymark}[1]{\markright{#1}}
    -

    or to prevent it from changing the headers: - - +

    or to prevent it from changing the headers: + +

    -
    - \renewcommand{\glsglossarymark}[1]{} +
    +\renewcommand{\glsglossarymark}[1]{}
    -

    If you want

    If you want \glsglossarymark to use \MakeUppercase in the header, use the ucmark - option described below. -

    Occasionally you may find that another package defines \cleardoublepage when it is - not required. This may cause an unwanted blank page to appear before each glossary. - This can be fixed by redefining \glsclearpage  option described +below. +

    Occasionally you may find that another package defines \cleardoublepage when it is not required. This +may cause an unwanted blank page to appear before each glossary. This can be fixed by redefining +\glsclearpage: - - + +

    -
    - \renewcommand*{\glsclearpage}{\clearpage} +
    +\renewcommand*{\glsclearpage}{\clearpage}
    -

    -

    -

    +

    +

    +

    ucmark

    This is a boolean option (default: ucmark=false, unless ucmark={boolean} +

    This is a boolean option. The default is ucmark=false, unless memoir has been loaded, - in which case it defaults to ucmark=true). If set, has been loaded, in which case the default +is ucmark=true. +

    If set, \glsglossarymark uses - uses +\MakeTextUppercase2.3. - You can test whether this option has been set or not using -


    \ifglsucmark  \ifglsucmark . +You can test whether this option has been set or not using +


    \ifglsucmarktrue part\else false part\fi

    -

    - For example: - - -

    -
    - \renewcommand{\glsglossarymark}[1]{% -  
      \ifglsucmark -  
        \markright{\MakeTextUppercase{#1}}% -  
      \else -  
        \markright{#1}% -  
      \fi} -
    -

    If

    +For example: + + +

    +
    +\renewcommand{\glsglossarymark}[1]{% + 
      \ifglsucmark + 
        \markright{\MakeTextUppercase{#1}}% + 
      \else + 
        \markright{#1}% + 
      \fi} +
    +

    If memoir has been loaded and ucfirst is set, then has been loaded and ucmark is set, then memoir’s ’s \memUChead is - used. -

    - is used. +

    +

    +

    numberedsection

    The glossaries are placed in unnumbered sectional units by default, but - this can be changed using numberedsection={value} +

    The glossaries are placed in unnumbered sectional units by default, but this can be changed using +numberedsection. This option can take one of the following - values: -

      -
    • . This option can take one of the following values:

      +
        +
      • false: - no number, i.e. use starred form of sectioning command (e.g. \chapter* or - : no number, i.e. use starred form of sectioning command (e.g. \chapter* or \section*); -
      • -
      • +
      • nolabel: use a numbered section, i.e. the unstarred form of sectioning - command (e.g. \chapter or : use a numbered section, i.e. the unstarred form of sectioning command (e.g. \chapter or + \section), but the section not labelled; -
      • -
      • +
      • autolabel: numbered with automatic labelling. Each glossary uses the unstarred - form of a sectioning command (e.g. : numbered with automatic labelling. Each glossary uses the unstarred form of a sectioning + command (e.g. \chapter or \section) and is assigned a label - (via \section) and is assigned a label (via \label). The label is formed from -


        \glsautoprefix  ). The label is formed + from +


        \glsautoprefix type

        -

        - where ⟨type⟩ is the label identifying that glossary. The default value of - \glsautoprefix is empty. For example, if you load

        + where ⟨type⟩ is the label identifying that glossary. The default value of \glsautoprefix is empty. For + example, if you load glossaries using: - - + +

        -
        - \usepackage[section,numberedsection=autolabel] -  
          {glossaries} +
        + \usepackage[section,numberedsection=autolabel] +  
          {glossaries}
        -

        then each glossary will appear in a numbered section, and can be referenced using - something like: - - +

        then each glossary will appear in a numbered section, and can be referenced using something + like: + +

        -
        - The main glossary is in section~\ref{main} and -  
        the list of acronyms is in section~\ref{acronym}. +
        + The main glossary is in section~\ref{main} and +  
        the list of acronyms is in section~\ref{acronym}.
        -

        If you can’t decide whether to have the acronyms in the main glossary or a - separate list of acronyms, you can use

        If you can’t decide whether to have the acronyms in the main glossary or a separate list of acronyms, you + can use \acronymtype which is set to main if the - which is set to main if the acronym option is not used and is set to acronym if the option is not used and is set to acronym if the + acronym option is used. For - example: - - -

        -
        - The list of acronyms is in section~\ref{\acronymtype}. -
        -

        You can redefine the prefix if the default label clashes with another label in your - document. For example: - - -

        -
        - \renewcommand*{\glsautoprefix}{glo:} -
        -

        will add glo: to the automatically generated label, so you can then, for example, - refer to the list of acronyms as follows: - - -

        -
        - The list of acronyms is in -  
        section~\ref{glo:\acronymtype}. -
        -

        Or, if you are undecided on a prefix: - - -

        -
        - The list of acronyms is in -  
        section~\ref{\glsautoprefix\acronymtype}. -
        -

        -

      • -
      • nameref: this is like autolabel but uses an unnumbered sectioning command - (e.g. \chapter* or \section*). It’s designed for use with the nameref package. - For example: - - -
        - \usepackage{nameref} -  
        \usepackage[numberedsection=nameref]{glossaries} -
        -

        Now \nameref{main} will display the (TOC) section title associated with the - main glossary. As above, you can redefine \glsautoprefix to provide a prefix for - the label.

      -
    -

    + id="dx1-43009"> option is used. For example: + +

    -

    Top

    2.3 Glossary Appearance Options

    -
    -entrycounter
    This is a boolean option. (Default is entrycounter=false.) If set, each main - (level 0) glossary entry will be numbered when using the standard glossary styles. - This option creates the counter glossaryentry glossaryentry. -

    If you use this option, you can reference the entry number within the document - using -


    \glsrefentry  + The list of acronyms is in section~\ref{\acronymtype}. +
    +

    You can redefine the prefix if the default label clashes with another label in your document. For + example: + + +

    +
    + \renewcommand*{\glsautoprefix}{glo:} +
    +

    will add glo: to the automatically generated label, so you can then, for example, refer to the list of + acronyms as follows: + + +

    +
    + The list of acronyms is in +  
    section~\ref{glo:\acronymtype}. +
    +

    Or, if you are undecided on a prefix: + + +

    +
    + The list of acronyms is in +  
    section~\ref{\glsautoprefix\acronymtype}. +
    +

    +

    +
  • nameref: this is like autolabel but uses an unnumbered sectioning command (e.g. \chapter* or + \section*). It’s designed for use with the nameref package. For example: + + +
    + \usepackage{nameref} +  
    \usepackage[numberedsection=nameref]{glossaries} +
    +

    Now \nameref{main} will display the (TOC) section title associated with the main glossary. As above, + you can redefine \glsautoprefix to provide a prefix for the label.

  • +

    +

    +

    Top

    2.3 Glossary Appearance Options

    +

    +

    +

    savenumberlist={boolean}

    +

    This is a boolean option that specifies whether or not to gather and store the number list for each entry. The +default is savenumberlist=false. (See \glsentrynumberlist and \glsdisplaynumberlist in §9 Using Glossary +Terms Without Links.) This is always true if you use Option 1. +

    If you use the record option (with either no value or record=only or record=nameref) then this package option +has no effect. With bib2gls, the number lists are automatically saved with the default save-locations=true +and save-loclist=true resource settings.
    +

    +

    +

    +

    entrycounter={boolean}

    +

    This is a boolean option. (Default is entrycounter=false.) If set, each main (level 0) glossary entry will be +numbered when using the standard glossary styles. This option creates the counter glossaryentry. +

    If you use this option, you can reference the entry number within the document using +


    \glsrefentry{label}

    -

    - where ⟨label⟩ is the label associated with that glossary entry. The labelling - systems uses ⟨

    +where ⟨label⟩ is the label associated with that glossary entry. The labelling systems uses ⟨prefix⟩⟨label⟩, where ⟨label⟩ is the entry’s label and ⟨prefix⟩ is given - by -


    \GlsEntryCounterLabelPrefix  label⟩ is +the entry’s label and ⟨prefix⟩ is given by +


    \GlsEntryCounterLabelPrefix

    -

    - (which defaults to

    +(which defaults to glsentry-). -

    If you use

    If you use \glsrefentry, you must run LATEX twice after creating the glossary files - using EX twice after creating the glossary files using +makeglossaries, , makeindex or or xindy to ensure the cross-references are - up-to-date.
    -

    -

    - to ensure the cross-references are up-to-date.
    + + +

    +

    +

    +

    counterwithin
    This is a ⟨counterwithin={value}

    +

    This is a ⟨key⟩=⟨value⟩ option where ⟨value⟩ is the name of a counter. If used, this - option will automatically set entrycounter=true and the value⟩ is the name of a counter. If used, this option will automatically set +entrycounter=true and the glossaryentry counter will be - reset every time ⟨ counter will be reset every time ⟨value⟩ is incremented. -

    The

    The glossaryentry counter isn’t automatically reset at the start of each glossary, except - when glossary section numbering is on and the counter used by counter isn’t automatically reset at the start of each glossary, except when glossary section +numbering is on and the counter used by counterwithin is the - same as the counter used in the glossary’s sectioning command.
    - - -

    -

    If you want the counter reset at the start of each glossary, you can redefine - is the same as the counter used in the glossary’s +sectioning command.

    +

    +

    If you want the counter reset at the start of each glossary, you can modify the glossary preamble +(\glossarypreamble to use -


    \glsresetentrycounter  ) to use +


    \glsresetentrycounter

    -

    - which sets

    +which sets glossaryentry to zero: - - + id="dx1-47007"> to zero: + +

    -
    - \renewcommand{\glossarypreamble}{% -  
      \glsresetentrycounter -  
    } +
    +\renewcommand{\glossarypreamble}{% + 
      \glsresetentrycounter + 
    }
    -

    or if you are using

    or if you are using \setglossarypreamble, add it to each glossary preamble, as - required. For example: - - -

    -
    - \setglossarypreamble[acronym]{% -  
      \glsresetentrycounter -  
      The preamble text here for the list of acronyms. -  
    } -  
    \setglossarypreamble{% -  
      \glsresetentrycounter -  
      The preamble text here for the main glossary. -  
    } + id="dx1-47008">, add it to each glossary preamble, as required. For +example: + + +

    +
    +\setglossarypreamble[acronym]{% + 
      \glsresetentrycounter + 
      The preamble text here for the list of acronyms. + 
    } + 
    \setglossarypreamble{% + 
      \glsresetentrycounter + 
      The preamble text here for the main glossary. + 
    }
    -

    -

    -

    +

    +

    +

    subentrycounter

    This is a boolean option. (Default is subentrycounter=false.) If set, each - level 1 glossary entry will be numbered when using the standard glossary - styles. This option creates the counter glossarysubentry glossarysubentry. - The counter is reset with each main (level 0) entry. Note that this package - option is independent of subentrycounter={boolean} +

    This is a boolean option. (Default is subentrycounter=false.) If set, each level 1 glossary entry will be numbered +when using the standard glossary styles. This option creates the counter glossarysubentry. The counter is reset +with each main (level 0) entry. Note that this package option is independent of entrycounter. You can reference the number within the - document using . You can reference +the number within the document using \glsrefentry{label} where ⟨label⟩ is the label associated with the - sub-entry. -

    -

    +

    +

    style

    This is a ⟨style={value} +

    This is a ⟨key⟩=⟨value⟩ option. (Default is style=list, unless style=list, unless classicthesis has been loaded, in - which case the default is style=index.) Its value should be the name of the - glossary style to use. This key may only be used for styles defined in has been loaded, in which case the default is +style=index.) Its value should be the name of the glossary style to use. This key may only be used for styles +defined in glossary-list, - , glossary-long, , glossary-super or or glossary-tree. Alternatively, you can set the style - using -


    . Alternatively, you can set the style +using +


    \setglossarystyle{style name}

    -

    - (See §15

    +(See §15 Glossary Styles for further details.) -

    -

    +

    +

    nolong

    This prevents the nolong +

    This prevents the glossaries package from automatically loading glossary-long (which - means that the (which means that the longtable package also won’t be loaded). This reduces overhead by not - defining unwanted styles and commands. Note that if you use this option, you won’t be - able to use any of the glossary styles defined in the glossary-long package (unless you - explicitly load +package also won’t be loaded). This reduces overhead by not defining unwanted styles and commands. Note that +if you use this option, you won’t be able to use any of the glossary styles defined in the glossary-long package +(unless you explicitly load glossary-long). -

    -). + + +

    +

    +

    nosuper

    This prevents the nosuper +

    This prevents the glossaries package from automatically loading glossary-super (which - means that the (which means that the +supertabular package also won’t be loaded). This reduces overhead by - not defining unwanted styles and commands. Note that if you use this option, you won’t - be able to use any of the glossary styles defined in the glossary-super package (unless you - explicitly load package also won’t be loaded). This reduces overhead by not defining unwanted styles and +commands. Note that if you use this option, you won’t be able to use any of the glossary styles defined in the +glossary-super package (unless you explicitly load glossary-super). - - -

    -). +

    +

    +

    nolist

    This prevents the nolist +

    This prevents the glossaries package from automatically loading glossary-list. This - reduces overhead by not defining unwanted styles. Note that if you use this option, you - won’t be able to use any of the glossary styles defined in the glossary-list package (unless - you explicitly load . This reduces overhead by not +defining unwanted styles. Note that if you use this option, you won’t be able to use any of the glossary styles +defined in the glossary-list package (unless you explicitly load glossary-list). Note that since the default style is ). Note that since the default style is list (unless - +(unless classicthesis has been loaded), you will also need to use the has been loaded), you will also need to use the style option to set the style - to something else. -

    - option to set the style to something +else. +

    +

    +

    notree

    This prevents the notree +

    This prevents the glossaries package from automatically loading glossary-tree. This - reduces overhead by not defining unwanted styles. Note that if you use this - option, you won’t be able to use any of the glossary styles defined in the - . This reduces overhead by not +defining unwanted styles. Note that if you use this option, you won’t be able to use any of the glossary styles +defined in the glossary-tree package (unless you explicitly load glossary-tree). Note that if - ). Note that if classicthesis has been loaded, the default style is has been +loaded, the default style is index, which is provided by - , which is provided by glossary-tree. -

    -. +

    +

    +

    nostyles

    This prevents all the predefined styles from being loaded. If you use this option, you - need to load a glossary style package (such as nostyles +

    This prevents all the predefined styles from being loaded. If you use this option, you need to load a glossary +style package (such as glossary-mcols). Also if you use - this option, you can’t use the ). Also if you use this option, you can’t use the style package option. Instead you must either - use package option. Instead +you must either use \setglossarystyle{style} or the style key in the optional argument to - style key in the optional argument to \printglossary. Example: - - -

    - \usepackage[nostyles]{glossaries} -  
    \usepackage{glossary-mcols} -  
    \setglossarystyle{mcoltree} -
    -

    -

    -. +Example: + + +

    +
    +\usepackage[nostyles]{glossaries} + 
    \usepackage{glossary-mcols} + 
    \setglossarystyle{mcoltree} +
    +

    +

    +

    +

    nonumberlist

    This option will suppress the associated nonumberlist +

    This option will suppress the associated number lists in the glossaries (see also - §5 Number lists). Note that if you use Options s in the glossaries (see also §5 Number lists). Note +that if you use Options 2 or 3 (makeindex or or xindy) then the - locations must still be valid. This package option merely prevents the ) then the locations must still be valid. This +package option merely prevents the number list from - being displayed, but both from being displayed, but both makeindex and and xindy still require a location or - cross-reference for each term that’s indexed. Remember that +still require a location or cross-reference for each term that’s indexed. Remember that number list includes any - cross-references, so suppressing the +includes any cross-references, so suppressing the number list will also hide the cross-references (see - below). -

    - will also hide the cross-references (see +below). +

    +

    +

    seeautonumberlist

    If you suppress the seeautonumberlist +

    If you suppress the number lists with s with nonumberlist, described - above, this will also suppress any cross-referencing information supplied by - the see key in , described above, this will also suppress any cross-referencing +information supplied by the see key in \newglossaryentry or or \glssee. If you use . If you use seeautonumberlist, - the see key will automatically implement nonumberlist=false for that entry. - (Note this doesn’t affect \glssee.) For further details see §8 Cross-Referencing - Entries. -

    -, the see +key will automatically implement nonumberlist=false for that entry. (Note this doesn’t affect \glssee.) For +further details see §8 Cross-Referencing Entries. +

    +

    +

    counter

    This is a ⟨counter={value} +

    This is a ⟨key⟩=⟨value⟩ option. (Default is counter=page.) The value should be - the name of the default counter to use in the counter=page.) The value should be the name of the default counter to +use in the number lists (see §5 Number - lists). -

    -s (see §5 Number lists). +

    +

    +

    nopostdot

    This is a boolean option. If no value is specified, true is assumed. When set to - true, this option suppresses the default post description dot used by some of the - predefined styles. The default setting is nopostdot=false. -
    +class="cmss-10">nopostdot={boolean} +

    This is a boolean option. If no value is specified, true is assumed. When set to true, this option suppresses the +default post description dot used by some of the predefined styles. +

    The default setting is nopostdot=false for the base glossaries package and nopostdot=true for glossaries-extra. + + +

    The glossaries-extra package provides postdot, which is equivalent to nopostdot=false, and also postpunc, +which allows you to choose a different punctuation character.
    +

    +

    +

    +

    nogroupskip

    This is a boolean option. If no value is specified, true is assumed. When set to - true, this option suppresses the default vertical gap between groups used by some of - the predefined styles. The default setting is nogroupskip=false. -
    - - -

    +class="cmss-10">nogroupskip={boolean} +

    This is a boolean option. If no value is specified, true is assumed. When set to true, this option suppresses the +default vertical gap between letter groups used by some of the predefined styles. The default setting is +nogroupskip=false. +

    If you are using bib2gls without the --group (or -g) switch then you don’t need to use nogroupskip=true as +there won’t be any letter groups.
    +

    +

    +

    +

    stylemods={list} (glossaries-extra.sty)

    +

    Load the glossaries-extra-stylemods package and patch the predefined styles. The ⟨list⟩ argument is +optional. If present, this will also load glossary-element.sty for each ⟨element⟩ in the comma-separated +⟨list⟩. +

    -

    Top

    2.4 Sorting Options

    -
    -sort
    If you use Options 2 or 3, this package option is the only way of specifying how to - sort the glossaries. Only Option 1 allows you to specify sort methods for individual - glossaries via the sort key in the optional argument of \printnoidxglossary. If - you have multiple glossaries in your document and you are using Option 1, only - use the package options sort=def or sort=use if you want to set this sort method - for all your glossaries. -

    This is a ⟨key⟩=⟨value⟩ option where ⟨value⟩ may be one of the following:

    -
      -
    • standard : entries are sorted according to the value of the sort key used in - \newglossaryentry (if present) or the name key (if sort key is missing); -
    • -
    • def : entries are sorted in the order in which they were defined (the sort key - in \newglossaryentry is ignored); -
    • -
    • use : entries are sorted according to the order in which they are used in the - document (the sort key in \newglossaryentry is ignored). -

      Both sort=def and sort=use set the sort key to a six digit number via -


      \glssortnumberfmt  \glssortnumberfmt{number}

      -

      - (padded with leading zeros, where necessary). This can be redefined, if required, - before the entries are defined (in the case of sort=def) or before the entries are - used (in the case of sort=use). -

    • -
    • none : this setting is new to version 4.30 and is only for documents that don’t use - \makeglossaries (Options 2 or 3) or \makenoidxglossaries (Option 1). It - omits the code used to sanitize or escape the sort value, since it’s not - required. This can help to improve the document build speed, especially - if there are a large number of entries. This option can’t be used with - \printglossary or \printnoidxglossary (or the iterative versions - \printglossaries or \printnoidxglossaries). It may be used with - glossaries-extra’s \printunsrtglossary (Option 5).
    -

    Note that the group styles (such as listgroup) are incompatible with the sort=use and - sort=def options. -

    The default is sort=standard. When the standard sort option is in use, you can hook into - the sort mechanism by redefining: -


    \glsprestandardsort  \glsprestandardsort{sort cs}{type}{label}

    - - -

    - where ⟨sort cs⟩ is a temporary control sequence that stores the sort value (which was - either explicitly set via the sort key or implicitly set via the name key) before any - escaping of the Indexing Options +

    +

    +

    seenoindex={value}

    +

    Introduced in version 4.24, this option may take one of three values: error, warn or ignore. The see key +automatically indexes the cross-referenced entry using \glsadd. This means that if this key is +used in an entry definition before the relevant glossary file has been opened, the indexing can’t be +performed. Since this is easy to miss, the glossaries package by default issues an error message if the +see key is used before \makeglossaries. This option allows you to change the error into just a +warning (seenoindex=warn) or ignore it (seenoindex=ignore) if, for example, you want to temporarily +comment out \makeglossaries to speed up the compilation of a draft document by omitting the +indexing. + + +

    +

    +

    esclocations={boolean}

    +

    This is a boolean option. The default is esclocations=true, which is needed for Options 2 and 3. With Option 1 +\makenoidxglossaries changes it to esclocations=false. With Option 4 (bib2gls), this setting is +ignored. +

    Both makeindex/ and xindy special characters is performed. By default - \glsprestandardsort just does: -


    \glsdosanitizesort  \glsdosanitizesort

    -

    - which sanitizes ⟨sort cs⟩ if the sanitizesort package option is set (or does nothing if the - package option sanitizesort=false is used). -

    The other arguments, ⟨type⟩ and ⟨label⟩, are the glossary type and the entry label for the - current entry. Note that ⟨type⟩ will always be a control sequence, but ⟨label⟩ will be in the - form used in the first argument of \newglossaryentry. -

    Redefining \glsprestandardsort won’t affect any entries that have already been - defined and will have no effect at all if you are using sort=def or sort=use. -
    -

    - -

    Example 1 (Mixing Alphabetical and Order of Definition - Sorting) -

    Suppose I have three glossaries: main, acronym and notation, and let’s suppose I want - the main and acronym glossaries to be sorted alphabetically, but the notation type - should be sorted in order of definition. -

    For Option 1, I just need to set the sort key in the optional argument of - \printnoidxglossary: - - + id="dx1-63006"> are fussy about the location formats (makeindex more so than xindy) so the +glossaries package tries to ensure that special characters are escaped and allows for the location to be substituted +for a format that’s more acceptable to the indexing application. This requires a bit of trickery to circumvent the +problem posed by TEX’s asynchronous output routine, which can go wrong and also adds to the complexity of +the document build. +

    If you’re sure that your locations will always expand to an acceptable format (or you’re prepared to +post-process the glossary file before passing it to the relevant indexing application) then use esclocations=false to +avoid the complex escaping of location values. (See “Writing information to associated files” in the documented +code for further details.) +

    This isn’t an issue for Options 1 or 4 as the locations are written to the aux file so no syntax conversion is +required. +

    -
    - \printnoidxglossary[sort=word] -  
    \printnoidxglossary[type=acronym,sort=word] -  
    \printnoidxglossary[type=notation,sort=def] -
    -

    -

    For Options 2 or 3, I can set the sort to standard (which is the default, but can be - explicitly set via the package option sort=standard), and I can either define all my main - and acronym entries, then redefine \glsprestandardsort to set ⟨sort cs⟩ to an - incremented integer, and then define all my notation entries. Alternatively, I can - redefine \glsprestandardsort to check for the glossary type and only modify ⟨sort cs⟩ if - ⟨type⟩ is notation. -

    The first option can be achieved as follows: - - -

    -
    - \newcounter{sortcount} -  
    \renewcommand{\glsprestandardsort}[3]{% -  
      \stepcounter{sortcount}% -  
      \edef#1{\glssortnumberfmt{\arabic{sortcount}}}% -  
    } -
    -

    The second option can be achieved as follows: - - -

    -
    - \newcounter{sortcount} -  
    \renewcommand{\glsprestandardsort}[3]{% -  
      \ifdefstring{#2}{notation}% -  
      {% -  
         \stepcounter{sortcount}% -  
         \edef#1{\glssortnumberfmt{\arabic{sortcount}}}% -  
      }% -  
      {% -  
         \glsdosanitizesort -  
      }% -  
    } +

    indexonlyfirst={boolean}

    +

    This is a boolean option that specifies whether to only add information to the external glossary file on first use. +The default is indexonlyfirst=false, which will add a line to the file every time one of the \gls-like or +\glstext-like commands are used. Note that \glsadd will always add information to the external glossary +file2.4 (since +that’s the purpose of that command). +

    Resetting the first use flag with commands like \glsreset after an entry has been indexed will cause that +entry to be indexed multiple times if it’s used again after the reset. Likewise unsetting the first use flag before +an entry has been indexed will prevent it from being indexed (unless specifically indexed with \glsadd). +
    +

    +

    You can customise this by redefining +


    \glswriteentry{label}{wr-code}

    +

    +where ⟨label⟩ is the entry’s label and ⟨wr-code⟩ is the code that writes the entry’s information to the external file. +The default definition of \glswriteentry is: + + +

    +
    +\newcommand*{\glswriteentry}[2]{% + 
      \ifglsindexonlyfirst + 
        \ifglsused{#1}{}{#2}% + 
      \else + 
        #2% + 
      \fi + 
    } +
    +

    This checks the indexonlyfirst package option (using \ifglsindexonlyfirst) and does ⟨wr-code⟩ if this is false +otherwise it only does ⟨wr-code⟩ of the entry hasn’t been used. +

    For example, suppose you only want to index the first use for entries in the acronym glossary and not in the +main (or any other) glossary: + + +

    +
    +\renewcommand*{\glswriteentry}[2]{% + 
     \ifthenelse{\equal{\glsentrytype{#1}}{acronym}} + 
     {\ifglsused{#1}{}{#2}}% + 
     {#2}% + 
    } +
    +

    Here I’ve used \ifthenelse to ensure the arguments of \equal are fully expanded before the comparison is +made. +

    With the glossaries-extra package it’s possible to only index first use for particular categories. For example, if +you only want this enabled for abbreviations and acronyms then you can set the indexonlyfirst attribute for the +abbreviation and acronym categories. (Instead of using the indexonlyfirst package option.) See the +glossaries-extra manual for further details. +

    +

    +

    indexcrossrefs={boolean} (glossaries-extra.sty)

    +

    If true, this will automatically index any cross-referenced entries that haven’t been marked as used at +the end of the document. Increases document build time. See glossaries-extra manual for further +details. +

    +

    +

    autoseeindex={boolean} (glossaries-extra.sty)

    +

    If true, makes the see and seealso keys automatically index the cross-reference when the entry is defined +(default, and the only option with just the base glossaries package). +

    +

    +

    record={value} (glossaries-extra.sty)

    +

    If not off, this option indicates that bib2gls is required. If the value is omitted, only is assumed. Permitted +values: +

    +off
    bib2gls isn’t being used; +
    +only
    bib2gls is being used to fetch entries from a bib file, to sort the entries and collate the number + lists, where the location information is the same as for Options 13; + + +
    +nameref
    like only but provides extra information that allows the associated title to be used instead of + the location number; +
    +alsoindex
    a hybrid approach where bib2gls is begin used to fetch entries from a bib file but makeindex + or xindy are used for the indexing. This requires a more complicated document build and isn’t + recommended.
    +

    See glossaries-extra manual for further details. +

    +

    +

    equations={boolean} (glossaries-extra.sty)

    +

    If true, this option will cause the default location counter to automatically switch to equation when inside a +numbered equation environment. +

    +

    +

    floats={boolean} (glossaries-extra.sty)

    +

    If true, this option will cause the default location counter to automatically switch to the corresponding counter +when inside a float. (Remember that with floats it’s the \caption command that increments the counter so the +location will be incorrect if an entry is indexed within the float before the caption.) +

    +

    +

    indexcounter (glossaries-extra.sty)

    +

    This valueless option is primarily intended for use with bib2gls and hyperref allowing the page location +hyperlink to the relevant point in the page (rather than the top of the page). Unexpected results will occur with +other indexing methods. See glossaries-extra manual for further details. +

    +

    +

    Top

    2.5 Sorting Options

    +

    This section is mostly for Options 2 and 3. Only the sort and order options are applicable for +Option 1. +

    With Options 46, only sort=none is applicable (and this is automatically implemented by +record=only and record=nameref). With bib2gls, the sort method is provided in the optional argument of +\GlsXtrLoadResources not with the sort package option. There’s no sorting with Options 5 and 6. +
    + + +

    +

    +

    +

    sanitizesort={boolean}

    +

    This is a boolean option that determines whether or not to sanitize the sort value when writing to the external +glossary file. For example, suppose you define an entry as follows: + + +

    +
    +\newglossaryentry{hash}{name={\#},sort={#}, + 
     description={hash symbol}} +
    +

    The sort value (#) must be sanitized before writing it to the glossary file, otherwise LATEX will try to +interpret it as a parameter reference. If, on the other hand, you want the sort value expanded, you need to +switch off the sanitization. For example, suppose you do: + + +

    +
    +\newcommand{\mysortvalue}{AAA} + 
    \newglossaryentry{sample}{% + 
      name={sample}, + 
      sort={\mysortvalue}, + 
      description={an example}} +
    +

    and you actually want \mysortvalue expanded, so that the entry is sorted according to AAA, then use the +package option sanitizesort=false. +

    The default for Options 2 and 3 is sanitizesort=true, and the default for Option 1 is sanitizesort=false. +

    +

    +

    sort={value}

    +

    If you use Options 2 or 3, this package option is the only way of specifying how to sort the glossaries. Only +Option 1 allows you to specify sort methods for individual glossaries via the sort key in the optional argument +of \printnoidxglossary. If you have multiple glossaries in your document and you are using Option 1, +only use the package options sort=def or sort=use if you want to set this sort method for all your +glossaries. +

    This is a ⟨key⟩=⟨value⟩ option where ⟨value⟩ may be one of the following:

    +
      +
    • standard : entries are sorted according to the value of the sort key used in \newglossaryentry (if + present) or the name key (if sort key is missing); +
    • +
    • def : entries are sorted in the order in which they were defined (the sort key in \newglossaryentry + is ignored); +
    • +
    • use : entries are sorted according to the order in which they are used in the document (the sort + key in \newglossaryentry is ignored). +

      Both sort=def and sort=use set the sort key to a six digit number via +


      \glssortnumberfmt{number}

      +

      + (padded with leading zeros, where necessary). This can be redefined, if required, before the entries are + defined (in the case of sort=def) or before the entries are used (in the case of sort=use). +

    • +
    • none : this setting is new to version 4.30 and is only for documents that don’t use \makeglossaries + (Options 2 or 3) or \makenoidxglossaries (Option 1). It omits the code used to sanitize or escape the + sort value, since it’s not required. This can help to improve the document build speed, especially if there + are a large number of entries. + + +

      This option can’t be used with \printglossary or \printnoidxglossary (or the iterative + versions \printglossaries or \printnoidxglossaries). It may be used with glossaries-extra’s + \printunsrtglossary (Option 5).

    +

    Note that the group styles (such as listgroup) are incompatible with the sort=use and sort=def options. +

    The default is sort=standard. When the standard sort option is in use, you can hook into the sort mechanism +by redefining: +


    \glsprestandardsort{sort cs}{type}{label}

    +

    +where ⟨sort cs⟩ is a temporary control sequence that stores the sort value (which was either explicitly set via the +sort key or implicitly set via the name key) before any escaping of the makeindex/xindy special characters is +performed. By default \glsprestandardsort just does: +


    \glsdosanitizesort

    +

    +which sanitizes ⟨sort cs⟩ if the sanitizesort package option is set (or does nothing if the package option +sanitizesort=false is used). +

    The other arguments, ⟨type⟩ and ⟨label⟩, are the glossary type and the entry label for the current entry. Note +that ⟨type⟩ will always be a control sequence, but ⟨label⟩ will be in the form used in the first argument of +\newglossaryentry. +

    Redefining \glsprestandardsort won’t affect any entries that have already been defined and will have no +effect at all if you are using sort=def or sort=use.
    +

    + +

    Example 1 (Mixing Alphabetical and Order of Definition Sorting) +

    Suppose I have three glossaries: main, acronym and notation, and let’s suppose I want the main and +acronym glossaries to be sorted alphabetically, but the notation type should be sorted in order of +definition. +

    For Option 1, the sort option can be used in \printnoidxglossary: + + +

    +
    +\printnoidxglossary[sort=word] + 
    \printnoidxglossary[type=acronym,sort=word] + 
    \printnoidxglossary[type=notation,sort=def] +
    +

    +

    For Options 2 or 3, I can set the sort to standard (which is the default, but can be explicitly set via the +package option sort=standard), and I can either define all my main and acronym entries, then redefine +\glsprestandardsort to set ⟨sort cs⟩ to an incremented integer, and then define all my notation entries. +Alternatively, I can redefine \glsprestandardsort to check for the glossary type and only modify ⟨sort cs⟩ if +⟨type⟩ is notation. +

    The first option can be achieved as follows: + + +

    +
    +\newcounter{sortcount} + 
    \renewcommand{\glsprestandardsort}[3]{% + 
      \stepcounter{sortcount}% + 
      \edef#1{\glssortnumberfmt{\arabic{sortcount}}}% + 
    } +
    +

    The second option can be achieved as follows: + + +

    +
    +\newcounter{sortcount} + 
    \renewcommand{\glsprestandardsort}[3]{% + 
      \ifdefstring{#2}{notation}% + 
      {% + 
         \stepcounter{sortcount}% + 
         \edef#1{\glssortnumberfmt{\arabic{sortcount}}}% + 
      }% + 
      {% + 
         \glsdosanitizesort + 
      }% + 
    }
    -

    (

    (\ifdefstring is defined by the etoolbox package.) For a complete document, see the - sample file package.) For a complete document, see the sample file +sampleSort.tex.

    -
    -

    -

    ____________________________

    +

    +

    ____________________________

    -

    +

    Example 2 (Customizing Standard Sort (Options 2 or - 3)) -

    Suppose you want a glossary of people and you want the names listed as ⟨first-name⟩ - ⟨surname⟩ in the glossary, but you want the names sorted by ⟨ (Customizing Standard Sort (Options 2 or 3)) +

    Suppose you want a glossary of people and you want the names listed as ⟨first-name⟩ ⟨surname⟩ in the glossary, +but you want the names sorted by ⟨surname⟩, ⟨first-name⟩. You - can do this by defining a command called, say, first-name⟩. You can do this by defining a command called, say, +\name{first-name}{surname} that you - can use in the name key when you define the entry, but hook into the standard - sort mechanism to temporarily redefine } that you can use in the name key when you define the entry, but +hook into the standard sort mechanism to temporarily redefine \name while the sort value is being - set. -

    First, define two commands to set the person’s name: - - +set. +

    First, define two commands to set the person’s name: + +

    -
    - \newcommand{\sortname}[2]{#2, #1} -  
    \newcommand{\textname}[2]{#1 #2} +
    +\newcommand{\sortname}[2]{#2, #1} + 
    \newcommand{\textname}[2]{#1 #2}
    -

    and

    and \name needs to be initialised to \textname: - - + +

    -
    - \let\name\textname +
    +\let\name\textname
    -

    Now redefine

    Now redefine \glsprestandardsort so that it temporarily sets \name to \sortname - and expands the sort value, then sets \sortname and expands the sort +value, then sets \name to \textname so that the person’s name - appears as ⟨\textname so that the person’s name appears as ⟨first-name⟩ ⟨surname⟩ in the text: - - -

    -
    - \renewcommand{\glsprestandardsort}[3]{% -  
     \let\name\sortname -  
     \edef#1{\expandafter\expandonce\expandafter{#1}}% -  
     \let\name\textname -  
     \glsdosanitizesort -  
    } +class="cmti-10">surname⟩ in the +text: + + +

    +
    +\renewcommand{\glsprestandardsort}[3]{% + 
     \let\name\sortname + 
     \edef#1{\expandafter\expandonce\expandafter{#1}}% + 
     \let\name\textname + 
     \glsdosanitizesort + 
    }
    -

    (The somewhat complicate use of \expandafter etc helps to protect fragile commands, - but care is still needed.) -

    Now the entries can be defined: - - -

    -
    - \newglossaryentry{joebloggs}{name={\name{Joe}{Bloggs}}, -  
      description={some information about Joe Bloggs}} -  
    \newglossaryentry{johnsmith}{name={\name{John}{Smith}}, -  
      description={some information about John Smith}} -
    -

    For a complete document, see the sample file

    (The somewhat complicate use of \expandafter etc helps to protect fragile commands, but care is still +needed.) +

    Now the entries can be defined: + + +

    +
    +\newglossaryentry{joebloggs}{name={\name{Joe}{Bloggs}}, + 
      description={some information about Joe Bloggs}} + 
    \newglossaryentry{johnsmith}{name={\name{John}{Smith}}, + 
      description={some information about John Smith}} +
    +

    For a complete document, see the sample file samplePeople.tex.

    -
    -

    -

    ____________________________

    -
    -

    +

    ____________________________

    +

    +

    +

    order
    This may take two values: order={value}

    +

    This may take two values: word or or letter. The default is word ordering. -

    Note that the . The default is word ordering. +

    Note that with Options 2 and 3, the order option has no effect if you don’t use option has no effect if you don’t use makeglossaries. -
    -

    -

    If you use . +

    +

    +

    If you use Option 1, this setting will be used if you use sort=standard in the optional - argument of sort=standard in the optional argument of +\printnoidxglossary: - - + id="dx1-74006">: + +

    -
    - \printnoidxglossary[sort=standard] +
    +\printnoidxglossary[sort=standard]
    -

    Alternatively, you can specify the order for individual glossaries: - - +

    Alternatively, you can specify the order for individual glossaries: + +

    -
    - \printnoidxglossary[sort=word] -  
    \printnoidxglossary[type=acronym,sort=letter] +
    +\printnoidxglossary[sort=word] + 
    \printnoidxglossary[type=acronym,sort=letter]
    -

    -

    -

    +

    With bib2gls, use the break-at option in \GlsXtrLoadResources instead of order.
    +

    +

    +

    +

    makeindex

    (Option 2) The glossary information and indexing style file will be written in - makeindex +

    (Option 2) The glossary information and indexing style file will be written in makeindex format. If you use format. If you use +makeglossaries, it will automatically detect that it - needs to call , it will automatically detect that it needs to call makeindex. If you don’t use . If you don’t use makeglossaries, you need to remember - to use , +you need to remember to use makeindex not not xindy. The indexing style file will been given a .ist - extension. -

    You may omit this package option if you are using Option 2 as this is the default. It’s - available in case you need to override the effect of an earlier occurrence of . The indexing style file will been given a ist +extension. +

    You may omit this package option if you are using Option 2 as this is the default. It’s available in case you +need to override the effect of an earlier occurrence of xindy in the - package option list. -

    - in the package option list. +

    +

    +

    xindy

    (Option 3) The glossary information and indexing style file will be written in - xindy +

    (Option 3) The glossary information and indexing style file will be written in xindy format. If you use format. If you use +makeglossaries, it will automatically detect that it - needs to call , it will automatically detect that it needs to call xindy. If you don’t use . If you don’t use makeglossaries, you need to remember - to use , +you need to remember to use xindy not not makeindex. The indexing style file will been given a .xdy - extension. -

    This package option may additionally have a value that is a ⟨. The indexing style file will been given a xdy +extension. +

    This package option may additionally have a value that is a ⟨key⟩=⟨value⟩ comma-separated - list to override the language and codepage. For example: - - +class="cmti-10">value⟩ comma-separated list to override the +language and codepage. For example: + +

    -
    - \usepackage[xindy={language=english,codepage=utf8}] -  
      {glossaries} +
    +\usepackage[xindy={language=english,codepage=utf8}] + 
      {glossaries}
    -

    You can also specify whether you want a number group in the glossary. This defaults to - true, but can be suppressed. For example: - - +

    You can also specify whether you want a number group in the glossary. This defaults to true, but can be +suppressed. For example: + +

    -
    - \usepackage[xindy={glsnumbers=false}]{glossaries} +
    +\usepackage[xindy={glsnumbers=false}]{glossaries}
    -

    If no value is supplied to this package option (either simply writing xindy or writing - xindy={}) then the language, codepage and number group settings are unchanged. See - §11 Xindy (Option 3) for further details on using

    If no value is supplied to this package option (either simply writing xindy or writing xindy={}) then the +language, codepage and number group settings are unchanged. See §11 Xindy (Option 3) for further details on +using xindy with the glossaries - package. -

    - with the glossaries package. +

    +

    +

    xindygloss

    (xindygloss +

    (Option 3) This is equivalent to xindy={} (that is, the xindy option without any - value supplied) and may be used as a document class option. The language and code - page can be set via option without any value supplied) and may be +used as a document class option. The language and code page can be set via \GlsSetXdyLanguage and and +\GlsSetXdyCodePage (see §11.1 - (see §11.1 Language and Encodings.) -

    -

    +

    +

    xindynoglsnumbers

    (xindynoglsnumbers +

    (Option 3) This is equivalent to xindy={glsnumbers=false} and may - be used as a document class option. -

    -xindy={glsnumbers=false} and may be used as a document class +option. +

    +

    +

    automake

    This is option was introduced to version 4.08 as a boolean option. As from version - 4.42 it may now take three values: automake={value} +

    This is option was introduced to version 4.08 as a boolean option. As from version 4.42 it may now take three +values: false (default), true or immediate. If no option is - supplied, immediate is assumed. The option automake=true will attempt to run - immediate. If no option is supplied, immediate is assumed. The +option automake=true will attempt to run makeindex or or xindy using T using TEX’s \write18 mechanism at the end of the document. - The option automake=immediate will attempt to run mechanism +at the end of the document. The option automake=immediate will attempt to run makeindex or or +xindy at the start - of at the start of \makeglossaries using using \immediate (before the glossary files have been - opened). -

    In the case of automake=true, the associated files are created at the end of the - document ready for the next LATEX run. Since there is a possibility of commands such - as \gls occurring on the last page of the document, it’s not possible to use \immediate - to close the associated file or with \write18 since the writing of the final - indexing lines may have been delayed. In certain situations this can mean that - the

    In the case of automake=true, the associated files are created at the end of the document ready for +the next LATEX run. Since there is a possibility of commands such as \gls occurring on the +last page of the document, it’s not possible to use \immediate to close the associated file or with +\write18 since the writing of the final indexing lines may have been delayed. In certain situations +this can mean that the \write18 fails. In such cases, you will need to use automake=immediate - instead. -

    With automake=immediate, you will get a warning on the first LATEX run as the - associated glossary files don’t exist yet. -

    Since this mechanism can be a security risk, some TEX distributions disable it - completely, in which case this option won’t have an effect. (If this option doesn’t appear - to work, search the log file for “runsystem” and see if it is followed by “enabled” or - “disabled”.) -

    Some distributions allow \write18 in a restricted mode. This mode has a limited - number of trusted applications, which usually includes automake=immediate +instead. +

    With automake=immediate, you will get a warning on the first LATEX run as the associated glossary files +don’t exist yet. + + +

    Since this mechanism can be a security risk, some TEX distributions disable it completely, in which case +this option won’t have an effect. (If this option doesn’t appear to work, search the log file for “runsystem” and +see if it is followed by “enabled” or “disabled”.) +

    Some distributions allow \write18 in a restricted mode. This mode has a limited number of trusted +applications, which usually includes makeindex but may not include - but may not include xindy. So if you have the restricted mode on, . So if you have the restricted mode +on, automake should work with should work with makeindex - but may not work with but may not work with xindy. - - -

    However even in unrestricted mode this option may not work with . +

    However even in unrestricted mode this option may not work with xindy as as xindy uses - language names that don’t always correspond with uses language names that +don’t always correspond with \babel’s language names. (The - ’s language names. (The makeglossaries script applies mappings to assist you.) Note that you still need - at least two LAT script applies mappings to assist +you.) Note that you still need at least two LATEX runs to ensure the document is up-to-date with this - setting. -

    Since this package option attempts to run the indexing application on every - LATEX run, its use should be considered a last resort for those who can’t work out - how to incorporate the indexing application into their document build. The default - value for this option is automake=false. -

    -
    -

    -

    -

    Top

    2.5 Acronym Options

    -
    -acronym
    This creates a new glossary with the label acronym. This is equivalent - to: - - -
    - \newglossary[alg]{acronym}{acr}{acn}{\acronymname} -
    -

    It will also define -


    \printacronyms  \printacronyms[options]

    -

    - that’s equivalent to

    -
    - \printglossary[type=acronym,options] -
    -
    (unless that command is already defined before the beginning of the document or the - package option compatible-3.07 is used). -

    If you are using Option 1, you need to use

    -
    - \printnoidxglossary[type=acronym,options] -
    -
    to display the list of acronyms. -

    If the acronym package option is used, \acronymtype is set to acronym otherwise it is set to - main.2.4 - Entries that are defined using \newacronym are placed in the glossary whose label is - given by \acronymtype, unless another glossary is explicitly specified. -

    Remember to use the nomain package option if you’re only interested in using - this acronym glossary. (That is, you don’t intend to use the main glossary.) -
    -

    -

    -acronyms
    This is equivalent to acronym=true and may be used in the document class option - list. -
    -acronymlists
    By default, only the \acronymtype glossary is considered to be a list of - acronyms. If you have other lists of acronyms, you can specify them as a - comma-separated list in the value of acronymlists. For example, if you use the acronym - package option but you also want the main glossary to also contain a list of acronyms, - you can do: - - -
    - \usepackage[acronym,acronymlists={main}]{glossaries} -
    -

    No check is performed to determine if the listed glossaries exist, so you can add - glossaries you haven’t defined yet. For example: - - -

    -
    - \usepackage[acronym,acronymlists={main,acronym2}] -  
      {glossaries} -  
    \newglossary[alg2]{acronym2}{acr2}{acn2}% -  
      {Statistical Acronyms} -
    -

    You can use -


    \DeclareAcronymList  \DeclareAcronymList{list}

    -

    - instead of or in addition to the acronymlists option. This will add the glossaries given in - ⟨list⟩ to the list of glossaries that are identified as lists of acronyms. To replace the list of - acronym lists with a new list use: -


    \SetAcronymLists  \SetAcronymLists{list}

    -

    -

    You can determine if a glossary has been identified as being a list of acronyms - using: -


    \glsIfListOfAcronyms  \glsIfListOfAcronyms{label}{true part}{false part} -

    -

    -

    -shortcuts
    This option provides shortcut commands for acronyms. See §13 Acronyms and - Other Abbreviations for further details. Alternatively you can use: -


    \DefineAcronymSynonyms  \DefineAcronymSynonyms

    -

    -

    -

    -

    -

    Top

    2.5.1 Deprecated Acronym Style Options

    -

    The package options listed in this section are now deprecated but are kept for -backward-compatibility. Use \setacronymstyle instead. See §13 Acronyms and Other -Abbreviations for further details. -

    -description
    This option changes the definition of \newacronym to allow a description. This - option may be replaced by - - -
    - \setacronymstyle{long-short-desc} -
    -

    or (with smallcaps) - - -

    -
    - \setacronymstyle{long-sc-short-desc} -
    -

    or (with smaller) - - -

    -
    - \setacronymstyle{long-sm-short-desc} -
    -

    or (with footnote) - - -

    -
    - \setacronymstyle{footnote-desc} -
    -

    or (with footnote and smallcaps) - - -

    -
    - \setacronymstyle{footnote-sc-desc} -
    -

    or (with footnote and smaller) - - -

    -
    - \setacronymstyle{footnote-sm-desc} -
    -

    or (with dua) - - -

    -
    - \setacronymstyle{dua-desc} -
    -

    -

    -smallcaps
    This option changes the definition of \newacronym and the way that acronyms are - displayed. This option may be replaced by: - - -
    - \setacronymstyle{long-sc-short} -
    -

    or (with description) - - -

    -
    - \setacronymstyle{long-sc-short-desc} -
    -

    or (with description and footnote) - - -

    -
    - \setacronymstyle{footnote-sc-desc} -
    -

    -

    -smaller
    This option changes the definition of \newacronym and the way that acronyms are - displayed. -

    If you use this option, you will need to include the relsize package or otherwise define - \textsmaller or redefine \acronymfont.
    -

    - This option may be replaced by: - - -

    -
    - \setacronymstyle{long-sm-short} -
    -

    or (with description) - - +setting. +

    Since this package option attempts to run the indexing application on every LATEX run, its use should be +considered a last resort for those who can’t work out how to incorporate the indexing application into their +document build. The default value for this option is automake=false. +

    -
    - \setacronymstyle{long-sm-short-desc} -
    -

    or (with description and footnote) - - +

    disablemakegloss

    +

    This valueless option indicates that \makeglossaries and \makenoidxglossaries should be disabled. This +option is provided in the event that you have to use a class or package that disregards the advice in §1.1 Indexing +Options and automatically performs \makeglossaries or \makenoidxglossaries but you don’t want this. (For +example, you want to use a different indexing method or you want to disable indexing while working on a draft +document.) +

    This option may be passed in the standard document class option list or passed using \PassOptionsToPackage +before glossaries is loaded. Note that this does nothing if \makeglossaries or \makenoidxglossaries has +already been used whilst enabled. +

    -
    - \setacronymstyle{footnote-sm-desc} -
    -

    -

    -footnote
    This option changes the definition of \newacronym and the way that acronyms are - displayed. This option may be replaced by: - - -
    - \setacronymstyle{footnote} -
    -

    or (with smallcaps) - - +

    restoremakegloss

    +

    Cancels the effect of disablemakegloss. This option may be used in \setupglossaries. It issues a +warning if \makeglossaries or \makenoidxglossaries has already been used whilst enabled. For +example, suppose the class customclass.cls automatically loads glossaries and does \makeglossaries +but you need an extra glossary, which has to be defined before \makeglossaries, then you can +do: + +

    -
    - \setacronymstyle{footnote-sc} +
    +\documentclass[disablemakegloss]{customclass} + 
    \newglossary*{functions}{Functions} + 
    \setupglossaries{restoremakegloss} + 
    \makeglossaries
    -

    or (with smaller) - - +

    or + +

    -
    - \setacronymstyle{footnote-sm} +
    +\PassOptionsToPackage{disablemakegloss}{glossaries} + 
    \documentclass{customclass} + 
    \newglossary*{functions}{Functions} + 
    \setupglossaries{restoremakegloss} + 
    \makeglossaries
    -

    or (with description) - - +

    +

    Note that restoring these commands doesn’t necessarily mean that they can be used. It just means that their +normal behaviour given the current settings will apply. For example, if you use the record=only or record=nameref +options with glossaries-extra then you can’t use \makeglossaries or \makenoidxglossaries regardless of +restoremakegloss. +

    -
    - \setacronymstyle{footnote-desc} -
    -

    or (with smallcaps and description) - - +

    Top

    2.6 Glossary Type Options

    +

    -
    - \setacronymstyle{footnote-sc-desc} -
    -

    or (with smaller and description) - - +

    nohypertypes={list}

    +

    Use this option if you have multiple glossaries and you want to suppress the entry hyperlinks for a particular +glossary or glossaries. The value of this option should be a comma-separated list of glossary types where \gls +etc shouldn’t have hyperlinks by default. Make sure you enclose the value in braces if it contains any commas. +Example: + + +

    +
    +\usepackage[acronym,nohypertypes={acronym,notation}] + 
      {glossaries} + 
    \newglossary[nlg]{notation}{not}{ntn}{Notation} +
    +

    The values must be fully expanded, so don’t try nohypertypes=\acronymtype. You may also +use +


    \GlsDeclareNoHyperList{list}

    +

    +instead or additionally. See §6 Links to Glossary Entries for further details. +

    -
    - \setacronymstyle{footnote-sm-desc} +

    nomain

    +

    This suppresses the creation of the main glossary and associated glo file, if unrequired. Note that if you use this +option, you must create another glossary in which to put all your entries (either via the acronym (or acronyms) +package option described in §2.7 Acronym and Abbreviation Options or via the symbols, numbers or +index options described in §2.8 Other Options or via \newglossary described in §12 Defining New +Glossaries). +

    If you don’t use the main glossary and you don’t use this option, makeglossaries will produce a warning.
    -

    -

    -dua
    This option changes the definition of \newacronym so that acronyms are always - expanded. This option may be replaced by: - - -
    - \setacronymstyle{dua} -
    -

    or (with description) - - -

    -
    - \setacronymstyle{dua-desc} +

    +

    +
    +Warning: File 'filename.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.
    -

    -

    -
    -

    +

    If you did actually want to use the main glossary and you see this warning, check that you have referenced the +entries in that glossary via commands such as \gls. +

    -

    Top

    2.6 Other Options

    -

    Other available options that don’t fit any of the above categories are: -

    -symbols
    This option defines a new glossary type with the label symbols +

    This valueless option defines a new glossary type with the label symbols via - - -

    - \newglossary[slg]{symbols}{sls}{slo}{\glssymbolsgroupname} -
    -

    It also defines -


    \printsymbols  +
    +\newglossary[slg]{symbols}{sls}{slo}{\glssymbolsgroupname} +
    +

    It also defines +


    \printsymbols[options]

    -

    - which is a synonym for

    -
    -

    +which is a synonym for

    +
    +\printglossary[type=symbols,options]
    -
    -

    If you use +

    If you use Option 1, you need to use:

    -
    - +\printnoidxglossary[type=symbols,options]
    -
    to display the list of symbols. -

    Remember to use the to display the list of symbols. +

    Remember to use the nomain package option if you’re only interested in using this - symbols glossary and don’t intend to use the package option if you’re only interested in using this symbols glossary and +don’t intend to use the main glossary.
    -

    -

    The glossaries-extra package has a slightly modified version of this option which - additionally provides \glsxtrnewsymbol as a convenient shortcut method for defining - symbols. See the glossaries-extra manual for further details. -

    -

    +

    The glossaries-extra package has a slightly modified version of this option which additionally provides +\glsxtrnewsymbol as a convenient shortcut method for defining symbols. See the glossaries-extra manual for +further details.
    +

    +

    +

    +

    numbers

    This option defines a new glossary type with the label numbers +

    This valueless option defines a new glossary type with the label numbers via - - -

    - \newglossary[nlg]{numbers}{nls}{nlo}{\glsnumbersgroupname} + + +

    +
    +\newglossary[nlg]{numbers}{nls}{nlo}{\glsnumbersgroupname}
    -

    It also defines -


    \printnumbers 

    It also defines +


    \printnumbers[options]

    -

    - which is a synonym for

    -
    -

    +which is a synonym for

    +
    +\printglossary[type=numbers,options]
    -
    -

    If you use +

    If you use Option 1, you need to use:

    -
    - +\printnoidxglossary[type=numbers,options]
    -
    to display the list of numbers. -

    Remember to use the to display the list of numbers. +

    Remember to use the nomain package option if you’re only interested in using this - numbers glossary and don’t intend to use the package option if you’re only interested in using this numbers glossary and +don’t intend to use the main glossary.
    -

    -

    The glossaries-extra package has a slightly modified version of this option which - additionally provides \glsxtrnewnumber as a convenient shortcut method for defining - numbers. See the glossaries-extra manual for further details. -

    -

    +

    The glossaries-extra package has a slightly modified version of this option which additionally provides +\glsxtrnewnumber as a convenient shortcut method for defining numbers. See the glossaries-extra manual for +further details.
    +

    +

    +

    +

    index

    This option defines a new glossary type with the label index +

    This valueless option defines a new glossary type with the label index via - - -

    - \newglossary[ilg]{index}{ind}{idx}{\indexname}% + + +

    +
    +\newglossary[ilg]{index}{ind}{idx}{\indexname}%
    -

    It also defines -


    \newterm 

    It also defines +


    \newterm[options]{term}

    -

    - which is a synonym for

    -
    -

    +which is a synonym for

    +
    +\newglossaryentry{term}[type=index,name={term},% -
    description=\nopostdesc,options]
    -
    and -


    \printindex  and +


    \printindex[options]

    -

    - which is a synonym for

    -
    -

    +which is a synonym for

    +
    +\printglossary[type=index,options]
    -
    -

    If you use +

    If you use Option 1, you need to use:

    -
    - +\printnoidxglossary[type=index,options]
    -
    to display this glossary. -

    Remember to use the to display this glossary. +

    Remember to use the nomain package option if you’re only interested in using this - index glossary and don’t intend to use the main glossary. Note that you can’t mix this - option with package option if you’re only interested in using this index glossary and +don’t intend to use the main glossary. Note that you can’t mix this option with \index. Either use glossaries for the indexing or use a custom - indexing package, such as . Either use +glossaries for the indexing or use a custom indexing package, such as makeidx, , index or or imakeidx. (You can, of course, load - one of those packages and load . (You +can, of course, load one of those packages and load glossaries without the index package option.) -
    -

    - - -

    Since the index isn’t designed for terms with descriptions, you might also want to - disable the hyperlinks for this glossary using the package option nohypertypes=index or - the command -
    package option.) +

    +

    +

    Since the index isn’t designed for terms with descriptions, you might also want to disable the hyperlinks for +this glossary using the package option nohypertypes=index or the command +
    \GlsDeclareNoHyperList{index} -
    -

    The example file +

    The example file sample-index.tex illustrates the use of the index package - option. -

    - package option. + + +

    +

    +

    noglossaryindex

    This option switches off noglossaryindex +

    This valueless option switches off index if if index has been passed implicitly (for - example, through global document options). This option can’t be used in - has been passed implicitly (for example, through global +document options). This option can’t be used in \setupglossaries. -

    -compatible-2.07
    Compatibility mode for old documents created using version 2.07 or - below. -
    -compatible-3.07
    Compatibility mode for old documents created using version 3.07 or - below. -
    -kernelglossredefs
    As a legacy from the precursor glossary package, the standard glossary - commands provided by the LATEX kernel (\makeglossary and \glossary) are - redefined in terms of the glossaries package’s commands. However, they were never - documented in this user manual, and the conversion guide (“Upgrading from - the glossary package to the glossaries package”) explicitly discourages their - use. -

    The use of those kernel commands (instead of the appropriate commands documented - in this user guide) are deprecated, and you will now get a warning if you try using - them. -

    In the event that you require the original form of these kernel commands, - for example, if you need to use the glossaries package with another class or - package that also performs glossary-style indexing, then you can restore these - commands to their previous definition (that is, their definitions prior to loading the - glossaries package) with the package option kernelglossredefs=false. You may - also need to use the nomain option in the event of file extension conflicts. (In - which case, you must provide a new default glossary for use with the glossaries - package.) -

    This option may take one of three values: true (redefine with warnings, default), - false (restore previous definitions) or nowarn (redefine without warnings, not - recommended). -

    Note that the only glossary-related commands provided by the LATEX kernel are - \makeglossary and \glossary. Other packages or classes may provide additional - - - glossary-related commands or environments that conflict with glossaries (such as - \printglossary and theglossary). These non-kernel commands aren’t affected by this - package option, and you will have to find some way to resolve the conflict if you require - both glossary mechanisms. (The glossaries package will override the existing definitions - of \printglossary and theglossary.) -

    In general, if possible, it’s best to stick with just one package that provides a glossary - mechanism. (The glossaries package does check for the doc package and patches - \PrintChanges.) -

    -
    -

    +

    -

    Top

    2.7 Setting Options After the Package is Loaded

    -

    Some of the options described above may also be set after the glossaries package has been -loaded using -


    \setupglossaries  \setupglossaries{key-val list}

    -

    -The following package options can’t be used in \setupglossaries: xindy, xindygloss, + id="sec:pkgopts-acronym">Acronym and Abbreviation Options +

    +

    +

    acronym={boolean}

    +

    If true, this creates a new glossary with the label acronym. This is equivalent to: + + +

    +
    +\newglossary[alg]{acronym}{acr}{acn}{\acronymname} +
    +

    It will also define +


    \printacronyms[options]

    +

    +that’s equivalent to

    +
    xindynoglsnumbers, makeindex, nolong, nosuper, nolist, notree, nostyles, nomain, compatible-2.07, +class="cmtt-10">\printglossary[type=acronym,options] +
    +
    (unless that command is already defined before the beginning of the document or the package option translate, notranslate, acronym. These options have to be set while the package is loading, -except for the xindy sub-options which can be set using commands like \GlsSetXdyLanguage -(see §11 Xindy (Option 3) for further details). -

    If you need to use this command, use it as soon as possible after loading glossaries -otherwise you might end up using it too late for the change to take effect. For example, if you -try changing the acronym styles (such as smallcaps) after you have started defining your -acronyms, you are likely to get unexpected results. If you try changing the sort -option after you have started to define entries, you may get unexpected results. +class="cmss-10">compatible-3.07 is used). +

    If you are using Option 1, you need to use

    +
    +\printnoidxglossary[type=acronym,options]
    -

    - - +

    to display the list of acronyms. +

    If the acronym package option is used, \acronymtype is set to acronym otherwise it is set to +main.2.5 +Entries that are defined using \newacronym are placed in the glossary whose label is given by \acronymtype, +unless another glossary is explicitly specified. +

    Remember to use the nomain package option if you’re only interested in using this acronym glossary. (That +is, you don’t intend to use the main glossary.)
    +

    +

    The glossaries-extra extension package comes with an analogous abbreviations option, which creates a new +glossary with the label abbreviations and sets the command \glsxtrabbrvtype to this. If the acronym option +hasn’t also been used, then \acronymtype will be set to \glsxtrabbrvtype. This enables both \newacronym +and \newabbreviation to use the same glossary. +

    Make sure you have at least v1.42 of glossaries-extra if you use the acronym (or acronyms) package option +with the extension package to avoid a bug that interferes with the abbreviation style.

    +

    +

    -

    -

    Top

    3. Setting Up

    -

    In the preamble you need to indicate whether you want to use Option 1, Option 2 or -Option 3. It’s not possible to mix these options within a document, although some -combinations are possible with glossaries-extra. (For Options 4 and 5 see the bib2gls and -acronyms +

    This is equivalent to acronym=true and may be used in the document class option list. + + +

    +

    +

    abbreviations (glossaries-extra.sty)

    +

    This valueless option creates a new glossary type using: + + +

    +
    +\newglossary[glg-abr]{abbreviations}{gls-abr}{glo-abr}{\abbreviationsname} +
    +

    The label can be accessed with \glsxtrabbrvtype, which is analogous to \acronymtype. See glossaries-extra manuals.) +class="cmss-10">glossaries-extra +manual for further details. +

    -

    Top

    3.1 Option 1

    -

    The command -


    \makenoidxglossaries  \makenoidxglossaries

    -

    -must be placed in the preamble. This sets up the internal commands required to make -Option 1 work. If you omit \makenoidxglossaries none of the glossaries will be +

    acronymlists={value}

    +

    By default, only the \acronymtype glossary is considered to be a list of acronyms. If you have other lists of +acronyms, you can specify them as a comma-separated list in the value of acronymlists. For example, if you use +the acronym package option but you also want the main glossary to also contain a list of acronyms, you can +do: + + +

    +
    +\usepackage[acronym,acronymlists={main}]{glossaries} +
    +

    No check is performed to determine if the listed glossaries exist, so you can add glossaries you haven’t defined +yet. For example: + + +

    +
    +\usepackage[acronym,acronymlists={main,acronym2}] + 
      {glossaries} + 
    \newglossary[alg2]{acronym2}{acr2}{acn2}% + 
      {Statistical Acronyms} +
    +

    You can use +


    \DeclareAcronymList{list}

    +

    +instead of or in addition to the acronymlists option. This will add the glossaries given in ⟨list⟩ to the list of +glossaries that are identified as lists of acronyms. To replace the list of acronym lists with a new list +use: +


    \SetAcronymLists{list}

    +

    +

    You can determine if a glossary has been identified as being a list of acronyms using: +


    \glsIfListOfAcronyms{label}{true part}{false part}

    +

    +

    This option is incompatible with glossaries-extra’s abbreviation mechanism.
    +

    +

    +

    +

    shortcuts

    +

    This option provides shortcut commands for acronyms. See §13 Acronyms and Other Abbreviations for further +details. Alternatively you can use: +


    \DefineAcronymSynonyms

    +

    +

    The glossaries-extra package provides additional shortcuts.
    +

    +

    +

    +

    Top

    2.7.1 Deprecated Acronym Style Options

    +

    The package options listed in this section are now deprecated but are kept for backward-compatibility. Use displayed. -

    +class="cmtt-10">\setacronymstyle instead. See §13 Acronyms and Other Abbreviations for further details. + + +

    -

    Top

    3.2 Options 2 and 3

    -

    The command -


    \makeglossaries  \makeglossaries

    -

    -must be placed in the preamble in order to create the customised makeindex (.ist) or xindy -(.xdy) style file (for Options 2 or 3, respectively) and to ensure that glossary entries are -written to the appropriate output files. If you omit \makeglossaries none of the -glossary files will be created. -

    Note that some of the commands provided by the glossaries package must not be used -after \makeglossaries as they are required when creating the customised style file. If -you attempt to use those commands after \makeglossaries you will generate an -error. -

    Similarly, there are some commands that must not be used before \makeglossaries. +

    description

    +

    This option changes the definition of \newacronym to allow a description. This option may be replaced +by + + +

    +
    +\setacronymstyle{long-short-desc}
    -

    -

    You can suppress the creation of the customised xindy or makeindex style file -using -


    \noist  \noist

    -

    -That this command must not be used after \makeglossaries. -

    Note that if you have a custom .xdy file created when using glossaries version 2.07 or -below, you will need to use the compatible-2.07 package option with it.
    -

    - - -

    The default name for the customised style file is given by \jobname.ist (Option 2) or -\jobname.xdy (Option 3). This name may be changed using: -


    \setStyleFile  \setStyleFile{name}

    -

    -where ⟨name⟩ is the name of the style file without the extension. Note that this command must -not be used after \makeglossaries. -

    Each glossary entry is assigned a number list that lists all the locations in the document -where that entry was used. By default, the location refers to the page number but this may -be overridden using the counter package option. The default form of the location number -assumes a full stop compositor (e.g. 1.2), but if your location numbers use a different -compositor (e.g. 1-2) you need to set this using -


    \glsSetCompositor  \glsSetCompositor{symbol}

    -

    -For example: - - +

    or (with smallcaps) + +

    -
    -\glsSetCompositor{-} +
    +\setacronymstyle{long-sc-short-desc}
    -

    This command must not be used after \makeglossaries. -

    If you use Option 3, you can have a different compositor for page numbers starting with -an upper case alphabetical character using: -


    \glsSetAlphaCompositor  \glsSetAlphaCompositor{symbol}

    -

    -This command has no effect if you use Option 2. For example, if you want number lists -containing a mixture of A-1 and 2.3 style formats, then do: - - +

    or (with smaller) + +

    -
    -\glsSetCompositor{.}\glsSetAlphaCompositor{-} +
    +\setacronymstyle{long-sm-short-desc}
    -

    See §5 Number lists for further information about number lists. - - +

    or (with footnote) + +

    -

    -

    Top

    4. Defining Glossary Entries

    -

    All glossary entries must be defined before they are used, so it is better to define them in -the preamble to ensure this. In fact, some commands such as \longnewglossaryentry -may only be used in the preamble. See §4.8 Drawbacks With Defining Entries in -the Document Environment for a discussion of the problems with defining entries -within the document instead of in the preamble. (The glossaries-extra package has an -option that provides a restricted form of document definitions that avoids some of -the issues discussed in §4.8 +\setacronymstyle{footnote-desc} +

    +

    or (with footnote and smallcaps) + + +

    +
    +\setacronymstyle{footnote-sc-desc} +
    +

    or (with footnote and smaller) + + +

    +
    +\setacronymstyle{footnote-sm-desc} +
    +

    or (with dua) + + +

    +
    +\setacronymstyle{dua-desc} +
    +

    +

    +

    +

    smallcaps

    +

    This option changes the definition of \newacronym and the way that acronyms are displayed. This option may +be replaced by: + + +

    +
    +\setacronymstyle{long-sc-short} +
    +

    or (with description) + + +

    +
    +\setacronymstyle{long-sc-short-desc} +
    +

    or (with description and footnote) + + +

    +
    +\setacronymstyle{footnote-sc-desc} +
    +

    +

    +

    +

    smaller

    +

    This option changes the definition of \newacronym and the way that acronyms are displayed. +

    If you use this option, you will need to include the relsize package or otherwise define \textsmaller or +redefine \acronymfont.
    +

    +This option may be replaced by: + + +

    +
    +\setacronymstyle{long-sm-short} +
    +

    or (with description) + + +

    +
    +\setacronymstyle{long-sm-short-desc} +
    +

    or (with description and footnote) + + +

    +
    +\setacronymstyle{footnote-sm-desc} +
    +

    +

    +

    +

    footnote

    +

    This option changes the definition of \newacronym and the way that acronyms are displayed. This option may +be replaced by: + + +

    +
    +\setacronymstyle{footnote} +
    +

    or (with smallcaps) + + +

    +
    +\setacronymstyle{footnote-sc} +
    +

    or (with smaller) + + +

    +
    +\setacronymstyle{footnote-sm} +
    +

    or (with description) + + +

    +
    +\setacronymstyle{footnote-desc} +
    +

    or (with smallcaps and description) + + +

    +
    +\setacronymstyle{footnote-sc-desc} +
    +

    or (with smaller and description) + + +

    +
    +\setacronymstyle{footnote-sm-desc} +
    +

    +

    +

    +

    dua

    +

    This option changes the definition of \newacronym so that acronyms are always expanded. This option may be +replaced by: + + +

    +
    +\setacronymstyle{dua} +
    +

    or (with description) + + +

    +
    +\setacronymstyle{dua-desc} +
    +

    +

    +

    +

    Top

    2.8 Other Options

    +

    Other available options that don’t fit any of the above categories are described below. +

    +

    +

    accsupp (glossaries-extra.sty)

    +

    Load the glossaries-accsupp package. +

    +

    +

    prefix (glossaries-extra.sty)

    +

    Load the glossaries-prefix package. +

    +

    +

    nomissingglstext={boolean} (glossaries-extra.sty)

    +

    This option may be used to suppress the boilerplate text generated by \printglossary if the glossary file is +missing. +

    +

    +

    compatible-2.07={boolean}

    +

    Compatibility mode for old documents created using version 2.07 or below. + + +

    +

    +

    compatible-3.07={boolean}

    +

    Compatibility mode for old documents created using version 3.07 or below. +

    +

    +

    kernelglossredefs={value}

    +

    As a legacy from the precursor glossary package, the standard glossary commands provided by the +LATEX kernel (\makeglossary and \glossary) are redefined in terms of the glossaries package’s commands. +However, they were never documented in this user manual, and the conversion guide (“Upgrading from the +glossary package to the glossaries package”) explicitly discourages their use. +

    The use of those kernel commands (instead of the appropriate commands documented in this user guide) are +deprecated, and you will now get a warning if you try using them. +

    In the event that you require the original form of these kernel commands, for example, if you need to use the +glossaries package with another class or package that also performs glossary-style indexing, then you can restore +these commands to their previous definition (that is, their definitions prior to loading the glossaries package) +with the package option kernelglossredefs=false. You may also need to use the nomain option in the event of file +extension conflicts. (In which case, you must provide a new default glossary for use with the glossaries +package.) +

    This option may take one of three values: true (redefine with warnings, default), false (restore previous +definitions) or nowarn (redefine without warnings, not recommended). +

    The only glossary-related commands provided by the LATEX kernel are \makeglossary and \glossary. +Other packages or classes may provide additional glossary-related commands or environments that conflict with +glossaries (such as \printglossary and theglossary). These non-kernel commands aren’t affected by this +package option, and you will have to find some way to resolve the conflict if you require both glossary +mechanisms. (The glossaries package will override the existing definitions of \printglossary and +theglossary.) +

    In general, if possible, it’s best to stick with just one package that provides a glossary mechanism. (The +glossaries package does check for the doc package and patches \PrintChanges.) +

    +

    +

    Top

    2.9 Setting Options After the Package is Loaded

    +

    Some of the options described above may also be set after the glossaries package has been loaded +using +


    \setupglossaries{key-val list}

    +

    +The following package options can’t be used in \setupglossaries: xindy, xindygloss, xindynoglsnumbers, +makeindex, nolong, nosuper, nolist, notree, nostyles, nomain, compatible-2.07, translate, notranslate, +acronym. These options have to be set while the package is loading, except for the xindy sub-options +which can be set using commands like \GlsSetXdyLanguage (see §11 Xindy (Option 3) for further +details). + + +

    If you need to use this command, use it as soon as possible after loading glossaries otherwise you might end +up using it too late for the change to take effect. For example, if you try changing the acronym styles (such as +smallcaps) after you have started defining your acronyms, you are likely to get unexpected results. If you try +changing the sort option after you have started to define entries, you may get unexpected results. +
    +

    + + +

    +

    +

    Top

    3. Setting Up

    +

    In the preamble you need to indicate whether you want to use Option 1, Option 2 or Option 3. It’s not +possible to mix these options within a document, although some combinations are possible with glossaries-extra. +(For Options 4 and 5 see the bib2gls and glossaries-extra manuals.) +

    +

    Top

    3.1 Option 1

    +

    The command +


    \makenoidxglossaries

    +

    +must be placed in the preamble. This sets up the internal commands required to make Option 1 work. If you +omit \makenoidxglossaries none of the glossaries will be displayed. +

    +

    +

    Top

    3.2 Options 2 and 3

    +

    The command +


    \makeglossaries

    +

    +must be placed in the preamble in order to create the customised makeindex (ist) or xindy (xdy) style file (for +Options 2 or 3, respectively) and to ensure that glossary entries are written to the appropriate output files. If +you omit \makeglossaries none of the glossary files will be created. +

    If you are using glossaries-extra, \makeglossaries has an optional argument that allows you to +have a hybrid of Options 1 or 2 or Options 1 or 3. See glossaries-extra manual for further details. +
    +

    +

    Note that some of the commands provided by the glossaries package must not be used after +\makeglossaries as they are required when creating the customised style file. If you attempt to use those +commands after \makeglossaries you will generate an error. Similarly, there are some commands that must +not be used before \makeglossaries. +

    You can suppress the creation of the customised xindy or makeindex style file using +


    \noist

    +

    +That this command must not be used after \makeglossaries. +

    Note that if you have a custom xdy file created when using glossaries version 2.07 or below, you will need to +use the compatible-2.07 package option with it.
    +

    +

    The default name for the customised style file is given by \jobnameist (Option 2) or \jobnamexdy +(Option 3). This name may be changed using: +


    \setStyleFile{name}

    + + +

    +where ⟨name⟩ is the name of the style file without the extension. Note that this command must not be used after +\makeglossaries. +

    Each glossary entry is assigned a number list that lists all the locations in the document where that entry +was used. By default, the location refers to the page number but this may be overridden using the +counter package option. The default form of the location number assumes a full stop compositor +(e.g. 1.2), but if your location numbers use a different compositor (e.g. 1-2) you need to set this +using +


    \glsSetCompositor{symbol}

    +

    +For example: + + +

    +
    +\glsSetCompositor{-} +
    +

    This command must not be used after \makeglossaries. +

    If you use Option 3, you can have a different compositor for page numbers starting with an upper case +alphabetical character using: +


    \glsSetAlphaCompositor{symbol}

    +

    +This command has no effect if you use Option 2. For example, if you want number lists containing a mixture of +A-1 and 2.3 style formats, then do: + + +

    +
    +\glsSetCompositor{.}\glsSetAlphaCompositor{-} +
    +

    See §5 Number lists for further information about number lists. + + +

    +

    +

    Top

    4. Defining Glossary Entries

    +

    All glossary entries must be defined before they are used, so it is better to define them in the +preamble to ensure this. In fact, some commands such as \longnewglossaryentry may only be used +in the preamble. See §4.8 Drawbacks With Defining Entries in the Document Environment for a +discussion of the problems with defining entries within the document instead of in the preamble. +(The glossaries-extra package has an option that provides a restricted form of document definitions +that avoids some of the issues discussed in §4.8 Drawbacks With Defining Entries in the Document Environment.) -

    Option 1 enforces the preamble-only restriction on \newglossaryentry. Option 4 -requires that definitions are provided in .bib format. Option 5 requires either -preamble-only definitions or the use of the glossaries-extra package option docdef=restricted. -
    -

    -

    Only those entries that are indexed in the document (using any of the commands -described in §6 Links to Glossary Entries, §7 Adding an Entry to the Glossary Without -Generating Text or §8 Cross-Referencing Entries) will appear in the glossary. See §10 -Displaying a glossary to find out how to display the glossary. -

    New glossary entries are defined using the command: -


    \newglossaryentry  . Option 4 requires that definitions +are provided in bib format. Option 5 requires either preamble-only definitions or the use of the glossaries-extra +package option docdef=restricted.
    +

    +

    Only those entries that are indexed in the document (using any of the commands described in §6 Links to +Glossary Entries, §7 Adding an Entry to the Glossary Without Generating Text or §8 Cross-Referencing +Entries) will appear in the glossary. See §10 Displaying a glossary to find out how to display the +glossary. +

    New glossary entries are defined using the command: +


    \newglossaryentry{label}{key=value list}

    -

    +

    This is a short command, so values in ⟨key-val list⟩ can’t contain any paragraph breaks. Take -care to enclose values containing any commas (key-val list⟩ can’t contain any paragraph breaks. Take care to enclose +values containing any commas (,) or equal signs (=) with braces to hide them -from the key=value list parser. Be careful to ensure that no spurious spaces are included at -the start and end of the braces. -

    If you have a long description that needs to span multiple paragraphs, use -


    \longnewglossaryentry  =) with braces to hide them from the key=value list +parser. +

    If you have a long description that needs to span multiple paragraphs, use +


    \longnewglossaryentry{label}{key=value list}{long -descriptionlong description}

    -

    -instead. Note that this command may only be used in the preamble. Be careful of unwanted -spaces. \longnewglossaryentry will remove trailing spaces in the description (via \unskip) -but won’t remove leading spaces (otherwise it would interfere with commands like -\Glsentrydesc). This command also appends \nopostdesc to the end of the description, -which suppresses the post-description hook. The glossaries-extra package provides a -starred version of \longnewglossaryentry that doesn’t append either \unskip or +

    +instead. Note that this command may only be used in the preamble. Be careful of unwanted spaces. \longnewglossaryentry will remove trailing spaces in the description (via \unskip) but won’t remove leading +spaces. This command also appends \nopostdesc to the end of the description, which suppresses the +post-description hook. The glossaries-extra package provides a starred version of \longnewglossaryentry that +doesn’t append either \unskip or \nopostdesc. -

    There are also commands that will only define the entry if it hasn’t already been -defined: -


    \provideglossaryentry 

    There are also commands that will only define the entry if it hasn’t already been defined: +


    \provideglossaryentry{label}{key=value list} -

    -

    +class="cmtt-10">}


    +

    and -


    \longprovideglossaryentry 


    \longprovideglossaryentry{label}{key=value list} - - -{}{long description}

    -

    +

    (These are both preamble-only commands.) -

    For all the above commands, the first argument, ⟨label⟩, must be a unique label with which -to identify this entry. This can’t contain any non-expandable commands -or active characters. The reason for this restriction is that the label is used to -construct internal commands that store the associated information (similarly to -commands like

    For all the above commands, the first argument, ⟨label⟩, must be a unique label with which to identify this +entry. This can’t contain any non-expandable commands or active characters. The reason for this restriction +is that the label is used to construct internal commands that store the associated information +(similarly to commands like \label) and therefore must be able to expand to a valid control sequence name. -

    Note that although an

    Note that although an extended Latin character or other or other non-Latin character, such as é -or ß, looks like a plain character in your .tex file, it’s actually a macro (an active character) -and therefore can’t be used in the label. (This applies to LATEX rather than XeLaTeX.) -Also be careful of , such as é or ß, looks + + +like a plain character in your .tex file, it’s actually a macro (an active character) and therefore +can’t be used in the label. (This applies to LATEX rather than XeLaTeX.) Also be careful of +babel’s options that change certain punctuation characters (such as ’s options that change certain punctuation characters (such as : or -) -to active characters.
    -

    -

    The second argument, ⟨-) to active characters. +

    +

    +

    The second argument, ⟨key=value list⟩, is a ⟨key⟩=⟨value⟩ list that supplies the relevant -information about this entry. There are two required fields: description and either name or -parent. The description is set in the third argument of \longnewglossaryentry and -\longprovideglossaryentry. With the other commands it’s set via the description key. As is -typical with ⟨value⟩ list that supplies the relevant information about this +entry. There are two required fields: description and either name or parent. The description is set in the third +argument of \longnewglossaryentry and \longprovideglossaryentry. With the other commands it’s set via +the description key. As is typical with ⟨key⟩=⟨value⟩ lists, values that contain a comma or equal sign must be enclosed in -braces. Available fields are listed below. Additional fields are provided by the supplementary -packages value⟩ lists, values that contain a comma or equal sign +must be enclosed in braces. Available fields are listed below. Additional fields are provided by the +supplementary packages glossaries-prefix (§17 (§17 Prefixes or Determiners) and glossaries-accsupp (§18 -Accessibility Support) and also by (§18 Accessibility +Support) and also by glossaries-extra. You can also define your own custom keys -(see §4.3 Additional Keys). +class="cmss-10">glossaries-extra. You can also define your own custom keys (see §4.3 Additional +Keys).

    name
    The name of the entry (as it will appear in the glossary). If this key is omitted - and the parent key is supplied, this value will be the same as the parent’s name. -

    If the name key contains any commands, you must also use the sort key (described - below) if you intend sorting the entries alphabetically, otherwise the entries can’t be - sorted correctly.
    -

    +class="cmtt-10">name

    The name of the entry (as it will appear in the glossary). If this key is omitted and the parent + key is supplied, this value will be the same as the parent’s name. +

    If the name key contains any commands, you must also use the sort key (described below) if + you intend sorting the entries alphabetically, otherwise the entries can’t be sorted correctly. +
    +

    description
    A brief description of this term (to appear in the glossary). Within this value, - you can use -


    \nopostdesc  description
    A brief description of this term (to appear in the glossary). Within this value, you can + use: +


    \nopostdesc

    -

    - to suppress the description terminator for this entry. For example, if this - entry is a parent entry that doesn’t require a description, you can do - description={\nopostdesc}. If you want a paragraph break in the description - use -


    \glspar 

    + to suppress the description terminator for this entry. For example, if this entry is a parent entry that + doesn’t require a description, you can do description={\nopostdesc}. If you want a paragraph break in + the description use: +


    \glspar

    - - -

    +

    or, better, use \longnewglossaryentry. However, note that not all glossary styles - support multi-line descriptions. If you are using one of the tabular-like glossary styles - that permit multi-line descriptions, use \longnewglossaryentry. However, note that not all glossary styles support multi-line + descriptions. If you are using one of the tabular-like glossary styles that permit multi-line descriptions, use + \newline not \\ if you want to force a line - break. + id="dx1-112023"> not \\ if you want to force a line break. +

    With glossaries-extra, use \glsxtrnopostpunc instead of \nopostdesc to suppress the post-description + punctuation.
    +

    parent
    The label of the parent entry. Note that the parent entry must be defined before its - sub-entries. See §4.5 parent
    The label of the parent entry. Note that the parent entry must be defined before its sub-entries. See §4.5 + Sub-Entries for further details. + +
    descriptionplural
    The plural form of the description, if required. If omitted, the value is set to - the same as the description key. +class="cmtt-10">descriptionplural
    The plural form of the description, if required. If omitted, the value is set to the same as + the description key.
    text
    text
    How this entry will appear in the document text when using \gls (or one of its - upper case variants). If this field is omitted, the value of the name key is - used. + id="dx1-112029"> (or one of its upper case variants). If + this field is omitted, the value of the name key is used.
    first
    first
    How the entry will appear in the document text on first use with \gls (or one of its - upper case variants). If this field is omitted, the value of the text key is used. Note that - if you use (or one of its upper case + variants). If this field is omitted, the value of the text key is used. Note that if you use \glspl, , + \Glspl, , \GLSpl, , \glsdisp before using before using \gls, the firstplural value - won’t be used with , the firstplural value won’t be used with + \gls. + id="dx1-112040">.
    plural
    plural
    How the entry will appear in the document text when using \glspl (or one - of its upper case variants). If this field is omitted, the value is obtained by - appending (or one of its upper case variants). + If this field is omitted, the value is obtained by appending \glspluralsuffix to the value of the text field. The default value of - to the value of the text + field. The default value of \glspluralsuffix is the letter “s”. + id="dx1-112045"> is the letter “s”.
    firstplural
    firstplural
    How the entry will appear in the document text on first use with \glspl (or one - of its upper case variants). If this field is omitted, the value is obtained from the plural - key, if the first key is omitted, or by appending (or one of its upper case + variants). If this field is omitted, the value is obtained from the plural key, if the first key is omitted, or + by appending \glspluralsuffix to the value of - the first field, if the first field is present. Note that if you use to the value of the first field, if the first field is present. Note that if + you use \gls, , \Gls, - , \GLS, , \glsdisp before using \glspl, the firstplural value won’t be used with + id="dx1-112056">, the firstplural value won’t be used with \glspl. -

    Note: prior to version 1.13, the default value of firstplural was always taken by - appending “s” to the first key, which meant that you had to specify both plural and + id="dx1-112058">. +

    Note: prior to version 1.13, the default value of firstplural was always taken by appending “s” to the firstplural, even if you hadn’t used the first key. +class="cmtt-10">first key, which meant that you had to specify both plural and firstplural, even if you hadn’t used + the first key.

    symbol
    This field is provided to allow the user to specify an associated symbol. If - omitted, the value is set to \relax. Note that not all glossary styles display the - symbol. +class="cmtt-10">symbol
    This field is provided to allow the user to specify an associated symbol. If omitted, the value is set to + \relax. Note that not all glossary styles display the symbol.
    symbolplural
    symbolplural
    This is the plural form of the symbol (as passed to \glsdisplay and - - - and \glsdisplayfirst by by + \glspl, , \Glspl and and \GLSpl). If omitted, the value is set to the - same as the symbol key. + id="dx1-112070">). If omitted, the value is set to the same as the symbol key.
    sort
    sort
    This value indicates how this entry should be sorted. If omitted, the value is given by the name field unless one of the package options sort=def and sort=use have been - used. In general, it’s best to use the sort key if the name contains commands - (e.g. \ensuremath{\alpha}). You can also override the sort key by redefining - name field unless one of the package options sort=def and sort=use have been used. In general, + it’s best to use the sort key if the name contains commands (e.g. \ensuremath{\alpha}). + You can also override the sort key by redefining \glsprestandardsort (see §2.4 Sorting Options). -

    (see §2.5 Sorting + Options). +

    The sort key shouldn’t be used with bib2gls. It has a system of fallbacks that allow different types of + entries to obtain the sort value from the most relevant field. See the bib2gls manual for further details + and see also bib2gls gallery: sorting.
    +

    + + +

    Option 1 by default strips the standard LATEX accents (that is, accents generated by - core LATEX accents (that is, accents generated by core + LATEX commands) from the name key when it sets the sort key. So with - name key when it sets the sort key. So with Option 1: - - + +

    -
    +
    \newglossaryentry{elite}{%  
      name={{\'e}lite},  
      description={select group of people}  
    }
    -

    This is equivalent to: - - +

    This is equivalent to: + +

    -
    +
    \newglossaryentry{elite}{%  
      name={{\'e}lite},  
      description={select group of people},  
      sort={elite}  
    }
    -

    Unless you use the package option sanitizesort=true, in which case it’s equivalent - to: - - +

    Unless you use the package option sanitizesort=true, in which case it’s equivalent to: + +

    -
    +
    \newglossaryentry{elite}{%  
      name={{\'e}lite},  
      description={select group of people},  
      sort={\'elite}  
    }
    -

    This will place the entry before the “A” letter group since the sort value starts with a - symbol. -

    Similarly if you use the

    This will place the entry before the “A” letter group since the sort value starts with a symbol. +

    Similarly if you use the inputenc package:

    + id="dx1-112086"> package:

    - \newglossaryentry{elite}{% + \newglossaryentry{elite}{%
      name={{é}lite}, +class="cmtt-10"> name={{é}lite},
      description={select description={select group of people} -
    } +class="cmtt-10"> people} +
    }
    This is equivalent to
    - \newglossaryentry{elite}{% + \newglossaryentry{elite}{%
      name={{é}lite}, +class="cmtt-10"> name=i{{é}lite},
      description={select description={select group of people}, +class="cmtt-10"> people},
      sort=elite -
    } +
    }
    Unless you use the package option sanitizesort=true, in which case it’s equivalent to: -
    +class="cmss-10">sanitizesort=true, in which case it’s equivalent to:
    - \newglossaryentry{elite}{% + \newglossaryentry{elite}{%
      name={{é}lite}, +class="cmtt-10"> name={{é}lite},
      description={select description={select group of people}, +class="cmtt-10"> people},
      sort=élite -
    } +
    }
    Again, this will place the entry before the “A” group. - - -

    With Options 

    With Options 2 and 3, the default value of sort will either be set to the name - key (if sanitizesort=true) or it will set it to the expansion of the name key (if - sanitizesort=false). -

    Take care with sort will either be set to the name key (if sanitizesort=true) or + it will set it to the expansion of the name key (if sanitizesort=false). + + +

    Take care with xindy ( (Option 3): if you have entries with the same sort value they will - be treated as the same entry. If you use sort value they will be treated as + the same entry. If you use xindy and aren’t using the and aren’t using the def or use sort - methods, always use the sort key for entries where the name just consists of a control - sequence (for example use sort methods, always use + the sort key for entries where the name just consists of a control sequence (for example + name={\alpha}). -

    Take care if you use

    Take care if you use Option 1 and the name contains fragile commands. You will either - need to explicitly set the sort key or use the sanitizesort=true package option (unless you - use the name contains fragile commands. You will either need to explicitly + set the sort key or use the sanitizesort=true package option (unless you use the def or use sort methods).

    -

    +class="cmtt-10">use sort methods). +

    +

    type
    This specifies the label of the glossary in which this entry belongs. If omitted, the - default glossary is assumed unless type
    This specifies the label of the glossary in which this entry belongs. If omitted, the default glossary is + assumed unless \newacronym is used (see §13 Acronyms and Other - Abbreviations). + id="dx1-112101"> is used (see §13 Acronyms and Other Abbreviations).
    user1user1, …, user6
    Six keys provided for any additional information the user may want to - specify. (For example, an associated dimension or an alternative plural or some other - grammatical construct.) Alternatively, you can add new keys using user6
    Six keys provided for any additional information the user may want to specify. (For + example, an associated dimension or an alternative plural or some other grammatical construct.) + Alternatively, you can add new keys using \glsaddkey or - or \glsaddstoragekey (see §4.3 Additional Keys). + id="dx1-112109"> (see §4.3 Additional + Keys).
    nonumberlist
    nonumberlist
    A boolean key. If the value is missing or is true, this will suppress the number list just for this entry. Conversely, if you have used the package option just for this entry. Conversely, if you have used the package option nonumberlist, you + id="dx1-112112">, you can activate the number list just for this entry with nonumberlist=false. (See §5 just for this entry with nonumberlist=false. (See §5 Number lists.)
    see
    see
    Cross-reference another entry. Using the see key will automatically add this entry to the - glossary, but will not automatically add the cross-referenced entry. The referenced entry - should be supplied as the value to this key. If you want to override the “see” tag, - you can supply the new tag in square brackets before the label. For example - see key will automatically add this entry to the glossary, but will + not automatically add the cross-referenced entry. The referenced entry should be supplied as the value to + this key. If you want to override the “see” tag, you can supply the new tag in square brackets before the + label. For example see=[see also]{anotherlabel}. Note that if you have suppressed the number - list, the cross-referencing information won’t appear in the glossary, as it - forms part of the number list. You can override this for individual glossary - entries using nonumberlist=false (see above). Alternatively, you can use the -  also]{anotherlabel}. Note that if you have suppressed the number list, + the cross-referencing information won’t appear in the glossary, as it forms part of the number list. You can + override this for individual glossary entries using nonumberlist=false (see above). Alternatively, you + can use the seeautonumberlist package option. For further details, see §8 package option. For further details, see §8 Cross-Referencing Entries. -

    This key essentially provides a convenient shortcut that performs

    +

    This key essentially provides a convenient shortcut that performs

    \glssee[xr-label list}
    - -
    after the entry has been defined. -

    For Options 

    For Options 2 and 3, \makeglossaries must be used before any occurrence of - must be used before any occurrence of \newglossaryentry that contains the see key. This key should not be used with entries - defined in the that + contains the see key. This key should not be used with entries defined in the document environment.
    -

    - Since it’s useful to suppress the indexing while working on a draft document, - consider using the seenoindex package option to warn or ignore the see key while + id="dx1-112124"> environment. +

    + + +

    + Since it’s useful to suppress the indexing while working on a draft document, consider using the \makeglossaries is commented out. -

    If you use the see key, you may want to consider using the seenoindex package option to warn or ignore the see key while \makeglossaries is commented + out. +

    If you use the see key, you may want to consider using the glossaries-extra package which - additionally provides a glossaries-extra package which additionally + provides a seealso and alias key. If you want to avoid the automatic - indexing triggered by the see key, consider using alias key. If you want to avoid the automatic indexing triggered by the see key, + consider using Option 4. -

    +

    +seealso
    This key is only available with glossaries-extra and is similar to see but it doesn’t allow for the + optional tag. The glossaries-extra package provides \seealsoname and seealso={list} is essentially like + see=[\seealsoname]list⟩ (Options 3 and 4 may treat these differently). +
    +alias
    This key is only available with glossaries-extra and is another form of cross-referencing. An entry can be + aliased to another entry with alias={label}. This behaves like see={label} but also alters the + behaviour of commands like \gls so that they index the entry given by ⟨label⟩ instead of the original entry. + More variations with the key are available with bib2gls. +
    +category
    This key is only available with glossaries-extra and is used to assign a category to the entry. The value + should be a label that can be used to identify the category. See glossaries-extra manual for further + details.
    -

    The following keys are reserved for

    The following keys are reserved for \newacronym (see §13 Acronyms and Other -Abbreviations): long, longplural, short and shortplural. -

    Avoid using any of the (see §13 Acronyms and Other Abbreviations) +and also for \newabbreviation (see the glossaries-extra manual): long, longplural, short and +shortplural. +

    There are also special internal field names used by bib2gls. See the bib2gls manual for further details. +
    +

    +

    The supplementary packages glossaries-prefix (§17 Prefixes or Determiners) and glossaries-accsupp (§18 +Accessibility Support) provide additional keys. +

    Avoid using any of the \gls-like or \glstext-like commands within the text, first, short -or long keys (or their plural equivalent) or any other key that you plan to access through -those commands. (For example, the symbol key if you intend to use \glssymbol.) Otherwise -you end up with nested links, which can cause complications and they won’t work with the -case-changing commands. You can use them within the value of keys that won’t be accessed -through those commands. For example, the description key if you don’t use \glsdesc. -Additionally, they’ll confuse the entry formatting commands, such as text, first, short or long keys +(or their plural equivalent) or any other key that you plan to access through those commands. (For example, the +symbol key if you intend to use \glssymbol.) Otherwise you end up with nested links, which can cause +complications and they won’t work with the case-changing commands. You can use them within the value of +keys that won’t be accessed through those commands. For example, the description key if you don’t +use \glsdesc. Additionally, they’ll confuse the entry formatting commands, such as \glslabel.
    -

    -

    Note that if the name starts with

    +

    Note that if the name starts with non-Latin character, you must group the -character, otherwise it will cause a problem for commands like , you must group the character, otherwise it will cause +a problem for commands like \Gls and and \Glspl. For -example: - - + id="dx1-112153">. For example: + +

    -
    +
    \newglossaryentry{elite}{name={{\'e}lite},  
    description={select group or class}}
    -

    Note that the same applies if you are using the

    Note that the same applies if you are using the inputenc package:

    + id="dx1-112154"> package:

    -\newglossaryentry{elite}{name={{é}lite}, +\newglossaryentry{elite}{name={{é}lite},
    description={selectdescription={select group or class}} +class="cmtt-10"> class}}
    (This doesn’t apply for XeLaTeX documents using the fontspec package. For further details, -see the “UTF-8” section in the package. For further details, see the “UTF-8” +section in the mfirstuc user manual.) -

    Note that in both of the above examples, you will also need to supply the sort key if you -are using user manual.) +

    Note that in both of the above examples, you will also need to supply the sort key if you are +using Option 2 whereas xindy ( (Option 3) is usually able to sort non-Latin characters -correctly. s correctly. +Option 1 discards accents from standard LATEX extended Latin characters unless -you use the sanitizesort=true. + id="dx1-112160">s unless you use the +sanitizesort=true.

    -

    Top

    4.1 Plurals

    -

    You may have noticed from above that you can specify the plural form when you define a -term. If you omit this, the plural will be obtained by appending -


    \glspluralsuffix 

    You may have noticed from above that you can specify the plural form when you define a term. If you omit this, +the plural will be obtained by appending +


    \glspluralsuffix

    -

    +

    to the singular form. This command defaults to the letter “s”. For example: - - + +

    -
    +
    \newglossaryentry{cow}{name=cow,description={a fully grown  
    female of any bovine animal}}
    -

    defines a new entry whose singular form is “cow” and plural form is “cows”. However, if you -are writing in archaic English, you may want to use “kine” as the plural form, in which case -you would have to do: - - +

    defines a new entry whose singular form is “cow” and plural form is “cows”. However, if you are writing in +archaic English, you may want to use “kine” as the plural form, in which case you would have to +do: + +

    -
    +
    \newglossaryentry{cow}{name=cow,plural=kine,  
    description={a fully grown female of any bovine animal}}
    -

    -

    If you are writing in a language that supports multiple plurals (for a given term) then use -the plural key for one of them and one of the user keys to specify the other plural form. For -example: - - +

    +

    If you are writing in a language that supports multiple plurals (for a given term) then use the plural key for +one of them and one of the user keys to specify the other plural form. For example: + +

    -
    +
    \newglossaryentry{cow}{%  
      name=cow,%  
      description={a fully grown female of any bovine animal  
                   (plural cows, archaic plural kine)},%  
      user1={kine}}
    -

    You can then use

    You can then use \glspl{cow} to produce “cows” and \glsuseri{cow} to produce “kine”. -You can, of course, define an easy to remember synonym. For example: - - +class="cmtt-10">\glsuseri{cow} to produce “kine”. You can, of course, +define an easy to remember synonym. For example: + +

    -
    +
    \let\glsaltpl\glsuseri
    -

    Then you don’t have to remember which key you used to store the second plural. -Alternatively, you can define your own keys using

    Then you don’t have to remember which key you used to store the second plural. Alternatively, you can define +your own keys using \glsaddkey, described in §4.3 Additional -Keys. -

    If you are using a language that usually forms plurals by appending a different letter, or -sequence of letters, you can redefine \glspluralsuffix as required. However, this must be -done before the entries are defined. For languages that don’t form plurals by simply -appending a suffix, all the plural forms must be specified using the plural key (and the -firstplural key where necessary). -

    -

    -

    , described in §4.3 Additional Keys. +

    If you are using a language that usually forms plurals by appending a different letter, or sequence of letters, +you can redefine \glspluralsuffix as required. However, this must be done before the entries are defined. For +languages that don’t form plurals by simply appending a suffix, all the plural forms must be specified using the +plural key (and the firstplural key where necessary). +

    +

    +

    Top

    4.2 Other Grammatical Constructs

    -

    You can use the six user keys to provide alternatives, such as participles. For example: - - +

    You can use the six user keys to provide alternatives, such as participles. For example: + +

    -
    +
    \let\glsing\glsuseri  
    \let\glsd\glsuserii  
    \newcommand*{\ingkey}{user1} @@ -10641,73 +12997,66 @@ href="#top">Top

      }%  
    }

    -

    With the above definitions, I can now define terms like this: - - +

    With the above definitions, I can now define terms like this: + +

    -
    +
    \newword{play}{to take part in activities for enjoyment}  
    \newword[\edkey={ran},\ingkey={running}]{run}{to move fast using  
    the legs}
    -

    and use them in the text: - - +

    and use them in the text: + +

    -
    +
    Peter is \glsing{play} in the park today.  
    Jane \glsd{play} in the park yesterday.  
    Peter and Jane \glsd{run} in the park last week.
    -

    -

    Alternatively, you can define your own keys using

    +

    Alternatively, you can define your own keys using \glsaddkey, described below in §4.3 -Additional Keys. -

    + id="dx1-114001">, described below in §4.3 Additional +Keys. +

    -

    Top

    4.3 Additional Keys

    -

    You can now also define your own custom keys using the commands described in this section. -There are two types of keys: those for use within the document and those to store information -used behind the scenes by other commands. -

    For example, if you want to add a key that indicates the associated unit for a term, you -might want to reference this unit in your document. In this case use \glsaddkey described in -§4.3.1 Document Keys. If, on the other hand, you want to add a key to indicate to a -glossary style or acronym style that this entry should be formatted differently to -other entries, then you can use

    You can now also define your own custom keys using the commands described in this section. There are two +types of keys: those for use within the document and those to store information used behind the scenes by other +commands. +

    For example, if you want to add a key that indicates the associated unit for a term, you might want to +reference this unit in your document. In this case use \glsaddkey described in §4.3.1 Document Keys. If, on the +other hand, you want to add a key to indicate to a glossary style or acronym style that this entry should be +formatted differently to other entries, then you can use \glsaddstoragekey described in §4.3.2 §4.3.2 Storage Keys. -

    In both cases, a new command ⟨no link cs⟩ will be defined that can be used to access the -value of this key (analogous to commands such as \glsentrytext). This can be used in an -expandable context (provided any fragile commands stored in the key have been protected). -The new keys must be added using \glsaddkey or \glsaddstoragekey before glossary -entries are defined. -

    -

    -

    In both cases, a new command ⟨no link cs⟩ will be defined that can be used to access the value of this key +(analogous to commands such as \glsentrytext). This can be used in an expandable context (provided any +fragile commands stored in the key have been protected). The new keys must be added using \glsaddkey or +\glsaddstoragekey before glossary entries are defined. +

    +

    +

    Top

    4.3.1 Document Keys

    -

    A custom key that can be used in the document is defined using: -


    \glsaddkey 

    A custom key that can be used in the document is defined using: +


    \glsaddkey{key}{}{no link cs}{no link ucfirst cs} -{}{link cs}{link ucfirst cslink ucfirst +cs}{link allcaps cs}

    -

    +

    where:

    key
    is the new key to use in is the new key to use in \newglossaryentry (or similar commands such as + id="dx1-116002"> (or similar commands such as \longnewglossaryentry); - - + id="dx1-116003">); + +
    default value
    is the default value to use if this key isn’t used in an entry definition - (this may reference the current entry label via \glslabel, but you will have to - switch on expansion via the starred version of \glsaddkey and protect fragile - commands); +class="description">is the default value to use if this key isn’t used in an entry definition (this may reference + the current entry label via \glslabel, but you will have to switch on expansion via the starred + version of \glsaddkey and protect fragile commands);
    no link cs
    is the control sequence to use analogous to commands like \glsentrytext; + id="dx1-116004">;
    no link ucfirst cs
    is the control sequence to use analogous to commands like - is the control sequence to use analogous to commands like \Glsentrytext; + id="dx1-116005">;
    link cs
    is the control sequence to use analogous to commands like \glstext; + id="dx1-116006">;
    link ucfirst cs
    is the control sequence to use analogous to commands like \Glstext; + id="dx1-116007">;
    link allcaps cs
    is the control sequence to use analogous to commands like \GLStext.
    -

    The starred version of \glsaddkey switches on expansion for this key. The unstarred version -doesn’t override the current expansion setting. + id="dx1-116008">. +

    The starred version of \glsaddkey switches on expansion for this key. The unstarred version doesn’t override the +current expansion setting. -

    +

    Example 3 (Defining Custom Keys) -

    Suppose I want to define two new keys, +

    Suppose I want to define two new keys, ed and ing, that default to the entry text followed -by “ed” and “ing”, respectively. The default value will need expanding in both cases, so I -need to use the starred form: - - +class="cmtt-10">ing, that default to the entry text followed by “ed” and +“ing”, respectively. The default value will need expanding in both cases, so I need to use the starred +form: + +

    -
    +
     % Define "ed" key:  
     \glsaddkey*  
      {ed}% key @@ -10815,11 +13162,11 @@ need to use the starred form:  
      {\Glsing}% command analogous to \Glstext  
      {\GLSing}% command analogous to \GLStext
    -

    Now I can define some entries: - - +

    Now I can define some entries: + +

    -
    +
     % No need to override defaults for this entry:  
     \newglossaryentry{jump}{name={jump},description={}}  
     % Need to override defaults on these entries: @@ -10832,91 +13179,83 @@ need to use the starred form:  
       ing={waddling},%  
       description={}}
    -

    -

    These entries can later be used in the document: - - +

    +

    These entries can later be used in the document: + +

    -
    +
    The dog \glsed{jump} over the duck.  
    The duck was \glsing{waddle} round the dog.  
    The dog \glsed{run} away from the duck.
    -

    For a complete document, see the sample file

    For a complete document, see the sample file sample-newkeys.tex.

    -

    -

    ____________________________

    -

    +

    +

    ____________________________

    +

    -

    Top

    4.3.2 Storage Keys

    -

    A custom key that can be used for simply storing information is defined using: -


    \glsaddstoragekey 

    A custom key that can be used for simply storing information is defined using: +


    \glsaddstoragekey{key}{default value}{no link cs} -

    -

    +class="cmtt-10">}


    +

    where the arguments are as the first three arguments of \glsaddkey, described above in -§4.3.1 Document Keys. -

    This is essentially the same as \glsaddkey except that it doesn’t define the additional -commands. You can access or update the value of your new field using the commands -described in §16.3 Fetching and Updating the Value of a Field. +class="cmtt-10">\glsaddkey, described above in §4.3.1 Document +Keys. +

    This is essentially the same as \glsaddkey except that it doesn’t define the additional commands. You can +access or update the value of your new field using the commands described in §16.3 Fetching and Updating the +Value of a Field. -

    +

    Example 4 (Defining Custom Storage Key (Acronyms and -Initialisms)) -

    Suppose I want to define acronyms and other forms of abbreviations, such as initialisms, -but I want them all in the same glossary and I want the acronyms on first use to be displayed -with the short form followed by the long form in parentheses, but the opposite way round for -other forms of abbreviations. (The glossaries-extra package provides a simpler way of achieving -this.) -

    Here I can define a new key that determines whether the term is actually an acronym -rather than some other form of abbreviation. I’m going to call this key  (Defining Custom Storage Key (Acronyms and Initialisms)) +

    Suppose I want to define acronyms and other forms of abbreviations, such as initialisms, but I want them all +in the same glossary and I want the acronyms on first use to be displayed with the short form followed by the +long form in parentheses, but the opposite way round for other forms of abbreviations. (The glossaries-extra +package provides a simpler way of achieving this.) +

    Here I can define a new key that determines whether the term is actually an acronym rather +than some other form of abbreviation. I’m going to call this key abbrtype (since type -already exists): - - +class="cmtt-10">type already +exists): + +

    -
    +
    \glsaddstoragekey  
     {abbrtype}% key/field name  
     {word}% default value if not explicitly set  
     {\abbrtype}% custom command to access the value if required
    -

    -

    Now I can define a style that looks up the value of this new key to determine how to -display the full form: - - +

    +

    Now I can define a style that looks up the value of this new key to determine how to display the full +form: + +

    -
    +
    \newacronymstyle  
     {mystyle}% style name  
     {% Use the generic display @@ -10963,8 +13302,8 @@ display the full form:  
          (\protect\firstacronymfont{\glsentryshortpl{##1}})%  
        }%  
      }% - - + +  
      % plural and first letter upper case  
      \renewcommand*{\Genplacrfullformat}[2]{%  
        \ifglsfieldeq{##1}{abbrtype}{word} @@ -10990,31 +13329,31 @@ display the full form:  
      \renewcommand*{\acrpluralsuffix}{\glspluralsuffix}%  
     }
    -

    Remember that the new style needs to be set before defining any terms: - - +

    Remember that the new style needs to be set before defining any terms: + +

    -
    +
    \setacronymstyle{mystyle}
    -

    -

    Since it’s a bit confusing to use

    +

    Since it’s a bit confusing to use \newacronym for something that’s not technically an -acronym, let’s define a new command for initialisms: - - + id="dx1-117004"> for something that’s not technically an acronym, let’s define a +new command for initialisms: + +

    -
    +
    \newcommand*{\newinitialism}[4][]{%  
      \newacronym[abbrtype=initialism,#1]{#2}{#3}{#4}%  
    }
    -

    Now the entries can all be defined: - - +

    Now the entries can all be defined: + +

    -
    +
    \newacronym{radar}{radar}{radio detecting and ranging}  
    \newacronym{laser}{laser}{light amplification by stimulated  
    emission of radiation} @@ -11023,152 +13362,151 @@ acronym, let’s define a new command for initialisms:  
    \newinitialism{dsp}{DSP}{digital signal processing}  
    \newinitialism{atm}{ATM}{automated teller machine}
    -

    On

    On first use, \gls{radar} will produce “radar (radio detecting and ranging)” but \gls{dsp} -will produce “DSP (digital signal processing)”. -

    For a complete document, see the sample file \gls{dsp} will produce +“DSP (digital signal processing)”. +

    For a complete document, see the sample file sample-storage-abbr.tex.

    -

    -

    ____________________________

    -

    In the above example, if \newglossaryentry is explicitly used (instead of through -\newacronym) the abbrtype key will be set to its default value of “word” but the -\ifglshaslong test in the custom acronym style will be false (since the long key hasn’t been -set) so the display style will switch to that given by \glsgenentryfmt and they’ll be no test -performed on the

    +

    ____________________________

    +

    In the above example, if \newglossaryentry is explicitly used (instead of through \newacronym) the +abbrtype key will be set to its default value of “word” but the \ifglshaslong test in the custom acronym style +will be false (since the long key hasn’t been set) so the display style will switch to that given by +\glsgenentryfmt and they’ll be no test performed on the abbrtype field. -

    +

    Example 5 (Defining Custom Storage Key (Acronyms and +class="cmbx-12"> (Defining Custom Storage Key (Acronyms and Non-Acronyms with Non-Acronyms with Descriptions)) -

    The previous example can be modified if the description also needs to be provided. Here -I’ve changed “word” to “acronym”: - - +class="cmbx-12">Descriptions)) +

    The previous example can be modified if the description also needs to be provided. Here I’ve changed +“word” to “acronym”: + +

    -
    +
    \glsaddstoragekey  
     {abbrtype}% key/field name  
     {acronym}% default value if not explicitly set  
     {\abbrtype}% custom command to access the value if required
    -

    This may seem a little odd for non-abbreviated entries defined using \newglossaryentry -directly, but

    This may seem a little odd for non-abbreviated entries defined using \newglossaryentry directly, but +\ifglshaslong can be used to determine whether or not to reference the value -of this new abbrtype field. -

    The new acronym style has a minor modification that forces the user to specify a -description. In the previous example, the line: - - + id="dx1-117009"> can be used to determine whether or not to reference the value of this new abbrtype +field. +

    The new acronym style has a minor modification that forces the user to specify a description. In the +previous example, the line: + +

    -
    +
       \renewcommand*{\GenericAcronymFields}{%  
         description={\the\glslongtok}}%
    -

    needs to be changed to: - - +

    needs to be changed to: + +

    -
    +
       \renewcommand*{\GenericAcronymFields}{}%
    -

    Additionally, to accommodate the change in the default value of the abbrtype key, all -instances of - - +

    Additionally, to accommodate the change in the default value of the abbrtype key, all instances +of + +

    -
    +
        \ifglsfieldeq{##1}{abbrtype}{word}
    -

    need to be changed to: - - +

    need to be changed to: + +

    -
    +
        \ifglsfieldeq{##1}{abbrtype}{acronym}
    -

    -

    Once this new style has been set, the new acronyms can be defined using the optional -argument to set the description: - - +

    +

    Once this new style has been set, the new acronyms can be defined using the optional argument to set the +description: + +

    -
    +
    \newacronym[description={system for detecting the position and  
    speed of aircraft, ships, etc}]{radar}{radar}{radio detecting  
    and ranging}
    -

    -

    No change is required for the definition of \newinitialism but again the optional -argument is required to set the description: - - +

    +

    No change is required for the definition of \newinitialism but again the optional argument is required to +set the description: + +

    -
    +
    \newinitialism[description={mathematical manipulation of an  
    information signal}]{dsp}{DSP}{digital signal processing}
    -

    -

    We can also accommodate contractions in a similar manner to the initialisms: - - +

    +

    We can also accommodate contractions in a similar manner to the initialisms: + +

    -
    +
    \newcommand*{\newcontraction}[4][]{%  
      \newacronym[abbrtype=contraction,#1]{#2}{#3}{#4}%  
    }
    -

    The contractions can similarly been defined using this new command: - - +

    The contractions can similarly been defined using this new command: + +

    -
    +
    \newcontraction[description={front part of a ship below the  
    deck}]{focsle}{fo'c's'le}{forecastle}
    -

    -

    Since the custom acronym style just checks if

    +

    Since the custom acronym style just checks if abbrtype is acronym, the contractions will -be treated the same as the initialisms, but the style could be modified by a further test of the -abbrtype value if required. -

    To test regular non-abbreviated entries, I’ve also defined a simple word: - - +class="cmtt-10">acronym, the contractions will be treated the +same as the initialisms, but the style could be modified by a further test of the abbrtype value if +required. +

    To test regular non-abbreviated entries, I’ve also defined a simple word: + +

    -
    +
    \newglossaryentry{apple}{name={apple},description={a fruit}}
    -

    -

    Now for a new glossary style that provides information about the abbreviation (in -addition to the description): - - +

    +

    Now for a new glossary style that provides information about the abbreviation (in addition to the +description): + +

    -
    +
    \newglossarystyle  
     {mystyle}% style name  
     {% base it on the "list" style @@ -11181,101 +13519,96 @@ addition to the description):  
           \glossentrydesc{##1}\glspostdescription\space ##2}%  
     }
    -

    This uses

    This uses \ifglshaslong to determine whether or not the term is an abbreviation. If it has -an abbreviation, the full form is supplied in parentheses and \abbrtype (defined by -\glsaddstoragekey earlier) is used to indicate the type of abbreviation. -

    With this style set, the to determine whether or not the term is an abbreviation. If it has an abbreviation, +the full form is supplied in parentheses and \abbrtype (defined by \glsaddstoragekey earlier) is used to +indicate the type of abbreviation. +

    With this style set, the apple entry is simply displayed in the glossary as

    apple
    a fruit.
    -

    but the abbreviations are displayed in the form +

    but the abbreviations are displayed in the form

    laser
    (acronym: light amplification by stimulated emission of radiation) device that - creates a narrow beam of intense light.
    -

    (for acronyms) or +class="description">(acronym: light amplification by stimulated emission of radiation) device that creates a narrow + beam of intense light. +

    (for acronyms) or

    DSP
    (initialism: digital signal processing) mathematical manipulation of an - information signal.
    -

    (for initalisms) or +class="description">(initialism: digital signal processing) mathematical manipulation of an information signal. +

    (for initalisms) or

    fo’c’s’le
    (contraction: forecastle) front part of a ship below the deck.
    -

    (for contractions). -

    For a complete document, see

    (for contractions). +

    For a complete document, see sample-storage-abbr-desc.tex.

    -

    -

    ____________________________

    - - -

    +

    +

    ____________________________

    + + +

    -

    Top

    4.4 Expansion

    -

    When you define new glossary entries expansion is performed by default, except for the name, +

    When you define new glossary entries expansion is performed by default, except for the name, description, +descriptionplural, symbol, symbolplural and sort keys (these keys all have expansion suppressed via description, descriptionplural, symbol, symbolplural and sort keys (these keys all have expansion -suppressed via \glssetnoexpandfield). -

    You can switch expansion on or off for individual keys using -


    \glssetexpandfield 

    You can switch expansion on or off for individual keys using +


    \glssetexpandfield{field}

    -

    +

    or -


    \glssetnoexpandfield 


    \glssetnoexpandfield{field}

    -

    +

    respectively, where ⟨field⟩ is the field tag corresponding to the key. In most cases, this is the -same as the name of the key except for those listed in field⟩ is the field tag corresponding to the key. In most cases, this is the same as the name of +the key except for those listed in table 4.1.

    - - -


    - - + +
    Table 4.1: Key to Field Mappings
    +class="content">Key to Field Mappings
    Key Key Field
    sort sort sortvalue
    firstplural firstplural firstpl
    description description desc
    descriptionplural descriptionplural descplural
    user1 user1 useri
    user2 user2 userii
    user3 user3 useriii
    user4 user4 useriv
    user5 user5 userv
    user6 user6 uservi
    longplural longplural longpl
    shortplural shortplural shortpl
    - - + +

    -

    Any keys that haven’t had the expansion explicitly set using \glssetexpandfield or -\glssetnoexpandfield are governed by -


    \glsexpandfields 

    Any keys that haven’t had the expansion explicitly set using \glssetexpandfield or \glssetnoexpandfield +are governed by +


    \glsexpandfields

    -

    +

    and -


    \glsnoexpandfields 


    \glsnoexpandfields

    -

    -

    If your entries contain any fragile commands, I recommend you switch off expansion via -\glsnoexpandfields. (This should be used before you define the entries.) +

    +

    If your entries contain any fragile commands, I recommend you switch off expansion via \glsnoexpandfields. +(This should be used before you define the entries.)

    -

    Top

    4.5 Sub-Entries

    -

    As from version 1.17, it is possible to specify sub-entries. These may be used to order the -glossary into categories, in which case the sub-entry will have a different name to its parent -entry, or it may be used to distinguish different definitions for the same word, in which -case the sub-entries will have the same name as the parent entry. Note that not all -glossary styles support hierarchical entries and may display all the entries in a -flat format. Of the styles that support sub-entries, some display the sub-entry’s -name whilst others don’t. Therefore you need to ensure that you use a suitable -style. (See §15 Glossary Styles for a list of predefined styles.) As from version 3.0, -level 1 sub-entries are automatically numbered in the predefined styles if you use the -

    As from version 1.17, it is possible to specify sub-entries. These may be used to order the glossary into +categories, in which case the sub-entry will have a different name to its parent entry, or it may be used to +distinguish different definitions for the same word, in which case the sub-entries will have the same name as the +parent entry. Note that not all glossary styles support hierarchical entries and may display all the entries in a +flat format. Of the styles that support sub-entries, some display the sub-entry’s name whilst others don’t. +Therefore you need to ensure that you use a suitable style. (See §15 Glossary Styles for a list of predefined +styles.) As from version 3.0, level 1 sub-entries are automatically numbered in the predefined styles +if you use the subentrycounter package option (see §2.3 package option (see §2.3 Glossary Appearance Options for further details). -

    Note that the parent entry will automatically be added to the glossary if any of its child -entries are used in the document. If the parent entry is not referenced in the document, it will -not have a

    Note that the parent entry will automatically be added to the glossary if any of its child entries are used in +the document. If the parent entry is not referenced in the document, it will not have a number list. Note also that . Note also +that makeindex has a restriction on the maximum -sub-entry depth. -

    + id="dx1-119003"> has a restriction on the maximum sub-entry depth. +

    -

    Top

    4.5.1 Hierarchical Categories

    -

    To arrange a glossary with hierarchical categories, you need to first define the category and -then define the sub-entries using the relevant category entry as the value of the parent -key. +

    To arrange a glossary with hierarchical categories, you need to first define the category and then define the +sub-entries using the relevant category entry as the value of the parent key. -

    +

    Example 6 (Hierarchical Categories—Greek and Roman Mathematical Symbols) -

    Suppose I want a glossary of mathematical symbols that are divided into Greek letters - - -and Roman letters. Then I can define the categories as follows: - - + id="x1-120003"> +

    Suppose I want a glossary of mathematical symbols that are divided into Greek letters and Roman letters. +Then I can define the categories as follows: + +

    -
    +
    \newglossaryentry{greekletter}{name={Greek letters},  
    description={\nopostdesc}}  
    \newglossaryentry{romanletter}{name={Roman letters},  
    description={\nopostdesc}}
    -

    -

    Note that in this example, the category entries don’t need a description so I have set the -descriptions to

    +

    Note that in this example, the category entries don’t need a description so I have set the descriptions to +\nopostdesc. This gives a blank description and suppresses the description -terminator. -

    I can now define my sub-entries as follows: - - + id="dx1-120004">. This gives a blank description and suppresses the description terminator. +

    I can now define my sub-entries as follows: + +

    -
    +
    \newglossaryentry{pi}{name={\ensuremath{\pi}},sort={pi},  
    description={ratio of the circumference of a circle to  
    the diameter}, @@ -11476,41 +13796,40 @@ terminator.  
    description={Euler's constant},  
    parent=romanletter}
    -

    For a complete document, see the sample file

    For a complete document, see the sample file sampletree.tex.

    -

    -

    ____________________________

    -

    +

    +

    ____________________________

    +

    -

    Top

    4.5.2 Homographs

    -

    Sub-entries that have the same name as the parent entry, don’t need to have the -name key. For example, the word “glossary” can mean a list of technical words or a -collection of glosses. In both cases the plural is “glossaries”. So first define the parent -entry: - - +

    Sub-entries that have the same name as the parent entry, don’t need to have the name key. For example, the +word “glossary” can mean a list of technical words or a collection of glosses. In both cases the plural is +“glossaries”. So first define the parent entry: + +

    -
    +
    \newglossaryentry{glossary}{name=glossary,  
    description={\nopostdesc},  
    plural={glossaries}}
    -

    Again, the parent entry has no description, so the description terminator needs to be -suppressed using

    Again, the parent entry has no description, so the description terminator needs to be suppressed using +\nopostdesc. -

    Now define the two different meanings of the word: - - + id="dx1-121002">. +

    Now define the two different meanings of the word: + +

    -
    +
    \newglossaryentry{glossarylist}{  
    description={list of technical words},  
    sort={1}, @@ -11520,38 +13839,39 @@ class="cmtt-10">\nopostdescsort={2},  
    parent={glossary}}
    -

    Note that if I reference the parent entry, the location will be added to the parent’s number -list, whereas if I reference any of the child entries, the location will be added to the child -entry’s number list. Note also that since the sub-entries have the same name, the sort key is -required unless you are using the sort=use or sort=def package options (see §2.4 -

    Note that if I reference the parent entry, the location will be added to the parent’s number list, whereas if I +reference any of the child entries, the location will be added to the child entry’s number list. Note also that since +the sub-entries have the same name, the sort key is required unless you are using the sort=use or +sort=def package options (see §2.5 Sorting Options). You can use the subentrycounter package option to automatically -number the first-level child entries. See §2.3 package option to +automatically number the first-level child entries. See §2.3 Glossary Appearance Options for further details. -

    In the above example, the plural form for both of the child entries is the same as the -parent entry, so the plural key was not required for the child entries. However, if the -sub-entries have different plurals, they will need to be specified. For example: - - +

    In the above example, the plural form for both of the child entries is the same as the parent entry, so the +plural key was not required for the child entries. However, if the sub-entries have different plurals, they will +need to be specified. For example: + +

    -
    +
    \newglossaryentry{bravo}{name={bravo},  
    description={\nopostdesc}}  
    \newglossaryentry{bravocry}{description={cry of approval @@ -11565,89 +13885,84 @@ sub-entries have different plurals, they will need to be specified. For example:  
    plural={bravoes},  
    parent=bravo}
    -

    -

    +

    +

    -

    Top

    4.6 Loading Entries From a File

    -

    You can store all your glossary entry definitions in another file and use: -


    \loadglsentries 

    You can store all your glossary entry definitions in another file and use: +


    \loadglsentries[type]{filename}

    -

    +

    where ⟨filename⟩ is the name of the file containing all the \newglossaryentry or - or \longnewglossaryentry commands. The optional argument ⟨type⟩ is the name of the glossary -to which those entries should belong, for those entries where the type key has been omitted -(or, more specifically, for those entries whose type has been specified by +commands. The optional argument ⟨type⟩ is the name of the glossary to which those entries should +belong, for those entries where the type key has been omitted (or, more specifically, for those entries +whose type has been specified by \glsdefaulttype, -which is what , which is what \newglossaryentry uses by default). -

    This is a preamble-only command. You may also use uses by +default). +

    This is a preamble-only command. You may also use \input to load the file but don’t use - to load the file but don’t use \include. If you find that your file is becoming unmanageably large, you may want to -consider switching to . If you +find that your file is becoming unmanageably large, you may want to consider switching to bib2gls and use an application such as JabRef to manage the entry -definitions. -

    If you want to use and use an +application such as JabRef to manage the entry definitions. +

    If you want to use \AtBeginDocument to \input all your entries automatically at the -start of the document, add the to \input all your entries automatically at the start of the document, +add the \AtBeginDocument command before you load the glossaries -package (and package (and babel, if you are also loading that) to avoid the creation of the .glsdefs file and -any associated problems that are caused by defining commands in the , if you are also loading +that) to avoid the creation of the glsdefs file and any associated problems that are caused by defining +commands in the document -environment. (See §4.8 Drawbacks With Defining Entries in the Document Environment.) -
    -

    - - + id="dx1-122014"> environment. (See §4.8 Drawbacks With Defining Entries in the Document +Environment.)

    +

    + + -

    +

    Example 7 (Loading Entries from Another File) -

    Suppose I have a file called +

    Suppose I have a file called myentries.tex which contains: - - + +

    -
    +
    \newglossaryentry{perl}{type=main,  
    name={Perl},  
    description={A scripting language}} @@ -11657,1061 +13972,1008 @@ class="cmtt-10">myentries.tex which contains:  
    name={html},  
    description={A mark up language}}
    -

    and suppose in my document preamble I use the command: - - +

    and suppose in my document preamble I use the command: + +

    -
    +
    \loadglsentries[languages]{myentries}
    -

    then this will add the entries

    then this will add the entries tex and html to the glossary whose type is given by -languages, but the entry perl will be added to the main glossary, since it explicitly sets the -type to main.

    +class="cmtt-10">html to the glossary whose type is given by languages, +but the entry perl will be added to the main glossary, since it explicitly sets the type to main. +

    -

    -

    ____________________________

    -

    Note: if you use

    +

    ____________________________

    +

    Note: if you use \newacronym (see §13 Acronyms and Other Abbreviations) the type is -set as type=\acronymtype unless you explicitly override it. For example, if my file -myacronyms.tex contains: - - -

    -
    + id="dx1-122018"> (see §13 Acronyms and Other Abbreviations) the type is set +as type=\acronymtype unless you explicitly override it. For example, if my file myacronyms.tex +contains: + + +

    +
    \newacronym{aca}{aca}{a contrived acronym}
    -

    then (supposing I have defined a new glossary type called

    then (supposing I have defined a new glossary type called altacronym) - - + +

    -
    +
    \loadglsentries[altacronym]{myacronyms}
    -

    will add

    will add aca to the glossary type acronym, if the package option acronym has been specified, + id="dx1-122019"> has been specified, or will add aca to the glossary type altacronym, if the package option acronym is not + id="dx1-122020"> is not specified.4.1 -

    If you have used the +

    If you have used the acronym package option, there are two possible solutions to this -problem: + id="dx1-122025"> package option, there are two possible solutions to this problem:

    1. Change Change myacronyms.tex so that entries are defined in the form: - - -
      + + +
      \newacronym[type=\glsdefaulttype]{aca}{aca}{a  
      contrived acronym}
      -

      and do: - - +

      and do: + +

      -
      +
      \loadglsentries[altacronym]{myacronyms}
      -

      +

    2. Temporarily change Temporarily change \acronymtype to the target glossary: - - -
      + + +
      \let\orgacronymtype\acronymtype  
      \renewcommand{\acronymtype}{altacronym}  
      \loadglsentries{myacronyms}  
      \let\acronymtype\orgacronymtype
      -

    -

    Note that only those entries that have been used in the text will appear in the relevant -glossaries. Note also that

    +

    Note that only those entries that have been used in the text will appear in the relevant glossaries. Note also +that \loadglsentries may only be used in the preamble. -

    Remember that you can use

    Remember that you can use \provideglossaryentry rather than rather than \newglossaryentry. -Suppose you want to maintain a large database of acronyms or terms that you’re likely to use -in your documents, but you may want to use a modified version of some of those entries. -(Suppose, for example, one document may require a more detailed description.) Then if you -define the entries using \provideglossaryentry in your database file, you can override the -definition by simply using \newglossaryentry before loading the file. For example, suppose -your file (called, say, . Suppose you want +to maintain a large database of acronyms or terms that you’re likely to use in your documents, but you may +want to use a modified version of some of those entries. (Suppose, for example, one document may require a +more detailed description.) Then if you define the entries using \provideglossaryentry in your database file, +you can override the definition by simply using \newglossaryentry before loading the file. For example, +suppose your file (called, say, terms.tex) contains: - - + +

    -
    +
    \provideglossaryentry{mallard}{name=mallard,  
     description={a type of duck}}
    -

    but suppose your document requires a more detailed description, you can do: - - +

    but suppose your document requires a more detailed description, you can do: + +

    -
    +
    \usepackage{glossaries}  
    \makeglossaries  
    \newglossaryentry{mallard}{name=mallard,  
     description={a dabbling duck where the male has a green head}}  
    \loadglsentries{terms}
    -

    Now the

    Now the mallard definition in the terms.tex file will be ignored. -

    +

    -

    Top

    4.7 Moving Entries to Another Glossary

    -

    As from version 3.02, you can move an entry from one glossary to another using: -


    \glsmoveentry 

    As from version 3.02, you can move an entry from one glossary to another using: +


    \glsmoveentry{label}{target glossary label}

    -

    +

    where ⟨label⟩ is the unique label identifying the required entry and ⟨target glossary label⟩ is the -unique label identifying the glossary in which to put the entry. -

    Note that no check is performed to determine the existence of the target glossary. If -you want to move an entry to a glossary that’s skipped by target glossary label⟩ is the unique label +identifying the glossary in which to put the entry. +

    Note that no check is performed to determine the existence of the target glossary. If you want to move an +entry to a glossary that’s skipped by \printglossaries, -then define an ignored glossary with , then define an ignored glossary with +\newignoredglossary. (See §12 Defining New -Glossaries.) -

    Unpredictable results may occur if you move an entry to a different glossary from its -parent or children.
    -

    -

    + id="dx1-123003">. (See §12 Defining New Glossaries.) +

    Unpredictable results may occur if you move an entry to a different glossary from its parent or children. +
    +

    +

    -

    Top

    4.8 Drawbacks With Defining Entries in the Document Environment

    -

    Originally,

    Originally, \newglossaryentry (and (and \newacronym) could only be used in the preamble. I -reluctantly removed this restriction in version 1.13, but there are issues with defining -commands in the ) could only be used in the preamble. I reluctantly removed +this restriction in version 1.13, but there are issues with defining commands in the document environment instead of the preamble, which is why the restriction -is maintained for newer commands. This restriction is also reimposed for \newglossaryentry -by the new environment +instead of the preamble, which is why the restriction is maintained for newer commands. This restriction is also +reimposed for \newglossaryentry by the new Option 1. (The glossaries-extra package automatically reimposes this -restriction for Options glossaries-extra package automatically +reimposes this restriction for Options 2 and 3 but provides a package option to allow document definitions.) - - -

    + + +

    -

    Top

    4.8.1 Technical Issues

    -

    +

    1. If you define an entry mid-way through your document, but subsequently shuffle - sections around, you could end up using an entry before it has been defined. + class="enumerate" id="x1-125002x1">If you define an entry mid-way through your document, but subsequently shuffle sections around, + you could end up using an entry before it has been defined.
    2. Entry information is required when displaying the glossary. If this occurs at the - start of the document, but the entries aren’t defined until later, then the entry - details are being looked up before the entry has been defined. + class="enumerate" id="x1-125004x2">Entry information is required when displaying the glossary. If this occurs at the start of the + document, but the entries aren’t defined until later, then the entry details are being looked up + before the entry has been defined.
    3. If you use a package, such as If you use a package, such as babel, that makes certain characters active at the start - of the , that makes certain characters active at the start of the document environment, there will be a problem if those characters have - a special significance when defining glossary entries. These characters include the - double-quote + environment, there will be a problem if those characters have a special significance when defining + glossary entries. These characters include the double-quote " character, the exclamation mark ! character, the question mark - ! + character, the question mark ? character, and the pipe | character. They must not be active when defining - a glossary entry where they occur in the sort key (and they should be avoided in - the label if they may be active at any point in the document). Additionally, the - comma , character and the equals = character should not be active when using - commands that have ⟨| character. They must not be active when + defining a glossary entry where they occur in the sort key (and they should be avoided in the label + if they may be active at any point in the document). Additionally, the comma , character and the + equals = character should not be active when using commands that have ⟨key⟩=⟨value⟩ arguments.
    -

    To overcome the first two problems, as from version 4.0 the glossaries package modifies the -definition of

    To overcome the first two problems, as from version 4.0 the glossaries package modifies the definition of +\newglossaryentry at the beginning of the document environment so that the -definitions are written to an external file (\jobname.glsdefs) which is then read in at the -start of the document on the next run. The entry will then only be defined in the - environment so that the definitions are written to an +external file (\jobnameglsdefs) which is then read in at the start of the document on the next run. The entry +will then only be defined in the document environment if it doesn’t already exist. This means that the entry can now -be looked up in the glossary, even if the glossary occurs at the beginning of the + id="dx1-125014"> environment if it doesn’t already exist. This means that the +entry can now be looked up in the glossary, even if the glossary occurs at the beginning of the document. -

    There are drawbacks to this mechanism: if you modify an entry definition, you need a -second run to see the effect of your modification; this method requires an extra \newwrite, -which may exceed TEX’s maximum allocation; unexpected expansion issues could occur; the -see key isn’t stored, which means it can’t be added to the .glsdefs file when it’s -created at the end of the document (and therefore won’t be present on subsequent +

    There are drawbacks to this mechanism: if you modify an entry definition, you need a second run to see the +effect of your modification; this method requires an extra \newwrite, which may exceed TEX’s maximum +allocation; unexpected expansion issues could occur; the see key isn’t stored, which means it can’t be added to +the glsdefs file when it’s created at the end of the document (and therefore won’t be present on subsequent runs). -

    The

    The glossaries-extra package provides a setting (but only for Options 2 and 3) that allows -\newglossaryentry to occur in the document environment but doesn’t create the -.glsdefs file. This circumvents some problems but it means that you can’t display -any of the glossaries before all the entries have been defined (so it’s all right if all -the glossaries are at the end of the document but not if any occur in the front +href="#option3">3) that allows \newglossaryentry +to occur in the document environment but doesn’t create the glsdefs file. This circumvents some problems but +it means that you can’t display any of the glossaries before all the entries have been defined (so +it’s all right if all the glossaries are at the end of the document but not if any occur in the front matter). - - -

    +

    -

    Top

    4.8.2 Good Practice Issues

    -

    The above section covers technical issues that can cause your document to have compilation -errors or produce incorrect output. This section focuses on good writing practice. The main -reason cited by users wanting to define entries within the

    The above section covers technical issues that can cause your document to have compilation errors or produce +incorrect output. This section focuses on good writing practice. The main reason cited by users wanting to + + +define entries within the document environment -rather than in the preamble is that they want to write the definition as they type in -their document text. This suggests a “stream of consciousness” style of writing -that may be acceptable in certain literary genres but is inappropriate for factual + id="dx1-126001"> environment rather than in the preamble is that they want to +write the definition as they type in their document text. This suggests a “stream of consciousness” +style of writing that may be acceptable in certain literary genres but is inappropriate for factual documents. -

    When you write technical documents, regardless of whether it’s a PhD thesis or an article -for a journal or proceedings, you must plan what you write in advance. If you plan in -advance, you should have a fairly good idea of the type of terminology that your -document will contain, so while you are planning, create a new file with all your -entry definitions. If, while you’re writing your document, you remember another -term you need, then you can switch over to your definition file and add it. Most -text editors have the ability to have more than one file open at a time. The other -advantage to this approach is that if you forget the label, you can look it up in -the definition file rather than searching through your document text to find the +

    When you write technical documents, regardless of whether it’s a PhD thesis or an article for a journal or +proceedings, you must plan what you write in advance. If you plan in advance, you should have a fairly good +idea of the type of terminology that your document will contain, so while you are planning, create a new file +with all your entry definitions. If, while you’re writing your document, you remember another term you need, +then you can switch over to your definition file and add it. Most text editors have the ability to have more than +one file open at a time. The other advantage to this approach is that if you forget the label, you +can look it up in the definition file rather than searching through your document text to find the definition. - - + +

    -

    -

    +

    Top

    5. Number lists

    -

    Each entry in the glossary has an associated

    Each entry in the glossary has an associated number list. By default, these numbers refer -to the pages on which that entry has been indexed (using any of the commands described in -§6 Links to Glossary Entries and §7 Adding an Entry to the Glossary Without Generating -Text). The number list can be suppressed using the . By default, these numbers refer to the +pages on which that entry has been indexed (using any of the commands described in §6 Links to +Glossary Entries and §7 Adding an Entry to the Glossary Without Generating Text). The number list +can be suppressed using the nonumberlist package option, or an -alternative counter can be set as the default using the package option, or an alternative counter can be set as +the default using the counter package option. The number -list is also referred to as the location list. -

    package option. The number list is also referred to as the location +list. +

    Number lists are more common with indexes rather than glossaries (although you can use -the glossaries package for indexes as well). However, the glossaries package makes use of -s are more common with indexes rather than glossaries (although you can use the glossaries +package for indexes as well). However, the glossaries package makes use of makeindex or or xindy to hierarchically sort and collate the entries since they are readily -available with most modern TEX distributions. Since these are both designed as indexing -applications they both require that terms either have a valid location or a cross-reference. -Even if you use to hierarchically +sort and collate the entries since they are readily available with most modern TEX distributions. Since these +are both designed as indexing applications they both require that terms either have a valid location or a +cross-reference. Even if you use nonumberlist, the locations must still be provided and acceptable -to the indexing application or they will cause an error during the indexing stage, -which will interrupt the document build. However, if you’re not interested in the -locations, each entry only needs to be indexed once, so consider using , the locations must still be provided and acceptable to the indexing +application or they will cause an error during the indexing stage, which will interrupt the document build. +However, if you’re not interested in the locations, each entry only needs to be indexed once, so consider using +indexonlyfirst, -which can improve the document build time by only indexing the , which can improve the document build time by only indexing the first use of each term. -

    The

    The \glsaddall command (see §7 Adding an Entry to the Glossary Without Generating -Text), which is used to automatically index all entries, iterates over all defined entries and -does command (see §7 Adding an Entry to the Glossary Without Generating Text), which is used +to automatically index all entries, iterates over all defined entries and does \glsadd{label} for each entry (where ⟨label⟩ is that entry’s label). This means that -\glsaddall automatically adds the same location to every entry’s } for +each entry (where ⟨label⟩ is that entry’s label). This means that \glsaddall automatically adds +the same location to every entry’s number list, which looks -weird if the number list hasn’t been suppressed. -

    With , which looks weird if the number list hasn’t been +suppressed. +

    With Option 4, the indexing is performed by bib2gls, which was specifically designed for -the , which was specifically designed for the glossaries-extra package. So it will allow any location format, and its selection=all -option will select all entries without adding an unwanted location to the glossaries-extra +package. So it will allow any location format, and its selection=all option will select all entries without +adding an unwanted location to the number list. If -. If bib2gls can deduce a numerical value for a location, it will attempt to form a range over -consecutive locations, otherwise it won’t try to form a range and the location will just form -an individual item in the list. can deduce a numerical value for a location, it will +attempt to form a range over consecutive locations, otherwise it won’t try to form a range and the location will +just form an individual item in the list. Option 1 also allows any location but it doesn’t form ranges.

    -

    Top

    5.1 Encap Values

    -

    Each location in the

    Each location in the number list is encapsulated with a command formed from the is encapsulated with a command formed from the encap -value. By default this is the value. By default this +is the \glsnumberformat command, which corresponds to the encap -glsnumberformat, but this may be overridden using the format key in the optional argument -to commands like command, which corresponds to the encap glsnumberformat, but this may be +overridden using the format key in the optional argument to commands like \gls. (See §6 Links to Glossary Entries.) For example, you may want the -location to appear in bold to indicate the principle use of a term or symbol. If the encap -starts with an open parenthesis §6 Links to Glossary +Entries.) For example, you may want the location to appear in bold to indicate the principle use of a term or +symbol. If the encap starts with an open parenthesis ( this signifies the start of a range and if the encap starts with close parenthesis ) this signifies the end of a range. These must always occur in -matching pairs. -

    The ) this signifies the end of a range. These must always occur in matching +pairs. +

    The glossaries package provides the command \glsignore which ignores its argument. -This is the format used by \glsaddallunused to suppress the location, which works fine as -long as no other locations are added to the which ignores its argument. This is the format +used by \glsaddallunused to suppress the location, which works fine as long as no other locations are added to +the number list. For example, if you use - - -. For example, if you use \gls{sample} on page 2 then reset the first use flag and then use \glsaddallunused on -page 10, the first use flag and then use +\glsaddallunused on page 10, the number list for for sample will be 2, \glsignore{10} which will result in “2, ” -which has a spurious comma. -

    This isn’t a problem with  \glsignore{10} which will result in +“2, ” which has a spurious comma. +

    This isn’t a problem with bib2gls because you’d use selection=all instead of -\glsaddallunused, but even if you explicitly had, for example, \gls[format=glsignore] -{ because you’d use selection=all instead of \glsaddallunused, but +even if you explicitly had, for example, \gls[format=glsignore]{label} for some reason, bib2gls will recognise glsignore as a special encap indicating an -ignored location, so it will select the entry but not add that location to the will + + +recognise glsignore as a special encap indicating an ignored location, so it will select the entry but not add +that location to the number list. It’s a -problem for all the other options (except Option 5, which doesn’t perform any -indexing). -

    Complications can arise if you use different encap values for the same location. For -example, suppose on page 10 you have both the default . It’s a problem for all the other options (except Option 5, which doesn’t +perform any indexing). +

    Complications can arise if you use different encap values for the same location. For example, suppose on +page 10 you have both the default glsnumberformat and textbf -encaps. While it may seem apparent that textbf encaps. While it may seem apparent that +textbf should override glsnumberformat in this -situation, the indexing application may not know it. This is therefore something you need to -be careful about if you use the format key or if you use a command that implicitly sets -it. -

    In the case of glsnumberformat in this situation, the indexing application may not know it. This is +therefore something you need to be careful about if you use the format key or if you use a command that +implicitly sets it. +

    In the case of xindy, it only accepts one encap (according to the order of precedence given -in the , it only accepts one encap (according to the order of precedence given in the xindy module) and discards the others for identical locations (for the same -entry). This can cause a problem if a discarded location forms the start or end of a -range. -

    In the case of +module) and discards the others for identical locations (for the same entry). This can cause a problem if a +discarded location forms the start or end of a range. +

    In the case of makeindex, it accepts different encaps for the same location, but warns -about it. This leads to a , it accepts different encaps for the same location, but warns about it. This leads to +a number list with the same location repeated in different formats. If -you use the with the same location repeated in different formats. If you use the makeglossaries Perl script with Perl script +with Option 2 it will detect makeindex’s warning -and attempt to fix the problem, ensuring that the glsnumberformat encap always has the -least precedence unless it includes a range identifier. Other conflicting encaps will have the -last one override earlier ones for the same location with range identifiers taking + id="dx1-128017">’s warning and attempt to fix the problem, ensuring that the +glsnumberformat encap always has the least precedence unless it includes a range identifier. Other conflicting +encaps will have the last one override earlier ones for the same location with range identifiers taking priority. -

    No discard occurs with Option 1 so again you get the same location repeated in different -formats. With

    No discard occurs with Option 1 so again you get the same location repeated in different formats. With +Option 4, bib2gls will discard according to order of precedence, -giving priority to start and end range encaps. (See the will discard according to order of precedence, giving priority to start and end range encaps. +(See the bib2gls manual for further -details.) -

    + id="dx1-128019"> manual for further details.) +

    -

    Top

    5.2 Locations

    -

    Neither

    Neither Option 1 nor Option 4 care about the location syntax as long as it’s valid -LATEX code (and doesn’t contain fragile commands). In both cases, the indexing is -performed by writing a line to the .aux file. The write operation is deferred to avoid the -problems associated with TEX’s asynchronous output routine. (See, for example, Finding if -you’re on an odd or an even page for more details on this issue.) Unfortunately Options 2 -and Option 4 care about the location syntax as long as it’s valid LATEX code (and doesn’t +contain fragile commands). In both cases, the indexing is performed by writing a line to the aux file. The write +operation is deferred to avoid the problems associated with TEX’s asynchronous output routine. (See, for +example, Finding if you’re on an odd or an even page for more details on this issue.) Unfortunately +Options 2 and 3 are far more problematic and need some complex code to deal with awkward locations. -

    If you know that your locations will always expand to a format acceptable to your chosen -indexing application then use the package option esclocations=false to bypass this operation. -This setting only affects Options 

    If you know that your locations will always expand to a format acceptable to your chosen indexing +application then use the package option esclocations=false to bypass this operation. This setting only affects +Options 2 and 3 as the problem doesn’t arise with the other - - -indexing options. -

    Both 3 as the problem doesn’t arise with the other indexing options. +

    Both makeindex and and xindy are fussy about the syntax of the locations. In the -case of are fussy about the syntax of the locations. In the case of makeindex, only the numbering system obtained with , only the +numbering system obtained with \arabic, \roman, -\roman, \Roman, \alph and \Alph or composites formed from them with the same separator -(set with \Alph or composites formed from them +with the same separator (set with \glsSetCompositor{char}) are accepted. (makeindex won’t accept an -empty location.) In the case of won’t accept an empty +location.) In the case of xindy, you can define your own location classes, -but if the location contains a robust command then the leading backslash must be -escaped. The , you can define your own location classes, but if the location contains a robust +command then the leading backslash must be escaped. The glossaries package tries to do this, but it’s caught between two conflicting -requirements: + id="dx1-129008"> package tries to do this, but it’s caught +between two conflicting requirements:

    1. The location must be fully expanded before The location must be fully expanded before \ can be converted to \\ (there’s no - point converting \\ (there’s no point converting + \thepage to \\thepage);
    2. + +
    3. The page number can’t be expanded until the deferred write operation (so \c@page - mustn’t expand in the previous step but \the\c@page mustn’t be converted to + class="enumerate" id="x1-129012x2">The page number can’t be expanded until the deferred write operation (so \c@page mustn’t + expand in the previous step but \the\c@page mustn’t be converted to \\the\\c@page and \\the\\c@page and \number\c@page mustn’t be converted to \\number\\c@page - etc).
    -

    There’s a certain amount of trickery needed to deal with this conflict and the code requires -the location to be in a form that doesn’t embed the counter’s internal register in -commands like \value. For example, suppose you have a robust command called -\tallynum that takes a number as the argument and an expandable command called -\tally that converts a counter name into the associated register or number to -pass to \\number\\c@page etc). +

    There’s a certain amount of trickery needed to deal with this conflict and the code requires the location to be in a +form that doesn’t embed the counter’s internal register in commands like \value. For example, +suppose you have a robust command called \tallynum that takes a number as the argument and an +expandable command called \tally that converts a counter name into the associated register or +number to pass to \tallynum. Let’s suppose that this command is used to represent the page number: - - + +

    -
    +
    \renewcommand{\thepage}{\tally{page}}
    -

    Now let’s suppose that a term is indexed at the beginning of page 2 at the end of a -paragraph that started on page 1. With

    Now let’s suppose that a term is indexed at the beginning of page 2 at the end of a paragraph that started on +page 1. With xindy, the location \tally{page} needs to be -written to the file as \\tallynum{2}. If it’s written as , the location \tally{page} needs to be written to the file as \\tallynum{2}. If it’s written +as \tallynum{2} then xindy will -interpret \t as the character “t” (which means the location would appear as “tallynum2”). So - will interpret \t as the character “t” (which means the location would appear as +“tallynum2”). So glossaries tries to expand tries to expand \thepage without expanding \c@page and then escapes all the -backslashes, except for the page counter’s internal command. The following definitions of -\tally will work:

    +backslashes, except for the page counter’s internal command. The following definitions of \tally will work: +

    • In the following, \arabic works as its internal command \c@arabic is temporarily - redefined to check for \c@arabic is temporarily redefined to check for + \c@page: - - -
      + + +
      \newcommand{\tally}[1]{\tallynum{\arabic{#1}}}
      -

      +

    • The form \expandafter\the\csname c@counter\endcsname also works (provided \the - is allowed to be temporarily redefined, see below): - - -
      +class="cmtt-10">\the is allowed to be + temporarily redefined, see below): + + +
      \newcommand{\tally}[1]{%  
       \tallynum{\expandafter\the\csname c@#1\endcsname}}
      -

      +

    • \expandafter\the\value{counter} now also works (with the same condition as - above): - - -
      +class="cmtt-10">} now also works (with the same condition as above): + + +
      \newcommand{\tally}[1]{\tallynum{\expandafter\the\value{#1}}}
      -

      +

    • Another variation that will work: - - -
      + + +
      \newcommand{\tally}[1]{%  
        \expandafter\tallynum\expandafter{\the\csname c@#1\endcsname}}
      -

      +

    • and also: - - -
      + + +
      \newcommand{\tally}[1]{\tallynum{\the\csname c@#1\endcsname}}
      -

    -

    The following

    +

    The following don’t work:

    • This definition leads to the premature expansion of \c@page to “1” when, in this case, - it should be “2”: - - -
      +class="cmtt-10">\c@page to “1” when, in this case, it should be + “2”: + + +
      \newcommand{\tally}[1]{\tallynum{\the\value{#1}}}
      -

      +

    • This definition leads to \\c@page in the glossary file: - - -
      + + +
      \newcommand{\tally}[1]{\tallynum{\csname c@#1\endcsname}}
      -

    -

    If you have a numbering system where

    +

    If you have a numbering system where \cs name{page} expands to \internal cs name\c@page -(for example, if \c@page (for example, if +\tally{page} expands to \tallynum\c@page) then you need to -use: -


    \glsaddprotectedpagefmt  \tallynum\c@page) then you need to use: +


    \glsaddprotectedpagefmt{internal cs name} -

    -

    +class="cmtt-10">}


    +

    Note that the backslash must be omitted from ⟨internal cs name⟩ and the corresponding -command must be able to process a count register as the (sole) argument. -

    For example, suppose you have a style internal cs name⟩ and the corresponding command must be able +to process a count register as the (sole) argument. +

    For example, suppose you have a style samplenum that is implemented as follows: - - + +

    -
    +
     \newcommand*{\samplenum}[1]{%  
       \expandafter\@samplenum\csname c@#1\endcsname}  
     \newcommand*{\@samplenum}[1]{\two@digits{#1}}
    -

    (That is, it displays the value of the counter as a two-digit number.) Then to ensure the -location is correct for entries in page-spanning paragraphs, you need to do: - - +

    (That is, it displays the value of the counter as a two-digit number.) Then to ensure the location is correct for +entries in page-spanning paragraphs, you need to do: + +

    -
    +
    \glsaddprotectedpagefmt{@samplenum}
    -

    (If you are using a different counter for the location, such as

    (If you are using a different counter for the location, such as section or equation, you don’t -need to worry about this provided the inner command is expandable.) -

    If the inner macro (as given by equation, you don’t need to worry +about this provided the inner command is expandable.) +

    If the inner macro (as given by \internal cs name⟩) contains non-expandable -commands then you may need to redefine internal cs name⟩) contains non-expandable commands then you may need +to redefine \glsinternal cs namepage after using +class="cmtt-10">page after using

    +
    \glsaddprotectedpagefmt{internal cs name}. This command doesn’t take any arguments as -internal cs name} +
    +
    This command doesn’t take any arguments as the location is assumed to be given by \c@page because that’s the only occasion this -command should be used. For example, suppose now my page counter format uses small caps -Roman numerals: - - -

    -
    +class="cmitt-10">\c@page because that’s +the only occasion this command should be used. For example, suppose now my page counter format uses small +caps Roman numerals: + + +
     \newcommand*{\samplenum}[1]{%  
      \expandafter\@samplenum\csname c@#1\endcsname}  
     \newcommand*{\@samplenum}[1]{\textsc{\romannumeral#1}}
    -

    Again, the inner macro needs to be identified using: - - +

    Again, the inner macro needs to be identified using: + +

    -
    +
    \glsaddprotectedpagefmt{@samplenum}
    -

    However, since \textsc isn’t fully expandable, the location is written to the file as -

    However, since \textsc isn’t fully expandable, the location is written to the file as \textsc  {i} (for page 1),  {i} (for page 1), +\textsc  {ii} (for page 2), etc. This format may cause a -problem for the indexing application (particularly for  {ii} (for page 2), etc. This format may cause a problem for the indexing application +(particularly for makeindex). To compensate for this, -the ). To compensate for this, the \glsinternal cs namepage command may be redefined so that it expands to a format -that’s acceptable to the indexing application. For example: - - +class="cmtt-10">page command +may be redefined so that it expands to a format that’s acceptable to the indexing application. For +example: + +

    -
    +
    \renewcommand*{\gls@samplenumpage}{\romannumeral\c@page}
    -

    While this modification means that the

    While this modification means that the number list in the glossary won’t exactly match the -format of the page numbers (displaying lower case Roman numbers instead of small cap -Roman numerals) this method will at least work correctly for both in the glossary won’t exactly match the format of the page +numbers (displaying lower case Roman numbers instead of small cap Roman numerals) this method +will at least work correctly for both makeindex and and xindy. If -you are using . If you are using xindy, the following definition: - - + id="dx1-129021">, the following +definition: + +

    -
    +
     \renewcommand*{\gls@samplenumpage}{%  
       \glsbackslash\string\textsc{\romannumeral\c@page}}
    -

    combined with - - +

    combined with + +

    -
    +
    \GlsAddXdyLocation{romansc}{:sep "\string\textsc\glsopenbrace"  
     "roman-numbers-lowercase" :sep "\glsclosebrace"}
    -

    will now have lowercase Roman numerals in the location list (see §11.2 Locations and -Number lists for further details on that command). Take care of the backslashes. The location -(which ends up in the :locref attribute) needs \\ but the location class (identified with -\GlsAddXdyLocation) just has a single backslash. Note that this example will cause problems -if your locations should be hyperlinks. -

    Another possibility that may work with both

    will now have lowercase Roman numerals in the location list (see §11.2 Locations and Number lists for +further details on that command). Take care of the backslashes. The location (which ends up in the +:locref attribute) needs \\ but the location class (identified with \GlsAddXdyLocation) just +has a single backslash. Note that this example will cause problems if your locations should be +hyperlinks. +

    Another possibility that may work with both makeindex and and xindy is to redefine - is to redefine \glsinternal cs namepage (\gls@samplenumpage in this example) to just expand to the -decimal page number (\number\c@page) and redefine page +(\gls@samplenumpage in this example) to just expand to the decimal page number (\number\c@page) and +redefine \glsnumberformat to change the -displayed format: - - + id="dx1-129025"> to change the displayed format: + +

    -
    +
    \renewcommand*{\gls@samplenumpage}{\number\c@page}  
    \renewcommand*{\glsnumberformat}[1]{\textsc{\romannumeral#1}}
    -

    -

    If you redefine

    +

    If you redefine \glsinternal cs namepage, you must make sure that \c@page is expanded -when it’s written to the file. (So don’t, for example, hide \c@page inside a robust command.) -
    -

    -

    The mechanism that allows this to work temporarily redefines \c@page is expanded when it’s written +to the file. (So don’t, for example, hide \c@page inside a robust command.)

    +

    +

    The mechanism that allows this to work temporarily redefines \the and and \number while it -processes the location. If this causes a problem you can disallow it using -


    \glswrallowprimitivemodsfalse  while it processes the +location. If this causes a problem you can disallow it using +


    \glswrallowprimitivemodsfalse

    -

    +

    but you will need to find some other way to ensure the location expands correctly. -

    +

    -

    Top

    5.3 Range Formations

    -

    Both

    Both makeindex and and xindy (Options  (Options 2 and 3) concatenate a sequence of 3 or more -consecutive pages into a range. With 3) concatenate a sequence of 3 or more consecutive pages into a +range. With xindy (Option 3) you can vary the minimum sequence -length using (Option 3) you can vary the minimum sequence length using \GlsSetXdyMinRangeLength +{n} where ⟨n⟩ is either an integer or the keyword -none which indicates that there should be no range formation (see §11.2 Locations and -Number lists for further details). -

    Note that n⟩ is either an integer or the keyword none which indicates that there should be no range formation +(see §11.2 Locations and Number lists for further details). +

    Note that \GlsSetXdyMinRangeLength must be used before \makeglossaries and has -no effect if and has no effect if \noist is used.
    -

    -

    With both +is used.

    +

    +

    With both makeindex and and xindy (Options  (Options 2 and 3), you can replace the separator and -the closing number in the range using: -


    \glsSetSuffixF  3), you can replace the separator and the closing number +in the range using: +


    \glsSetSuffixF{suffix}

    -

    -


    \glsSetSuffixFF 

    +


    \glsSetSuffixFF{suffix}

    -

    -where the former command specifies the suffix to use for a 2 page list and the latter specifies -the suffix to use for longer lists. For example: - - +

    +where the former command specifies the suffix to use for a 2 page list and the latter specifies the suffix to use for +longer lists. For example: + +

    -
    +
    \glsSetSuffixF{f.}  
    \glsSetSuffixFF{ff.}
    -

    Note that if you use

    Note that if you use xindy (Option 3), you will also need to set the minimum range length -to 1 if you want to change these suffixes: - - + id="dx1-130011"> (Option 3), you will also need to set the minimum range length to 1 if you want to +change these suffixes: + +

    -
    +
    \GlsSetXdyMinRangeLength{1}
    -

    Note that if you use the

    Note that if you use the hyperref package, you will need to use package, you will need to use \nohyperpage in the suffix to -ensure that the hyperlinks work correctly. For example: - - + id="dx1-130013"> in the suffix to ensure that the +hyperlinks work correctly. For example: + +

    -
    +
    \glsSetSuffixF{\nohyperpage{f.}}  
    \glsSetSuffixFF{\nohyperpage{ff.}}
    -

    -

    Note that

    +

    Note that \glsSetSuffixF and \glsSetSuffixFF must be used before \makeglossaries -and have no effect if and have no +effect if \noist is used.
    -

    -

    It’s also possible to concatenate a sequence of consecutive locations into a range or have -suffixes with is used.

    +

    +

    It’s also possible to concatenate a sequence of consecutive locations into a range or have suffixes with +Option 4, but with bib2gls these implicit ranges can’t be merged with -explicit ranges (created with the ( and these implicit ranges can’t be merged with explicit ranges (created with the ( and +) encaps). See the bib2gls manual for further -details. -

    Option 1 doesn’t form ranges. However, with this option you can iterate over an entry’s - manual for further details. +

    Option 1 doesn’t form ranges. However, with this option you can iterate over an entry’s number list using: -


    \glsnumberlistloop  +using: +


    \glsnumberlistloop{label}{handler cs}{xr handler cs} -

    -

    +class="cmtt-10">}


    +

    where ⟨label⟩ is the entry’s label and ⟨handler cs⟩ is a handler control sequence of the -form: -


    handler cs⟩ is a handler control sequence of the form: +


    handler cs{prefixformat}{location}

    -

    +

    where ⟨prefix⟩ is the hyperref prefix, ⟨counter⟩ is the name of the counter used for the location, -⟨format⟩ is the format used to display the location (e.g.  prefix, ⟨counter⟩ is the name of the counter used for the location, ⟨format⟩ is the +format used to display the location (e.g. textbf) and ⟨location⟩ is the location. -The third argument is the control sequence to use for any cross-references in the list. This -handler should have the syntax: -


    location⟩ is the location. The third argument +is the control sequence to use for any cross-references in the list. This handler should have the +syntax: +


    xr handler cs[tag]{xr list}

    -

    +

    where ⟨tag⟩ is the cross-referenced text (e.g. “see”) and ⟨xr list⟩ is a comma-separated list of -labels. (This actually has a third argument but it’s always empty when used with -xr list⟩ is a comma-separated list of labels. (This actually +has a third argument but it’s always empty when used with Option 1.) -

    For example, if on page 12 I have used - - +

    For example, if on page 12 I have used + +

    -
    +
    \gls[format=textbf]{apple}
    -

    and on page 18 I have used - - +

    and on page 18 I have used + +

    -
    +
    \gls[format=emph]{apple}
    -

    then - - +

    then + +

    -
    +
    \glsnumberlistloop{apple}{\myhandler}
    -

    will be equivalent to: - - +

    will be equivalent to: + +

    -
    +
    \myhandler{}{page}{textbf}{12}%  
    \myhandler{}{page}{emph}{18}%
    -

    There is a predefined handler that’s used to display the

    There is a predefined handler that’s used to display the number list in the glossary: -


    \glsnoidxdisplayloc  in the glossary: +


    \glsnoidxdisplayloc{prefix}{}{format}{location} -

    -

    +class="cmtt-10">}


    +

    The predefined handler used for the cross-references in the glossary is: -



    \glsseeformat[tag]{xr list}{location}

    -

    +

    which is described in §8.1 §8.1 Customising Cross-reference Text. -

    \glsnumberlistloop is not available for Options 2 and 3.
    -

    -

    +

    +

    -

    Top

    5.4 Style Hook

    -

    As from version 4.24, there’s a hook that’s used near the end of

    As from version 4.24, there’s a hook that’s used near the end of \writeist before the file is -closed. You can set the code to be performed then using: -


    \GlsSetWriteIstHook  before the file is closed. You can set +the code to be performed then using: +


    \GlsSetWriteIstHook{code}

    -

    +

    If you want the ⟨code⟩ to write any information to the file, you need to use -


    \glswrite 


    \write\glswrite{style information}

    -

    +

    Make sure you use the correct format within ⟨style information⟩. For example, if you are using -style information⟩. For example, if you are using makeindex: - - + id="dx1-131004">: + +

    -
    +
    \GlsSetWriteIstHook{%  
     \write\glswrite{page_precedence "arnAR"}%  
     \write\glswrite{line_max 80}%  
    }
    -

    This changes the page type precedence and the maximum line length used by -

    This changes the page type precedence and the maximum line length used by makeindex. -

    Remember that if you switch to . +

    Remember that if you switch to xindy, this will no longer be valid code. - - + id="dx1-131007">, this will no longer be valid code. + +

    -

    -

    +

    Top

    6. Links to Glossary Entries

    -

    Once you have defined a glossary entry using

    Once you have defined a glossary entry using \newglossaryentry (§4 Defining -Glossary Entries) or (§4 Defining Glossary Entries) or +\newacronym (see §13 Acronyms and Other Abbreviations), you -can refer to that entry in the document using one of the commands listed in §6.1 - (see §13 Acronyms and Other Abbreviations), you can refer to that entry in the document using +one of the commands listed in §6.1 The \gls-Like Commands (First Use Flag Queried) or §6.2 §6.2 The \glstext-Like -Commands (First Use Flag Not Queried). The text which appears at that point in the -document when using one of these commands is referred to as the . The text which appears at that point in the document when using +one of these commands is referred to as the link text (even if -there are no hyperlinks). These commands also add a line to an external file that is -used to generate the relevant entry in the glossary. This information includes an -associated location that is added to the (even if there are no hyperlinks). These commands also +add a line to an external file that is used to generate the relevant entry in the glossary. This information +includes an associated location that is added to the number list for that entry. By default, the -location refers to the page number. For further information on number lists, see §5 -Number lists. These external files need to be post-processed by for that entry. By default, the location refers to +the page number. For further information on number lists, see §5 Number lists. These external files need to be +post-processed by makeindex or or xindy -unless you have chosen Options  unless you have chosen Options 1 or 4. If you don’t use 4. If you don’t use +\makeglossaries these -external files won’t be created. (Options  these external files won’t be created. (Options 1 and 4 write the information to the .aux +class="cmtt-10">aux file.) -

    Note that repeated use of these commands for the same entry can cause the

    Note that repeated use of these commands for the same entry can cause the number list to -become quite long, which may not be particular helpful to the reader. In this case, -you can use the non-indexing commands described in §9 Using Glossary Terms -Without Links or you can use the supplemental glossaries-extra package, which -provides a means to suppress the automated indexing of the commands listed in this -chapter. -

    I strongly recommend that you don’t use the commands defined in this chapter in the -arguments of sectioning or caption commands or any other command that has a moving -argument. -

    Aside from problems with expansion issues, PDF bookmarks and possible nested -hyperlinks in the table of contents (or list of whatever) any use of the commands + id="dx1-132009"> to become quite +long, which may not be particular helpful to the reader. In this case, you can use the non-indexing commands described in §6.1 §9 Using Glossary Terms Without Links or you can use the supplemental glossaries-extra +package, which provides a means to suppress the automated indexing of the commands listed in this +chapter. +

    I strongly recommend that you don’t use the commands defined in this chapter in the arguments of +sectioning or caption commands or any other command that has a moving argument. +

    Aside from problems with expansion issues, PDF bookmarks and possible nested hyperlinks in the table of +contents (or list of whatever) any use of the commands described in §6.1 The \gls-Like Commands (First Use Flag Queried) will have their -\gls-Like Commands (First Use +Flag Queried) will have their first use flag unset when they appear in the table of contents (or list of whatever).

    -

    -

    The above warning is particularly important if you are using the glossaries package in -conjunction with the

    +

    The above warning is particularly important if you are using the glossaries package in conjunction with the +hyperref package. Instead, use one of the expandable commands listed in -§9 Using Glossary Terms Without Links (such as package. Instead, use one of the expandable commands listed in §9 Using Glossary Terms Without Links +(such as \glsentrytext but not the non-expandable -case changing versions like but not the non-expandable case changing versions like \Glsentrytext). Alternatively, provide an alternative via the -optional argument to the sectioning/caption command or use ). Alternatively, +provide an alternative via the optional argument to the sectioning/caption command or use hyperref’s ’s +\texorpdfstring. -Examples: - - + id="dx1-132014">. Examples: + +

    -
    +
    \chapter{An overview of \glsentrytext{perl}}  
    \chapter[An overview of Perl]{An overview of \gls{perl}}  
    \chapter{An overview of \texorpdfstring{\gls{perl}}{Perl}}
    -

    If you want to retain the formatting that’s available through commands like \acrshort (for -example, if you are using one of the small caps styles), then you might want to consider the -

    If you want to retain the formatting that’s available through commands like \acrshort (for example, if you are +using one of the small caps styles), then you might want to consider the glossaries-extra package which provides commands for this purpose. -

    If you want the glossaries-extra package which provides +commands for this purpose. +

    If you want the link text to produce a hyperlink to the corresponding entry details in the -glossary, you should load the to produce a hyperlink to the corresponding entry details in the glossary, you +should load the hyperref package package before the glossaries package. That’s what I’ve -done in this document, so if you see a hyperlinked term, such as glossaries package. That’s what I’ve done in this document, so if you +see a hyperlinked term, such as link text, you can click on -the word or phrase and it will take you to a brief description in this document’s -glossary. -

    If you use the , you can click on the word or phrase and it will take you to a brief +description in this document’s glossary. +

    If you use the hyperref package, I strongly recommend you use package, I strongly recommend you use pdflatex rather than - rather than latex to compile your document, if possible. The DVI format of LATEX has limitations with -the hyperlinks that can cause a problem when used with the glossaries package. Firstly, the -DVI format can’t break a hyperlink across a line whereas PDFLATEX can. This means that -long glossary entries (for example, the full form of an acronym) won’t be able to break across -a line with the DVI format. Secondly, the DVI format doesn’t correctly size hyperlinks in -subscripts or superscripts. This means that if you define a term that may be used as a -subscript or superscript, if you use the DVI format, it won’t come out the correct + id="dx1-132020"> to compile your +document, if possible. The DVI format of LATEX has limitations with the hyperlinks that can cause a problem +when used with the glossaries package. Firstly, the DVI format can’t break a hyperlink across a line +whereas PDFLATEX can. This means that long glossary entries (for example, the full form of an +acronym) won’t be able to break across a line with the DVI format. Secondly, the DVI format doesn’t +correctly size hyperlinks in subscripts or superscripts. This means that if you define a term that may +be used as a subscript or superscript, if you use the DVI format, it won’t come out the correct size. -

    These are limitations of the DVI format not of the

    These are limitations of the DVI format not of the glossaries package.

    -

    -

    It may be that you only want terms in certain glossaries to have hyperlinks, but not for -other glossaries. In this case, you can use the package option package.

    +

    +

    It may be that you only want terms in certain glossaries to have hyperlinks, but not for other glossaries. In +this case, you can use the package option nohypertypes to identify the -glossary lists that shouldn’t have hyperlinked to identify the glossary lists that shouldn’t have +hyperlinked link text. See §2.1 General Options for further -details. -

    The way the . See §2.1 General Options for further details. +

    The way the link text is displayed depends on -


    \glstextformat  is displayed depends on +


    \glstextformat{text}

    -

    +

    For example, to make all link text appear in a sans-serif font, do: - - + id="dx1-132026"> appear in a sans-serif font, do: + +

    -
    +
    \renewcommand*{\glstextformat}[1]{\textsf{#1}}
    -

    Further customisation can be done via

    Further customisation can be done via \defglsentryfmt or by redefining or by redefining \glsentryfmt. See -§6.3 Changing the format of the link text for further details. -

    Each entry has an associated conditional referred to as the first use flag. Some of the -commands described in this chapter automatically unset this flag and can also use it -to determine what text should be displayed. These types of commands are the -. See §6.3 Changing the +format of the link text for further details. +

    Each entry has an associated conditional referred to as the first use flag. Some of the commands described in +this chapter automatically unset this flag and can also use it to determine what text should be displayed. +These types of commands are the \gls-like commands and are described in §6.1 §6.1 The \gls-Like Commands (First Use -Flag Queried). The commands that don’t reference or change the \gls-Like +Commands (First Use Flag Queried). The commands that don’t reference or change the first use flag are \glstext-like commands and are described in §6.2 §6.2 The \glstext-Like Commands (First Use -Flag Not Queried). See §14 Unsetting and Resetting Entry Flags for commands that unset -(mark the entry as having been used) or reset (mark the entry as not used) the first use -flag without referencing the entries. -

    The \glstext-Like Commands (First Use Flag Not +Queried). See §14 Unsetting and Resetting Entry Flags for commands that unset (mark the entry as +having been used) or reset (mark the entry as not used) the first use flag without referencing the +entries. +

    The \gls-like and \glstext-like commands all take a first optional argument that is a -comma-separated list of ⟨\glstext-like commands all take a first optional argument that is a comma-separated +list of ⟨key⟩=⟨value⟩ options, described below. They also have a star-variant, -which inserts hyper=false at the start of the list of options and a plus-variant, which -inserts hyper=true at the start of the list of options. For example \gls*{sample} -is the same as value⟩ options, described below. They also have a star-variant, which inserts hyper=false at the +start of the list of options and a plus-variant, which inserts hyper=true at the start of the list of options. For +example \gls*{sample} is the same as \gls[hyper=false]{sample} and \gls+{sample} is the same as \gls[hyper=true]{sample}, whereas just \gls{sample} will use the default hyperlink -setting which depends on a number of factors (such as whether the entry is in a glossary that -has been identified in the \gls{sample} will use the default hyperlink setting which depends +on a number of factors (such as whether the entry is in a glossary that has been identified in the +nohypertypes list). You can override the hyper key in the variant’s -optional argument, for example, \gls*[hyper=true]{sample} but this creates redundancy -and is best avoided. The glossaries-extra package provides the option to add a third custom -variant. -

    Avoid nesting these commands. For example don’t do list). You can override the hyper key in the variant’s optional argument, for example, +\gls*[hyper=true]{sample} but this creates redundancy and is best avoided. The glossaries-extra package +provides the option to add a third custom variant. +

    Avoid nesting these commands. For example don’t do \glslink{label}{\gls -{\gls{label2}} as this is likely to cause problems. By implication, this means that -you should avoid using any of these commands within the text, first, short or long -keys (or their plural equivalent) or any other key that you plan to access through -these commands. (For example, the symbol key if you intend to use } as this is likely to +cause problems. By implication, this means that you should avoid using any of these commands within the +text, first, short or long keys (or their plural equivalent) or any other key that you plan to +access through these commands. (For example, the symbol key if you intend to use \glssymbol.)
    -

    -

    The keys listed below are available for the optional argument. The

    +

    The keys listed below are available for the optional argument. The glossaries-extra package -provides additional keys. (See the glossaries-extra package provides +additional keys. (See the glossaries-extra manual for further details.)

    hyper
    This is a boolean key which can be used to enable/disable the hyperlink - to the relevant entry in the glossary. If this key is omitted, the value is - determined by current settings, as indicated above. For example, when used with - a hyper
    This is a boolean key which can be used to enable/disable the hyperlink to the relevant entry in + the glossary. If this key is omitted, the value is determined by current settings, as indicated above. + For example, when used with a \gls-like command, if this is the first use and the hyperfirst=false package - option has been used, then the default value is hyper=false. The hyperlink - can be forced on using hyper=true unless the hyperlinks have been suppressed - using \gls-like command, if this is the first use and the hyperfirst=false + package option has been used, then the default value is hyper=false. The hyperlink can be forced + on using hyper=true unless the hyperlinks have been suppressed using \glsdisablehyper. You must load the . You + must load the hyperref package before the package before the glossaries - package to ensure the hyperlinks work. - - + id="dx1-132040"> package to ensure the hyperlinks work.
    format
    This specifies how to format the associated location number for this entry in the - glossary. This value is equivalent to the format
    This specifies how to format the associated location number for this entry in the glossary. This value is + equivalent to the makeindex encap value, and (as with - encap value, and (as with \index) the value needs to be the name of a command without the initial - backslash. As with ) the value needs to be the name of a + command without the initial backslash. As with \index, the characters , the characters ( and ) can also be used to specify the - beginning and ending of a number range and they must be in matching pairs. (For - example, \gls[format={(}]{sample} on one page to start the range and later +class="cmtt-10">) can also be used to specify + the beginning and ending of a number range and they must be in matching pairs. (For example, + + \gls[format={)}]{sample} to close the range.) Again as with \gls[format={(}]{sample} on one page to start the range and later \gls[format={)}]{sample} to + close the range.) Again as with \index, the command - should be the name of a command which takes an argument (which will be the - associated location). Be careful not to use a declaration (such as bfseries) instead of a - text block command (such as textbf) as the effect is not guaranteed to be - localised. If you want to apply more than one style to a given entry (e.g. bold - and , the command should be the name of a command + which takes an argument (which will be the associated location). Be careful not to use a + declaration (such as bfseries) instead of a text block command (such as textbf) as the + effect is not guaranteed to be localised. If you want to apply more than one style to a given + entry (e.g. bold and italic) you will need to create a command that applies both formats, e.g.  - - -
    + + +
    \newcommand*{\textbfem}[1]{\textbf{\emph{#1}}}
    -

    and use that command. -

    In this document, the standard formats refer to the standard text block commands such - as

    and use that command. +

    In this document, the standard formats refer to the standard text block commands such as \textbf or or + \emph or any of the commands listed in table 6.1. You can combine - a range and format using or any of the commands listed in table 6.1. You can combine a range and format using (format⟩ to start the range and format⟩ to + start the range and )format⟩ to end - the range. The ⟨format⟩ part must match. For example, format={(emph} and +class="cmti-10">format⟩ to end the range. The ⟨format⟩ part must match. For example, format={(emph} and format={)emph}. -

    If you use

    If you use xindy instead of instead of makeindex, you must specify any non-standard - formats that you want to use with the format key using , you must specify any non-standard formats that you want to use + with the format key using \GlsAddXdyAttribute - {name}. So if you use xindy with the above example, you would need to - add: - - + id="dx1-132052"> with the above example, + you would need to add: + +

    -
    +
    \GlsAddXdyAttribute{textbfem}
    -

    See §11

    See §11 Xindy (Option 3) for further details.

    -

    -

    If you are using hyperlinks and you want to change the font of the hyperlinked location, - don’t use

    +

    If you are using hyperlinks and you want to change the font of the hyperlinked location, don’t use + \hyperpage (provided by the (provided by the hyperref package) as the locations may not refer - to a page number. Instead, the glossaries package provides number formats listed in - table 6.1. + id="dx1-132054"> package) as the locations may not refer to a page number. Instead, + the glossaries package provides number formats listed in table 6.1. These commands are designed to work + with the particular location formats created by makeindex and xindy and shouldn’t be used in other + contexts.

    -


    Table 6.1: Predefined Hyperlinked Location Formats
    +class="content">Predefined Hyperlinked Location Formats
    hyperrm serif hyperlink
    hypersf sans-serif hyperlink
    hypertt monospaced hyperlink
    hyperbf bold hyperlink
    hypermd medium weight hyperlink
    hyperit italic hyperlink
    hypersl slanted hyperlink
    hyperup upright hyperlink
    hypersc small caps hyperlink
    hyperemph emphasized hyperlink

    -

    Note that if the

    Note that if the \hyperlink command hasn’t been defined, the command hasn’t been defined, the hyperxx⟩ formats are - equivalent to the analogous xx⟩ formats are equivalent to the + analogous textxx⟩ font commands (and hyperemph is equivalent to - emph). If you want to make a new format, you will need to define a command - which takes one argument and use that. For example, if you want the location - number to be in a bold sans-serif font, you can define a command called, say, +class="cmtt-10">hyperemph is equivalent to emph). If you want to make a new + format, you will need to define a command which takes one argument and use that. For example, if you + want the location number to be in a bold sans-serif font, you can define a command called, say, \hyperbsf: - - + id="dx1-132069">: + +

    -
    +
    \newcommand{\hyperbsf}[1]{\textbf{\hypersf{#1}}}
    -

    and then use

    and then use hyperbsf as the value for the format +class="cmtt-10">format key.6.1 - Remember that if you use +

    When defining a custom location format command that uses one of the \hyperxx commands, make sure + that the argument of \hyperxx is just the location. Any formatting must be outside of \hyperxx (as in + the above \hyperbfsf example).
    +

    +

    Remember that if you use xindy, you will need to add this to the list of location - attributes: - - + id="dx1-132075">, you will need to add this to the list of location attributes: + +

    -
    +
    \GlsAddXdyAttribute{hyperbsf}
    -

    +

    counter
    This specifies which counter to use for this location. This overrides the default - counter used by this entry. (See also §5 counter
    This specifies which counter to use for this location. This overrides the default counter used by this + entry. (See also §5 Number lists.)
    local
    local
    This is a boolean key that only makes a difference when used with \gls-like commands - that change the entry’s \gls-like commands that change the + entry’s first use flag. If local=true, the change to the first use flag will - be localised to the current scope. The default is local=true, the change to the first use flag will be localised to the current scope. + The default is local=false. +
    +noindex
    This is a boolean key that suppresses the indexing. Only available with glossaries-extra. +
    +hyperoutside
    This is a boolean key that determines whether to put the hyperlink outside of \glstextformat. + Only available with glossaries-extra. +
    +wrgloss
    This key determines whether to index before (wrgloss=before) or after (wrgloss=after) the link + text. Only available with glossaries-extra. +
    +textformat
    This key identifies the name of the control sequence to encapsulate the link text instead of the + default \glstextformat. Only available with glossaries-extra. +
    +prefix
    This key locally redefines \glolinkprefix to the given value. Only available with glossaries-extra. +
    +thevalue
    This key explicitly sets the location. Only available with glossaries-extra. +
    +theHvalue
    This key explicitly sets the hyperlink location. Only available with glossaries-extra.
    -

    The

    The link text isn’t scoped by default. Any unscoped declarations in the isn’t scoped by default with just the base glossaries package. Any unscoped declarations in the +link text may -affect subsequent text.
    -

    + id="dx1-132092"> may affect subsequent text.

    +

    -

    Top

    6.1 The \gls-Like Commands (First Use Flag Queried)

    -

    This section describes the commands that unset (mark as used) the first use flag on -completion, and in most cases they use the current state of the flag to determine the text to -be displayed. As described above, these commands all have a star-variant (hyper=false) and -a plus-variant (hyper=true) and have an optional first argument that is a ⟨

    This section describes the commands that unset (mark as used) the first use flag on completion, and in most +cases they use the current state of the flag to determine the text to be displayed. As described above, these +commands all have a star-variant (hyper=false) and a plus-variant (hyper=true) and have an optional first +argument that is a ⟨key⟩=⟨value⟩ -list. -

    These commands use value⟩ list. These commands use \glsentryfmt or the equivalent definition provided by + id="dx1-133001"> or the equivalent definition provided by \defglsentryfmt to determine the automatically generated text and its format (see §6.3 -Changing the format of the link text). -

    Apart from to determine the automatically generated text and its format (see §6.3 Changing the format of +the link text). +

    Apart from \glsdisp, the commands described in this section also have a final optional -argument ⟨insert⟩ which may be used to insert material into the automatically generated -text. -

    Since the commands have a final optional argument, take care if you actually want to -display an open square bracket after the command when the final optional argument is -absent. Insert an empty set of braces {} immediately before the opening square bracket to -prevent it from being interpreted as the final argument. For example: - - -

    -
    + id="dx1-133003">, the commands described in this section also have a final optional argument ⟨insert⟩ +which may be used to insert material into the automatically generated text. +

    Since the commands have a final optional argument, take care if you actually want to display an open +square bracket after the command when the final optional argument is absent. Insert an empty set of braces {} +immediately before the opening square bracket to prevent it from being interpreted as the final argument. For +example: + + +

    +
    \gls{sample} {}[Editor's comment]
    -

    -

    Don’t use any of the

    +

    Don’t use any of the \gls-like or \glstext-like commands in the ⟨insert⟩ argument. -

    -

    -

    Take care using these commands within commands or environments that are processed -multiple times as this can confuse the first use flag query and state change. This includes -frames with overlays in insert⟩ argument.

    +

    +

    Take care using these commands within commands or environments that are processed multiple times as this +can confuse the first use flag query and state change. This includes frames with overlays in beamer and the and the +tabularx environment provided by tabularx. The + id="dx1-133005">. The glossaries package automatically deals with this issue in glossaries package automatically deals with this issue in amsmath’s align environment. You can -apply a patch to ’s align environment. You can apply a patch to tabularx by placing the following command (new to v4.28) in the -preamble: -


    \glspatchtabularx  by placing the following command (new to +v4.28) in the preamble: +


    \glspatchtabularx

    -

    +

    This does nothing if tabularx hasn’t been loaded. There’s no patch available for hasn’t been loaded. There’s no patch available for beamer. See -§14 Unsetting and Resetting Entry Flags for more details. -


    \gls  . See §14 Unsetting and +Resetting Entry Flags for more details. +


    \gls[options]{label}[insert]

    -

    +

    This command typically determines the link text from the values of the text or first keys -supplied when the entry was defined using from the values of the text or first keys supplied when the +entry was defined using \newglossaryentry. However, if the entry was -defined using . However, if the entry was defined using \newacronym and and +\setacronymstyle was used, then the link text will usually -be determined from the long or short keys. -

    There are two upper case variants: -


    \Gls  was used, then the link text will usually be determined from the long or short +keys. +

    There are two upper case variants: +


    \Gls[options]{label}[insert]

    -

    +

    and -


    \GLS 


    \GLS[options]{label}[insert]

    -

    -which make the first letter of the link text or all the link text upper case, respectively. For the -former, the uppercasing of the first letter is performed by

    +which make the first letter of the link text or all the link text upper case, respectively. For the former, the +uppercasing of the first letter is performed by \makefirstuc. -

    The first letter uppercasing command \makefirstuc has limitations which must be taken -into account if you use \Gls or any of the other commands that convert the first letter to -uppercase.
    -

    + id="dx1-133023">. +

    The first letter uppercasing command \makefirstuc has limitations which must be taken into +account if you use \Gls or any of the other commands that convert the first letter to uppercase. +
    +

    The upper casing is performed as follows:

    • If the first thing in the link text is a command follow by a group, the upper casing is - performed on the first object of the group. For example, if an entry has been defined - as - - -
      + id="dx1-133024"> is a command follow by a group, the upper casing is performed on the + first object of the group. For example, if an entry has been defined as + + +
      \newglossaryentry{sample}{  
       name={\emph{sample} phrase},  
       sort={sample phrase},  
       description={an example}}
      -

      Then

      Then \Gls{sample} will set the link text - to to6.2 - - + id="x1-133026f2"> + +

      -
      +
      \emph{\MakeUppercase sample} phrase
      -

      which will appear as

      which will appear as Sample phrase.

    • If the first thing in the link text isn’t a command or is a command but isn’t followed by - a group, then the upper casing will be performed on that first thing. For example, if an - entry has been defined as: - - -
      + id="dx1-133027"> isn’t a command or is a command but isn’t followed by a group, then the + upper casing will be performed on that first thing. For example, if an entry has been defined + as: + + +
      \newglossaryentry{sample}{  
        name={\oe-ligature},  
        sort={oe-ligature},  
        description={an example}  
      }
      -

      Then

      Then \Gls{sample} will set the link text to - - + id="dx1-133028"> to + +

      -
      +
      \MakeUppercase \oe-ligature
      -

      which will appear as Œ-ligature. +

      which will appear as Œ-ligature.

    • If you have mfirstuc v2.01 or above, an extra case is added. If the first thing is \protect - it will be discarded and the above rules will then be tried. + id="dx1-133029"> v2.01 or above, an extra case is added. If the first thing is \protect it will be + discarded and the above rules will then be tried.
    -

    (Note the use of the sort key in the above examples.) -

    There are hundreds of LATEX packages that altogether define thousands of commands -with various syntax and it’s impossible for

    (Note the use of the sort key in the above examples.) +

    There are hundreds of LATEX packages that altogether define thousands of commands with +various syntax and it’s impossible for mfirstuc to take them all into account. The above -rules are quite simplistic and are designed for to take them all into account. The above rules are +quite simplistic and are designed for link text that starts with a text-block -command (such as that starts with a text-block command (such as +\emph) or a command that produces a character (such as \oe). This means -that if your \oe). This means that if your link text starts with something that doesn’t adhere to +starts with something that doesn’t adhere to mfirstuc’s assumptions then -things are likely to go wrong. -

    For example, starting with a math-shift symbol: - - + id="dx1-133034">’s assumptions then things are likely to go +wrong. +

    For example, starting with a math-shift symbol: + +

    -
    +
    \newglossaryentry{sample}{  
      name={$a$},  
      sort={a},  
      description={an example}  
    }
    -

    This falls into case 2 above, so the

    This falls into case 2 above, so the link text will be set to - - + id="dx1-133035"> will be set to + +

    -
    +
    \MakeUppercase $a$
    -

    This attempts to uppercase the math-shift $, which will go wrong. In this case it’s not -appropriate to perform any case-changing, but it may be that you want to use \Gls -programmatically without checking if the text contains any maths. In this case, the simplest -solution is to insert an empty brace at the start: - - +

    This attempts to uppercase the math-shift $, which will go wrong. In this case it’s not appropriate to perform +any case-changing, but it may be that you want to use \Gls programmatically without checking if +the text contains any maths. In this case, the simplest solution is to insert an empty brace at the +start: + +

    -
    +
    \newglossaryentry{sample}{  
      name={{}$a$},  
      sort={a},  
      description={an example}  
    }
    -

    Now the

    Now the link text will be set to - - + id="dx1-133036"> will be set to + +

    -
    +
    \MakeUppercase{}$a$
    -

    and the

    and the \uppercase becomes harmless. -

    Another issue occurs when the

    Another issue occurs when the link text starts with a command followed by an argument -(case 1) but the argument is a label, identifier or something else that shouldn’t have a -case-change. A common example is when the starts with a command followed by an argument (case 1) but the +argument is a label, identifier or something else that shouldn’t have a case-change. A common example is when +the link text starts with one of the commands -described in this chapter. (But you haven’t done that, have you? What with the warning not -to do it at the beginning of the chapter.) Or when the starts with one of the commands described in this chapter. (But you haven’t done that, have you? +What with the warning not to do it at the beginning of the chapter.) Or when the link text starts with one of the -non-linking commands described in §9 starts +with one of the non-linking commands described in §9 Using Glossary Terms Without Links. For example: - - + +

    -
    +
    \newglossaryentry{sample}{name={sample},description={an example}}  
    \newglossaryentry{sample2}{  
       name={\glsentrytext{sample} two}, @@ -13732,33 +16015,31 @@ example:  
       description={another example}  
     }
    -

    Now the

    Now the link text will be set to: - - + id="dx1-133040"> will be set to: + +

    -
    +
    \glsentrytext{\MakeUppercase sample} two
    -

    This will generate an error because there’s no entry with the label given by -\MakeUppercase sample. The best solution here is to write the term out in the text field and -use the command in the name field. If you don’t use \glsname anywhere in your document, -you can use

    This will generate an error because there’s no entry with the label “\MakeUppercase sample”. The best +solution here is to write the term out in the text field and use the command in the name field. If you don’t use +\glsname anywhere in your document, you can use \gls in the name field: - - +class="cmtt-10">name field: + +

    -
    +
    \newglossaryentry{sample}{name={sample},description={an example}}  
    \newglossaryentry{sample2}{  
       name={\gls{sample} two}, @@ -13767,68 +16048,64 @@ class="cmss-10">name   description={another example}  
     }
    -

    -

    If the

    +

    If the link text starts with a command that has an optional argument or with multiple -arguments where the actual text isn’t in the first argument, then \makefirstuc will also fail. -For example: - - + id="dx1-133044"> starts with a command that has an optional argument or with multiple arguments where the +actual text isn’t in the first argument, then \makefirstuc will also fail. For example: + +

    -
    +
    \newglossaryentry{sample}{  
     name={\textcolor{blue}{sample} phrase},  
     sort={sample phrase},  
     description={an example}}
    -

    Now the

    Now the link text will be set to: - - + id="dx1-133045"> will be set to: + +

    -
    +
    \textcolor{\MakeUppercase blue}{sample} phrase
    -

    This won’t work because

    This won’t work because \MakeUppercase blue isn’t a recognised colour name. In this case -you will have to define a helper command where the first argument is the text. For -example: - - +class="cmtt-10"> blue isn’t a recognised colour name. In this case you will have to +define a helper command where the first argument is the text. For example: + +

    -
    +
    \newglossaryentry{sample}{  
    \newcommand*{\blue}[1]{\textcolor{blue}{#1}}  
     name={\blue{sample} phrase},  
     sort={sample phrase},  
     description={an example}}
    -

    In fact, since the whole design ethos of LATEX is the separation of content and style, it’s -better to use a semantic command. For example: - - +

    In fact, since the whole design ethos of LATEX is the separation of content and style, it’s better to use a +semantic command. For example: + +

    -
    +
    \newglossaryentry{sample}{  
    \newcommand*{\keyword}[1]{\textcolor{blue}{#1}}  
     name={\keyword{sample} phrase},  
     sort={sample phrase},  
     description={an example}}
    -

    For further details see the

    For further details see the mfirstuc user manual. -

    There are plural forms that are analogous to user manual. +

    There are plural forms that are analogous to \gls: -


    \glspl 


    \glspl[options]{label}[insert]

    -

    -


    \Glspl 

    +


    \Glspl[options]{label}[insert]

    -

    -


    \GLSpl 

    +


    \GLSpl[options]{label}[insert]

    -

    +

    These typically determine the link text from the plural or firstplural keys supplied when the -entry was defined using plural or firstplural keys supplied when the entry was +defined using \newglossaryentry or, if the entry is an abbreviation and -\setacronymstyle was used, from the longplural or shortplural keys. -

    Be careful when you use glossary entries in math mode especially if you are using or, if the entry is an abbreviation and \setacronymstyle was used, from the +longplural or shortplural keys. +

    Be careful when you use glossary entries in math mode especially if you are using hyperref -as it can affect the spacing of subscripts and superscripts. For example, suppose you have -defined the following entry: - - + id="dx1-133055"> as it can affect +the spacing of subscripts and superscripts. For example, suppose you have defined the following +entry: + +

    -
    +
    \newglossaryentry{Falpha}{name={F_\alpha},  
    description=sample}
    -

    and later you use it in math mode: - - +

    and later you use it in math mode: + +

    -
    +
    $\gls{Falpha}^2$
    -

    This will result in

    This will result in Fα2 instead of Fα2. In this situation it’s best to bring the superscript into -the hyperlink using the final ⟨2. In this situation it’s best to bring the superscript into the hyperlink +using the final ⟨insert⟩ optional argument: - - + +

    -
    +
    $\gls{Falpha}[^2]$
    -

    -

    -


    \glsdisp 

    +

    +


    \glsdisp[options]{label}{link text}

    -

    +

    This behaves in the same way as the above commands, except that the ⟨link text⟩ is explicitly -set. There’s no final optional argument as any inserted material can be added to the ⟨link text⟩ -argument. -

    Don’t use any of the link text⟩ is explicitly set. There’s no final +optional argument as any inserted material can be added to the ⟨link text⟩ argument. +

    Don’t use any of the \gls-like or \glstext-like commands in the ⟨link text⟩ argument of -\glsdisp.
    -

    -

    +class="cmti-10">link text⟩ argument of \glsdisp. +

    +

    +

    -

    Top

    6.2 The \glstext-Like Commands (First Use Flag Not Queried)

    -

    This section describes the commands that don’t change or reference the first use flag. -As described above, these commands all have a star-variant (hyper=false) and a -plus-variant (hyper=true) and have an optional first argument that is a ⟨

    This section describes the commands that don’t change or reference the first use flag. As described above, these +commands all have a star-variant (hyper=false) and a plus-variant (hyper=true) and have an optional first +argument that is a ⟨key⟩=⟨value⟩ -list. These commands also don’t use value⟩ list. These commands also don’t use \glsentryfmt or the equivalent definition + id="dx1-134001"> or the equivalent definition provided by \defglsentryfmt (see §6.3 Changing the format of the link text). -Additional commands for abbreviations are described in §13 Acronyms and Other -Abbreviations. -

    Apart from (see §6.3 Changing the format of the link text). Additional commands for +abbreviations are described in §13 Acronyms and Other Abbreviations. +

    Apart from \glslink, the commands described in this section also have a final -optional argument ⟨insert⟩ which may be used to insert material into the automatically -generated text. See the caveat above in §6.1 The \gls-Like Commands (First Use Flag -Queried). -


    \glslink  , the commands described in this section also have a final optional argument ⟨insert⟩ +which may be used to insert material into the automatically generated text. See the caveat above in §6.1 The +\gls-Like Commands (First Use Flag Queried). +


    \glslink[options]{label}{link text}

    -

    +

    This command explicitly sets the link text as given in the final argument. -

    Don’t use any of the as given in the final argument. +

    Don’t use any of the \gls-like or \glstext-like commands in the argument of -\glslink. By extension, this means that you can’t use them in the value of fields that are -used to form \glstext-like commands in the argument of \glslink. By +extension, this means that you can’t use them in the value of fields that are used to form link text.
    -

    -


    \glstext  . +
    +

    +


    \glstext[options]{label}[insert]

    -

    +

    This command always uses the value of the text key as the text key as the link text. - - -

    There are also analogous commands: -


    \Glstext  . +

    There are also analogous commands: +


    \Glstext[options]{text}[insert]

    -

    -


    \GLStext 

    + + +


    \GLStext[options]{text}[insert]

    -

    -These convert the first character or all the characters to uppercase, respectively. See the note -on \Gls above for details on the limitations of converting the first letter to upper -case. -

    There’s no equivalent command for title-casing, but you can use the more generic -command

    +These convert the first character or all the characters to uppercase, respectively. See the note on \Gls above for +details on the limitations of converting the first letter to upper case. +

    There’s no equivalent command for title-casing, but you can use the more generic command +\glsentrytitlecase in combination with in combination with \glslink. For example: - - + +

    -
    +
    \glslink{sample}{\glsentrytitlecase{sample}{text}}
    -

    (See §9

    (See §9 Using Glossary Terms Without Links.) -


    \glsfirst 


    \glsfirst[options]{label}[insert]

    -

    +

    This command always uses the value of the first key as the first key as the link text. -

    There are also analogous uppercasing commands: -


    \Glsfirst  . +

    There are also analogous uppercasing commands: +


    \Glsfirst[options]{text}[insert]

    -

    -


    \GLSfirst 

    +


    \GLSfirst[options]{text}[insert]

    -

    -

    The value of the first key (and firstplural key) doesn’t necessarily match the text produced -by

    +

    The value of the first key (and firstplural key) doesn’t necessarily match the text produced by \gls (or (or +\glspl) on ) on first use as the link text used by used by \gls may be modified -through commands like may be modified through commands like \defglsentry. (Similarly, the value of the text and plural keys -don’t necessarily match the link text used by . +(Similarly, the value of the text and plural keys don’t necessarily match the link text used by \gls or \glspl on subsequent use.) -
    -

    -


    \glsplural  \glspl +on subsequent use.)
    +

    +


    \glsplural[options]{label}[insert]

    -

    +

    This command always uses the value of the plural key as the plural key as the link text. -

    There are also analogous uppercasing commands: -


    \Glsplural  . +

    There are also analogous uppercasing commands: +


    \Glsplural[options]{text}[insert]

    -

    -


    \GLSplural 

    +


    \GLSplural[options]{text}[insert]

    -

    -


    \glsfirstplural 

    +


    \glsfirstplural[options]{label}[insert]

    -

    +

    This command always uses the value of the firstplural key as the firstplural key as the link text. -

    There are also analogous uppercasing commands: -


    \Glsfirstplural  . +

    There are also analogous uppercasing commands: +


    \Glsfirstplural[options]{text}[insert]

    -

    -


    \GLSfirstplural 

    +


    \GLSfirstplural[options]{text}[insert]

    -

    -


    \glsname 

    +


    \glsname[options]{label}[insert]

    - - -

    +

    This command always uses the value of the name key as the name key as the link text. Note that this may be -different from the values of the text or first keys. In general it’s better to use \glstext or -\glsfirst instead of . Note that this may be different from the + + +values of the text or first keys. In general it’s better to use \glstext or \glsfirst instead of +\glsname. -

    There are also analogous uppercasing commands: -


    \Glsname 

    There are also analogous uppercasing commands: +


    \Glsname[options]{text}[insert]

    -

    -


    \GLSname 

    +


    \GLSname[options]{text}[insert]

    -

    -

    In general it’s best to avoid

    +

    In general it’s best to avoid \Glsname with acronyms. Instead, consider using \Acrlong, +class="cmtt-10">\Acrlong, \Acrshort or \Acrshort or \Acrfull.
    -

    -


    \glssymbol 

    +


    \glssymbol[options]{label}[insert]

    -

    +

    This command always uses the value of the symbol key as the symbol key as the link text. -

    There are also analogous uppercasing commands: -


    \Glssymbol  . +

    There are also analogous uppercasing commands: +


    \Glssymbol[options]{text}[insert]

    -

    -


    \GLSsymbol 

    +


    \GLSsymbol[options]{text}[insert]

    -

    -


    \glsdesc 

    +


    \glsdesc[options]{label}[insert]

    -

    +

    This command always uses the value of the description key as the description key as the link text. -

    There are also analogous uppercasing commands: -


    \Glsdesc  . +

    There are also analogous uppercasing commands: +


    \Glsdesc[options]{text}[insert]

    -

    -


    \GLSdesc 

    +


    \GLSdesc[options]{text}[insert]

    -

    -

    If you want the title case version you can use - - +

    +

    If you want the title case version you can use + +

    -
    +
    \glslink{sample}{\glsentrytitlecase{sample}{desc}}
    -

    -


    \glsuseri 

    +


    \glsuseri[options]{label}[insert]

    -

    +

    This command always uses the value of the user1 key as the user1 key as the link text. -

    There are also analogous uppercasing commands: -


    \Glsuseri  . +

    There are also analogous uppercasing commands: +


    \Glsuseri[options]{text}[insert]

    -

    -


    \GLSuseri 

    +


    \GLSuseri[options]{text}[insert]

    -

    -


    \glsuserii 

    +


    \glsuserii[options]{text}[insert]

    -

    +

    This command always uses the value of the user2 key as the user2 key as the link text. -

    There are also analogous uppercasing commands: -


    \Glsuserii  . +

    There are also analogous uppercasing commands: +


    \Glsuserii[options]{text}[insert]

    -

    -


    \GLSuserii 

    +


    \GLSuserii[options]{text}[insert]

    -

    -


    \glsuseriii 

    +


    \glsuseriii[options]{text}[insert]

    -

    +

    This command always uses the value of the user3 key as the user3 key as the link text. -

    There are also analogous uppercasing commands: -


    \Glsuseriii  . +

    There are also analogous uppercasing commands: +


    \Glsuseriii[options]{text}[insert]

    -

    -


    \GLSuseriii 

    +


    \GLSuseriii[options]{text}[insert]

    -

    -


    \glsuseriv 

    +


    \glsuseriv[options]{text}[insert]

    -

    +

    This command always uses the value of the user4 key as the user4 key as the link text. -

    There are also analogous uppercasing commands: -


    \Glsuseriv  . +

    There are also analogous uppercasing commands: +


    \Glsuseriv[options]{text}[insert]

    -

    -


    \GLSuseriv 

    +


    \GLSuseriv[options]{text}[insert]

    - - -

    -


    \glsuserv 

    +


    \glsuserv[options]{text}[insert]

    -

    +

    This command always uses the value of the user5 key as the user5 key as the link text. -

    There are also analogous uppercasing commands: -


    \Glsuserv  . +

    There are also analogous uppercasing commands: +


    \Glsuserv[options]{text}[insert]

    -

    -


    \GLSuserv 

    +


    \GLSuserv[options]{text}[insert]

    -

    -


    \glsuservi 

    +


    \glsuservi[options]{text}[insert]

    -

    +

    This command always uses the value of the user6 key as the user6 key as the link text. -

    There are also analogous uppercasing commands: -


    \Glsuservi  . +

    There are also analogous uppercasing commands: +


    \Glsuservi[options]{text}[insert]

    -

    -


    \GLSuservi 

    +


    \GLSuservi[options]{text}[insert]

    -

    -

    +

    +

    -

    Top

    6.3 Changing the format of the link text

    -

    The default format of the

    The glossaries-extra package provides ways of altering the format according to the category. See the +glossaries-extra manual for further details.
    +

    +

    The default format of the link text for the for the \gls-like commands is governed by6.3: -


    \glsentryfmt  : +


    \glsentryfmt

    -

    -This may be redefined but if you only want the change the display style for a given glossary, -then you need to use -


    \defglsentryfmt 

    +This may be redefined but if you only want the change the display style for a given glossary, then you need to +use +


    \defglsentryfmt[type]{definition}

    -

    +

    instead of redefining \glsentryfmt. The optional first argument ⟨type⟩ is the glossary type. -This defaults to type⟩ is the glossary type. This defaults to +\glsdefaulttype if omitted. The second argument is the entry format -definition. -

    Note that \glsentryfmt is the default display format for entries. Once the display format -has been changed for an individual glossary using if omitted. The second argument is the entry format definition. +

    Note that \glsentryfmt is the default display format for entries. Once the display format has been +changed for an individual glossary using \defglsentryfmt, redefining -\glsentryfmt won’t have an effect on that glossary, you must instead use \defglsentryfmt -again. Note that glossaries that have been identified as lists of acronyms (via the package -option , redefining \glsentryfmt won’t have an +effect on that glossary, you must instead use \defglsentryfmt again. Note that glossaries that +have been identified as lists of acronyms (via the package option acronymlists or the command or the command + + +\DeclareAcronymList, see §2.5 Acronym Options) use -\defglsentryfmt to set their display style.
    - - -

    -

    Within the ⟨, see §2.7 Acronym and Abbreviation Options) use \defglsentryfmt to set their display +style.

    +

    +

    Within the ⟨definition⟩ argument of \defglsentryfmt, or if you want to redefine -\glsentryfmt, you may use the following commands: -


    \glslabel  \defglsentryfmt, or if you want to redefine \glsentryfmt, you may use +the following commands: +


    \glslabel

    -

    -This is the label of the entry being referenced. As from version 4.08, you can also access the -glossary entry type using: -


    \glstype 

    +This is the label of the entry being referenced. As from version 4.08, you can also access the glossary entry type +using: +


    \glstype

    -

    +

    This is defined using \edef so the replacement text is the actual glossary type rather than + id="dx1-135014"> so the replacement text is the actual glossary type rather than \glsentrytype{\glslabel}. -


    \glscustomtext 


    \glscustomtext

    -

    +

    This is the custom text supplied in \glsdisp. It’s always empty for \gls, , \glspl and their -upper case variants. (You can use and their upper case variants. +(You can use etoolbox’s ’s \ifdefempty to determine if \glscustomtext is -empty.) -


    \glsinsert  \glscustomtext is empty.) +


    \glsinsert

    -

    +

    The custom text supplied in the final optional argument to \gls, \glspl and their upper case variants. -


    \glsifplural 


    \glsifplural{true text}{false text}

    -

    +

    If \glspl, \Glspl or \GLSpl was used, this command does ⟨true text⟩ otherwise it does ⟨false -text⟩. -


    \glscapscase  false text⟩. +


    \glscapscase{no case}{first uc}{all caps}

    -

    +

    If \gls, \glspl or \glsdisp were used, this does ⟨no case⟩. If \Gls or \Glspl were used, this -does ⟨first uc⟩. If \Glspl were used, this does ⟨first uc⟩. If +\GLS or \GLSpl were used, this does ⟨all caps⟩. -


    \glsifhyperon 


    \glsifhyperon{hyper true}{hyper false}

    -

    +

    This will do ⟨hyper true⟩ if the hyperlinks are on for the current reference, otherwise it will -do ⟨hyper false⟩. The hyperlink may be off even if it wasn’t explicitly switched off -with the hyper key or the use of a starred command. It may be off because the -hyper true⟩ if the hyperlinks are on for the current reference, otherwise it will do ⟨hyper false⟩. The +hyperlink may be off even if it wasn’t explicitly switched off with the hyper key or the use of a starred +command. It may be off because the hyperref package hasn’t been loaded or because package hasn’t been loaded or because \glsdisablehyper has been used or -because the entry is in a glossary type that’s had the hyperlinks switched off (using - +has been used or because the entry is in a glossary type that’s had the hyperlinks switched off +(using nohypertypes) or because it’s the ) or because it’s the first use and the hyperlinks have been suppressed on first use. -

    Note that

    The \glsifhyperon command should be used instead of \glsifhyper is now deprecated. If you want to know if the command used to -reference this entry was used with the star or plus variant, you can use: -


    \glslinkvar  , which is now deprecated (and no +longer documented).
    +

    +

    If you want to know if the command used to reference this entry was used with the star or plus variant, you +can use: +


    \glslinkvar{unmodified}{star}{plus}

    -

    +

    This will do ⟨unmodified⟩ if the unmodified version was used, or will do ⟨star⟩ if the starred -version was used, or will do ⟨plus⟩ if the plus version was used. Note that this doesn’t -take into account if the hyper key was used to override the default setting, so this -command shouldn’t be used to guess whether or not the hyperlink is on for this - - -reference. -

    Note that you can also use commands such as star⟩ if the starred version was used, or + + +will do ⟨plus⟩ if the plus version was used. Note that this doesn’t take into account if the hyper key was used to +override the default setting, so this command shouldn’t be used to guess whether or not the hyperlink is on for +this reference. +

    Note that you can also use commands such as \ifglsused within the definition of - within the definition of \glsentryfmt (see §14 §14 +Unsetting and Resetting Entry Flags). -

    The commands

    The commands \glslabel, , \glstype, , \glsifplural, , \glscapscase, \glscustomtext and -, \glsinsert are typically updated at the start of the and \glscustomtext are +typically updated at the start of the \gls-like and \glstext-like commands -so they can usually be accessed in the hook user commands, such as \glstext-like commands so they can usually be accessed in +the hook user commands, such as \glspostlinkhook and - and \glslinkpostsetkeys. -

    This means that using commands like . +

    This means that using commands like \gls within the fields that are accessed using the - within the fields that are accessed using the \gls-like or \gls-like or +\glstext-like commands (such as the first, text, long or short keys) will cause a -problem. The entry formatting performed by \glsentryfmt and related commands isn’t -scoped (otherwise if would cause problems for \glspostlinkhook which may need to look -ahead as well as look behind). This means that any nested commands will, at the very least, -change the label stored in \glslabel.
    -

    -

    If you only want to make minor modifications to first, text, long or short keys) will cause a problem. The entry +formatting performed by \glsentryfmt and related commands isn’t scoped (otherwise if would +cause problems for \glspostlinkhook which may need to look ahead as well as look behind). This +means that any nested commands will, at the very least, change the label stored in \glslabel. +

    +

    +

    If you only want to make minor modifications to \glsentryfmt, you can use -


    \glsgenentryfmt 


    \glsgenentryfmt

    -

    +

    This uses the above commands to display just the first, text, plural or firstplural keys (or the -custom text) with the insert text appended. -

    Alternatively, if want to change the entry format for abbreviations (defined via -first, text, plural or firstplural keys (or the custom +text) with the insert text appended. +

    Alternatively, if you want to change the entry format for abbreviations (defined via \newacronym) you can use: -


    \glsgenacfmt  ) you can +use: +


    \glsgenacfmt

    -

    +

    This uses the values from the long, short, longplural and shortplural keys, rather than -using the text, plural, first and firstplural keys. The first use singular text is obtained -via: -


    \genacrfullformat  long, short, longplural and shortplural keys, rather than using the text, +plural, first and firstplural keys. The first use singular text is obtained via: +


    \genacrfullformat{label}{insert}

    -

    +

    instead of from the first key, and the first use plural text is obtained via: -


    \genplacrfullformat  first key, and the first use plural text is obtained via: +


    \genplacrfullformat{label}{insert}

    -

    +

    instead of from the firstplural key. In both cases, ⟨firstplural key. In both cases, ⟨label⟩ is the entry’s label and ⟨insert⟩ is the -insert text provided in the final optional argument of commands like insert⟩ is the insert text +provided in the final optional argument of commands like \gls. The default -behaviour is to do the long form (or plural long form) followed by ⟨insert⟩ and a space -and the short form (or plural short form) in parentheses, where the short form -is in the argument of . The default behaviour is to do the long form (or +plural long form) followed by ⟨insert⟩ and a space and the short form (or plural short form) in parentheses, where +the short form is in the argument of \firstacronymfont. There are also first letter upper case + id="dx1-135064">. There are also first letter upper case versions: -


    \Genacrfullformat 


    \Genacrfullformat{label}{insert}

    -

    +

    and -


    \Genplacrfullformat 


    \Genplacrfullformat{label}{insert}

    -

    -By default these perform a protected expansion on their no-case-change equivalents and then -use

    +By default these perform a protected expansion on their no-case-change equivalents and then use \makefirstuc to convert the first character to upper case. If there are issues -caused by this expansion, you will need to redefine those commands to explicitly - - -use commands like +to convert the first character to upper case. If there are issues caused by this expansion, you will need to +redefine those commands to explicitly use commands like \Glsentrylong (which is what the predefined acronym styles, -such as (which is what the predefined +acronym styles, such as long-short, do). Otherwise, you only need to redefine , do). Otherwise, you only need to redefine \genacrfullformat -and and + + +\genplacrfullformat to change the behaviour of to change the behaviour of \glsgenacfmt. See §13 -Acronyms and Other Abbreviations for further details on changing the style of -acronyms. -

    Note that . See §13 Acronyms and Other Abbreviations +for further details on changing the style of acronyms. +

    Note that \glsentryfmt (or the formatting given by \defglsentryfmt) is not used by -the \defglsentryfmt) is not used by the +\glstext-like commands.
    -

    -

    As from version 4.16, both the

    +

    As from version 4.16, both the \gls-like and \glstext-like commands use -


    \glslinkpostsetkeys 


    \glslinkpostsetkeys

    -

    +

    after the ⟨options⟩ are set. This macro does nothing by default but can be redefined. (For -example, to switch off the hyperlink under certain conditions.) This version also -introduces -


    \glspostlinkhook  options⟩ are set. This macro does nothing by default but can be redefined. (For example, to switch off +the hyperlink under certain conditions.) This version also introduces +


    \glspostlinkhook

    -

    +

    which is done after the link text has been displayed and also after the first use flag has been -unset (see example 25). +href="#glo:firstuseflag">first use flag has been unset (see +example 25). -

    +

    Example 8 (Custom Entry Display in Text) -

    Suppose you want a glossary of measurements and units, you can use the symbol key to -store the unit: - - + id="x1-135076"> +

    Suppose you want a glossary of measurements and units, you can use the symbol key to store the +unit: + +

    -
    +
    \newglossaryentry{distance}{name=distance,  
    description={The length between two points},  
    symbol={km}}
    -

    and now suppose you want

    and now suppose you want \gls{distance} to produce “distance (km)” on first use, then -you can redefine first use, then you can redefine +\glsentryfmt as follows: - - + id="dx1-135078"> as follows: + +

    -
    +
    \renewcommand*{\glsentryfmt}{%  
      \glsgenentryfmt  
      \ifglsused{\glslabel}{}{\space (\glsentrysymbol{\glslabel})}%  
    }
    -

    -

    (Note that I’ve used

    +

    (Note that I’ve used \glsentrysymbol rather than rather than \glssymbol to avoid nested -hyperlinks.) -

    Note also that all of the to avoid nested hyperlinks.) +

    Note also that all of the link text will be formatted according to will be formatted according to \glstextformat -(described earlier). So if you do, say: - - + id="dx1-135082"> (described earlier). So if +you do, say: + +

    -
    +
    \renewcommand{\glstextformat}[1]{\textbf{#1}}  
    \renewcommand*{\glsentryfmt}{%  
      \glsgenentryfmt  
      \ifglsused{\glslabel}{}{\space(\glsentrysymbol{\glslabel})}%  
    }
    -

    then

    then \gls{distance} will produce “distance (km)”. -

    For a complete document, see the sample file

    For a complete document, see the sample file sample-entryfmt.tex.

    -

    -

    ____________________________

    +

    +

    ____________________________

    -

    +

    Example 9 (Custom Format for Particular Glossary) -

    Suppose you have created a new glossary called notation and you want to change -the way the entry is displayed on first use so that it includes the symbol, you can -do: - - + id="x1-135084"> +

    Suppose you have created a new glossary called notation and you want to change the way the entry is +displayed on first use so that it includes the symbol, you can do: + +

    -
    +
    \defglsentryfmt[notation]{\glsgenentryfmt  
     \ifglsused{\glslabel}{}{\space  
       (denoted \glsentrysymbol{\glslabel})}}
    -

    Now suppose you have defined an entry as follows: - - +

    Now suppose you have defined an entry as follows: + +

    -
    +
    \newglossaryentry{set}{type=notation,  
      name=set,  
      description={A collection of objects},  
      symbol={$S$}  
    }
    -

    The

    The first time you reference this entry it will be displayed as: “set (denoted S)” (assuming -S)” (assuming \gls was used). -

    Alternatively, if you expect all the symbols to be set in math mode, you can -do: - - + id="dx1-135085"> was +used). +

    Alternatively, if you expect all the symbols to be set in math mode, you can do: + +

    -
    +
    \defglsentryfmt[notation]{\glsgenentryfmt  
     \ifglsused{\glslabel}{}{\space  
       (denoted $\glsentrysymbol{\glslabel}$)}}
    -

    and define entries like this: - - +

    and define entries like this: + +

    -
    +
    \newglossaryentry{set}{type=notation,  
      name=set,  
      description={A collection of objects},  
      symbol={S}  
    }
    -

    +

    -

    -

    ____________________________

    -

    Remember that if you use the symbol key, you need to use a glossary style that displays -the symbol, as many of the styles ignore it. -

    -

    -

    +

    ____________________________

    +

    Remember that if you use the symbol key, you need to use a glossary style that displays the symbol, as many +of the styles ignore it. +

    +

    +

    Top

    6.4 Enabling and disabling hyperlinks to glossary entries

    -

    If you load the

    If you load the hyperref or or html packages prior to loading the glossaries package, the - packages prior to loading the glossaries package, the \gls-like and \gls-like and +\glstext-like commands will automatically have hyperlinks to the relevant -glossary entry, unless the hyper option has been switched off (either explicitly or through -implicit means, such as via the \glstext-like commands will automatically have hyperlinks to the relevant glossary entry, unless the hyper +option has been switched off (either explicitly or through implicit means, such as via the nohypertypes package option). -

    You can disable or enable links using: -


    \glsdisablehyper  package +option). +

    You can disable or enable links using: +


    \glsdisablehyper

    -

    +

    and -


    \glsenablehyper 


    \glsenablehyper

    -

    -respectively. The effect can be localised by placing the commands within a group. Note that -you should only use

    +respectively. The effect can be localised by placing the commands within a group. Note that you should only use +\glsenablehyper if the commands \hyperlink and and \hypertarget have -been defined (for example, by the have been defined (for example, by the +hyperref package). -

    You can disable just the package). +

    You can disable just the first use links using the package option hyperfirst=false. Note -that this option only affects the hyperfirst=false. Note that this option only +affects the \gls-like commands that recognise the first use -flag. +href="#glo:firstuseflag">first use flag. -

    +

    Example 10 (First Use With Hyperlinked Footnote Description) -

    Suppose I want the first use to have a hyperlink to the description in a footnote instead of -hyperlinking to the relevant place in the glossary. First I need to disable the hyperlinks on -first use via the package option hyperfirst=false: - - + id="x1-136012"> +

    Suppose I want the first use to have a hyperlink to the description in a footnote instead of hyperlinking to +the relevant place in the glossary. First I need to disable the hyperlinks on first use via the package option +hyperfirst=false: + +

    -
    +
    \usepackage[hyperfirst=false]{glossaries}
    -

    Now I need to redefine

    Now I need to redefine \glsentryfmt (see §6.3 Changing the format of the link -text): - - + id="dx1-136014"> (see §6.3 Changing the format of the link text): + +

    -
    +
    \renewcommand*{\glsentryfmt}{%  
      \glsgenentryfmt  
      \ifglsused{\glslabel}{}{\footnote{\glsentrydesc{\glslabel}}}%  
    }
    -

    -

    Now the first use won’t have hyperlinked text, but will be followed by a footnote. See the -sample file

    +

    Now the first use won’t have hyperlinked text, but will be followed by a footnote. See the sample file +sample-FnDesc.tex for a complete document.

    -

    -

    ____________________________

    -

    Note that the

    +

    ____________________________

    +

    Note that the hyperfirst option applies to all defined glossaries. It may be that you only -want to disable the hyperlinks on first use for glossaries that have a different form on first use. -This can be achieved by noting that since the entries that require hyperlinking for all -instances have identical first and subsequent text, they can be unset via option applies to all defined glossaries. It may be that you only want to disable the +hyperlinks on first use for glossaries that have a different form on first use. This can be achieved by noting that +since the entries that require hyperlinking for all instances have identical first and subsequent text, they can be +unset via \glsunsetall (see -§14 (see §14 Unsetting and Resetting Entry Flags) so that the hyperfirst option doesn’t get + id="dx1-136017"> option doesn’t get applied. -

    +

    Example 11 (Suppressing Hyperlinks on First Use Just For -Acronyms) -

    Suppose I want to suppress the hyperlink on first use for acronyms but not for entries in -the main glossary. I can load the  (Suppressing Hyperlinks on First Use Just For Acronyms) +

    Suppose I want to suppress the hyperlink on first use for acronyms but not for entries in the main glossary. +I can load the glossaries package using: - - + +

    -
    +
    \usepackage[hyperfirst=false,acronym]{glossaries}
    -

    Once all glossary entries have been defined I then do: - - +

    Once all glossary entries have been defined I then do: + +

    -
    +
    \glsunsetall[main]
    -

    +

    -

    -

    ____________________________

    -

    For more complex requirements, you might find it easier to switch off all hyperlinks via -

    +

    ____________________________

    +

    For more complex requirements, you might find it easier to switch off all hyperlinks via \glsdisablehyper and put the hyperlinks (where required) within the definition of - +and put the hyperlinks (where required) within the definition of \glsentryfmt (see §6.3 Changing the format of the link text) via (see §6.3 Changing the format of +the link text) via \glshyperlink (see §9 - (see §9 Using Glossary Terms Without Links). -

    +

    Example 12 (Only Hyperlink in Text Mode Not Math Mode) -

    This is a bit of a contrived example, but suppose, for some reason, I only want the - +

    This is a bit of a contrived example, but suppose, for some reason, I only want the \gls-like commands to have hyperlinks when used in text mode, but not in math mode. -I can do this by adding the glossary to the list of nohypertypes and redefining -\gls-like commands to +have hyperlinks when used in text mode, but not in math mode. I can do this by adding the glossary to the list +of nohypertypes and redefining \glsentryfmt: - - + id="dx1-136025">: + +

    -
    +
    \GlsDeclareNoHyperList{main}  
    \renewcommand*{\glsentryfmt}{%  
      \ifmmode @@ -15377,74 +17504,70 @@ class="cmtt-10">\glsentryfmt  \fi  
    }
    -

    Note that this doesn’t affect the

    Note that this doesn’t affect the \glstext-like commands, which will have the hyperlinks off -unless they’re forced on using the plus variant. -

    See the sample file \glstext-like commands, which will have the hyperlinks off unless they’re +forced on using the plus variant. +

    See the sample file sample-nomathhyper.tex for a complete document.

    -

    -

    ____________________________

    +

    +

    ____________________________

    -

    +

    Example 13 (One Hyper Link Per Entry Per Chapter) -

    Here’s a more complicated example that will only have the hyperlink on the first time an -entry is used per chapter. This doesn’t involve resetting the first use flag. Instead it adds -a new key using +

    Here’s a more complicated example that will only have the hyperlink on the first time an entry is +used per chapter. This doesn’t involve resetting the first use flag. Instead it adds a new key using +\glsaddstoragekey (see §4.3.2 Storage Keys) that keeps track of the -chapter number that the entry was last used in: - - + id="dx1-136028"> (see §4.3.2 Storage Keys) that keeps track of the chapter number that the entry was last +used in: + +

    -
    +
    \glsaddstoragekey{chapter}{0}{\glschapnum}
    -

    This creates a new user command called

    This creates a new user command called \glschapnum that’s analogous to \glsentrytext. -The default value for this key is 0. I then define my glossary entries as usual. -

    Next I redefine the hook \glsentrytext. The default value +for this key is 0. I then define my glossary entries as usual. +

    Next I redefine the hook \glslinkpostsetkeys (see §6.3 Changing the format of the link -text) so that it determines the current chapter number (which is stored in \currentchap -using \edef). This value is then compared with the value of the entry’s chapter key that I -defined earlier. If they’re the same, this entry has already been used in this chapter so the -hyperlink is switched off using (see §6.3 Changing the format of the link text) so that it +determines the current chapter number (which is stored in \currentchap using \edef). This value is then +compared with the value of the entry’s chapter key that I defined earlier. If they’re the same, this entry +has already been used in this chapter so the hyperlink is switched off using xkeyval’s \setkeys command. If the chapter number isn’t the -same, then this entry hasn’t been used in the current chapter. The chapter field is -updated using ’s \setkeys +command. If the chapter number isn’t the same, then this entry hasn’t been used in the current +chapter. The chapter field is updated using \glsfieldxdef (§16.3 Fetching and Updating the Value of a Field) -provided the user hasn’t switched off the hyperlink. (This test is performed using + id="dx1-136031"> (§16.3 Fetching and Updating the +Value of a Field) provided the user hasn’t switched off the hyperlink. (This test is performed using \glsifhyperon. - - + +

    -
    +
    \renewcommand*{\glslinkpostsetkeys}{%  
     \edef\currentchap{\arabic{chapter}}%  
     \ifnum\currentchap=\glschapnum{\glslabel}\relax @@ -15454,147 +17577,206 @@ class="cmtt-10">\glsifhyperon.  
     \fi  
    }
    -

    Note that this will be confused if you use \gls etc when the chapter counter is 0. (That is, -before the first

    Note that this will be confused if you use \gls etc when the chapter counter is 0. (That is, before the first +\chapter.) -

    See the sample file sample-chap-hyperfirst.tex for a complete document. -

    +

    See the sample file sample-chap-hyperfirst.tex for a complete document.

    -

    -

    ____________________________

    - - -

    -

    +

    ____________________________

    + + +

    +

    Top

    7. Adding an Entry to the Glossary Without Generating Text

    -

    It is possible to add a line to the glossary file without generating any text at that point in -the document using: -


    \glsadd 

    It is possible to add a line to the glossary file without generating any text at that point in the document +using: +


    \glsadd[options]{label}

    -

    +

    This is similar to the \glstext-like commands, only it doesn’t produce any text (so -therefore, there is no hyper key available in ⟨options⟩ but all the other options that can be -used with \glstext-like commands, only it doesn’t produce any text (so therefore, there is no hyper +key available in ⟨options⟩ but all the other options that can be used with \glstext-like commands can be passed to \glsadd). For example, to -add a page range to the glossary number list for the entry whose label is given by +class="cmtt-10">\glstext-like commands can be passed +to \glsadd). For example, to add a page range to the glossary number list for the entry whose label is given by set: - - + +

    -
    +
    \glsadd[format=(]{set}  
    Lots of text about sets spanning many pages.  
    \glsadd[format=)]{set}
    -

    -

    To add all entries that have been defined, use: -


    \glsaddall 

    +

    To add all entries that have been defined, use: +


    \glsaddall[options]

    -

    +

    The optional argument is the same as for \glsadd, except there is also a key types which can -be used to specify which glossaries to use. This should be a comma separated list. For -example, if you only want to add all the entries belonging to the list of acronyms (specified by -the glossary type types which can be +used to specify which glossaries to use. This should be a comma-separated list. For example, if +you only want to add all the entries belonging to the list of acronyms (specified by the glossary +type \acronymtype) and a list of notation (specified by the glossary type -notation) then you can do: - - + id="dx1-137005">) and a list of notation (specified by the glossary type notation) then you can +do: + +

    -
    +
    \glsaddall[types={\acronymtype,notation}]
    -

    -

    Note that

    If you are using bib2gls with glossaries-extra, you can’t use \glsaddall. Instead use the selection=all resource +option to select all entries in the given bib files. +

    Note that \glsadd and \glsaddall add the current location to the number list. In the -case of \glsaddall, all entries in the glossary will have the same location in the number list. -If you want to use \glsaddall, it’s best to suppress the number list with the . In the case of \glsaddall, +all entries in the glossary will have the same location in the number list. If you want to use \glsaddall, it’s +best to suppress the number list with the nonumberlist -package option. (See sections  package option. (See sections 2.3 and 5.)
    -

    -

    There is now a variation of \glsaddall that skips any entries that have already been -used: -


    \glsaddallunused  5.) +
    +

    +

    There is now a variation of \glsaddall that skips any entries that have already been used: +


    \glsaddallunused[list]

    -

    +

    This command uses \glsadd[format=@gobble] which will ignore this location in the number -list. The optional argument ⟨list⟩ is a comma-separated list of glossary types. If omitted, it -defaults to the list of all defined glossaries. -

    If you want to use \glsaddallunused, it’s best to place the command at the end of the -document to ensure that all the commands you intend to use have already been -used. Otherwise you could end up with a spurious comma or dash in the location -list. +class="cmtt-10">\glsadd[format=glsignore] which will ignore this location in the number list. The +optional argument ⟨list⟩ is a comma-separated list of glossary types. If omitted, it defaults to the list of all defined +glossaries. +

    If you want to use \glsaddallunused, it’s best to place the command at the end of the document to ensure +that all the commands you intend to use have already been used. Otherwise you could end up with a spurious +comma or dash in the location list.
    +

    +

    With glossaries-extra and bib2gls, glsignore indicates an “ignored location” which influences selection but +isn’t added to the location list. In this case, if you use selection=all then only those entries that have been +explicitly indexed in the document will have location lists. The other entries that were selected as a result of +selection=all won’t have location lists. +

    Base glossaries package only: + + +

    +
    +\documentclass{article} + 
    \usepackage{glossaries} + 
    \makeglossaries + 
    \newglossaryentry{cat}{name={cat},description={feline}} + 
    \newglossaryentry{dog}{name={dog},description={canine}} + 
    \begin{document} + 
    \gls{cat}. + 
    \printglossaries + 
    \glsaddallunused % <- make sure dog is also listed + 
    \end{document} +
    +

    Corresponding glossaries-extra and bib2gls document code: + + +

    +
    +\documentclass{article} + 
    \usepackage[record]{glossaries-extra} + 
    \GlsXtrLoadResources[src={entries},selection=all] + 
    \begin{document} + 
    \gls{cat}. + 
    \printunsrtglossaries + 
    \end{document} +
    +

    With the file entries.bib: + + +

    +
    +@entry{cat,name={cat},description={feline}} + 
    @entry{dog,name={dog},description={canine}} +
    +

    -

    +

    Example 14 (Dual Entries) -

    The example file +

    The example file sample-dual.tex makes use of \glsadd to allow for an entry that -should appear both in the main glossary and in the list of acronyms. This example sets up the -list of acronyms using the \glsadd to allow for an entry that should appear both in +the main glossary and in the list of acronyms. This example sets up the list of acronyms using the acronym package option: - - + id="dx1-137016"> +package option: + +

    -
    +
    \usepackage[acronym]{glossaries}
    -

    A new command is then defined to make it easier to define dual entries: - - +

    A new command is then defined to make it easier to define dual entries: + +

    -
    +
    \newcommand*{\newdualentry}[5][]{%  
      \newglossaryentry{main-#2}{name={#4},%  
      text={#3\glsadd{#2}},% @@ -15604,11 +17786,11 @@ class="cmss-10">acronym  \newacronym{#2}{#3\glsadd{main-#2}}{#4}%  
    }
    -

    This has the following syntax:

    +

    This has the following syntax:

    \newdualentry[options]{description}
    You can then define a new dual entry: - - -
    + + +
    \newdualentry{svm}% label  
      {SVM}% abbreviation  
      {support vector machine}% long form  
      {Statistical pattern recognition technique}% description
    -

    Now you can reference the acronym with \gls{svm} or you can reference the entry in the -main glossary with \gls{main-svm}.

    +

    Now you can reference the acronym with \gls{svm} or you can reference the entry in the main glossary with +\gls{main-svm}. +

    Note that with bib2gls, there are special dual entry types that implement this behaviour. That is, if an +entry is referenced then its corresponding dual entry will automatically be selected as well. So there +is less need for \glsadd with bib2gls. (Although it can still be useful, as shown in Option 6.) +

    -

    -

    ____________________________

    - - -

    -

    +

    ____________________________

    + + +

    +

    Top

    8. Cross-Referencing Entries

    -

    You must use

    You must use \makeglossaries (Options  (Options 2 or 3) or \makenoidxglossaries -( (Option 1) before defining any terms that cross-reference entries. If any of the terms that -you have cross-referenced don’t appear in the glossary, check that you have put -before +defining any terms that cross-reference entries. If any of the terms that you have cross-referenced +don’t appear in the glossary, check that you have put \makeglossaries/\makenoidxglossaries before all entry definitions. The \makenoidxglossaries +before all entry definitions. The glossaries-extra -package provides better cross-reference handling.
    -

    -

    There are several ways of cross-referencing entries in the glossary: +class="cmss-10">glossaries-extra package provides better cross-reference handling. +

    +

    +

    There are several ways of cross-referencing entries in the glossary:

    1. You can use commands such as You can use commands such as \gls in the entries description. For example: - - -
      + id="dx1-138005"> in the entries description. For example: + + +
      \newglossaryentry{apple}{name=apple,  
      description={firm, round fruit. See also \gls{pear}}}
      -

      Note that with this method, if you don’t use the cross-referenced term in the main part - of the document, you will need two runs of

      Note that with this method, if you don’t use the cross-referenced term in the main part of the document, + you will need two runs of makeglossaries: - - -

      -
      - latex filename -  
      makeglossaries filename -  
      latex filename -  
      makeglossaries filename -  
      latex filename -
      -

      + id="dx1-138006">: +

      
      +     
      pdflatex filename +
      makeglossaries filename +
      pdflatex filename +
      makeglossaries filename +
      pdflatex filename +
      +

    2. As described in §4 As described in §4 Defining Glossary Entries, you can use the see key when you define - the entry. For example: - - -
      +class="cmtt-10">see key when you define the entry. For + example: + + +
      \newglossaryentry{MaclaurinSeries}{name={Maclaurin  
      series},  
      description={Series expansion},  
      see={TaylorsTheorem}}
      -

      Note that in this case, the entry with the see key will automatically be added to the - glossary, but the cross-referenced entry won’t. You therefore need to ensure that you - use the cross-referenced term with the commands described in §6 Links to - Glossary Entries or §7 Adding an Entry to the Glossary Without Generating - Text. -

      The “see” tag is produce using

      Note that in this case, the entry with the see key will automatically be added to the glossary, but the + cross-referenced entry won’t. You therefore need to ensure that you use the cross-referenced term with the + commands described in §6 Links to Glossary Entries or §7 Adding an Entry to the Glossary Without + Generating Text. +

      The “see” tag is produce using \seename, but can be overridden in specific instances - using square brackets at the start of the see value. For example: - - + id="dx1-138011">, but can be overridden in specific instances using square brackets + at the start of the see value. For example: + +

      -
      +
      \newglossaryentry{MaclaurinSeries}{name={Maclaurin  
      series},  
      description={Series expansion},  
      see=[see also]{TaylorsTheorem}}
      -

      Take care if you want to use the optional argument of commands such as

      Take care if you want to use the optional argument of commands such as \newacronym - or or \newterm as the value will need to be grouped. For example: - - + id="dx1-138014"> as + the value will need to be grouped. For example: + +

      -
      +
      \newterm{seal}  
      \newterm[see={[see also]seal}]{sea lion}
      -

      Similarly if the value contains a list. For example: - - +

      Similarly if the value contains a list. For example: + +

      -
      +
      \glossaryentry{lemon}{  
        name={lemon},  
        description={Yellow citrus fruit} @@ -15769,14 +17956,12 @@ class="cmtt-10">\newterm  see={lemon,lime}  
      }
      -

      +

    3. After you have defined the entry, use -


      \glssee  After you have defined the entry, use +


      \glssee[tag]{label}{xr label list}

      -

      +

      where ⟨xr label list⟩ is a comma-separated list of entry labels to be cross-referenced, ⟨label⟩ - is the label of the entry doing the cross-referencing and ⟨tag⟩ is the “see” tag. (The - default value of ⟨label⟩ is the label of the + entry doing the cross-referencing and ⟨tag⟩ is the “see” tag. (The default value of ⟨tag⟩ is \seename.) For example: - - + id="dx1-138018">.) For + example: + +

      -
      +
      \glssee[see also]{series}{FourierSeries,TaylorsTheorem}
      -

      Note that this automatically adds the entry given by ⟨label⟩ to the glossary - but doesn’t add the cross-referenced entries (specified by ⟨xr label list⟩) to the - glossary.

    -

    In both cases 2 and 3 above, the cross-referenced information appears in the

    Note that this automatically adds the entry given by ⟨label⟩ to the glossary but doesn’t add the + cross-referenced entries (specified by ⟨xr label list⟩) to the glossary.

    +

    In both cases 2 and 3 above, the cross-referenced information appears in the number list, -whereas in case 1, the cross-referenced information appears in the description. (See the -sample-crossref.tex example file that comes with this package.) This means that in -cases 2 and 3, the cross-referencing information won’t appear if you have suppressed the -number list. In this case, you will need to activate the number list for the given entries using -nonumberlist=false. Alternatively, if you just use the see key instead of , whereas in case 1, +the cross-referenced information appears in the description. (See the sample-crossref.tex example file that +comes with this package.) This means that in cases 2 and 3, the cross-referencing information won’t appear if +you have suppressed the number list. In this case, you will need to activate the number list for +the given entries using nonumberlist=false. Alternatively, if you just use the see key instead +of \glssee, you -can automatically activate the number list using the , you can automatically activate the number list using the seeautonumberlist package + id="dx1-138026"> package option.

    -

    Top

    8.1 Customising Cross-reference Text

    -

    When you use either the see key or the command \glssee, the cross-referencing information -will be typeset in the glossary according to: -


    \glsseeformat 

    When you use either the see key or the command \glssee, the cross-referencing information will be typeset in +the glossary according to: +


    \glsseeformat[tag]{label-list}{location}

    -

    +

    The default definition of \glsseeformat is:
    }
    Note that the location is always ignored.8.1 + id="x1-139003f1"> For example, if you want the tag to appear in bold, you can do:8.2 - - + id="x1-139005f2"> + +

    -
    +
    \renewcommand*{\glsseeformat}[3][\seename]{\textbf{#1}  
     \glsseelist{#2}}
    -

    -

    The list of labels is dealt with by \glsseelist, which iterates through the list and -typesets each entry in the label. The entries are separated by -


    \glsseesep 

    +

    The list of labels is dealt with by \glsseelist, which iterates through the list and typesets each entry in +the label. The entries are separated by +


    \glsseesep

    -

    +

    or (for the last pair) -


    \glsseelastsep 


    \glsseelastsep

    -

    +

    These default to “,\space” and “\space\andname\space” respectively. The list entry text is -displayed using: -


    \glsseeitemformat  \space” respectively. The list entry text is displayed +using: +


    \glsseeitemformat{label}

    -

    +

    This defaults to \glsentrytext{label}.8.3 + id="x1-139013f3"> For example, to make the cross-referenced list use small caps: - - + +

    -
    +
    \renewcommand{\glsseeitemformat}[1]{%  
      \textsc{\glsentrytext{#1}}}
    -

    -

    You can use

    +

    You can use \glsseeformat and and \glsseelist in the main body of the text, but they -won’t automatically add the cross-referenced entries to the glossary. If you want them added -with that location, you can do: - - + id="dx1-139017"> in the main body of the text, but they won’t automatically +add the cross-referenced entries to the glossary. If you want them added with that location, you can +do: + +

    -
    +
    Some information (see also  
    \glsseelist{FourierSeries,TaylorsTheorem}%  
    \glsadd{FourierSeries}\glsadd{TaylorsTheorem}).
    -

    -

    - - +

    +

    + +

    -

    -

    +

    Top

    9. Using Glossary Terms Without Links

    -

    The commands described in this section display entry details without adding any -information to the glossary. They don’t use

    The commands described in this section display entry details without adding any information to the +glossary. They don’t use \glstextformat, they don’t have any optional -arguments, they don’t affect the first use flag and, apart from , they don’t have any optional arguments, they don’t affect the first +use flag and, apart from \glshyperlink, they don’t -produce hyperlinks. -

    Commands that aren’t expandable will be ignored by PDF bookmarks, so you will need -to provide an alternative via , they don’t produce hyperlinks. +

    Commands that aren’t expandable will be ignored by PDF bookmarks, so you will need to provide an +alternative via hyperref’s \texorpdfstring if you want to use them in -sectioning commands. (This isn’t specific to the ’s \texorpdfstring if you want to use them in sectioning commands. (This isn’t specific +to the glossaries package.) See the hyperref -documentation for further details. All the commands that convert the first letter to upper -case aren’t expandable. The other commands depend on whether their corresponding keys + id="dx1-140004"> documentation for further details. All the commands that convert the +first letter to upper case aren’t expandable. The other commands depend on whether their corresponding keys were assigned non-expandable values.
    -

    -

    If you want to title case a field, you can use: -


    \glsentrytitlecase 

    +

    If you want to title case a field, you can use: +


    \glsentrytitlecase{label}{field}

    -

    +

    where ⟨label⟩ is the label identifying the glossary entry, ⟨field⟩ is the field label (see table 4.1). -For example: - - +href="#tab:fieldmap">table 4.1). For +example: + +

    -
    +
    \glsentrytitlecase{sample}{desc}
    -

    (If you want title-casing in your glossary style, you might want to investigate the -glossaries-extra package.) -

    Note that this command has the same limitations as \makefirstuc which is used by -commands like \Gls and \Glsentryname to upper-case the first letter (see the notes about -

    (If you want title-casing in your glossary style, you might want to investigate the glossaries-extra package.) This +command will trigger an error if the entry is undefined. +

    Note that this command has the same limitations as \makefirstuc which is used by commands like \Gls +and \Glsentryname to upper-case the first letter (see the notes about \Gls in §6.1 §6.1 The \gls-Like Commands (First Use Flag Queried)). -


    \glsentryname  \gls-Like Commands +(First Use Flag Queried)). +


    \glsentryname{label}

    -

    -


    \Glsentryname 

    +


    \Glsentryname{label}

    -

    +

    These commands display the name of the glossary entry given by ⟨label⟩, as specified by the -name key. \Glsentryname makes the first letter upper case. Neither of these commands check -for the existence of ⟨label⟩. The first form \glsentryname is expandable (unless the name -contains unexpandable commands). Note that this may be different from the values of the -text or first keys. In general it’s better to use \glsentrytext or \glsentryfirst instead of +class="cmti-10">label⟩, as specified by the name key. \Glsentryname makes the first letter upper case. Neither of these commands check for the existence of ⟨label⟩. +The first form \glsentryname is expandable (unless the name contains unexpandable commands). Note that +this may be different from the values of the text or first keys. In general it’s better to use \glsentrytext or +\glsentryfirst instead of \glsentryname. -

    In general it’s best to avoid \Glsentryname with abbreviations. Instead, consider using +

    In general it’s best to avoid \Glsentryname with abbreviations. Instead, consider using \Glsentrylong, \Glsentrylong, \Glsentryshort or \Glsentryfull.
    -

    -


    \glossentryname 

    +


    \glossentryname{label}

    -

    +

    This is like \glsnamefont{\glsentryname{label}} but also checks for the existence of ⟨label⟩. -This command is not expandable. It’s used in the predefined glossary styles, so if you want to -change the way the name is formatted in the glossary, you can redefine \glsnamefont to use -the required fonts. For example: - - -

    -
    +class="cmti-10">label⟩. This command is +not expandable. It’s used in the predefined glossary styles, so if you want to change the way the +name is formatted in the glossary, you can redefine \glsnamefont to use the required fonts. For +example: + + +

    +
    \renewcommand*{\glsnamefont}[1]{\textmd{\sffamily #1}}
    -

    -


    \Glossentryname 

    +


    \Glossentryname{label}

    -

    +

    This is like \glossentryname but makes the first letter of the name upper case. -


    \glsentrytext 


    \glsentrytext{label}

    -

    -


    \Glsentrytext 

    +


    \Glsentrytext{label}

    -

    +

    These commands display the subsequent use text for the glossary entry given by ⟨label⟩, as -specified by the text key. \Glsentrytext makes the first letter upper case. The first form is -expandable (unless the text contains unexpandable commands). The second form is not -expandable. Neither checks for the existence of ⟨label⟩, as specified by the text +key. \Glsentrytext makes the first letter upper case. The first form is expandable (unless the text contains +unexpandable commands). The second form is not expandable. Neither checks for the existence of +⟨label⟩. -


    \glsentryplural 


    \glsentryplural{label}

    -

    -


    \Glsentryplural 

    +


    \Glsentryplural{label}

    -

    +

    These commands display the subsequent use plural text for the glossary entry given by ⟨label⟩, -as specified by the plural key. \Glsentryplural makes the first letter upper case. -The first form is expandable (unless the value of that key contains unexpandable -commands). The second form is not expandable. Neither checks for the existence of -⟨label⟩, as specified by the +plural key. \Glsentryplural makes the first letter upper case. The first form is expandable (unless the value +of that key contains unexpandable commands). The second form is not expandable. Neither checks for the +existence of ⟨label⟩. -


    \glsentryfirst 


    \glsentryfirst{label}

    -

    -


    \Glsentryfirst 

    +


    \Glsentryfirst{label}

    -

    +

    These commands display the first use text for the glossary entry given by ⟨label⟩, -as specified by the first key. \Glsentryfirst makes the first letter upper case. -The first form is expandable (unless the value of that key contains unexpandable -commands). The second form is not expandable. Neither checks for the existence of +class="cmti-10">label⟩, as specified by the first key. +\Glsentryfirst makes the first letter upper case. The first form is expandable (unless the value of that key +contains unexpandable commands). The second form is not expandable. Neither checks for the existence of ⟨label⟩. -


    \glsentryfirstplural 


    \glsentryfirstplural{label}

    -

    -


    \Glsentryfirstplural 

    +


    \Glsentryfirstplural{label}

    -

    +

    These commands display the plural form of the first use text for the glossary entry given by -⟨label⟩, as specified by the firstplural key. \Glsentryfirstplural makes the first letter upper -case. The first form is expandable (unless the value of that key contains unexpandable - - -commands). The second form is not expandable. Neither checks for the existence of -⟨first use text for the glossary entry given by ⟨label⟩, as specified +by the firstplural key. \Glsentryfirstplural makes the first letter upper case. The first form is expandable +(unless the value of that key contains unexpandable commands). The second form is not expandable. Neither +checks for the existence of ⟨label⟩. -


    \glsentrydesc 


    \glsentrydesc{label}

    -

    -


    \Glsentrydesc 

    +


    \Glsentrydesc{label}

    -

    +

    These commands display the description for the glossary entry given by ⟨label⟩. \Glsentrydesc -makes the first letter upper case. The first form is expandable (unless the value of that key -contains unexpandable commands). The second form is not expandable. Neither checks for -the existence of ⟨label⟩. -


    \glossentrydesc 

    \Glsentrydesc makes the first letter upper case. The first form is expandable (unless the value of that key +contains unexpandable commands). The second form is not expandable. Neither checks for the existence of +⟨label⟩. +


    \glossentrydesc{label}

    -

    +

    This is like \glsentrydesc{label} but also checks for the existence of ⟨label⟩. This -command is not expandable. It’s used in the predefined glossary styles to display the -description. -


    \Glossentrydesc  label⟩. This command is not expandable. +It’s used in the predefined glossary styles to display the description. +


    \Glossentrydesc{label}

    -

    +

    This is like \glossentrydesc but converts the first letter to upper case. This command is not expandable. -


    \glsentrydescplural 


    \glsentrydescplural{label}

    -

    -


    \Glsentrydescplural 

    +


    \Glsentrydescplural{label}

    -

    +

    These commands display the plural description for the glossary entry given by ⟨label⟩. \Glsentrydescplural +makes the first letter upper case. The first form is expandable (unless the value of that key contains +unexpandable commands). The second form is not expandable. Neither checks for the existence of +⟨label⟩. -\Glsentrydescplural makes the first letter upper case. The first form is expandable (unless -the value of that key contains unexpandable commands). The second form is not expandable. -Neither checks for the existence of ⟨label⟩. -


    \glsentrysymbol 


    \glsentrysymbol{label}

    -

    -


    \Glsentrysymbol 

    +


    \Glsentrysymbol{label}

    -

    +

    These commands display the symbol for the glossary entry given by ⟨label⟩. \Glsentrysymbol -makes the first letter upper case. The first form is expandable (unless the value of that key -contains unexpandable commands). The second form is not expandable. Neither checks for -the existence of ⟨label⟩. -


    \glsletentryfield 

    \Glsentrysymbol makes the first letter upper case. The first form is expandable (unless the value of that +key contains unexpandable commands). The second form is not expandable. Neither checks for the existence of +⟨label⟩. +


    \glsletentryfield{cs}{label}{field}

    -

    -This command doesn’t display anything. It merely fetches the value associated with the given -field (where the available field names are listed in table 4.1) and stores the result in the -control sequence ⟨cs⟩. For example, to store the description for the entry whose label is “apple” -in the control sequence

    +This command doesn’t display anything. It merely fetches the value associated with the given field (where +the available field names are listed in table 4.1) and stores the result in the control sequence ⟨cs⟩. +For example, to store the description for the entry whose label is “apple” in the control sequence +\tmp: - - + +

    -
    +
    \glsletentryfield{\tmp}{apple}{desc}
    -

    -


    \glossentrysymbol 

    +


    \glossentrysymbol{label}

    -

    +

    This is like \glsentrysymbol{label} but also checks for the existence of ⟨label⟩. This command -is not expandable. It’s used in some of the predefined glossary styles to display the -symbol. -


    \Glossentrysymbol  label⟩. This command is not expandable. +It’s used in some of the predefined glossary styles to display the symbol. +


    \Glossentrysymbol{label}

    -

    +

    This is like \glossentrysymbol but converts the first letter to upper case. This command is -not expandable. -


    \glsentrysymbolplural  \glossentrysymbol but converts the first letter to upper case. This command is not +expandable. +


    \glsentrysymbolplural{label}

    -

    -


    \Glsentrysymbolplural 

    +


    \Glsentrysymbolplural{label}

    -

    +

    These commands display the plural symbol for the glossary entry given by ⟨label⟩. \Glsentrysymbolplural +makes the first letter upper case. The first form is expandable (unless the value of that key contains +unexpandable commands). The second form is not expandable. Neither checks for the existence of +⟨label⟩. -\Glsentrysymbolplural makes the first letter upper case. The first form is expandable -(unless the value of that key contains unexpandable commands). The second form is not -expandable. Neither checks for the existence of ⟨label⟩. -


    \glsentryuseri 


    \glsentryuseri{label}

    -

    -


    \Glsentryuseri 

    +


    \Glsentryuseri{label}

    -

    -


    \glsentryuserii 

    +


    \glsentryuserii{label}

    -

    -


    \Glsentryuserii 

    +


    \Glsentryuserii{label}

    -

    -


    \glsentryuseriii 

    +


    \glsentryuseriii{label}

    -

    -


    \Glsentryuseriii 

    +


    \Glsentryuseriii{label}

    -

    -


    \glsentryuseriv 

    +


    \glsentryuseriv{label}

    -

    -


    \Glsentryuseriv 

    +


    \Glsentryuseriv{label}

    - - -

    -


    \glsentryuserv 

    +


    \glsentryuserv{label}

    -

    -


    \Glsentryuserv 

    +


    \Glsentryuserv{label}

    -

    -


    \glsentryuservi 

    +


    \glsentryuservi{label}

    -

    -


    \Glsentryuservi 

    +


    \Glsentryuservi{label}

    -

    +

    These commands display the value of the user keys for the glossary entry given by ⟨label⟩. The -lower case forms are expandable (unless the value of the key contains unexpandable -commands). The commands beginning with an upper case letter convert the first letter of the -required value to upper case and are not expandable. None of these commands check for the -existence of ⟨label⟩. The lower case forms +are expandable (unless the value of the key contains unexpandable commands). The commands beginning with +an upper case letter convert the first letter of the required value to upper case and are not expandable. None of +these commands check for the existence of ⟨label⟩. -


    \glshyperlink 


    \glshyperlink[link text]{label}

    -

    +

    This command provides a hyperlink to the glossary entry given by ⟨labelbut does not add -any information to the glossary file. The link text is given by labelbut does not add +any information to the glossary file. The link text is given by \glsentrytext{label} by default9.1, -but can be overridden using the optional argument. Note that the hyperlink will be -suppressed if you have used , +but can be overridden using the optional argument. Note that the hyperlink will be suppressed if you have used +\glsdisablehyper or if you haven’t loaded the or if you haven’t loaded the hyperref -package. -

    If you use \glshyperlink, you need to ensure that the relevant entry has been added to -the glossary using any of the commands described in §6 package. +

    If you use \glshyperlink, you need to ensure that the relevant entry has been added to the glossary using +any of the commands described in §6 Links to Glossary Entries or §7 -Adding an Entry to the Glossary Without Generating Text otherwise you will end up with an -undefined link.
    -

    -

    The next two commands are only available with §7 Adding an Entry to the Glossary Without +Generating Text otherwise you will end up with an undefined link.

    +

    +

    The next two commands are only available with Option 1 or with the savenumberlist -package option: -


    \glsentrynumberlist  package +option: +


    \glsentrynumberlist{label}

    -

    -


    \glsdisplaynumberlist 

    +


    \glsdisplaynumberlist{label}

    -

    +

    Both display the number list for the entry given by ⟨ for the entry given by ⟨label⟩. When used with Option 1 a rerun -is required to ensure this list is up-to-date, when used with Options Option 1 a rerun is required to +ensure this list is up-to-date, when used with Options 2 or 3 a run of -3 a run of makeglossaries (or (or makeindex//xindy) followed by one or two runs of LATEX is -required. -

    The first command, \glsentrynumberlist, simply displays the number list as is. The -second command, ) +followed by one or two runs of LATEX is required. +

    The first command, \glsentrynumberlist, simply displays the number list as is. The second command, +\glsdisplaynumberlist, formats the list using: -


    \glsnumlistsep 


    \glsnumlistsep

    - - -

    +

    as the separator between all but the last two elements and -


    \glsnumlistlastsep 


    \glsnumlistlastsep

    -

    +

    + + between the final two elements. The defaults are ,␣ and ␣\&␣, respectively. -

    \glsdisplaynumberlist is fairly experimental. It works with Option 1, but for -Options 2 or 3 it only works when the default counter format is used (that is, when the +href="#option1">Option 1, but for Options 2 +or 3 it only works when the default counter format is used (that is, when the format key is set to format key is set to glsnumberformat). This command will only work with hyperref if you -choose Option 1. If you try using this command with Options  if you choose Option 1. If you try using +this command with Options 2 or 3 and hyperref, -\glsentrynumberlist will be used instead.
    -

    -

    For further information see “Displaying entry details without adding information to the -glossary” in the documented code (, \glsentrynumberlist will be used instead. +

    +

    +

    For further information see “Displaying entry details without adding information to the glossary” in the +documented code (glossaries-code.pdf). - - + +

    -

    -

    +

    Top

    10. Displaying a glossary

    -

    All defined glossaries may be displayed using: +

    All defined glossaries may be displayed using:

    Option 1:
    -


    \printnoidxglossaries  \printnoidxglossaries

    -

    - (Must be used with (Must be used with \makenoidxglossaries in the preamble.) + id="dx1-141001"> in the preamble.) +


    \printnoidxglossaries

    +

    Options 3:
    -


    \printglossaries  \printglossaries

    -

    - (Must be used with (Must be used with \makeglossaries in the preamble.)

    -

    These commands will display all the glossaries in the order in which they were defined. -Note that, in the case of Options  in the preamble.) +


    \printglossaries

    +

    +

    +

    These commands will display all the glossaries in the order in which they were defined. +

    Note that, in the case of Options 2 and 3, no glossaries will appear until you have either used -the Perl script 3, no glossaries will appear until you have either used the Perl script +makeglossaries or Lua script or Lua script makeglossaries-lite or have directly used - or have directly used makeindex or or xindy (as described in §1.5 (as described +in §1.4 Generating the Associated Glossary Files). -(While the external files are missing, these commands will just do \null for each -missing glossary to assist dictionary style documents that just use \glsaddall -without inserting any text. If you use

    While the external files are missing, \printglossary will just do \null for each missing glossary to assist +dictionary style documents that just use \glsaddall without inserting any text. This use of \null ensures that +all indexing information is written before the final page is shipped out. Once the external files are present \null +will no longer be used. This can cause a spurious blank page on the first LATEX run before the glossary files +have been created. Once these files are present, \null will no longer be used and so shouldn’t cause interference +for the final document.
    +

    +

    If you use glossaries-extra, it will insert a heading and -boilerplate text when the external files are missing. The extension package also provides -glossaries-extra, it will insert a heading and boilerplate text when the external files are missing. +The extension package also provides \printunsrtglossaries as an alternative. See the glossaries-extra manual for further -details.) -

    If the glossary still does not appear after you re-LATEX your document, check the -glossaries-extra manual +for further details.

    +

    +

    If the glossary still does not appear after you re-LATEX your document, check the makeindex//xindy log files to see if there is a problem. With Option 1, you just need two -LATEX runs to make the glossaries appear, but you may need further runs to make the - log +files to see if there is a problem. With Option 1, you just need two LATEX runs to make the glossaries appear, +but you may need further runs to make the number lists up-to-date. -

    An individual glossary can be displayed using: + id="dx1-141013">s up-to-date. +

    An individual glossary can be displayed using:

    Option 1:
    -


    \printnoidxglossary 


    \printnoidxglossary[options]

    -

    +

    (Must be used with \makenoidxglossaries in the preamble.) + id="dx1-141015"> in the preamble.)

    Options3:
    -


    \printglossary 


    \printglossary[options]

    -

    +

    (Must be used with \makeglossaries in the preamble.)

    -

    where ⟨ in the preamble.)

    +

    where ⟨options⟩ is a ⟨key⟩=⟨value⟩ list of options. (Again, when the associated external file is missing, -\null is inserted into the document.) - - -

    The following keys are available: +class="cmti-10">value⟩ list of options. (Again, when the associated external file is missing, \null is inserted +into the document.) +

    The following keys are available:

    type
    The value of this key specifies which glossary to print. If omitted, the default glossary is - assumed. For example, to print the list of acronyms: - - -
    +class="cmtt-10">type
    The value of this key specifies which glossary to print. If omitted, the default glossary is assumed. For + example, to print the list of acronyms: + + +
    \printglossary[type=\acronymtype]
    -

    Note that you can’t display an ignored glossary, so don’t try setting type to the name of - a glossary that was defined using

    Note that you can’t display an ignored glossary, so don’t try setting type to the name of a glossary that + was defined using \newignoredglossary, described in §12 Defining New - Glossaries. (You can display an ignored glossary with \printunsrtglossary provided - by , described in §12 Defining New Glossaries. (You can display an + ignored glossary with \printunsrtglossary provided by glossaries-extra.)

    title
    This is the glossary’s title (overriding the title specified when the glossary was - defined). +class="cmtt-10">title
    This is the glossary’s title (overriding the title specified when the glossary was defined).
    toctitle
    toctitle
    This is the title to use for the table of contents (if the toc package option has been - used). It may also be used for the page header, depending on the page style. If omitted, - the value of title is used. + id="dx1-141023"> package option has been used). It may also + be used for the page header, depending on the page style. If omitted, the value of title is + used.
    style
    This specifies which glossary style to use for this glossary, overriding the effect of the - style
    This specifies which glossary style to use for this glossary, overriding the effect of the style package option or package option + or \glossarystyle. + id="dx1-141027">.
    numberedsection
    This specifies whether to use a numbered section for this glossary, - overriding the effect of the numberedsection
    This specifies whether to use a numbered section for this glossary, overriding the effect of the + numberedsection package option. This key has the same - syntax as the package option. This key has the same syntax as the numberedsection package option, described in §2.2 Sectioning, Headings - and TOC Options. + id="dx1-141030"> package option, + described in §2.2 Sectioning, Headings and TOC Options.
    nonumberlist
    nonumberlist
    This is a boolean key. If true (nonumberlist=true) the numberlist is - suppressed for this glossary. If false (nonumberlist=false) the numberlist is displayed - for this glossary. +class="cmtt-10">nonumberlist=true) the numberlist is suppressed for this + glossary. If false (nonumberlist=false) the numberlist is displayed for this glossary.
    nogroupskip
    This is a boolean key. If true the vertical gap between groups is suppressed for - this glossary. +class="cmtt-10">nogroupskip
    This is a boolean key. If true the vertical gap between groups is suppressed for this + glossary.
    nopostdot
    This is a boolean key. If true the full stop after the description is suppressed for - this glossary. +class="cmtt-10">nopostdot
    This is a boolean key. If true the full stop after the description is suppressed for this + glossary.
    entrycounter
    This is a boolean key. Behaves similar to the package option of the same name. - The corresponding package option must be used to make entrycounter
    This is a boolean key. Behaves similar to the package option of the same name. The + corresponding package option must be used to make \glsrefentry work - correctly. - - + id="dx1-141035"> work correctly.
    subentrycounter
    This is a boolean key. Behaves similar to the package option of the same - name. If you want to set both entrycounter and subentrycounter, make sure you specify - entrycounter first. The corresponding package option must be used to make - subentrycounter
    This is a boolean key. Behaves similar to the package option of the same name. If you want + to set both entrycounter and subentrycounter, make sure you specify entrycounter first. The + corresponding package option must be used to make \glsrefentry work correctly. + id="dx1-141040"> work correctly.
    sort
    sort
    This key is only available for Option 1. Possible values are: word (word order), letter - (letter order), letter (letter order), + + + standard (word or letter ordering taken from the order package option), - package option), use (order of use), def (order of definition) def (order of + definition) nocase (case-insensitive) or case - (case-sensitive). Note that the word and letter comparisons (that is, everything other - than case (case-sensitive). Note that the word and letter comparisons + (that is, everything other than sort=use and sort=def) just use a simple character code comparison. For a - locale-sensitive sort, you must use either sort=def) just use a simple character code comparison. For + a locale-sensitive sort, you must use either xindy ( (Option 3) or bib2gls (Option 4). - Note that (Option 4). Note that bib2gls provides many other sort options. -

    If you use the + provides many other sort options. +

    If you use the use or def values make sure that you select a glossary style that doesn’t - have a visual indicator between groups, as the grouping no longer makes sense. Consider - using the def values make sure that you select a glossary style that doesn’t have a visual + indicator between groups, as the grouping no longer makes sense. Consider using the nogroupskip option.
    -

    -

    The + id="dx1-141046"> option. +

    +

    +

    The word and letter @@ -16903,14 +18967,14 @@ class="cmss-10">nogroupskipdatatool’s + id="dx1-141047">’s \dtlwordindexcompare + id="dx1-141048"> and \dtlletterindexcompare + id="dx1-141049"> handlers. The case-insensitive @@ -16919,10 +18983,10 @@ class="cmtt-10">\dtlletterindexcomparedatatool’s + id="dx1-141050">’s \dtlicompare + id="dx1-141051"> handler. The case-sensitive @@ -16931,135 +18995,190 @@ class="cmtt-10">\dtlicomparedatatool’s - - + id="dx1-141052">’s \dtlcompare + id="dx1-141053"> handler. See the datatool + id="dx1-141054"> documentation for further + + details. -

    If you don’t get an error with

    If you don’t get an error with sort=use and sort=def but you do get an error with one - of the other sort options, then you probably need to use the sanitizesort=true package - option or make sure none of the entries have fragile commands in their sort - field.

    -

    By default, the glossary is started either by sort=def but you do get an error with one of the other sort + options, then you probably need to use the sanitizesort=true package option or make sure none of the + entries have fragile commands in their sort field. +

    +label={label}
    This key is only available with glossaries-extra and labels the glossary with \label{label}. This + is an alternative to the package option numberedsection=autolabel +
    +target
    This is a boolean key only available with glossaries-extra, which can be used to switch off the + automatic hypertarget for each entry. (This refers to the target used by commands like \gls and + \glslink.) +

    This option is useful with \printunsrtglossary as it allows the same list (of sub-list) of entries to be + displayed multiple times without causing duplicate hypertarget names. +

    +prefix={prefix}
    This key is only available with glossaries-extra and provides another way of avoiding + duplicate hypertarget names is to use a different prefix for those names. This locally redefines + \glolinkprefix but note this will also affect the target for any entry referenced within the glossary with + commands like \gls, \glslink or \glshypertarget. +
    +targetnameprefix={prefix}
    This key is only available with glossaries-extra. This is similar to the prefix + option, but it alters the prefix of the hypertarget anchors without changing \glslinkprefix (so it won’t + change the hyperlinks for any entries referenced in the glossary). +
    +

    By default, the glossary is started either by \chapter* or by or by \section*, depending on -whether or not , depending on whether or not +\chapter is defined. This can be overridden by the is defined. This can be overridden by the section package option or -the package option or the \setglossarysection command. Numbered sectional units can be obtained using -the +command. Numbered sectional units can be obtained using the numberedsection package option. Each glossary sets the page header via the -command -


    \glsglossarymark  package option. Each glossary +sets the page header via the command +


    \glsglossarymark{title}

    -

    -If this mechanism is unsuitable for your chosen class file or page style package, you will need -to redefine

    +If this mechanism is unsuitable for your chosen class file or page style package, you will need to redefine +\glsglossarymark. Further information about these options and commands is -given in §2.2 Sectioning, Headings and TOC Options. -

    Information can be added to the start of the glossary (after the title and before the main -body of the glossary) by redefining -


    \glossarypreamble  . Further information about these options and commands is given in §2.2 Sectioning, Headings +and TOC Options. +

    Information can be added to the start of the glossary (after the title and before the main body of the +glossary) by redefining +


    \glossarypreamble

    -

    +

    For example: - - + +

    -
    +
    \renewcommand{\glossarypreamble}{Numbers in italic  
    indicate primary definitions.}
    -

    This needs to be done before the glossary is displayed. -

    If you want a different preamble per glossary you can use -


    \setglossarypreamble 

    This needs to be done before the glossary is displayed. +

    If you want a different preamble per glossary you can use +


    \setglossarypreamble[type]{preamble text}

    -

    +

    If ⟨type⟩ is omitted, \glsdefaulttype is used. -

    For example: - - +

    For example: + +

    -
    +
    \setglossarypreamble{Numbers in italic  
    indicate primary definitions.}
    -

    This will print the given preamble text for the main glossary, but not have any preamble text -for any other glossaries. -

    There is an analogous command to

    This will print the given preamble text for the main glossary, but not have any preamble text for any other +glossaries. +

    There is an analogous command to \glossarypreamble called -


    \glossarypostamble 


    \glossarypostamble

    -

    +

    which is placed at the end of each glossary. -

    +

    Example 15 (Switch to Two Column Mode for Glossary) -

    Suppose you are using the +

    Suppose you are using the superheaderborder + id="dx1-141079"> style10.1, -and you want the glossary to be in two columns, but after the glossary you want to switch -back to one column mode, you could do: - - + id="x1-141080f1">, +and you want the glossary to be in two columns, but after the glossary you want to switch back to one column +mode, you could do: + +

    -
    +
    \renewcommand*{\glossarysection}[2][]{%  
      \twocolumn[{\chapter*{#2}}]%  
      \setlength\glsdescwidth{0.6\linewidth}% @@ -17067,611 +19186,570 @@ back to one column mode, you could do:  
    }  
    \renewcommand*{\glossarypostamble}{\onecolumn}
    -

    +

    -

    -

    ____________________________

    -

    Within each glossary, each entry name is formatted according to -


    \glsnamefont 

    +

    ____________________________

    +

    Within each glossary, each entry name is formatted according to +


    \glsnamefont{name}

    -

    -which takes one argument: the entry name. This command is always used regardless of the -glossary style. By default, \glsnamefont simply displays its argument in whatever the -surrounding font happens to be. This means that in the list-like glossary styles (defined in -the

    +which takes one argument: the entry name. This command is always used regardless of the glossary style. By +default, \glsnamefont simply displays its argument in whatever the surrounding font happens to be. +This means that in the list-like glossary styles (defined in the glossary-list style file) the name will appear in bold, since the name is placed -in the optional argument of \item, whereas in the tabular styles (defined in the - style file) the name will +appear in bold, since the name is placed in the optional argument of \item, whereas in the tabular +styles (defined in the glossary-long and and glossary-super style files) the name will appear in the normal font. The -hierarchical glossary styles (defined in the style files) the name will appear in the normal +font. The hierarchical glossary styles (defined in the glossary-tree style file) also set the name in + id="dx1-141088"> style file) also set the name in bold. -

    If you want to change the font for the description, or if you only want to change the name -font for some types of entries but not others, you might want to consider using the -glossaries-extra package. +

    If you want to change the font for the description, or if you only want to change the name +font for some types of entries but not others, you might want to consider using the glossaries-extra +package. -

    +

    Example 16 (Changing the Font Used to Display Entry Names in the Glossary) -

    Suppose you want all the entry names to appear in medium weight small caps in your -glossaries, then you can do: - - + id="x1-141090"> +

    Suppose you want all the entry names to appear in medium weight small caps in your glossaries, then you +can do: + +

    -
    +
    \renewcommand{\glsnamefont}[1]{\textsc{\mdseries #1}}
    -

    +

    -

    -

    ____________________________

    - - -

    -

    +

    ____________________________

    + + +

    +

    Top

    11. Xindy (Option 3)

    -

    If you want to use

    If you want to use xindy to sort the glossary, you must use the package option - to sort the glossary, you must use the package option xindy: - - + id="dx1-142002">: + +

    -
    +
    \usepackage[xindy]{glossaries}
    -

    This ensures that the glossary information is written in

    This ensures that the glossary information is written in xindy syntax. -

    §1.5 syntax. +

    §1.4 Generating the Associated Glossary Files covers how to use the external indexing -application, and §5.2 Locations covers the issues involved in the location syntax. This section -covers the commands provided by the indexing application, and §5.2 +Locations covers the issues involved in the location syntax. This section covers the commands provided by the +glossaries package that allow you to adjust the xindy -style file (.xdy) and parameters. -

    To assist writing information to the style file (xdy) and parameters. +

    To assist writing information to the xindy style file, the glossaries package provides the -following commands: -


    \glsopenbrace  style file, the glossaries package provides the following +commands: +


    \glsopenbrace

    -

    -


    \glsclosebrace 

    +


    \glsclosebrace

    -

    +

    which produce an open and closing brace. (This is needed because \{ and \} don’t expand to -a simple brace character when written to a file.) Similarly, you can write a percent character -using: -


    \glspercentchar  \} don’t expand to a simple brace +character when written to a file.) Similarly, you can write a percent character using: +


    \glspercentchar

    -

    +

    and a tilde character using: -


    \glstildechar 


    \glstildechar

    -

    +

    For example, a newline character is specified in a xindy style file using ~n so you can use -\glstildechar n to write this correctly (or you can do \string~n). A backslash can be -written to a file using -


    \glsbackslash  style file using ~n so you can use \glstildechar n to +write this correctly (or you can do \string~n). A backslash can be written to a file using +


    \glsbackslash

    -

    -

    In addition, if you are using a package that makes the double quote character active (e.g. -

    +

    In addition, if you are using a package that makes the double quote character active (e.g. ngerman) you can use: -


    \glsquote  ) you can +use: +


    \glsquote{text}

    -

    +

    which will produce "text". Alternatively, you can use \string" to write the double-quote -character. This document assumes that the double quote character has not been made active, -so the examples just use " for clarity. -

    If you want greater control over the \string" to write the double-quote character. This +document assumes that the double quote character has not been made active, so the examples just use " for +clarity. +

    If you want greater control over the xindy style file than is available through the -LATEX commands provided by the style file than is available through the LATEX commands +provided by the glossaries package, you will need to edit the xindy -style file. In which case, you must use style file. In which case, you must use +\noist to prevent the style file from being -overwritten by the glossaries package. For additional information about to prevent the style file from being overwritten by the glossaries package. For additional +information about xindy, read -the , read the xindy documentation. I’m sorry I can’t provide any assistance with writing - documentation. I’m sorry I can’t provide any assistance +with writing xindy style files. If you need help, I recommend you ask on the style files. If you need help, I recommend you ask on the xindy mailing list + id="dx1-142021"> mailing list (http://xindy.sourceforge.net/mailing-list.html). - -

    -

    Top

    11.1 Language and Encodings

    -

    When you use

    When you use xindy, you need to specify the language and encoding used (unless you -have written your own custom , you need to specify the language and encoding used (unless you have written your own + + +custom xindy style file that defines the relevant alphabet -and sort rules). If you use style file that defines the relevant alphabet and sort rules). If you use makeglossaries, this information is obtained from the -document’s auxiliary (.aux) file. The , +this information is obtained from the document’s auxiliary (aux) file. The makeglossaries script attempts to find the root -language given your document settings, but in the event that it gets it wrong or if - script +attempts to find the root language given your document settings, but in the event that it gets +it wrong or if xindy doesn’t support that language, then you can specify the required language + id="dx1-143006"> doesn’t support that language, then you can specify the required language using: -


    \GlsSetXdyLanguage 


    \GlsSetXdyLanguage[glossary type]{language}

    -

    +

    where ⟨language⟩ is the name of the language. The optional argument can be used if you have -multiple glossaries in different languages. If ⟨glossary type⟩ is omitted, it will be applied to all -glossaries, otherwise the language setting will only be applied to the glossary given by -⟨language⟩ is the name of the language. The optional argument can be used if you have multiple glossaries +in different languages. If ⟨glossary type⟩ is omitted, it will be applied to all glossaries, otherwise the language +setting will only be applied to the glossary given by ⟨glossary type⟩. -

    If the

    If the inputenc package is used, the encoding will be obtained from the value of - package is used, the encoding will be obtained from the value of \inputencodingname. Alternatively, you can specify the encoding using: -


    \GlsSetXdyCodePage  . +Alternatively, you can specify the encoding using: +


    \GlsSetXdyCodePage{code}

    -

    +

    where ⟨code⟩ is the name of the encoding. For example: - - + +

    -
    +
    \GlsSetXdyCodePage{utf8}
    -

    -

    Note that you can also specify the language and encoding using the package option +

    +

    Note that you can also specify the language and encoding using the package option xindy={language=lang,codepage=code}. For example: - - + +

    -
    +
    \usepackage[xindy={language=english,codepage=utf8}]{glossaries}
    -

    -

    If you write your own custom

    +

    If you write your own custom xindy style file that includes the language settings, you need -to set the language to nothing: - - + id="dx1-143011"> style file that includes the language settings, you need to set the +language to nothing: + +

    -
    +
    \GlsSetXdyLanguage{}
    -

    (and remember to use

    (and remember to use \noist to prevent the style file from being overwritten). -

    The commands to prevent the style file from being overwritten). +

    The commands \GlsSetXdyLanguage and \GlsSetXdyCodePage have no effect if -you don’t use \GlsSetXdyCodePage have no effect if you don’t use +makeglossaries. If you call . If you call xindy without without makeglossaries you -need to remember to set the language and encoding using the you need to remember to set the language and +encoding using the -L and and -C switches. -
    -

    -

    + id="dx1-143017"> switches.

    +

    +

    -

    Top

    11.2 Locations and Number lists

    -

    If you use

    If you use xindy, the glossaries package needs to know which counters you will be using in the -, the glossaries package needs to know which counters you will be using in the number list in order to correctly format the in +order to correctly format the xindy style file. Counters specified using the - style file. Counters specified using the counter package option or the ⟨counter⟩ option of package option or the ⟨counter⟩ +option of \newglossary are automatically taken -care of, but if you plan to use a different counter in the counter key for commands -like are automatically taken care of, but if you plan to use a different counter in the +counter key for commands like \glslink, then you need to identify these counters , then you need to identify these counters before \makeglossaries + id="dx1-144008"> using: -


    \GlsAddXdyCounters 


    \GlsAddXdyCounters{counter list}

    -

    +

    where ⟨counter list⟩ is a comma-separated list of counter names. -

    The most likely attributes used in the format key (

    The most likely attributes used in the format key (textrm, , hyperrm etc) are automatically -added to the etc) are automatically added to the +xindy style file, but if you want to use another attribute, you need to add it -using: -


    \GlsAddXdyAttribute  style file, but if you want to use another attribute, you need to add it using: +


    \GlsAddXdyAttribute{name}

    -

    +

    where ⟨name⟩ is the name of the attribute, as used in the format key. -

    Take care if you have multiple instances of the same location with different formats. The -duplicate locations will be discarded according to the order in which the attributes are -listed. Consider defining semantic commands to use for primary references. For -example: - - +class="cmtt-10">format key. +

    Take care if you have multiple instances of the same location with different formats. The duplicate locations +will be discarded according to the order in which the attributes are listed. Consider defining semantic commands +to use for primary references. For example: + +

    -
    +
    \newcommand*{\primary}[1]{\textbf{#1}}  
    \GlsAddXdyAttribute{primary}
    -

    Then in the document: - - +

    Then in the document: + +

    -
    +
    A \gls[format=primary]{duck} is an aquatic bird.  
    There are lots of different types of \gls{duck}.
    -

    This will give the format=primary instance preference over the next use that doesn’t use the -format key. +

    This will give the format=primary instance preference over the next use that doesn’t use the format +key. -

    +

    Example 17 (Custom Font for Displaying a Location) -

    Suppose I want a bold, italic, hyperlinked location. I first need to define a command that -will do this: - - + id="x1-144020"> +

    Suppose I want a bold, italic, hyperlinked location. I first need to define a command that will do +this: + +

    -
    +
    \newcommand*{\hyperbfit}[1]{\textit{\hyperbf{#1}}}
    -

    but with

    but with xindy, I also need to add this as an allowed attribute: - - + id="dx1-144021">, I also need to add this as an allowed attribute: + +

    -
    +
    \GlsAddXdyAttribute{hyperbfit}
    -

    Now I can use it in the optional argument of commands like

    Now I can use it in the optional argument of commands like \gls: - - + id="dx1-144023">: + +

    -
    +
    Here is a \gls[format=hyperbfit]{sample} entry.
    -

    (where

    (where sample is the label of the required entry).

    -

    -

    ____________________________

    -

    Note that

    +

    ____________________________

    +

    Note that \GlsAddXdyAttribute has no effect if \noist is used or if is used or if \makeglossaries is -omitted. is omitted. +\GlsAddXdyAttribute must be used before \makeglossaries. Additionally, -\GlsAddXdyCounters must come before . Additionally, \GlsAddXdyCounters must come +before \GlsAddXdyAttribute.
    -

    -

    If the location numbers include formatting commands, then you need to add a location -style in the appropriate format using -


    \GlsAddXdyLocation 

    +

    If the location numbers include formatting commands, then you need to add a location style in the +appropriate format using +


    \GlsAddXdyLocation[prefix-location]{name}{definition} -

    -

    +class="cmtt-10">}


    +

    where ⟨name⟩ is the name of the format and ⟨definition⟩ is the xindy definition. The optional -argument ⟨ definition. The optional argument +⟨prefix-location⟩ is needed if \theHcounter⟩ either isn’t defined or is different from -counter⟩ either isn’t defined or is different from \thecounter⟩. Be sure to also read §5.2 Locations for some issues that you may -encounter. -

    Note that counter⟩. Be sure to also +read §5.2 Locations for some issues that you may encounter. +

    Note that \GlsAddXdyLocation has no effect if \noist is used or if is used or if \makeglossaries is -omitted. is omitted. +\GlsAddXdyLocation must be used before \makeglossaries.
    -

    + id="dx1-144031">.

    +

    -

    +

    Example 18 (Custom Numbering System for Locations) -

    Suppose I decide to use a somewhat eccentric numbering system for sections where I -redefine \thesection as follows: - - + id="x1-144033"> +

    Suppose I decide to use a somewhat eccentric numbering system for sections where I redefine \thesection +as follows: + +

    -
    +
    \renewcommand*{\thesection}{[\thechapter]\arabic{section}}
    -

    If I haven’t done counter=section in the package option, I need to specify that the counter -will be used as a location number: - - +

    If I haven’t done counter=section in the package option, I need to specify that the counter will be used as a +location number: + +

    -
    +
    \GlsAddXdyCounters{section}
    -

    Next I need to add the location style (\thechapter is assumed to be the standard -

    Next I need to add the location style (\thechapter is assumed to be the standard \arabic{chapter}): - - + +

    -
    +
    \GlsAddXdyLocation{section}{:sep "[" "arabic-numbers" :sep "]"  
      "arabic-numbers"  
    }
    -

    Note that if I have further decided to use the

    Note that if I have further decided to use the hyperref package and want to redefine -\theHsection as: - - + id="dx1-144034"> package and want to redefine \theHsection +as: + +

    -
    +
    \renewcommand*{\theHsection}{\thepart.\thesection}  
    \renewcommand*{\thepart}{\Roman{part}}
    -

    then I need to modify the

    then I need to modify the \GlsAddXdyLocation code above to: - - + +

    -
    +
    \GlsAddXdyLocation["roman-numbers-uppercase"]{section}{:sep "["  
      "arabic-numbers" :sep "]" "arabic-numbers"  
    }
    -

    Since

    Since \Roman will result in an empty string if the counter is zero, it’s a good idea to add an -extra location to catch this: - - + id="dx1-144035"> will result in an empty string if the counter is zero, it’s a good idea to add an extra location to +catch this: + +

    -
    +
    \GlsAddXdyLocation{zero.section}{:sep "["  
      "arabic-numbers" :sep "]" "arabic-numbers"  
    }
    -

    This example is illustrated in the sample file

    This example is illustrated in the sample file samplexdy2.tex.

    -

    -

    ____________________________

    +

    +

    ____________________________

    -

    +

    Example 19 (Locations as Dice) -

    Suppose I want a rather eccentric page numbering system that’s represented by the -number of dots on dice. The +

    Suppose I want a rather eccentric page numbering system that’s represented by the number of +dots on dice. The stix package provides package provides \dicei, …, \dicevi that represent the six -sides of a die. I can define a command that takes a number as its argument. If the -number is less than seven, the appropriate \dicevi that represent the six sides of a die. I +can define a command that takes a number as its argument. If the number is less than seven, the +appropriate \dicen⟩ command is used otherwise it -does \dicevi the required number of times with the leftover in a final n⟩ command is used otherwise it does \dicevi the required number of times with the +leftover in a final \dicen⟩. For -example, the number 16 is represented by \dicevi\dicevi\diceiv (6 + 6 + 4 = 16). -I’ve called this command n⟩. For example, the number 16 is represented by \dicevi\dicevi\diceiv +(6 + 6 + 4 = 16). I’ve called this command \tallynum to match the example given earlier in §5.2 +href="#sec:locationsyntax">§5.2 Locations: - - + +

    -
    +
    \newrobustcmd{\tallynum}[1]{%  
     \ifnum\number#1<7  
      $\csname dice\romannumeral#1\endcsname$% @@ -17681,57 +19759,55 @@ href="#sec:locationsyntax">Locations:  
     \fi  
    }
    -

    Here’s the counter command: - - +

    Here’s the counter command: + +

    -
    +
    newcommand{\tally}[1]{\tallynum{\arabic{#1}}}
    -

    The

    The page counter representation ( counter representation (\thepage) needs to be changed to use this command: - - + +

    -
    +
    \renewcommand*{\thepage}{\tally{page}}
    -

    The

    The \tally command expands to \tallynum {number} so this needs a location class that -matches this format: - - +class="cmtt-10">} so this needs a location class that matches this +format: + +

    -
    +
    \GlsAddXdyLocation{tally}{%  
     :sep "\string\tallynum\space\glsopenbrace"  
     "arabic-numbers"  
     :sep "\glsclosebrace"  
    }
    -

    The space between

    The space between \tallynum and {number} is significant to xindy so \space is -required. -

    Note that so \space is required. +

    Note that \GlsAddXdyLocation{name}{definition} will define commands in the -form: -


    } will define commands in the form: +


    \glsXcounterXHprefix}{location}

    -

    +

    for each counter that has been identified either by the counter package option, the ⟨counter⟩ -option for package option, the ⟨counter⟩ option for +\newglossary or in the argument of or in the argument of \GlsAddXdyCounters. The first argument -⟨Hprefix⟩ is only relevant when used with the . The first argument ⟨Hprefix⟩ is only relevant when +used with the hyperref package and indicates that package and indicates that \theHcounter⟩ -is given by counter⟩ is given by \Hprefix.\thecounter⟩. -

    The sample file

    The sample file samplexdy.tex, which comes with the glossaries package, uses the default -glossaries package, uses the default page counter for locations, and it uses the default counter for +locations, and it uses the default \glsnumberformat and a custom - and a custom \hyperbfit format. A new xindy location called tallynum, as illustrated above, is defined -to make the page numbers appear as dice. In order for the location numbers to -hyperlink to the relevant pages, I need to redefine the necessary location +called tallynum, as illustrated above, is defined to make the page numbers appear as dice. In order for the +location numbers to hyperlink to the relevant pages, I need to redefine the necessary \glsXcounterXformat⟩ commands: - - + +

    -
    +
    \renewcommand{\glsXpageXglsnumberformat}[2]{%  
     \linkpagenumber#2%  
    } @@ -17796,20 +19870,19 @@ commands:  
    }  
    \newcommand{\linkpagenumber}[2]{\hyperlink{page.#2}{#1{#2}}}
    -

    Note that the second argument of

    Note that the second argument of \glsXpageXglsnumberformat is in the format \tallynum -{\tallynum{n} so the line - - +class="cmtt-10">} so the +line + +

    -
    +
     \linkpagenumber#2%
    -

    does

    +

    does

     \linkpagenumber\tallynum{}
    so \tallynum is the first argument of \linkpagenumber and ⟨number⟩ is the second -argument. +class="cmti-10">number⟩ is the second argument.
    -

    -

    ____________________________

    -

    This method is very sensitive to the internal definition of the location command. -
    -

    +

    +

    ____________________________

    +

    This method is very sensitive to the internal definition of the location command.
    +

    -

    +

    Example 20 (Locations as Words not Digits) -

    Suppose I want the page numbers written as words rather than digits and I use the - +

    Suppose I want the page numbers written as words rather than digits and I use the fmtcount package to do this. I can redefine package to do +this. I can redefine \thepage as follows: - - + id="dx1-144051"> as follows: + +

    -
    +
    \renewcommand*{\thepage}{\Numberstring{page}}
    -

    This

    This used to get expanded to \protect \Numberstringnum {n} where ⟨n⟩ is the -Arabic page number. This means that I needed to define a new location with the -form: - - +class="cmti-10">n⟩ is the Arabic page number. This +means that I needed to define a new location with the form: + +

    -
    +
    \GlsAddXdyLocation{Numberstring}{:sep "\string\protect\space  
      \string\Numberstringnum\space\glsopenbrace"  
      "arabic-numbers" :sep "\glsclosebrace"}
    -

    and if I’d used the \linkpagenumber command from the previous example, it would need -three arguments (the first being

    and if I’d used the \linkpagenumber command from the previous example, it would need three arguments (the +first being \protect): - - + +

    -
    +
    \newcommand{\linkpagenumber}[3]{\hyperlink{page.#3}{#1#2{#3}}}
    -

    -

    The internal definition of \Numberstring has since changed so that it now expands to -

    +

    The internal definition of \Numberstring has since changed so that it now expands to \Numberstringnum   +{n} (no \protect). This means that the location class definition must be -changed to: - - +class="cmtt-10">\protect). This means that the location class definition must be changed to: + +

    -
    +
    \GlsAddXdyLocation{Numberstring}{% no \protect now!  
      :sep "\string\Numberstringnum\space\glsopenbrace"  
      "arabic-numbers" :sep "\glsclosebrace"}
    -

    and

    and \linkpagenumber goes back to only two arguments: - - + +

    -
    +
    \newcommand{\linkpagenumber}[2]{\hyperlink{page.#2}{#1{#2}}}
    -

    The other change is that

    The other change is that \Numberstring uses

    \endcsname
    so it hides \c@page from the location escaping mechanism (see §5.2 Locations). This means -that the page number may be incorrect if the indexing occurs during the output -routine. -

    A more recent change to §5.2 Locations). This means that the page +number may be incorrect if the indexing occurs during the output routine. +

    A more recent change to fmtcount (v3.03) now puts three instances of \expandafter -before (v3.03) now puts three instances of \expandafter before +\the\value which no longer hides \c@page from the location escaping mechanism, so -the page numbers should once more be correct. Further changes to the \c@page from the location escaping mechanism, so the page +numbers should once more be correct. Further changes to the fmtcount package may -cause a problem again. -

    When dealing with custom formats where the internal definitions are outside of your -control and liable to change, it’s best to provide a wrapper command.
    -

    -

    Instead of directly using package may cause a problem +again. +

    When dealing with custom formats where the internal definitions are outside of your control and liable to +change, it’s best to provide a wrapper command.
    +

    +

    Instead of directly using \Numberstring in the definition of \thepage, I can provide a -custom command in the same form as the earlier \thepage, I can provide a custom command in +the same form as the earlier \tally command: - - + +

    -
    +
    \newcommand{\customfmt}[1]{\customfmtnum{\arabic{#1}}}  
    \newrobustcmd{\customfmtnum}[1]{\Numberstringnum{#1}}
    -

    This ensures that the location will always be written to the indexing file in the form: -

    +

    This ensures that the location will always be written to the indexing file in the form:

    :locrefn}}"
    So the location class can be defined as: - - -
    + + +
    \GlsAddXdyLocation{customfmt}{  
     :sep "\string\customfmtnum\space\glsopenbrace"  
     "arabic-numbers"  
     :sep "\glsclosebrace"}
    -

    -

    The sample file

    +

    The sample file samplexdy3.tex illustrates this.

    -

    -

    ____________________________

    -

    In the

    +

    ____________________________

    +

    In the number list, the locations are sorted according to the list of provided location classes. + id="dx1-144054">, the locations are sorted according to the list of provided location classes. The default ordering is: roman-page-numbers (i, ii, …), arabic-page-numbers (1, 2, …), @@ -17989,41 +20055,36 @@ class="cmtt-10">arabic-page-numbers (1, 2, …), class="cmtt-10">arabic-section-numbers (for example, 1.1 if the compositor is a full stop or 1-1 if the compositor is a hyphen11.1), + id="x1-144055f1">), alpha-page-numbers (a, b, …), Roman-page-numbers (I, II, …), +class="cmtt-10">Roman-page-numbers (I, II, …), Alpha-page-numbers (A, B, …), Alpha-page-numbers (A, B, …), Appendix-page-numbers (for example, A.1 -if the Alpha compositor is a full stop or A-1 if the Alpha compositor is a +class="cmtt-10">Appendix-page-numbers (for example, A.1 if the Alpha compositor is a full stop or A-1 if the Alpha compositor is a hyphen11.2), -user defined location names (as specified by ), user defined +location names (as specified by \GlsAddXdyLocation in -the order in which they were defined), and finally in the order in which they were defined), and finally see (cross-referenced entries).11.3 + id="x1-144060f3"> This ordering can be changed using: -


    \GlsSetXdyLocationClassOrder 


    \GlsSetXdyLocationClassOrder{location names} -

    -

    -where each location name is delimited by double quote marks and separated by white space. -For example: - - +class="cmtt-10">}


    +

    +where each location name is delimited by double quote marks and separated by white space. For +example: + +

    -
    +
    \GlsSetXdyLocationClassOrder{  
      "arabic-page-numbers"  
      "arabic-section-numbers" @@ -18035,129 +20096,116 @@ For example:  
      "see"  
    }
    -

    (Remember to add

    (Remember to add "seealso" if you’re using glossaries-extra.) -

    Note that

    Note that \GlsSetXdyLocationClassOrder has no effect if \noist is used or if - is used or if \makeglossaries is omitted. \GlsSetXdyLocationClassOrder must be used before - is +omitted. \GlsSetXdyLocationClassOrder must be used before \makeglossaries.
    -

    -

    If a .

    +

    +

    If a number list consists of a sequence of consecutive numbers, the range will be -concatenated. The number of consecutive locations that causes a range formation defaults to -2, but can be changed using: -


    \GlsSetXdyMinRangeLength  consists of a sequence of consecutive numbers, the range will be concatenated. The +number of consecutive locations that causes a range formation defaults to 2, but can be changed +using: +


    \GlsSetXdyMinRangeLength{n}

    -

    +

    For example: - - + +

    -
    +
    \GlsSetXdyMinRangeLength{3}
    -

    The argument may also be the keyword none, to indicate that there should be no range -formations. See the

    The argument may also be the keyword none, to indicate that there should be no range formations. See the +xindy manual for further details on range formations. -

    Note that manual for further details on range formations. +

    Note that \GlsSetXdyMinRangeLength has no effect if \noist is used or if - is used or if \makeglossaries is omitted. \GlsSetXdyMinRangeLength must be used before + id="dx1-144069"> is omitted. \GlsSetXdyMinRangeLength must be used before \makeglossaries.
    -

    + id="dx1-144070">.

    +

    See also §5.3 §5.3 Range Formations. -

    +

    -

    Top

    11.3 Glossary Groups

    -

    The glossary is divided into groups according to the first letter of the sort key. The glossaries -package also adds a number group by default, unless you suppress it in the

    The glossary is divided into groups according to the first letter of the sort key. The glossaries package also adds a +number group by default, unless you suppress it in the xindy package -option. For example: - - + id="dx1-145001"> package option. For example: + +

    -
    +
    \usepackage[xindy={glsnumbers=false}]{glossaries}
    -

    Any entry that doesn’t go in one of the letter groups or the number group is placed in the -default group. If you want

    Any entry that doesn’t go in one of the letter groups or the number group is placed in the default group. If you +want xindy to sort the number group numerically (rather than by a -string sort) then you need to use to sort the number group numerically (rather than by a string sort) then you need to use xindy’s ’s +numeric-sort module: - - + +

    -
    +
    \GlsAddXdyStyle{numeric-sort}
    -

    -

    If you don’t use glsnumbers=false, the default behaviour is to locate the number group -before the “A” letter group. If you are not using a Roman alphabet, you need to change this -using: -


    \GlsSetXdyFirstLetterAfterDigits 

    +

    If you don’t use glsnumbers=false, the default behaviour is to locate the number group before the “A” +letter group. If you are not using a Roman alphabet, you need to change this using: +


    \GlsSetXdyFirstLetterAfterDigits{letter} -

    -

    +class="cmtt-10">}


    +

    where ⟨letter⟩ is the first letter of your alphabet. Take care if you’re using inputenc as -non-ASCII characters are actually active characters that expand. (This isn’t a problem with -the native UTF-8 engines and as non-ASCII characters are +actually active characters that expand. (This isn’t a problem with the native UTF-8 engines and +fontspec.) The starred form will sanitize the argument to -prevent expansion. Alternatively you can use: -


    \GlsSetXdyNumberGroupOrder  .) The starred form will sanitize the argument to prevent expansion. Alternatively you can +use: +


    \GlsSetXdyNumberGroupOrder{relative location} -

    -

    +class="cmtt-10">}


    +

    to change the default

    \string"
    to ⟨relative location⟩. For example: - - -
    + + +
    \GlsSetXdyNumberGroupOrder{:after \string"Z\string"}
    -

    will put the number group after the “Z” letter group. Again take care of active characters. -There’s a starred version that sanitizes the argument (so don’t use \string in it). -

    +

    will put the number group after the “Z” letter group. Again take care of active characters. There’s a starred +version that sanitizes the argument (so don’t use \string in it).

    \GlsSetXdyNumberGroupOrder*"}
    -

    Note that these commands have no effect if

    Note that these commands have no effect if \noist is used or if is used or if \makeglossaries is -omitted. is omitted. +\GlsSetXdyFirstLetterAfterDigits must be used before \makeglossaries. + id="dx1-145010">.
    -

    - - +

    + +

    -

    -

    +

    Top

    12. Defining New Glossaries

    -

    A new glossary can be defined using: -


    \newglossary 

    A new glossary can be defined using: +


    \newglossary[log-ext]{title}[counter]

    -

    +

    where ⟨name⟩ is the label to assign to this glossary. The arguments ⟨in-ext⟩ and ⟨out-ext⟩ specify -the extensions to give to the input and output files for that glossary, ⟨title⟩ is the default title -for this new glossary and the final optional argument ⟨counter⟩ specifies which counter to use -for the associated out-ext⟩ specify the extensions to +give to the input and output files for that glossary, ⟨title⟩ is the default title for this new glossary and the final +optional argument ⟨counter⟩ specifies which counter to use for the associated number lists (see also §5 Number lists). The first optional argument -specifies the extension for the s (see also §5 Number +lists). The first optional argument specifies the extension for the makeindex ( (Option 2) or xindy (Option 3) transcript file (this -information is only used by +(Option 3) transcript file (this information is only used by makeglossaries which picks up the information from the -auxiliary file). If you use which picks up the +information from the auxiliary file). If you use Option 1, the ⟨log-ext⟩, ⟨in-ext⟩ and ⟨out-ext⟩ arguments are ignored. -

    The glossary label ⟨name⟩ must not contain any active characters. It’s generally best to -stick with just characters that have category code 11 (typically the non-extended Latin -characters for standard LATEX).
    -

    -

    There is also a starred version (new to v4.08): -


    \newglossary* 

    The glossary label ⟨name⟩ must not contain any active characters. It’s generally best to stick with just +characters that have category code 11 (typically the non-extended Latin characters for standard LATEX). +
    +

    +

    There is also a starred version (new to v4.08): +


    \newglossary*{name}{title}[counter]

    -

    +

    which is equivalent to

    counter]
    or you can also use: -


    \altnewglossary 


    \altnewglossary{name}{title}[counter]

    -

    +

    which is equivalent to

    counter]
    -

    It may be that you have some terms that are so common that they don’t need to be listed. -In this case, you can define a special type of glossary that doesn’t create any associated files. -This is referred to as an “ignored glossary” and it’s ignored by commands that iterate -over all the glossaries, such as

    It may be that you have some terms that are so common that they don’t need to be listed. In this case, you +can define a special type of glossary that doesn’t create any associated files. This is referred to as an “ignored +glossary” and it’s ignored by commands that iterate over all the glossaries, such as \printglossaries. To define an ignored glossary, -use -


    \newignoredglossary  . To +define an ignored glossary, use +


    \newignoredglossary{name}

    -

    +

    where ⟨name⟩ is the name of the glossary (as above). This glossary type will automatically be - - -added to the name⟩ is the name of the glossary (as above). This glossary type will automatically be added to the +nohypertypes list, since there are no hypertargets for the entries in -an ignored glossary. (The sample file sample-entryfmt.tex defines an ignored -glossary.) -

    You can test if a glossary is an ignored one using: -


    \ifignoredglossary  list, since there are no hypertargets for the entries in an ignored glossary. (The sample file +sample-entryfmt.tex defines an ignored glossary.) + + +

    The glossaries-extra package provides a starred version of this command that allows hyperlinks (since +ignored glossaries can be useful with bib2gls). There is also an analogous \provideignoredglossary +command.
    +

    +

    You can test if a glossary is an ignored one using: +


    \ifignoredglossary{name}{true}{false}

    -

    +

    This does ⟨true⟩ if ⟨name⟩ was defined as an ignored glossary, otherwise it does ⟨false⟩. -

    Note that the main (default) glossary is automatically created as: - - +

    Note that the main (default) glossary is automatically created as: + +

    -
    +
    \newglossary{main}{gls}{glo}{\glossaryname}
    -

    so it can be identified by the label

    so it can be identified by the label main (unless the nomain package option is used). Using -the package option is used). Using the acronym package option is equivalent to: - - + id="dx1-146016"> package +option is equivalent to: + +

    -
    +
    \newglossary[alg]{acronym}{acr}{acn}{\acronymname}
    -

    so it can be identified by the label

    so it can be identified by the label acronym. If you are not sure whether the acronym -option has been used, you can identify the list of acronyms by the command -\acronymtype  option has been used, you +can identify the list of acronyms by the command \acronymtype which is set to acronym, if the acronym option has been used, -otherwise it is set to main. Note that if you are using the main glossary as your list of -acronyms, you need to declare it as a list of acronyms using the package option + id="dx1-146019"> +option has been used, otherwise it is set to main. Note that if you are using the main glossary +as your list of acronyms, you need to declare it as a list of acronyms using the package option acronymlists. -

    The . +

    The symbols package option creates a new glossary with the label package option creates a new glossary with the label symbols using: - - + +

    -
    +
    \newglossary[slg]{symbols}{sls}{slo}{\glssymbolsgroupname}
    -

    The

    The numbers package option creates a new glossary with the label package option creates a new glossary with the label numbers using: - - + +

    -
    +
    \newglossary[nlg]{numbers}{nls}{nlo}{\glsnumbersgroupname}
    -

    The

    The index package option creates a new glossary with the label package option creates a new glossary with the label index using: - - + +

    -
    +
    \newglossary[ilg]{index}{ind}{idx}{\indexname}
    -

    -

    Options 

    +

    Options 2 and 3: all glossaries must be defined before \makeglossaries to ensure that -the relevant output files are opened. -

    See §1.4.1 to ensure that the relevant output +files are opened. +

    See §1.3.1 Changing the Fixed Names if you want to redefine \glossaryname, -especially if you are using \glossaryname, especially if you are using +babel or or translator. (Similarly for \glssymbolsgroupname and -\glsnumbersgroupname.) If you want to redefine . (Similarly for \glssymbolsgroupname and \glsnumbersgroupname.) If you +want to redefine \indexname, just follow the advice in How -to change LaTeX’s “fixed names”.

    -

    - - -

    -

    -

    , just follow the advice in How to change LaTeX’s “fixed names”. +

    +

    + + +

    +

    +

    Top

    13. Acronyms and Other Abbreviations

    -

    The glossaries-extra package provides superior abbreviation handling. You may want to -consider using that package instead of the commands described here. -

    Note that although this chapter uses the term “acronym”, you can also use the -commands described here for initialisms or contractions (as in the case of some of the -examples given below). If the glossary title is no longer applicable (for example, -it should be “Abbreviations” rather than “Acronyms”) then you can change the +

    The glossaries-extra package provides superior abbreviation handling. You may want to consider using that +package instead of the commands described here.
    +

    +

    Note that although this chapter uses the term “acronym”, you can also use the commands described here +for initialisms or contractions (as in the case of some of the examples given below). If the glossary title is no +longer applicable (for example, it should be “Abbreviations” rather than “Acronyms”) then you can change the title either by redefining \acronymname (see §1.4 Multi-Lingual Support) or by -using the title in the optional argument of (see §1.3 Multi-Lingual Support) or by using the title in the optional +argument of \printglossary (or \printacronym). -Alternatively consider using the glossaries-extra package’s abbreviations option instead. -
    -

    -

    You may have noticed in §4 Defining Glossary Entries that when you specify a new entry, -you can specify alternate text to use when the term is first used in the document. This -provides a useful means to define abbreviations. For convenience, the glossaries package -defines the command: -


    \newacronym  (or \printacronyms). Alternatively consider using the glossaries-extra package’s +abbreviations option instead.
    +

    +

    You may have noticed in §4 Defining Glossary Entries that when you specify a new entry, you can specify +alternate text to use when the term is first used in the document. This provides a useful means to define +abbreviations. For convenience, the glossaries package defines the command: +


    \newacronym[key-val list]{abbrv}{long}

    -

    -

    This uses

    +

    This uses \newglossaryentry to create an entry with the given label in the glossary given -by to create an entry with the given label in the glossary given by +\acronymtype. You can specify a different glossary using the type key within the optional -argument. The . You can specify a different glossary using the type key within the optional argument. The +\newacronym command also uses the long, longplural, short and shortplural -keys in \newglossaryentry to store the long and abbreviated forms and their -plurals. -

    Note that the same restrictions on the entry ⟨long, longplural, short and shortplural keys in \newglossaryentry +to store the long and abbreviated forms and their plurals. +

    Note that the same restrictions on the entry ⟨label⟩ in \newglossaryentry also apply to - also apply to \newacronym (see §4 §4 +Defining Glossary Entries). -

    If you haven’t identified the specified glossary type as a list of acronyms (via -the package option

    If you haven’t identified the specified glossary type as a list of acronyms (via the package option acronymlists or the command +or the command \DeclareAcronymList, see §2.5 -Acronym Options) \newacronym will add it to the list and reset the display style -for that glossary via , see §2.7 Acronym and Abbreviation Options) \newacronym will add it +to the list and reset the display style for that glossary via \defglsentryfmt. If you have a mixture of acronyms and -regular entries within the same glossary, care is needed if you want to change the -display style: you must first identify that glossary as a list of acronyms and then -use . If you have a mixture of acronyms +and regular entries within the same glossary, care is needed if you want to change the display style: you must +first identify that glossary as a list of acronyms and then use \defglsentryfmt (not redefine (not redefine \glsentryfmt) before defining your entries. -
    -

    -

    The optional argument ) +before defining your entries.

    +

    +

    The optional argument {key-val list} allows you to specify additional information. Any -key that can be used in the second argument of } allows you to specify additional information. Any key that can be used +in the second argument of \newglossaryentry can also be used -here in ⟨ can also be used here in ⟨key-val list⟩. For example, description (when used with one of the styles that -require a description, described in §13.1 Changing the Abbreviation Style) or you can -override plural forms of ⟨description +(when used with one of the styles that require a description, described in §13.1 Changing the Abbreviation Style) +or you can override plural forms of ⟨abbrv⟩ or ⟨long⟩ using the shortplural or longplural keys. For +class="cmtt-10">shortplural or longplural keys. For example: - - + +

    -
    +
    \newacronym[longplural={diagonal matrices}]%  
      {dm}{DM}{diagonal matrix}
    -

    If the

    If the first use uses the plural form, \glspl{dm} will display: diagonal matrices -(DMs). If you want to use the longplural or shortplural keys, I recommend you use +class="cmtt-10">\glspl{dm} will display: diagonal matrices (DMs). If you want to use the longplural or shortplural keys, I recommend you use \setacronymstyle to set the display style rather than using one of the pre-version 4.02 -acronym styles. -

    As with plural and firstplural, if longplural is missing, it’s obtained by appended - to set the display style rather than +using one of the pre-version 4.02 acronym styles. +

    As with plural and firstplural, if longplural is missing, it’s obtained by appended \glspluralsuffix to the singular form. The short plural shortplural is obtained (is not -explicitly set) by appending +to the singular form. The short plural shortplural is obtained (is not explicitly set) by appending +\glsacrpluralsuffix to the short form. These commands may -be changed by the associated language files, but they can’t be added to the usual -caption hooks as there’s no guarantee when they’ll be expanded (as discussed earlier). -A different approach is used by glossaries-extra, which has category attributes to -determine whether or not to append a suffix when forming the default value of -shortplural. -

    Since to the short form. These commands may be changed by the associated +language files, but they can’t be added to the usual caption hooks as there’s no guarantee when +they’ll be expanded (as discussed earlier). A different approach is used by glossaries-extra, which has +category attributes to determine whether or not to append a suffix when forming the default value of +shortplural. +

    Since \newacronym uses uses \newglossaryentry, you can use commands like , you can use commands like \gls and - and \glsreset as with any other glossary entry. -

    Since as with any +other glossary entry. +

    Since \newacronym sets type=\acronymtype, if you want to load a file containing -acronym definitions using type=\acronymtype, if you want to load a file containing acronym definitions using +\loadglsentries[type]{filename}, the optional argument ⟨type⟩ -will not have an effect unless you explicitly set the type as type=\glsdefaulttype -in the optional argument to type⟩ will not have an effect unless you explicitly set +the type as type=\glsdefaulttype in the optional argument to \newacronym. See §4.6 Loading Entries From a File. -
    -

    + id="dx1-147040">. See §4.6 Loading Entries From a +File.

    +

    -

    +

    Example 21 (Defining an Abbreviation) -

    The following defines the abbreviation IDN: - - + id="x1-147042"> +

    The following defines the abbreviation IDN: + +

    -
    +
    \newacronym{idn}{IDN}{identification number}
    -

    \gls{idn} will produce “identification number (IDN)” on first use and “IDN” on -subsequent uses. If you want to use one of the smallcaps acronym styles, described in §13.1 -Changing the Abbreviation Style, you need to use lower case characters for the shortened -form: - - +href="#glo:firstuse">first use and “IDN” on subsequent uses. If you want +to use one of the small caps acronym styles, described in §13.1 Changing the Abbreviation Style, you need to use +lower case characters for the shortened form: + +

    -
    +
    \newacronym{idn}{idn}{identification number}
    -

    Now

    Now \gls{idn} will produce “identification number (ifirst use and “idn” on -subsequent uses.

    +class="small-caps">n” on subsequent uses. +

    -

    -

    ____________________________

    -

    Avoid nested definitions.
    -

    -

    Recall from the warning in §4 Defining Glossary Entries that you should avoid using the -

    +

    ____________________________

    +

    Avoid nested definitions.
    +

    +

    Recall from the warning in §4 Defining Glossary Entries that you should avoid using the \gls-like and \gls-like and +\glstext-like commands within the value of keys like text and first due to -complications arising from nested links. The same applies to abbreviations defined using -text and first due to complications arising from nested +links. The same applies to abbreviations defined using \newacronym. -

    For example, suppose you have defined: - - +

    For example, suppose you have defined: + +

    -
    +
    \newacronym{ssi}{SSI}{server side includes}  
    \newacronym{html}{HTML}{hypertext markup language}
    -

    you may be tempted to do: - - +

    you may be tempted to do: + +

    -
    +
    \newacronym{shtml}{S\gls{html}}{\gls{ssi} enabled \gls{html}}
    -

    Don’t! This will break the case-changing commands, such as

    Don’t! This will break the case-changing commands, such as \Gls, it will cause -inconsistencies on first use, and, if hyperlinks are enabled, will cause nested hyperlinks. It will -also confuse the commands used by the entry formatting (such as , it will cause inconsistencies on first use, and, +if hyperlinks are enabled, will cause nested hyperlinks. It will also confuse the commands used by the entry +formatting (such as \glslabel). -

    Instead, consider doing: - - + id="dx1-147047">). +

    Instead, consider doing: + +

    -
    +
    \newacronym  
     [description={\gls{ssi} enabled \gls{html}}]  
     {shtml}{SHTML}{SSI enabled HTML}
    -

    or - - +

    or + +

    -
    +
    \newacronym  
     [description={\gls{ssi} enabled \gls{html}}]  
     {shtml}{SHTML}  
     {server side includes enabled hypertext markup language}
    -

    Similarly for the

    Similarly for the \glstext-like commands. -

    Other approaches are available with glossaries-extra. See the section “Nested Links” in the -glossaries-extra user manual. -

    The commands described below are similar to the

    Other approaches are available with glossaries-extra. See the section “Nested Links” in the glossaries-extra +user manual. +

    The commands described below are similar to the \glstext-like commands in that they -don’t modify the \glstext-like commands in that they don’t modify the +first use flag. However, their display is governed by \defentryfmt with - with \glscustomtext set as appropriate. All caveats that apply to the set as appropriate. All +caveats that apply to the \glstext-like commands -also apply to the following commands. (Including the warning immediately above this box.) -
    -

    -

    The optional arguments are the same as those for the \glstext-like commands also apply to the following commands. (Including the +warning immediately above this box.)

    +

    +

    The optional arguments are the same as those for the \glstext-like commands, -and there are similar star and plus variants that switch off or on the hyperlinks. -As with the \glstext-like commands, and there are similar star +and plus variants that switch off or on the hyperlinks. As with the \glstext-like commands, the link text is placed in the argument of - is +placed in the argument of \glstextformat. -


    \acrshort  . +


    \acrshort[options]{label}[insert]

    -

    +

    This sets the link text to the short form (within the argument of to the short form (within the argument of \acronymfont) for the entry -given by ⟨label⟩. The short form is as supplied by the short key, which ) for the entry given by ⟨label⟩. +The short form is as supplied by the short key, which \newacronym implicitly -sets. -

    There are also analogous upper case variants: -


    \Acrshort  implicitly sets. +

    There are also analogous upper case variants: +


    \Acrshort[options]{label}[insert]

    -

    -


    \ACRshort 

    +


    \ACRshort[options]{label}[insert]

    -

    +

    There are also plural versions: -


    \acrshortpl 


    \acrshortpl[options]{label}[insert]

    -

    -


    \Acrshortpl 

    +


    \Acrshortpl[options]{label}[insert]

    -

    -


    \ACRshortpl 

    +


    \ACRshortpl[options]{label}[insert]

    -

    +

    The short plural form is as supplied by the shortplural key, which shortplural key, which \newacronym implicitly -sets. -


    \acrlong  implicitly sets. +


    \acrlong[options]{label}[insert]

    - - -

    +

    This sets the link text to the long form for the entry given by ⟨label⟩. The long form is as -supplied by the long key, which to the long form for the entry given by ⟨label⟩. The long form is as supplied by the long +key, which \newacronym implicitly sets. -

    There are also analogous upper case variants: -


    \Acrlong  implicitly sets. +

    There are also analogous upper case variants: +


    \Acrlong[options]{label}[insert]

    -

    -


    \ACRlong 

    +


    \ACRlong[options]{label}[insert]

    -

    +

    Again there are also plural versions: -


    \acrlongpl 


    \acrlongpl[options]{label}[insert]

    -

    -


    \Acrlongpl 

    +


    \Acrlongpl[options]{label}[insert]

    -

    -


    \ACRlongpl 

    +


    \ACRlongpl[options]{label}[insert]

    -

    +

    The long plural form is as supplied by the longplural key, which longplural key, which \newacronym implicitly -sets. -

    The commands below display the full form of the acronym, but note that this isn’t -necessarily the same as the form used on first use. These full-form commands are shortcuts -that use the above commands, rather than creating the implicitly sets. +

    The commands below display the full form of the acronym, but note that this isn’t necessarily the same as +the form used on first use. These full-form commands are shortcuts that use the above commands, rather than +creating the link text from the complete full form. -These full-form commands have star and plus variants and optional arguments that are -passed to the above commands. -


    \acrfull  from the complete full form. These full-form commands have star and plus variants and +optional arguments that are passed to the above commands. +


    \acrfull[options]{label}[insert]

    -

    +

    This is a shortcut for -


    \acrfullfmt 


    \acrfullfmt{options}{label}{insert}

    -

    +

    which by default does

    \acrfullformat
     {\acrlong[ {\acrlong[options]{label}{insert}} +class="cmtt-10">}}
     {\acrshort[ {\acrshort[options]{label}} +class="cmtt-10">}}
    where -


    \acrfullformat 


    \acrfullformat{long}{short}

    -

    +

    by default does ⟨long⟩ (⟨short⟩). This command is now deprecated for new acronym styles but is -used by the default for backward compatibility if short⟩). This command is now deprecated for new acronym styles but is used by +the default for backward compatibility if \setacronymstyle (§13.1 Changing the -Abbreviation Style) hasn’t been used. (For further details of these format commands see the -documented code, §13.1 Changing the Abbreviation +Style) hasn’t been used. (For further details of these format commands see the documented code, +glossaries-code.pdf.) -

    There are also analogous upper case variants: -


    \Acrfull 

    There are also analogous upper case variants: +


    \Acrfull[options]{label}[insert]

    - - -

    -


    \ACRfull 

    +


    \ACRfull[options]{label}[insert]

    -

    +

    and plural versions: -


    \acrfullpl 


    \acrfullpl[options]{label}[insert]

    -

    -


    \Acrfullpl 

    +


    \Acrfullpl[options]{label}[insert]

    -

    -


    \ACRfullpl 

    +


    \ACRfullpl[options]{label}[insert]

    -

    -

    If you find the above commands too cumbersome to write, you can use the

    +

    If you find the above commands too cumbersome to write, you can use the shortcuts -package option to activate the shorter command names listed in package option to +activate the shorter command names listed in table 13.1.

    - - -


    - - + +
    Table 13.1: Synonyms provided by the package option shortcuts
    +class="cmss-10">shortcuts
    Equivalent Command style="vertical-align:baseline;" id="TBL-7-2-"> + id="dx1-147087"> + id="dx1-147089"> + id="dx1-147091"> + id="dx1-147093"> + id="dx1-147095"> + id="dx1-147097"> + id="dx1-147099"> + id="dx1-147101"> + id="dx1-147103"> + id="dx1-147105"> + id="dx1-147107"> + id="dx1-147109"> + id="dx1-147111"> + id="dx1-147113"> + id="dx1-147115">
    \acs \acrshort
    \Acs \Acrshort
    \acsp \acrshortpl
    \Acsp \Acrshortpl
    \acl \acrlong
    \Acl \Acrlong
    \aclp \acrlongpl
    \Aclp \Acrlongpl
    \acf \acrfull
    \Acf \Acrfull
    \acfp \acrfullpl
    \Acfp \Acrfullpl
    \ac \gls
    \Ac \Gls
    \acp \glspl
    \Acp \Glspl
    + id="dx1-147117">
    - - + +

    -

    It is also possible to access the long and short forms without adding information to the -glossary using commands analogous to

    It is also possible to access the long and short forms without adding information to the glossary using +commands analogous to \glsentrytext (described in §9 Using Glossary Terms -Without Links). -

    The commands that convert the first letter to upper case come with the same caveats as -those for analogous commands like (described in §9 Using Glossary Terms Without Links). +

    The commands that convert the first letter to upper case come with the same caveats as those for analogous +commands like \Glsentrytext (non-expandable, can’t be used in PDF -bookmarks, care needs to be taken if the first letter is an accented character etc). See §9 -Using Glossary Terms Without Links.
    -

    -

    The long form can be accessed using: -


    \glsentrylong  (non-expandable, can’t be used in PDF bookmarks, care needs to be +taken if the first letter is an accented character etc). See §9 Using Glossary Terms Without Links. +
    +

    +

    The long form can be accessed using: +


    \glsentrylong{label}

    -

    +

    or, with the first letter converted to upper case: -


    \Glsentrylong 


    \Glsentrylong{label}

    -

    +

    Plural forms: -


    \glsentrylongpl 


    \glsentrylongpl{label}

    -

    -


    \Glsentrylongpl 

    +


    \Glsentrylongpl{label}

    -

    -

    Similarly, to access the short form: -


    \glsentryshort 

    +

    Similarly, to access the short form: +


    \glsentryshort{label}

    -

    +

    or, with the first letter converted to upper case: -


    \Glsentryshort 


    \Glsentryshort{label}

    -

    +

    Plural forms: -


    \glsentryshortpl 


    \glsentryshortpl{label}

    -

    -


    \Glsentryshortpl 

    +


    \Glsentryshortpl{label}

    -

    -

    And the full form can be obtained using: -


    \glsentryfull 

    +

    And the full form can be obtained using: +


    \glsentryfull{label}

    -

    -


    \Glsentryfull 

    +


    \Glsentryfull{label}

    -

    -


    \glsentryfullpl 

    +


    \glsentryfullpl{label}

    - - -

    -


    \Glsentryfullpl 

    + + +


    \Glsentryfullpl{label}

    -

    +

    These again use \acrfullformat by default, but the new styles described in the section -below use different formatting commands. + id="dx1-147132"> by default, but the new styles described in the section below use different +formatting commands.

    -

    Top

    13.1 Changing the Abbreviation Style

    -

    It may be that the default style doesn’t suit your requirements in which case you can switch -to another style using -


    \setacronymstyle 

    It may be that the default style doesn’t suit your requirements in which case you can switch to another style +using +


    \setacronymstyle{style name}

    -

    +

    where ⟨style name⟩ is the name of the required style. -

    You must use

    You must use \setacronymstyle before you define the acronyms with \newacronym. -
    -

    -

    For example: - - +class="cmtt-10">\newacronym.

    +

    +

    For example: + +

    -
    +
    \usepackage[acronym]{glossaries}  
    \makeglossaries  
    \setacronymstyle{long-sc-short}  
    \newacronym{html}{html}{hypertext markup language}  
    \newacronym{xml}{xml}{extensible markup language}
    -

    Unpredictable results can occur if you try to use multiple styles. -

    If you need multiple abbreviation styles, then try using the

    Unpredictable results can occur if you try to use multiple styles. +

    If you need multiple abbreviation styles, then try using the glossaries-extra package, which -has better abbreviation management.
    -

    -

    Note that unlike the default behaviour of \newacronym, the styles used via -glossaries-extra package, which has better +abbreviation management.

    +

    +

    Unlike the default behaviour of \newacronym, the styles used via \setacronymstyle don’t use the first or text keys, but instead they use first or +text keys, but instead they use \defglsentryfmt to -set a custom format that uses the long and short keys (or their plural equivalents). This -means that these styles cope better with plurals that aren’t formed by simply appending the -singular form with the letter “s”. In fact, most of the predefined styles use to set a custom format that uses the long and short keys +(or their plural equivalents). This means that these styles cope better with plurals that aren’t formed by simply +appending the singular form with the letter “s”. In fact, most of the predefined styles use \glsgenacfmt and + id="dx1-148007"> and modify the definitions of commands like \genacrfullformat. -

    Note that when you use . +

    Note that when you use \setacronymstyle the name key is set to -


    \acronymentry  name key is set to +


    \acronymentry{label}

    -

    +

    and the sort key is set to -


    \acronymsort  sort key is set to +


    \acronymsort{short}{long}

    -

    -These commands are redefined by the acronym styles. However, you can redefine them again -after the style has been set but before you use \newacronym. Protected expansion is -performed on \acronymsort when the entry is defined. -

    -

    -

    +These commands are redefined by the acronym styles. However, you can redefine them again after the style has +been set but before you use \newacronym. Protected expansion is performed on \acronymsort when the entry is +defined. +

    +

    +

    Top

    13.1.1 Predefined Acronym Styles

    -

    The

    The glossaries package provides a number of predefined styles. These styles apply -


    \firstacronymfont 


    \firstacronymfont{text}

    -

    +

    to the short form on first use and -


    \acronymfont 


    \acronymfont{text}

    -

    +

    on subsequent use. The styles modify the definition of \acronymfont as required, but -\acronymfont as required, but \firstacronymfont is only set once by the package when it’s loaded. By default - - - is +only set once by the package when it’s loaded. By default \firstacronymfont{text} is the same as } is the same as +\acronymfont{text}. If you want the short form -displayed differently on first use, you can redefine }. If you want the short form displayed differently on first use, you can redefine +\firstacronymfont independently of the -acronym style. -

    The predefined styles that contain independently of the acronym style. + + +

    The predefined styles that contain sc in their name (for example long-sc-short) redefine + id="dx1-149007">) redefine \acronymfont to use \acronymfont to use \textsc, which means that the short form needs to be specified in lower -case. -

    , which means that the short form needs to be specified in lower case. +

    -

    Some fonts don’t support bold smallcaps, so you may need to redefine

    Some fonts don’t support bold small caps, so you may need to redefine \glsnamefont (see -§10 Displaying a glossary) to switch to medium weight if you are using a glossary style that -displays entry names in bold and you have chosen an acronym style that uses (see §10 Displaying a +glossary) to switch to medium weight if you are using a glossary style that displays entry names in bold and you +have chosen an acronym style that uses \textsc. -
    -

    -

    The predefined styles that contain .

    +

    +

    The predefined styles that contain sm in their name (for example long-sm-short) redefine -\acronymfont to use ) redefine \acronymfont to +use \textsmaller. -

    . +

    -

    Note that the glossaries package doesn’t define or load any package that defines -

    Note that the glossaries package doesn’t define or load any package that defines \textsmaller. If you use one of the acronym styles that set . If you use +one of the acronym styles that set \acronymfont to \textsmaller -you must explicitly load the to \textsmaller you must explicitly load the relsize package or otherwise define package +or otherwise define \textsmaller.
    -

    -

    The remaining predefined styles redefine

    +

    The remaining predefined styles redefine \acronymfont{text} to simply do its argument -⟨} to simply do its argument ⟨text⟩. -

    In most cases, the predefined styles adjust

    In most cases, the predefined styles adjust \acrfull and and \glsentryfull (and their -plural and upper case variants) to reflect the style. The only exceptions to this are the (and their plural and upper case +variants) to reflect the style. The only exceptions to this are the dua -and and footnote styles (and their variants).
    -

    -

    The following styles are supplied by the styles (and their variants). +

    +

    +

    The following styles are supplied by the glossaries package:

    • long-short, , long-sc-short, , long-sm-short, , long-sp-short: -

      With these three styles, acronyms are displayed in the form -


      : +

      With these three styles, acronyms are displayed in the form +


      long(\firstacronymfont{short})

      -

      +

      on first use and -



      \acronymfont{short}

      -

      +

      on subsequent use. They also set \acronymsort{short}{long} to just ⟨short⟩. This means - that the acronyms are sorted according to their short form. In addition, \acronymentry - {short⟩. This means that the + acronyms are sorted according to their short form. In addition, \acronymentry{label} is set to just the short form (enclosed in } is set to + just the short form (enclosed in \acronymfont) and the description key - is set to the long form. -

      The description key is set to the long + form. +

      The long-sp-short style was introduced in version 4.16 and uses -


      \glsacspace  style was introduced in version 4.16 and uses +


      \glsacspace{label}

      - - -

      - for the space between the long and short forms. This defaults to a non-breakable space - (~) if (

      + for the space between the long and short forms. This defaults to a non-breakable space (~) if + (\acronymfont{short}) is less than 3em, otherwise it uses a normal space. This - may be redefined as required. For example, to always use a non-breakable - space: - - +class="cmtt-10">}) is less than 3em, otherwise it uses a normal space. This may be redefined as + required. For example, to always use a non-breakable space: + +

      -
      +
      \renewcommand*{\glsacspace}[1]{~}
      -

      +

    • short-long, , sc-short-long, , sm-short-long: -

      These three styles are analogous to the above three styles, except the display order is - swapped to -


      : +

      These three styles are analogous to the above three styles, except the display order is swapped + to +


      \firstacronymfont{short} (long)

      -

      +

      on first use. -

      Note, however, that

      Note, however, that \acronymsort and and \acronymentry are the same as for the ⟨long⟩ - (⟨short⟩) styles above, so the acronyms are still sorted according to the short - form. + id="dx1-149035"> are the same as for the ⟨long⟩ (⟨short⟩) styles above, + so the acronyms are still sorted according to the short form.

    • long-short-desc, , long-sc-short-desc, , long-sm-short-desc, , long-sp-short-desc: -

      These are like the : +

      These are like the long-short, , long-sc-short, , long-sm-short and and long-sp-short styles - described above, except that the description key must be supplied in the optional - argument of styles described above, except + that the description key must be supplied in the optional argument of \newacronym. They also redefine . They also redefine + \acronymentry to to {long} (\acronymfont - {\acronymfont{short}) and redefine \acronymsort{short}{long} to just ⟨long⟩. This means that the - acronyms are sorted according to the long form, and in the list of acronyms the name - field has the long form followed by the short form in parentheses. I recommend you use - a glossary style such as long⟩. + This means that the acronyms are sorted according to the long form, and in the list of acronyms + the name field has the long form followed by the short form in parentheses. I recommend + you use a glossary style such as altlist with these acronym styles to allow for the long name + id="dx1-149048"> with these acronym styles to allow for the long name field.

    • short-long-desc, , sc-short-long-desc, , sm-short-long-desc: -

      These styles are analogous to the above three styles, but the first use display style - is: -


      : +

      These styles are analogous to the above three styles, but the first use display style is: +


      \firstacronymfont{short} (long)

      -

      +

      The definitions of \acronymsort and \acronymentry are the same as those for - \acronymentry are the same as those for long-short-desc etc. + id="dx1-149052"> + etc.

    • dua, , dua-desc: - - -

      With these styles, the : +

      With these styles, the \gls-like commands always display the long form regardless of - whether the entry has been used or not. However, \gls-like commands always display the long form regardless of whether + the entry has been used or not. However, \acrfull and and \glsentryfull will - display ⟨long⟩ ( will display ⟨long⟩ + (\acronymfont{short}). In the case of dua, the name and sort keys are set - to the short form and the description is set to the long form. In the case of , the name and sort keys are set to the short + form and the description is set to the long form. In the case of dua-desc, the + id="dx1-149060">, the name and sort + keys are set to the long form and the description is supplied in the optional argument of name and sort keys are set to the long form and the description is supplied in the - optional argument of \newacronym. + id="dx1-149063">. + +

    • footnote, , footnote-sc, , footnote-sm: -

      With these three styles, on first use the : +

      With these three styles, on first use the \gls-like commands display: -



      \firstacronymfont{short}\footnote{long}

      -

      +

      However, \acrfull and and \glsentryfull are set to are set to \acronymfont{short} (⟨long⟩). On - subsequent use the display is: -


      long⟩). On subsequent use the + display is: +


      \acronymfont{short}

      -

      +

      The sort and name keys are set to the short form, and the description is set to the long +class="cmtt-10">sort and name keys are set to the short form, and the description is set to the long form. -

      In order to avoid nested hyperlinks on first use the footnote styles automatically - implement hyperfirst=false for the acronym lists.
      -

      +

      In order to avoid nested hyperlinks on first use the footnote styles automatically implement + hyperfirst=false for the acronym lists.
      +

    • footnote-desc, , footnote-sc-desc, , footnote-sm-desc: -

      These three styles are similar to the previous three styles, but the description - has to be supplied in the optional argument of : +

      These three styles are similar to the previous three styles, but the description has to be supplied in the + optional argument of \newacronym. The name key - is set to the long form followed by the short form in parentheses and the - sort key is set to the long form. This means that the acronyms will be sorted + id="dx1-149077">. The name key is set to the long form followed by the short form in + parentheses and the sort key is set to the long form. This means that the acronyms will be sorted according to the long form. In addition, since the name will typically be quite - wide it’s best to choose a glossary style that can accommodate this, such as - name will typically be quite wide it’s best to choose a + glossary style that can accommodate this, such as altlist. + id="dx1-149081">.

    -

    +

    Example 22 (Adapting a Predefined Acronym Style) -

    Suppose I want to use the +

    Suppose I want to use the footnote-sc-desc style, but I want the name key set to the short -form followed by the long form in parentheses and the sort key set to the short form. Then I -need to specify the style, but I want the name key set to the short form followed by +the long form in parentheses and the sort key set to the short form. Then I need to specify the footnote-sc-desc style: - - + id="dx1-149087"> +style: + +

    -
    +
    \setacronymstyle{footnote-sc-desc}
    -

    and then redefine

    and then redefine \acronymsort and and \acronymentry: - - + id="dx1-149089">: + +

    -
    +
    \renewcommand*{\acronymsort}[2]{#1}% sort by short form  
    \renewcommand*{\acronymentry}[1]{%  
      \acronymfont{\glsentryshort{#1}}\space (\glsentrylong{#1})}%
    -

    (I’ve used

    (I’ve used \space for extra clarity, but you can just use an actual space instead.) -

    Since the default Computer Modern fonts don’t support bold smallcaps, I’m also going to -redefine

    Note that the default Computer Modern fonts don’t support bold small caps, so another font is required. For +example: + + +

    +
    +\usepackage[T1]{fontenc} +
    +

    The alternative is to redefine \acronymfont so that it always switches to medium weight to ensure the smallcaps -setting is used: - - + id="dx1-149091"> so that it always switches to medium weight to ensure the small +caps setting is used. For example: + +

    -
    +
    \renewcommand*{\acronymfont}[1]{\textmd{\scshape #1}}
    -

    This isn’t necessary if you use a font that supports bold smallcaps. -

    The sample file

    +

    The sample file sampleFnAcrDesc.tex illustrates this example.

    -

    -

    ____________________________

    -

    +

    +

    ____________________________

    +

    -

    Top

    13.1.2 Defining A Custom Acronym Style

    -

    You may find that the predefined acronyms styles that come with the glossaries -package don’t suit your requirements. In this case you can define your own style -using: -


    \newacronymstyle 

    You may find that the predefined acronyms styles that come with the glossaries package don’t suit your +requirements. In this case you can define your own style using: +


    \newacronymstyle{style name}{display}{definitions} -

    -

    +class="cmtt-10">}


    +

    where ⟨style name⟩ is the name of the new style (avoid active characters). The second -argument, ⟨display⟩, is equivalent to the mandatory argument of style name⟩ is the name of the new style (avoid active characters). The second argument, ⟨display⟩, is +equivalent to the mandatory argument of \defglsentryfmt. You can -simply use . You can simply use \glsgenacfmt or you can customize the display using commands like - or you can +customize the display using commands like \ifglsused, , \glsifplural and and \glscapscase. (See §6.3 Changing the format -of the link text for further details.) If the style is likely to be used with a mixed -glossary (that is entries in that glossary are defined both with . (See §6.3 Changing +the format of the link text for further details.) If the style is likely to be used with a mixed glossary (that is +entries in that glossary are defined both with \newacronym and - and \newglossaryentry) then you can test if the entry is an acronym and use ) then you can test if the +entry is an acronym and use \glsgenacfmt if it -is or if it is or \glsgenentryfmt if it isn’t. For example, the if it isn’t. For example, the long-short style sets ⟨display⟩ -as - - + id="dx1-150011"> +style sets ⟨display⟩ as + +

    -
    +
    \ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}%
    -

    (You can use

    (You can use \ifglshasshort instead of instead of \ifglshaslong to test if the entry is an acronym if -you prefer.) -

    The third argument, ⟨definitions⟩, can be used to redefine the commands that affect the -display style, such as to test if the entry is an acronym if you +prefer.) +

    The third argument, ⟨definitions⟩, can be used to redefine the commands that affect the display style, such as +\acronymfont or, if ⟨ or, if ⟨display⟩ uses \glsgenacfmt, \genacrfullformat -and its variants. -

    Note that and its variants. +

    Note that \setacronymstyle redefines redefines \glsentryfull and and \acrfullfmt to use - to use \genacrfullformat (and similarly for the plural and upper case variants). If this isn’t -appropriate for the style (as in the case of styles like (and +similarly for the plural and upper case variants). If this isn’t appropriate for the style (as in the +case of styles like footnote and and dua) \newacronymstyle -should redefine these commands within ⟨) \newacronymstyle should redefine these commands within +⟨definitions⟩. -

    Within

    Within \newacronymstyle’s ⟨definitions⟩ argument you can also redefine -


    \GenericAcronymFields 


    \GenericAcronymFields

    -

    +

    This is a list of additional fields to be set in \newacronym. You can use the following token -registers to access the entry label, long form and short form: \glslabeltok \glslabeltok, -\glslongtok \glslongtok and \glsshorttok \glsshorttok. As with all TEX registers, you -can access their values by preceding the register with . You can use the following token registers to access +the entry label, long form and short form: \glslabeltok, \glslongtok and \glsshorttok. As with all +TEX registers, you can access their values by preceding the register with \the. For example, the . For example, the long-short style + id="dx1-150028"> style does: - - + +

    -
    +
    \renewcommand*{\GenericAcronymFields}{%  
       description={\the\glslongtok}}%
    -

    which sets the description field to the long form of the acronym whereas the

    which sets the description field to the long form of the acronym whereas the long-short-desc -style does: - - + id="dx1-150030"> style +does: + +

    -
    +
    \renewcommand*{\GenericAcronymFields}{}%
    -

    since the description needs to be specified by the user. -

    It may be that you want to define a new acronym style that’s based on an existing style. -Within ⟨display⟩ you can use -


    \GlsUseAcrEntryDispStyle 

    since the description needs to be specified by the user. +

    It may be that you want to define a new acronym style that’s based on an existing style. Within ⟨display⟩ you +can use +


    \GlsUseAcrEntryDispStyle{style name}

    -

    +

    to use the ⟨display⟩ definition from the style given by ⟨style name⟩. Within ⟨definitions⟩ you can -use -


    \GlsUseAcrStyleDefs  definitions⟩ you can use +


    \GlsUseAcrStyleDefs{style name}

    -

    +

    to use the ⟨definitions⟩ from the style given by ⟨style name⟩. For example, the long-sc-short -acronym style is based on the acronym style is +based on the long-short style with minor modifications (remember to use ## -instead of # within ⟨ style with minor modifications (remember to use ## instead of # within +⟨definitions⟩): - - + +

    -
    +
    \newacronymstyle{long-sc-short}%  
    {% use the same display as "long-short"  
      \GlsUseAcrEntryDispStyle{long-short}% @@ -20188,18 +22094,16 @@ class="cmti-10">definitions⟩):  
      \renewcommand*{\acrpluralsuffix}{\glstextup{\glspluralsuffix}}%  
    }
    -

    (\glstextup 

    (\glstextup is used to cancel the effect of \textsc. This defaults to . This defaults to \textulc, -if defined, otherwise , if defined, otherwise \textup. For example, the plural of . +For example, the plural of svm should be rendered as svms -rather than ms rather than svms.) -

    +

    Example 23 (Defining a Custom Acronym Style) -

    Suppose I want my acronym on first use to have the short form in the text and the long -form with the description in a footnote. Suppose also that I want the short form to be put in -small caps in the main body of the document, but I want it in normal capitals in the list of -acronyms. In my list of acronyms, I want the long form as the name with the short form in -brackets followed by the description. That is, in the text I want +

    Suppose I want my acronym on first use to have the short form in the text and the long form with the +description in a footnote. Suppose also that I want the short form to be put in small caps in the main body of +the document, but I want it in normal capitals in the list of acronyms. In my list of acronyms, I want the long +form as the name with the short form in brackets followed by the description. That is, in the text I want \gls on first use to display: - + id="dx1-150041"> +on first use to display:
    \textsc{abbrv}\footnote} on subsequent use:
    \textsc{abbrv} @@ -20255,37 +22157,36 @@ class="cmti-10">long⟩ (⟨short⟩) ⟨description
    -

    Let’s suppose it’s possible that I may have a mixed glossary. I can check this in the second -argument of

    Let’s suppose it’s possible that I may have a mixed glossary. I can check this in the second argument of +\newacronymstyle using: - - + id="dx1-150044"> using: + +

    -
    +
    \ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}%
    -

    This will use

    This will use \glsgenentryfmt if the entry isn’t an acronym, otherwise it will use - if the entry isn’t an acronym, otherwise it will use \glsgenacfmt. The third argument (⟨. The third +argument (⟨definitions⟩) of \newacronymstyle needs to redefine - needs to redefine \genacrfullformat etc so that the first use displays the short form in the text with the long -form in a footnote followed by the description. This is done as follows (remember to use ## -instead of etc so that the first +use displays the short form in the text with the long form in a footnote followed by the description. This is done +as follows (remember to use ## instead of #): - - + +

    -
    +
     % No case change, singular first use:  
      \renewcommand*{\genacrfullformat}[2]{%  
       \firstacronymfont{\glsentryshort{##1}}##2% @@ -20307,12 +22208,12 @@ class="cmtt-10">#):  
       \footnote{\glsentrylongpl{##1}: \glsentrydesc{##1}}%  
      }%
    -

    If you think it inappropriate for the short form to be capitalised at the start of a sentence -you can change the above to: - - +

    If you think it inappropriate for the short form to be capitalised at the start of a sentence you can change the +above to: + +

    -
    +
     % No case change, singular first use:  
      \renewcommand*{\genacrfullformat}[2]{%  
       \firstacronymfont{\glsentryshort{##1}}##2% @@ -20326,34 +22227,33 @@ you can change the above to:  
     \let\Genacrfullformat\genacrfullformat  
     \let\Genplacrfullformat\genplacrfullformat
    -

    Another variation is to use

    Another variation is to use \Glsentrylong and and \Glsentrylongpl in the footnote instead of - in the footnote instead of \glsentrylong and +and \glsentrylongpl. -

    Now let’s suppose that commands such as . +

    Now let’s suppose that commands such as \glsentryfull and and \acrfull shouldn’t use -a footnote, but instead use the format: ⟨ shouldn’t use a footnote, but +instead use the format: ⟨long⟩ (⟨short⟩). This means that the style -needs to redefine short⟩). This means that the style needs to redefine \glsentryfull, \acrfullfmt and their plural and upper case -variants. -

    First, the non-linking commands: - - + id="dx1-150055"> +and their plural and upper case variants. +

    First, the non-linking commands: + +

    -
    +
      \renewcommand*{\glsentryfull}[1]{%  
        \glsentrylong{##1}\space  
          (\acronymfont{\glsentryshort{##1}})% @@ -20371,11 +22271,11 @@ variants.  
          (\acronymfont{\glsentryshortpl{##1}})%  
      }%
    -

    Now for the linking commands: - - +

    Now for the linking commands: + +

    -
    +
      \renewcommand*{\acrfullfmt}[3]{%  
        \glslink[##1]{##2}{%  
         \glsentrylong{##2}##3\space @@ -20417,103 +22317,100 @@ variants.  
        }%  
      }%
    -

    (This may cause problems with long hyperlinks, in which case adjust the definitions so that, -for example, only the short form is inside the argument of

    (This may cause problems with long hyperlinks, in which case adjust the definitions so that, for example, only +the short form is inside the argument of \glslink.) -

    The style also needs to redefine .) +

    The style also needs to redefine \acronymsort so that the acronyms are sorted according -to the long form: - - + id="dx1-150057"> so that the acronyms are sorted according to the long +form: + +

    -
    +
      \renewcommand*{\acronymsort}[2]{##2}%
    -

    If you prefer them to be sorted according to the short form you can change the above -to: - - +

    If you prefer them to be sorted according to the short form you can change the above to: + +

    -
    +
      \renewcommand*{\acronymsort}[2]{##1}%
    -

    The acronym font needs to be set to

    The acronym font needs to be set to \textsc and the plural suffix adjusted so that the “s” -suffix in the plural short form doesn’t get converted to smallcaps: - - + id="dx1-150058"> and the plural suffix adjusted so that the “s” suffix in the plural +short form doesn’t get converted to small caps: + +

    -
    +
      \renewcommand*{\acronymfont}[1]{\textsc{##1}}%  
      \renewcommand*{\acrpluralsuffix}{\glstextup{\glspluralsuffix}}%
    -

    There are a number of ways of dealing with the format in the list of acronyms. The simplest -way is to redefine

    There are a number of ways of dealing with the format in the list of acronyms. The simplest way is to redefine +\acronymentry to the long form followed by the upper case short form in -parentheses: - - + id="dx1-150060"> to the long form followed by the upper case short form in parentheses: + +

    -
    +
     \renewcommand*{\acronymentry}[1]{%  
       \Glsentrylong{##1}\space  
         (\MakeTextUppercase{\glsentryshort{##1}})}%
    -

    (I’ve used

    (I’ve used \Glsentrylong instead of instead of \glsentrylong to capitalise the name in the -glossary.) -

    An alternative approach is to set to capitalise the name in the glossary.) +

    An alternative approach is to set \acronymentry to just the long form and redefine - to just the long form and redefine \GenericAcronymFields to set the symbol key to the short form and use a glossary style -that displays the symbol in parentheses after the name (such as the to +set the symbol key to the short form and use a glossary style that displays the symbol in parentheses after the +name (such as the tree style) like -this: - - + id="dx1-150067"> style) like this: + +

    -
    +
     \renewcommand*{\acronymentry}[1]{\Glsentrylong{##1}}%  
     \renewcommand*{\GenericAcronymFields}{%  
        symbol={\protect\MakeTextUppercase{\the\glsshorttok}}}%
    -

    I’m going to use the first approach and set

    I’m going to use the first approach and set \GenericAcronymFields to do nothing: - - + id="dx1-150068"> to do nothing: + +

    -
    +
     \renewcommand*{\GenericAcronymFields}{}%
    -

    -

    Finally, this style needs to switch off hyperlinks on first use to avoid nested -links: - - +

    +

    Finally, this style needs to switch off hyperlinks on first use to avoid nested links: + +

    -
    +
     \glshyperfirstfalse
    -

    Putting this all together: - - +

    Putting this all together: + +

    -
    +
    \newacronymstyle{custom-fn}% new style name  
    {%  
      \ifglshaslong{\glslabel}{\glsgenacfmt}{\glsgenentryfmt}% @@ -20560,8 +22457,8 @@ links:  
        }%  
      }%  
      \renewcommand*{\Acrfullfmt}[3]{% - - + +  
        \glslink[##1]{##2}{%  
         \Glsentrylong{##2}##3\space  
          (\acronymfont{\glsentryshort{##2}})% @@ -20603,10292 +22500,25476 @@ links:  
         (\MakeTextUppercase{\glsentryshort{##1}})}%  
    }
    -

    -

    Now I need to specify that I want to use this new style: - - +

    +

    Now I need to specify that I want to use this new style: + + +

    +
    +\setacronymstyle{custom-fn} +
    +

    I also need to use a glossary style that suits this acronym style, for example altlist: + + +

    +
    +\setglossarystyle{altlist} +
    +

    +

    Once the acronym style has been set, I can define my acronyms: + + +

    +
    +\newacronym[description={set of tags for use in + 
    developing hypertext documents}]{html}{html}{Hyper + 
    Text Markup Language} + 
    \newacronym[description={language used to describe the + 
    layout of a document written in a markup language}]{css} + 
    {css}{Cascading Style Sheet} +
    +

    +

    The sample file sample-custom-acronym.tex illustrates this example.

    +
    +

    +

    ____________________________

    + +

    Example 24 (Italic and Upright Abbreviations) +

    Suppose I want to have some abbreviations in italic and some that just use the surrounding font. +Hard-coding this into the ⟨short⟩ argument of \newacronym can cause complications. +

    This example uses \glsaddstoragekey to add an extra field that can be used to store the formatting +declaration (such as \em). + + +

    +
    +\glsaddstoragekey{font}{}{\entryfont} +
    +

    This defines a new field/key called font, which defaults to nothing if it’s not explicitly set. This also defines a +command called \entryfont that’s analogous to \glsentrytext. A new style is then created to format +abbreviations that access this field. +

    There are two ways to do this. The first is to create a style that doesn’t use \glsgenacfmt +but instead provides a modified version that doesn’t use \acronymfont{short} but instead uses +{\entryfont{\glslabel}short}. The full format given by commands such as \genacrfullformat need to be +similarly adjusted. For example: + + +

    +
    +  \renewcommand*{\genacrfullformat}[2]{% + 
       \glsentrylong{##1}##2\space + 
       ({\entryfont{##1}\glsentryshort{##1}})% + 
      }% +
    +

    This will deal with commands like \gls but not commands like \acrshort which still use \acronymfont. +Another approach is to redefine \acronymfont to look up the required font declaration. Since \acronymfont +doesn’t take the entry label as an argument, the following will only work if \acronymfont is used in a context +where the label is provided by \glslabel. This is true in \gls, \acrshort and \acrfull. The redefinition is +now: + + +

    +
    +\renewcommand*{\acronymfont}[1]{{\entryfont{\glslabel}#1}}% +
    +

    So the new style can be defined as: + + +

    +
    +\newacronymstyle{long-font-short} + 
    {% + 
      \GlsUseAcrEntryDispStyle{long-short}% + 
    } + 
    {% + 
      \GlsUseAcrStyleDefs{long-short}% + 
      \renewcommand*{\genacrfullformat}[2]{% + 
       \glsentrylong{##1}##2\space + 
       ({\entryfont{##1}\glsentryshort{##1}})% + 
      }% + 
      \renewcommand*{\Genacrfullformat}[2]{% + 
       \Glsentrylong{##1}##2\space + 
       ({\entryfont{##1}\glsentryshort{##1}})% + 
      }% + 
      \renewcommand*{\genplacrfullformat}[2]{% + 
       \glsentrylongpl{##1}##2\space + 
       ({\entryfont{##1}\glsentryshortpl{##1}})% + 
      }% + 
      \renewcommand*{\Genplacrfullformat}[2]{% + 
       \Glsentrylongpl{##1}##2\space + 
       ({\entryfont{##1}\glsentryshortpl{##1}})% + 
      }% + 
      \renewcommand*{\acronymfont}[1]{{\entryfont{\glslabel}##1}}% + 
      \renewcommand*{\acronymentry}[1]{{\entryfont{##1}\glsentryshort{##1}}}% + 
    } +
    +

    Remember the style needs to be set before defining the entries: + + +

    +
    +\setacronymstyle{long-font-short} +
    +

    +

    The complete document is contained in the sample file sample-font-abbr.tex.

    +
    +

    +

    ____________________________

    +

    Some writers and publishing houses have started to drop full stops (periods) from upper case initials but +may still retain them for lower case abbreviations, while others may still use them for both upper and lower +case. This can cause complications. Chapter 12 of The TEXbook discusses the spacing between words but, +briefly, the default behaviour of TEX is to assume that an upper case character followed by a full stop and +space is an abbreviation, so the space is the default inter-word space whereas a lower case character followed by +a full stop and space is a word occurring at the end of a sentence. In the event that this isn’t true, you +need to make a manual adjustment using (back slash space) in place of just a space character +for an inter-word mid-sentence space and use \@ before the full stop to indicate the end of the +sentence. +

    For example: + + +

    +
    +I was awarded a B.Sc. and a Ph.D. (From the same place.) +
    +

    is typeset as +
    I was awarded a B.Sc. and a Ph.D. (From the same place.) +
    +The spacing is more noticeable with the typewriter font: + + +

    +
    +\ttfamily + 
    I was awarded a B.Sc. and a Ph.D. (From the same place.) +
    +

    is typeset as +
    I was awarded a B.Sc. and a Ph.D. (From the same place.) +
    +The lower case letter at the end of “B.Sc.” is confusing TEX into thinking that the full stop after it marks the +end of the sentence. Whereas the upper case letter at the end of “Ph.D.” has confused TEX into thinking that +the following full stop is just part of the abbreviation. These can be corrected: + + +

    +
    +I was awarded a B.Sc.\ and a Ph.D\@. (From the same place.) +
    +

    +

    This situation is a bit problematic for glossaries. The full stops can form part of the ⟨short⟩ argument of +\newacronym and the B.Sc.\␣ part can be dealt with by remembering to add \␣ (for example, +\gls{bsc}\␣) but the end of sentence case is more troublesome as you need to omit the sentence +terminating full stop (to avoid two dots) which can make the source code look a little strange +but you also need to adjust the space factor, which is usually done by inserting \@ before the full +stop. +

    The next example shows one way of achieving this. (Note that the supplemental glossaries-extra +package provides a much simpler way of doing this, which you may prefer to use. See the initialisms +example.) + +

    Example 25 (Abbreviations with Full Stops (Periods)) +

    As from version 4.16, there’s now a hook (\glspostlinkhook) that’s called at the very end of the +\gls-like and \glstext-like commands. This can be redefined to check if the following character is a full stop. +The amsgen package (which is automatically loaded by glossaries) provides an internal command called +\new@ifnextchar that can be used to determine if the given character appears next. (For more information see +the amsgen documentation.) +

    It’s possible that I may also want acronyms or contractions in my document, so I need some way to +differentiate between them. Here I’m going to use the same method as in example 4 where a new field is defined +to indicate the type of abbreviation: + + +

    +
    +\glsaddstoragekey{abbrtype}{word}{\abbrtype} + 
    \newcommand*{\newabbr}[1][]{\newacronym[abbrtype=initials,#1]} +
    +

    Now I just use \newacronym for the acronyms, for example, + + +

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

    and my new command \newabbr for initials, for example, + + +

    +
    +\newabbr{eg}{e.g.}{exempli gratia} + 
    \newabbr{ie}{i.e.}{id est} + 
    \newabbr{bsc}{B.Sc.}{Bachelor of Science} + 
    \newabbr{ba}{B.A.}{Bachelor of Arts} + 
    \newabbr{agm}{A.G.M.}{annual general meeting} +
    +

    Within \glspostlinkhook the entry’s label can be accessed using \glslabel and \ifglsfieldeq can be used +to determine if the current entry has the new abbrtype field set to “initials”. If it doesn’t, then nothing needs to +happen, but if it does, a check is performed to see if the next character is a full stop. If it is, this signals the +end of a sentence otherwise it’s mid-sentence. +

    Remember that internal commands within the document file (rather than in a class or package) need to be +placed between \makeatletter and \makeatother: + + +

    +
    +\makeatletter + 
    \renewcommand{\glspostlinkhook}{% + 
     \ifglsfieldeq{\glslabel}{abbrtype}{initials}% + 
     {\new@ifnextchar.\doendsentence\doendword} + 
     {}% + 
    } + 
    \makeatother +
    +

    In the event that a full stop is found \doendsentence is performed but it will be followed by the full stop, +which needs to be discarded. Otherwise \doendword will be done but it won’t be followed by a full stop so +there’s nothing to discard. The definitions for these commands are: + + +

    +
    +\newcommand{\doendsentence}[1]{\spacefactor=10000{}} + 
    \newcommand{\doendword}{\spacefactor=1000{}} +
    +

    Now, I can just do \gls{bsc} mid-sentence and \gls{phd}. at the end of the sentence. The terminating full +stop will be discarded in the latter case, but it won’t be discarded in, say, \gls{laser}. as that doesn’t have +the abbrtype field set to “initials”. +

    This also works on first use when the style is set to one of the ⟨long⟩ (⟨short⟩) styles but it will fail with the +⟨short⟩ (⟨long⟩) styles as in this case the terminating full stop shouldn’t be discarded. Since \glspostlinkhook is +used after the first use flag has been unset for the entry, this can’t be fixed by simply checking with +\ifglsused. One possible solution to this is to redefine \glslinkpostsetkeys to check for the first use +flag and define a macro that can then be used in \glspostlinkhook. +

    The other thing to consider is what to do with plurals. One possibility is to check for plural use +within \doendsentence (using \glsifplural) and put the full stop back if the plural has been +used. +

    The complete document is contained in the sample file sample-dot-abbr.tex.

    +
    +

    +

    ____________________________

    +

    +

    +

    Top

    13.2 Displaying the List of Acronyms

    +

    The list of acronyms is just like any other type of glossary and can be displayed on its own using: +

    +Option 1:
    +
    +
    + \printnoidxglossary[type=\acronymtype] +
    +
    +
    +Options 2 and 3:
    +
    + + +
    + \printglossary[type=\acronymtype] +
    +
    +

    (If you use the acronym package option you can also use

    +
    + \printacronyms[options] +
    +
    as a synonym for
    +
    + \printglossary[type=\acronymtype,options] +
    +
    See §2.7 Acronym and Abbreviation Options.) +
    +

    Alternatively the list of acronyms can be displayed with all the other glossaries using: +

    +Option 1:
    \printnoidxglossaries +
    +Options 2 and 3:
    \printglossaries
    +

    However, care must be taken to choose a glossary style that’s appropriate to your acronym style. +Alternatively, you can define your own custom style (see §15.2 Defining your own glossary style for further +details). +

    +

    +

    Top

    13.3 Upgrading From the glossary Package

    +

    Users of the obsolete glossary package may recall that the syntax used to define new acronyms has changed with +the replacement glossaries package. In addition, the old glossary package created the command \acr-name⟩ when +defining the acronym ⟨acr-name⟩. +

    In order to facilitate migrating from the old package to the new one, the glossaries +package13.1 +provides the command: +


    \oldacronym[label]{abbrv}{long}{key-val list}

    + + +

    +This uses the same syntax as the glossary package’s method of defining acronyms. It is equivalent to: + +
    \newacronym[key-val list]{label}{abbrv}{long} +
    +In addition, \oldacronym also defines the commands \label⟩, which is equivalent to \gls{label}, and \label*, +which is equivalent to \Gls{label}. If ⟨label⟩ is omitted, ⟨abbrv⟩ is used. Since commands names must consist only +of alphabetical characters, ⟨label⟩ must also only consist of alphabetical characters. Note that \label⟩ doesn’t allow +you to use the first optional argument of \gls or \Gls — you will need to explicitly use \gls or \Gls to change +the settings. +

    Recall that, in general, LATEX ignores spaces following command names consisting of alphabetical +characters. This is also true for \label⟩ unless you additionally load the xspace package, but be aware that there +are some issues with using xspace.13.2
    +

    + +

    The glossaries package doesn’t load the xspace package since there are both advantages and disadvantages to +using \xspace in \label⟩. If you don’t use the xspace package you need to explicitly force a space +using \␣ (backslash space) however you can follow \label⟩ with additional text in square brackets +(the final optional argument to \gls). If you use the xspace package you don’t need to escape +the spaces but you can’t use the optional argument to insert text (you will have to explicitly use +\gls). +

    To illustrate this, suppose I define the acronym “abc” as follows: + + +

    +
    +\oldacronym{abc}{example acronym}{} +
    +

    This will create the command \abc and its starred version \abc*. Table 13.2 illustrates the effect of \abc (on +subsequent use) according to whether or not the xspace package has been loaded. As can be seen +from the final row in the table, the xspace package prevents the optional argument from being +recognised. +

    +
    + + +


    + + +
    Table 13.2: The effect of using xspace with \oldacronym
    +
    + + + + +
    Code With xspace Without xspace
    \abc. abc. abc.
    \abc xyz abc xyz abcxyz
    \abc\ xyz abc xyz abc xyz
    \abc* xyz Abc xyz Abc xyz
    \abc[’s] xyz abc [’s] xyz abc’s xyz
    +
    + + +

    +
    + + +

    +

    Top

    14. Unsetting and Resetting Entry Flags

    +

    When using the \gls-like commands it is possible that you may want to use the value given by the first +key, even though you have already used the glossary entry. Conversely, you may want to use the value given by +the text key, even though you haven’t used the glossary entry. The former can be achieved by one of the +following commands: +


    \glsreset{label}

    +

    +


    \glslocalreset{label}

    +

    +while the latter can be achieved by one of the following commands: +


    \glsunset{label}

    +

    +


    \glslocalunset{label}

    +

    +You can also reset or unset all entries for a given glossary or list of glossaries using: +


    \glsresetall[glossary list]

    +

    +


    \glslocalresetall[glossary list]

    +

    +


    \glsunsetall[glossary list]

    +

    +


    \glslocalunsetall[glossary list]

    +

    +where ⟨glossary list⟩ is a comma-separated list of glossary labels. If omitted, all defined glossaries are assumed +(except for the ignored ones). For example, to reset all entries in the main glossary and the list of +acronyms: + + +

    +
    +\glsresetall[main,acronym] +
    +

    +

    You can determine whether an entry’s first use flag is set using: +


    \ifglsused{label}{true part}{false part}

    +

    +where ⟨label⟩ is the label of the required entry. If the entry has been used, ⟨true part⟩ will be done, otherwise ⟨false +part⟩ will be done. +

    Be careful when using \gls-like commands within an environment or command argument that gets +processed multiple times as it can cause unwanted side-effects when the first use displayed text is different from +subsequent use.
    +

    +

    For example, the frame environment in beamer processes its argument for each overlay. This means that the +first use flag will be unset on the first overlay and subsequent overlays will use the non-first use +form. +

    Consider the following example: + + +

    +
    +\documentclass{beamer} + 
    \usepackage{glossaries} + 
    \newacronym{svm}{SVM}{support vector machine} + 
    \begin{document} + 
    \begin{frame} + 
     \frametitle{Frame 1} + 
     \begin{itemize} + 
      \item<+-> \gls{svm} + 
      \item<+-> Stuff. + 
     \end{itemize} + 
    \end{frame} + 
    \end{document} +
    +

    +

    On the first overlay, \gls{svm} produces “support vector machine (SVM)” and then unsets the first use flag. +When the second overlay is processed, \gls{svm} now produces “SVM”, which is unlikely to be the desired +effect. I don’t know anyway around this and I can only offer two suggestions. +

    Firstly, unset all acronyms at the start of the document and explicitly use \acrfull when you want the full +version to be displayed: + + +

    +
    +\documentclass{beamer} + 
    \usepackage{glossaries} + 
    \newacronym{svm}{SVM}{support vector machine} + 
    \glsunsetall + 
    \begin{document} + 
    \begin{frame} + 
     \frametitle{Frame 1} + 
     \begin{itemize} + 
      \item<+-> \acrfull{svm} + 
      \item<+-> Stuff. + 
     \end{itemize} + 
    \end{frame} + 
    \end{document} +
    +

    +

    Secondly, explicitly reset each acronym on first use: + + +

    +
    +\begin{frame} + 
     \frametitle{Frame 1} + 
     \begin{itemize} + 
      \item<+-> \glsreset{svm}\gls{svm} + 
      \item<+-> Stuff. + 
     \end{itemize} + 
    \end{frame} +
    +

    These are non-optimal, but the beamer class is too complex for me to provide a programmatic solution. Other +potentially problematic environments are some tabular-like environments (but not tabular itself) that process the +contents in order to work out the column widths and then reprocess the contents to do the actual +typesetting. +

    The amsmath environments, such as align, also process their contents multiple times, but the glossaries +package now checks for this. For tabularx, you need to explicitly patch it by placing \glspatchtabularx in the +preamble (or anywhere before the problematic use of tabularx). +

    If you need to use commands like \gls in any problematic context that interferes with the first use flag, +then you can try using the buffering system provided with glossaries-extra. See the “First Use Flag” section of +the glossaries-extra manual.
    +

    +

    +

    Top

    14.1 Counting the Number of Times an Entry has been Used (First Use Flag Unset)

    +

    As from version 4.14, it’s now possible to keep track of how many times an entry is used. That is, +how many times the first use flag is unset. Note that the supplemental glossaries-extra package +improves this function and also provides per-unit counting, which isn’t available with the glossaries +package. +

    This function is disabled by default as it adds extra overhead to the document build time and +also switches \newglossaryentry (and therefore \newacronym) into a preamble-only command. +
    +

    +

    To enable this function, use +


    \glsenableentrycount

    +

    +before defining your entries. This adds two extra (internal) fields to entries: currcount and prevcount. +

    The currcount field keeps track of how many times \glsunset is used within the document. A local unset +(using \glslocalunset) performs a local rather than global increment to currcount. Remember that +not all commands use \glsunset. Only the \gls-like commands do this. The reset commands +\glsreset and \glslocalreset reset this field back to zero (where \glslocalreset performs a local +change). + + +

    The prevcount field stores the final value of the currcount field from the previous run. This value is read +from the aux file at the beginning of the document environment. +

    You can access these fields using +


    \glsentrycurrcount{label}

    +

    +for the currcount field, and +


    \glsentryprevcount{label}

    +

    +for the prevcount field. +

    These commands are only defined if you have used \glsenableentrycount.
    +

    +

    For example: + + +

    +
    +\documentclass{article} + 
    \usepackage{glossaries} + 
    \makeglossaries + 
    \glsenableentrycount + 
    \newglossaryentry{apple}{name=apple,description={a fruit}} + 
    \begin{document} + 
    Total usage on previous run: \glsentryprevcount{apple}. + 
    \gls{apple}. \gls{apple}. \glsadd{apple}\glsentrytext{apple}. + 
    \glslink{apple}{apple}. \glsdisp{apple}{apple}. \Gls{apple}. + 
    Number of times apple has been used: \glsentrycurrcount{apple}. + 
    \end{document} +
    +

    On the first LATEX run, \glsentryprevcount{apple} produces 0. At the end of the document, +\glsentrycurrcount{apple} produces 4. This is because the only commands that have incremented the entry +count are those that use \glsunset. That is: \gls, \glsdisp and \Gls. The other commands used in the above +example, \glsadd, \glsentrytext and \glslink, don’t use \glsunset so they don’t increment the +entry count. On the next LATEX run, \glsentryprevcount{apple} now produces 4 as that was +the value of the currcount field for the apple entry at the end of the document on the previous +run. +

    When you enable the entry count using \glsenableentrycount, you also enable the following +commands: +


    \cgls[options]{label}[insert]

    +

    +(no case-change, singular) +


    \cglspl[options]{label}[insert]

    +

    +(no case-change, plural) +


    \cGls[options]{label}[insert]

    +

    +(first letter uppercase, singular), and +


    \cGlspl[options]{label}[insert]

    +

    +(first letter uppercase, plural). These all have plus and starred variants like the analogous \gls, \glspl, \Gls +and \Glspl commands. +

    If you don’t use \glsenableentrycount, these commands behave like \gls, \glspl, \Gls and \Glspl, +respectively, only there will be a warning that you haven’t enabled entry counting. If you have enabled entry +counting with \glsenableentrycount then these commands test if \glsentryprevcount{label} equals 1. If it +doesn’t then the analogous \gls etc will be used. If it does, then the first optional argument will be ignored and +

    + + +
    +⟨cs format{label}{insert}\glsunset{label} +
    +
    will be performed, where ⟨cs format⟩ is a command that takes two arguments. The command used depends +whether you have used \cgls, \cglspl, \cGls or \cGlspl. +


    \cglsformat{label}{insert}

    +

    +This command is used by \cgls and defaults to

    +
    +\glsentrylong{label}insert⟩ +
    +
    if the entry given by ⟨label⟩ has a long form or
    +
    +\glsentryfirst{label}insert⟩ +
    +
    otherwise. +


    \cglsplformat{label}{insert}

    +

    +This command is used by \cglspl and defaults to

    +
    +\glsentrylongpl{label}insert⟩ +
    +
    if the entry given by ⟨label⟩ has a long form or
    +
    +\glsentryfirstplural{label}insert⟩ +
    +
    otherwise. +


    \cGlsformat{label}{insert}

    +

    +This command is used by \cGls and defaults to

    +
    +\Glsentrylong{label}insert⟩ +
    +
    if the entry given by ⟨label⟩ has a long form or
    + + +
    +\Glsentryfirst{label}insert⟩ +
    +
    otherwise. +


    \cGlsplformat{label}{insert}

    +

    +This command is used by \cGlspl and defaults to

    +
    +\Glsentrylongpl{label}insert⟩ +
    +
    if the entry given by ⟨label⟩ has a long form or
    +
    +\Glsentryfirstplural{label}insert⟩ +
    +
    otherwise. +

    This means that if the previous count for the given entry was 1, the entry won’t be hyperlinked with the +\cgls-like commands and they won’t add a line to the external glossary file. If you haven’t used any of the +other commands that add information to glossary file (such as \glsadd or the \glstext-like commands) then +the entry won’t appear in the glossary. +

    Remember that since these commands use \glsentryprevcount you need to run LATEX twice to ensure +they work correctly. The document build order is now (at least): (pdf)latex, (pdf)latex, makeglossaries, +(pdf)latex. + +

    Example 26 (Don’t index entries that are only used once) +

    In this example, the abbreviations that have only been used once (on the previous run) only have their long +form shown with \cgls. + + +

    +
    +\documentclass{article} + 
    \usepackage[colorlinks]{hyperref} + 
    \usepackage[acronym]{glossaries} + 
    \makeglossaries + 
    \glsenableentrycount + 
    \setacronymstyle{long-short} + 
    \newacronym{html}{HTML}{hypertext markup language} + 
    \newacronym{css}{CSS}{cascading style sheets} + 
    \newacronym{xml}{XML}{extensible markup language} + 
    \newacronym{sql}{SQL}{structured query language} + 
    \newacronym{rdbms}{RDBMS}{relational database management system} + 
    \newacronym{rdsms}{RDSMS}{relational data stream management system} + 
    \begin{document} + 
    These entries are only used once: \cgls{sql}, \cgls{rdbms}, + 
    \cgls{xml}. These entries are used multiple times: + 
    \cgls{html}, \cgls{html}, \cgls{css}, \cgls{css}, \cgls{css}, + 
    \cgls{rdsms}, \cgls{rdsms}. + 
    \printglossaries + 
    \end{document} +
    +

    After a complete document build (latex, latex, makeglossaries, latex) the list of abbrevaitions only +includes the entries HTML, CSS and RDSMS. The entries SQL, RDBMS and XML only have their long forms +displayed and don’t have a hyperlink.

    +
    +

    +

    ____________________________

    +

    Remember that if you don’t like typing \cgls you can create a synonym. For example + + +

    +
    +\let\ac\cgls +
    +

    +

    With bib2gls there’s an analogous record counting set of commands. See glossaries-extra and bib2gls +manuals for further details.
    +

    + + +

    +

    +

    Top

    15. Glossary Styles

    +

    Glossaries vary from lists that simply contain a symbol with a terse description to lists of terms or phrases +with lengthy descriptions. Some glossaries may have terms with associated symbols. Some may have hierarchical +entries. There is therefore no single style that fits every type of glossary. The glossaries package comes with a +number of pre-defined glossary styles, described in §15.1 Predefined Styles. You can choose one of these that best +suits your type of glossary or, if none of them suit your document, you can defined your own style (see +§15.2 Defining your own glossary style). There are some examples of glossary styles available at +https://www.dickimaw-books.com/gallery/#glossaries. +

    The glossary style can be set using the style key in the optional argument to \printnoidxglossary +(Option 1) or \printglossary (Options 2 and 3) or using the command: +


    \setglossarystyle{style-name}

    +

    +(before the glossary is displayed). +

    Some of the predefined glossary styles may also be set using the style package option, it depends if the +package in which they are defined is automatically loaded by the glossaries package. +

    You can use the lorum ipsum dummy entries provided in the accompanying example-glossaries-*.tex +files (described in §1.2 Dummy Entries for Testing) to test the different styles. +

    The glossaries-extra-stylemods package provided with glossaries-extra patches the predefined styles. There also +more styles available with glossaries-extra.
    +

    +

    +

    Top

    15.1 Predefined Styles

    +

    The predefined styles can accommodate numbered level 0 (main) and level 1 entries. See the package options +entrycounter, counterwithin and subentrycounter described in §2.3 Glossary Appearance Options. There is a +summary of available styles in table 15.1. You can view samples of all the predefined styles at +https://www.dickimaw-books.com/gallery/glossaries-styles/. Note that glossaries-extra provides +additional styles in the supplementary packages glossary-bookindex and glossary-longnoloc. See the glossaries-extra +manual for further details. +

    Note that the group styles (such as listgroup) will have unexpected results if used with the sort=def or +sort=use options. If you don’t sort your entries alphabetically, it’s best to set the nogroupskip package option to +prevent odd vertical gaps appearing.
    +

    +

    The group title is obtained using \glsgetgrouptitle{label}, which is described in §15.2 Defining your own +glossary style. +

    +
    + + +


    + + +
    Table 15.1: Glossary Styles. An asterisk in the style name indicates anything that matches that doesn’t +match any previously listed style (e.g. long3col* matches long3col, long3colheader, long3colborder and +long3colheaderborder). A maximum level of 0 indicates a flat glossary (sub-entries are displayed in the +same way as main entries). Where the maximum level is given as — there is no limit, but note that +makeindex (Option 2) imposes a limit of 2 sub-levels. If the homograph column is checked, then the +name is not displayed for sub-entries. If the symbol column is checked, then the symbol will be displayed.
    +
    + + + + + + + + + + + + + +
    Style Maximum Level Homograph Symbol
    listdotted 0
    sublistdotted 1
    list* 1
    altlist* 1 +
    long*3col* 1 +
    long4col* 1
    altlong*4col* 1
    long* 1
    super*3col* 1
    super4col* 1
    altsuper*4col* 1
    super* 1
    *index* 2
    treenoname*
    *alttree*
    *tree*
    inline 1
    + + +

    +
    +

    The tabular-like styles that allow multi-line descriptions and page lists use the length +


    \glsdescwidth

    +

    +to set the width of the description column and the length +


    \glspagelistwidth

    +

    +to set the width of the page list column.15.1 +These will need to be changed using \setlength if the glossary is too wide. Note that the long4col and super4col +styles (and their header and border variations) don’t use these lengths as they are designed for single line +entries. Instead you should use the analogous altlong4col and altsuper4col styles. If you want to explicitly create +a line-break within a multi-line description in a tabular-like style it’s better to use \newline instead of +\\. +

    Remember that a cell within a tabular-like environment can’t be broken across a page, so even if a +tabular-like style, such as long, allows multilined descriptions, you’ll probably encounter page-breaking problems +if you have entries with long descriptions. You may want to consider using the alttree style instead. +
    +

    +

    Note that if you use the style key in the optional argument to \printnoidxglossary (Option 1) or +\printglossary (Options 2 and 3), it will override any previous style settings for the given glossary, so if, for +example, you do + + +

    +
    +\renewcommand*{\glsgroupskip}{} + 
    \printglossary[style=long] +
    +

    then the new definition of \glsgroupskip will not have an affect for this glossary, as \glsgroupskip is +redefined by style=long. Likewise, \setglossarystyle will also override any previous style definitions, so, +again + + +

    +
    +\renewcommand*{\glsgroupskip}{} + 
    \setglossarystyle{long} +
    +

    will reset \glsgroupskip back to its default definition for the named glossary style (long in this case). If you +want to modify the styles, either use \newglossarystyle (described in the next section) or make the +modifications after \setglossarystyle, e.g.: + + +

    +
    +\setglossarystyle{long} + 
    \renewcommand*{\glsgroupskip}{} +
    +

    As from version 3.03, you can now use the package option nogroupskip to suppress the gap between groups for +the default styles instead of redefining \glsgroupskip. +

    All the styles except for the three- and four-column styles and the listdotted style use the command +


    \glspostdescription

    +

    +after the description. This simply displays a full stop by default. To eliminate this full stop (or replace it with +something else, say, a comma) you will need to redefine \glspostdescription before the glossary is displayed. +Alternatively, you can suppress it for a given entry by placing \nopostdesc in the entry’s description. Note that +\longnewglossaryentry puts \nopostdesc at the end of the description. The glossaries-extra package provides +a starred version that doesn’t. +

    As from version 3.03 you can now use the package option nopostdot to suppress this full stop. This is the +better option if you want to use the glossaries-extra package. The glossaries-extra-stylemods package provides +some adjustments some of to the predefined styles listed here, allowing for greater flexibility. See the +glossaries-extra documentation for further details. +

    +

    Top

    15.1.1 List Styles

    +

    The styles described in this section are all defined in the package glossary-list. Since they all use the description +environment, they are governed by the same parameters as that environment. These styles all ignore the entry’s +symbol. Note that these styles will automatically be available unless you use the nolist or nostyles package +options. +

    Note that, except for the listdotted style, these list styles are incompatible with classicthesis. They +may also be incompatible with other classes or packages that modify the description environment. +
    +

    +

    +list
    The list style uses the description environment. The entry name is placed in the optional argument of + the \item command (so it will usually appear in bold by default). The description follows, and then + the associated number list for that entry. The symbol is ignored. If the entry has child entries, the + description and number list follows (but not the name) for each child entry. Groups are separated + using \indexspace. +

    The closest matching non-list style is the index style. +

    +listgroup
    The listgroup style is like list but the glossary groups have headings obtained using + \glsgetgrouptitle{label}, which is described in §15.2 Defining your own glossary style. + + +
    +listhypergroup
    The listhypergroup style is like listgroup but has a navigation line at the start of the glossary + with links to each group that is present in the glossary. This requires an additional run through + LATEX to ensure the group information is up to date. In the navigation line, each group is separated + by +


    \glshypernavsep

    +

    + which defaults to a vertical bar with a space on either side. For example, to simply have a space separating + each group, do: + + +

    +
    + \renewcommand*{\glshypernavsep}{\space} +
    +

    +

    Note that the hyper-navigation line is now (as from version 1.14) set inside the optional + argument to \item instead of after it to prevent a spurious space at the start. This can cause a + problem if the navigation line is too long. As from v4.22, if you need to adjust this, you can + redefine +


    \glslistnavigationitem{navigation line}

    +

    + The default definition is \item[navigation line] but may be redefined independently of setting the style. + For example: + + +

    +
    + \renewcommand*{\glslistnavigationitem}[1]{\item \textbf{#1}} +
    +

    +

    You may prefer to use the tree-like styles, such as treehypergroup instead. +

    +altlist
    The altlist style is like list but the description starts on the line following the name. (As with the list + style, the symbol is ignored.) Each child entry starts a new line, but as with the list style, the name + associated with each child entry is ignored. +

    The closest matching non-list style is the index style with the following adjustment: + + +

    +
    + \renewcommand{\glstreepredesc}{% +  
     \glstreeitem\parindent\hangindent} +
    +

    +

    +altlistgroup
    The altlistgroup style is like altlist but the glossary groups have headings. +
    +altlisthypergroup
    The altlisthypergroup style is like altlistgroup but has a set of links to the glossary groups. + The navigation line is the same as that for listhypergroup, described above. +
    +listdotted
    This style uses the description + environment.15.2 + Each entry starts with \item[], followed by the name followed by a dotted line, followed + by the description. Note that this style ignores both the number list and the symbol. The + length +


    \glslistdottedwidth

    +

    + governs where the description should start. This is a flat style, so child entries are formatted in the same + way as the parent entries. +

    A non-list alternative is to use the index style with + + +

    +
    + \renewcommand{\glstreepredesc}{\dotfill} +  
    \renewcommand{\glstreechildpredesc}{\dotfill} +
    +

    Note that this doesn’t use \glslistdottedwidth and causes the description to be flush-right and will + display the symbol, if provided. (It also doesn’t suppress the number list, but that can be achieved with + the nonumberlist option.) +

    +sublistdotted
    This is a variation on the listdotted style designed for hierarchical glossaries. The main entries + have just the name displayed. The sub entries are displayed in the same manner as listdotted. Unlike the + listdotted style, this style is incompatible with classicthesis.
    +

    +

    +

    Top

    15.1.2 Longtable Styles

    +

    The styles described in this section are all defined in the package glossary-long. Since they all use the +longtable environment, they are governed by the same parameters as that environment. Note that +these styles will automatically be available unless you use the nolong or nostyles package options. +These styles fully justify the description and page list columns. If you want ragged right formatting +instead, use the analogous styles described in §15.1.3 Longtable Styles (Ragged Right). If you want to +incorporate rules from the booktabs package, try the styles described in §15.1.4 Longtable Styles +(booktabs). +

    +long
    The long style uses the longtable environment (defined by the longtable package). It has two columns: + the first column contains the entry’s name and the second column contains the description followed + by the number list. The entry’s symbol is ignored. Sub groups are separated with a blank row. The + width of the first column is governed by the widest entry in that column. The width of the second + column is governed by the length \glsdescwidth. Child entries have a similar format to the parent + entries except that their name is suppressed. +
    +longborder
    The longborder style is like long but has horizontal and vertical lines around it. +
    +longheader
    The longheader style is like long but has a header row. +
    +longheaderborder
    The longheaderborder style is like longheader but has horizontal and vertical lines + around it. + + +
    +long3col
    The long3col style is like long but has three columns. The first column contains the entry’s + name, the second column contains the description and the third column contains the number list. + The entry’s symbol is ignored. The width of the first column is governed by the widest entry in + that column, the width of the second column is governed by the length \glsdescwidth, and the + width of the third column is governed by the length \glspagelistwidth. +
    +long3colborder
    The long3colborder style is like the long3col style but has horizontal and vertical lines + around it. +
    +long3colheader
    The long3colheader style is like long3col but has a header row. +
    +long3colheaderborder
    The long3colheaderborder style is like long3colheader but has horizontal and + vertical lines around it. +
    +long4col
    The long4col style is like long3col but has an additional column in which the entry’s associated + symbol appears. This style is used for brief single line descriptions. The column widths are governed + by the widest entry in the given column. Use altlong4col for multi-line descriptions. +
    +long4colborder
    The long4colborder style is like the long4col style but has horizontal and vertical lines + around it. +
    +long4colheader
    The long4colheader style is like long4col but has a header row. +
    +long4colheaderborder
    The long4colheaderborder style is like long4colheader but has horizontal and + vertical lines around it. +
    +altlong4col
    The altlong4col style is like long4col but allows multi-line descriptions and page lists. The + width of the description column is governed by the length \glsdescwidth and the width of the page + list column is governed by the length \glspagelistwidth. The widths of the name and symbol + columns are governed by the widest entry in the given column. +
    +altlong4colborder
    The altlong4colborder style is like the long4colborder but allows multi-line + descriptions and page lists. +
    +altlong4colheader
    The altlong4colheader style is like long4colheader but allows multi-line descriptions + and page lists. +
    +altlong4colheaderborder
    The altlong4colheaderborder style is like long4colheaderborder but allows + multi-line descriptions and page lists.
    + + +

    +

    +

    Top

    15.1.3 Longtable Styles (Ragged Right)

    +

    The styles described in this section are all defined in the package glossary-longragged. These styles are analogous +to those defined in glossary-long but the multiline columns are left justified instead of fully justified. Since these +styles all use the longtable environment, they are governed by the same parameters as that environment. The +glossary-longragged package additionally requires the array package. Note that these styles will only be available +if you explicitly load glossary-longragged: + + +

    +
    +\usepackage{glossaries} + 
    \usepackage{glossary-longragged} +
    +

    Note that you can’t set these styles using the style package option since the styles aren’t defined until after the +glossaries package has been loaded. If you want to incorporate rules from the booktabs package, try the styles +described in §15.1.4 Longtable Styles (booktabs). +

    +longragged
    The longragged style has two columns: the first column contains the entry’s name and the + second column contains the (left-justified) description followed by the number list. The entry’s + symbol is ignored. Sub groups are separated with a blank row. The width of the first column is + governed by the widest entry in that column. The width of the second column is governed by the + length \glsdescwidth. Child entries have a similar format to the parent entries except that their + name is suppressed. +
    +longraggedborder
    The longraggedborder style is like longragged but has horizontal and vertical lines + around it. +
    +longraggedheader
    The longraggedheader style is like longragged but has a header row. +
    +longraggedheaderborder
    The longraggedheaderborder style is like longraggedheader but has horizontal + and vertical lines around it. +
    +longragged3col
    The longragged3col style is like longragged but has three columns. The first column + contains the entry’s name, the second column contains the (left justified) description and the third + column contains the (left justified) number list. The entry’s symbol is ignored. The width of the + first column is governed by the widest entry in that column, the width of the second column is + governed by the length \glsdescwidth, and the width of the third column is governed by the + length \glspagelistwidth. +
    +longragged3colborder
    The longragged3colborder style is like the longragged3col style but has horizontal + and vertical lines around it. +
    +longragged3colheader
    The longragged3colheader style is like longragged3col but has a header row. +
    +longragged3colheaderborder
    The longragged3colheaderborder style is like longragged3colheader but + has horizontal and vertical lines around it. + + +
    +altlongragged4col
    The altlongragged4col style is like longragged3col but has an additional column in + which the entry’s associated symbol appears. The width of the description column is governed + by the length \glsdescwidth and the width of the page list column is governed by the length + \glspagelistwidth. The widths of the name and symbol columns are governed by the widest + entry in the given column. +
    +altlongragged4colborder
    The altlongragged4colborder style is like the altlongragged4col but has + horizontal and vertical lines around it. +
    +altlongragged4colheader
    The altlongragged4colheader style is like altlongragged4col but has a header + row. +
    +altlongragged4colheaderborder
    The altlongragged4colheaderborder style is like + altlongragged4colheader but has horizontal and vertical lines around it. +
    +

    +

    +

    Top

    15.1.4 Longtable Styles (booktabs)

    +

    The styles described in this section are all defined in the package glossary-longbooktabs. +

    Since these styles all use the longtable environment, they are governed by the same parameters as that +environment. The glossary-longbooktabs package automatically loads the glossary-long (§15.1.2 Longtable Styles) +and glossary-longragged (§15.1.3 Longtable Styles (Ragged Right)) packages. Note that these styles will only be +available if you explicitly load glossary-longbooktabs: + + +

    +
    +\usepackage{glossaries} + 
    \usepackage{glossary-longbooktabs} +
    +

    Note that you can’t set these styles using the style package option since the styles aren’t defined until after the +glossaries package has been loaded. +

    These styles are similar to the “header” styles in the glossary-long and glossary-ragged packages, but they add +the rules provided by the booktabs package, \toprule, \midrule and \bottomrule. Additionally these styles +patch the longtable environment to check for instances of the group skip occurring at a page break. If you don’t +want this patch to affect any other use of longtable in your document, you can scope the effect by only setting +the style through the style key in the optional argument of \printglossary. (The nogroupskip package option +is checked by these styles.) +

    Alternatively, you can restore the original longtable behaviour with: +


    \glsrestoreLToutput

    +

    +For more information about the patch, see the documented code (glossaries-code.pdf). +

    +long-booktabs
    This style is similar to the longheader style but adds rules above and below the header + (\toprule and \midrule) and inserts a rule at the bottom of the table (\bottomrule). +
    +long3col-booktabs
    This style is similar to the long3colheader style but adds rules as per long-booktabs. +
    +long4col-booktabs
    This style is similar to the long4colheader style but adds rules as above. +
    +altlong4col-booktabs
    This style is similar to the altlong4colheader style but adds rules as above. +
    +longragged-booktabs
    This style is similar to the longraggedheader style but adds rules as above. +
    +longragged3col-booktabs
    This style is similar to the longragged3colheader style but adds rules as above. +
    +altlongragged4col-booktabs
    This style is similar to the altlongragged4colheader style but adds rules as + above. +
    + + +

    +

    +

    Top

    15.1.5 Supertabular Styles

    +

    The styles described in this section are all defined in the package glossary-super. Since they all use the +supertabular environment, they are governed by the same parameters as that environment. Note that these styles +will automatically be available unless you use the nosuper or nostyles package options. In general, +the longtable environment is better, but there are some circumstances where it is better to use +supertabular.15.3 +These styles fully justify the description and page list columns. If you want ragged right formatting instead, use +the analogous styles described in §15.1.6 Supertabular Styles (Ragged Right). +

    +super
    The super style uses the supertabular environment (defined by the supertabular package). It has two + columns: the first column contains the entry’s name and the second column contains the description + followed by the number list. The entry’s symbol is ignored. Sub groups are separated with a blank + row. The width of the first column is governed by the widest entry in that column. The width of + the second column is governed by the length \glsdescwidth. Child entries have a similar format + to the parent entries except that their name is suppressed. +
    +superborder
    The superborder style is like super but has horizontal and vertical lines around it. +
    +superheader
    The superheader style is like super but has a header row. +
    +superheaderborder
    The superheaderborder style is like superheader but has horizontal and vertical + lines around it. +
    +super3col
    The super3col style is like super but has three columns. The first column contains the entry’s + name, the second column contains the description and the third column contains the number list. + The entry’s symbol is ignored. The width of the first column is governed by the widest entry in that + column. The width of the second column is governed by the length \glsdescwidth. The width of + the third column is governed by the length \glspagelistwidth. +
    +super3colborder
    The super3colborder style is like the super3col style but has horizontal and vertical + lines around it. +
    +super3colheader
    The super3colheader style is like super3col but has a header row. +
    +super3colheaderborder
    The super3colheaderborder style is like the super3colheader style but has + horizontal and vertical lines around it. + + +
    +super4col
    The super4col style is like super3col but has an additional column in which the entry’s + associated symbol appears. This style is designed for entries with brief single line descriptions. The + column widths are governed by the widest entry in the given column. Use altsuper4col for multi-line + descriptions. +
    +super4colborder
    The super4colborder style is like the super4col style but has horizontal and vertical + lines around it. +
    +super4colheader
    The super4colheader style is like super4col but has a header row. +
    +super4colheaderborder
    The super4colheaderborder style is like the super4colheader style but has + horizontal and vertical lines around it. +
    +altsuper4col
    The altsuper4col style is like super4col but allows multi-line descriptions and page lists. + The width of the description column is governed by the length \glsdescwidth and the width of + the page list column is governed by the length \glspagelistwidth. The width of the name and + symbol columns is governed by the widest entry in the given column. +
    +altsuper4colborder
    The altsuper4colborder style is like the super4colborder style but allows multi-line + descriptions and page lists. +
    +altsuper4colheader
    The altsuper4colheader style is like super4colheader but allows multi-line + descriptions and page lists. +
    +altsuper4colheaderborder
    The altsuper4colheaderborder style is like super4colheaderborder but allows + multi-line descriptions and page lists.
    +

    +

    +

    Top

    15.1.6 Supertabular Styles (Ragged Right)

    +

    The styles described in this section are all defined in the package glossary-superragged. These styles are +analogous to those defined in glossary-super but the multiline columns are left justified instead of fully justified. +Since these styles all use the supertabular environment, they are governed by the same parameters as that +environment. The glossary-superragged package additionally requires the array package. Note that these styles +will only be available if you explicitly load glossary-superragged: + + +

    +
    +\usepackage{glossaries} + 
    \usepackage{glossary-superragged} +
    +

    Note that you can’t set these styles using the style package option since the styles aren’t defined until after the +glossaries package has been loaded. +

    +superragged
    The superragged style uses the supertabular environment (defined by the supertabular + package). It has two columns: the first column contains the entry’s name and the second column + contains the (left justified) description followed by the number list. The entry’s symbol is ignored. + Sub groups are separated with a blank row. The width of the first column is governed by the widest + entry in that column. The width of the second column is governed by the length \glsdescwidth. + Child entries have a similar format to the parent entries except that their name is suppressed. +
    +superraggedborder
    The superraggedborder style is like superragged but has horizontal and vertical + lines around it. +
    +superraggedheader
    The superraggedheader style is like superragged but has a header row. +
    +superraggedheaderborder
    The superraggedheaderborder style is like superraggedheader but has + horizontal and vertical lines around it. +
    +superragged3col
    The superragged3col style is like superragged but has three columns. The first column + contains the entry’s name, the second column contains the (left justified) description and the third + column contains the (left justified) number list. The entry’s symbol is ignored. The width of the + first column is governed by the widest entry in that column. The width of the second column is + governed by the length \glsdescwidth. The width of the third column is governed by the length + \glspagelistwidth. +
    +superragged3colborder
    The superragged3colborder style is like the superragged3col style but has + horizontal and vertical lines around it. +
    +superragged3colheader
    The superragged3colheader style is like superragged3col but has a header row. +
    +superragged3colheaderborder
    The superragged3colheaderborder style is like the above but has + horizontal and vertical lines around it. + + +
    +altsuperragged4col
    The altsuperragged4col style is like superragged3col but has an additional column + in which the entry’s associated symbol appears. The column widths for the name and symbol + column are governed by the widest entry in the given column. +
    +altsuperragged4colborder
    The altsuperragged4colborder style is like the altsuperragged4col style but + has horizontal and vertical lines around it. +
    +altsuperragged4colheader
    The altsuperragged4colheader style is like altsuperragged4col but has a + header row. +
    +altsuperragged4colheaderborder
    The altsuperragged4colheaderborder style is like the above but has + horizontal and vertical lines around it. +
    +

    +

    +

    Top

    15.1.7 Tree-Like Styles

    +

    The styles described in this section are all defined in the package glossary-tree. These styles are designed for +hierarchical glossaries but can also be used with glossaries that don’t have sub-entries. These styles will display +the entry’s symbol if it exists. Note that these styles will automatically be available unless you use the notree or +nostyles package options. +

    These styles all format the entry name using: +


    \glstreenamefmt{name}

    +

    +This defaults to \textbf{name}, but note that ⟨name⟩ includes \glsnamefont so the bold setting in +\glstreenamefont may be counteracted by another font change in \glsnamefont (or in \acronymfont). The +tree-like styles that also display the header use +


    \glstreegroupheaderfmt{text}

    +

    +to format the heading. This defaults to \glstreenamefmt{text}. The tree-like styles that display navigation +links to the groups (such as indexhypergroup), format the navigation line using +


    \glstreenavigationfmt{text}

    +

    +which defaults to \glstreenamefmt{text}. +

    Note that this is different from \glslistnavigationitem, provided with the styles such as listhypergroup, as +that also includes \item. +

    With the exception of the alttree style (and those derived from it), the space before the description for +top-level entries is produced with +


    \glstreepredesc

    +

    +This defaults to \space. + + +

    With the exception of the treenoname and alttree styles (and those derived from them), the space before the +description for child entries is produced with +


    \glstreechildpredesc

    +

    +This defaults to \space. +

    Most of these styles are not designed for multi-paragraph descriptions. (The tree style isn’t too bad for +multi-paragraph top-level entry descriptions, or you can use the index style with the adjustment shown below.) +
    +

    +

    +index
    The index style is similar to the way indices are usually formatted in that it has a hierarchical + structure up to three levels (the main level plus two sub-levels). The name is typeset in bold, and if + the symbol is present it is set in parentheses after the name and before the description. Sub-entries + are indented and also include the name, the symbol in brackets (if present) and the description. + Groups are separated using \indexspace. +

    Each main level item is started with +


    \glstreeitem

    +

    + The level 1 entries are started with +


    \glstreesubitem

    +

    +

    The level 2 entries are started with +


    \glstreesubsubitem

    +

    +

    Note that the index style automatically sets + + +

    +
    + \let\item\glstreeitem +  
    \let\subitem\glstreesubitem +  
    \let\subsubitem\glstreesubsubitem +
    +

    at the start of the glossary for backward compatibility. +

    The index style isn’t suitable for multi-paragraph descriptions, but this limitation can be overcome by + redefining the above commands. For example: + + +

    +
    + \renewcommand{\glstreeitem}{% +  
     \parindent0pt\par\hangindent40pt +  
     \everypar{\parindent50pt\hangindent40pt}} +
    +

    +

    +indexgroup
    The indexgroup style is similar to the index style except that each group has a heading + obtained using \glsgetgrouptitle{label}, which is described in §15.2 Defining your own glossary + style. +
    +indexhypergroup
    The indexhypergroup style is like indexgroup but has a set of links to the glossary groups. + The navigation line is the same as that for listhypergroup, described above, but is formatted using + \glstreenavigationfmt. +
    +tree
    The tree style is similar to the index style except that it can have arbitrary levels. (Note that makeindex is + limited to three levels, so you will need to use xindy if you want more than three levels.) Each sub-level is + indented by \glstreeindent. Note that the name, symbol (if present) and description are placed in the + same paragraph block. If you want the name to be apart from the description, use the alttree style instead. + (See below.) +
    +treegroup
    The treegroup style is similar to the tree style except that each group has a heading. +
    +treehypergroup
    The treehypergroup style is like treegroup but has a set of links to the glossary groups. The + navigation line is the same as that for listhypergroup, described above, but is formatted using + \glstreenavigationfmt. +
    +treenoname
    The treenoname style is like the tree style except that the name for each sub-entry is + ignored. +
    +treenonamegroup
    The treenonamegroup style is similar to the treenoname style except that each group has a + heading. +
    +treenonamehypergroup
    The treenonamehypergroup style is like treenonamegroup but has a set of links to the + glossary groups. The navigation line is the same as that for listhypergroup, described above, but is + formatted using \glstreenavigationfmt. + + +
    +alttree
    The alttree style is similar to the tree style except that the indentation for each level is determined by + the width of the text specified by +


    \glssetwidest[level]{text}

    +

    + The optional argument ⟨level⟩ indicates the level, where 0 indicates the top-most level, 1 indicates the first + level sub-entries, etc. If \glssetwidest hasn’t been used for a given sub-level, the level 0 widest text is + used instead. If ⟨level⟩ is omitted, 0 is assumed. +

    As from v4.22, the glossary-tree package also provides +


    \glsfindwidesttoplevelname[glossary list]

    +

    + This iterates over all parentless entries in the given glossary lists and determines the widest entry. If the + optional argument is omitted, all glossaries are assumed (as per \forallglossaries). +

    For example, to have the same name width for all glossaries: + + +

    +
    + \glsfindwidesttoplevelname +  
    \setglossarystyle{alttree} +  
    \printglossaries +
    +

    Alternatively, to compute the widest entry for each glossary before it’s displayed: + + +

    +
    + \renewcommand{\glossarypreamble}{% +  
      \glsfindwidesttoplevelname[\currentglossary]} +  
    \setglossarystyle{alttree} +  
    \printglossaries +
    +

    +

    These commands only affects the alttree styles, including those listed below and the ones in the + glossary-mcols package. If you forget to set the widest entry name, the description will overwrite the name. +
    +

    +

    For each level, the name is placed to the left of the paragraph block containing the symbol + (optional) and the description. If the symbol is present, it is placed in parentheses before the + description. +

    The name is placed inside a left-aligned \makebox. As from v4.19, this can now be adjusted by + redefining +


    \glstreenamebox{width}{text}

    +

    + where ⟨width⟩ is the width of the box and ⟨text⟩ is the contents of the box. For example, to make the name + right-aligned: + + +

    +
    + \renewcommand*{\glstreenamebox}[2]{% +  
      \makebox[#1][r]{#2}% +  
    } +
    +

    +

    +alttreegroup
    The alttreegroup is like the alttree style except that each group has a heading. +
    +alttreehypergroup
    The alttreehypergroup style is like alttreegroup but has a set of links to the glossary groups. + The navigation line is the same as that for listhypergroup, described above. +
    +

    +

    +

    Top

    15.1.8 Multicols Style

    +

    The glossary-mcols package provides tree-like styles that are in the multicols environment (defined by the multicol +package). The style names are as their analogous tree styles (as defined in §15.1.7 Tree-Like Styles) but are +prefixed with “mcol”. For example, the mcolindex style is essentially the index style but put in a multicols +environment. For the complete list, see table 15.2. The glossary-tree package is automatically loaded by +glossary-mcols (even if the notree package option is used when loading glossaries). The formatting commands +\glstreenamefmt, \glstreegroupheaderfmt and \glstreenavigationfmt are all used by the corresponding +glossary-mcols styles. +

    Note that glossary-mcols is not loaded by glossaries. If you want to use any of the multicol styles in that +package you need to load it explicitly with \usepackage and set the required glossary style using +\setglossarystyle.
    +

    +

    The default number of columns is 2, but can be changed by redefining +


    \glsmcols

    +

    +to the required number. For example, for a three column glossary: + + +

    +
    +\usepackage{glossary-mcols} + 
    \renewcommand*{\glsmcols}{3} + 
    \setglossarystyle{mcolindex} +
    +

    +

    +
    + + +


    + + +
    Table 15.2: Multicolumn Styles
    +
    + + + + + + + + + +
    glossary-mcols Style Analogous Tree Style
    mcolindex index
    mcolindexgroup indexgroup
    mcolindexhypergroup or mcolindexspannav indexhypergroup
    mcoltree tree
    mcoltreegroup treegroup
    mcoltreehypergroup or mcoltreespannav treehypergroup
    mcoltreenoname treenoname
    mcoltreenonamegroup treenonamegroup
    mcoltreenonamehypergroup or mcoltreenonamespannav treenonamehypergroup
    mcolalttree alttree
    mcolalttreegroup alttreegroup
    mcolalttreehypergroup or mcolalttreespannav alttreehypergroup
    + + +

    +
    +

    The styles with a navigation line, such as mcoltreehypergroup, now have a variant (as from +v4.22) with “hypergroup” replaced with “spannav” in the style name. The original “hypergroup” +styles place the navigation line at the start of the first column. The newer “spannav” styles put the +navigation line in the optional argument of the multicols environment so that it spans across all the +columns. +

    +

    Top

    15.1.9 In-Line Style

    +

    This section covers the glossary-inline package that supplies the inline style. This is a style that is designed for +in-line use (as opposed to block styles, such as lists or tables). This style doesn’t display the number +list. +

    You will most likely need to redefine \glossarysection with this style. For example, suppose you are +required to have your glossaries and list of acronyms in a footnote, you can do: + + +

    +
    + \usepackage{glossary-inline} + 
     \renewcommand*{\glossarysection}[2][]{\textbf{#1}: } + 
     \setglossarystyle{inline} +
    +

    +

    Note that you need to include glossary-inline with \usepackage as it’s not automatically included by the +glossaries package and then set the style using \setglossarystyle.
    +

    +

    Where you need to include your glossaries as a footnote you can do: + + +

    +
    +\footnote{\printglossaries} +
    +

    +

    The inline style is governed by the following: +


    \glsinlineseparator

    +

    +This defaults to “; ” and is used between main (i.e. level 0) entries. +


    \glsinlinesubseparator

    +

    +This defaults to “, ” and is used between sub-entries. +


    \glsinlineparentchildseparator

    +

    +This defaults to “: ” and is used between a parent main entry and its first sub-entry. +


    \glspostinline

    +

    +This defaults to “; ” and is used at the end of the glossary. +


    \glsinlinenameformat{label}{name}

    +

    +This is used to format the entry name and defaults to \glstarget{label}{name}, where ⟨name⟩ is provided in +the form \glossentryname{label} and ⟨label⟩ is the entry’s label. For example, if you want the name to appear in +small caps: + + +

    +
    +\renewcommand*{\glsinlinenameformat}[2]{\glstarget{#1}{\textsc{#2}}} +
    +

    Sub-entry names are formatted according to +


    \glsinlinesubnameformat{label}{name}

    +

    +This defaults to \glstarget{label}{} so the sub-entry name is ignored. +

    If the description has been suppressed (according to \ifglsdescsuppressed) then +


    \glsinlineemptydescformat{symbol}{number list}

    +

    +(which defaults to nothing) is used, otherwise the description is formatted according to +


    \glsinlinedescformat{description}{symbol}{number list}

    +

    +This defaults to just \spacedescription⟩ so the symbol and location list are ignored. If the description is missing +(according to \ifglshasdesc), then \glsinlineemptydescformat is used instead. +

    For example, if you want a colon between the name and the description: + + +

    +
    +\renewcommand*{\glsinlinedescformat}[3]{: #1} +
    +

    +

    The sub-entry description is formatted according to: +


    \glsinlinesubdescformat{description}{symbol}{number list}

    +

    +This defaults to just ⟨description⟩. +

    +

    +

    Top

    15.2 Defining your own glossary style

    +

    If the predefined styles don’t fit your requirements, you can define your own style using: +


    \newglossarystyle{name}{definitions}

    +

    +where ⟨name⟩ is the name of the new glossary style (to be used in \setglossarystyle). The second argument +⟨definitions⟩ needs to redefine all of the following: +


    theglossary

    +

    +This environment defines how the main body of the glossary should be typeset. +

    Note that this does not include the section heading, the glossary preamble (defined by \glossarypreamble) +or the glossary postamble (defined by \glossarypostamble). For example, the list style uses the description +environment, so the theglossary environment is simply redefined to begin and end the description +environment. +


    \glossaryheader

    +

    +This macro indicates what to do at the start of the main body of the glossary. Note that this is not the same as +\glossarypreamble, which should not be affected by changes in the glossary style. The list glossary style +redefines \glossaryheader to do nothing, whereas the longheader glossary style redefines \glossaryheader to +do a header row. +


    \glsgroupheading{label}

    +

    +This macro indicates what to do at the start of each logical block within the main body of the glossary. If you +use makeindex the glossary is sub-divided into a maximum of twenty-eight logical blocks that are determined by +the first character of the sort key (or name key if the sort key is omitted). The sub-divisions are in the +following order: symbols, numbers, A, …, Z. If you use xindy, the sub-divisions depend on the language +settings. +

    Note that the argument to \glsgroupheading is a label not the group title. The group title can be obtained +via +


    \glsgetgrouptitle{label}

    + + +

    +This obtains the title as follows: if ⟨label⟩ consists of a single non-active character or ⟨label⟩ is equal to glssymbols +or glsnumbers and \labelgroupname exists, this is taken to be the title, otherwise the title is just ⟨label⟩. +(The “symbols” group has the label glssymbols, so the command \glssymbolsgroupname is used, +and the “numbers” group has the label glsnumbers, so the command \glsnumbersgrouptitle is +used.) If you are using xindy, ⟨label⟩ may be an active character (for example ø), in which case the +title will be set to just ⟨label⟩. You can redefine \glsgetgrouptitle if this is unsuitable for your +document. +

    A navigation hypertarget can be created using +


    \glsnavhypertarget{label}{text}

    +

    +This typically requires \glossaryheader to be redefined to use +


    \glsnavigation

    +

    +which displays the navigation line. +

    For further details about \glsnavhypertarget, see the documented code (glossaries-code.pdf). +

    Most of the predefined glossary styles redefine \glsgroupheading to simply ignore its argument. The +listhypergroup style redefines \glsgroupheading as follows: + + +

    +
    +\renewcommand*{\glsgroupheading}[1]{% + 
    \item[\glsnavhypertarget{##1}{\glsgetgrouptitle{##1}}]} +
    +

    See also \glsgroupskip below. +

    Note that command definitions within \newglossarystyle must use ##1 instead of #1 etc. +


    \glsgroupskip

    +

    +This macro determines what to do after one logical group but before the header for the next logical group. The +list glossary style simply redefines \glsgroupskip to be \indexspace, whereas the tabular-like styles redefine +\glsgroupskip to produce a blank row. +

    As from version 3.03, the package option nogroupskip can be used to suppress this default gap for the +predefined styles. +


    \glossentry{label}{number list}

    +

    +This macro indicates what to do for each top-level (level 0) glossary entry. The entry label is given by ⟨label⟩ and +the associated number list is given by ⟨number list⟩. You can redefine \glossentry to use commands like +\glossentryname{label}, \glossentrydesc{label} and \glossentrysymbol{label} to display the name, +description and symbol fields, or to access other fields, use commands like \glsentryuseri{label}. +(See §9 Using Glossary Terms Without Links for further details.) You can also use the following +commands: +


    \glsentryitem{label}

    +

    +This macro will increment and display the associated counter for the main (level 0) entries if the entrycounter or +counterwithin package options have been used. This macro is typically called by \glossentry before +\glstarget. The format of the counter is controlled by the macro +


    \glsentrycounterlabel

    +

    +

    Each time you use a glossary entry it creates a hyperlink (if hyperlinks are enabled) to the relevant line in +the glossary. Your new glossary style must therefore redefine \glossentry to set the appropriate target. This is +done using +


    \glstarget{label}{text}

    +

    +where ⟨label⟩ is the entry’s label. Note that you don’t need to worry about whether the hyperref package has been +loaded, as \glstarget won’t create a target if \hypertarget hasn’t been defined. +

    For example, the list style defines \glossentry as follows: + + +

    +
    +  \renewcommand*{\glossentry}[2]{% + 
        \item[\glsentryitem{##1}% + 
              \glstarget{##1}{\glossentryname{##1}}] + 
           \glossentrydesc{##1}\glspostdescription\space ##2} +
    +

    +

    Note also that ⟨number list⟩ will always be of the form +


    \glossaryentrynumbers{\relax
    \setentrycounter[Hprefix]{counter name}format cmd{number(s)}}

    +

    +where ⟨number(s)⟩ may contain \delimN (to delimit individual numbers) and/or \delimR (to indicate a range of +numbers). There may be multiple occurrences of \setentrycounter[Hprefix]{counter name}format cmd⟩ +{number(s)}, but note that the entire number list is enclosed within the argument of \glossaryentrynumbers. +The user can redefine this to change the way the entire number list is formatted, regardless of the glossary style. +However the most common use of \glossaryentrynumbers is to provide a means of suppressing the number list +altogether. (In fact, the nonumberlist option redefines \glossaryentrynumbers to ignore its argument.) +Therefore, when you define a new glossary style, you don’t need to worry about whether the user has specified +the nonumberlist package option. +


    \subglossentry{level}{label}{number list}

    +

    +This is used to display sub-entries. The first argument, ⟨level⟩, indicates the sub-entry level. This must be an +integer from 1 (first sub-level) onwards. The remaining arguments are analogous to those for \glossentry +described above. +


    \glssubentryitem{label}

    +

    +This macro will increment and display the associated counter for the level 1 entries if the subentrycounter +package option has been used. This macro is typically called by \subglossentry before \glstarget. The +format of the counter is controlled by the macro +


    \glssubentrycounterlabel

    +

    +

    Note that \printglossary (which \printglossaries calls) sets +


    \currentglossary

    +

    +to the current glossary label, so it’s possible to create a glossary style that varies according to the glossary +type. +

    For further details of these commands, see “Displaying the glossary” in the documented code +(glossaries-code.pdf). + +

    Example 27 (Creating a completely new style) +

    If you want a completely new style, you will need to redefine all of the commands and the environment listed + + +above. +

    For example, suppose you want each entry to start with a bullet point. This means that the glossary should +be placed in the itemize environment, so theglossary should start and end that environment. Let’s also suppose +that you don’t want anything between the glossary groups (so \glsgroupheading and \glsgroupskip should +do nothing) and suppose you don’t want anything to appear immediately after \begin{theglossary} (so +\glossaryheader should do nothing). In addition, let’s suppose the symbol should appear in brackets +after the name, followed by the description and last of all the number list should appear within +square brackets at the end. Then you can create this new glossary style, called, say, mylist, as +follows: + + +

    +
    + \newglossarystyle{mylist}{% + 
     % put the glossary in the itemize environment: + 
     \renewenvironment{theglossary}% + 
       {\begin{itemize}}{\end{itemize}}% + 
     % have nothing after \begin{theglossary}: + 
     \renewcommand*{\glossaryheader}{}% + 
     % have nothing between glossary groups: + 
     \renewcommand*{\glsgroupheading}[1]{}% + 
     \renewcommand*{\glsgroupskip}{}% + 
     % set how each entry should appear: + 
     \renewcommand*{\glossentry}[2]{% + 
     \item % bullet point + 
     \glstarget{##1}{\glossentryname{##1}}% the entry name + 
     \space (\glossentrysymbol{##1})% the symbol in brackets + 
     \space \glossentrydesc{##1}% the description + 
     \space [##2]% the number list in square brackets + 
     }% + 
     % set how sub-entries appear: + 
     \renewcommand*{\subglossentry}[3]{% + 
       \glossentry{##2}{##3}}% + 
     } +
    +

    Note that this style creates a flat glossary, where sub-entries are displayed in exactly the same way as the top +level entries. It also hasn’t used \glsentryitem or \glssubentryitem so it won’t be affected by the +entrycounter, counterwithin or subentrycounter package options. +

    Variations:

    +
      +
    • You might want the entry name to be capitalised, in which case use \Glossentryname instead of + \glossentryname. +
    • +
    • You might want to check if the symbol hasn’t been set and omit the parentheses if the symbol is absent. In + this case you can use \ifglshassymbol (see §16 Utilities): + + +
      +  \renewcommand*{\glossentry}[2]{% +  
       \item % bullet point +  
       \glstarget{##1}{\glossentryname{##1}}% the entry name +  
       \ifglshassymbol{##1}% check if symbol exists +  
       {% +  
         \space (\glossentrysymbol{##1})% the symbol in brackets +  
       }% +  
       {}% no symbol so do nothing +  
       \space \glossentrydesc{##1}% the description +  
       \space [##2]% the number list in square brackets +  
       }% +
      +

    +
    +

    +

    ____________________________

    + +

    Example 28 (Creating a new glossary style based on an existing style) +

    If you want to define a new style that is a slightly modified version of an existing style, you can use +\setglossarystyle within the second argument of \newglossarystyle followed by whatever alterations you +require. For example, suppose you want a style like the list style but you don’t want the extra vertical space +created by \indexspace between groups, then you can create a new glossary style called, say, mylist as +follows: + + +

    +
    +\newglossarystyle{mylist}{% + 
    \setglossarystyle{list}% base this style on the list style + 
    \renewcommand{\glsgroupskip}{}% make nothing happen + 
                                  % between groups + 
    } +
    +

    (In this case, you can actually achieve the same effect using the list style in combination with the package +option nogroupskip.)

    +
    +

    +

    ____________________________

    + +

    Example 29 (Example: creating a glossary style that uses the user1, …, user6 +keys) +

    Suppose each entry not only has an associated symbol, but also units (stored in user1) and dimension +(stored in user2). Then you can define a glossary style that displays each entry in a longtable as +follows: + + +

    +
    +\newglossarystyle{long6col}{% + 
     % put the glossary in a longtable environment: + 
     \renewenvironment{theglossary}% + 
      {\begin{longtable}{lp{\glsdescwidth}cccp{\glspagelistwidth}}}% + 
      {\end{longtable}}% + 
     % Set the table's header: + 
     \renewcommand*{\glossaryheader}{% + 
      \bfseries Term & \bfseries Description & \bfseries Symbol & + 
      \bfseries Units & \bfseries Dimensions & \bfseries Page List + 
      \\\endhead}% + 
     % No heading between groups: + 
      \renewcommand*{\glsgroupheading}[1]{}% + 
     % Main (level 0) entries displayed in a row optionally numbered: + 
      \renewcommand*{\glossentry}[2]{% + 
        \glsentryitem{##1}% Entry number if required + 
        \glstarget{##1}{\glossentryname{##1}}% Name + 
        & \glossentrydesc{##1}% Description + 
        & \glossentrysymbol{##1}% Symbol + 
        & \glsentryuseri{##1}% Units + 
        & \glsentryuserii{##1}% Dimensions + 
        & ##2% Page list + 
        \tabularnewline % end of row + 
      }% + 
     % Similarly for sub-entries (no sub-entry numbers): + 
     \renewcommand*{\subglossentry}[3]{% + 
        % ignoring first argument (sub-level) + 
        \glstarget{##2}{\glossentryname{##2}}% Name + 
        & \glossentrydesc{##2}% Description + 
        & \glossentrysymbol{##2}% Symbol + 
        & \glsentryuseri{##2}% Units + 
        & \glsentryuserii{##2}% Dimensions + 
        & ##3% Page list + 
        \tabularnewline % end of row + 
      }% + 
     % Nothing between groups: + 
     \renewcommand*{\glsgroupskip}{}% + 
    } +
    +

    +
    +

    +

    ____________________________

    + + +

    +

    Top

    16. Utilities

    +

    This section describes some utility commands. Additional commands can be found in the documented code +(glossaries-code.pdf). +

    The glossaries-extra package provides extra utility commands. See the “Utilities” section of the +glossaries-extra manual.
    +

    +

    +

    Top

    16.1 Loops

    +

    Some of the commands described here take a comma-separated list as an argument. As with LATEX’s \@for +command, make sure your list doesn’t have any unwanted spaces in it as they don’t get stripped. (Discussed in +more detail in §2.7.2 of “LATEX for Administrative Work”.)
    +

    +


    \forallglossaries[glossary list]{cs}{body}

    +

    +This iterates through ⟨glossary list⟩, a comma-separated list of glossary labels (as supplied when the glossary was +defined). At each iteration ⟨cs⟩ (which must be a control sequence) is set to the glossary label for the current +iteration and ⟨body⟩ is performed. If ⟨glossary list⟩ is omitted, the default is to iterate over all glossaries (except the +ignored ones). +


    \forallacronyms{cs}{body}

    +

    +This is like \forallglossaries but only iterates over the lists of acronyms (that have previously been declared +using \DeclareAcronymList or the acronymlists package option). This command doesn’t have an optional +argument. If you want to explicitly say which lists to iterate over, just use the optional argument of +\forallglossaries. +


    \forglsentries[glossary label]{cs}{body}

    +

    +This iterates through all entries in the glossary given by ⟨glossary label⟩. At each iteration ⟨cs⟩ (which must be a +control sequence) is set to the entry label for the current iteration and ⟨body⟩ is performed. If ⟨glossary label⟩ is +omitted, \glsdefaulttype (usually the main glossary) is used. +


    \forallglsentries[glossary list]{cs}{body}

    +

    +This is like \forglsentries but for each glossary in ⟨glossary list⟩ (a comma-separated list of glossary labels). If +⟨glossary list⟩ is omitted, the default is the list of all defined glossaries (except the ignored ones). At each iteration +⟨cs⟩ is set to the entry label and ⟨body⟩ is performed. (The current glossary label can be obtained using +\glsentrytype{cs} within ⟨body⟩.) +

    +

    +

    Top

    16.2 Conditionals

    +


    \ifglossaryexistslabel⟩⟨true part⟩⟨false part

    + + +

    +This checks if the glossary given by ⟨label⟩ exists. If it does ⟨true part⟩ is performed, otherwise ⟨false +part⟩. +


    \ifglsentryexistslabel⟩⟨true part⟩⟨false part

    +

    +This checks if the glossary entry given by ⟨label⟩ exists. If it does ⟨true part⟩ is performed, otherwise ⟨false part⟩. +(Note that \ifglsentryexists will always be true after the containing glossary has been displayed via +\printglossary or \printglossaries even if the entry is explicitly defined later in the document. This is +because the entry has to be defined before it can be displayed in the glossary, see §4.8.1 Technical Issues for +further details.) +


    \glsdoifexists{label}{code}

    +

    +Does ⟨code⟩ if the entry given by ⟨label⟩ exists. If it doesn’t exist, an error is generated. (This command uses +\ifglsentryexists.) +


    \glsdoifnoexists{label}{code}

    +

    +Does the reverse of \glsdoifexists. (This command uses \ifglsentryexists.) +


    \glsdoifexistsorwarn{label}{code}

    +

    +As \glsdoifexists but issues a warning rather than an error if the entry doesn’t exist. +


    \glsdoifexistsordo{label}{code}{else code}

    +

    +Does ⟨code⟩ if the entry given by ⟨label⟩ exists otherwise generate an error and do ⟨else code⟩. +


    \glsdoifnoexistsordo{label}{code}{else code}

    +

    +Does ⟨code⟩ if the entry given by ⟨label⟩ doesn’t exist otherwise generate an error and do ⟨else code⟩. +


    \ifglsusedlabel⟩⟨true part⟩⟨false part

    +

    +See §14 Unsetting and Resetting Entry Flags. +


    \ifglshaschildrenlabel⟩⟨true part⟩⟨false part

    +

    +This checks if the glossary entry given by ⟨label⟩ has any sub-entries. If it does, ⟨true part⟩ is performed, otherwise +⟨false part⟩. +


    \ifglshasparentlabel⟩⟨true part⟩⟨false part

    +

    +This checks if the glossary entry given by ⟨label⟩ has a parent entry. If it does, ⟨true part⟩ is performed, otherwise +⟨false part⟩. +


    \ifglshassymbol{label}{true part}{false part}

    +

    +This checks if the glossary entry given by ⟨label⟩ has had the symbol field set. If it has, ⟨true part⟩ is performed, +otherwise ⟨false part⟩. +


    \ifglshaslong{label}{true part}{false part}

    +

    +This checks if the glossary entry given by ⟨label⟩ has had the long field set. If it has, ⟨true part⟩ is performed, +otherwise ⟨false part⟩. This should be true for any entry that has been defined via \newacronym. There is no +check for the existence of ⟨label⟩. + + +


    \ifglshasshort{label}{true part}{false part}

    +

    +This checks if the glossary entry given by ⟨label⟩ has had the short field set. If it has, ⟨true part⟩ is performed, +otherwise ⟨false part⟩. This should be true for any entry that has been defined via \newacronym. There is no +check for the existence of ⟨label⟩. +


    \ifglshasdesc{label}{true part}{false part}

    +

    +This checks if the description field is non-empty for the entry given by ⟨label⟩. If it has, ⟨true part⟩ is performed, +otherwise ⟨false part⟩. Compare with: +


    \ifglsdescsuppressed{label}{true part}{false part}

    +

    +This checks if the description field has been set to just \nopostdesc for the entry given by ⟨label⟩. If it has, ⟨true +part⟩ is performed, otherwise ⟨false part⟩. There is no check for the existence of ⟨label⟩. +

    For all other fields you can use: +


    \ifglshasfield{field}{label}{true part}{false part}

    +

    +This tests the value of the field given by ⟨field⟩ for the entry identified by ⟨label⟩. If the value is empty or the +default value, then ⟨false part⟩ is performed, otherwise ⟨true part⟩ is performed. If the field supplied is unrecognised +⟨false part⟩ is performed and a warning is issued. Unlike the above commands, such as \ifglshasshort, an error +occurs if the entry is undefined. +

    As from version 4.23, within ⟨true part⟩ you can use +


    \glscurrentfieldvalue

    +

    +to access the field value. This command is initially defined to nothing but has no relevance outside ⟨true part⟩. +This saves re-accessing the field if the test is true. For example: + + +

    +
    +\ifglshasfield{useri}{sample}{, \glscurrentfieldvalue}{} +
    +

    will insert a comma, space and the field value if the user1 key has been set for the entry whose label is +sample. +

    You can test if the value of the field is equal to a given string using: +


    \ifglsfieldeq{label}{field}{string}{true}{false}

    +

    +In this case the ⟨field⟩ must be the field name not the key (see table 4.1). If the field isn’t recognised, an error will +occur. This command internally uses etoolbox’s \ifcsstring to perform the comparison. The string is not +expanded during the test. +

    The result may vary depending on whether or not expansion is on for the given field (when the entry was +defined). For example: + +

    -
    -\setacronymstyle{custom-fn} +
    +\documentclass{article} + 
    \usepackage{glossaries} + 
    \newcommand*{\foo}{FOO} + 
    \newglossaryentry{sample1}{name={sample1},description={an example}, + 
    user1={FOO}} + 
    \newglossaryentry{sample2}{name={sample2},description={an example}, + 
    user1={\foo}} + 
    \begin{document} + 
    \ifglsfieldeq{sample1}{useri}{FOO}{TRUE}{FALSE}. + 
    \ifglsfieldeq{sample2}{useri}{FOO}{TRUE}{FALSE}. + 
    \end{document}
    -

    I also need to use a glossary style that suits this acronym style, for example altlist: - - +

    This will produce “TRUE” in both cases since expansion is on, so \foo was expanded to “FOO” when sample2 +was defined. If the tests are changed to: + +

    -
    -\setglossarystyle{altlist} +
    +\ifglsfieldeq{sample1}{useri}{\foo}{TRUE}{FALSE}. + 
    \ifglsfieldeq{sample2}{useri}{\foo}{TRUE}{FALSE}.
    -

    -

    Once the acronym style has been set, I can define my acronyms: - - +

    then this will produce “FALSE” in both cases. Now suppose expansion is switched off for the user1 +key: + +

    -
    -\newacronym[description={set of tags for use in - 
    developing hypertext documents}]{html}{html}{Hyper - 
    Text Markup Language} - 
    \newacronym[description={language used to describe the - 
    layout of a document written in a markup language}]{css} - 
    {css}{Cascading Style Sheet} +
    +\documentclass{article} + 
    \usepackage{glossaries} + 
    \newcommand*{\foo}{FOO} + 
    \glssetnoexpandfield{useri} + 
    \newglossaryentry{sample1}{name={sample1},description={an example}, + 
    user1={FOO}} + 
    \newglossaryentry{sample2}{name={sample2},description={an example}, + 
    user1={\foo}} + 
    \begin{document} + 
    \ifglsfieldeq{sample1}{useri}{FOO}{TRUE}{FALSE}. + 
    \ifglsfieldeq{sample2}{useri}{FOO}{TRUE}{FALSE}. + 
    \end{document}
    -

    -

    The sample file sample-custom-acronym.tex illustrates this example.

    -
    -

    -

    ____________________________

    +

    This now produces “TRUE” for the first case (comparing “FOO” with “FOO”) and “FALSE” for the second +case (comparing “\foo” with “FOO”). +

    The reverse happens in the following: + + +

    +
    +\documentclass{article} + 
    \usepackage{glossaries} + 
    \newcommand*{\foo}{FOO} + 
    \glssetnoexpandfield{useri} + 
    \newglossaryentry{sample1}{name={sample1},description={an example}, + 
    user1={FOO}} + 
    \newglossaryentry{sample2}{name={sample2},description={an example}, + 
    user1={\foo}} + 
    \begin{document} + 
    \ifglsfieldeq{sample1}{useri}{\foo}{TRUE}{FALSE}. + 
    \ifglsfieldeq{sample2}{useri}{\foo}{TRUE}{FALSE}. + 
    \end{document} +
    +

    This now produces “FALSE” for the first case (comparing “FOO” with “\foo”) and “TRUE” for the second +case (comparing “\foo” with “\foo”). +

    You can test if the value of a field is equal to the replacement text of a command using: +


    \ifglsfielddefeq{label}{field}{command}{true}{false}

    +

    +This internally uses etoolbox’s \ifdefstrequal command to perform the comparison. The argument ⟨command⟩ +must be a macro. +

    For example: + + +

    +
    +\documentclass{article} + 
    \usepackage{glossaries} + 
    \newcommand*{\foo}{FOO} + 
    \glssetnoexpandfield{useri} + 
    \newglossaryentry{sample1}{name={sample1},description={an example}, + 
    user1={FOO}} + 
    \newglossaryentry{sample2}{name={sample2},description={an example}, + 
    user1={\foo}} + 
    \begin{document} + 
    \ifglsfielddefeq{sample1}{useri}{\foo}{TRUE}{FALSE}. + 
    \ifglsfielddefeq{sample2}{useri}{\foo}{TRUE}{FALSE}. + 
    \end{document} +
    +

    Here, the first case produces “TRUE” since the value of the useri field (“FOO”) is the same as the +replacement text (definition) of \foo (“FOO”). We have the result “FOO” is equal to “FOO”. +

    The second case produces “FALSE” since the value of the useri field (“\foo”) is not the same as the +replacement text (definition) of \foo (“FOO”). No expansion has been performed on the value of the useri +field. We have the result “\foo” is not equal to “FOO”. +

    If we add: + + +

    +
    +\newcommand{\FOO}{\foo} + 
    \ifglsfielddefeq{sample2}{useri}{\FOO}{TRUE}{FALSE}. +
    +

    we now get “TRUE” since the value of the useri field (“\foo”) is the same as the replacement text (definition) +of \FOO (“\foo”). We have the result “\foo” is equal to “\foo”. +

    There is a similar command that requires the control sequence name (without the leading backslash) instead +of the actual control sequence: +


    \ifglsfieldcseq{label}{field}{csname}{true}{false}

    +

    +This internally uses etoolbox’s \ifcsstrequal command instead of \ifdefstrequal. +

    +

    +

    Top

    16.3 Fetching and Updating the Value of a Field

    +

    In addition to the commands described in §9 Using Glossary Terms Without Links, the following may also be +used to fetch field information. +


    \glsentrytype{label}

    +

    +Expands to the entry’s glossary type. No existence check is performed. +


    \glsentryparent{label}

    +

    +Expands to the label of the entry’s parent. No existence check is performed. +


    \glsentrysort{label}

    +

    +Expands to the entry’s sort value. No existence check is performed. +

    You can fetch the value of a given field and store it in a control sequence using: +


    \glsfieldfetch{label}{field}{cs}

    +

    +where ⟨label⟩ is the label identifying the glossary entry, ⟨field⟩ is the field label (see table 4.1) and ⟨cs⟩ is the control +sequence in which to store the value. Remember that ⟨field⟩ is the internal label and is not necessarily the same as +the key used to set that field in the argument of \newglossaryentry (or the optional argument of +\newacronym). +

    You can change the value of a given field using one of the following commands. Note that these commands +only change the value of the given field. They have no affect on any related field. For example, if you change the +value of the text field, it won’t modify the value given by the name, plural, first or any other related +key. +

    In all the four related commands below, ⟨label⟩ and ⟨field⟩ are as above and ⟨definition⟩ is the new value of the +field. +


    \glsfielddef{label}{field}{definition}

    +

    +This uses \def to change the value of the field (so it will be localised by any grouping). + + +


    \glsfieldedef{label}{field}{definition}

    +

    +This uses \edef to change the value of the field (so it will be localised by any grouping). Any fragile commands +contained in the ⟨definition⟩ must be protected. +


    \glsfieldgdef{label}{field}{definition}

    +

    +This uses \gdef to change the value of the field. +


    \glsfieldxdef{label}{field}{definition}

    +

    +This uses \xdef to change the value of the field. Any fragile commands contained in the ⟨definition⟩ must be +protected. + + +

    +

    +

    Top

    17. Prefixes or Determiners

    +

    The glossaries-prefix package that comes with the glossaries package provides additional keys that can be +used as prefixes. For example, if you want to specify determiners (such as “a”, “an” or “the”). +The glossaries-prefix package automatically loads the glossaries package and has the same package +options. +

    The extra keys for \newglossaryentry are as follows: +

    +prefix
    The prefix associated with the text key. This defaults to nothing. +
    +prefixplural
    The prefix associated with the plural key. This defaults to nothing. +
    +prefixfirst
    The prefix associated with the first key. If omitted, this defaults to the value of the + prefix key. +
    +prefixfirstplural
    The prefix associated with the firstplural key. If omitted, this defaults to the + value of the prefixplural key.
    -

    Example 24 (Italic and Upright Abbreviations) -

    Suppose I want to have some abbreviations in italic and some that just use the -surrounding font. Hard-coding this into the ⟨short⟩ argument of \newacronym can cause -complications. -

    This example uses \glsaddstoragekey to add an extra field that can be used to store the -formatting declaration (such as \em). - - + id="ex:determiners"> +

    Example 30 (Defining Determiners) +

    Here’s the start of my example document: + +

    -
    -\glsaddstoragekey{font}{}{\entryfont} +
    +\documentclass{article} + 
    \usepackage[colorlinks]{hyperref} + 
    \usepackage[toc,acronym]{glossaries-prefix} +
    +

    Note that I’ve simply replaced glossaries from previous sample documents with glossaries-prefix. Now for a sample +definition17.1: + + +

    +
    +\newglossaryentry{sample}{name={sample},% + 
      description={an example},% + 
      prefix={a~},% + 
      prefixplural={the\space}% + 
    } +
    +

    Note that I’ve had to explicitly insert a space after the prefix since there’s no designated separator between the +prefix and the term being referenced. This not only means that you can vary between a breaking space and +non-breaking space, but also allows for the possibility of prefixes that shouldn’t have a space, such +as: + + +

    +
    +\newglossaryentry{oeil}{name={oeil}, + 
      plural={yeux}, + 
      description={eye}, + 
      prefix={l'}, + 
      prefixplural={les\space}}
    -

    This defines a new field/key called font, which defaults to nothing if it’s not explicitly set. -This also defines a command called \entryfont that’s analogous to \glsentrytext. A new -style is then created to format abbreviations that access this field. -

    There are two ways to do this. The first is to create a style that doesn’t use \glsgenacfmt -but instead provides a modified version that doesn’t use \acronymfont{short} but instead -uses {\entryfont{\glslabel}short}. The full format given by commands such as +

    Where a space is required at the end of the prefix, you must use a spacing command, such as \genacrfullformat need to be similarly adjusted. For example: - - +class="cmtt-10">\space, \␣ (backslash space) or ~ due to the automatic spacing trimming performed in ⟨key⟩=⟨value⟩ +options. +

    In the event that you always require a space between the prefix and the term, then you can instead +redefine +


    \glsprefixsep

    +

    +to do a space. (This command does nothing by default.) For example: + +

    -
    -  \renewcommand*{\genacrfullformat}[2]{% - 
       \glsentrylong{##1}##2\space - 
       ({\entryfont{##1}\glsentryshort{##1}})% - 
      }% +
    +\renewcommand{\glsprefixsep}{\space} +
    +

    +

    The prefixes can also be used with acronyms. For example: + + +

    +
    +\newacronym + 
     [% + 
       prefix={an\space},prefixfirst={a~}% + 
     ]{svm}{SVM}{support vector machine}
    -

    This will deal with commands like

    +
    +

    +

    ____________________________

    +

    The glossaries-prefix package provides convenient commands to use these prefixes with commands such as +\gls but not commands like \acrshort which still use + id="dx1-171019">. Note that the prefix is not considered part of the link text, so it’s not included in the hyperlink (where +hyperlinks are enabled). The options and any star or plus modifier are passed on to the \gls-like command. +(See §6 Links to Glossary Entries for further details.) +


    \pgls[options]{label}[insert]

    +

    +This is inserts the value of the prefix key (or prefixfirst key, on first use) in front of \gls[options]{label} \acronymfont. Another approach is to redefine \acronymfont to look up the required font -declaration. Since \acronymfont doesn’t take the entry label as an argument, the following -will only work if \acronymfont is used in a context where the label is provided by +class="cmtt-10">[⟨insert]. +


    \Pgls[options]{label}[insert]

    +

    +If the prefix key (or prefixfirst, on first use) has been set, this displays the value of that key with the first +letter converted to upper case followed by \gls[options]{label}[insert]. If that key hasn’t been set, this is +equivalent to \Gls[options]{label}[insert]. +


    \PGLS[options]{label}[insert]

    +

    +As \pgls but converts the prefix to upper case and uses \GLS instead of \gls. +


    \pglspl[options]{label}[insert]

    +

    +This is inserts the value of the prefixplural key (or prefixfirstplural key, on first use) in front of \glspl \glslabel. This is true in \gls, \acrshort and \acrfull. The redefinition is -now: - - +class="cmtt-10">[⟨options]{label}[insert]. +


    \Pglspl[options]{label}[insert]

    +

    +If the prefixplural key (or prefixfirstplural, on first use) has been set, this displays the value of that key +with the first letter converted to upper case followed by \glspl[options]{label}[insert]. If that key hasn’t been +set, this is equivalent to \Glspl[options]{label}[insert]. +


    \PGLSpl[options]{label}[insert]

    +

    +As \pglspl but converts the prefix to upper case and uses \GLSpl instead of \glspl. + +

    Example 31 (Using Prefixes) +

    Continuing from Example 30, now that I’ve defined my entries, I can use them in the text via the above + + +commands: + +

    -
    -\renewcommand*{\acronymfont}[1]{{\entryfont{\glslabel}#1}}% +
    +First use: \pgls{svm}. Next use: \pgls{svm}. + 
    Singular: \pgls{sample}, \pgls{oeil}. + 
    Plural: \pglspl{sample}, \pglspl{oeil}.
    -

    So the new style can be defined as: - - -

    -
    -\newacronymstyle{long-font-short} - 
    {% - 
      \GlsUseAcrEntryDispStyle{long-short}% - 
    } - 
    {% - 
      \GlsUseAcrStyleDefs{long-short}% - 
      \renewcommand*{\genacrfullformat}[2]{% - 
       \glsentrylong{##1}##2\space - 
       ({\entryfont{##1}\glsentryshort{##1}})% - 
      }% - 
      \renewcommand*{\Genacrfullformat}[2]{% - 
       \Glsentrylong{##1}##2\space - 
       ({\entryfont{##1}\glsentryshort{##1}})% - 
      }% - 
      \renewcommand*{\genplacrfullformat}[2]{% - 
       \glsentrylongpl{##1}##2\space - 
       ({\entryfont{##1}\glsentryshortpl{##1}})% - 
      }% - 
      \renewcommand*{\Genplacrfullformat}[2]{% - 
       \Glsentrylongpl{##1}##2\space - 
       ({\entryfont{##1}\glsentryshortpl{##1}})% - 
      }% - 
      \renewcommand*{\acronymfont}[1]{{\entryfont{\glslabel}##1}}% - 
      \renewcommand*{\acronymentry}[1]{{\entryfont{##1}\glsentryshort{##1}}}% +

    which produces: +

    +

    First use: a support vector machine (SVM). Next use: an SVM. Singular: a sample, l’oeil. + Plural: the samples, les yeux.

    +

    For a complete document, see sample-prefix.tex.

    +
    +

    +

    ____________________________

    +

    This package also provides the commands described below, none of which perform any check to determine +the entry’s existence. +


    \ifglshasprefix{label}{true part}{false part}

    +

    +Does ⟨true part⟩ if the entry identified by ⟨label⟩ has a non-empty value for the prefix key. +

    This package also provides the following commands: +


    \ifglshasprefixplural{label}{true part}{false part}

    +

    +Does ⟨true part⟩ if the entry identified by ⟨label⟩ has a non-empty value for the prefixplural key. +


    \ifglshasprefixfirst{label}{true part}{false part}

    +

    +Does ⟨true part⟩ if the entry identified by ⟨label⟩ has a non-empty value for the prefixfirst key. +


    \ifglshasprefixfirstplural{label}{true part}{false part}

    +

    +Does ⟨true part⟩ if the entry identified by ⟨label⟩ has a non-empty value for the prefixfirstplural +key. +


    \glsentryprefix{label}

    +

    +Displays the value of the prefix key for the entry given by ⟨label⟩. +


    \glsentryprefixfirst{label}

    +

    +Displays the value of the prefixfirst key for the entry given by ⟨label⟩. +


    \glsentryprefixplural{label}

    +

    +Displays the value of the prefixplural key for the entry given by ⟨label⟩. (No check is performed to determine if +the entry exists.) +


    \glsentryprefixfirstplural{label}

    + + +

    +Displays the value of the prefixfirstplural key for the entry given by ⟨label⟩. (No check is performed to +determine if the entry exists.) +

    There are also variants that convert the first letter to upper +case17.2: +


    \Glsentryprefix{label}

    +

    +


    \Glsentryprefixfirst{label}

    +

    +


    \Glsentryprefixplural{label}

    +

    +


    \Glsentryprefixfirstplural{label}

    +

    +

    As with analogous commands such as \Glsentrytext, these commands aren’t expandable so can’t be used +in PDF bookmarks.
    +

    + +

    Example 32 (Adding Determiner to Glossary Style) +

    You can use the above commands to define a new glossary style that uses the determiner. For +example, the following style is a slight modification of the list style that inserts the prefix before the +name: + + +

    +
    +\newglossarystyle{plist}{% + 
      \setglossarystyle{list}% + 
      \renewcommand*{\glossentry}[2]{% + 
        \item[\glsentryitem{##1}% + 
              \glsentryprefix{##1}% + 
              \glstarget{##1}{\glossentryname{##1}}] + 
           \glossentrydesc{##1}\glspostdescription\space ##2}%  
    }
    -

    Remember the style needs to be set before defining the entries: - - +

    If you want to change the prefix separator (\glsprefixsep) then the following is better: + +

    -
    -\setacronymstyle{long-font-short} +
    +\newglossarystyle{plist}{% + 
      \setglossarystyle{list}% + 
      \renewcommand*{\glossentry}[2]{% + 
        \item[\glsentryitem{##1}% + 
              \ifglshasprefix{##1}{\glsentryprefix{##1}\glsprefixsep}{}% + 
              \glstarget{##1}{\glossentryname{##1}}] + 
           \glossentrydesc{##1}\glspostdescription\space ##2}% + 
    }
    -

    -

    The complete document is contained in the sample file sample-font-abbr.tex. +

    The conditional is also useful if you want the style to use an uppercase letter at the start of the entry +item: + +

    +
    +\newglossarystyle{plist}{% + 
      \setglossarystyle{list}% + 
      \renewcommand*{\glossentry}[2]{% + 
        \item[\glsentryitem{##1}% + 
              \glstarget{##1}% + 
              {% + 
                \ifglshasprefix{##1}% + 
                {\Glsentryprefix{##1}\glsprefixsep\glossentryname{##1}}% + 
                {\Glossentryname{##1}}% + 
              }] + 
           \glossentrydesc{##1}\glspostdescription\space ##2}% + 
    } +
    +

    -

    -

    ____________________________

    -

    Some writers and publishing houses have started to drop full stops (periods) from upper -case initials but may still retain them for lower case abbreviations, while others -may still use them for both upper and lower case. This can cause complications. -Chapter 12 of The TEXbook discusses the spacing between words but, briefly, the default -behaviour of TEX is to assume that an upper case character followed by a full stop -and space is an abbreviation, so the space is the default inter-word space whereas -a lower case character followed by a full stop and space is a word occurring at the -end of a sentence. In the event that this isn’t true, you need to make a manual -adjustment using (back slash space) in place of just a space character for an -inter-word mid-sentence space and use \@ before the full stop to indicate the end of the -sentence. -

    For example: - - -

    -
    -I was awarded a B.Sc. and a Ph.D. (From the same place.) -
    -

    is typeset as -
    I was awarded a B.Sc. and a Ph.D. (From the same place.) -
    -The spacing is more noticeable with the typewriter font: - - +

    +

    ____________________________

    + + +

    +

    Top

    18. Accessibility Support

    +

    Limited accessibility support is provided by the accompanying glossaries-accsupp package, but note that this +package is experimental and it requires the accsupp package which is also listed as experimental. This package +automatically loads the glossaries package. Any options are passed to glossaries (if it hasn’t already been loaded). +For example: + +

    -
    -\ttfamily - 
    I was awarded a B.Sc. and a Ph.D. (From the same place.) +
    +\usepackage[acronym]{glossaries-accsupp}
    -

    is typeset as -
    I was awarded a B.Sc. and a Ph.D. (From the same place.) -
    -The lower case letter at the end of “B.Sc.” is confusing TEX into thinking that the full stop -after it marks the end of the sentence. Whereas the upper case letter at the end of “Ph.D.” -has confused TEX into thinking that the following full stop is just part of the abbreviation. -These can be corrected: - - +

    This will load glossaries with the acronym package option as well as loading glossaries-accsupp. +

    If you are using the glossaries-extra extension package, you need to load glossaries-extra with the accsupp +package option. For example: + +

    -
    -I was awarded a B.Sc.\ and a Ph.D\@. (From the same place.) +
    +\usepackage[abbreviations,accsupp]{glossaries-extra}
    -

    -

    This situation is a bit problematic for glossaries. The full stops can form part of -the ⟨short⟩ argument of \newacronym and the B.Sc.\␣ part can be dealt with by -remembering to add \␣ (for example, \gls{bsc}\␣) but the end of sentence case is -more troublesome as you need to omit the sentence terminating full stop (to avoid -two dots) which can make the source code look a little strange but you also need -to adjust the space factor, which is usually done by inserting \@ before the full -stop. -

    The next example shows one way of achieving this. (Note that the supplemental -

    This will load glossaries-extra package provides a much simpler way of doing this, which you may prefer to -use. See the initialisms example.) - -

    Example 25 (Abbreviations with Full Stops (Periods)) -

    As from version 4.16, there’s now a hook (\glspostlinkhook) that’s called at the very -end of the \gls-like and \glstext-like commands. This can be redefined to check if the -following character is a full stop. The amsgen package (which is automatically loaded by +class="cmss-10">glossaries-extra (with the abbreviations option), glossaries and glossaries-accsupp and make +appropriate patches to integrate the accessibility support with the extension commands. +

    The glossaries-accsupp package defines additional keys that may be used when defining glossary entries. The +keys are as follows: +

    glossaries) provides an internal command called \new@ifnextchar that can be used to -determine if the given character appears next. (For more information see the amsgen -documentation.) -

    It’s possible that I may also want acronyms or contractions in my document, so I need -some way to differentiate between them. Here I’m going to use the same method as in -example 4 where a new field is defined to indicate the type of abbreviation: - - -

    -
    -\glsaddstoragekey{abbrtype}{word}{\abbrtype} - 
    \newcommand*{\newabbr}[1][]{\newacronym[abbrtype=initials,#1]} -
    -

    Now I just use access

    + The + replacement + text + corresponding + to + the + name + key. +
    +textaccess
    + The + replacement + text + corresponding + to + the + text + key. +
    +firstaccess
    + The + replacement + text + corresponding + to + the + first + key. +
    + + +pluralaccess
    + The + replacement + text + corresponding + to + the + plural + key. +
    +firstpluralaccess
    + The + replacement + text + corresponding + to + the + firstplural + key. +
    +symbolaccess
    + The + replacement + text + corresponding + to + the + symbol + key. +
    +symbolpluralaccess
    + The + replacement + text + corresponding + to + the + symbolplural + key. +
    + + +descriptionaccess
    + The + replacement + text + corresponding + to + the + description + key. +
    +descriptionpluralaccess
    + The + replacement + text + corresponding + to + the + descriptionplural + key. +
    +longaccess
    + The + replacement + text + corresponding + to + the + long + key + (used + by + \newacronym for the acronyms, for example, - - -

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

    and my new command \newabbr for initials, for example, - - -

    -
    -\newabbr{eg}{e.g.}{exempli gratia} - 
    \newabbr{ie}{i.e.}{id est} - 
    \newabbr{bsc}{B.Sc.}{Bachelor of Science} - 
    \newabbr{ba}{B.A.}{Bachelor of Arts} - 
    \newabbr{agm}{A.G.M.}{annual general meeting} -
    -

    Within \glspostlinkhook the entry’s label can be accessed using \glslabel and + id="dx1-172033">). +

    \ifglsfieldeq can be used to determine if the current entry has the new abbrtype field set -to “initials”. If it doesn’t, then nothing needs to happen, but if it does, a check is performed -to see if the next character is a full stop. If it is, this signals the end of a sentence otherwise -it’s mid-sentence. -

    Remember that internal commands within the document file (rather than in a class or -package) need to be placed between \makeatletter and \makeatother: - - -

    -
    -\makeatletter - 
    \renewcommand{\glspostlinkhook}{% - 
     \ifglsfieldeq{\glslabel}{abbrtype}{initials}% - 
     {\new@ifnextchar.\doendsentence\doendword} - 
     {}% - 
    } - 
    \makeatother -
    -

    In the event that a full stop is found \doendsentence is performed but it will be followed by -the full stop, which needs to be discarded. Otherwise \doendword will be done but it won’t be -followed by a full stop so there’s nothing to discard. The definitions for these commands -are: - - -

    -
    -\newcommand{\doendsentence}[1]{\spacefactor=10000{}} - 
    \newcommand{\doendword}{\spacefactor=1000{}} -
    -

    Now, I can just do \gls{bsc} mid-sentence and \gls{phd}. at the end of the -sentence. The terminating full stop will be discarded in the latter case, but it won’t be -discarded in, say, \gls{laser}. as that doesn’t have the abbrtype field set to -“initials”. -

    This also works on first use when the style is set to one of the ⟨long⟩ (⟨short⟩) styles but it -will fail with the ⟨short⟩ (⟨long⟩) styles as in this case the terminating full stop shouldn’t be -discarded. Since \glspostlinkhook is used after the first use flag has been unset for the -entry, this can’t be fixed by simply checking with \ifglsused. One possible solution to this is -to redefine \glslinkpostsetkeys to check for the first use flag and define a macro that can -then be used in \glspostlinkhook. -

    The other thing to consider is what to do with plurals. One possibility is to check for -plural use within \doendsentence (using \glsifplural) and put the full stop back if the -plural has been used. -

    The complete document is contained in the sample file sample-dot-abbr.tex. -

    -
    -

    -

    ____________________________

    -

    -

    -

    Top

    13.2 Displaying the List of Acronyms

    -

    The list of acronyms is just like any other type of glossary and can be displayed on its own -using: -

    -Option 1:
    shortaccess
    -
    -
    + The + replacement + text + corresponding + to + the + short + + + key + (used + by + \newacronym). +
    +longpluralaccess
    + The + replacement + text + corresponding + to + the + longplural + key + (used + by + \newacronym). +
    +shortpluralaccess
    + The + replacement + text + corresponding + to + the + shortplural + key + (used + by \printnoidxglossary[type=\acronymtype] -
    -
    - - +class="cmtt-10">\newacronym).
    Options 2 and 3:
    user1access
    -
    -
    + The + replacement + text + corresponding + to + the \printglossary[type=\acronymtype] -
    -
    -

    (If you use the acronym package option you can also use

    -
    +class="cmtt-10">user1 + key. +
    + + +user2access
    + The + replacement + text + corresponding + to + the \printacronyms[options] -
    -
    as a synonym for
    -
    +class="cmtt-10">user2 + key. +
    +user3access
    + The + replacement + text + corresponding + to + the \printglossary[type=\acronymtype,options] -
    -
    See §2.5 Acronym Options.) - -

    Alternatively the list of acronyms can be displayed with all the other glossaries using: -

    -Option 1:
    \printnoidxglossaries +class="cmtt-10">user3 + key.
    Options 2 and 3:
    \printglossaries
    -

    However, care must be taken to choose a glossary style that’s appropriate to your acronym -style. Alternatively, you can define your own custom style (see §15.2 Defining your own -glossary style for further details). -

    -

    -

    Top

    13.3 Upgrading From the glossary Package

    -

    Users of the obsolete glossary package may recall that the syntax used to define new -acronyms has changed with the replacement glossaries package. In addition, the -old glossary package created the command \acr-name⟩ when defining the acronym -⟨acr-name⟩. - - -

    In order to facilitate migrating from the old package to the new one, the glossaries -package13.1 -provides the command: -


    \oldacronym  \oldacronym[label]{abbrv}{long}{key-val list}

    -

    -This uses the same syntax as the glossary package’s method of defining acronyms. It is -equivalent to: -
    \newacronym[key-val list]{label}{abbrv}{long} -
    -In addition, \oldacronym also defines the commands \label⟩, which is equivalent to \gls +class="cmtt-10">user4access

    + The + replacement + text + corresponding + to + the + user4 + key. +
    {label}, and \label*, which is equivalent to \Gls{label}. If ⟨label⟩ is omitted, ⟨abbrv⟩ is used. -Since commands names must consist only of alphabetical characters, ⟨label⟩ must also only -consist of alphabetical characters. Note that \label⟩ doesn’t allow you to use the first optional -argument of \gls or \Gls — you will need to explicitly use \gls or \Gls to change the -settings. -

    Recall that, in general, LATEX ignores spaces following command names consisting of -alphabetical characters. This is also true for \label⟩ unless you additionally load the xspace -package, but be aware that there are some issues with using xspace.13.2
    -

    - -

    The glossaries package doesn’t load the xspace package since there are both advantages -and disadvantages to using \xspace in \label⟩. If you don’t use the xspace package -you need to explicitly force a space using \␣ (backslash space) however you can -follow \label⟩ with additional text in square brackets (the final optional argument -to \gls). If you use the xspace package you don’t need to escape the spaces but -you can’t use the optional argument to insert text (you will have to explicitly use +class="cmtt-10">user5access

    + The + replacement + text + corresponding + to + the + user5 + key. +
    + + \gls). -

    To illustrate this, suppose I define the acronym “abc” as follows: - - -

    -
    -\oldacronym{abc}{example acronym}{} +class="cmtt-10">user6access
    + The + replacement + text + corresponding + to + the + user6 + key.
    +

    For example: + + +

    +
    +\newglossaryentry{tex}{name={\TeX},description={Document + 
    preparation language},access={TeX}}
    -

    This will create the command \abc and its starred version \abc*. Table 13.2 illustrates the -effect of \abc (on subsequent use) according to whether or not the xspace package has been -loaded. As can be seen from the final row in the table, the xspace package prevents the -optional argument from being recognised. +

    Now the link text produced by \gls{tex} will be: + +

    -
    - - -


    - - -
    Table 13.2: The effect of using xspace with \oldacronym
    -
    - - - - -
    Code With xspace Without xspace
    \abc. abc. abc.
    \abc xyz abc xyz abcxyz
    \abc\ xyz abc xyz abc xyz
    \abc* xyz Abc xyz Abc xyz
    \abc[’s] xyz abc [’s] xyz abc’s xyz
    +
    +\BeginAccSupp{ActualText={TeX}}\TeX\EndAccSupp{}
    - - -

    -
    - - -

    -

    Top

    14. Unsetting and Resetting Entry Flags

    -

    When using the \gls-like commands it is possible that you may want to use the -value given by the first key, even though you have already used the glossary entry. -Conversely, you may want to use the value given by the text key, even though you -haven’t used the glossary entry. The former can be achieved by one of the following -commands: -


    \glsreset  \glsreset{label

    The sample file sampleaccsupp.tex illustrates the glossaries-accsupp package. +

    If you prefer to use accessibility or tagpdf instead of accsupp then you’ll need to define \gls@accsupp@engine +and \gls@accessibility before loading glossaries-accsupp. See the section “Accessibility Support”in the +documented code for further details. +

    The PDF specification identifies three different types of replacement text: +

    +Alt
    Description of some content that’s non-textual (for example, an image). A word break is assumed + after the content. +
    +ActualText
    A character or sequence of characters that replaces textual content (for example, a dropped + capital, a ligature or a symbol). No word break is assumed after the content. +
    +E
    Expansion of an abbreviation to avoid ambiguity (for example, “St” could be short for “saint” or + “street”).
    +

    Many PDF viewers don’t actually support any type of replacement text. Some may support “ActualText” +but not “Alt” or “E”. PDFBox’s “PDFDebugger” tool can be used to inspect the PDF content to make sure +that the replacement text has been correctly set.
    +

    +

    If you define abbreviations with \newacronym, the shortaccess field will automatically be set +to: +


    \glsdefaultshortaccess{long}{short}

    -

    -


    \glslocalreset  \glslocalreset{label

    +With the base glossaries package this just expands to ⟨long⟩. With glossaries-extra this expands to ⟨long⟩ (⟨short⟩). +This command must be fully expandable. It expands when the abbreviation is defined. +

    As from glossaries-accsupp v4.45, the helper command used to identify the replacement text depends on the +field name. Previous versions just used: +


    \glsaccsupp{replacement}{content}

    -

    -while the latter can be achieved by one of the following commands: -


    \glsunset  \glsunset{

    +for all fields. This is defined to use ActualText, which is appropriate for symbols but not for abbreviations. +

    As from v4.45, there’s a new helper command: +


    \glsfieldaccsupp{replacement}{content}{field}{label}

    -

    -


    \glslocalunset  \glslocalunset{label

    +This will use \glsfieldaccsupp if it’s defined otherwise it will just use \glsaccsupp. There are just two of +these field commands for short and shortplural: +


    \glsshortaccsupp{replacement}{content}

    -

    -You can also reset or unset all entries for a given glossary or list of glossaries using: -


    \glsresetall  \glsresetall[glossary list]

    -

    -


    \glslocalresetall  \glslocalresetall[glossary list]

    -

    -


    \glsunsetall  \glsunsetall[glossary list]

    -

    -


    \glslocalunsetall  \glslocalunsetall[glossary list]

    -

    -where ⟨glossary list⟩ is a comma-separated list of glossary labels. If omitted, all defined -glossaries are assumed (except for the ignored ones). For example, to reset all entries in the -main glossary and the list of acronyms: - - -

    -
    -\glsresetall[main,acronym] -
    -

    -

    You can determine whether an entry’s first use flag is set using: -


    \ifglsused  \ifglsused{label

    +which is like \glsaccsupp but uses E instead of ActualText and +


    \glsshortplaccsupp{replacement}{true partcontent}

    + + +

    +which just does \glsshortaccsupp{replacement}{false partcontent}. Note that ⟨field⟩ indicates the internal field name +(such as shortpl) not the key name (such as shortplural). See table 4.1. +

    Rather than explicitly using \BeginAccSupp, these helper commands can use: +


    \glsaccessibility[options]{tag}{value}{content}

    -

    +

    where ⟨label⟩ is the label of the required entry. If the entry has been used, ⟨true part⟩ will be -done, otherwise ⟨false part⟩ will be done. -

    Be careful when using \gls-like commands within an environment or command -argument that gets processed multiple times as it can cause unwanted side-effects when the -first use displayed text is different from subsequent use.
    -

    -

    For example, the frame environment in beamer processes its argument for each overlay. -This means that the first use flag will be unset on the first overlay and subsequent overlays -will use the non-first use form. -

    Consider the following example: - - +class="cmti-10">tag⟩ is one of E, Alt or ActualText. The replacement text for ⟨content⟩ should be provided in ⟨value⟩. This +does:

    +
    +\BeginAccSupp{tag={value},options}content\EndAccSupp{} +
    +
    but it also provides debugging information if debug=showaccsupp is used. If you explicitly use \BeginAccSupp +instead of this command then the debugging support won’t be available. +

    You can define your own custom helper commands for specific fields that require them. For +example: + +

    -
    -\documentclass{beamer} - 
    \usepackage{glossaries} - 
    \newacronym{svm}{SVM}{support vector machine} - 
    \begin{document} - 
    \begin{frame} - 
     \frametitle{Frame 1} - 
     \begin{itemize} - 
      \item<+-> \gls{svm} - 
      \item<+-> Stuff. - 
     \end{itemize} - 
    \end{frame} - 
    \end{document} +
    +\newcommand{\glssymbolaccsupp}[2]{% + 
     \glsaccessibility[method=hex,unicode]{ActualText}{#1}{#2}% + 
    }
    -

    -

    On the first overlay, \gls{svm} produces “support vector machine (SVM)” and then -unsets the first use flag. When the second overlay is processed, \gls{svm} now produces -“SVM”, which is unlikely to be the desired effect. I don’t know anyway around this and I can -only offer two suggestions. -

    Firstly, unset all acronyms at the start of the document and explicitly use \acrfull when -you want the full version to be displayed: - - +

    This definition requires the replacement text to be specified with the hexadecimal character code. For +example: + +

    -
    -\documentclass{beamer} - 
    \usepackage{glossaries} - 
    \newacronym{svm}{SVM}{support vector machine} - 
    \glsunsetall - 
    \begin{document} - 
    \begin{frame} - 
     \frametitle{Frame 1} - 
     \begin{itemize} - 
      \item<+-> \acrfull{svm} - 
      \item<+-> Stuff. - 
     \end{itemize} - 
    \end{frame} - 
    \end{document} +
    +\newglossaryentry{int}{name={int},description={integral}, + 
      symbol={\ensuremath{\int}},symbolaccess={222B} + 
    }
    -

    -

    Secondly, explicitly reset each acronym on first use: - - -

    -
    -\begin{frame} - 
     \frametitle{Frame 1} - 
     \begin{itemize} - 
      \item<+-> \glsreset{svm}\gls{svm} - 
      \item<+-> Stuff. - 
     \end{itemize} - 
    \end{frame} +

    +

    If you are using glossaries-extra, then \glsfieldaccsupp will first test for the existence of +\glsxtrcategory⟩⟨fieldaccsupp and \glsxtrcategoryaccsupp and then for \glsfieldaccsupp. For +example: + + +

    +
    +\usepackage{siunitx} + 
    \usepackage[accsupp]{glossaries-extra} + 
    \glsnoexpandfields + 
    \newcommand{\glsxtrsymbolaccsupp}[2]{% + 
     \glsaccessibility[method=hex,unicode]{ActualText}{#1}{#2}% + 
    } + 
    \newcommand{\glsxtrunitaccsupp}[2]{\glsaccessibility{E}{#1}{#2}} + 
    \newglossaryentry{cm}{name={\si{\centi\metre}}, + 
     access={centimetre}, + 
     description={centimetre}, + 
     category=unit + 
    } + 
    \newglossaryentry{int}{name={\ensuremath{\int}},access={222B}, + 
      description={integral},category={symbol} + 
    }
    -

    These are non-optimal, but the beamer class is too complex for me to provide -a programmatic solution. Other potentially problematic environments are some -tabular-like environments (but not tabular itself) that process the contents in order -to work out the column widths and then reprocess the contents to do the actual -typesetting. -

    The amsmath environments, such as align, also process their contents multiple times, but -the glossaries package now checks for this. For tabularx, you need to explicitly patch it by -placing \glspatchtabularx in the preamble (or anywhere before the problematic use of +

    The above uses the \glsxtrcategoryaccsupp form that doesn’t include the field name. Remember that if you +want to supply a command specifically for the name field then it won’t be picked up by the text, plural, +firstplural and first fields. You’d need to supply them all. For example: + + +

    +
    +\newcommand{\glsnameaccsupp}[2]{% + 
     \glsaccessibility[method=hex,unicode]{ActualText}{#1}{#2}% + 
    } + 
    \newcommand{\glstextaccsupp}{\glsnameaccsupp} + 
    \newcommand{\glspluralaccsupp}{\glsnameaccsupp} + 
    \newcommand{\glsfirstaccsupp}{\glsnameaccsupp} + 
    \newcommand{\glsfirstplaccsupp}{\glsnameaccsupp} +
    +

    +

    See the documented code (glossaries-code.pdf) for further details. I recommend that you also read the tabularx). -

    -

    Top

    14.1 Counting the Number of Times an Entry has been Used (First Use Flag -Unset)

    -

    As from version 4.14, it’s now possible to keep track of how many times an entry is used. -That is, how many times the first use flag is unset. Note that the supplemental -accsupp documentation. See also the accessibility and tagpdf packages. + + +

    +

    +

    Top

    19. Sample Documents

    +

    The glossaries package is provided with some sample documents that illustrate the various functions. These +should be located in the samples subdirectory (folder) of the glossaries documentation directory. This +location varies according to your operating system and TEX distribution. You can use texdoc +to locate the main glossaries documentation. For example, in a terminal or command prompt, +type: +

    
    +   
    texdoc -l glossaries +
    +
    +This should display a list of all the files in the glossaries documentation directory with their full pathnames. +(The GUI version of texdoc may also provide you with the information.) +

    If you can’t find the sample files on your computer, they are also available from your nearest CTAN mirror +at http://mirror.ctan.org/macros/latex/contrib/glossaries/samples/. Each sample file listed below has +a hyperlink to the file’s location on the CTAN mirror. +

    The glossaries-extra package improves this function and also provides per-unit counting, which isn’t -available with the glossaries package. -

    This function is disabled by default as it adds extra overhead to the document build time -and also switches \newglossaryentry (and therefore \newacronym) into a preamble-only -command.
    -

    -

    To enable this function, use -


    \glsenableentrycount  \glsenableentrycount

    -

    -before defining your entries. This adds two extra (internal) fields to entries: currcount and +class="cmss-10">glossaries-extra package and bib2gls provide some additional sample files. There are also examples in +the Dickimaw Books Gallery. +

    If you prefer to use UTF-8 aware engines (xelatex or lualatex) remember that you’ll need to switch from prevcount. -

    The currcount field keeps track of how many times \glsunset is used within the -document. A local unset (using \glslocalunset) performs a local rather than global -increment to currcount. Remember that not all commands use \glsunset. Only the +class="cmss-10">fontenc & inputenc to fontspec where appropriate. +

    If you get any errors or unexpected results, check that you have up-to-date versions of all the required +packages. (Search the log file for lines starting with “Package: ”.) Where hyperref is loaded you will get +warnings about non-existent references that look something like: + + +

    +
    +pdfTeX warning (dest): name{glo:aca} has been + 
    referenced but does not exist, replaced by a fixed one +
    +

    These warnings may be ignored on the first LATEX run. (The destinations won’t be defined until the glossary +has been created.) +

    +

    Top

    19.1 Basic

    \gls-like commands do this. The reset commands \glsreset and \glslocalreset reset this -field back to zero (where \glslocalreset performs a local change). -

    The prevcount field stores the final value of the currcount field from the previous run. -This value is read from the .aux file at the beginning of the document environment. - - -

    You can access these fields using -


    \glsentrycurrcount  \glsentrycurrcount{label}

    -

    -for the currcount field, and -


    \glsentryprevcount  \glsentryprevcount{label}

    -

    -for the prevcount field. These commands are only defined if you have used -\glsenableentrycount. -

    For example: - - + id="x1-174001r1"> +

    -
    -\documentclass{article} - 
    \usepackage{glossaries} - 
    \makeglossaries - 
    \glsenableentrycount - 
    \newglossaryentry{apple}{name=apple,description={a fruit}} - 
    \begin{document} - 
    Total usage on previous run: \glsentryprevcount{apple}. - 
    \gls{apple}. \gls{apple}. \glsadd{apple}\glsentrytext{apple}. - 
    \glslink{apple}{apple}. \glsdisp{apple}{apple}. \Gls{apple}. - 
    Number of times apple has been used: \glsentrycurrcount{apple}. - 
    \end{document} -
    -

    On the first LATEX run, \glsentryprevcount{apple} produces 0. At the end of the -document, \glsentrycurrcount{apple} produces 4. This is because the only commands -that have incremented the entry count are those that use \glsunset. That is: \gls, \glsdisp -and \Gls. The other commands used in the above example, \glsadd, \glsentrytext and -\glslink, don’t use \glsunset so they don’t increment the entry count. On the next -LATEX run, \glsentryprevcount{apple} now produces 4 as that was the value of the -currcount field for the apple entry at the end of the document on the previous -run. -

    When you enable the entry count using \glsenableentrycount, you also enable the -following commands: -


    \cgls  \cgls[options]{label}[insert]

    -

    -(no case-change, singular) -


    \cglspl  \cglspl[options]{label}[insert]

    -

    -(no case-change, plural) -


    \cGls  \cGls[options]{label}[insert]

    -

    -(first letter uppercase, singular), and -


    \cGlspl  \cGlspl[options]{label}[insert]

    -

    -(first letter uppercase, plural). These all have plus and starred variants like the analogous +

    🔗minimalgls.tex

    +

    This document is a minimal working example. You can test your installation using this file. To create the +complete document you will need to do the following steps: +

      +
    1. Run minimalgls.tex through LATEX either by typing +

      
      +     
      pdflatex minimalgls +
      +
      + in a terminal or by using the relevant button or menu item in your text editor or front-end. This will + create the required associated files but you will not see the glossary in the document. +

    2. +
    3. If you have Perl installed, run makeglossaries on the document (§1.4 Generating the Associated Glossary + Files). This can be done on a terminal by typing: +

      
      +     
      makeglossaries minimalgls +
      +
      + otherwise do: +

      
      +     
      makeglossaries-lite minimalgls +
      +
      + If for some reason you want to call makeindex explicitly, you can do this in a terminal by typing (all on + one line): + + +

      
      +     
      makeindex -s minimalgls.ist -t minimalgls.glg -o minimalgls.gls minimalgls.glo +
      +
      + See §1.4.4 Using makeindex explicitly (Option 2) for further details on using makeindex explicitly. +

      Note that if the file name contains spaces, you will need to use the double-quote character to delimit the + name. +

    4. +
    5. Run minimalgls.tex through LATEX again (as step 1)
    +

    You should now have a complete document. The number following each entry in the glossary is the location +number. By default, this is the page number where the entry was referenced. +

    The acronym package option creates a second glossary with the label acronym (which can be referenced with \gls, \glspl, \Gls and \Glspl commands. -

    If you don’t use \glsenableentrycount, these commands behave like \gls, \glspl, \Gls -and \Glspl, respectively, only there will be a warning that you haven’t enabled entry -counting. If you have enabled entry counting with \glsenableentrycount then these - - -commands test if \glsentryprevcount{label} equals 1. If it doesn’t then the analogous \gls -etc will be used. If it does, then the first optional argument will be ignored and -

    +class="cmtt-10">\acronymtype). If you decide to enable this option then there will be a second set of glossary files that need to +be processed by makeindex. If you use makeglossaries or makeglossaries-lite you don’t need to worry +about it, as those scripts automatically detect which files need to be processed and will run makeindex (or +xindy) the appropriate number of times. +

    If for some reason you don’t want to use makeglossaries or makeglossaries-lite and you want the +acronym package option then the complete build process is: +

    
    +   
    pdflatex minimalgls +
    makeindex -s minimalgls.ist -t minimalgls.glg -o minimalgls.gls minimalgls.glo +
    makeindex -s minimalgls.ist -t minimalgls.alg -o minimalgls.acr minimalgls.acn +
    pdflatex minimalgls +
    +
    +

    There are three other files that can be used as minimal working examples: mwe-gls.tex, mwe-acr.tex and +mwe-acr-desc.tex. +


    glossaries-extraIf you want to try out the glossaries-extra extension package, you need to replace the package +loading line:

    -⟨cs format{label}{insert}\glsunset{label\usepackage[acronym]{glossaries}
    -
    will be performed, where ⟨cs format⟩ is a command that takes two arguments. The command -used depends whether you have used \cgls, \cglspl, \cGls or \cGlspl. -


    \cglsformat  \cglsformat{label}{insert}

    -

    -This command is used by \cgls and defaults to

    +
    with:
    \glsentrylong{label}insert⟩ +class="cmtt-10">\usepackage[acronym,postdot,stylemods]{glossaries-extra} + +
    -
    if the entry given by ⟨label⟩ has a long form or
    -
    +
    Note the different default package options. (You may omit the acronym package option in both cases if +you only want a single glossary.) The glossaries-extra package internally loads the base glossaries +package so you don’t need to explicitly load both (in fact, it’s better to let glossaries-extra load \glsentryfirst{label}insert⟩ -
    -
    otherwise. -


    \cglsplformat  \cglsplformat{label}{insert}

    -

    -This command is used by \cglspl and defaults to

    +class="cmss-10">glossaries). +

    Next, replace:

    \glsentrylongpl{label}insert⟩ +class="cmtt-10">\setacronymstyle{long-short}
    -
    if the entry given by ⟨label⟩ has a long form or
    +
    with:
    -\glsentryfirstplural{label}insert⟩ -
    -
    otherwise. -


    \cGlsformat  \cGlsformat{label}{insert}

    -

    -This command is used by \cGls and defaults to

    - - +\setabbreviationstyle[acronym]{long-short} +
    +
    The optional argument acronym identifies the category that this style should be applied to. The \newacronym +command provided by the base glossaries package is redefined by glossaries-extra to use \newabbreviation with +the category set to acronym. +

    If you prefer to replace \newacronym with \newabbreviation then the default category is abbreviation so the +style should instead be:

    -\Glsentrylong{label}insert⟩ -
    -
    if the entry given by ⟨label⟩ has a long form or
    +\setabbreviationstyle[abbreviation]{long-short} +
    +
    This is actually the default category if the optional argument is omitted, so you can simply do: +
    -\Glsentryfirst{label}insert⟩ -
    -
    otherwise. -


    \cGlsplformat  \cGlsplformat{label}{insert}

    -

    -This command is used by \cGlspl and defaults to

    +\setabbreviationstyle{long-short} +
    +
    The long-short style is the default for the abbreviation category so you can omit this line completely if you +replace \newacronym. (The default style for the acronym category is short-nolong, which only shows the short +form on first use.) +

    As mentioned earlier, the acronym package option creates a new glossary with the label acronym. This is +independent of the acronym category. You can use the acronym package option with either \newacronym or +\newabbreviation. +

    You may instead prefer to use the abbreviations package option, which creates a new glossary with the label +abbreviations:

    \Glsentrylongpl{label}insert⟩ -
    -
    if the entry given by ⟨label⟩ has a long form or
    +class="cmtt-10">\usepackage[abbreviations,postdot,stylemods]{glossaries-extra} + + +
    +
    This can again be used with either \newacronym or \newabbreviation, but the file extensions are different. +This isn’t a problem if you are using makeglossaries or makeglossaries-lite. If you are explicitly calling +makeindex (or xindy) then you need to modify the file extensions. See the glossaries-extra user manual for +further details. +

    If you use both the acronym and abbreviations package options then \newacronym will default to the acronym +glossary and \newabbreviation will default to the abbreviations glossary. +

    bib2glsIf you want to try bib2gls, you first need to convert the document to use glossaries-extra as +described above. Then add the record package option. For example:

    \Glsentryfirstplural{label}insert⟩ +class="cmtt-10">\usepackage[record,postdot,stylemods]{glossaries-extra}
    -
    otherwise. -

    This means that if the previous count for the given entry was 1, the entry won’t be -hyperlinked with the \cgls-like commands and they won’t add a line to the external glossary -file. If you haven’t used any of the other commands that add information to glossary file (such -as \glsadd or the \glstext-like commands) then the entry won’t appear in the -glossary. -

    Remember that since these commands use \glsentryprevcount you need to run -LATEX twice to ensure they work correctly. The document build order is now (at least): +

    Next you need to convert the entry definitions into the bib format required by bib2gls. This can easily be +done with convertgls2bib. For example: +

    
    +   
    convertgls2bib --preamble-only minimalgls.tex entries.bib +
    +
    +This will create a file called entries.bib. Next, replace:

    +
    (pdf)latex, (pdf)latex, makeglossaries, (pdf)latex. - -

    Example 26 (Don’t index entries that are only used once) -

    In this example, the abbreviations that have only been used once (on the previous run) -only have their long form shown with \cgls. - - -

    -
    -\documentclass{article} - 
    \usepackage[colorlinks]{hyperref} - 
    \usepackage[acronym]{glossaries} - 
    \makeglossaries - 
    \glsenableentrycount - 
    \setacronymstyle{long-short} - 
    \newacronym{html}{HTML}{hypertext markup language} - 
    \newacronym{css}{CSS}{cascading style sheets} - 
    \newacronym{xml}{XML}{extensible markup language} - 
    \newacronym{sql}{SQL}{structured query language} - 
    \newacronym{rdbms}{RDBMS}{relational database management system} - 
    \newacronym{rdsms}{RDSMS}{relational data stream management system} - 
    \begin{document} - 
    These entries are only used once: \cgls{sql}, \cgls{rdbms}, - 
    \cgls{xml}. These entries are used multiple times: - 
    \cgls{html}, \cgls{html}, \cgls{css}, \cgls{css}, \cgls{css}, - 
    \cgls{rdsms}, \cgls{rdsms}. - 
    \printglossaries - 
    \end{document} +class="cmtt-10">\makeglossaries
    -

    After a complete document build (latex, latex, makeglossaries, latex) the list of -abbrevaitions only includes the entries HTML, CSS and RDSMS. The entries SQL, -RDBMS and XML only have their long forms displayed and don’t have a hyperlink. -

    -
    -

    -

    ____________________________

    -

    Remember that if you don’t like typing \cgls you can create a synonym. For -example - - -

    -
    -\let\ac\cgls +
    with:
    +
    +\GlsXtrLoadResources[src=entries]
    -

    - - -

    -

    -

    Top

    15. Glossary Styles

    -

    Glossaries vary from lists that simply contain a symbol with a terse description to lists of -terms or phrases with lengthy descriptions. Some glossaries may have terms with associated -symbols. Some may have hierarchical entries. There is therefore no single style that fits every -type of glossary. The glossaries package comes with a number of pre-defined glossary styles, -described in §15.1 Predefined Styles. You can choose one of these that best suits your type of -glossary or, if none of them suit your document, you can defined your own style (see §15.2 -Defining your own glossary style). There are some examples of glossary styles available at -http://www.dickimaw-books.com/gallery/#glossaries. -

    The glossary style can be set using the style key in the optional argument to +

    Now remove all the entry definitions in the preamble (\longnewglossaryentry, \newglossaryentry and \printnoidxglossary (Option 1) or \printglossary (Options 2 and 3) or using the -command: -


    \setglossarystyle  \setglossarystyle{style-name}

    -

    -(before the glossary is displayed). -

    Some of the predefined glossary styles may also be set using the style package option, it -depends if the package in which they are defined is automatically loaded by the glossaries -package. -

    You can use the lorum ipsum dummy entries provided in the accompanying +class="cmtt-10">\newacronym or \newabbreviation). +

    The abbreviation style command must go before \GlsXtrLoadResources. For example (if you are using example-glossaries-*.tex files (described in §1.3 Dummy Entries for Testing) to test the -different styles. +class="cmtt-10">\newacronym):

    +
    +\setabbreviationstyle[acronym]{long-short} +
    \GlsXtrLoadResources[src=entries] +
    +
    Finally, replace: + + +
    +\printglossaries +
    +

    with:

    +
    +\printunsrtglossaries +
    +
    The document build is now: +

    
    +   
    pdflatex minimalgls +
    bib2gls minimalgls +
    pdflatex minimalgls +
    +
    + +

    -

    Top

    15.1 Predefined Styles

    -

    The predefined styles can accommodate numbered level 0 (main) and level 1 entries. See the -package options entrycounter, counterwithin and subentrycounter described in §2.3 Glossary -Appearance Options. There is a summary of available styles in table 15.1. You can view samples of -all the predefined styles at http://www.dickimaw-books.com/gallery/glossaries-styles/. -Note that glossaries-extra provides additional styles in the supplementary packages -glossary-bookindex and glossary-longnoloc. See the 🔗sampleDB.tex +

    This document illustrates how to load external files containing the glossary definitions. It also illustrates how to +define a new glossary type. This document has the number list suppressed and uses \glsaddall to add all the +entries to the glossaries without referencing each one explicitly. (Note that it’s more efficient to +use glossaries-extra manual for further -details. -

    Note that the group styles (such as listgroup) will have unexpected results if used with -the sort=def or sort=use options. If you don’t sort your entries alphabetically, it’s -best to set the nogroupskip package option to prevent odd vertical gaps appearing. -
    -

    -

    The group title is obtained using \glsgetgrouptitle{label}, which is described in §15.2 -Defining your own glossary style. -

    -
    - - -


    - - -
    Table 15.1: Glossary Styles. An asterisk in the style name indicates anything that -matches that doesn’t match any previously listed style (e.g. long3col* matches +class="cmss-10">glossaries-extra and bib2gls if you have a large number of entries.) To create the document +do: +

    
    +   
    pdflatex sampleDB +
    makeglossaries sampleDB +
    pdflatex sampleDB +
    +
    +or +

    
    +   
    pdflatex sampleDB +
    makeglossaries-lite sampleDB +
    pdflatex sampleDB +
    +
    +The glossary definitions are stored in the accompanying files database1.tex and database2.tex. +If for some reason you want to call makeindex explicitly you must have a separate call for each +glossary: + + +

      +
    1. Create the main glossary (all on one line): +

      
      +     
      makeindex -s sampleDB.ist -t sampleDB.glg -o sampleDB.gls sampleDB.glo +
      +
      +

    2. +
    3. Create the secondary glossary (all on one line): +

      
      +     
      makeindex -s sampleDB.ist -t sampleDB.nlg -o sampleDB.not sampleDB.ntn +
      +
      + Note that both makeglossaries and makeglossaries-lite do this all in one call, so they not only make + it easier because you don’t need to supply all the switches and remember all the extensions but they also + call makeindex the appropriate number of times.

    +

    bib2glsIf you want to switch to using bib2gls with glossaries-extra, you can convert database1.tex and +database2.tex to bib files using convertgls2bib: +

    
    +   
    convertgls2bib database1.tex database1.bib +
    convertgls2bib database2.tex database2.bib +
    +
    +The document code then needs to be:

    +
    long3col, long3colheader, long3colborder and long3colheaderborder). A maximum level of -0 indicates a flat glossary (sub-entries are displayed in the same way as main entries). -Where the maximum level is given as — there is no limit, but note that \documentclass{article} +
    +
    \usepackage[colorlinks,plainpages=false]{hyperref} +
    \usepackage[record,postdot]{glossaries-extra} +
    +
    \newglossary*
    {punc}{Punctuation Characters} +
    +
    \GlsXtrLoadResources[src={database1}, +
     selection=all,sort=en] +
    \GlsXtrLoadResources[src={database2},type=punc, +
     selection=all,sort=letter-case] +
    +
    \begin{document} +
    \printunsrtglossaries +
    \end{document} + + +
    +
    Note that the nonumberlist package option has been omitted. It’s not needed because there are no +locations in this amended document (whereas in the original sampleDB.tex locations are created with +\glsaddall). The starred \newglossary* is used since the makeindex -(Option 2) imposes a limit of 2 sub-levels. If the homograph column is checked, then -the name is not displayed for sub-entries. If the symbol column is checked, then the -symbol will be displayed.
    -
    - - - - - - - - - - - - - -
    Style Maximum Level Homograph Symbol
    listdotted 0
    sublistdotted 1
    list* 1
    altlist* 1 -
    long*3col* 1 + id="dx1-176025">/xindy extensions are now +irrelevant. +

    Instead of using makeglossaries you need to use bib2gls when you build the document: +

    
    +   
    pdflatex sampleDB +
    bib2gls sampleDB +
    pdflatex sampleDB +
    +
    +Note that one bib2gls call processes all the indexing (rather than one call per glossary). Unlike makeindex and +xindy, bib2gls processes each resource set in turn, but the resource sets aren’t linked to a specific glossary. +Multiple glossaries may be processed in a single resource set or sub-blocks of a single glossary may be processed +by multiple resource sets. In this example, there happens to be one resource set per glossary because each +glossary requires a different sort method. (A locale-sensitive alphabetical sort for the first and a character code +sort for the second.) +

    If you want letter groups, you need to use the --group switch: +

    
    +   
    bib2gls --group sampleDB +
    +
    +and use an appropriate glossary style. +

    See also bib2gls gallery: sorting, glossaries-extra and bib2gls: An Introductory Guide and the bib2gls user +manual. +

    +

    +

    Top

    19.2 Acronyms and First Use

    + +

    +

    +

    🔗sampleAcr.tex

    +

    This document has some sample abbreviations. It also adds the glossary to the table of contents, so an extra run +through LATEX is required to ensure the document is up to date: +

    
    +   
    pdflatex sampleAcr +
    makeglossaries sampleAcr +
    pdflatex sampleAcr +
    pdflatex sampleAcr +
    + + +
    +(or use makeglossaries-lite). +

    Note that if the glossary is at the start of the document and spans across multiple pages, then this can cause +the locations to be shifted. In that case, an extra makeglossaries and LATEX call are required. In +this particular example, the glossary is at the end of the document so it’s not a problem. It’s also +not a problem for a glossary at the start of the document if the page numbering is reset at the +end of the glossary. For example, if the glossary is at the end of the front matter in a book-style +document. +

    This document uses \ifglsused to determine whether to use “a” or “an” in:

    +
    long4col* 1
    altlong*4col* 1
    long* 1
    super*3col* 1
    super4col* 1
    altsuper*4col* 1
    super* 1
    *index* 2
    treenoname*
    *alttree*
    *tree*
    inline 1
    - - -

    -
    -

    The tabular-like styles that allow multi-line descriptions and page lists use the length -\glsdescwidth \glsdescwidth to set the width of the description column and the -length \glspagelistwidth \glspagelistwidth to set the width of the page list -column.15.1 -These will need to be changed using \setlength if the glossary is too wide. Note that the +class="cmtt-10">… is \ifglsused{svm}{an}{a} \gls{svm}  +

    +
    This clumsy bit of code can be tidied up with the glossaries-prefix package. Since that package automatically +loads glossaries and passes all its options to the base package it’s possible to do a simple replacement +of: + + +
    +\usepackage[style=long,toc]{glossaries} +
    +

    with:

    +
    long4col and super4col styles (and their header and border variations) don’t use these lengths -as they are designed for single line entries. Instead you should use the analogous +class="cmtt-10">\usepackage[style=long,toc]{glossaries-prefix} +
    +
    The definition of svm now needs an adjustment:
    +
    altlong4col and altsuper4col styles. If you want to explicitly create a line-break within a -multi-line description in a tabular-like style it’s better to use \newline instead of -\\. -

    Remember that a cell within a tabular-like environment can’t be broken across a page, so -even if a tabular-like style, such as long, allows multilined descriptions, you’ll probably -encounter page-breaking problems if you have entries with long descriptions. You may want to -consider using the alttree style instead.
    -

    -

    Note that if you use the style key in the optional argument to \printnoidxglossary -(Option 1) or \printglossary (Options 2 and 3), it will override any previous style settings -for the given glossary, so if, for example, you do - - -

    -
    -\renewcommand*{\glsgroupskip}{} - 
    \printglossary[style=long] +class="cmtt-10">\newacronym[description={statistical pattern recognition +
    technique~\protect\cite{svm}}, +
    prefixfirst={a~},prefix={an\space} +
    ]{svm}{svm}{support vector machine}
    -

    then the new definition of \glsgroupskip will not have an affect for this glossary, as +

    The clumsy text can now simply be changed to:
    +
    \glsgroupskip is redefined by style=long. Likewise, \setglossarystyle will also override -any previous style definitions, so, again - - -

    -
    -\renewcommand*{\glsgroupskip}{} - 
    \setglossarystyle{long} +class="cmtt-10">… is \pgls{svm} 
    -

    will reset \glsgroupskip back to its default definition for the named glossary style -(long in this case). If you want to modify the styles, either use \newglossarystyle -(described in the next section) or make the modifications after \setglossarystyle, -e.g.: - - -

    -
    -\setglossarystyle{long} - 
    \renewcommand*{\glsgroupskip}{}
    -

    As from version 3.03, you can now use the package option nogroupskip to suppress the gap -between groups for the default styles instead of redefining \glsgroupskip. -

    All the styles except for the three- and four-column styles and the listdotted style use the -command -


    \glspostdescription  \glspostdescription

    -

    -after the description. This simply displays a full stop by default. To eliminate this full -stop (or replace it with something else, say, a comma) you will need to redefine +


    glossaries-extraIf you want to convert this sample document to use glossaries-extra, you may want the +patched version of the styles provided in glossary-long, in which case you can also add stylemods: +

    +
    \glspostdescription before the glossary is displayed. Alternatively, you can suppress it -for a given entry by placing \nopostdesc in the entry’s description. Note that +class="cmtt-10">\usepackage[stylemods,style=long]{glossaries-extra} +
    +
    If you want to suppress all the other glossary style packages with nostyles, then you need to specify exactly +which package (or packages) that you do want:
    +
    \longnewglossaryentry puts \nopostdesc at the end of the description. The glossaries-extra -package provides a starred version that doesn’t. -

    As from version 3.03 you can now use the package option nopostdot to suppress this full -stop. This is the better option if you want to use the glossaries-extra package. The +class="cmtt-10">\usepackage[nostyles,stylemods=long,style=long]{glossaries-extra} +

    +
    (Now that glossaries-extra is being used, there are more available “long” styles in the glossary-longextra package, +which you may prefer.) + + +

    If you want to use glossaries-prefix, you can either load it after glossaries-extra or (with at least glossaries-extra +v1.42) you can simply use the prefix package option. +

    Note that the toc package option has been dropped. This is the default with glossaries-extra, so it doesn’t +need to be specified now. The document build is now shorter: +

    
    +   
    pdflatex sampleAcr +
    makeglossaries sampleAcr +
    pdflatex sampleAcr +
    +
    +The third LATEX call is no longer required to make the table of contents up-to-date. This is because +glossaries-extra provides boilerplate text on the first LATEX call when the glossary files are missing. This means +that the glossary header is added to the toc file on the first LATEX call, whereas with just the base glossaries +package, the header isn’t present until the second LATEX call. (As with just the base glossaries package, if the +glossary occurs at the start of the document without a page reset after it then part of the build process needs +repeating to ensure all referenced page numbers are up-to-date. This problem isn’t specific to the glossaries +package.) +

    The other different default setting is the post-description punctuation. The base package has nopostdot=false +as the default. This means that a full stop (period) is automatically inserted after the description in the +glossary. The extension package has nopostdot=true as the default. If you want the original behaviour then you +can use nopostdot=false or the shorter synonym postdot. +

    The glossaries-extra package has different abbreviation handling that’s far more flexible than that provided +by the base glossaries package. The style now needs to be set with \setabbreviationstyle instead of glossaries-extra-stylemods package provides some adjustments some of to the predefined styles -listed here, allowing for greater flexibility. See the glossaries-extra documentation for further -details. +class="cmtt-10">\setacronymstyle:

    +
    +\setabbreviationstyle[acronym]{long-short-sc} +
    \newacronym{svm}{svm}{support vector machine} +
    +
    (Note the different style name long-short-sc instead of long-sc-short and the optional argument acronym.) If +you prefer to replace \newacronym with \newabbreviation then omit the optional argument: +
    +
    +\setabbreviationstyle{long-short-sc} +
    \newabbreviation{svm}{svm}{support vector machine} +
    +
    (The optional argument of \setabbreviationstyle is the category to which the style should be +applied. If it’s omitted, abbreviation is assumed. You can therefore have different styles for different +categories.) +

    Finally, you need to replace \acrshort, \acrlong and \acrfull and their variants with \glsxtrshort, +\glsxtrlong and \glsxtrfull etc. + + + +

    -

    Top

    15.1.1 List Styles

    -

    The styles described in this section are all defined in the package 🔗sampleAcrDesc.tex +

    This is similar to the previous example, except that the abbreviations have an associated description. As with +the previous example, the glossary is added to the table of contents, so an extra run through LATEX is +required: +

    
    +   
    pdflatex sampleAcrDesc +
    makeglossaries sampleAcrDesc +
    pdflatex sampleAcrDesc +
    pdflatex sampleAcrDesc +
    +
    +This document uses the acronym package option, which creates a new glossary used by \newacronym. This +leaves the default main glossary available for general terms. However, in this case there are no general terms so +the main glossary is redundant. The nomain package option will prevent its creation. Obviously, if you decide to +add some terms with \newglossaryentry you will need to remove the nomain option as the main glossary will +now be required. +


    glossaries-extraAs with the previous example, if you want to convert this document to use glossaries-extra you +need to make a few modifications. The most obvious one is to replace glossaries with glossaries-extra in +the \usepackage argument. Again you can omit toc as this is the default for glossaries-extra. As in the previous +example, you may want to use the patched styles. This document uses altlist which is provided by glossary-list. Since -they all use the description environment, they are governed by the same parameters -as that environment. These styles all ignore the entry’s symbol. Note that these -styles will automatically be available unless you use the nolist or nostyles package -options. -

    Note that, except for the listdotted style, these list styles are incompatible with + id="dx1-179006">, so +the style can be patched with stylemods.

    +
    classicthesis. They may also be incompatible with other classes or packages that modify the +class="cmtt-10">\usepackage[acronym,nomain,style=altlist,stylemods]{glossaries-extra} +
    +
    You may prefer to replace the acronym option with abbreviations, but this will change the file +extensions. If you use makeglossaries or makeglossaries-lite you don’t need to worry about +it. +

    Again the style command needs to be changed:

    +
    +\setabbreviationstyle[acronym]{long-short-sc-desc} +
    +
    (Note the change in style name long-short-sc-desc instead of long-sc-short-desc and the optional argument +acronym.) +

    As with the previous example, if you prefer to use \newabbreviation instead of \newacronym then you need +to omit the optional argument:

    +
    +\setabbreviationstyle{long-short-sc-desc} + + +
    +
    The original document uses:
    +
    description environment.
    -

    -

    +class="cmtt-10">\renewcommand*{\glsseeitemformat}[1]{% +
     \acronymfont{\glsentrytext{#1}}} +
    +
    to ensure that the cross-references (from the see key) use the acronym font. The new abbreviation styles don’t +use \acronymfont so this isn’t appropriate with glossaries-extra. If you’re using at least version 1.42 of +glossaries-extra, you don’t need to do anything as it automatically redefines \glsseeitemformat to take the +style formatting into account. If you have an earlier version you can redefine this command as follows: +
    +
    list
    The list style uses the description environment. The entry name is placed in the - optional argument of the \item command (so it will usually appear in bold by - default). The description follows, and then the associated number list for that - entry. The symbol is ignored. If the entry has child entries, the description and - number list follows (but not the name) for each child entry. Groups are separated - using \indexspace. - - -

    The closest matching non-list style is the index style. -

    +class="cmtt-10">\renewcommand*{\glsseeitemformat}[1]{% +
     \ifglshasshort{#1}{\glsfmttext{#1}}{\glsfmtname{#1}}% +
    } +
    +
    This will just show the short form in the cross-reference. If you prefer the name instead (which includes the +short and long form) you can use:
    +
    listgroup
    The listgroup style is like list but the glossary groups have headings obtained - using \glsgetgrouptitle{label}, which is described in §15.2 Defining your own - glossary style. -
    +class="cmtt-10">\renewcommand*{\glsseeitemformat}[1]{\glsfmtname{#1}} +
    +
    +

    The glossaries-extra package provides two additional cross-referencing keys seealso and alias, so see={[see +also]{svm}} can be replaced with a more appropriate key:

    +
    listhypergroup
    The listhypergroup style is like listgroup but has a navigation line - at the start of the glossary with links to each group that is present in the - glossary. This requires an additional run through LATEX to ensure the group - information is up to date. In the navigation line, each group is separated - by -


    \glshypernavsep  \glshypernavsep

    -

    - which defaults to a vertical bar with a space on either side. For example, to simply have - a space separating each group, do: - - -

    -
    - \renewcommand*{\glshypernavsep}{\space} +class="cmtt-10">\newacronym[description={Statistical pattern recognition +
    technique using the ``kernel trick''}, +
    seealso={svm}, +
    ]{ksvm}{ksvm}{kernel support vector machine}
    -

    -

    Note that the hyper-navigation line is now (as from version 1.14) set inside the optional - argument to \item instead of after it to prevent a spurious space at the start. This can - cause a problem if the navigation line is too long. As from v4.22, if you need to adjust - this, you can redefine -


    \glslistnavigationitem  \glslistnavigationitem{navigation line}

    -

    - The default definition is \item[navigation line] but may be redefined independently of - setting the style. For example: - - -

    -
    - \renewcommand*{\glslistnavigationitem}[1]{\item \textbf{#1}}
    -

    -

    You may prefer to use the tree-like styles, such as treehypergroup instead. -

    +

    Finally, as with the previous example, you need to replace \acrshort, \acrlong and \acrfull etc with +\glsxtrshort, \glsxtrlong and \glsxtrfull etc. +

    bib2glsIf you want to convert this document so that it uses bib2gls, you first need to convert it to use +glossaries-extra, as above, but remember that you now need the record option:

    + + +
    altlist
    The altlist style is like list but the description starts on the line following the name. - (As with the list style, the symbol is ignored.) Each child entry starts a new - line, but as with the list style, the name associated with each child entry is - ignored. -

    The closest matching non-list style is the index style with the following adjustment: - - -

    -
    - \renewcommand{\glstreepredesc}{% -  
     \glstreeitem\parindent\hangindent} +class="cmtt-10">\usepackage[acronym,nomain,style=altlist,record,postdot,stylemods] +
    {glossaries-extra}
    -

    -

    +
    Now you need to convert the abbreviation definitions to the bib format required by bib2gls. This can be done +with: +

    
    +   
    convertgls2bib --preamble-only sampleAcrDesc.tex entries.bib +
    +
    +If you retained \newacronym from the original example file, then the new entries.bib file will contain entries +defined with @acronym. For example:

    +
    +@acronym{ksvm, +
      description = {Statistical pattern recognition technique +
      using the ``kernel trick''}, +
      seealso = {svm}, +
      short = {ksvm}, +
      long = {kernel support vector machine} +
    } +
    +
    If you switched to \newabbreviation then the entries will instead be defined with @abbreviation. +

    Next replace \makeglossaries with the resource command, but note that the abbreviation style must be set +first:

    +
    +\setabbreviationstyle[acronym]{long-short-sc-desc} +
    \GlsXtrLoadResources[src=entries,% terms defined in entries.bib +
     abbreviation-sort-fallback=long] +
    +
    Another possibility is to make @acronym behave as though it was actually @abbreviation:
    +
    +\setabbreviationstyle{long-short-sc-desc} +
    \GlsXtrLoadResources[src=entries,abbreviation-sort-fallback=long, +
     entry-type-aliases={acronym=abbreviation}
    ] +
    +
    Note that the category is now abbreviation not acronym so the optional argument of \setabbreviationstyle +needs adjusting. +

    If the sort field is missing (which should usually be the case), then both @acronym and @abbreviation will +fallback on the short field (not the name field, which is usually set by the style and therefore not visible to +bib2gls). For some styles, as in this example, it’s more appropriate to sort by the long form so the fallback is + + +changed. (Remember that you will break this fallback mechanism if you explicitly set the sort value.) See the +bib2gls manual for further details and other examples. +

    Remember to delete any \newacronym or \newabbreviation in the tex file. Finally replace \printglossary +with \printunsrtglossary. The document build is now: +

    
    +   
    pdflatex sampleAcrDesc +
    bib2gls sampleAcrDesc +
    pdflatex sampleAcrDesc +
    +
    +

    Note that it’s now much easier to revert back to the descriptionless style used in sampleAcr.tex: +

    +
    +\setabbreviationstyle[acronym]{long-short-sc} +
    \GlsXtrLoadResources[src=entries,ignore-fields=description] +
    +
    With the other options it would be necessary to delete all the description fields from the abbreviation +definitions in order to omit them, but with bib2gls you can simply instruct bib2gls to ignore the description. +This makes it much easier to have a large database of abbreviations for use across multiple documents that may +or may not require the description. + +

    +

    +

    🔗sampleDesc.tex

    +

    This is similar to the previous example, except that it defines the abbreviations using \newglossaryentry +instead of \newacronym. As with the previous example, the glossary is added to the table of contents, so an +extra run through LATEX is required: +

    
    +   
    pdflatex sampleDesc +
    makeglossaries sampleDesc +
    pdflatex sampleDesc +
    pdflatex sampleDesc +
    +
    +This sample file demonstrates the use of the first and text keys but in general it’s better to use \newacronym +instead as it’s more flexible. For even greater flexibility use \newabbreviation provided by glossaries-extra. For +other variations, such as showing the symbol on first use, you may prefer to make use of the post-link category +hook. For examples, see the section “Changing the Formatting” in glossaries-extra and bib2gls: An Introductory +Guide. + + + +

    +

    +

    🔗sampleFnAcrDesc.tex

    +

    This document has some sample abbreviations that use the footnote-sc-desc acronym style. As with the +previous example, the glossary is added to the table of contents, so an extra run through LATEX is +required: +

    
    +   
    pdflatex sampleFnAcrDesc +
    makeglossaries sampleFnAcrDesc +
    pdflatex sampleFnAcrDesc +
    pdflatex sampleFnAcrDesc +
    +
    +
    glossaries-extraIf you want to convert this sample document to use glossaries-extra, then you just need to follow +the same steps as for sampleAcr.tex with a slight modification. This time the short-sc-footnote-desc +abbreviation style is needed:

    +
    +\setabbreviationstyle[acronym]{short-sc-footnote-desc} +
    +
    The command redefinitions (performed with \renewcommand) should now all be deleted as they are no longer +applicable. +

    You may prefer to use the short-sc-postfootnote-desc style instead. There are subtle differences between the +postfootnote and footnote set of styles. Try changing the abbreviation style to short-sc-footnote and compare the +location of the footnote marker with the two styles. +

    This modified sample file now has a shorter build: +

    
    +   
    pdflatex sampleFnAcrDesc +
    makeglossaries sampleFnAcrDesc +
    pdflatex sampleFnAcrDesc +
    +
    +This is because the glossaries-extra package produces boilerplate text when the glossary file is missing (on the +first LATEX run) which adds the glossary title to the table of contents (toc) file. + +

    +

    +

    🔗sampleCustomAcr.tex

    +

    This document has some sample abbreviations with a custom acronym style. It also adds the glossary to the +table of contents, so an extra run through LATEX is required: +

    
    +   
    pdflatex sampleCustomAcr +
    makeglossaries sampleCustomAcr + + +
    pdflatex sampleCustomAcr +
    pdflatex sampleCustomAcr +
    +
    +This is a slight variation on the previous example where the name is in the form ⟨long⟩ (⟨short⟩) instead of ⟨short⟩ +(⟨long⟩), and the sort key is set to the long form instead of the short form. On first use, the footnote text is in +the form ⟨long⟩: ⟨description⟩ (instead of just the long form). This requires defining a new acronym style that +inherits from the footnote-sc-desc style. +


    glossaries-extraThe conversion to glossaries-extra starts in much the same way as the previous examples: +

    +
    altlistgroup
    The altlistgroup style is like altlist but the glossary groups have headings. -
    +class="cmtt-10">\usepackage[acronym,nomain,postdot,stylemods,style=altlist] +
    {glossaries-extra} +
    +
    The abbreviation styles have associated helper commands that may be redefined to make minor modifications. +These redefinitions should be done before the abbreviations are defined. +

    The short-sc-footnote-desc abbreviation style is the closest match to the requirement, so replace the altlisthypergroup

    The altlisthypergroup style is like altlistgroup but has a set of links to the - glossary groups. The navigation line is the same as that for listhypergroup, described - above. -
    +class="cmtt-10">\setacronymstyle command with:

    +
    +\setabbreviationstyle[acronym]{short-sc-footnote-desc} +
    +
    Again, you may prefer short-sc-postfootnote-desc. Both styles use the same helper commands. +

    Next some adjustments need to be made to fit the new requirements. The name needs to be ⟨long⟩ (⟨short⟩): +

    +
    listdotted
    This style uses the description - environment.15.2 - Each entry starts with \item[], followed by the name followed by a dotted line, - followed by the description. Note that this style ignores both the number list and the - symbol. The length -


    \glslistdottedwidth  \glslistdottedwidth

    -

    - governs where the description should start. This is a flat style, so child entries are - formatted in the same way as the parent entries. -

    A non-list alternative is to use the index style with - - -

    -
    - \renewcommand{\glstreepredesc}{\dotfill} -  
    \renewcommand{\glstreechildpredesc}{\dotfill} +class="cmtt-10">\renewcommand*{\glsxtrfootnotedescname}{% +
      \protect\glslongfont{\the\glslongtok}% +
      \protect\glsxtrfullsep{\the\glslabeltok}% +
      \protect\glsxtrparen{\protect\glsabbrvfont{\the\glsshorttok}}% +
    }
    -

    Note that this doesn’t use \glslistdottedwidth and causes the description - to be flush-right and will display the symbol, if provided. (It also doesn’t - suppress the number list, but that can be achieved with the nonumberlist - option.) -

    +
    This command expands when the abbreviations are defined so take care to \protect commands that shouldn’t +be expanded at that point, and make sure that the token registers that store the label, long and short values are +able to expand. Similarly the sort value needs adjusting:
    +
    sublistdotted
    This is a variation on the listdotted style designed for hierarchical glossaries. - The main entries have just the name displayed. The sub entries are displayed in the - same manner as listdotted. Unlike the listdotted style, this style is incompatible with - classicthesis.
    -

    -

    -

    Top

    15.1.2 Longtable Styles

    -

    The styles described in this section are all defined in the package glossary-long. Since they all -use the longtable environment, they are governed by the same parameters as that -environment. Note that these styles will automatically be available unless you use the +class="cmtt-10">\renewcommand*{\glsxtrfootnotedescsort}{\the\glslongtok} + + +

    +
    The footnote for all the footnote abbreviation styles is produced with:
    +
    +\glsxtrabbrvfootnote{label}{text} +
    +
    where ⟨text⟩ is the singular or plural long form, depending on what command was used to reference the +abbreviation (\gls, \glspl etc). This can simply be redefined as:
    +
    nolong or nostyles package options. These styles fully justify the description and page -list columns. If you want ragged right formatting instead, use the analogous styles -described in §15.1.3 Longtable Styles (Ragged Right). If you want to incorporate rules -from the booktabs package, try the styles described in §15.1.4 Longtable Styles -(booktabs). -

    +class="cmtt-10">\renewcommand*{\glsxtrabbrvfootnote}[2]{\footnote{% +
      #2: \glsentrydesc{#1}}} +
    +
    This will mimic the result from the original sample document. +

    You may prefer to replace #2 with a reference to a specific field (or fields). For example:

    +
    long
    The long style uses the longtable environment (defined by the longtable package). - It has two columns: the first column contains the entry’s name and the second - column contains the description followed by the number list. The entry’s symbol is - ignored. Sub groups are separated with a blank row. The width of the first column - is governed by the widest entry in that column. The width of the second column - is governed by the length \glsdescwidth. Child entries have a similar format to - the parent entries except that their name is suppressed. -
    +class="cmtt-10">\renewcommand*{\glsxtrabbrvfootnote}[2]{\footnote{% +
     \Glsfmtlong{#1} (\glsfmtshort{#1}): \glsentrydesc{#1}.}} +
    +
    As with the earlier sampleAcrDesc.tex, you need to remove or change the redefinition of \glsseeitemformat +since \acronymfont is no longer appropriate. +

    In the original sampleCustomAcr.tex source code, I started the description with a capital: + + +

    +
    +\newacronym[description={Statistical pattern recognition + 
    technique using the ``kernel trick''}, + 
    see={[see also]{svm}}, + 
    ]{ksvm}{ksvm}{kernel support vector machine} +
    +

    This leads to a capital letter after the colon in the footnote, which is undesirable, but I would like to +have the description start with a capital in the glossary. The solution to this problem is easy with +glossaries-extra. I start the description with a lowercase letter and set the glossdesc attribute to firstuc: +

    +
    +\glssetcategoryattribute{acronym}{glossdesc}{firstuc} +
    +
    The abbreviation definitions are modified slightly:
    +
    longborder
    The longborder style is like long but has horizontal and vertical lines around - it. - - -
    +class="cmtt-10">\newacronym[description={statistical pattern recognition +
    technique using the ``kernel trick''}, +
    seealso={svm}, +
    ]{ksvm}{ksvm}{kernel support vector machine} +
    +
    Note the use of the seealso key, which is only available with glossaries-extra. +

    If you prefer to use \newabbreviation instead of \newacronym, then the category needs to be abbreviation +rather than acronym:

    +
    +\glssetcategoryattribute{abbreviation}{glossdesc}{firstuc} +
    +
    and the style command needs to be adjusted so that it omits the optional argument. For example: +
    +
    +\setabbreviationstyle{short-sc-postfootnote-desc} +
    +
    + + + +

    +

    +

    🔗sample-FnDesc.tex

    +

    This example defines a custom display format that puts the description in a footnote on first use. +

    
    +   
    pdflatex sample-FnDesc +
    makeglossaries sample-FnDesc +
    pdflatex sample-FnDesc +
    +
    +In order to prevent nested hyperlinks, this document uses the hyperfirst=false package option (otherwise the +footnote marker hyperlink would be inside the hyperlink around the link text which would result in a nested +hyperlink). +


    glossaries-extraThe glossaries-extra package has category post-link hooks that make it easier to adjust the +formatting. The post-link hook is placed after the hyperlink around the link text, so a hyperlink created by longheader

    The longheader style is like long but has a header row. -
    +class="cmtt-10">\footnote in the post-link hook won’t cause a nested link. This means that the hyperfirst=false option isn’t +required:

    +
    longheaderborder
    The longheaderborder style is like longheader but has horizontal - and vertical lines around it. -
    +class="cmtt-10">\usepackage[postdot,stylemods]{glossaries-extra} +
    +
    +

    Never use commands like \gls or \glsdesc in the post-link hook as you can end up with infinite recursion. +Use commands that don’t themselves have a post-link hook, such as \glsentrydesc or \glossentrydesc, +instead.
    +

    +

    In the original sample-FnDesc.tex file, the format was adjusted with:

    +
    long3col
    The long3col style is like long but has three columns. The first column contains - the entry’s name, the second column contains the description and the third column - contains the number list. The entry’s symbol is ignored. The width of the first - column is governed by the widest entry in that column, the width of the second - column is governed by the length \glsdescwidth, and the width of the third - column is governed by the length \glspagelistwidth. -
    +class="cmtt-10">\renewcommand*{\glsentryfmt}{% +
      \glsgenentryfmt +
      \ifglsused{\glslabel}{}{\footnote{\glsentrydesc{\glslabel}}}% +
    } +
    +
    This can be changed to:
    +
    +\glsdefpostlink +
    {general}% category label +
    {\glsxtrifwasfirstuse{\footnote{\glsentrydesc{\glslabel}}}{}} + + +
    +
    This sets the post-link hook for the general category (which is the default category for entries defined with long3colborder
    The long3colborder style is like the long3col style but has horizontal - and vertical lines around it. -
    +class="cmtt-10">\newglossaryentry). If I added some abbreviations (which have a different category) then this change wouldn’t +apply to them. +

    The first paragraph in the document is: + + +

    +
    +First use: \gls{sample}. +
    +

    So the PDF will have the word “sample” (the link text created by \gls{sample}) as a hyperlink to the entry in +the glossary followed by the footnote marker, which is a hyperlink to the footnote. This is then followed by the +sentence terminator. “First use: sample1.” +

    It would look tidier if the footnote marker could be shifted after the full stop. “First use: sample.1” This can +easily be achieved with a minor modification:

    +
    +\glsdefpostlink +
    {general}% category label +
    {\glsxtrifwasfirstuse +
     {\glsxtrdopostpunc{\footnote{\glsentrydesc{\glslabel}}}}% +
     {}% +
    } +
    +
    You may prefer to use \glossentrydesc instead of \glsentrydesc. This will obey the glossdesc attribute. If +you append \glspostdescription, you can also pick up the postdot package option. For example: +
    +
    +\glssetcategoryattribute{general}{glossdesc}{firstuc} +
    +
    \glsdefpostlink +
    {general}% category label +
    {\glsxtrifwasfirstuse +
     {\glsxtrdopostpunc{\footnote{% +
        \glossentrydesc{\glslabel}\glspostdescription}}}% +
     {}% +
    } +
    +
    Alternatively, you could just use \Glsentrydesc and explicitly append the full stop. + +

    +

    +

    🔗sample-custom-acronym.tex

    +

    This document illustrates how to define your own acronym style if the predefined styles don’t suit your +requirements. + + +

    
    +   
    pdflatex sample-custom-acronym +
    makeglossaries sample-custom-acronym +
    pdflatex sample-custom-acronym +
    +
    +In this case, a style is defined to show the short form in the text with the long form and description in a +footnote on first use. The long form is used for the sort value. The short form is displayed in small caps in the +main part of the document but in uppercase in the list of acronyms. (So it’s a slight variation of some of the +examples above.) The name is set to the long form (starting with an initial capital) followed by the all caps short +form in parentheses. The final requirement is that the inline form should show the long form followed by the +short form in parentheses. +


    glossaries-extraAs with sampleFnAcrDesc.tex, the short-sc-footnote-desc and short-sc-postfootnote-desc +abbreviation styles produce almost the required effect so one of those can be used as a starting point. +However the final requirement doesn’t fit. It’s now necessary to actually define a custom abbreviation +style, but it can mostly inherit from the short-sc-footnote-desc or short-sc-postfootnote-desc style: +

    +
    +\newabbreviationstyle{custom-fn}% +
    {% +
      \GlsXtrUseAbbrStyleSetup{short-sc-footnote-desc}% +
    }% +
    {% +
      \GlsXtrUseAbbrStyleFmts{short-sc-footnote-desc}% +
      \renewcommand*{\glsxtrinlinefullformat}[2]{% +
        \glsfirstlongfootnotefont{\glsaccesslong{##1}% +
           \ifglsxtrinsertinside##2\fi}% +
         \ifglsxtrinsertinside\else##2\fi\glsxtrfullsep{##1}% +
        \glsxtrparen{\glsfirstabbrvscfont{\glsaccessshort{##1}}}% +
      }% +
      \renewcommand*{\glsxtrinlinefullplformat}[2]{% +
        \glsfirstlongfootnotefont{\glsaccesslongpl{##1}% +
           \ifglsxtrinsertinside##2\fi}% +
        \ifglsxtrinsertinside\else##2\fi\glsxtrfullsep{##1}% +
        \glsxtrparen{\glsfirstabbrvscfont{\glsaccessshortpl{##1}}}% +
      }% +
      \renewcommand*{\Glsxtrinlinefullformat}[2]{% +
        \glsfirstlongfootnotefont{\Glsaccesslong{##1}% +
           \ifglsxtrinsertinside##2\fi}% +
         \ifglsxtrinsertinside\else##2\fi\glsxtrfullsep{##1}% +
        \glsxtrparen{\glsfirstabbrvscfont{\glsaccessshort{##1}}}% +
      }% +
      \renewcommand*{\Glsxtrinlinefullplformat}[2]{% +
        \glsfirstlongfootnotefont{\Glsaccesslongpl{##1}% + + +
           \ifglsxtrinsertinside##2\fi}% +
        \ifglsxtrinsertinside\else##2\fi\glsxtrfullsep{##1}% +
        \glsxtrparen{\glsfirstabbrvscfont{\glsaccessshortpl{##1}}}% +
      }% +
    } +
    +
    (See the glossaries-extra user manual for further details.) +

    This new custom style now needs to be set:

    +
    +\setabbreviationstyle[acronym]{custom-fn} +
    +
    Remember that if you decide to use \newabbreviation instead of \newacronym then the category will be +abbreviation not acronym:
    +
    +\setabbreviationstyle{custom-fn} +
    +
    This custom style simply adjusts the inline full form. There are other adjustments to be made that apply to the +inherited style. (The alternative is to design a new style from scratch.) The footnote contains the +long form followed by the description. This is the same as the modification to an earlier example: +
    +
    long3colheader
    The long3colheader style is like long3col but has a header row. -
    +class="cmtt-10">\renewcommand*{\glsxtrabbrvfootnote}[2]{\footnote{#2: +
    \glsentrydesc{#1}.}} +
    +
    As with sampleCustomAcr.tex, if you specifically want the singular long form then you can ignore the second +argument. For example:
    +
    long3colheaderborder
    The long3colheaderborder style is like long3colheader but has - horizontal and vertical lines around it. -
    +class="cmtt-10">\renewcommand*{\glsxtrabbrvfootnote}[2]{\footnote +
     {\Glsfmtlong{#1}: \glsentrydesc{#1}.}} +
    +
    +

    The name now needs to be the long form followed by the short form in parentheses, but note the new +requirement that the short form should now be in all capitals not small caps and the long form should start with +a capital letter.

    + + +
    long4col
    The long4col style is like long3col but has an additional column in which - the entry’s associated symbol appears. This style is used for brief single line - descriptions. The column widths are governed by the widest entry in the given - column. Use altlong4col for multi-line descriptions. -
    +class="cmtt-10">\renewcommand*{\glsxtrfootnotedescname}{% +
      \protect\glsfirstlongfootnotefont +
        {\makefirstuc{\the\glslongtok}} +
      (\protect\MakeTextUppercase{\the\glsshorttok})% +
    } +
    +
    The inherited abbreviation style uses the short form as the sort value by default. This needs to be changed to +the long form:
    +
    long4colborder
    The long4colborder style is like the long4col style but has horizontal - and vertical lines around it. -
    +class="cmtt-10">\renewcommand*{\glsxtrfootnotedescsort}{\the\glslongtok} +
    +
    +

    If you want to switch to using bib2gls, remember to set the abbreviation style before the +resource command and change the default sort fallback field to long, as with sampleAcrDesc.tex. +
    +

    + +

    +

    +

    🔗sample-dot-abbr.tex

    +

    This document illustrates how to use the base post link hook to adjust the space factor after abbreviations. +

    
    +   
    pdflatex sample-dot-abbr +
    makeglossaries sampledot-abbrf +
    pdflatex sample-dot-abbr +
    +
    +This example creates a custom storage key that provides a similar function to glossaries-extra’s category +key. +


    glossaries-extraThis example is much simpler with glossaries-extra. The custom storage key, which is defined +using:

    +
    long4colheader
    The long4colheader style is like long4col but has a header row. -
    +class="cmtt-10">\glsaddstoragekey{abbrtype}{word}{\abbrtype} +
    +
    can now be removed. +

    The category key is set to initials for the initialisms (which are defined with the custom \newacr +command). The abbreviation styles can be set with:

    + + +
    +\setabbreviationstyle[acronym]{long-short} +
    \setabbreviationstyle[initials]{long-short} +
    +
    The discardperiod attribute will discard any full stop (period) following commands like \gls:
    +
    +\glssetcategoryattribute{initials}{discardperiod}{true} +
    +
    (If you want to use the noshortplural attribute then you will also need to set the pluraldiscardperiod +attribute.) +

    The first use is governed by the retainfirstuseperiod attribute. If set, the period won’t be discarded if it +follows the first use of commands like \gls. This is useful for styles where the first use doesn’t end with the +short form. In this case, the first use of the long-short style ends with a closing parenthesis, so the end of +sentence might be clearer if the period is retained:

    +
    +\glssetcategoryattribute{initials}{retainfirstuseperiod}{true} +
    +
    +

    The insertdots attribute can automatically insert dots into the short form with a final space factor +adjustment:

    +
    +\glssetcategoryattribute{initials}{insertdots}{true} +
    +
    +

    The custom helper command defined in the example needs to be slightly modified:

    +
    long4colheaderborder
    The long4colheaderborder style is like long4colheader but has - horizontal and vertical lines around it. -
    +class="cmtt-10">\newcommand*{\newabbr}[1][]{% +
     \newabbreviation[category=initials,#1]} +
    +
    The definitions need to be slightly modified to work with the insertdots attribute:
    +
    altlong4col
    The altlong4col style is like long4col but allows multi-line descriptions - and page lists. The width of the description column is governed by the length - \glsdescwidth and the width of the page list column is governed by the length - \glspagelistwidth. The widths of the name and symbol columns are governed - by the widest entry in the given column. - - -
    +class="cmtt-10">\newabbr{eg}{eg}{eg} +
    \newabbr{ie}{ie}{ie} +
    \newabbr{bsc}{B{Sc}}{Bachelor of Science} +
    \newabbr{ba}{BA}{BA} +
    \newabbr{agm}{AGM}{AGM} + + +
    +
    (This makes it much easier to change your mind if you decide at a later date to omit the dots, especially if you +are storing all your definitions in a file that’s shared across multiple documents, but note the need to group +“Sc”.) +

    The “laser” definition remains unchanged: + + +

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

    The remaining code in the preamble must now be removed. (It will interfere with glossaries-extra’s category +post-link hooks.) No change is required in the document body. +

    See the glossaries-extra user manual for further details about category attributes and post-link +hooks. + +

    +

    +

    🔗sample-font-abbr.tex

    +

    This document illustrates how to have different fonts for abbreviations within the style. The document build +is: +

    
    +   
    pdflatex sample-font-abbr +
    makeglossaries sample-font-abbr +
    pdflatex sample-font-abbr +
    +
    +The acronym mechanism provided by the base glossaries package isn’t well suited to having a mixture of styles. +This example provides a workaround that involves defining a new storage key with \glsaddstoragekey that’s +used to hold the font declaration (such as \em). + + +

    +
    +\glsaddstoragekey{font}{}{\entryfont} +
    +

    A new custom acronym style is defined that fetches the font information from this new key so that it can be +applied to the abbreviation. Some helper commands are also provided to define the different types of +abbreviation: + + +

    +
    +\newcommand*{\newitabbr}[1][]{\newacronym[font=\em,#1]} + 
    \newcommand*{\newupabbr}{\newacronym} + 
    \newitabbr{eg}{e.g.}{exempli gratia} + 
    \newupabbr{bsc}{BSc}{Bachelor of Science} +
    +

    This makes the first use of \gls{eg} appear as “exempli gratia (e.g.)” whereas the first use of \gls{bsc} is +“Bachelor of Science (BSc)”. +


    glossaries-extraThis example document is much simpler with glossaries-extra. First the \usepackage +command needs adjusting:

    +
    altlong4colborder
    The altlong4colborder style is like the long4colborder but allows - multi-line descriptions and page lists. -
    +class="cmtt-10">\usepackage[postdot,stylemods]{glossaries-extra} +
    +
    The custom storage key can now be removed and also the custom acronym style. Now replace the altlong4colheader
    The altlong4colheader style is like long4colheader but allows - multi-line descriptions and page lists. -
    +class="cmtt-10">\setacronymstyle line with:
    +
    +\setabbreviationstyle[acronym]{long-short-em} +
    +
    and change the definition of the helper commands:
    +
    altlong4colheaderborder
    The altlong4colheaderborder style is like - long4colheaderborder but allows multi-line descriptions and page lists.
    -

    +class="cmtt-10">\newcommand*{\newitabbr}{\newacronym} +
    \newcommand*{\newupabbr}{\newabbreviation} +

    +
    Note that the font=\em, part has been removed from the definition of the first command and the second +command uses \newabbreviation instead of \newacronym. This means that \newitabbr will default to +category=acronym and \newupabbr will default to category=abbreviation. The default style for the +abbreviation category is long-short, which is the required style for this example. This just means that +only the acronym category needs to have the style set (with the above \setabbreviationstyle +command). +

    Finally, the \acrshort, \acrlong and \acrfull commands need to be replaced with \glsxtrshort, +\glsxtrlong and \glsxtrfull. +

    You may notice that the spacing after “e.g.” and “i.e.” isn’t correct. This is similar to the sample-dot-abbr.tex +example where the space factor needs adjusting. In this case I’ve inserted the dots manually (rather than relying +on the insertdots attribute). You can either remove the dots and use insertdots with discardperiod: +

    + + +
    +\glssetcategoryattribute{acronym}{insertdots}{true} +
    \glssetcategoryattribute{acronym}{discardperiod}{true} +
    +
    \newitabbr{eg}{eg}{exempli gratia} +
    \newitabbr{ie}{ie}{id est} +
    +
    Or you can manually insert the space factor adjustment and only use the discardperiod attribute: +
    +
    +\glssetcategoryattribute{acronym}{discardperiod}{true} +
    +
    \newitabbr{eg}{e.g.\@}{exempli gratia} +
    \newitabbr{ie}{i.e.\@}{id est} +
    +
    +

    You don’t have to use the acronym category. You may prefer a different label that fits better semantically. +For example:

    +
    +\setabbreviationstyle[latinabbr]{long-short-em} +
    \newcommand*{\newlatinabbr}[1][]{\newabbreviation[category=latinabbr,#1]} +
    \glssetcategoryattribute{latinabbr}{insertdots}{true} +
    \glssetcategoryattribute{latinabbr}{discardperiod}{true} +
    +
    \newlatinabbr{eg}{e.g.\@}{exempli gratia} +
    \newlatinabbr{ie}{i.e.\@}{id est} +
    +
    +

    -

    Top

    15.1.3 Longtable Styles (Ragged Right)

    -

    The styles described in this section are all defined in the package glossary-longragged. These -styles are analogous to those defined in glossary-long but the multiline columns are left -justified instead of fully justified. Since these styles all use the longtable environment, they are -governed by the same parameters as that environment. The glossary-longragged package -additionally requires the array package. Note that these styles will only be available if you -explicitly load glossary-longragged: - - +

    Top

    19.3 Non-Page Locations

    + +

    -
    -\usepackage{glossaries} - 
    \usepackage{glossary-longragged} +

    🔗sampleEq.tex

    + + +

    This document illustrates how to change the location to something other than the page number. In this case, +the equation counter is used since all glossary entries appear inside an equation environment. To create the +document do: +

    
    +   
    pdflatex sampleEq +
    makeglossaries sampleEq +
    pdflatex sampleEq +
    +
    +The glossaries package provides some location formats, such as \hyperrm and \hyperbf, that allow the +locations in the number list to hyperlink to the appropriate place in the document (if hyperref has +been used). Since it’s not possible to include the hyperlink name in the indexing information with +makeindex and xindy, the glossaries package has to reform the name from a prefix and the location +value. +

    Unfortunately it’s not always possible to split the link name into a prefix and location. That happens with +the equation counter in certain classes, such as the report class (which is used in this example). +This means that it’s necessary to redefine \theHequation so that it has a format that fits the +requirement: + + +

    +
    +\renewcommand*\theHequation{\theHchapter.\arabic{equation}} +
    +

    If you don’t do this, the equation locations in the glossary won’t form valid hyperlinks. +

    Each glossary entry represents a mathematical symbol. This means that with Options 13 it’s necessary to +use the sort key. For example:

    +
    +\newglossaryentry{Gamma}{name=\ensuremath{\Gamma(z)}, +
    description=Gamma function,sort=Gamma}
    -

    Note that you can’t set these styles using the style package option since the styles aren’t -defined until after the glossaries package has been loaded. If you want to incorporate rules -from the booktabs package, try the styles described in §15.1.4 Longtable Styles -(booktabs). -

    +
    +

    bib2glsIf you want to switch to using bib2gls, the first change you need to make is to switch from +explicitly loading glossaries to loading glossaries-extra with the record package option. If record=only (or record +without a value) is used, then the above redefinition of \theHequation is still required. If record=nameref is used +instead then the redefinition of \theHequation isn’t required. You may also want to use the stylemods and +postdot options:

    +
    longragged
    The longragged style has two columns: the first column contains the entry’s - name and the second column contains the (left-justified) description followed by - the \usepackage[record=nameref,stylemods,postdot, +
     ucmark,style=long3colheader,counter=equation]{glossaries-extra} +
    +
    The entries now need to be converted into the bib format required by bib2gls, which can be done with +convertgls2bib: +

    
    +   
    convertgls2bib --preamble-only sampleEq.tex entries.bib +
    +
    +This will create a file called entries.bib that starts:

    +
    +% Encoding: UTF-8 +
    @entry{Gamma, +
      name = {\ensuremath{\Gamma(z)}}, +
      description = {Gamma function} +
    } +
    +
    You may prefer to change @entry to @symbol. (This should be easy to do with your text editor’s search and +replace function.) + + +

    Note that the sort key has been omitted. This is because it typically shouldn’t be used. The difference +between using @entry and @symbol is that with @entry the sort value will be obtained from the name but with +@symbol the sort value will be obtained from the label. If you explicitly use the sort key then you will break +this behaviour. (If you try this example out, notice the difference in the ordering if you switch between @entry +and @symbol. See also bib2gls gallery: sorting.) +

    Next replace \makeglossaries with:

    +
    +\GlsXtrLoadResources[src=entries] +
    +
    If you have used record=nameref then you can remove the redefinition of \theHequation. Next remove all the +lines defining the glossary entries (since they’re now defined in the bib file). +

    Finally, replace \printglossary with \printunsrtglossary:

    +
    +\printunsrtglossary[title={Index of Special Functions and +
    Notations}] +
    +
    The rest of the document remains unchanged (unless you want to use \glsxtrfmt as described in the following +example). + +

    +

    +

    🔗sampleEqPg.tex

    +

    This is similar to the previous example, but the number list. The entry’s symbol is ignored. Sub groups are separated with a - blank row. The width of the first column is governed by the widest entry in that - column. The width of the second column is governed by the length \glsdescwidth. - Child entries have a similar format to the parent entries except that their name - is suppressed. -

    + id="dx1-189001">s are a mixture of page numbers and +equation numbers. This example adds the glossary to the table of contents, so an extra LATEX run is +required: +

    
    +   
    pdflatex sampleEqPg +
    makeglossaries sampleEqPg +
    pdflatex sampleEqPg +
    pdflatex sampleEqPg +
    +
    +As with the previous example, entries are defined like this: + + +

    +
    +\newglossaryentry{Gamma}{name=\ensuremath{\Gamma(z)}, + 
    description=Gamma function,sort=Gamma} +
    +

    The counter=equation package option is used to set the default indexing counter to equation. This means that it +has to be changed for indexing outside of any numbered equation. For example: + + +

    +
    +\glslink[format=hyperbf,counter=page]{Gamma}{gamma function} +
    +

    I’ve set the format to hyperbf to indicate that this is a primary reference. (Note that I’m using \hyperbf not +\textbf in order to include a hyperlink in the location.) +

    The link text here is almost identical to the description. The only difference is that the description starts +with a capital. If it started with a lowercase character instead, I could simply use \glsdesc instead of longraggedborder

    The longraggedborder style is like longragged but has horizontal - and vertical lines around it. -
    +class="cmtt-10">\glslink. If I change the entry descriptions so that they all start with a lowercase letter then I would need to +create a custom glossary style that used \Glossentrydesc instead of \glossentrydesc. +


    glossaries-extraIf I switch to using glossaries-extra I wouldn’t need a new glossary style. Instead I could just +use the glossdesc attribute to perform the case change. Remember that the first change to make is to replace longraggedheader

    The longraggedheader style is like longragged but has a header row. -
    +class="cmss-10">glossaries with glossaries-extra:

    +
    longraggedheaderborder
    The longraggedheaderborder style is like longraggedheader - but has horizontal and vertical lines around it. -
    +class="cmtt-10">\usepackage[style=long3colheader,postdot,stylemods, +
                counter=equation]{glossaries-extra} +
    +
    The entries are now all defined so that the description starts with a lowercase letter (except for the descriptions +that start with a proper noun). For example:
    +
    longragged3col
    The longragged3col style is like longragged but has three columns. - The first column contains the entry’s name, the second column contains the (left - justified) description and the third column contains the (left justified) number - list. The entry’s symbol is ignored. The width of the first column is governed by - the widest entry in that column, the width of the second column is governed by - the length \glsdescwidth, and the width of the third column is governed by the - length \glspagelistwidth. -
    +class="cmtt-10">\newglossaryentry{Gamma}{name=\ensuremath{\Gamma(z)}, +
    description=gamma function,sort=Gamma} +
    +
    The glossdesc attribute needs setting:
    +
    +\glssetcategoryattribute{general}{glossdesc}{firstuc} +
    +
    This means that I can now use \glsdesc instead of \glslink. +

    It’s a bit cumbersome typing [format=hyperbf,counter=page] for each primary reference, but +glossaries-extra provides a convenient way of having a third modifier for commands like \gls and \glstext. This +needs to be a single punctuation character (but not * or + which are already in use). For example: +

    +
    +\GlsXtrSetAltModifier{!}{format=hyperbf,counter=page} + + +
    +
    Now \glsdesc!{Gamma} is equivalent to:
    +
    longragged3colborder
    The longragged3colborder style is like the longragged3col style - but has horizontal and vertical lines around it. -
    +class="cmtt-10">\glsdesc[format=hyperbf,counter=page]{Gamma} +
    +
    So the text at the start of the “Gamma Functions” chapter is now just:
    +
    longragged3colheader
    The longragged3colheader style is like longragged3col but has - a header row. - - -
    +class="cmtt-10">The \glsdesc!{Gamma} is defined as +
    +
    which is much more compact. Similar changes can be made for the other instance of \glslink where the link +text is just the description:
    +
    longragged3colheaderborder
    The longragged3colheaderborder style is like - longragged3colheader but has horizontal and vertical lines around it. -
    +class="cmtt-10">The \glsdesc!{erf} is defined as +
    +
    +

    There are three other instances of \glslink, such as:

    +
    altlongragged4col
    The altlongragged4col style is like longragged3col but has an - additional column in which the entry’s associated symbol appears. The width of - the description column is governed by the length \glsdescwidth and the width of - the page list column is governed by the length \glspagelistwidth. The widths - of the name and symbol columns are governed by the widest entry in the given - column. -
    +class="cmtt-10">\glslink{Gamma}{\Gamma(x+1)} +
    +
    If I just use \gls{Gamma} then I would get Γ(z) as the link text. For entries like this that represent functions +with variable parameters it would be more convenient (and help with consistency) if a command was available +to easily replace the parameters. +

    With the base glossaries package, one simple solution that works for this example is to save just the function +symbol in the symbol field, for example:

    +
    altlongragged4colborder
    The altlongragged4colborder style is like the - altlongragged4col but has horizontal and vertical lines around it. -
    +class="cmtt-10">\newglossaryentry{Gamma}{name=\ensuremath{\Gamma(z)}, +
    symbol={\ensuremath{\Gamma}}, +
    description=gamma function,sort=Gamma} +
    +
    and then use:
    +
    +\glssymbol{Gamma}[(\Gamma(x+1))] +
    +
    (which includes the function parameter inside the link text) or just:
    + + +
    altlongragged4colheader
    The altlongragged4colheader style is like altlongragged4col - but has a header row. -
    +class="cmtt-10">\glssymbol{Gamma}(\Gamma(x+1)) +
    +
    (which has the function parameter after the link text). This is a convenient approach where the extra material +can simply follow the symbol, and it can also be used with glossaries-extra. +

    The glossaries-extra package provides another possibility. It requires a command that takes a single +argument, for example: + + +

    +
    +\newcommand{\Gammafunction}[1]{\Gamma(#1)} +
    +

    The control sequence name (the command name without the leading backslash) is stored in the field identified +by the command \GlsXtrFmtField (this should be the internal field name not the key name, see table 4.1). +The default is useri which corresponds to the user1 key. This means that the Gamma entry would need to be +defined with user1=Gammafunction. With this approach, each function entry would need a separate associated +command. +

    Another approach is to store the parameterless function in the symbol key (as earlier) and have a more +generic command that uses this symbol. This requires the entry label, which can be obtained with \glslabel +within the link text:

    +
    altlongragged4colheaderborder
    The altlongragged4colheaderborder style is like - altlongragged4colheader but has horizontal and vertical lines around it. -
    -

    -

    -

    Top

    15.1.4 Longtable Styles (booktabs)

    -

    The styles described in this section are all defined in the package glossary-longbooktabs. -

    Since these styles all use the longtable environment, they are governed by the same -parameters as that environment. The glossary-longbooktabs package automatically loads the +class="cmtt-10">\newcommand{\entryfunc}[1]{\glsentrysymbol{\glslabel}(#1)} +

    +
    (Obviously, this command can’t be used outside of the link text or post-link hooks since it uses glossary-long (§15.1.2 Longtable Styles) and glossary-longragged (§15.1.3 Longtable Styles -(Ragged Right)) packages. Note that these styles will only be available if you explicitly load +class="cmtt-10">\glslabel.) +

    So the entry now needs the parameterless function in symbol and the control sequence name of this generic +command in user1. For example:

    +
    glossary-longbooktabs: - - -

    -
    -\usepackage{glossaries} - 
    \usepackage{glossary-longbooktabs} +class="cmtt-10">\newglossaryentry{Gamma}{name=\ensuremath{\Gamma(z)}, +
    symbol={\ensuremath{\Gamma}},user1=entryfunc, +
    description=gamma function,sort=Gamma}
    -

    Note that you can’t set these styles using the style package option since the styles aren’t -defined until after the glossaries package has been loaded. -

    These styles are similar to the “header” styles in the glossary-long and glossary-ragged -packages, but they add the rules provided by the booktabs package, \toprule, \midrule and +

    (This doesn’t need to be done for the C and G entries since they’re constants not functions.) +

    You may want to consider providing helper commands to make the functions easier to define. For +example: + + +

    +
    +\newcommand{\func}[2]{#1(#2)} + 
    \newcommand{\entryfunc}[1]{\func{\glsentrysymbol{\glslabel}}{#1}} + 
    \newcommand{\newfunc}[5][]{% + 
     \newglossaryentry{#2}{name={\ensuremath{\func{#3}{#4}}}, + 
       symbol={#3}, + 
       user1={entryfunc}, + 
       description={#5}, + 
       sort={#2},#1 + 
     }% + 
    } +
    +

    The entries can now be defined using this custom \newfunc command. For example: + + +

    +
    +\newfunc{Gamma}{\Gamma}{z}{gamma function} + 
    \newfunc[sort=gamma1]{gamma}{\gamma}{\alpha,x}{lower + 
      incomplete gamma function} + 
    \newfunc[sort=Gamma2]{iGamma}{\Gamma}{\alpha,x}{upper + 
      incomplete gamma function} +
    +

    +

    Note that in \newfunc the symbol key doesn’t have its value encapsulated with \ensuremath so \glssymbol +will need to explicitly be placed in math mode. If you switch to a glossary style that displays the symbol, you +will either need to adjust the definition of \newfunc to use \ensuremath in the symbol field or you can add the +encapsulation with the glosssymbolfont attribute. +

    Now \glslink{Znu}{Z_\nu} can simply be replaced with \glssymbol{Znu} (no parameter is required in +this case). For the other cases, where the parameter is different from that given in the text field (which is +obtained from the name), you can use \glsxtrfmt. For example, \glslink{Gamma}{\Gamma(x+1)} can now be +replaced with:

    +
    +\glsxtrfmt{Gamma}{x+1} +
    +
    This effectively works like \glslink but omits the post-link hook. (See the glossaries-extra user manual for +further details.) +

    Don’t use \glsxtrfmt within the argument of another \glsxtrfmt command (or inside any other link +text).
    +

    +

    Similarly \glslink{Gamma}{\Gamma(\alpha)} can now be replaced with:

    +
    +\glsxtrfmt{Gamma}{\alpha} +
    +
    Note that it’s still possible to use:
    +
    \bottomrule. Additionally these styles patch the longtable environment to check for instances -of the group skip occurring at a page break. If you don’t want this patch to affect any other -use of longtable in your document, you can scope the effect by only setting the style through -the style key in the optional argument of \printglossary. (The nogroupskip package option -is checked by these styles.) -

    Alternatively, you can restore the original longtable behaviour with: -


    \glsrestoreLToutput  \glsrestoreLToutput

    -

    -For more information about the patch, see the documented code (glossaries-code.pdf). -

    +class="cmtt-10">\glssymbol{Gamma}[(\alpha)] +
    +
    You may prefer to define a helper command that makes it easier to switch between your preferred method. For +example: + + +
    +\newcommand*{\Fn}[3][]{\glssymbol[#1]{#2}[(#3)]} +
    +

    or:

    +
    long-booktabs
    This style is similar to the longheader style but adds rules above and - below the header (\toprule and \midrule) and inserts a rule at the bottom of - the table (\bottomrule). -
    +class="cmtt-10">\newcommand*{\Fn}[3][]{\glsxtrfmt[#1]{#2}{#3}} +
    +
    +

    bib2glsIf you want to convert this example so that it works with bib2gls, first convert it to use +glossaries-extra (as described above), and then follow the instructions from sampleEq.tex. The +convertgls2bib application recognises \newcommand so it will be able to parse the custom \newfunc +commands. +

    Note that bib2gls allows you to separate the locations in the number list into different groups according to +the counter used for the location. This can be done with the loc-counters resource option. It’s also possible to +identify primary formats (such as hyperbf used in this example) using the primary-location-formats option. +The primary locations can then be given a more prominent position in the number list. See the bib2gls user +manual for further details. + +

    +

    +

    🔗sampleSec.tex

    +

    This document also illustrates how to change the location to something other than the page number. In this +case, the section counter is used. This example adds the glossary to the table of contents, so an extra +LATEX run is required: +

    
    +   
    pdflatex sampleSec +
    makeglossaries sampleSec +
    pdflatex sampleSec +
    pdflatex sampleSec +
    +
    +Note that there are conflicting location formats, which trigger a warning from makeindex: + + +

    +
    +## Warning (input = sampleSec.glo, line = 6; output = + 
    sampleSec.gls, line = 9): + 
       -- Conflicting entries: multiple encaps for the same page + 
    under same key. + 
    ## Warning (input = sampleSec.glo, line = 2; output = + 
    sampleSec.gls, line = 10): + 
       -- Conflicting entries: multiple encaps for the same page + 
    under same key. +
    +

    This is the result of indexing an entry multiple times for the same +location19.1 +with different values of the format key. In this case, it’s caused by three references to the ident entry in +section 2.1: + + +

    +
    +\gls[format=hyperit]{ident} + 
    \glspl{ident} % default format=glsnumberformat + 
    \gls*[format=hyperbf]{ident} +
    +

    +

    If you use the makeglossaries Perl script it will detect the warnings in the makeindex transcript file and +attempt to fix the conflict by removing entries from the glo file: + + +

    +
    +Multiple encaps detected. Attempting to remedy. + 
    Reading sampleSec.glo... + 
    Writing sampleSec.glo... + 
    Retrying +
    +

    (Range formats have highest precedence. The default glsnumberformat has the lowest precedence.) +

    If you use makeglossaries-lite or call makeindex directly then the problem won’t be fixed and the +glossary will end up with the rather odd number list for the identity matrix entry consisting of three references +to section 2.1: the first in the default font, followed by bold (hyperbf) and then italic (hyperit), +which results in 2.1, 2.1, 2.1. If you use makeglossaries then only the bold entry (2.1) will be +present. +

    If you switch to xindy:

    +
    long3col-booktabs
    This style is similar to the long3colheader style but adds rules as - per long-booktabs. -
    +class="cmtt-10">\usepackage[xindy,style=altlist,toc,counter=section]{glossaries} +
    +
    then the conflict will be resolved using the number format attribute list order of priority. In this case, long4col-booktabs
    This style is similar to the long4colheader style but adds rules as - above. -
    +class="cmtt-10">glsnumberformat has the highest priority. This means that only the upright medium weight entry (2.1) will be +present. The simplest way of altering this is to provide your own custom format. For example: +
    +
    +\newcommand*{\primary}[1]{\hyperit{#1}} +
    \GlsAddXdyAttribute{primary} +
    +
    and change \gls[format=hyperit] to \gls[format=primary] etc. This will give format=primary the highest +priority. (It’s also better practice to provide this kind of semantic command.) +

    With bib2gls, you can supply rules to deal with location format conflicts, as illustrated below. +

    bib2glsIn order to switch to bib2gls, first replace glossaries with glossaries-extra, and add the record +package option. Remember that glossaries-extra has a different set of defaults and you may also want to patch +the predefined base styles. For example:

    +
    altlong4col-booktabs
    This style is similar to the altlong4colheader style but adds rules - as above. -
    +class="cmtt-10">\usepackage[style=altlist,postdot,stylemods,counter=section] +
    {glossaries-extra} +
    +
    +

    The entry definitions now need to be converted into bib2gls format and saved in a bib file (say, +entries.bib). You can use convertgls2bib: + + +

    
    +   
    convertgls2bib --preamble-only sampleSec.tex entries.bib +
    +
    +

    Next replace \makeglossaries with:

    +
    +\GlsXtrLoadResources[src=entries] +
    +
    and remove all the \newglossaryentry commands. +

    Finally, replace \printglossaries with \printunsrtglossaries. The document build is now: +

    
    +   
    pdflatex sampleSec +
    bib2gls sampleSec +
    pdflatex sampleSec +
    +
    +As with the original example, there’s still a location format conflict, which bib2gls warns about: + + +

    +
    +Warning: Entry location conflict for formats: hyperbf and hyperit + 
    Discarding: {ident}{}{section}{hyperbf}{2.1} + 
    Conflicts with: {ident}{}{section}{hyperit}{2.1} +
    +

    This means that it has discarded the bold location and kept the italic one. (As with makeglossaries, range +formats have the highest priority and glsnumberformat has the lowest.) +

    It would be better if the conflict could be merged into a single location that was both bold and italic. To +achieve this, it’s first necessary to define a command that produces this effect:

    +
    longragged-booktabs
    This style is similar to the longraggedheader style but adds rules - as above. -
    +class="cmtt-10">\newcommand*{\hyperbfit}[1]{\textbf{\hyperit{#1}}} +
    +
    Now bib2gls needs to be invoked with the appropriate mapping with the --map-format or -m +switch: +

    
    +   
    bib2gls -m ”hyperbf:hyperbfit,hyperit:hyperbfit” sampleSec +
    +
    +If you are using arara the directive should be:

    +
    longragged3col-booktabs
    This style is similar to the longragged3colheader style but - adds rules as above. - - -
    +class="cmtt-10">% arara: bib2gls: { mapformats: [ [hyperbf, hyperbfit], +
    % arara: --> [hyperit, hyperbfit] ] } +
    +
    +

    If you try out this example, notice the difference between record=only and record=nameref. If you use the +latter, the locations will now be the section titles rather than the section numbers. If you use the nameref setting +you can customize the location by defining the command:

    +
    +\glsxtrcounterlocfmt{location}{title} +
    +
    +

    In this case the counter is section, so the command should be \glsxtrsectionlocfmt. It takes two +arguments: the first is the location and the second is the title. For example:

    +
    altlongragged4col-booktabs
    This style is similar to the altlongragged4colheader style - but adds rules as above. -
    -

    +class="cmtt-10">\newcommand*{\glsxtrsectionlocfmt}[2]{\S#1 #2} + + +

    +
    (The only command of this type that is defined by default is the one for the equation counter, +\glsxtrequationlocfmt.) Make sure that you have at least version 1.42 of glossaries-extra. +

    +

    +

    Top

    19.4 Multiple Glossaries

    +

    See also sampleSort.tex in §19.5 Sorting, which has three glossaries. + +

    -

    Top

    15.1.5 Supertabular Styles

    -

    The styles described in this section are all defined in the package glossary-super. -Since they all use the supertabular environment, they are governed by the same -parameters as that environment. Note that these styles will automatically be available -unless you use the nosuper or nostyles package options. In general, the longtable -environment is better, but there are some circumstances where it is better to use +

    🔗sampleNtn.tex

    +

    This document illustrates how to create an additional glossary type. This example adds the glossary to the table +of contents, so an extra LATEX run is required: +

    
    +   
    pdflatex sampleNtn +
    makeglossaries sampleNtn +
    pdflatex sampleNtn +
    pdflatex sampleNtn +
    +
    +Note that if you want to call makeindex explicitly instead of using the makeglossaries or makeglossaries-lite +scripts then you need to call makeindex twice: +

      +
    1. Create the main glossary (all on one line): +

      
      +     
      makeindex -s sampleNtn.ist -t sampleNtn.glg -o sampleNtn.gls sampleNtn.glo +
      +
      +

    2. +
    3. Create the secondary glossary (all on one line): +

      
      +     
      makeindex -s sampleNtn.ist -t sampleNtn.nlg -o sampleNtn.not sampleNtn.ntn +
      +
      +

    +

    This document creates a new glossary using:

    + + +
    supertabular.15.3 -These styles fully justify the description and page list columns. If you want ragged right -formatting instead, use the analogous styles described in §15.1.6 Supertabular Styles (Ragged -Right). -

    +class="cmtt-10">\newglossary[nlg]{notation}{not}{ntn}{Notation} +
    +
    This defines a glossary that can be identified with the label notation with the default title “Notation”. The +other arguments are the file extensions required with Options 2 and 3. For those two options, the glossaries +package needs to know the input and output files required by makeindex or xindy. +

    (The optional argument is the file extension of the indexing transcript file, which glossaries doesn’t need to +know about, but it writes the information to the aux file for the benefit of makeglossaries and +makeglossaries-lite.) +

    If you switch to a different indexing option then these file extensions aren’t required, in which case it’s +simpler to use the starred form:

    +
    super
    The super style uses the supertabular environment (defined by the supertabular - package). It has two columns: the first column contains the entry’s name and the - second column contains the description followed by the number list. The entry’s - symbol is ignored. Sub groups are separated with a blank row. The width of the - first column is governed by the widest entry in that column. The width of the - second column is governed by the length \glsdescwidth. Child entries have a - similar format to the parent entries except that their name is suppressed. -
    +class="cmtt-10">\newglossary*{notation}{Notation} +
    +
    +

    This example uses a label prefixing system19.2 to +differentiate between the different types of entries. For example, the term “set” is defined as: + + +

    +
    +\newglossaryentry{gls:set}{name=set, + 
    description={A collection of distinct objects}} +
    +

    and the set notation is defined as: + + +

    +
    +\newglossaryentry{not:set}{type=notation, + 
    name={\ensuremath{\mathcal{S}}}, + 
    description={A \gls{gls:set}},sort={S}} +
    +

    Notice that the latter description contains \gls. This means you shouldn’t use \glsdesc with this entry +otherwise you will end up with nested links. +


    glossaries-extraThe glossaries-extra package provides a command for use in within field values to prevent +nested link text:

    +
    +\glsxtrp{field}{label} +
    +
    There are convenient shortcuts for common fields: \glsps{label} (for the short field) and \glspt{label} +(for the text field). So the set notation definition can be modified:
    +
    superborder
    The superborder style is like super but has horizontal and vertical lines - around it. -
    +class="cmtt-10">\newglossaryentry{not:set}{type=notation, +
    name={\ensuremath{\mathcal{S}}}, +
    description={A \glspt{gls:set}},sort=S} +
    +
    This will stop the inner reference from causing interference if you use \glsdesc. It will also suppress indexing +within the glossary but will have a hyperlink (if hyperref is used). +

    The glossaries-extra package provides a way of defining commands like \gls that automatically insert a +prefix. For example:

    +
    +\glsxtrnewgls{not:}{\sym} +
    \glsxtrnewglslike{gls:}{\term}{\termpl}{\Term}{\Termpl} +
    +
    (there’s no point providing commands for plural or case-changing with symbols). Now \gls{not:set} can be +replaced with \sym{set} and \gls{gls:set} can be replaced with \term{set}. +

    bib2glsThese two commands are primarily provided for the benefit of bib2gls as the information is written +to the aux file. This allows bib2gls to recognise the custom commands if they have been used in the bib files. +When combined with label-prefix and ext-prefixes (see below) this makes it much simpler to change the +prefixes if necessary. +

    If you want to convert this document to use bib2gls, remember that you need the record or record=nameref +option. For example:

    + + +
    superheader
    The superheader style is like super but has a header row. -
    +class="cmtt-10">\usepackage[record,postdot,stylemods]{glossaries-extra} +
    +
    As with earlier examples, convertgls2bib can be used to convert the entry definitions into +the required bib format. You may prefer to split the entries into separate files according to +type.19.3 +This is useful if you want to reuse a large database of entries across multiple documents as it doesn’t lock you +into using a specific glossary. For example: +

    
    +   
    convertgls2bib --split-on-type --preamble-only sampleNtn.tex entries.bib +
    +
    +This will create a file called entries.bib that contains the entries that didn’t have a type assigned in the +original file, such as:

    +
    +@entry{gls:set, +
      name = {set}, +
      description = {A collection of distinct objects} +
    } +
    +
    It will also create a file called notation.bib that contains the entries that had the type set to notation in the +original file, such as:
    +
    +@entry{not:set, +
      name = {\ensuremath{\mathcal{S}}}, +
      description = {A \glspt{gls:set}} +
    } +
    +
    Note that the type field has been removed. The above entry in the notation.bib file references a term in +the entries.bib file. It’s possible to strip all the prefixes from the bib files and get bib2gls to +automatically insert them. In which case, this cross-reference needs adjusting to indicate that it’s +referring to an entry in another file. This can be done with one of the special extn. prefixes: +
    +
    +@entry{set, +
      name = {\ensuremath{\mathcal{S}}}, +
      description = {A \glspt{ext1.set}} +
    } + + +
    +
    The corresponding term in the entries.bib file is now:
    +
    +@entry{set, +
      name = {set}, +
      description = {A collection of distinct objects} +
    } +
    +
    +

    Now you can replace \makeglossaries with:

    +
    +\GlsXtrLoadResources[src={entries},label-prefix={gls:}] +
    \GlsXtrLoadResources[src={notation},type=notation, +
     label-prefix={not:},ext-prefixes={gls:}] +
    +
    Remove all the \newglossaryentry definitions and replace \printglossaries with \printunsrtglossaries. +

    Regardless of how many resource sets the document contains, only one bib2gls call is required: +

    
    +   
    pdflatex sampleNtn +
    bib2gls sampleNtn +
    pdflatex sampleNtn +
    +
    +

    You may notice that the ordering in the notations list has changed from the original. This is because the +sort field was automatically removed by convertgls2bib, so the entries are now sorted according to the name +field (since they are defined with @entry). You can use your text editor’s search and replace function to replace +all instances of @entry with @symbol in the notations.bib file so that, for example, the set definition +becomes:

    +
    +@symbol{set, +
      name = {\ensuremath{\mathcal{S}}}, +
      description = {A \glspt{ext1.set}} +
    } +
    +
    Now these @symbol entries will be sorted according to their label. (The original label in the bib file, not the +prefixed label.) This will put them in the same order as the original document. (See the “Examples” +chapter of the bib2gls user manual for examples of varying the sorting and also bib2gls gallery: +sorting.) + + + +

    +

    +

    🔗sample-dual.tex

    +

    This document illustrates how to define an entry that both appears in the list of acronyms and in the main +glossary. To create the document do: +

    
    +   
    pdflatex sample-dual +
    makeglossaries sample-dual +
    pdflatex sample-dual +
    +
    +This defines a custom command \newdualentry that defines two entries at once (a normal entry and +an abbreviation). It uses \glsadd to ensure that if one is used then the other is automatically +indexed: + + +

    +
    +\newcommand*{\newdualentry}[5][]{% + 
      % main entry: + 
      \newglossaryentry{main-#2}{name={#4},% + 
      text={#3\glsadd{#2}},% + 
      description={#5},% + 
      #1% additional options for main entry + 
      }% + 
      % abbreviation: + 
      \newacronym{#2}{#3\glsadd{main-#2}}{#4}% + 
    } +
    +

    A sample dual entry is defined with this command: + + +

    +
    +\newdualentry{svm}% label + 
      {SVM}% abbreviation + 
      {support vector machine}% long form + 
      {Statistical pattern recognition technique}% description +
    +

    This defines an acronym with the label svm that can be referenced with \gls{svm} but it also defines an entry +with the label main-svm. This isn’t used in the document with \gls but it’s automatically added from the +\glsadd{main-svm} in the short form of svm. +

    For this trivial document, this kind of dual entry is redundant and unnecessarily leads the +reader down a trail, first to the list of acronyms and from there the reader then has to go to the +main glossary to look up the description. It’s better to simply include the description in the list of +acronyms. +

    bib2glsIf you want to switch over to bib2gls, first change to glossaries-extra:

    +
    +\usepackage[record,postdot,stylemods,acronym]{glossaries-extra} +
    +
    Next, the definition needs to be converted to the bib format required by bib2gls. If you do: +

    
    +   
    convertgls2bib --preamble-only sample-dual.tex entries.bib +
    +
    +then convertgls2bib will report the following: + + +

    +
    +Overriding default definition of \newdualentry with custom + 
    definition. (Change \newcommand to \providecommand if you want + 
    \newdualentry[options]{label}{short}{long}{description} + 
    converted to @dualabbreviationentry.) +
    +

    This is because convertgls2bib has its own internal definition of \newdualentry, but if it encounters a +new definition that will override its default. If you want to retain convertgls2bib’s definition +(recommended) then just replace \newcommand with \providecommand in the document source and rerun +convertgls2bib. +

    With \providecommand, the new entries.bib file created by convertgls2bib contains:

    +
    +@dualabbreviationentry{svm, +
      short = {SVM}, +
      description = {Statistical pattern recognition technique}, +
      long = {support vector machine} +
    } +
    +
    If \newcommand is retained, it will instead contain:
    +
    +@entry{main-svm, +
      name = {support vector machine}, +
      description = {Statistical pattern recognition technique}, +
      text = {SVM\glsadd{svm}} +
    } +
    +
    @acronym{svm, +
      short = {SVM\glsadd{main-svm}}, +
      long = {support vector machine} +
    } +
    +
    In the first case, bib2gls creates two linked entries using its primary-dual mechanism. In the second case, +bib2gls creates two entries that simply reference each other. +

    Assuming that your entries.bib file just contains @dualabbreviationentry, now replace superheaderborder

    The superheaderborder style is like superheader but has horizontal - and vertical lines around it. -
    +class="cmtt-10">\makeglossaries with:

    +
    super3col
    The super3col style is like super but has three columns. The first column - contains the entry’s name, the second column contains the description and the - third column contains the \GlsXtrLoadResources[src=entries,% entries.bib +
      type=acronym,dual-type=main,dual-prefix={main-}] + + +
    +
    +

    Then remove the definition of \newdualentry and the entry definition. Finally, replace \printglossaries +with \printunsrtglossaries. The document build is: +

    
    +   
    pdflatex sample-dual +
    bib2gls sample-dual +
    pdflatex sample-dual +
    +
    +

    If, instead, your entries.bib file contains separate @entry and @acronym, then you need:

    +
    +\setabbreviationstyle[acronym]{long-short} +
    \GlsXtrLoadResources[src=entries] +
    +
    If you need number list. The entry’s symbol is ignored. The width - of the first column is governed by the widest entry in that column. The width of - the second column is governed by the length \glsdescwidth. The width of the - third column is governed by the length \glspagelistwidth. - - -
    -super3colborder
    The super3colborder style is like the super3col style but has - horizontal and vertical lines around it. -
    + id="dx1-193028">s, the document build is now +

    
    +   
    pdflatex sample-dual +
    bib2gls sample-dual +
    pdflatex sample-dual +
    bib2gls sample-dual +
    pdflatex sample-dual +
    +
    +and this time bib2gls complains about the use of \glsadd within the short and text fields as +this can be problematic. (The extra bib2gls and LATEX calls are to ensure the number list is +up to date for the main-svm entry, which can only be indexed with \glsadd after svm has been +defined.) +

    Dual entries make much more sense when one entry is for a glossary with the description displayed but +no number list, and the other is for the index without the description but with a number list. +This can be created with by replacing @dualabbreviationentry with @dualindexabbreviation: +

    +
    +@dualindexabbreviation{svm, +
      description = {Statistical pattern recognition technique}, +
      short = {SVM}, +
      long = {support vector machine} +
    } +
    +
    This can be mixed with @index terms for example:
    + + +
    +@index{machlearn, +
       name={machine learning} +
    } +
    +
    The document needs modifying:
    +
    super3colheader
    The super3colheader style is like super3col but has a header row. -
    +class="cmtt-10">\documentclass{article} +
    +
    \usepackage[record,postdot, +
     nostyles,stylemods={bookindex,list},% only want bookindex and list styles +
     acronym]{glossaries-extra} +
    +
    \setabbreviationstyle{long-short-desc} +
    \GlsXtrLoadResources[src=entries,% entries.bib +
     dual-type=acronym, +
     label-prefix={idx.},dual-prefix={}, +
     combine-dual-locations={primary}] +
    +
    \glsxtrnewglslike{idx.}{\idx}{\idxpl}{\Idx}{\Idxpl} +
    +
    \begin{document} +
    \gls{svm} and \idx{machlearn}. +
    +
    \printunsrtglossary[type=main,style=altlist] +
    \printunsrtglossary[style=bookindex,title={Index}] +
    \end{document} +
    +
    See the bib2gls manual for further details. + +

    +

    +

    🔗sample-langdict.tex

    +

    This document illustrates how to use the glossaries package to create English to French and French to English +dictionaries. To create the document do: +

    
    +   
    pdflatex sample-langdict +
    makeglossaries sample-langdict +
    pdflatex sample-langdict +
    + + +
    +This example uses the nomain package option to prevent the creation of the main glossary. This means that the +document must provide its own glossaries: + + +

    +
    +\newglossary[glg]{english}{gls}{glo}{English to French} + 
    \newglossary[flg]{french}{flx}{flo}{French to English} +
    +

    This means that if you want to call makeindex explicitly you need to take these new extensions into +account: +

    
    +   
    makeindex -s sample-langdict.ist -t sample-langdict.glg -o sample-langdict.gls sample-langdict.glo +
    makeindex -s sample-langdict.ist -t sample-langdict.flg -o sample-langdict.flx sample-langdict.flo +
    +
    +As with the previous example, this document provides a custom command that defines two related +entries: + + +

    +
    +\newcommand*{\newword}[4]{% + 
      \newglossaryentry{en-#1}{type=english,name={#2},description={#3 #4}}% + 
      \newglossaryentry{fr-#1}{type=french,name={#3 #4},text={#4},sort={#4}, + 
        description={#2}}% + 
    } +
    +

    This has the syntax:

    +
    super3colheaderborder
    The super3colheaderborder style is like the super3colheader - style but has horizontal and vertical lines around it. -
    +class="cmtt-10">\newword{⟨label}{english}{determiner}{french} +
    +
    (Note that this trivial example doesn’t take plurals into account.) This custom command will +define two terms with labels en-label⟩ (for the English term) and fr-label⟩ (for the French term). +So + + +
    +\newword{cat}{cat}{le}{chat} +
    +

    is equivalent to: + + +

    +
    +\newglossaryentry{en-cat}{type=english,name={cat},description={le chat}} + 
    \newglossaryentry{fr-cat}{type=french,name={le chat},sort={chat}, + 
      description={cat}} +
    +

    +

    Unlike the previous example (sample-dual.tex), there’s no link between these two entries. If the document +only uses \gls{en-cat}, then the en-cat entry will appear in the english glossary but the fr-cat entry won’t +appear in the french one. +

    bib2glsIf you want to switch to bib2gls then you first need to convert the document so that it +uses glossaries-extra, but include the prefix option to ensure that glossaries-prefix is also loaded: +

    +
    super4col
    The super4col style is like super3col but has an additional column in which - the entry’s associated symbol appears. This style is designed for entries with brief - single line descriptions. The column widths are governed by the widest entry in - the given column. Use altsuper4col for multi-line descriptions. -
    +class="cmtt-10">\usepackage[record,prefix,postdot,stylemods,nomain]{glossaries-extra} +
    +
    You don’t need to worry about file extensions now, so it’s simpler to use the starred form of \newglossary: +
    +
    super4colborder
    The super4colborder style is like the super4col style but has - horizontal and vertical lines around it. -
    +class="cmtt-10">\newglossary*{english}{English to French} +
    \newglossary*{french}{French to English} +
    +
    Next the entries need to be converted to the bib format required by bib2gls: +

    
    +   
    convertgls2bib --only-preamble sample-langdict.tex entries.bib +
    +
    +This creates the file entries.bib that contains entries defined like:

    +
    +@entry{en-cat, +
      name = {cat}, +
      description = {le chat}, +
      type = {english} +
    } +
    +
    @entry{fr-cat, +
      name = {le chat}, + + +
      description = {cat}, +
      text = {chat}, +
      type = {french} +
    } +
    +
    (Note that the sort field has been omitted.) +

    This would be more flexible, and much briefer, if these entries were defined using bib2gls’s dual entry +system combined with the glossaries-prefix package:

    +
    +@dualentry{cat, +
      name = {chat}, +
      description = {cat}, +
      prefix = {le}, +
      prefixplural = {les} +
    } +
    +
    Similarly for the “chair” entry:
    +
    +@dualentry{chair, +
      name = {chaise}, +
      description = {chair}, +
      prefix = {la}, +
      prefixplural = {les} +
    } +
    +
    +

    With @dualentry, the English and French terms are now automatically linked from bib2gls’s point of view. +If only one is referenced in the document, the other will also be added by default. +

    Now that the determiner has been moved out of the description, it won’t show in the glossary. However, it’s +possible to include it by providing a command to encapsulate the description (which can also apply the language +change as well). +

    +
    +
    +\GlsXtrLoadResources[src=entries,% entries.bib +
     append-prefix-field={space}, +
     category={same as type},dual-category={same as type}, +
     label-prefix={en-},dual-prefix={fr-}, +
     type=english,dual-type=french, +
     sort=en,dual-sort=fr] + + +
    +
    \newcommand{\FrEncap}[1]{% +
     \foreignlanguage{french}{\glsentryprefix{\glscurrententrylabel}#1}} +
    \newcommand{\EnEncap}[1]{\foreignlanguage{english}{#1}} +
    +
    \glssetcategoryattribute{english}{glossnamefont}{EnEncap} +
    \glssetcategoryattribute{english}{glossdescfont}{FrEncap} +
    \glssetcategoryattribute{french}{glossnamefont}{FrEncap} +
    \glssetcategoryattribute{french}{glossdescfont}{EnEncap} +
    +
    +

    Remember to remove \makeglossaries, the definition of \newword and the entry definitions from the +document preamble, and replace \printglossary with:

    +
    +\printunsrtglossary +
    +
    +

    Other refinements that you might like to make include using \glsxtrnewglslike so you don’t have to worry +about the label prefix (“en-” and “fr-”). + +

    +

    +

    🔗sample-index.tex

    +

    This document uses the glossaries package to create both a glossary and an index. This requires two +makeglossaries (or makeglossaries-lite) calls to ensure the document is up to date: +

    
    +   
    pdflatex sample-index +
    makeglossaries sample-index +
    pdflatex sample-index +
    makeglossaries sample-index +
    pdflatex sample-index +
    +
    +

    +

    +

    Top

    19.5 Sorting

    + + + +

    +

    +

    🔗samplePeople.tex

    +

    This document illustrates how you can hook into the standard sort mechanism to adjust the way the sort key is +set. This requires an additional run to ensure the table of contents is up-to-date: +

    
    +   
    pdflatex samplePeople +
    makeglossaries samplePeople +
    pdflatex samplePeople +
    pdflatex samplePeople +
    +
    +This provides two commands for typesetting a name: + + +

    +
    +\newcommand{\sortname}[2]{#2, #1} + 
    \newcommand{\textname}[2]{#1 #2} +
    +

    where the first argument contains the forenames and the second is the surname. The first command is the one +required for sorting the name and the second is the one required for displaying the name in the document. A +synonym is then defined: + + +

    +
    +\let\name\textname +
    +

    This command defaults to the display name command (\textname) but is temporarily redefined to the sort +name command (\sortname) within the sort field assignment hook:

    +
    super4colheader
    The super4colheader style is like super4col but has a header row. -
    +class="cmtt-10">\renewcommand{\glsprestandardsort}[3]{% +
     \let\name\sortname +
     \edef#1{\expandafter\expandonce\expandafter{#1}}% +
     \let\name\textname +
     \glsdosanitizesort +
    } +
    +
    The people are defined using the custom \name command:
    +
    super4colheaderborder
    The super4colheaderborder style is like the super4colheader - style but has horizontal and vertical lines around it. -
    +class="cmtt-10">\newglossaryentry{joebloggs}{name={\name{Joe}{Bloggs}}, +
     description={\nopostdesc}} +
    +
    Since \name is temporarily changed while the sort key is being assigned, the sort value for this entry ends up +as “Bloggs, Joe”, but the name appears in the document as “Joe Bloggs”. +

    bib2glsIf you want to use bib2gls, you first need to convert the document to use glossaries-extra but make +sure you include the record option:

    +
    altsuper4col
    The altsuper4col style is like super4col but allows multi-line descriptions - and page lists. The width of the description column is governed by the length - \glsdescwidth and the width of the page list column is governed by the length - \glspagelistwidth. The width of the name and symbol columns is governed by - the widest entry in the given column. -
    +class="cmtt-10">\usepackage[record,stylemods,style=listgroup]{glossaries-extra} +
    +
    Next it’s necessary to convert the entry definitions to the bib format required by bib2gls. You can simply +do: +

    
    +   
    convertgls2bib --preamble-only samplePeople people.bib +
    +
    +which will create a file called people.bib that contains definitions like:

    + + +
    +@entry{joebloggs, +
      name = {\name{Joe}{Bloggs}}, +
      description = {\nopostdesc} +
    } +
    +
    However, you may prefer to use the --index-conversion (-i) switch: +

    
    +   
    convertgls2bib -i --preamble-only samplePeople people.bib +
    +
    +This will discard the description field and use @index instead of @entry if the description is either empty or +simply set to \nopostdesc or \glsxtrnopostpunc. The people.bib file now contains definitions like: +

    +
    +@index{joebloggs, +
      name = {\name{Joe}{Bloggs}} +
    } +
    +
    Regardless of which approach you used to create the bib file, you now need to edit it to provide a definition of +the custom \name command for bib2gls’s use:
    +
    +@preamble{"\providecommand{\name}[2]{#2, #1}"} +
    +
    Note the use of \providecommand instead of \newcommand. +

    In the document (samplePeople.tex) you now need to delete \makeglossaries, the definitions of +\sortname, \textname, \name, \glsprestandardsort, and all the entry definitions. Then add the following to +the document preamble:

    +
    altsuper4colborder
    The altsuper4colborder style is like the super4colborder style but - allows multi-line descriptions and page lists. -
    +class="cmtt-10">\newcommand{\name}[2]{#1 #2} +
    \GlsXtrLoadResources[src=people] +
    +
    Next, use your text editor’s search and replace function to subsitute all instances of \glsentrytext in the +chapter headings with \glsfmttext. For example:
    +
    altsuper4colheader
    The altsuper4colheader style is like super4colheader but allows - multi-line descriptions and page lists. -
    +class="cmtt-10">\chapter{\glsfmttext{joebloggs}} +
    +
    Finally, replace \printunsrtglossaries with:
    + + +
    +\printunsrtglossaries +
    +
    The document build is now: +

    
    +   
    pdflatex samplePeople +
    bib2gls samplePeople +
    pdflatex samplePeople +
    pdflatex samplePeople +
    +
    +The third LATEX call is required to ensure that the PDF bookmarks are up to date, as the entries +aren’t defined until after the bib2gls run (which is why you have to use \glsfmttext instead of altsuper4colheaderborder
    The altsuper4colheaderborder style is like - super4colheaderborder but allows multi-line descriptions and page lists.
    - - -

    -

    -

    Top

    15.1.6 Supertabular Styles (Ragged Right)

    -

    The styles described in this section are all defined in the package glossary-superragged. These -styles are analogous to those defined in glossary-super but the multiline columns are left -justified instead of fully justified. Since these styles all use the supertabular environment, they -are governed by the same parameters as that environment. The glossary-superragged package -additionally requires the array package. Note that these styles will only be available if you -explicitly load glossary-superragged: - - +class="cmtt-10">\glsentrytext). +

    This again leads to a list sorted by surname. The reason this works is because bib2gls only sees the +definition of \name provided in @preamble, but the document uses the definition of \name provided before +\GlsXtrLoadResources. The use of \providecommand in @preamble prevents \name from being redefined +within the document. +

    See also the “Examples” chapter of the bib2gls user manual, which provides another “people” +example. + +

    -
    -\usepackage{glossaries} - 
    \usepackage{glossary-superragged} +

    🔗sampleSort.tex

    +

    This is another document that illustrates how to hook into the standard sort mechanism. An additional run is +required to ensure the table of contents is up-to-date: +

    
    +   
    pdflatex sampleSort +
    makeglossaries sampleSort +
    pdflatex sampleSort +
    pdflatex sampleSort +
    +
    +This document has three glossaries (main, acronym and a custom notation), so if you want to +use makeindex explicitly you will need to have three makeindex calls with the appropriate file +extensions: +

    
    +   
    pdflatex sampleSort +
    makeindex -s sampleSort.ist -t sampleSort.alg -o sampleSort.acr sampleSort.acn +
    makeindex -s sampleSort.ist -t sampleSort.glg -o sampleSort.gls sampleSort.glo +
    makeindex -s sampleSort.ist -t sampleSort.nlg -o sampleSort.not sampleSort.ntn +
    pdflatex sampleSort + + +
    pdflatex sampleSort +
    +
    +It’s much simpler to just use makeglossaries or makeglossaries-lite. +

    In this example, the sort hook is adjusted to ensure the list of notation is sorted according to the order of +definition. A new counter is defined to keep track of the entry number: + + +

    +
    +\newcounter{sortcount} +
    +

    The sort hook is then redefined to increment this counter and assign the sort key to that numerical +value, but only for the notation glossary. The other two glossaries have their sort keys assigned as +normal: + + +

    +
    +\renewcommand{\glsprestandardsort}[3]{% + 
      \ifdefstring{#2}{notation}% + 
      {% + 
         \stepcounter{sortcount}% + 
         \edef#1{\glssortnumberfmt{\arabic{sortcount}}}% + 
      }% + 
      {% + 
         \glsdosanitizesort + 
      }% + 
    }
    -

    Note that you can’t set these styles using the style package option since the styles aren’t -defined until after the glossaries package has been loaded. -

    -superragged
    The superragged style uses the supertabular environment (defined by the - supertabular package). It has two columns: the first column contains the entry’s - name and the second column contains the (left justified) description followed by - the number list. The entry’s symbol is ignored. Sub groups are separated with a - blank row. The width of the first column is governed by the widest entry in that - column. The width of the second column is governed by the length \glsdescwidth. - Child entries have a similar format to the parent entries except that their name - is suppressed. -
    -superraggedborder
    The superraggedborder style is like superragged but has horizontal - and vertical lines around it. -
    -superraggedheader
    The superraggedheader style is like superragged but has a header - row. -
    +

    This means that makeindex will sort the notation in numerical order. +


    glossaries-extraIf you want to convert this document to use glossaries-extra, a much simpler approach is +available with its hybrid method. First change the package loading line to:

    +
    superraggedheaderborder
    The superraggedheaderborder style is like - superraggedheader but has horizontal and vertical lines around it. -
    +class="cmtt-10">\usepackage[postdot,stylemods,acronym]{glossaries-extra} +
    +
    Either remove \setacronymstyle and replace all instances of \newacronym with \newabbreviation or +replace: + + +
    +\setacronymstyle{long-short} +
    +

    with:

    +
    +\setabbreviationstyle[acronym]{long-short} +
    +
    +

    The custom counter and redefinition of \glsprestandardsort can now be removed. The file extensions for +the custom notation glossary are no longer relevant so the glossary definition can be changed to: +

    +
    superragged3col
    The superragged3col style is like superragged but has three columns. - The first column contains the entry’s name, the second column contains the (left - justified) description and the third column contains the (left justified) number list. - The entry’s symbol is ignored. The width of the first column is governed by the - widest entry in that column. The width of the second column is governed by the - length \glsdescwidth. The width of the third column is governed by the length - \glspagelistwidth. -
    +class="cmtt-10">\newglossary*{notation}{Notation} +
    +
    The \makeglossaries command now needs to be adjusted to indicate which glossaries need to be processed by +makeindex:
    +
    superragged3colborder
    The superragged3colborder style is like the superragged3col - style but has horizontal and vertical lines around it. -
    +class="cmtt-10">\makeglossaries[main,acronym] +
    +
    Finally, \printglossaries needs to be replaced with:
    +
    superragged3colheader
    The superragged3colheader style is like superragged3col but - has a header row. - - -
    +class="cmtt-10">\printglossary +
    \printacronyms +
    \printnoidxglossary[type=notation,sort=def] +
    +
    Note that the notation glossary, which hasn’t been listed in the optional argument of \makeglossaries, must +be displayed with \printnoidxglossary. +

    This means that makeindex only needs to process the main and acronym glossaries. No actual sorting is +performed for the notation glossary because, when used with sort=def, \printnoidxglossary simply iterates +over the list of entries that have been indexed. +

    The document build doesn’t need the third LATEX call now (since none of the glossaries extend beyond a +page break): +

    
    +   
    pdflatex sampleSort +
    makeglossaries sampleSort + + +
    pdflatex sampleSort +
    +
    +This time makeglossaries will include the message: + + +

    +
    +only processing subset 'main,acronym' +
    +

    This means that although makeglossaries has noticed the notation glossary, it will be skipped. +

    If you are explicitly calling makeindex then you need to drop the call for the notation glossary: +

    
    +   
    pdflatex sampleSort +
    makeindex -s sampleSort.ist -t sampleSort.alg -o sampleSort.acr sampleSort.acn +
    makeindex -s sampleSort.ist -t sampleSort.glg -o sampleSort.gls sampleSort.glo +
    pdflatex sampleSort +
    +
    +

    bib2glsIf you prefer to use bib2gls, the package loading line needs to be changed to:

    +
    superragged3colheaderborder
    The - superragged3colheaderborder style is like superragged3colheader but has horizontal - and vertical lines around it. -
    +class="cmtt-10">\usepackage[record,postdot,stylemods,acronym]{glossaries-extra} +
    +
    Next the entry definitions need to be convert to the bib format required by bib2gls. +

    For this example, it’s simpler to split the entries into different files according to the glossary type. This can +be done with the --split-on-type or -t switch: +

    
    +   
    convertgls2bib -t --preamble-only sampleSort.tex entries.bib +
    +
    +This will create three files: +

    altsuperragged4col
    The altsuperragged4col style is like superragged3col but has an - additional column in which the entry’s associated symbol appears. The column - widths for the name and symbol column are governed by the widest entry in the - given column. +class="cmtt-10">entries.bib
    which contains the entries that were defined with \newglossaryentry. For example: +
    +
    + @entry{gls:set, +
      name = set, +
      description = A collection of distinct objects +
    } +
    +
    + +
    altsuperragged4colborder
    The altsuperragged4colborder style is like the - altsuperragged4col style but has horizontal and vertical lines around it. +class="cmtt-10">abbreviations.bib
    which contains the entries that were defined with \newacronym. For example: +
    +
    + @acronym{zfc, +
      short = {ZFC}, +
      long = {Zermelo-Fraenkel set theory} +
    } +
    +
    If you changed \newacronym to \newabbreviation then @abbreviation will be used instead: +
    +
    + @abbreviation{zfc, +
      short = {ZFC}, +
      long = {Zermelo-Fraenkel set theory} +
    } +
    +
    altsuperragged4colheader
    The altsuperragged4colheader style is like - altsuperragged4col but has a header row. -
    +class="cmtt-10">notation.bib
    which contains the entries that were defined with type=notation. For example: +
    +
    + @entry{not:set, +
      name = {$\mathcal{S}$}, +
      description = {A set}, +
      text = {\mathcal{S}} +
    } +
    +
    You may prefer to replace @entry with @symbol in this file.
    +

    After the definition of the notation glossary (\newglossary), add:

    + + +
    altsuperragged4colheaderborder
    The altsuperragged4colheaderborder style is like - altsuperragged4colheader but has horizontal and vertical lines around it. -
    -

    -

    -

    Top

    15.1.7 Tree-Like Styles

    -

    The styles described in this section are all defined in the package glossary-tree. These styles -are designed for hierarchical glossaries but can also be used with glossaries that don’t have -sub-entries. These styles will display the entry’s symbol if it exists. Note that these -styles will automatically be available unless you use the notree or nostyles package -options. -

    These styles all format the entry name using: -


    \glstreenamefmt  \glstreenamefmt{name}

    -

    -This defaults to \textbf{name}, but note that ⟨name⟩ includes \glsnamefont so the -bold setting in \glstreenamefont may be counteracted by another font change in +class="cmtt-10">% abbreviation style must be set first: +
    \setabbreviationstyle[acronym]{long-short} +
    \GlsXtrLoadResources[src={entries,abbreviations}] +
    \GlsXtrLoadResources[src={notation},% notation.bib +
     type=notation,sort=unsrt] +

    +
    Delete the remainder of the preamble (\makeglossaries and entry definitions). +

    Finally, replace the lines that display the glossaries with:

    +
    +\printunsrtglossaries +
    +
    The build process is now: +

    
    +   
    pdflatex sampleSort +
    bib2gls sampleSort +
    pdflatex sampleSort +
    +
    +

    In this case, I have one resource command that processes two glossaries (main and acronym) at the same +time. The entries in these glossaries are ordered alphabetically. The second resource command processes the +notation glossary but the entries in this glossary aren’t sorted (and so will appear in the order of definition +within the bib file). +

    See also sampleNtn.tex, bib2gls gallery: sorting and the bib2gls user manual for more examples. +

    +

    +

    Top

    19.6 Child Entries

    + +

    +

    +

    🔗sample.tex

    +

    This document illustrates some of the basics, including how to create child entries that use the same name as +the parent entry. This example adds the glossary to the table of contents and it also uses \glsrefentry, so an +extra LATEX run is required: +

    
    +   
    pdflatex sample +
    makeglossaries sample +
    pdflatex sample + + +
    pdflatex sample +
    +
    +You can see the difference between word and letter ordering if you add the package option order=letter. (Note +that this will only have an effect if you use makeglossaries or makeglossaries-lite. If you use makeindex +explicitly, you will need to use the -l switch to indicate letter ordering.) +

    One of the entries has its name encapsulated with a semantic command:

    +
    \glsnamefont (or in \acronymfont). The tree-like styles that also display the header -use -


    \glstreegroupheaderfmt  \glstreegroupheaderfmt{text}

    -

    -to format the heading. This defaults to \glstreenamefmt{text}. The tree-like styles that -display navigation links to the groups (such as indexhypergroup), format the navigation line -using -


    \glstreenavigationfmt  \glstreenavigationfmt{text}

    - - -

    -which defaults to \glstreenamefmt{text}. Note that this is different from +class="cmtt-10">\newcommand{\scriptlang}[1]{\textsf{#1}} +
    +
    \newglossaryentry{Perl}{name=\scriptlang{Perl},sort=Perl, +
    description={A scripting language}} +

    +
    This means that this entry needs to have the sort key set otherwise makeindex will assign it +to the “symbol” letter group, since it starts with a backslash (which makeindex simply treats as +punctuation). +

    The homograph entries “glossary” and “bravo” are defined as sub-entries that inherit the name from the +parent entry. The parent entry doesn’t have a description, but with the default nopostdot=false setting this will +lead to a spurious dot. This can be removed by adding \nopostdesc to the description, which suppresses the +post-description hook for that entry. +

    Since the child entries have the same name as the parent, this means that the child entries will have +duplicate sort values unless the default is changed with the sort key:

    +
    \glslistnavigationitem, provided with the styles such as listhypergroup, as that also -includes \item. -

    With the exception of the alttree style (and those derived from it), the space before the -description for top-level entries is produced with -


    \glstreepredesc  \glstreepredesc

    -

    -This defaults to \space. -

    With the exception of the treenoname and alttree styles (and those derived from them), -the space before the description for child entries is produced with -


    \glstreechildpredesc  \glstreechildpredesc

    -

    -This defaults to \space. -

    Most of these styles are not designed for multi-paragraph descriptions. (The tree style -isn’t too bad for multi-paragraph top-level entry descriptions, or you can use the index style -with the adjustment shown below.)
    -

    -

    +class="cmtt-10">\newglossaryentry{glossary}{name=glossary, +
     description={\nopostdesc},plural={glossaries}} +
    +
    \newglossaryentry{glossarycol}{ +
     description={collection of glosses}, +
     sort={2}, +
     parent={glossary}% parent label +
    } +
    +
    \newglossaryentry{glossarylist}{ +
     description={list of technical words}, +
     sort={1}, +
     parent={glossary}% parent label +
    } +
    +
    (Remember that the entries are sorted hierarchically.) This will place glossarylist before glossarycol, but +both will come immediately after their parent glossary entry. +


    glossaries-extraIf you switch to using glossaries-extra, remember that the default package options are different: +

    + + +
    index
    The index style is similar to the way indices are usually formatted in that it has - a hierarchical structure up to three levels (the main level plus two sub-levels). The - name is typeset in bold, and if the symbol is present it is set in parentheses after - the name and before the description. Sub-entries are indented and also include - the name, the symbol in brackets (if present) and the description. Groups are - separated using \indexspace. -

    Each main level item is started with -


    \glstreeitem  \glstreeitem

    -

    - The level 1 entries are started with -


    \glstreesubitem  \glstreesubitem

    -

    -

    The level 2 entries are started with -


    \glstreesubsubitem  \glstreesubsubitem

    -

    -

    Note that the index style automatically sets - - +class="cmtt-10">\usepackage[postdot,stylemods,style=treenonamegroup,order=word, +
      subentrycounter]{glossaries-extra} +

    +
    +

    You may now want to consider replacing \nopostdesc in the descriptions with \glsxtrnopostpunc (using +your text editor’s search and replace function). This suppresses the post-description punctuation but not the +category post-description hook. +

    You may have noticed that some of the descriptions include the plural form, but it’s not done very +consistently. For example: + + +

    +
    +\newglossaryentry{cow}{name=cow, + 
      plural=cows,% not required as this is the default + 
      user1=kine, + 
      description={(\emph{pl.}\ cows, \emph{archaic} kine) an adult + 
    female of any bovine animal} + 
    } +
    +

    which has the parenthetical material at the start of the description with emphasis, + +

    -
    - \let\item\glstreeitem -  
    \let\subitem\glstreesubitem -  
    \let\subsubitem\glstreesubsubitem +
    +\newglossaryentry{bravocry}{ + 
      description={cry of approval (pl.\ bravos)}, + 
      sort={1}, + 
      parent={bravo} + 
    }
    -

    at the start of the glossary for backward compatibility. -

    The index style isn’t suitable for multi-paragraph descriptions, but this limitation can be - overcome by redefining the above commands. For example: - - +

    which has the parenthetical material at the end of the description without emphasis even though it’s a regular +plural, + +

    -
    - \renewcommand{\glstreeitem}{% -  
     \parindent0pt\par\hangindent40pt -  
     \everypar{\parindent50pt\hangindent40pt}} +
    +\newglossaryentry{bravoruffian}{ + 
      description={hired ruffian or killer (pl.\ bravoes)}, + 
      sort={2}, + 
      plural={bravoes}, + 
      parent=bravo} +
    +

    which has the parenthetical material at the end of the description without emphasis, and + + +

    +
    +\newglossaryentry{glossary}{name=glossary, + 
      description={\nopostdesc}, + 
      plural={glossaries}} +
    +

    which doesn’t show the plural in the description. +

    With glossaries-extra, you can remove this parenthetical material and implement it using the category +post-description hook instead. For example, the above definitions become: + + +

    +
    +\newglossaryentry{cow}{name=cow, + 
      user1=kine, + 
      description={an adult female of any bovine animal} + 
    } + 
    \newglossaryentry{bravocry}{ + 
      description={cry of approval}, + 
      sort={1}, + 
      parent={bravo} + 
    } + 
    \newglossaryentry{bravoruffian}{ + 
      description={hired ruffian or killer}, + 
      sort={2}, + 
      plural={bravoes}, + 
      parent=bravo} +
    +

    +
    +\newglossaryentry{glossary}{name=glossary, +
      description={\glsxtrnopostpunc}, +
      plural={glossaries}} +
    +
    The post-description hook for the general category can now be set:
    +
    +\glsdefpostdesc{general}{% +
    % Has the user1 key been set? +
      \glsxtrifhasfield{useri}{\glscurrententrylabel}% +
      {\space(\emph{pl.}\ \glsentryplural{\glscurrententrylabel}, +
        \emph{archaic} \glscurrentfieldvalue)% +
      }% +
      {% +
    % The user1 key hasnflt been set. Is the plural the same as the +
    % singular form with the plural suffix appended? +
        \GlsXtrIfXpFieldEqXpStr{plural}{\glscurrententrylabel}% +
        {\glsentrytext{\glscurrententrylabel}\glspluralsuffix}% +
        {% +
    % Sibling check with bib2gls (see below) +
        }% + + +
        {% +
    % The plural isnflt the default. Does this entry have a parent? +
          \ifglshasparent{\glscurrententrylabel}% +
          {% +
    % This entry has a parent. +
    % Are the plurals for the child and parent the same? +
            \GlsXtrIfXpFieldEqXpStr{plural}{\glscurrententrylabel}% +
            {\glsentryplural{\glsentryparent{\glscurrententrylabel}}}% +
            {}% child and parent plurals the same +
            {% +
              \space(\emph{pl.}\ \glsentryplural{\glscurrententrylabel})% +
            }% +
          }% +
          {\space(\emph{pl.}\ \glsentryplural{\glscurrententrylabel})}% +
        }% +
      }% +
    } +
    +
    (If you try this example out, notice the difference for the glossary entry if you use \nopostdesc and then +replace it with \glsxtrnopostpunc.) See the glossaries-extra user manual for further details and also +glossaries-extra and bib2gls: An Introductory Guide. +

    The “bravo” homographs are an oddity where the singular form is identical but the plural is different +(“bravos” and “bravoes”). In the original, both descriptions included the plural term. The above modifications +drop the display of the regular “bravos” plural (for the bravocry term) and only show the “bravoes” plural (for +the bravoruffian term). In this particular case it might be useful to show the regular plural in order to +highlight the difference. +

    While it’s straightforward to access an entry’s parent label (with \glsentryparent) it’s much harder to +access entry’s children or siblings. The \ifglshaschildren command has to iterate over all entries to determine +if any have a parent that matches the given label. This is obviously very time-consuming if you have a large +database of entries. It also doesn’t provide a way of determining whether or not the child entries have been +indexed. +

    With bib2gls, it’s possible to save this information with the save-child-count and save-sibling-count, +which not only save the total but also save the child or sibling labels in an etoolbox internal list. This makes the +information much faster to access and also only includes the labels of those entries that have actually been +indexed. +

    In the above, the comment line:

    +
    +% Sibling check with bib2gls (see below)
    -

    -

    +
    indicates where to put the extra code. If you switch to bib2gls and make sure to use save-sibling-count +then you can insert the following code in the block above where that comment is:
    + + +
    +\GlsXtrIfFieldNonZero{siblingcount}{\glscurrententrylabel}% +
    {% siblingcount field value non-zero +
     \glsxtrfieldforlistloop % iterate over internal list +
     {\glscurrententrylabel}% entry label +
     {siblinglist}% label of field containing list +
     {\siblinghandler}% loop handler +
    }% +
    {}% siblingcount field value 0 or empty or missing +
    +
    This uses a custom handler that’s defined as follows:
    +
    indexgroup
    The indexgroup style is similar to the index style except that each group has a - heading obtained using \glsgetgrouptitle{label}, which is described in §15.2 Defining - your own glossary style. -
    +class="cmtt-10">\newcommand{\siblinghandler}[1]{% +
      \GlsXtrIfXpFieldEqXpStr*{plural}{\glscurrententrylabel}% +
      {\glsentryplural{#1}}% +
      {}% current entryfls plural same as siblingfls plural +
      {% +
        \space(\emph{pl.}\ \glsentryplural{\glscurrententrylabel})% +
        \listbreak +
      }% +
    } +
    +
    The \listbreak command is provided by etoolbox and is used for prematurely exiting a loop. The handler +tests if the sibling’s plural field is identical to the current entry’s plural field. If they are the +same, it does nothing. If they are different, it displays the current entry’s plural and breaks the +loop. +

    Note that this assumes that the parent entry hasn’t had the plural form explicitly set to “bravoes” instead of +the default “bravos”. In that case, the parent entry would show the plural but the bravoruffian child entry +wouldn’t show the plural (since this case would led to the empty code block identified with the comment “child +and parent plurals the same”). The “bravoes” plural form would instead be shown for the parent, which +wouldn’t look right. +

    If you don’t use bib2gls or if you use it without the save-sibling-count resource option then the sibling +information won’t be available. +

    bib2glsIn order to switch to using bib2gls, it’s first necessary to switch to using glossaries-extra (as above). +Remember that the record option is required:

    +
    indexhypergroup
    The indexhypergroup style is like indexgroup but has a set of links to the - glossary groups. The navigation line is the same as that for listhypergroup, described - above, but is formatted using \glstreenavigationfmt. -
    +class="cmtt-10">\usepackage[record,postdot,stylemods,style=treenonamegroup, +
    subentrycounter]{glossaries-extra} +
    +
    Next the entry definitions need to be converted to the bib format required by bib2gls. This can be done with +convertgls2bib:
    + + +
    tree
    The tree style is similar to the index style except that it can have arbitrary levels. (Note - that makeindex is limited to three levels, so you will need to use convertgls2bib --preamble-only sample.tex entries. +
    +
    The semantic command may be moved to the bib file to ensure it’s defined:
    +
    +@preamble{"\providecommand{\scriptlang}[1]{\textsf{#1}}"} +
    +
    +

    The sort field typically shouldn’t be set when using bib2gls, so convertgls2bib strips it. If the sort field +is missing, bib2gls will obtain it from the sort fallback for that entry type. In this case, @entry has the name +field as the sort fallback. If this is also missing then its value is obtained from the parent’s name field (see +bib2gls gallery: sorting for other examples). +

    Therefore the “Perl” entry is simply defined as:

    +
    +@entry{Perl, +
      name = {\scriptlang{Perl}}, +
      description = {A scripting language} +
    } +
    +
    This isn’t a problem for bib2gls. In this case, the command has been provided in the @preamble, but bib2gls +strips font information so the sort value becomes Perl. If the definition isn’t placed in @preamble then +bib2gls will simply ignore the command (as xindy if you want - more than three levels.) Each sub-level is indented by \glstreeindent \glstreeindent. - Note that the name, symbol (if present) and description are placed in the same - paragraph block. If you want the name to be apart from the description, use the alttree - style instead. (See below.) -
    -treegroup
    The treegroup style is similar to the tree style except that each group has a - heading. -
    -treehypergroup
    The treehypergroup style is like treegroup but has a set of links to the - glossary groups. The navigation line is the same as that for listhypergroup, described - above, but is formatted using \glstreenavigationfmt. -
    -treenoname
    The treenoname style is like the tree style except that the name for each - sub-entry is ignored. -
    + id="dx1-200077"> does) so the sort value will still end up as treenonamegroup
    The Perl. +

    The homograph entries have also had their sort fields omitted:

    +
    +@entry{glossarycol, +
      parent = {glossary}, +
      description = {collection of glosses} +
    } +
    +
    @entry{glossarylist, +
      parent = {glossary}, +
      description = {list of technical words} +
    } +
    +
    + + +

    This means that the sort value for both these child entries is “glossary”. When bib2gls encounters identical +sort values it acts according to its identical-sort-action setting. The default action is to sort by the label +using a simple string comparison. In this case, it would put glossarycol before glossarylist. In the original +document, the sort value was manually chosen to ensure that the entries are ordered according to first use. +This ordering can easily be obtained by changing bib2gls’s identical sort action (requires at least bib2gls +v2.0):

    +
    +\GlsXtrLoadResources[src={entries},identical-sort-action=use] +
    +
    This command should replace \makeglossaries. If you want the sibling information (see earlier), then you +need to remember to add save-sibling-count to the list of options. +

    Note that this is a better solution than in the original example. If I edit the document so that glossarycol +is used first, then the ordering will be updated accordingly, but with the original example, the sort keys would +need to be manually changed. +

    The remainder of the preamble (that is, the definition of \scriptlang and all the entry definitions) should +now be removed. +

    Finally, replace \printglossaries with \printunsrtglossaries. The document build is now: +

    
    +   
    pdflatex sample +
    bib2gls --group sample +
    pdflatex sample +
    pdflatex sample +
    +
    +Note use of the --group (or -g) switch, which is needed to support the treenonamegroup style is similar to the treenoname style except that - each group has a heading. -
    + id="dx1-200093"> style. The third +LATEX call is needed because the document contains \glsrefentry. +

    Note that you can’t use the order=letter package option with bib2gls. Instead use the break-at=none +resource option:

    +
    +\GlsXtrLoadResources[src={entries},identical-sort-action=use, +
      break-at=none +
    ] +
    +
    + +

    +

    +

    🔗sample-inline.tex

    +

    This document is like sample.tex, above, but uses the inline glossary style to put the glossary in a footnote. +The document build is: + + +

    
    +   
    pdflatex sample-inline +
    makeglossaries sample-inline +
    pdflatex sample-inline +
    pdflatex sample-inline +
    +
    +If you want to convert this document to glossaries-extra, follow the same procedure as above. If you want to use +bib2gls then you don’t need the --group switch since no letter groups are required. + +

    +

    +

    🔗sampletree.tex

    +

    This document illustrates a hierarchical glossary structure where child entries have different names to their +corresponding parent entry. To create the document do: +

    
    +   
    pdflatex sampletree +
    makeglossaries sampletree +
    pdflatex sampletree +
    +
    +The document uses the alttreehypergroup glossary style, which needs to know the widest name for each +hierarchical level. This has been assigned manually in the preamble with \glssetwidest: + + +

    +
    +\glssetwidest{Roman letters} % level 0 widest name + 
    \glssetwidest[1]{Sigma}      % level 1 widest name +
    +

    (Level 0 is the top-most level. That is, entries that don’t have a parent.) It’s possible to get glossaries to +compute the widest top-level entry with \glsfindwidesttoplevelname but this will iterate over all top-level +entries, regardless of whether or not they appear in the glossary. If you have a large database of entries, this will +firstly take time and secondly the width may be too large due to an unindexed entry with a big +name. +

    This sample document doesn’t require any of the tabular styles so I’ve prevented those packages from being +loaded with nolong and nosuper. The reduces the overall package loading.

    +
    treenonamehypergroup
    The treenonamehypergroup style is like treenonamegroup but has a - set of links to the glossary groups. The navigation line is the same as that for - listhypergroup, described above, but is formatted using \glstreenavigationfmt. - - -
    +class="cmtt-10">\usepackage[style=alttreehypergroup,nolong,nosuper] +
    {glossaries} +
    +
    (This example glossary is actually better suited for one of the topic styles provided with glossary-topic, see +below.) +

    This is obviously a contrived example since it’s strange to have the symbol names (such as “Sigma”) in the +glossary. The purpose is to demonstrate the alttreehypergroup with an entry that’s noticeably wider than the +others in the same hierarchical level. A more sensible document would have the symbol in the name +key. +


    glossaries-extraIf you want to switch to glossaries-extra, then you can instead use a combination of nostyles +and stylemods:

    +
    alttree
    The alttree style is similar to the tree style except that the indentation for each level - is determined by the width of the text specified by -


    \glssetwidest  \glssetwidest[level]{text}

    -

    - The optional argument ⟨level⟩ indicates the level, where 0 indicates the top-most level, 1 - indicates the first level sub-entries, etc. If \glssetwidest hasn’t been used for a - given sub-level, the level 0 widest text is used instead. If ⟨level⟩ is omitted, 0 is - assumed. -

    As from v4.22, the \usepackage[style=alttreehypergroup,postdot,nostyles, +
    stylemods=tree
    ]{glossaries-extra} +

    +
    The stylemods package not only patches the original styles provided by the base glossaries package (such +as glossary-tree package also provides -


    \glsfindwidesttoplevelname  \glsfindwidesttoplevelname[glossary list] -

    -

    - This iterates over all parentless entries in the given glossary lists and determines the - widest entry. If the optional argument is omitted, all glossaries are assumed (as per - \forallglossaries). -

    For example, to have the same name width for all glossaries: - - + id="dx1-202012"> used in this example) but also provides extra helper commands. In this case, it +provides additional commands to calculate the widest name. For example, instead of manually +setting the widest entry with \glssetwidest, you could add the following before the glossary: +

    +
    +\glsFindWidestUsedTopLevelName +
    \glsFindWidestUsedLevelTwo + + +
    +
    This will only take into account the entries that have actually been used in the document, but it can still be +time-consuming if you have a large number of entries. +

    Note that the glossary must be at the end of the document (after all required entries have been used) with +this method. The alternative is to perform the calculation at the end of the document and save the results in the +aux file for the next run.
    +

    +

    This example document is using top-level entries for topics without descriptions. This means that the +descriptions simply contain \nopostdesc to prevent the post-description punctuation from being automatically +inserted. For example: + +

    -
    - \glsfindwidesttoplevelname -  
    \setglossarystyle{alttree} -  
    \printglossaries +
    +\newglossaryentry{greekletter}{name={Greek letters}, + 
    text={Greek letter}, + 
    description={\nopostdesc}} +
    +

    With glossaries-extra, you can convert this to \glsxtrnopostpunc which will prevent the post-description +punctuation without interfering with the category post-description hook. +

    In order to distinguish between the child entries, which are symbols, and the parent entries, which are topics, +it’s useful to give these two different types of entries different categories. The topics can use the default general +category, but the symbol entries can be assigned to a different category. The value of the category key must be +a label. For example:

    +
    +\newglossaryentry{C}{name={C}, +
    description={Euler's constant}, +
    category=symbol, +
    parent=romanletter} +
    +
    +

    There is some redundancy caused by a parenthetical note after the first use in some of the symbol entries. +For example: + + +

    +
    +\newglossaryentry{pi}{name={pi}, + 
    text={\ensuremath{\pi}}, + 
    first={\ensuremath{\pi} (lowercase pi)}, + 
    description={Transcendental number}, + 
    parent=greekletter} +
    +

    With glossaries-extra this can be dealt with through the category post-link hook:

    +
    +\glsdefpostlink{symbol}{% +
      \glsxtrifwasfirstuse +
      {% first use +
        \glsxtrifhasfield{useri}{\glslabel}% +
        { (\glscurrentfieldvalue)}{}% +
      }% +
      {}% not first use +
    }
    -

    Alternatively, to compute the widest entry for each glossary before it’s displayed: - - -

    -
    - \renewcommand{\glossarypreamble}{% -  
      \glsfindwidesttoplevelname[\currentglossary]} -  
    \setglossarystyle{alttree} -  
    \printglossaries +
    The parenthetical material is now stored in the user1 key. For example:
    +
    +\newglossaryentry{sigma}{name=Sigma, +
    text={\ensuremath\Sigma}, +
    user1={uppercase sigma}, +
    description={Used to indicate summation}, +
    parent=greekletter}
    -

    -

    These commands only affects the alttree styles, including those listed below and the - ones in the glossary-mcols package. If you forget to set the widest entry name, the - description will overwrite the name.
    -

    -

    For each level, the name is placed to the left of the paragraph block containing the - symbol (optional) and the description. If the symbol is present, it is placed in - parentheses before the description. -

    The name is placed inside a left-aligned \makebox. As from v4.19, this can now be - adjusted by redefining -


    \glstreenamebox  \glstreenamebox{width}{text}

    -

    - where ⟨width⟩ is the width of the box and ⟨text⟩ is the contents of the box. For example, to - make the name right-aligned: - - -

    -
    - \renewcommand*{\glstreenamebox}[2]{% -  
      \makebox[#1][r]{#2}% -  
    } +
    The category post-description link is also set to ensure that the symbol is displayed after the description in the +glossary:
    +
    +\glsdefpostdesc{symbol}{\space +
      ($\glsentrytext{\glscurrententrylabel}$)} +
    +
    These modifications only affect entries with the category set to symbol. +

    With glossaries-extra, it’s now possible to use the topic styles provided with the glossary-topic package: +

    + + +
    +\usepackage[style=topic,postdot,nostyles,stylemods={tree,topic}] +
    {glossaries-extra}
    -

    -

    +
    The topic style is designed for this kind of hierarchy where all the top-level entries don’t have descriptions. This +means that the \nopostdot and \glsxtrnopostpunc commands aren’t required. The top-level entries can +simply be defined as:
    +
    alttreegroup
    The alttreegroup is like the \newglossaryentry{greekletter}{name={Greek letters}, +
    text={Greek letter}, description={}} +
    +
    \newglossaryentry{romanletter}{name={Roman letters}, +
    text={Roman letter}, description={}} +
    +
    I’ve now loaded both the glossary-tree and glossary-topic packages (via stylemods={tree,topic}). The +glossary-topic package can be used without glossary-tree, in which case it will behave more like the normal tree +rather than alttree style except that each group has a - heading. -
    -alttreehypergroup
    The alttreehypergroup style is like alttreegroup but has a set of links to - the glossary groups. The navigation line is the same as that for listhypergroup, described - above. -
    -

    -

    -

    Top

    15.1.8 Multicols Style

    -

    The glossary-mcols package provides tree-like styles that are in the multicols environment -(defined by the multicol package). The style names are as their analogous tree styles (as -defined in §15.1.7 Tree-Like Styles) but are prefixed with “mcol”. For example, the mcolindex -style is essentially the index style but put in a multicols environment. For the complete list, see -table 15.2. The styles (but with different indentation and no description in the top-level). However, +if you use \glssetwidest (provided by glossary-tree package is automatically loaded by glossary-mcols (even if the + id="dx1-202044">) then the topic style will behave more like notree package option is used when loading glossaries). The formatting commands +class="cmss-10">alttree. +

    Since there’s no description for the top-level entries, the topic style ignores the widest name setting for the +top-level, so I can just have the level 1 setting: + + +

    +
    +\glssetwidest[1]{Sigma} +
    +

    +

    bib2glsIf you want to convert this document so that it uses bib2gls, you first need to convert it +to using glossaries-extra, as described above, but remember that you now need the record option. +

    +
    \glstreenamefmt, \glstreegroupheaderfmt and \glstreenavigationfmt are all used by -the corresponding glossary-mcols styles. -

    Note that glossary-mcols is not loaded by glossaries. If you want to use any of the multicol -styles in that package you need to load it explicitly with \usepackage and set the required -glossary style using \setglossarystyle.
    -

    -

    The default number of columns is 2, but can be changed by redefining -


    \glsmcols  \glsmcols

    -

    -to the required number. For example, for a three column glossary: - - -

    -
    -\usepackage{glossary-mcols} - 
    \renewcommand*{\glsmcols}{3} - 
    \setglossarystyle{mcolindex} +class="cmtt-10">\usepackage[record,style=topic,postdot,nostyles,stylemods={tree,topic}] +
    {glossaries-extra}
    -

    -

    -
    - - -


    - - -
    Table 15.2: Multicolumn Styles
    -
    - - - - - - - - - -
    glossary-mcols Style Analogous Tree Style
    mcolindex index
    mcolindexgroup indexgroup
    mcolindexhypergroup or mcolindexspannav indexhypergroup
    mcoltree tree
    mcoltreegroup treegroup
    mcoltreehypergroup or mcoltreespannav treehypergroup
    mcoltreenoname treenoname
    mcoltreenonamegroup treenonamegroup
    mcoltreenonamehypergroup or mcoltreenonamespannav treenonamehypergroup
    mcolalttree alttree
    mcolalttreegroup alttreegroup
    mcolalttreehypergroup or mcolalttreespannav alttreehypergroup
    - - -

    -
    -

    The styles with a navigation line, such as mcoltreehypergroup, now have a variant (as from -v4.22) with “hypergroup” replaced with “spannav” in the style name. The original -“hypergroup” styles place the navigation line at the start of the first column. The newer -“spannav” styles put the navigation line in the optional argument of the multicols -environment so that it spans across all the columns. +

    Next convert the entries to the bib format required by bib2gls: +

    
    +   
    convertgls2bib --preamble-only sampletree.tex entries.bib +
    +
    +Now replace \makeglossaries with:

    +
    +\GlsXtrLoadResources[src=entries,set-widest] +
    +
    I’ve used the set-widest option here to get bib2gls to compute the widest name. (Obviously, it can only do +this if it can correctly interpret any commands contained in the name field.) +

    This means that the \glssetwidest commands can now be removed completely. All the \newglossaryentry +commands also need to be removed from the preamble. Finally, \printunsrtglossaries needs to be replaced +with \printunsrtglossaries. The document build is now: +

    
    +   
    pdflatex sampletree +
    bib2gls sampletree +
    pdflatex sampletree +
    +
    +

    This produces the same result as with just glossaries-extra and makeglossaries. However, there are some +modifications that can be made to the bib file to make it neater. +

    The top-level entries are defined as:

    + + +
    +@entry{greekletter, +
      name = {Greek letters}, +
      description = {}, +
      text = {Greek letter} +
    } +
    +
    @entry{romanletter, +
      name = {Roman letters}, +
      description = {}, +
      text = {Roman letter} +
    } +
    +
    This is a direct translation from the \newglossaryentry commands (after switching to the topic style). There’s +a more appropriate entry type:
    +
    +@indexplural{greekletter, +
      text = {Greek letter} +
    } +
    +
    @indexplural{romanletter, +
      text = {Roman letter} +
    } +
    +
    The @indexplural entry type doesn’t require the description and will set the name field to the same as the +plural field. Since the plural field hasn’t been set it’s obtained by appending “s” to the text +field. +

    Now let’s assume that the symbol entries are defined in a more rational manner, with the actual symbol in +the name field. For example:

    +
    +@entry{sigma, +
      user1 = {uppercase sigma}, +
      parent = {greekletter}, +
      description = {Used to indicate summation}, +
      name = {\ensuremath{\Sigma}}, +
      category = {symbol} +
    } +
    +
    @entry{C, +
      parent = {romanletter}, +
      name = {\ensuremath{C}}, +
      description = {Euler's constant}, + + +
      category = {symbol} +
    } +
    +
    The category post-description hook (provided with \glsdefpostdesc) should now be removed from the +document. +

    If you make these changes and rebuild the document, you’ll find that the order has changed. Now the sigma +entry is before the pi entry. This is because bib2gls is obtaining the sort values from the name field, +which is the sort fallback for @entry. This means that the sort values end up as Σ and π (bib2gls +recognises the commands \Sigma and \pi and converts them to the Unicode characters 0x1D6F4 and +0x1D70B). +

    If you change @entry to @symbol then you will once again get the order from the original example (pi before +Sigma). This is because the sort fallback for @symbol is the label not the name. (Remember that the sort +fallback is only used if the sort field isn’t set. If you explicitly set the sort field then no fallback is required. See +bib2gls gallery: sorting.) +

    You can further tidy the bib file by removing the category fields. For example:

    +
    +@symbol{sigma, +
      user1 = {uppercase sigma}, +
      parent = {greekletter}, +
      description = {Used to indicate summation}, +
      name = {\ensuremath{\Sigma}} +
    } +
    +
    You can then assign the category in the resource set:
    +
    +\GlsXtrLoadResources[src=entries,set-widest,category={same as entry}] +
    +
    This means that all the entries defined with @symbol will have the category set to symbol and all the entries +defined with @indexplural will have the category set to indexplural. (Only the symbol category is significant +in this example.) +

    You can make the bib files even more flexible by introducing field and entry aliases with field-aliases and +entry-type-aliases. See the bib2gls manual for further details. +

    -

    Top

    15.1.9 In-Line Style

    -

    This section covers the glossary-inline package that supplies the inline style. This is a style that -is designed for in-line use (as opposed to block styles, such as lists or tables). This style -doesn’t display the

    Top

    19.7 Cross-Referencing

    + + + +

    +

    +

    🔗sample-crossref.tex

    +

    This document illustrates how to cross-reference entries in the glossary. +

    
    +   
    pdflatex sample-crossref +
    makeglossaries sample-crossref +
    pdflatex sample-crossref +
    +
    +The document provides a command \alsoname to produce some fixed text, which can be changed as +appropriate (usually within a language hook): + + +

    +
    +\providecommand{\alsoname}{see also} +
    +

    I’ve used \providecommand as some packages define this command. This is used to create a “see also” +cross-reference with the see key: + + +

    +
    +\newglossaryentry{apple}{name=apple,description={firm, round fruit}, + 
    see=[\alsoname]{pear}} + 
    \newglossaryentry{marrow}{name={marrow}, + 
     description={long vegetable with thin green skin and white flesh}, + 
     see={[\alsoname]courgette}} +
    +

    +

    Note that “marrow” is included in the glossary even though it hasn’t been referenced in the text. This is +because the see key automatically triggers \glssee which indexes the term. This behaviour is intended for +documents where only the terms that are actually required in the document are defined. It’s not +suitable for a large database of terms shared across multiple documents that may or may not be +used in a particular document. In that case, you may want to consider using glossaries-extra (see +below). +


    glossaries-extraThis example is quite simple to convert to glossaries-extra. If you want the dot after the +description, you need the nopostdot=false or postdot package option. You may also want to consider using the +stylemods option. +

    In order to prevent the “marrow” entry from being automatically being added to the glossary as a result of +the cross-reference, you can use autoseeindex=false to prevent the automatic indexing triggered by the see key +(or the seealso key provided by glossaries-extra). +

    +
    +
    +\usepackage[autoseeindex=false,postdot,stylemods]{glossaries-extra} +
    +
    The document build is the same, but now the “marrow” and “zucchini” entries aren’t present in the +document. +

    Note that the “fruit” entry is still included even though it hasn’t been used in the document. This is because +it was explicitly indexed with \glssee not via the see key. +

    The entries that contains see=[\alsoname] can be converted to use the seealso key:

    +
    +\newglossaryentry{apple}{name=apple,description={firm, round fruit}, +
    seealso={pear}} +
    +
    \newglossaryentry{marrow}{name={marrow}, +
     description={long vegetable with thin green skin and white flesh}, +
     seealso={courgette}} + + +
    +
    (The provided \alsoname definition may be removed.) +

    The original example redefines the cross-referencing format to use small caps:

    +
    +\renewcommand{\glsseeitemformat}[1]{\textsc{\glsentryname{#1}}} +
    +
    This will still produce the desired effect with glossaries-extra for this simple example but, as with +sampleAcrDesc.tex, this redefinition isn’t necessary if you have at least glossaries-extra v1.42. +

    bib2glsIf you want to switch to bib2gls then you first need to switch to glossaries-extra, as +described above, but you now need the record option but no longer need the autoseeindex=false option: +

    +
    +\usepackage[record,postdot,stylemods]{glossaries-extra} +
    +
    Next the entry definitions need to be converted to the bib format required by bib2gls. +

    
    +   
    convertgls2bib sample-crossref.tex entries.bib +
    +
    +If you have at least v2.0 then convertgls2bib will absorb the cross-referencing information supplied +by: + + +

    +
    +\glssee{fruit}{pear,apple,banana} +
    +

    into the fruit definition:

    +
    +@entry{fruit, +
      see = {pear,apple,banana}, +
      name = {fruit}, +
      description = {sweet, fleshy product of plant containing seed} +
    } +
    +
    Now remove \makeglossaries and all the entry definition commands (including \glssee from the preamble) +and add:
    +
    +\GlsXtrLoadResources[src=entries.bib] +
    +
    Finally, replace \printglossaries with \printunsrtglossaries. The document build is now: +

    
    +   
    pdflatex sample-crossref +
    bib2gls sample-crossref +
    pdflatex sample-crossref +
    +
    +The glossary now contains: apple, banana, courgette and pear. Note that it doesn’t contain fruit, zucchini or +marrow. +

    Now change the selection criteria:

    +
    +\GlsXtrLoadResources[src=entries.bib, +
     selection={recorded and deps and see}] +
    +
    The glossary now includes fruit, zucchini and marrow. +

    The fruit and zucchini use the see key which is a simple redirection for the reader. There’s no number list. -

    You will most likely need to redefine \glossarysection with this style. For example, -suppose you are required to have your glossaries and list of acronyms in a footnote, you can -do: - - + id="dx1-204031"> +for either of these entries. Whereas marrow uses the seealso key, which is typically intended as a +supplement to a number list but in this case there are no locations as marrow hasn’t been used in the +text. +

    With at least v2.0, there’s an alternative:

    + + +
    +\GlsXtrLoadResources[src=entries.bib, +
     selection={recorded and deps and see not also}] +
    +
    In this case, the glossary includes fruit and zucchini but not marrow. +

    +

    +

    Top

    19.8 Custom Keys

    + +

    -
    - \usepackage{glossary-inline} - 
     \renewcommand*{\glossarysection}[2][]{\textbf{#1}: } - 
     \setglossarystyle{inline} +

    🔗sample-newkeys.tex

    +

    This document illustrates how add custom keys (using \glsaddkey). There are two custom keys ed, where the +default value is the text field with “ed” appended, and ing, where the default value is the text field with “ing” +appended. Since the default value in both cases references the text field, the starred version \glsaddkey* +is required to ensure that the default value is expanded on definition if no alternative has been +provided. +

    The entries are then defined as follows: + + +

    +
    +\newglossaryentry{jump}{name={jump},description={}} + 
    \newglossaryentry{run}{name={run},% + 
     ed={ran},% + 
     ing={running}, + 
     description={}} + 
    \newglossaryentry{waddle}{name={waddle},% + 
     ed={waddled},% + 
     ing={waddling},% + 
     description={}} +
    +

    +

    Each custom key is provided a set of commands analogous to \glsentrytext, that allows the key value to +be accessed, and \glstext that allows the key value to be access with indexing and hyperlinking (where +applicable). +

    If you find yourself wanting to create a lot of custom keys that produce minor variations of existing keys +(such as different tenses) you may find it simpler to just use \glsdisp. When editing the document source, it’s +usually simpler to read: + + +

    +
    +The dog \glsdisp{jump}{jumped} over the duck. +
    +

    than + + +

    +
    +The dog \glsed{jump} over the duck.
    -

    -

    Note that you need to include glossary-inline with \usepackage as it’s not automatically -included by the glossaries package and then set the style using \setglossarystyle. +

    +

    bib2glsIf you want to convert this document to use bib2gls, you first need to switch to glossaries-extra, but +remember that you need the record option:

    +
    +\usepackage[record]glossaries-extra +
    +
    Next convert the entry definitions to the bib format required by bib2gls: +

    
    +   
    convertgls2bib --index-conversion --preamble-only sample-newkeys.tex entries.bib +
    +
    +The --index-conversion switch requires at least v2.0 and will convert entries without a description (or where +the description is simply \nopostdesc or \glsxtrnopostpunc) to @index instead of @entry. This means that +the new entries.bib file will contain:

    +
    +@index{jump, +
      name = {jump} +
    } +
    +
    @index{run, +
      ing = {running}, +
      name = {run}, +
      ed = {ran} +
    } +
    +
    @index{waddle, +
      ing = {waddling}, +
      name = {waddle}, +
      ed = {waddled} +
    }
    -

    -

    Where you need to include your glossaries as a footnote you can do: - - +

    Now replace \makeglossaries with
    +
    +\GlsXtrLoadResources[src=entries] + + +
    +
    and delete the \newglossaryentry commands. Finally replace \printglossaries with \printunsrtglossaries. +

    The document build is now: +

    
    +   
    pdflatex sample-newkeys +
    bib2gls sample-newkeys +
    pdflatex sample-newkeys +
    +
    +Note that there’s no need for the nonumberlist package option when you don’t use bib2gls’s --group +switch. + +

    -
    -\footnote{\printglossaries} +

    🔗sample-storage-abbr.tex

    +

    This document illustrates how add custom storage keys (using \glsaddstoragekey). The document build +is: +

    
    +   
    pdflatex sample-storage-abbr +
    makeglossaries sample-storage-abbr +
    pdflatex sample-storage-abbr +
    +
    +

    The custom storage key is called abbrtype which defaults to word if not explicitly set. Its value can be +accessed with the provided custom command \abbrtype.

    +
    +\glsaddstoragekey{abbrtype}{word}{\abbrtype}
    -

    -

    The inline style is governed by the following: -


    \glsinlineseparator  \glsinlineseparator

    -

    -This defaults to “; ” and is used between main (i.e. level 0) entries. -


    \glsinlinesubseparator  \glsinlinesubseparator

    -

    -This defaults to “, ” and is used between sub-entries. -


    \glsinlineparentchildseparator  \glsinlineparentchildseparator

    -

    -This defaults to “: ” and is used between a parent main entry and its first sub-entry. -


    \glspostinline  \glspostinline

    -

    -This defaults to “; ” and is used at the end of the glossary. -


    \glsinlinenameformat  \glsinlinenameformat{label}{name}

    -

    -This is used to format the entry name and defaults to \glstarget{label}{name}, where -⟨name⟩ is provided in the form \glossentryname{label} and ⟨label⟩ is the entry’s label. For -example, if you want the name to appear in smallcaps: - - +

    A custom abbreviation style is then defined that checks the value of this key and makes certain adjustments +depending on whether or not its value is the default word. +

    This essentially forms a very similar function to the glossaries-extra package’s category key, which is also +defined as a storage key:

    +
    +\glsaddstoragekey{category}{general}{\glscategory} +
    +
    +


    glossaries-extraThis document is much simpler with the glossaries-extra package:

    + + +
    +\documentclass{article} +
    \usepackage[postdot]{glossaries-extra} +
    \makeglossaries +
    \setabbreviationstyle[acronym]{short-long} +
    \newacronym{radar}{radar}{radio detecting and ranging} +
    \newacronym{laser}{laser}{light amplification by stimulated +
    emission of radiation} +
    \newacronym{scuba}{scuba}{self-contained underwater breathing +
    apparatus} +
    +
    \newabbreviation{dsp}{DSP}{digital signal processing} +
    \newabbreviation{atm}{ATM}{automated teller machine} +
    +
    \begin{document} +
    +
    First use: \gls{radar}, \gls{laser}, \gls{scuba}, \gls{dsp}, +
    \gls{atm}. +
    +
    Next use: \gls{radar}, \gls{laser}, \gls{scuba}, \gls{dsp}, +
    \gls{atm}. +
    +
    \printglossaries +
    \end{document} +
    +
    + +

    -
    -\renewcommand*{\glsinlinenameformat}[2]{\glstarget{#1}{\textsc{#2}}} +

    🔗sample-storage-abbr-desc.tex

    +

    An extension of the previous example where the user needs to provide a description. + +

    +

    +

    🔗sample-chap-hyperfirst.tex

    +

    This document illustrates how to add a custom key using \glsaddstoragekey and hook into the \gls-like and +\glstext-like mechanism used to determine whether or not to hyperlink an entry. The document build +is: +

    
    +   
    pdflatex sample-chap-hyperfirst + + +
    makeglossaries sample-chap-hyperfirst +
    pdflatex sample-chap-hyperfirst +
    +
    +This example creates a storage key called chapter used to store the chapter number.

    +
    +\glsaddstoragekey{chapter}{0}{\glschapnum}
    -

    Sub-entry names are formatted according to -


    \glsinlinesubnameformat  \glsinlinesubnameformat{label}{name}

    -

    -This defaults to \glstarget{label}{} so the sub-entry name is ignored. -

    If the description has been suppressed (according to \ifglsdescsuppressed) -then -


    \glsinlineemptydescformat  \glsinlineemptydescformat{symbol}{number list It’s initialised to 0 and the \glslinkpostsetkeys hook is used to check this value against the current chapter +number. If the values are the same then the hyperlink is switched off, otherwise the key value is updated unless +the hyperlink has been switched off (through the optional argument of commands like \gls and \glstext). +
    +
    +\renewcommand*{\glslinkpostsetkeys}{% +
     \edef\currentchap{\arabic{chapter}}% +
     \ifnum\currentchap=\glschapnum{\glslabel}\relax +
      \setkeys{glslink}{hyper=false}% +
     \else +
      \glsifhyperon{\glsfieldxdef{\glslabel}{chapter}{\currentchap}}{}% +
     \fi +
    } -

    -

    -(which defaults to nothing) is used, otherwise the description is formatted according -to -


    \glsinlinedescformat  \glsinlinedescformat{description}{symbol}{number list +
    Since this key isn’t intended for use when the entry is being defined, it would be more appropriate to simply +use an internal field that doesn’t have an associated key or helper command, but \glsfieldxdef requires the +existence of the field. The glossaries-extra package provides utility commands designed to work on internal fields +that don’t have an associated key and may not have had a value assigned. +


    glossaries-extraIf you want to switch to glossaries-extra you need to change the package loading line: +

    +
    +\usepackage[postdot]{glossaries-extra} -

    -

    -This defaults to just \spacedescription⟩ so the symbol and location list are ignored. If the -description is missing (according to \ifglshasdesc), then \glsinlineemptydescformat is -used instead. -

    For example, if you want a colon between the name and the description: - - -

    -
    -\renewcommand*{\glsinlinedescformat}[3]{: #1}
    -

    -

    The sub-entry description is formatted according to: -


    \glsinlinesubdescformat  \glsinlinesubdescformat{description}{symbol}{number +
    The custom storage key (provided with \glsaddstoragekey) can be removed, and the \glslinkpostsetkeys +hook can be changed to:
    +
    list}

    -

    -This defaults to just ⟨description⟩. -

    +class="cmtt-10">\renewcommand*{\glslinkpostsetkeys}{% +
     \edef\currentchap{\arabic{chapter}}% +
     \GlsXtrIfFieldEqNum*{chapter}{\glslabel}{\currentchap} + + +
     {% +
       \setkeys{glslink}{hyper=false}% +
     }% +
     {% +
       \glsifhyperon{\xGlsXtrSetField{\glslabel}{chapter}{\currentchap}}{}% +
     }% +
    } +

    +
    The field name is still called chapter but there’s no longer an associated key or command. +

    -

    Top

    15.2 Defining your own glossary style

    -

    If the predefined styles don’t fit your requirements, you can define your own style -using: -


    \newglossarystyle  \newglossarystyle{name}{definitions}

    -

    -where ⟨name⟩ is the name of the new glossary style (to be used in \setglossarystyle). The -second argument ⟨definitions⟩ needs to redefine all of the following: -


    theglossary  theglossary

    -

    -This environment defines how the main body of the glossary should be typeset. Note that this -does not include the section heading, the glossary preamble (defined by \glossarypreamble) -or the glossary postamble (defined by \glossarypostamble). For example, the list style uses -the description environment, so the theglossary environment is simply redefined to begin and -end the description environment. -


    \glossaryheader  \glossaryheader

    -

    -This macro indicates what to do at the start of the main body of the glossary. Note that this -is not the same as \glossarypreamble, which should not be affected by changes in the -glossary style. The list glossary style redefines \glossaryheader to do nothing, -whereas the longheader glossary style redefines \glossaryheader to do a header -row. -


    \glsgroupheading  \glsgroupheading{label}

    -

    -This macro indicates what to do at the start of each logical block within the main body of -the glossary. If you use

    Top

    19.9 Xindy (Option 3)

    +

    Most of the earlier makeindex the glossary is sub-divided into a maximum of -twenty-eight logical blocks that are determined by the first character of the sort key (or -name key if the sort key is omitted). The sub-divisions are in the following order: -symbols, numbers, A, …, Z. If you use sample files can be adapted to use xindy, the sub-divisions depend on the language -settings. - - -

    Note that the argument to \glsgroupheading is a label not the group title. The group -title can be obtained via -


    \glsgetgrouptitle  \glsgetgrouptitle{label}

    -

    -This obtains the title as follows: if ⟨label⟩ consists of a single non-active character or ⟨label⟩ is -equal to glssymbols or glsnumbers and \labelgroupname exists, this is taken to be the title, -otherwise the title is just ⟨label⟩. (The “symbols” group has the label glssymbols, so the -command \glssymbolsgroupname is used, and the “numbers” group has the label -glsnumbers, so the command \glsnumbersgrouptitle is used.) If you are using instead by adding the xindy package +option. Situations that you need to be careful about are when the sort value (obtained from the name if the sort +key is omitted) contains commands (such as name={\pi}) or is identical to another value (or is identical after +xindy, -⟨label⟩ may be an active character (for example ø), in which case the title will be set -to just ⟨label⟩. You can redefine \glsgetgrouptitle if this is unsuitable for your -document. -

    A navigation hypertarget can be created using -


    \glsnavhypertarget  \glsnavhypertarget{label}{text}

    -

    -This typically requires \glossaryheader to be redefined to use -


    \glsnavigation  \glsnavigation

    -

    -which displays the navigation line. -

    For further details about \glsnavhypertarget, see the documented code -(glossaries-code.pdf). -

    Most of the predefined glossary styles redefine \glsgroupheading to simply ignore its -argument. The listhypergroup style redefines \glsgroupheading as follows: - - -

    -
    -\renewcommand*{\glsgroupheading}[1]{% - 
    \item[\glsnavhypertarget{##1}{\glsgetgrouptitle{##1}}]} -
    -

    See also \glsgroupskip below. (Note that command definitions within \newglossarystyle -must use ##1 instead of #1 etc.) -


    \glsgroupskip  \glsgroupskip

    -

    -This macro determines what to do after one logical group but before the header for the -next logical group. The list glossary style simply redefines \glsgroupskip to be -\indexspace, whereas the tabular-like styles redefine \glsgroupskip to produce a blank -row. -

    As from version 3.03, the package option nogroupskip can be used to suppress this default -gap for the predefined styles. -


    \glossentry  \glossentry{label}{number list}

    -

    -This macro indicates what to do for each top-level (level 0) glossary entry. The entry label is -given by ⟨label⟩ and the associated number list is given by ⟨number list⟩. You can redefine -\glossentry to use commands like \glossentryname{label}, \glossentrydesc{label} and -\glossentrysymbol{label} to display the name, description and symbol fields, or -to access other fields, use commands like \glsentryuseri{label}. (See §9 Using -Glossary Terms Without Links for further details.) You can also use the following -commands: -


    \glsentryitem  \glsentryitem{label}

    -

    -This macro will increment and display the associated counter for the main (level 0) entries if -the entrycounter or counterwithin package options have been used. This macro is typically -called by \glossentry before \glstarget. The format of the counter is controlled by the -macro -


    \glsentrycounterlabel  \glsentrycounterlabel

    -

    -

    Each time you use a glossary entry it creates a hyperlink (if hyperlinks are enabled) to the -relevant line in the glossary. Your new glossary style must therefore redefine \glossentry to -set the appropriate target. This is done using -


    \glstarget  \glstarget{label}{text}

    -

    -where ⟨label⟩ is the entry’s label. Note that you don’t need to worry about whether the hyperref -package has been loaded, as \glstarget won’t create a target if \hypertarget hasn’t been -defined. -

    For example, the list style defines \glossentry as follows: - - + id="dx1-210006"> has stripped all commands and braces). This section describes sample documents that use features which +are unavailable with makeindex. + +

    -
    -  \renewcommand*{\glossentry}[2]{% - 
        \item[\glsentryitem{##1}% - 
              \glstarget{##1}{\glossentryname{##1}}] - 
           \glossentrydesc{##1}\glspostdescription\space ##2} -
    -

    -

    Note also that ⟨number list⟩ will always be of the form -


    \glossaryentrynumbers{\relax
    \setentrycounter[Hprefix]{counter name}format cmd{number(s)}}

    -

    -where ⟨number(s)⟩ may contain \delimN (to delimit individual numbers) and/or \delimR (to -indicate a range of numbers). There may be multiple occurrences of \setentrycounter -[Hprefix]{counter name}format cmd{number(s)}, but note that the entire number list is -enclosed within the argument of \glossaryentrynumbers. The user can redefine this to -change the way the entire number list is formatted, regardless of the glossary style. -However the most common use of \glossaryentrynumbers is to provide a means of -suppressing the number list altogether. (In fact, the nonumberlist option redefines -\glossaryentrynumbers to ignore its argument.) Therefore, when you define a new glossary -style, you don’t need to worry about whether the user has specified the nonumberlist package -option. -


    \subglossentry  \subglossentry{level}{label}{number list}

    -

    -This is used to display sub-entries. The first argument, ⟨level⟩, indicates the sub-entry level. -This must be an integer from 1 (first sub-level) onwards. The remaining arguments are -analogous to those for \glossentry described above. -


    \glssubentryitem  \glssubentryitem{label}

    -

    -This macro will increment and display the associated counter for the level 1 entries if the -subentrycounter package option has been used. This macro is typically called by -\subglossentry before \glstarget. The format of the counter is controlled by the -macro -


    \glssubentrycounterlabel  \glssubentrycounterlabel

    -

    -

    Note that \printglossary (which \printglossaries calls) sets -


    \currentglossary  \currentglossary

    -

    -to the current glossary label, so it’s possible to create a glossary style that varies according to -the glossary type. -

    For further details of these commands, see “Displaying the glossary” in the documented -code (glossaries-code.pdf). - - +

    🔗samplexdy.tex

    +

    The document uses UTF8 encoding (with the inputenc package). This is information that needs to be passed to -

    Example 27 (Creating a completely new style) -

    If you want a completely new style, you will need to redefine all of the commands and the -environment listed above. -

    For example, suppose you want each entry to start with a bullet point. This -means that the glossary should be placed in the itemize environment, so theglossary -should start and end that environment. Let’s also suppose that you don’t want -anything between the glossary groups (so \glsgroupheading and \glsgroupskip -should do nothing) and suppose you don’t want anything to appear immediately -after \begin{theglossary} (so \glossaryheader should do nothing). In addition, -let’s suppose the symbol should appear in brackets after the name, followed by the -description and last of all the number list should appear within square brackets -at the end. Then you can create this new glossary style, called, say, mylist, as -follows: - - +href="#glo:xindy">xindy, so the encoding is picked up by makeglossaries from the aux file. +

    By default, this document will create a xindy style file called samplexdy.xdy, but if you uncomment the +lines + + +

    +
    +\setStyleFile{samplexdy-mc} + 
    \noist + 
    \GlsSetXdyLanguage{} +
    +

    it will set the style file to samplexdy-mc.xdy instead. This provides an additional letter group for entries +starting with “Mc” or “Mac”. If you use makeglossaries or makeglossaries-lite, you don’t need to supply +any additional information. If you don’t use makeglossaries, you will need to specify the required +information. Note that if you set the style file to samplexdy-mc.xdy you must also specify \noist, +otherwise the glossaries package will overwrite samplexdy-mc.xdy and you will lose the “Mc” letter +group. +

    To create the document do: +

    
    +   
    pdflatex samplexdy +
    makeglossaries samplexdy +
    pdflatex samplexdy +
    +
    +If you don’t have Perl installed then you can’t use makeglossaries, but you also can’t use xindy! However, if +for some reason you want to call xindy explicitly instead of using makeglossaries (or makeglossaries-lite):

    -
    - \newglossarystyle{mylist}{% - 
     % put the glossary in the itemize environment: - 
     \renewenvironment{theglossary}% - 
       {\begin{itemize}}{\end{itemize}}% - 
     % have nothing after \begin{theglossary}: - 
     \renewcommand*{\glossaryheader}{}% - 
     % have nothing between glossary groups: - 
     \renewcommand*{\glsgroupheading}[1]{}% - 
     \renewcommand*{\glsgroupskip}{}% - 
     % set how each entry should appear: - 
     \renewcommand*{\glossentry}[2]{% - 
     \item % bullet point - 
     \glstarget{##1}{\glossentryname{##1}}% the entry name - 
     \space (\glossentrysymbol{##1})% the symbol in brackets - 
     \space \glossentrydesc{##1}% the description - 
     \space [##2]% the number list in square brackets - 
     }% - 
     % set how sub-entries appear: - 
     \renewcommand*{\subglossentry}[3]{% - 
       \glossentry{##2}{##3}}% - 
     } -
    -

    Note that this style creates a flat glossary, where sub-entries are displayed in exactly the -same way as the top level entries. It also hasn’t used \glsentryitem or \glssubentryitem so -it won’t be affected by the entrycounter, counterwithin or subentrycounter package -options. -

    Variations:

      -
    • You might want the entry name to be capitalised, in which case use - \Glossentryname instead of \glossentryname. -
    • -
    • You might want to check if the symbol hasn’t been set and omit the parentheses if - the symbol is absent. In this case you can use \ifglshassymbol (see §16 - Utilities): - - -
      -  \renewcommand*{\glossentry}[2]{% -  
       \item % bullet point -  
       \glstarget{##1}{\glossentryname{##1}}% the entry name -  
       \ifglshassymbol{##1}% check if symbol exists -  
       {% -  
         \space (\glossentrysymbol{##1})% the symbol in brackets -  
       }% -  
       {}% no symbol so do nothing -  
       \space \glossentrydesc{##1}% the description -  
       \space [##2]% the number list in square brackets -  
       }% +
    • if you are using the default style file samplexdy.xdy, then do (no line breaks): +

      
      +     
      xindy -L english -C utf8 -I xindy -M samplexdy -t samplexdy.glg -o samplexdy.gls samplexdy.glo +
      +
      +

    • +
    • if you are using samplexdy-mc.xdy, then do (no line breaks): +

      
      +     
      xindy -I xindy -M samplexdy-mc -t samplexdy.glg -o samplexdy.gls samplexdy.glo +
      +
      +

    +

    This document creates a new command to use with the format key in the optional argument of commands +like \gls to format the location in the number list. The usual type of definition when a hyperlinked location is +required should use one of the \hyperxx commands listed in table 6.1: + + +

    +
    +\newcommand*{\hyperbfit}[1]{\textit{\hyperbf{#1}}}
    -

    -
    -

    -

    ____________________________

    - -

    Example 28 (Creating a new glossary style based on an existing +

    Unfortunately, this definition doesn’t work for this particular document and some adjustments are needed (see +below). As a result of the adjustments, this command doesn’t actually get used by TEX, even though style) -

    If you want to define a new style that is a slightly modified version of an existing style, -you can use \setglossarystyle within the second argument of \newglossarystyle followed -by whatever alterations you require. For example, suppose you want a style like -the list style but you don’t want the extra vertical space created by \indexspace -between groups, then you can create a new glossary style called, say, mylist as -follows: - - +class="cmtt-10">hyperbfit is used in the format key. It does, however, need to be identified as an attribute so that xindy can +recognise it: + +

    -
    -\newglossarystyle{mylist}{% - 
    \setglossarystyle{list}% base this style on the list style - 
    \renewcommand{\glsgroupskip}{}% make nothing happen - 
                                  % between groups - 
    } +
    +\GlsAddXdyAttribute{hyperbfit}
    -

    (In this case, you can actually achieve the same effect using the list style in combination with -the package option nogroupskip.)

    -
    -

    -

    ____________________________

    - -

    Example 29 (Example: creating a glossary style that uses the user1, +

    This will add information to the xdy file when it’s created by \makeglossaries. If you prevent the creation of +this file with \noist then you will need to add the attribute to your custom xdy file (see the provided …, user6 keys) -

    Suppose each entry not only has an associated symbol, but also units (stored in user1) and -dimension (stored in user2). Then you can define a glossary style that displays each entry in a +class="cmtt-10">samplexdy-mc.xdy file). +

    In order to illustrate unusual location formats, this sample document provides a command called longtable as follows: - - +class="cmtt-10">\tallynum{⟨n} that represents its numerical argument with a die or dice where the dots add up to +⟨n⟩: + +

    -
    -\newglossarystyle{long6col}{% - 
     % put the glossary in a longtable environment: - 
     \renewenvironment{theglossary}% - 
      {\begin{longtable}{lp{\glsdescwidth}cccp{\glspagelistwidth}}}% - 
      {\end{longtable}}% - 
     % Set the table's header: - 
     \renewcommand*{\glossaryheader}{% - 
      \bfseries Term & \bfseries Description & \bfseries Symbol & - 
      \bfseries Units & \bfseries Dimensions & \bfseries Page List - 
      \\\endhead}% - 
     % No heading between groups: - 
      \renewcommand*{\glsgroupheading}[1]{}% - 
     % Main (level 0) entries displayed in a row optionally numbered: - 
      \renewcommand*{\glossentry}[2]{% - 
        \glsentryitem{##1}% Entry number if required - 
        \glstarget{##1}{\glossentryname{##1}}% Name - 
        & \glossentrydesc{##1}% Description - 
        & \glossentrysymbol{##1}% Symbol - 
        & \glsentryuseri{##1}% Units - 
        & \glsentryuserii{##1}% Dimensions - 
        & ##2% Page list - 
        \tabularnewline % end of row - 
      }% - 
     % Similarly for sub-entries (no sub-entry numbers): - 
     \renewcommand*{\subglossentry}[3]{% - 
        % ignoring first argument (sub-level) - 
        \glstarget{##2}{\glossentryname{##2}}% Name - 
        & \glossentrydesc{##2}% Description - 
        & \glossentrysymbol{##2}% Symbol - 
        & \glsentryuseri{##2}% Units - 
        & \glsentryuserii{##2}% Dimensions - 
        & ##3% Page list - 
        \tabularnewline % end of row - 
      }% - 
     % Nothing between groups: - 
     \renewcommand*{\glsgroupskip}{}% +
    +\newrobustcmd*{\tallynum}[1]{% + 
     \ifnum\number#1<7 + 
      $\csname dice\romannumeral#1\endcsname$% + 
     \else + 
      $\dicevi$% + 
      \expandafter\tallynum\expandafter{\numexpr#1-6}% + 
     \fi  
    }
    -

    -
    -

    -

    ____________________________

    - - -

    -

    Top

    16. Utilities

    -

    This section describes some utility commands. Additional commands can be found in the -documented code (glossaries-code.pdf). +

    This command needs to be robust to prevent it from being expanded when it’s written to any of the auxiliary +files. The \dicei, …, \dicevi commands are provided by the stix package, so that needs to be +loaded. +

    An associated command \tally{counter} is defined that formats the value of the named ⟨counter⟩ according +to \tallynum: + +

    -

    Top

    16.1 Loops

    -

    Some of the commands described here take a comma-separated list as an argument. As with -LATEX’s \@for command, make sure your list doesn’t have any unwanted spaces in it as -they don’t get stripped. (Discussed in more detail in §2.7.2 of “LATEX for Administrative -Work”.)
    -

    -


    \forallglossaries  \forallglossaries[glossary list]{cs}{body}

    -

    -This iterates through ⟨glossary list⟩, a comma-separated list of glossary labels (as -supplied when the glossary was defined). At each iteration ⟨cs⟩ (which must be a control -sequence) is set to the glossary label for the current iteration and ⟨body⟩ is performed. If -⟨glossary list⟩ is omitted, the default is to iterate over all glossaries (except the ignored -ones). -


    \forallacronyms  \forallacronyms{cs}{body}

    -

    -This is like \forallglossaries but only iterates over the lists of acronyms (that have -previously been declared using \DeclareAcronymList or the acronymlists package option). -This command doesn’t have an optional argument. If you want to explicitly say which lists to -iterate over, just use the optional argument of \forallglossaries. -


    \forglsentries  \forglsentries[glossary label]{cs}{body}

    -

    -This iterates through all entries in the glossary given by ⟨glossary label⟩. At each iteration ⟨cs⟩ -(which must be a control sequence) is set to the entry label for the current iteration and ⟨body⟩ -is performed. If ⟨glossary label⟩ is omitted, \glsdefaulttype (usually the main glossary) is -used. -


    \forallglsentries  \forallglsentries[glossary list]{cs}{body}

    -

    -This is like \forglsentries but for each glossary in ⟨glossary list⟩ (a comma-separated list of -glossary labels). If ⟨glossary list⟩ is omitted, the default is the list of all defined glossaries -(except the ignored ones). At each iteration ⟨cs⟩ is set to the entry label and ⟨body⟩ is -performed. (The current glossary label can be obtained using \glsentrytype{cs} within -⟨body⟩.) -

    +

    +\newcommand*{\tally}[1]{\tallynum{\arabic{#1}}} +
    +

    (This shouldn’t be robust as it needs the counter value to expand.) The page numbers are altered to use this +format (by redefining \thepage). +

    This custom location format also needs to be identified in the xdy file so that xindy can recognise it and +determine how to form ranges if required. + +

    -

    Top

    16.2 Conditionals

    -


    \ifglossaryexists  \ifglossaryexistslabel⟩⟨true part⟩⟨false part

    - - -

    -This checks if the glossary given by ⟨label⟩ exists. If it does ⟨true part⟩ is performed, otherwise -⟨false part⟩. -


    \ifglsentryexists  \ifglsentryexistslabel⟩⟨true part⟩⟨false part

    -

    -This checks if the glossary entry given by ⟨label⟩ exists. If it does ⟨true part⟩ is performed, -otherwise ⟨false part⟩. (Note that \ifglsentryexists will always be true after the containing -glossary has been displayed via \printglossary or \printglossaries even if the entry is -explicitly defined later in the document. This is because the entry has to be defined -before it can be displayed in the glossary, see §4.8.1 Technical Issues for further -details.) -


    \glsdoifexists  \glsdoifexists{label}{code}

    -

    -Does ⟨code⟩ if the entry given by ⟨label⟩ exists. If it doesn’t exist, an error is generated. (This -command uses \ifglsentryexists.) -


    \glsdoifnoexists  \glsdoifnoexists{label}{code}

    -

    -Does the reverse of \glsdoifexists. (This command uses \ifglsentryexists.) -


    \glsdoifexistsorwarn  \glsdoifexistsorwarn{label}{code}

    -

    -As \glsdoifexists but issues a warning rather than an error if the entry doesn’t -exist. -


    \glsdoifexistsordo  \glsdoifexistsordo{label}{code}{else code}

    -

    -Does ⟨code⟩ if the entry given by ⟨label⟩ exists otherwise generate an error and do ⟨else -code⟩. -


    \glsdoifnoexistsordo  \glsdoifnoexistsordo{label}{code}{else code}

    -

    -Does ⟨code⟩ if the entry given by ⟨label⟩ doesn’t exist otherwise generate an error and do ⟨else +

    +\GlsAddXdyLocation{tally}{% tally location format + 
     :sep "\string\tallynum\space\glsopenbrace" + 
     "arabic-numbers" + 
     :sep "\glsclosebrace" + 
    } +
    +

    Again this information is written to the xdy file by \makeglossaries so if you use \noist then you need to +manually add it to your custom xdy file. +

    When xindy creates the associated glossary files, the locations will be written using:

    +
    code⟩. -


    \ifglsused  \ifglsusedlabel⟩⟨true part⟩⟨false part

    -

    -See §14 Unsetting and Resetting Entry Flags. -


    \ifglshaschildren  \ifglshaschildrenlabel⟩⟨true part⟩⟨false part

    -

    -This checks if the glossary entry given by ⟨label⟩ has any sub-entries. If it does, ⟨true part⟩ is -performed, otherwise ⟨false part⟩. -


    \ifglshasparent  \ifglshasparentlabel⟩⟨true part⟩⟨false part

    -

    -This checks if the glossary entry given by ⟨label⟩ has a parent entry. If it does, ⟨true part⟩ is -performed, otherwise ⟨false part⟩. -


    \ifglshassymbol  \ifglshassymbol{label}{true part}{false part}

    -

    -This checks if the glossary entry given by ⟨label⟩ has had the symbol field set. If it has, ⟨true part⟩ -is performed, otherwise ⟨false part⟩. -


    \ifglshaslong  \ifglshaslong{label}{true part\glsXcounterXformat{hyper-prefix}{false part}

    - - -

    -This checks if the glossary entry given by ⟨label⟩ has had the long field set. If it has, ⟨true part⟩ is -performed, otherwise ⟨false part⟩. This should be true for any entry that has been defined via +class="cmitt-10">location⟩} +

    +
    In this case:
    +
    \newacronym. There is no check for the existence of ⟨label⟩. -


    \ifglshasshort  \ifglshasshort{label}{true part}{false part}

    -

    -This checks if the glossary entry given by ⟨label⟩ has had the short field set. If it has, ⟨true part⟩ -is performed, otherwise ⟨false part⟩. This should be true for any entry that has been defined via +class="cmtt-10">\glsXpageXglsnumberformat{}{\tallynum{⟨number}} +

    +
    or
    +
    \newacronym. There is no check for the existence of ⟨label⟩. -


    \ifglshasdesc  \ifglshasdesc{label}{true part}{false part}

    -

    -This checks if the description field is non-empty for the entry given by ⟨label⟩. If it has, ⟨true part⟩ -is performed, otherwise ⟨false part⟩. Compare with: -


    \ifglsdescsuppressed  \ifglsdescsuppressed{label}{true part}{false part\glsXpageXhyperbfit{}{\tallynum{number}} +
    +
    This means that although \hyperbf is designed to create hyperlinked locations, the presence of \tallynum +interferes with it. In order to make the hyperlinks work correctly, the definitions of \glsXpageXhyperbfit need +to be redefined in order to grab the number part in order to work out the location’s numeric value. +If the value of \tally is changed so that it expands differently then these modifications won’t +work. +

    Remember that in both cases, the second argument #2 is in the form \tally{n}: + + +

    +
    +\renewcommand{\glsXpageXglsnumberformat}[2]{% + 
     \linkpagenumber#2% + 
    } + 
    \renewcommand{\glsXpageXhyperbfit}[2]{% + 
     \textbf{\em\linkpagenumber#2}% + 
    } +
    +

    These need a command that can grab the actual number and correctly encapsulate it: + + +

    +
    +\newcommand{\linkpagenumber}[2]{\hyperlink{page.#2}{#1{#2}}} +
    +

    +

    If you want to try out the samplexdy-mc.xdy file, the entries starting with “Mac” or “Mc” will be placed in +their own “Mc” letter group. Ideally it should be possible to do this simply with \GlsAddLetterGroup (and not +require a custom xdy file) but unfortunately the “M” letter group will have already been defined and take +precedence over “Mc”, which is why a custom file is required and the normal language module must be +suppressed: + + +

    +
    +\setStyleFile{samplexdy-mc} + 
    \noist + 
    \GlsSetXdyLanguage{} +
    +

    +

    This “Mc” group is suitable for names like “Maclaurin” but not for “Mach”. To prevent this, the sort key +for that value is set to lower case: + + +

    +
    +\newglossaryentry{mach}{name={Mach, Ernst}, + 
    first={Ernst Mach},text={Mach}, + 
    sort={mach, Ernst}, + 
    description={Czech/Austrian physicist and philosopher}} +
    +

    +

    bib2glsIf you want to convert this document so that it uses bib2gls, you first need to switch to +glossaries-extra and use the record package option:

    +
    +\usepackage[record,postdot]{glossaries-extra} -

    -

    -This checks if the description field has been set to just \nopostdesc for the entry given by -⟨label⟩. If it has, ⟨true part⟩ is performed, otherwise ⟨false part⟩. There is no check for the existence -of ⟨label⟩. -

    For all other fields you can use: -


    \ifglshasfield  \ifglshasfield{field}{label}{true part}{false part +
    The xindy-only commands can now all be removed (attribute \GlsAddXdyAttribute, location +\GlsAddXdyLocation, language \GlsSetXdyLanguage, location encapsulators \glsXcounterXformat and the +custom helper \linkpagenumber). Also \noist and \setStyleFile aren’t relevant with bib2gls and so should +be removed. +

    The definitions of \hyperbfit should be retained (as well as \tallynum, \tally and the redefinition of +\thepage). +

    The entries all need to be converted to the bib format required by bib2gls. +

    
    +   
    convertgls2bib --preamble-only samplexdy.tex entries.bib +
    +
    +Next replace \makeglossaries with:

    +
    +\GlsXtrLoadResources[src=entries] +
    +
    and remove all the entry definitions from the preamble. Use the search and replace function on your text editor +to replace all instances of \glsentryfirst with \glsfmtfirst, and all instances of \glsentryname with +\glsfmtname. +

    Finally, replace \printglossaries with \printunsrtglossaries. The document build is now: +

    
    +   
    pdflatex samplexdy +
    bib2gls --group samplexdy +
    pdflatex samplexdy +
    +
    + + +

    This results in a slightly different ordering from the original document (without the “Mc” letter group). In +the original example, “Mach number” was listed before “Mach, Ernest”. The modified document now has +“Mach, Ernest” before “Mach number”. This difference is due to bib2gls’s default break-at=word setting, +which marks word boundaries with the pipe (|) character, so the sort values for bib2gls are Mach|Earnest| +and Mach|number|. See the bib2gls manual for further details of this option, and also see the +examples chapter of that manual for alternative approaches when creating entries that contain people’s +names. +

    If you want the “Mc” letter group, it can be obtained by providing a custom sort rule:

    +
    +\GlsXtrLoadResources[src=entries, +
       sort=custom, +
       sort-rule={\glsxtrcontrolrules +
       ;\glsxtrspacerules;\glsxtrnonprintablerules +
       ;\glsxtrcombiningdiacriticrules,\glsxtrhyphenrules +
       <\glsxtrgeneralpuncrules<\glsxtrdigitrules +
       <a,A<b,B<c,C<d,D<e,E<f,F<g,G<h,H<i,I<j,J<k,K<l,L<Mc=Mac<m,M<o,O +
       <p,P<q,Q<r,R<s,S<t,T<u,U<v,V<r,R<s,S<t,T<u,U<v,V<w,W<x,X<y,Y<z,Z +
       } +
    ] +
    +
    Unfortunately, as with xindy, this puts “Mach” into the “Mc” letter group. +

    One way to get around this problem is to define a custom command to help identify genuine “Mc”/“Mac” +prefixes with names that happen to start with “Mac”. For example:

    +
    +@entry{mcadam, +
      name = {\Mac{Mc}Adam, John Loudon}, +
      description = {Scottish engineer}, +
      text = {McAdam}, +
      first = {John Loudon McAdam} +
    } -

    -

    -This tests the value of the field given by ⟨field⟩ for the entry identified by ⟨label⟩. If the value is -empty or the default value, then ⟨false part⟩ is performed, otherwise ⟨true part⟩ is performed. If -the field supplied is unrecognised ⟨false part⟩ is performed and a warning is issued. -Unlike the above commands, such as \ifglshasshort, an error occurs if the entry is -undefined. -

    As from version 4.23, within ⟨true part⟩ you can use -


    \glscurrentfieldvalue  \glscurrentfieldvalue

    -

    -to access the field value. This command is initially defined to nothing but has no -relevance outside ⟨true part⟩. This saves re-accessing the field if the test is true. For -example: - - +
    +
    @entry{maclaurin, +
      name = {\Mac{Mac}laurin, Colin}, +
      description ={Scottish mathematician best known for the +
    \gls{maclaurinseries}}, +
      text = {Maclaurin}, +
      first = {Colin Maclaurin} +
    } +

    +
    but not for “Mach”:
    + + +
    +@entry{mach, +
      name = {Mach, Ernst}, +
      description = {Czech/Austrian physicist and philosopher}, +
      text = {Mach}, +
      first = {Ernst Mach} +
    } +
    +
    With LATEX, this command should simply do its argument: + + +
    +\newcommand{\Mac}[1]{#1} +
    +

    However, when bib2gls works out the sort value, it needs to be defined with something unique that won’t +happen to occur at the start of another term. For example: + + +

    +
    +\providecommand{\Mac}[1]{MC} +
    +

    (Remember that break-at=word will strip spaces and punctuation so don’t include them unless you switch to +break-at=none.) +

    So add the first definition of \Mac to the tex file and modify entries.bib so that it includes the second +definition:

    +
    +@preamble{"\providecommand{\Mac}[1]{MC}"} +
    +
    Then modify the “Mc”/“Mac” entries as appropriate (see the above “McAdam” and “Maclaurin” +examples). +

    The custom sort rule needs to be modified:

    +
    +\GlsXtrLoadResources[src=entries, +
       write-preamble=false, +
       sort=custom, +
       sort-rule={\glsxtrcontrolrules +
       ;\glsxtrspacerules;\glsxtrnonprintablerules +
       ;\glsxtrcombiningdiacriticrules,\glsxtrhyphenrules +
       <\glsxtrgeneralpuncrules<\glsxtrdigitrules +
       <a,A<b,B<c,C<d,D<e,E<f,F<g,G<h,H<i,I<j,J<k,K<l,L<MC<m,M<o,O +
       <p,P<q,Q<r,R<s,S<t,T<u,U<v,V<r,R<s,S<t,T<u,U<v,V<w,W<x,X<y,Y<z,Z +
       } +
    ] +
    +
    This will create a “Mc” letter group that only includes the names that start with the custom \Mac +command. +

    Other alternatives include moving @preamble into a separate bib file, so that you can choose +whether or not to include it. See the “Examples” chapter of the bib2gls user manual for further +examples. + +

    +

    +

    🔗samplexdy2.tex

    +

    This document illustrates how to use the glossaries package where the location numbers don’t follow a standard +format. This example will only work with xindy. To create the document do: + + +

    
    +   
    pdflatex samplexdy2 +
    makeglossaries samplexdy2 +
    pdflatex samplexdy2 +
    +
    +The explicit xindy call is: +

    
    +   
    xindy -L english -C utf8 -I xindy -M samplexdy2 -t samplexdy2.glg -o samplexdy2.gls samplexdy2.glo +
    +
    +This example uses the section counter with xindy: + +

    -
    -\ifglshasfield{useri}{sample}{, \glscurrentfieldvalue}{} +
    +\usepackage[xindy,counter=section]{glossaries}
    -

    will insert a comma, space and the field value if the user1 key has been set for the entry -whose label is sample. -

    You can test if the value of the field is equal to a given string using: -


    \ifglsfieldeq  \ifglsfieldeq{label}{field}{string}{true}{false} -

    -

    -In this case the ⟨field⟩ must be the field name not the key (see table 4.1). If the -field isn’t recognised, an error will occur. This command internally uses etoolbox’s -\ifcsstring to perform the comparison. The string is not expanded during the -test. -

    The result may vary depending on whether or not expansion is on for the given field -(when the entry was defined). For example: - - +

    The document employs an eccentric section numbering system for illustrative purposes. The section numbers +are prefixed by the chapter number in square brackets: + +

    -
    -\documentclass{article} - 
    \usepackage{glossaries} - 
    \newcommand*{\foo}{FOO} - 
    \newglossaryentry{sample1}{name={sample1},description={an example}, - 
    user1={FOO}} - 
    \newglossaryentry{sample2}{name={sample2},description={an example}, - 
    user1={\foo}} - 
    \begin{document} - 
    \ifglsfieldeq{sample1}{useri}{FOO}{TRUE}{FALSE}. - 
    \ifglsfieldeq{sample2}{useri}{FOO}{TRUE}{FALSE}. - 
    \end{document} +
    +\renewcommand*{\thesection}{[\thechapter]\arabic{section}}
    -

    This will produce “TRUE” in both cases since expansion is on, so \foo was expanded to -“FOO” when sample2 was defined. If the tests are changed to: - - +

    Parts use Roman numerals: + +

    -
    -\ifglsfieldeq{sample1}{useri}{\foo}{TRUE}{FALSE}. - 
    \ifglsfieldeq{sample2}{useri}{\foo}{TRUE}{FALSE}. +
    +\renewcommand*{\thepart}{\Roman{part}}
    -

    then this will produce “FALSE” in both cases. Now suppose expansion is switched off for the -user1 key: - - +

    The section hyperlink name includes the part: + +

    -
    -\documentclass{article} - 
    \usepackage{glossaries} - 
    \newcommand*{\foo}{FOO} - 
    \glssetnoexpandfield{useri} - 
    \newglossaryentry{sample1}{name={sample1},description={an example}, - 
    user1={FOO}} - 
    \newglossaryentry{sample2}{name={sample2},description={an example}, - 
    user1={\foo}} - 
    \begin{document} - 
    \ifglsfieldeq{sample1}{useri}{FOO}{TRUE}{FALSE}. - 
    \ifglsfieldeq{sample2}{useri}{FOO}{TRUE}{FALSE}. - 
    \end{document} +
    +\renewcommand*{\theHsection}{\thepart.\thesection}
    -

    This now produces “TRUE” for the first case (comparing “FOO” with “FOO”) and -“FALSE” for the second case (comparing “\foo” with “FOO”). -

    The reverse happens in the following: - - +

    This custom numbering scheme needs to be identified in the xdy file: + +

    -
    -\documentclass{article} - 
    \usepackage{glossaries} - 
    \newcommand*{\foo}{FOO} - 
    \glssetnoexpandfield{useri} - 
    \newglossaryentry{sample1}{name={sample1},description={an example}, - 
    user1={FOO}} - 
    \newglossaryentry{sample2}{name={sample2},description={an example}, - 
    user1={\foo}} - 
    \begin{document} - 
    \ifglsfieldeq{sample1}{useri}{\foo}{TRUE}{FALSE}. - 
    \ifglsfieldeq{sample2}{useri}{\foo}{TRUE}{FALSE}. - 
    \end{document} +
    +\GlsAddXdyLocation["roman-numbers-uppercase"]{section}{:sep "[" + 
      "arabic-numbers" :sep "]" "arabic-numbers" + 
    }
    -

    This now produces “FALSE” for the first case (comparing “FOO” with “\foo”) and -“TRUE” for the second case (comparing “\foo” with “\foo”). -

    You can test if the value of a field is equal to the replacement text of a command -using: -


    \ifglsfielddefeq  \ifglsfielddefeq{label}{field}{command}{true}{false} -

    -

    -This internally uses etoolbox’s \ifdefstrequal command to perform the comparison. The -argument ⟨command⟩ must be a macro. -

    For example: - - +

    If the part is 0 then \thepart will be empty (there isn’t a zero Roman numeral). An extra case is needed to +catch this: + +

    -
    -\documentclass{article} - 
    \usepackage{glossaries} - 
    \newcommand*{\foo}{FOO} - 
    \glssetnoexpandfield{useri} - 
    \newglossaryentry{sample1}{name={sample1},description={an example}, - 
    user1={FOO}} - 
    \newglossaryentry{sample2}{name={sample2},description={an example}, - 
    user1={\foo}} - 
    \begin{document} - 
    \ifglsfielddefeq{sample1}{useri}{\foo}{TRUE}{FALSE}. - 
    \ifglsfielddefeq{sample2}{useri}{\foo}{TRUE}{FALSE}. - 
    \end{document} +
    +\GlsAddXdyLocation{zero.section}{:sep "[" + 
      "arabic-numbers" :sep "]" "arabic-numbers" + 
    }
    -

    Here, the first case produces “TRUE” since the value of the useri field (“FOO”) is the same -as the replacement text (definition) of \foo (“FOO”). We have the result “FOO” is equal to -“FOO”. -

    The second case produces “FALSE” since the value of the useri field (“\foo”) is not the -same as the replacement text (definition) of \foo (“FOO”). No expansion has been -performed on the value of the useri field. We have the result “\foo” is not equal to -“FOO”. -

    If we add: - - -

    -
    -\newcommand{\FOO}{\foo} - 
    \ifglsfielddefeq{sample2}{useri}{\FOO}{TRUE}{FALSE}. +

    Note that this will stop xindy giving a warning, but the location hyperlinks will be invalid if no \part is +used. +

    bib2glsIf you want to switch to bib2gls, you first need to switch to glossaries-extra but remember to use +record instead of xindy:

    +
    +\usepackage[record,counter=section]{glossaries-extra}
    -

    we now get “TRUE” since the value of the useri field (“\foo”) is the same as the -replacement text (definition) of \FOO (“\foo”). We have the result “\foo” is equal to -“\foo”. -

    There is a similar command that requires the control sequence name (without the leading -backslash) instead of the actual control sequence: -


    \ifglsfieldcseq  \ifglsfieldcseq{label}{field}{csname}{true}{false Next remove the \GlsAddXdyLocation commands and convert the entry definitions to the bib format required +by bib2gls: +

    
    +   
    convertgls2bib --preamble-only samplexdy2.tex entries.bib +
    +
    +Now replace \makeglossaries with:

    +
    +\GlsXtrLoadResources[src=entries] +
    +
    and remove the \newglossaryentry commands. Finally, replace \printglossaries with +\printunsrtglossaries. +

    The document build is: +

    
    +   
    pdflatex samplexdy2 +
    bib2gls samplexdy2 +
    pdflatex samplexdy2 +
    +
    +

    With unusual numbering systems, it’s sometimes better to use record=nameref:

    +
    +\usepackage[record=nameref,counter=section]{glossaries-extra} -

    -

    -This internally uses etoolbox’s \ifcsstrequal command instead of \ifdefstrequal. -

    + + +

    +
    In this case, the locations will be the actual section headings, rather than the section number. In order to make +the number appear instead you need to define:
    +
    +\newcommand*{\glsxtrsectionlocfmt}[2]{#1} +
    +
    (Make sure you have at least v1.42 of glossaries-extra.) See also the earlier sampleSec.tex. + +

    -

    Top

    16.3 Fetching and Updating the Value of a Field

    -

    You can fetch the value of a given field and store it in a control sequence using: -


    \glsfieldfetch  \glsfieldfetch{label}{field}{cs}

    -

    -where ⟨label⟩ is the label identifying the glossary entry, ⟨field⟩ is the field label (see +

    🔗samplexdy3.tex

    +

    This document is very similar to samplexdy.tex but uses the command \Numberstring from the +fmtcount package to format the page numbers instead of the \tally command from the earlier +example. table 4.1) and ⟨cs⟩ is the control sequence in which to store the value. Remember that -⟨field⟩ is the internal label and is not necessarily the same as the key used to set -that field in the argument of \newglossaryentry (or the optional argument of + id="x1-213002r32"> +

    +

    +

    🔗sampleutf8.tex

    +

    This is another example that uses xindy. Unlike makeindex, xindy can cope with non-Latin characters. This +document uses UTF-8 encoding. To create the document do: +

    
    +   
    pdflatex sampleutf8 +
    makeglossaries sampleutf8 +
    pdflatex sampleutf8 +
    +
    +The explicit xindy call is (no line breaks): +

    +

    
    +
    xindy +-L +english +-C +utf8 +-I +xindy +-M +sampleutf8 +-t + + +sampleutf8.glg +-o +sampleutf8.gls +sampleutf8.glo +
    +
    +

    If you remove the xindy option from sampleutf8.tex and do: +

    
    +   
    pdflatex sampleutf8 +
    makeglossaries sampleutf8 +
    pdflatex sampleutf8 +
    +
    +or +

    
    +   
    pdflatex sampleutf8 +
    makeglossaries-lite sampleutf8 +
    pdflatex sampleutf8 +
    +
    +you will see that the entries that start with an extended Latin character now appear in the symbols group, and +the word “manœuvre” is now after “manor” instead of before it. If you want to explicitly call makeindex (no +line breaks): +

    
    +   
    makeindex -s sampleutf8.ist -t sampleutf8.glg -o sampleutf8.gls sampleutf8.glo +
    +
    +

    bib2glsIf you want to switch to bib2gls, you first need to switch to glossaries-extra but replace xindy with +record:

    +
    \newacronym). -

    You can change the value of a given field using one of the following commands. Note that -these commands only change the value of the given field. They have no affect on any related -field. For example, if you change the value of the text field, it won’t modify the value given by -the name, plural, first or any other related key. -

    In all the four related commands below, ⟨label⟩ and ⟨field⟩ are as above and ⟨definition⟩ is the -new value of the field. -


    \glsfielddef  \glsfielddef{label}{field}{definition}

    -

    -This uses \def to change the value of the field (so it will be localised by any grouping). -


    \glsfieldedef  \glsfieldedef{label}{field}{definition}

    -

    -This uses \edef to change the value of the field (so it will be localised by any grouping). Any -fragile commands contained in the ⟨definition⟩ must be protected. -


    \glsfieldgdef  \glsfieldgdef{label}{field}{definition}

    -

    -This uses \gdef to change the value of the field. - - -


    \glsfieldxdef  \glsfieldxdef{label}{field}{definition}

    -

    -This uses \xdef to change the value of the field. Any fragile commands contained in the -⟨definition⟩ must be protected. - - +class="cmtt-10">\usepackage[record,postdot,stylemods,style=listgroup]{glossaries-extra} +

    +
    Note that you don’t need the nonumberlist option with bib2gls. You can instruct bib2gls to +simply not save the number lists, but in this case there won’t be any locations as there’s no actual +indexing. +

    The entries need to be converted to the bib format required by bib2gls: +

    
    +   
    convertgls2bib --preamble-only --texenc UTF-8 --bibenc UTF-8 sampleutf8.tex entries.bib +
    +
    +Note the first line of the entries.bib file:

    + + +
    +% Encoding: UTF-8 +
    +
    This is the encoding of the bib file. It doesn’t have to match the encoding of the tex file, but it’s generally +better to be consistent. When bib2gls parses this file, it will look for this encoding line. (If the --texenc and +--bibenc switches aren’t used, convertgls2bib will assume your system’s default encoding. See the bib2gls +manual for further details.) +

    Next replace \makeglossaries with:

    +
    +\GlsXtrLoadResources[src=entries,selection=all] +
    +
    and remove all the \newglossaryentry commands. +

    Iterative commands like \glsaddall don’t work with bib2gls. Instead, you can select all entries using the +selection=all option. This is actually better than \glsaddall, which enforces the selection of all entries by +indexing each entry. As a result, with makeindex and xindy (and Option 1), every entry will have the same +location (which is the location of the \glsaddall command, in this case page 1). With selection=all, +bib2gls will automatically selection all entries even if they don’t have any records (indexing information) so in +this case there are no number lists. +

    Finally, replace \printglossaries with \printunsrtglossaries. The build process is now: +

    
    +   
    pdflatex sampleutf8 +
    bib2gls --group sampleutf8 +
    pdflatex sampleutf8 +
    +
    +bib2gls picks up the encoding of the tex file from the aux file:

    +
    +\glsxtr@texencoding{utf8} +
    +
    If you experience any encoding issues, check the aux file for this command and check the bib file for the +encoding comment line. Also check bib2gls’s glg transcript file for encoding messages, which should look +like: + + +
    +TeX character encoding: UTF-8 +
    +

    +

    The document language, if it has been set, is also added to the aux file when the record option is used. In +this case, no language package has been used, so bib2gls will fallback on the system’s default locale. If no sort +method is set, the entries will be sorted according to the document language, if set, or the default +locale. You can specify a specific locale using the sort key with a locale tag identifier. For example: +

    +
    +\GlsXtrLoadResources[src=entries,selection=all,sort=de-CH-1996] +
    +
    (Swiss German new orthography) or:
    +
    +\GlsXtrLoadResources[src=entries,selection=all,sort=is] +
    +
    (Icelandic). +

    -

    -

    Top

    17. Prefixes or Determiners

    -

    The glossaries-prefix package that comes with the glossaries package provides additional -keys that can be used as prefixes. For example, if you want to specify determiners (such as -“a”, “an” or “the”). The glossaries-prefix package automatically loads the glossaries package -and has the same package options. -

    The extra keys for \newglossaryentry are as follows: -

    +

    Top

    19.10 No Indexing Application (Option 1)

    + +

    +

    +

    🔗sample-noidxapp.tex

    +

    This document illustrates how to use the glossaries package without an external indexing application +(Option 1). To create the complete document, you need to do: +

    
    +   
    pdflatex sample-noidxapp +
    pdflatex sample-noidxapp +
    +
    +Note the need to group the accent command that occurs at the start of the name:

    + + +
    prefix
    The prefix associated with the text key. This defaults to nothing. -
    +class="cmtt-10">\newglossaryentry{elite}{% +
      name={{\'e}lite}, +
      description={select group of people} +
    } +
    +
    This is necessary to allow the term to work with \Gls. Notice also how the number lists can’t be compacted +into ranges. For example, the list “1, 2, 3” would be converted to “1–3” with a proper indexing application +(Options 2 or 3 or, with glossaries-extra, Option 4). +

    The larger the list of entries, the longer the document build time. This method is very inefficient for large +glossaries. See Gallery: glossaries performance for a comparison. + +

    +

    +

    🔗sample-noidxapp-utf8.tex

    +

    As the previous example, except that it uses the inputenc package. To create the complete document, you need +to do: +

    
    +   
    pdflatex sample-noidxapp-utf8 +
    pdflatex sample-noidxapp-utf8 +
    +
    +This method is unsuitable for sorting languages with extended Latin alphabets or non-Latin alphabets. Use +Options 3 or 4 instead. +

    +

    +

    Top

    19.11 Other

    + +

    +

    +

    🔗sample4col.tex

    +

    This document illustrates a four column glossary where the entries have a symbol in addition to the name and +description. To create the complete document, you need to do: +

    
    +   
    pdflatex sample4col +
    makeglossaries sample4col +
    pdflatex sample4col + + +
    +
    +or +

    
    +   
    pdflatex sample4col +
    makeglossaries-lite sample4col +
    pdflatex sample4col +
    +
    +The vertical gap between entries is the gap created at the start of each group. This can be suppressed using the prefixplural
    The prefix associated with the plural key. This defaults to nothing. -
    +class="cmss-10">nogroupskip package option. (If you switch to bib2gls, simply omit the --group command line +option.) +

    This example uses the long4colheaderborder. This style doesn’t allow multi-line descriptions. You may prefer +to use altlong4colheaderborder with long descriptions. However, in either case a style that uses booktabs is +preferable. For example, long4col-booktabs or altlongragged4col-booktabs. Note that this requires prefixfirst

    The prefix associated with the first key. If omitted, this defaults to the value - of the prefix key. -
    +class="cmss-10">glossary-longbooktabs, which needs to be explicitly loaded. The style can only be set once this package has been +loaded:

    +
    prefixfirstplural
    The prefix associated with the firstplural key. If omitted, this defaults - to the value of the prefixplural key.
    - -

    Example 30 (Defining Determiners) -

    Here’s the start of my example document: - - -

    -
    -documentclass{article} - 
    \usepackage[colorlinks]{hyperref} - 
    \usepackage[toc,acronym]{glossaries-prefix} +class="cmtt-10">\usepackage{glossaries} +
    \usepackage{glossary-longbooktabs} +
    \setglossarystyle{altlongragged4col-booktabs}
    -

    Note that I’ve simply replaced glossaries from previous sample documents with glossaries-prefix. Now for a -sample definition17.1: - - -

    -
    -\newglossaryentry{sample}{name={sample},% - 
      description={an example},% - 
      prefix={a~},% - 
      prefixplural={the\space}% - 
    }
    -

    Note that I’ve had to explicitly insert a space after the prefix. This allows for the possibility -of prefixes that shouldn’t have a space, such as: - - -

    -
    -\newglossaryentry{oeil}{name={oeil}, - 
      plural={yeux}, - 
      description={eye}, - 
      prefix={l'}, - 
      prefixplural={les\space}} +


    glossaries-extraThe glossaries-extra package provides a more compact way of doing this with the stylemods +option:

    +
    +\usepackage[style=altlongragged4col-booktabs,stylemods=longbooktabs] +
    {glossaries-extra}
    -

    Where a space is required at the end of the prefix, you must use a spacing command, such as +

    The glossaries-extra package provides additional styles, including more “long” styles with the glossary-longextra +package. For example, the long-name-desc-sym-loc style:
    +
    \space, \␣ (backslash space) or ~ due to the automatic spacing trimming performed in -⟨key⟩=⟨value⟩ options. -

    The prefixes can also be used with acronyms. For example: - - +class="cmtt-10">\usepackage[style=long-name-desc-sym-loc,stylemods=longextra] +
    {glossaries-extra} +

    +
    If you use the stylemods option with an argument, you may prefer to use it with nostyles to prevent unwanted +styles from being automatically loaded. For example:
    + + +
    +\usepackage[style=long-name-desc-sym-loc,nostyles,stylemods=longextra] +
    {glossaries-extra} +
    +
    See also the gallery of predefined styles. + +

    -
    -\newacronym - 
     [% - 
       prefix={an\space},prefixfirst={a~}% - 
     ]{svm}{SVM}{support vector machine} +

    🔗sample-numberlist.tex

    +

    This document illustrates how to reference the number list in the document text. This requires an additional +LATEX run: +

    
    +   
    pdflatex sample-numberlist +
    makeglossaries sample-numberlist +
    pdflatex sample-numberlist +
    pdflatex sample-numberlist +
    +
    +This uses the savenumberlist package option, which enables \glsentrynumberlist and \glsdisplaynumberlist +(with limitations). The location counter is set to chapter, so the number list refers to the chapter +numbers. + + +

    +
    +\usepackage[savenumberlist,counter=chapter]{glossaries}
    -

    -
    -

    -

    ____________________________

    -

    The glossaries-prefix package provides convenient commands to use these prefixes with -commands such as \gls. Note that the prefix is not considered part of the link text, so it’s -not included in the hyperlink (where hyperlinks are enabled). The options and any star or -plus modifier are passed on to the \gls-like command. (See §6 Links to Glossary Entries for -further details.) -


    \pgls  \pgls[options]{label}[insert]

    -

    -This is inserts the value of the prefix key (or prefixfirst key, on first use) in front of \gls +

    The number list can’t be obtained until makeindex (or xindy) has created the glossary file. The number list is +picked up when this file is input by \printglossary and is then saved in the aux file so that it’s available on +the next LATEX run. +

    This document contains both commands:

    +
    [options]{label}[insert]. -


    \Pgls  \Pgls[options]{label}[insert]

    -

    -If the prefix key (or prefixfirst, on first use) has been set, this displays the value of that -key with the first letter converted to upper case followed by \gls[options]{label} +class="cmtt-10">This is a \gls{sample} document. \Glspl{sample} +
    are discussed in chapters~\glsdisplaynumberlist{sample} +
    (or \glsentrynumberlist{sample}). +

    +
    Without hyperref, the first list shows as “1–3, 5 & 6” and the second list shows as “1–3, 5, 6”. +

    Note that you can’t use \glsdisplaynumberlist with hyperref and Options 2 or 3. If you do, you will get +the warning: + + +

    +
    +Package glossaries Warning: \glsdisplaynumberlist doesn't work with + 
    hyperref. + 
    Using \glsentrynumberlist instead +
    +

    Now both lists show as “1–3, 5, 6”. +

    If you switch to Option 1 (replace \makeglossaries with \makenoidxglossaries and replace +\printglossaries with \printnoidxglossaries), then the document build is simply: +

    
    +   
    pdflatex sample-numberlist +
    pdflatex sample-numberlist +
    +
    +Now \glsdisplaynumberlist works with hyperref, however there are no ranges, so the first list shows as “1, 2, +3, 5, & 6” and the second list shows as “1, 2, 3, 4, 5, 6”. +

    bib2glsIf you want to switch to bib2gls, you first need to switch to glossaries-extra (at least v1.42) but +remember to include the record option:

    +
    [insert]. If that key hasn’t been set, this is equivalent to \Gls[options]{label\usepackage[record,counter=chapter]{glossaries-extra} +
    +
    Note that the savenumberlist option is no longer required. Next convert the entry to the bib format required by +bib2gls: +

    
    +   
    convertgls2bib sample-numberlist.tex entries.bib +
    +
    +Replace \makeglossaries with:

    +
    +\GlsXtrLoadResources[src=entries.bib] +
    +
    and remove the \newglossaryentry command from the document preamble. Finally, replace +\printglossaries with \printunsrtglossaries. The build process is now: +

    
    +   
    pdflatex sample-numberlist +
    bib2gls sample-numberlist +
    pdflatex sample-numberlist +
    +
    +Now both ranges and hyperlinks work. The first list shows “1–3, 5, & 6” and the second list shows “1–3, 5, 6”. +You can also use:

    + + +
    +\glsxtrfieldformatlist{sample}{loclist} +
    +
    which will show the complete list without ranges “1, 2, 3, 5 & 6”. +

    This method works much better than using the savenumberlist option because bib2gls saves the formatted +number list in the location field (which is an internal field provided by glossaries-extra for the benefit of +bib2gls) and the unformatted number list in the loclist internal field (which is also used by +Option 1). +

    With Options 2 and 3, both makeindex and xindy simply create a file containing the commands to typeset +the glossary, which is input by \printglossary. This means that it’s quite hard to gather information obtained +by the indexing application. +

    bib2gls, on the other hand, doesn’t write a file containing the glossary. It writes a file containing the entry +definitions and uses internal fields to save the indexing information. The glossary is then displayed with +\printunsrtglossary, which simply iterates over all defined entries and fetches the required information from +those internal fields. +

    The \glsdisplaynumberlist and \glsentrynumberlist commands are redefined by glossaries-extra-bib2gls +to simply access the location field. However, if you want a complete list without ranges you can use: +

    +
    +\glsxtrfieldformatlist{sample}{loclist} +
    +
    In this example, this produces “1, 2, 3, 5 & 6”. +

    Note the difference if you use the record=nameref package option instead of just record. + +

    +

    +

    🔗sample-nomathhyper.tex

    +

    This document illustrates how to selectively enable and disable entry hyperlinks in \glsentryfmt. The +document build is: +

    
    +   
    pdflatex sample-nomathhyper +
    makeglossaries sample-nomathhyper +
    pdflatex sample-nomathhyper +
    +
    +This disables the hyperlinks for the main glossary with:

    +
    [insert]. -


    \PGLS  \PGLS[options]{label}[insert]

    -

    -As \pgls but converts the prefix to upper case and uses \GLS instead of \gls. -


    \pglspl  \pglspl[options]{label}[insert]

    -

    -This is inserts the value of the prefixplural key (or prefixfirstplural key, on first use) in front of -\glspl[options]{label}[insert]. -


    \Pglspl  \Pglspl[options]{label}[insert]

    -

    -If the prefixplural key (or prefixfirstplural, on first use) has been set, this displays the value of -that key with the first letter converted to upper case followed by \glspl[options]{label\GlsDeclareNoHyperList{main} + + +

    +
    and then redefines \glsentryfmt so that it adds a hyperlink if not in maths mode and the hyperlinks haven’t +been forced off (with the hyper=false key). +


    glossaries-extraIf you want to switch to glossaries-extra, then you can instead use the hook that comes before +the keys are set. The preamble is much simpler:

    +
    +\usepackage{glossaries-extra} +
    +
    \makeglossaries +
    +
    \renewcommand{\glslinkpresetkeys}{% +
     \ifmmode \setkeys{glslink}{hyper=false}\fi +
    } +
    +
    % entry definition +
    +
    + +

    +

    +

    🔗sample-entryfmt.tex

    +

    This document illustrates how to change the way an entry is displayed in the text. (This is just a test document. +For a real document, I recommend you use the siunitx package to typeset units.) The document build +is: +

    
    +   
    pdflatex sample-entryfmt +
    makeglossaries sample-entryfmt +
    pdflatex sample-entryfmt +
    +
    +This redefines \glsentryfmt to add the symbol on first use:

    +
    [insert]. If that key hasn’t been set, this is equivalent to \Glspl[options]{label\renewcommand*{\glsentryfmt}{% +
      \glsgenentryfmt +
      \ifglsused{\glslabel}{}{\space (\glsentrysymbol{\glslabel})}% +
    } +
    +
    Note the use of \glsentrysymbol not \glssymbol (which would result in nested link text). +


    glossaries-extraIf you want to switch to the glossaries-extra package, you can make use of the category +post-link hook instead:

    + + +
    [insert]. -


    \PGLSpl  \PGLSpl[options]{label}[insert]

    -

    -As \pglspl but converts the prefix to upper case and uses \GLSpl instead of \glspl. - - +class="cmtt-10">\usepackage[stylemods,style=tree]{glossaries-extra} +
    +
    \makeglossaries +
    +
    \glsdefpostlink{unit}{\glsxtrpostlinkAddSymbolOnFirstUse} +
    +
    \newglossaryentry{distance}{ +
    category={unit}, +
    name=distance, +
    description={The length between two points}, +
    symbol={km}} +

    +
    Note that in this case the symbol is now outside of the hyperlink. -

    Example 31 (Using Prefixes) -

    Continuing from Example 30, now that I’ve defined my entries, I can use them in the text -via the above commands: - - + id="x1-222009r39"> +

    -
    -First use: \pgls{svm}. Next use: \pgls{svm}. - 
    Singular: \pgls{sample}, \pgls{oeil}. - 
    Plural: \pglspl{sample}, \pglspl{oeil}. +

    🔗sample-prefix.tex

    +

    This document illustrates the use of the glossaries-prefix package. An additional run is required to ensure the +table of contents is up-to-date: +

    
    +   
    pdflatex sample-prefix +
    makeglossaries sample-prefix +
    pdflatex sample-prefix +
    pdflatex sample-prefix +
    +
    +Remember that the default separator between the prefix and \gls (or one of its variants) is empty, so if a space +is required it must be inserted at the end of the prefix. However, the xkeyval package (which is used to parse the +⟨key=value⟩ lists) trims leading and trailing space from the values, so an ordinary space character will be lost. +

    +
    +\newglossaryentry{sample}{name={sample}, +
      description={an example}, +
      prefix={a~}, +
      prefixplural={the\space}% +
    } +
    +
    \newglossaryentry{oeil}{name={oeil}, +
      plural={yeux}, + + +
      description={eye}, +
      prefix={l'}, +
      prefixplural={les\space}}
    -

    which produces: -

    -

    First use: a support vector machine (SVM). Next use: an SVM. Singular: - a sample, l’oeil. Plural: the samples, les yeux.

    -

    For a complete document, see sample-prefix.tex.

    -
    -

    -

    ____________________________

    -

    This package also provides the commands described below, none of which perform any -check to determine the entry’s existence. -


    \ifglshasprefix  \ifglshasprefix{label}{true part}{false part}

    -

    -Does ⟨true part⟩ if the entry identified by ⟨label⟩ has a non-empty value for the prefix -key. -

    This package also provides the following commands: -


    \ifglshasprefixplural  \ifglshasprefixplural{label}{true part}{false part +


    glossaries-extraIf you want to convert this example to use glossaries-extra, then (as from v1.42) you can use +the prefix option:

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

    -

    -Does ⟨true part⟩ if the entry identified by ⟨label⟩ has a non-empty value for the prefixplural -key. -


    \ifglshasprefixfirst  \ifglshasprefixfirst{label}{true part}{false part +
    (Alternatively load glossaries-prefix after glossaries-extra.) The rest of the document is the same as for the base +glossaries package, unless you want to switch to using bib2gls. +

    bib2glsIf you want to switch to bib2gls, first switch to glossaries-extra (as above) but make sure you +include the record package option:

    +
    +\usepackage[record,prefix,postdot,acronym]{glossaries-extra} +
    +
    Next convert the entries into the bib format required by bib2gls: +

    
    +   
    convertgls2bib --preamble-only sample-prefix.tex entries.bib +
    +
    +Replace \makeglossaries with

    +
    +\setabbreviationstyle[acronym]{long-short} +
    \GlsXtrLoadResources[src=entries] +
    +
    remove the entry definitions from the preamble, and replace
    +
    +\printglossary[style=plist] +
    \printacronyms +
    +
    with
    +
    +\printunsrtglossary[style=plist] +
    \printunsrtacronyms + + +
    +
    The document build is now: +

    
    +   
    pdflatex sample-prefix +
    bib2gls sample-prefix +
    pdflatex sample-prefix +
    +
    +

    With bib2gls v2.0+, you don’t need to manually insert the spaces at the end of the prefixes. Instead you +can instruct bib2gls to insert them. To try this out, remove the trailing ~ and \space from the entries.bib +file:

    +
    +@entry{sample, +
      prefix = {a}, +
      name = {sample}, +
      description = {an example}, +
      prefixplural = {the} +
    } -

    -

    -Does ⟨true part⟩ if the entry identified by ⟨label⟩ has a non-empty value for the prefixfirst -key. -


    \ifglshasprefixfirstplural  \ifglshasprefixfirstplural{label}{true part +
    @entry{oeil, +
      plural = {yeux}, +
      prefix = {l'}, +
      name = {oeil}, +
      description = {eye}, +
      prefixplural = {les} +
    } -{false part}

    -

    -Does ⟨true part⟩ if the entry identified by ⟨label⟩ has a non-empty value for the prefixfirstplural -key. -


    \glsentryprefix  \glsentryprefix{label}

    -

    -Displays the value of the prefix key for the entry given by ⟨label⟩. -


    \glsentryprefixfirst  \glsentryprefixfirst{label}

    -

    -Displays the value of the prefixfirst key for the entry given by ⟨label⟩. - - -


    \glsentryprefixplural  \glsentryprefixplural{label}

    -

    -Displays the value of the prefixplural key for the entry given by ⟨label⟩. (No check is performed -to determine if the entry exists.) -


    \glsentryprefixfirstplural  \glsentryprefixfirstplural{label}

    -

    -Displays the value of the prefixfirstplural key for the entry given by ⟨label⟩. (No check is -performed to determine if the entry exists.) -

    There are also variants that convert the first letter to upper -case17.2: -


    \Glsentryprefix  \Glsentryprefix{label}

    -

    -


    \Glsentryprefixfirst  \Glsentryprefixfirst{label}

    -

    -


    \Glsentryprefixplural  \Glsentryprefixplural{label}

    -

    -


    \Glsentryprefixfirstplural  \Glsentryprefixfirstplural{label}

    -

    -

    As with analogous commands such as \Glsentrytext, these commands aren’t -expandable so can’t be used in PDF bookmarks.
    -

    +
    +
    @acronym{svm, +
      prefixfirst = {a}, +
      prefix = {an}, +
      short = {SVM}, +
      long = {support vector machine} +
    } +

    +
    Now add the append-prefix-field={space or nbsp} resource option:
    +
    +\GlsXtrLoadResources[src=entries,append-prefix-field={space or nbsp}] +
    +
    See the bib2gls manual for further details. -

    Example 32 (Adding Determiner to Glossary Style) -

    You can use the above commands to define a new glossary style that uses the determiner. -For example, the following style is a slight modification of the list style that inserts the prefix -before the name: - - + id="x1-223025r40"> + + +

    -
    -\newglossarystyle{plist}{% - 
      \setglossarystyle{list}% - 
      \renewcommand*{\glossentry}[2]{% - 
        \item[\glsentryitem{##1}% - 
              \Glsentryprefix{##1}% - 
              \glstarget{##1}{\glossentryname{##1}}] - 
           \glossentrydesc{##1}\glspostdescription\space ##2}% +

    🔗sampleaccsupp.tex

    +

    This document uses the glossaries-accsupp package (see §18 Accessibility Support). That package automatically +loads glossaries and passes all options to the base package. So you can load both packages at once with +just: + + +

    +
    +\usepackage[acronym]{glossaries-accsupp} +
    +

    This provides additional keys that aren’t available with just the base package, which may be used to provide +replacement text. The replacement text is inserted using accsupp’s \BeginAccSupp and \EndAccSupp +commands. See the accsupp package for further details of those commands. +

    Note that this example document is provided to demonstrate glossaries-accsupp as succinctly as possible. The +resulting document isn’t fully accessible as it’s not tagged. See the accessibility and tagpdf packages for further +information about tagging documents. +

    It’s not essential to use glossaries-accsupp. You can simply insert the replacement text directly into the field +values. For example: + + +

    +
    +\newglossaryentry{Drive}{ + 
     name={\BeginAccSupp{Actual=Drive}Dr.\EndAccSupp{}}, + 
     description={Drive} + 
    } + 
    \newglossaryentry{image}{name={sample image}, + 
     description={an example image}, + 
     user1={\protect\BeginAccSupp{Alt={a boilerplate image used in + 
      examples}}\protect\includegraphics + 
      [height=20pt]{example-image}\protect\EndAccSupp{}}  
    }
    -

    -
    -

    -

    ____________________________

    - - -

    -

    Top

    18. Accessibility Support

    -

    Limited accessibility support is provided by the accompanying

    However, this can cause interference (especially with case-changing). With glossaries-accsupp package, -but note that this package is experimental and it requires the accsupp package which is also -listed as experimental. This package defines additional keys that may be used when defining -glossary entries. The keys are as follows: -

    -access
    The replacement text corresponding to the name key. -
    -textaccess
    The replacement text corresponding to the text key. -
    + id="dx1-224010"> it’s possible to +obtain the field values without the accessibility information if required. (If in the future \includegraphics is +given extra options to provide replacement text then the image example here won’t be necessary. However, the +example can be adapted for images created with TEX code.) +

    The acronym style is set using: + + +

    +
    +\setacronymstyle{long-short} +
    +

    The first abbreviation is straightforward: + + +

    +
    +\newacronym{eg}{e.g.}{for example} +
    +

    The shortaccess replacement text is automatically set to the long form. The next abbreviation is awkward as +the long form contains formatting commands which can’t be included in the replacement text. This means that +the shortaccess key must be supplied:

    +
    firstaccess
    The replacement text corresponding to the first key. -
    +class="cmtt-10">\newacronym[shortaccess={TiKZ ist kein Zeichenprogramm}] +
    {tikz}{Ti\emph{k}Z}{Ti\emph{k}Z ist \emph{kein} Zeichenprogramm} +
    +
    In the above two cases, the short form obtained in \gls will use the “E” PDF element. +

    By way of comparison, there are some entries that are technically abbreviations but are defined using pluralaccess

    The replacement text corresponding to the plural key. -
    +class="cmtt-10">\newglossaryentry instead of \newacronym. The replacement text is provided in the access key: +

    +
    firstpluralaccess
    The replacement text corresponding to the firstplural key. -
    +class="cmtt-10">\newglossaryentry{Doctor}{name=Dr,description={Doctor},access={Doctor}} +
    \newglossaryentry{Drive}{name={Dr.},plural={Drvs},description={Drive}, +
      access={Drive}} +
    +
    These will use PDF’s “ActualText” element (not “E”). +

    The next entry is a symbol (the integration symbol + ). This could be defined simply as: + + +

    +
    +\newglossaryentry{int}{name={int},description={integral}, + 
     symbol={\ensuremath{\int}}} +
    +

    and then referenced in the text like this: + + +

    +
    +Symbol: \gls{int} (\glssymbol{int}). +
    +

    This results in the text “Symbol: integral ( + ).” However if you copy and paste this from the PDF you will +find the resulting text is “Symbol: int (R).” This is what’s actually read out by the text-to-speech +system. +

    It would be better if the actual text was the Unicode character 0x222B. This would not only assist the +text-to-speech system but also make it easier to copy and paste the text. The simplest method is to identify the +character by its hexadecimal code, but in order to do this the \BeginAccSupp command needs to have the +options adjusted. +

    In order to determine whether to use “E”, “ActualText” or “Alt” for a particular field, glossaries-accsupp will +check if the command \glsfieldaccsupp exists (where ⟨field⟩ is the internal field label, see table 4.1). Only two +of these commands are predefined: \glsshortaccsupp and \glsshortplaccsupp, which is why the +shortaccess field uses “E”. If the given command doesn’t exist then the generic \glsaccsupp command is used +instead. +

    This means that in order to simply set symbolaccess to the hexadecimal character code, I need to provide a +command called \glssymbolaccsupp:

    +
    symbolaccess
    The replacement text corresponding to the symbol key. -
    +class="cmtt-10">\newcommand{\glssymbolaccsupp}[2]{% +
     \glsaccessibility[method=hex,unicode]{ActualText}{#1}{#2}% +
    } +
    +
    Now I can adjust the definition of the int entry:
    +
    symbolpluralaccess
    The replacement text corresponding to the symbolplural key. -
    +class="cmtt-10">\newglossaryentry{int}{name={int},description={integral}, +
      symbol={\ensuremath{\int}},symbolaccess={222B} +
    } +
    +
    +

    The final entry has an image stored in the user1 key. (The image file is provided with the mwe +package.) This should use “Alt” instead of “ActualText” so I need to define \glsuseriaccsupp: +

    +
    descriptionaccess
    The replacement text corresponding to the description key. -
    +class="cmtt-10">\newcommand{\glsuseriaccsupp}[2]{% +
      \glsaccessibility{Alt}{#1}{#2}% +
    } + + +
    +
    The image description is provided in the user1access key:
    +
    descriptionpluralaccess
    The replacement text corresponding to the descriptionplural - key. -
    +class="cmtt-10">\newglossaryentry{sampleimage}{name={sample image}, +
     description={an example image}, +
     user1={\protect\includegraphics[height=20pt]{example-image}}, +
     user1access={a boilerplate image used in examples} +
    } +
    +
    (Note the need to protect the fragile \includegraphics. The alternative is to use \glsnoexpandfields before +defining the command. See §4.4 Expansion.) +

    If you try this example and inspect the +PDF19.4 then +you will find content like: + + +

    +
    +/Span << /ActualText (Doctor) >> BDC + 
      BT + 
        /F8 9.9626 Tf + 
        73.102 697.123 Td + 
        [ (Dr) ] TJ + 
      ET + 
    EMC +
    +

    This shows that “ActualText” was used for \gls{Doctor}. The integral symbol ( + ) created with +\glssymbol{int} is: + + +

    +
    +/Span << /ActualText (\376\377"+) >> BDC + 
      BT + 
        /F1 9.9626 Tf + 
        97.732 650.382 Td + 
        [ (R) ] TJ + 
      ET + 
    EMC +
    +

    Again, “ActualText” has been used, but the character code has been supplied. The image created with +\glsuseri{sampleimage} is: + + +

    +
    +/Span << /Alt (a boilerplate image used in examples) >> BDC + 
      1 0 0 1 106.588 618.391 cm + 
      q + 
        0.08301 0 0 0.08301 0 0 cm + 
        q + 
          1 0 0 1 0 0 cm + 
          /Im1 Do + 
        Q + 
      Q + 
    EMC +
    +

    This shows that “Alt” has been used. +

    The first use of \gls{eg} produces the long form (not reproduced here) followed by the short +form: + + +

    +
    +/Span << /E (for example) >> BDC + 
      BT + 
        /F8 9.9626 Tf + 
        161.687 563.624 Td + 
        [ (e.g.) ] TJ + 
      ET + 
    EMC +
    +

    The subsequent use also has the “E” element: + + +

    +
    +/Span << /E (for example) >> BDC + 
      BT + 
        /F8 9.9626 Tf + 
        118.543 551.669 Td + 
        [ (e.g.) ] TJ + 
      ET + 
    EMC +
    +

    Similarly for \acrshort{eg}. You can also use the debug=showaccsupp package option. This will show +the replacement text in the document, but note that this is the content before it’s processed by +\BeginAccSupp. +

    If the \setacronymstyle command is removed (or commented out) then the result would be different. The +first use of \gls uses “E” for the short form but the subsequent use has “ActualText” instead. This is because +without \setacronymstyle the original acronym mechanism is used, which is less sophisticated than the newer +acronym mechanism that’s triggered with \setacronymstyle. +

    If you want to convert this example so that it uses glossaries-extra, make sure you have at least version 1.42 +of the extension package.
    +

    +


    glossaries-extraIf you want to convert this example so that it uses glossaries-extra, you need to replace the +explicit loading of glossaries-accsupp with an implicit load through the accsupp package option: +

    +
    longaccess
    The replacement text corresponding to the long key (used by \usepackage[abbreviations,accsupp]{glossaries-extra} +
    +
    I’m switching from \newacronym). -
    + id="dx1-224040"> to \newabbreviation, which means that the default category is abbreviation +and also the file extensions are different. If you are using makeglossaries or makeglossaries-lite you don’t +need to worry about it. However, if you’re not using those helper scripts then you will need to adjust the file +extensions in your document build process. +

    The style command \setacronymstyle{long-short} needs to be replaced with:

    +
    shortaccess
    The replacement text corresponding to the short key (used by - \setabbreviationstyle{long-short} +
    +
    This is actually the default so you can simply delete the \setacronymstyle line. Substitute the two instances +of \newacronym). -
    + id="dx1-224046"> with \newabbreviation. For example:
    +
    +\newabbreviation{eg}{e.g.}{for example} + + +
    +
    Note that for the tikz entry you can now remove the explicit assignment of shortaccess with glossaries-extra +v1.42 as it will strip formatting commands like \emph:
    +
    +\newabbreviation +
     {tikz}{Ti\emph{k}Z}{Ti\emph{k}Z ist \emph{kein} Zeichenprogramm} +
    +
    It’s also necessary to replace \acrshort, \acrlong and \acrfull with \glsxtrshort, \glsxtrlong and +\glsxtrfull. +

    You may notice a slight difference from the original example. The shortaccess field now shows ⟨long⟩ (⟨short⟩) +instead of just ⟨long⟩. This is because glossaries-extra redefines \glsdefaultshortaccess to include the short +form. +

    Now that the extension package is being used, there are some other modifications that would tidy up the +code and fix a few issues. +

    The “Doctor” and “Drive” entries should really be defined as abbreviations but they shouldn’t be +expanded on first use. The short-nolong style can achieve this and it happens to be the default style +for the acronym category. This means that you can simply replace the “Doctor” definition with: +

    +
    longpluralaccess
    The replacement text corresponding to the longplural key (used by - \newacronym). -
    + id="dx1-224058">{Doctor}{Dr}{Doctor} +
    +
    The first use of \gls{Doctor} is just “Dr”. This means that the “E” element will be used instead +of “ActualText”. Now I don’t need to supply the accessibility text as its obtained from the long +form. +

    The “Drive” entry can be similarly defined but it has the awkward terminating full stop. This means that I +had to omit the end of sentence terminator in: + + +

    +
    +\gls{Doctor} Smith lives at 2, Blueberry \gls{Drive} +
    +

    This looks odd when reading the document source and it’s easy to forgot. This is very similar to the situation +in the sample-dot-abbr.tex example. I can again use the discardperiod attribute, but I need to assign a +different category so that it doesn’t interfere with the “Doctor” entry. +

    The category is simply a label that’s used in the construction of some internal command names. This means +that it must be fully expandable, but I can choose whatever label I like (general, abbreviation, acronym, index, +symbol and number are used by various commands provided by glossaries-extra). +

    In this case, I’ve decided to have a category called shortdotted to indicate an abbreviation that ends with a +dot but only the short form is shown on first use:

    +
    +\setabbreviationstyle[shortdotted]{short-nolong-noreg} +
    \glssetcategoryattribute{shortdotted}{discardperiod}{true} +
    \newabbreviation[category=shortdotted]{Drive}{Dr.\@}{Drive} +
    +
    In the sample-dot-abbr.tex example, I also used the insertdots attribute to automatically insert the dots and +add the space factor (which is adjusted if discardperiod discards a period). In this case I’m inserting the dot +manually so I’ve also added the space factor with \@ in case the abbreviation is used mid-sentence. For +example: + + +
    +\gls{Doctor} Smith lives at 2, Blueberry \gls{Drive}. Next sentence. + 
    \gls{Doctor} Smith lives at 2, Blueberry \gls{Drive} end of sentence. +
    +

    (The spacing is more noticeable if you first switch to a monospaced font with \ttfamily.) +

    The “e.g.” abbreviation similarly ends with a dot. It’s not usual to write “for example (e.g.)” in a +document, so it really ought to have the same shortdotted category, but it has a long-short form for illustrative +purposes in this test document. In this case I need to choose another category so that I can apply a different +style. For example:

    +
    +\setabbreviationstyle[longshortdotted]{long-short} +
    \glssetcategoryattribute{longshortdotted}{discardperiod}{true} +
    \newabbreviation[category=longshortdotted]{e.g.}{e.g.\@}{for +
    example} +
    +
    +

    To further illustrate categories, let’s suppose the symbol and image should be in the name field instead of the +symbol and user1 fields. Now the \glssymbolaccsupp and \glsuseriaccsupp commands won’t be used. I +can’t deal with both cases if I just provide \glsnameaccsupp. +

    I could provide category-field versions, such as \glsxtrsymbolnameaccsupp, but remember that this only +covers accessing the name field, which is typically only done in the glossary. I would also need similar commands +for the first, firstplural, text and plural keys. This is quite complicated, but since I don’t need to worry +about any of the other fields it’s simpler to just provide the \glsxtrcategoryaccsupp version: +

    +
    shortpluralaccess
    The replacement text corresponding to the shortplural key (used by - \newacronym). -
    -

    For example: - - -

    -
    -\newglossaryentry{tex}{name={\TeX},description={Document - 
    preparation language},access={TeX}} +class="cmtt-10">\newcommand{\glsxtrsymbolaccsupp}[2]{% +
     \glsaccessibility[method=hex,unicode]{ActualText}{#1}{#2}% +
    } +
    \newcommand{\glsxtrimageaccsupp}[2]{% +
      \glsaccessibility{Alt}{#1}{#2}% +
    } +
    +
    \newglossaryentry{int}{category=symbol, +
      name={\ensuremath{\int}},access={222B}, +
      description={integral} +
    } +
    +
    \newglossaryentry{sampleimage}{category=image, + + +
     description={an example image}, +
     name={\protect\includegraphics[height=20pt]{example-image}}, +
     access={a boilerplate image used in examples} +
    }
    -

    Now \gls{tex} will be equivalent to - - +

    If it’s necessary to provide support for additional fields, then the category-field command +\glsxtrcategory⟩⟨fieldaccsupp could be used to override the more general category command +\glsxtrcategoryaccsupp. + +

    -
    -\BeginAccSupp{ActualText=TeX}\TeX\EndAccSupp{} +

    🔗sample-ignored.tex

    +

    This document defines an ignored glossary for common terms that don’t need a definition. The document build +is: +

    
    +   
    pdflatex sample-ignored +
    makeglossaries sample-ignored +
    pdflatex sample-ignored +
    +
    +A new “ignored” glossary is defined with:

    +
    +\newignoredglossary{common} +
    +
    There are no associated files with an ignored glossary. An entry is defined with this as its glossary +type: + + +
    +\newglossaryentry{commonex}{type=common,name={common term}} +
    +

    Note that the description key isn’t required. This term may be referenced with \gls (which is useful for +consistent formatting) but it won’t be indexed. + +

    +

    +

    🔗sample-entrycount.tex

    +

    This document uses \glsenableentrycount and \cgls (described in §14.1 Counting the Number of Times an +Entry has been Used (First Use Flag Unset)) so that acronyms only used once don’t appear in the list of +acronyms. The document build is: +

    
    +   
    pdflatex sample-entrycount +
    pdflatex sample-entrycount +
    makeglossaries sample-entrycount +
    pdflatex sample-entrycount +
    +
    +Note the need to call LATEX twice before makeglossaries, and then a final LATEX call is required at the +end. +

    The glossaries-extra package has additions that extend this mechanism and comes with some other sample +files related to entry counting.
    +

    +

    If you switch to bib2gls you can use record counting instead. See the bib2gls manual for further details.
    -

    The sample file sampleaccsupp.tex illustrates the glossaries-accsupp package. -

    See the documented code (glossaries-code.pdf) for further details. I recommend that -you also read the accsupp documentation. - - +

    + +

    -

    -

    Top

    19.

    +

    Top

    20. Troubleshooting

    -

    In addition to the sample files listed in §1.2

    In addition to the sample files listed in §19 Sample Documents, the glossaries package -comes with some minimal example files, glossaries package comes with some +minimal example files, minimalgls.tex, mwe-gls.tex, mwe-acr.tex and -mwe-acr-desc.tex, which can be used for testing. These should be located in the samples -subdirectory (folder) of the glossaries documentation directory. The location varies according to -your operating system and TEX installation. For example, on my Linux partition it can be found -in /usr/local/texlive/2014/texmf-dist/doc/latex/glossaries/. The mwe-acr.tex and mwe-acr-desc.tex, which can be +used for testing. These should be located in the samples subdirectory (folder) of the glossaries documentation +directory. The location varies according to your operating system and TEX installation. For example, on my +Linux partition it can be found in /usr/local/texlive/2014/texmf-dist/doc/latex/glossaries/. The +makeglossariesgui -application can also be used to test for various problems. Further information on debugging -LAT application can also be used to test for various problems. Further information on +debugging LATEX code is available at http://www.dickimaw-books.com/latex/minexample/. -

    If you have any problems, please first consult the

    If you have any problems, please first consult the glossaries FAQ. If that doesn’t -help, try posting your query to somewhere like the comp.text.tex newsgroup, the -glossaries FAQ. If that doesn’t help, try posting your query +to somewhere like the comp.text.tex newsgroup, the LATEX Community Forum or TEX on StackExchange. Bug reports can be submitted via -EX on StackExchange. +Bug reports can be submitted via my package bug report form. - - + +

    Top

    Index

    - Index + Symbols
    \’  1
    +\@  2, 3, 4, 5, 6
    +\@gls@codepage  1
    +href="glossaries-user.html#dx1-22020" >7
    +\@gls@reference  8
    \@glsorder  2
    +href="glossaries-user.html#dx1-22017" >9
    +\@glsxtr@altmodifier  10
    +\@glsxtr@newglslike  11
    +\@glsxtr@prefixlabellist  12
    \@istfilename  3
    +href="glossaries-user.html#dx1-22005" >13
    \@newglossary  4
    +href="glossaries-user.html#dx1-22001" >14
    \@xdylanguage  5
    -

    15
    +

    A +\AA  16
    +abbreviation styles:
    +    footnote  17
    +    long-short  18, 19, 20
    +    long-short-sc  21
    +    long-short-sc-desc  22
    +    postfootnote  23
    +    short-nolong  24, 25
    +    short-sc-footnote  26
    +    short-sc-footnote-desc  27, 28, 29, 30
    +    short-sc-postfootnote-desc  31, 32, 33, 34
    +\Ac  35
    +\ac  36
    +accessibility package  37, 38, 39
    accsupp package  6, 7
    +href="glossaries-user.html#dx1-172002" >40, 41, 42, 43, 44
    +\Acf  45
    +\acf  46
    +\Acfp  47
    +\acfp  48
    + + +\Acl  49
    +\acl  50
    +\Aclp  51
    +\aclp  52
    +\Acp  53
    +\acp  54
    \ACRfull  8
    +href="glossaries-user.html#dx1-147080" >55
    \Acrfull  9
    +href="glossaries-user.html#dx1-147079" >56, 57
    \acrfull  10
    +href="glossaries-user.html#dx1-147076" >58, 59, 60, 61, 62, 63, 64, 65, 66
    \acrfullfmt  11
    +href="glossaries-user.html#dx1-147077" >67, 68, 69
    \acrfullformat  12
    +href="glossaries-user.html#dx1-147078" >70, 71
    \ACRfullpl  13
    +href="glossaries-user.html#dx1-147083" >72
    \Acrfullpl  14
    +href="glossaries-user.html#dx1-147082" >73, 74
    \acrfullpl  15
    +href="glossaries-user.html#dx1-147081" >75, 76
    \ACRlong  16
    +href="glossaries-user.html#dx1-147069" >77
    \Acrlong  17
    +href="glossaries-user.html#dx1-147068" >78, 79
    \acrlong  18
    +href="glossaries-user.html#dx1-147064" >80, 81, 82, 83, 84
    \ACRlongpl  19
    +href="glossaries-user.html#dx1-147072" >85
    \Acrlongpl  20
    +href="glossaries-user.html#dx1-147071" >86, 87
    \acrlongpl  21
    +href="glossaries-user.html#dx1-147070" >88, 89
    acronym styles:
        dua  22, 23, 24, 25
    +href="glossaries-user.html#dx1-149019" >90, 91, 92, 93
        dua-desc  26, 27
    +href="glossaries-user.html#dx1-149054" >94, 95
        footnote  28, 29, 30
    +href="glossaries-user.html#dx1-149020" >96, 97, 98
        footnote-desc  31
    +href="glossaries-user.html#dx1-149074" >99
        footnote-sc  32
    +href="glossaries-user.html#dx1-149065" >100
        footnote-sc-desc  33, 34, 35, 36
    +href="glossaries-user.html#dx1-149075" >101, 102, 103, 104, 105
        footnote-sm  37
    +href="glossaries-user.html#dx1-149066" >106
        footnote-sm-desc  38
    +href="glossaries-user.html#dx1-149076" >107
        long-sc-short  39, 40, 41, 42
    - - +href="glossaries-user.html#dx1-149007" >108, 109, 110, 111, 112
        long-sc-short-desc  43
    +href="glossaries-user.html#dx1-149037" >113, 114
        long-short  44, 45, 46, 47, 48, 49
    +href="glossaries-user.html#dx1-135069" >115, 116, 117, 118, 119, 120
        long-short-desc  50, 51, 52
    +href="glossaries-user.html#dx1-149036" >121, 122, 123
        long-sm-short  53, 54, 55
    +href="glossaries-user.html#dx1-149012" >124, 125, 126
        long-sm-short-desc  56
    +href="glossaries-user.html#dx1-149038" >127
        long-sp-short  57, 58, 59
    +href="glossaries-user.html#dx1-149024" >128, 129, 130
        long-sp-short-desc  60
    +href="glossaries-user.html#dx1-149039" >131
        sc-short-long  61
    +href="glossaries-user.html#dx1-149031" >132
        sc-short-long-desc  62
    +href="glossaries-user.html#dx1-149050" >133
        short-long  63
    +href="glossaries-user.html#dx1-149030" >134
        short-long-desc  64
    +href="glossaries-user.html#dx1-149049" >135
        sm-short-long  65
    +href="glossaries-user.html#dx1-149032" >136
        sm-short-long-desc  66
    +href="glossaries-user.html#dx1-149051" >137
    \acronymentry  67
    +href="glossaries-user.html#dx1-148010" >138, 139, 140, 141, 142, 143
    \acronymfont  68
    +href="glossaries-user.html#dx1-98004" >144, 145, 146, 147, 148, 149, 150, 151, 152, 153, 154
    +\acronymname  155, 156
    + + \acronymsort  69
    +href="glossaries-user.html#dx1-148012" >157, 158, 159, 160, 161
    \acronymtype  70
    +href="glossaries-user.html#dx1-43007" >162, 163, 164, 165, 166, 167, 168, 169, 170, 171, 172, 173, 174
    \ACRshort  71
    +href="glossaries-user.html#dx1-147058" >175
    \Acrshort  72
    +href="glossaries-user.html#dx1-147057" >176, 177
    \acrshort  73
    +href="glossaries-user.html#dx1-147052" >178, 179, 180, 181, 182, 183, 184
    \ACRshortpl  74
    +href="glossaries-user.html#dx1-147061" >185
    \Acrshortpl  75
    +href="glossaries-user.html#dx1-147060" >186, 187
    \acrshortpl  76
    +href="glossaries-user.html#dx1-147059" >188, 189
    +\Acs  190
    +\acs  191
    +\Acsp  192
    +\acsp  193
    +\addcontentsline  194
    +\alsoname  195
    \altnewglossary  77
    +href="glossaries-user.html#dx1-146008" >196
    amsgen package  78, 79, 80, 81, 82
    +href="glossaries-user.html#dx1-13" >197, 198, 199, 200, 201
    amsmath package  83, 84
    +href="glossaries-user.html#dx1-133006" >202, 203
    +\andname  204
    arara  85, 86, 87, 88
    +href="glossaries-user.html#dx1-4018" >205, 206, 207, 208, 209, 210, 211, 212, 213
    array package  89, 90
    -

    214, 215
    +\AtBeginDocument  216
    +atom  217
    +auto-completion  218
    +

    B +\babel  219
    babel package  91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117
    +href="glossaries-user.html#dx1-7018" >220, 221, 222, 223, 224, 225, 226, 227, 228, 229, 230, 231, 232, 233, 234, 235, 236, 237, 238, 239, 240, 241, 242, 243, 244, 245, 246, 247, 248, 249
    beamer class  118, 119, 120, 121
    +href="glossaries-user.html#dx1-133004" >250, 251, 252, 253
    beamer package  122
    -254
    +\BeginAccSupp  255, 256, 257, 258
    +bib2gls  123, 124, 259, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140, 141, 142, 143, 144, 145, 146, 147, 148, 149, 150, 151, 152, 153
    +class="cmbx-10">260
    , 261, 262, 263, 264, 265, 266, 267, 268, 269, 270, 271, 272, 273, 274, 275, 276, 277, 278, 279, 280, 281, 282, 283, 284, 285, 286, 287, 288, 289, 290, 291, 292, 293, 294, 295, 296, 297, 298, 299, 300, 301, 302, 303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315, 316, 317, 318, 319, 320, 321, 322, 323, 324, 325, 326, 327, 328, 329, 330, 331, 332, 333, 334, 335, 336, 337, 338, 339, 340, 341, 342, 343, 344, 345, 346, 347, 348, 349, 350, 351, 352, 353, 354, 355, 356, 357, 358, 359, 360, 361, 362, 363, 364, 365, 366, 367, 368, 369, 370, 371, 372, 373, 374, 375, 376, 377, 378, 379, 380, 381, 382, 383, 384, 385, 386, 387, 388, 389, 390, 391, 392, 393, 394, 395, 396, 397, 398, 399, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418, 419, 420, 421, 422, 423, 424, 425, 426, 427, 428, 429, 430, 431, 432, 433, 434, 435, 436, 437, 438, 439, 440, 441, 442, 443, 444, 445, 446, 447, 448, 449, 450, 451, 452, 453, 454, 455, 456, 457, 458, 459, 460, 461, 462, 463, 464, 465, 466, 467, 468, 469, 470, 471, 472, 473, 474, 475, 476, 477, 478, 479, 480
    +    --group  481, 482, 483, 484, 485
    +    --map-format  486
    +    -g  487
    +    -m  488
    +bib2gls entry types
    +    @abbreviation  489, 490, 491, 492, 493, 494, 495
    +    @acronym  496, 497, 498, 499, 500, 501, 502, 503
    +    @dualabbreviationentry  504, 505, 506
    +    @dualentry  507, 508, 509
    +    @dualindexabbreviation  510, 511
    +    @entry  512, 513, 514, 515, 516, 517, 518, 519, 520, 521, 522, 523, 524, 525, 526, 527, 528, 529, 530, 531, 532, 533, 534, 535, 536, 537, 538, 539, 540, 541, 542, 543, 544, 545, 546, 547, 548, 549, 550, 551, 552
    + + +    @index  553, 554, 555, 556, 557, 558, 559, 560, 561, 562, 563
    +    @indexplural  564, 565, 566, 567
    +    @preamble  568, 569, 570, 571, 572, 573, 574, 575
    +    @symbol  576, 577, 578, 579, 580, 581, 582, 583, 584, 585, 586, 587, 588, 589
    booktabs package  154, 155, 156
    -

    590, 591, 592, 593
    +\bottomrule  594
    +

    C +categories
    +    abbreviation  595, 596, 597, 598, 599, 600, 601, 602, 603
    +    acronym  604, 605, 606, 607, 608, 609, 610, 611, 612, 613, 614, 615, 616
    +    general  617, 618, 619, 620
    +    index  621
    +    number  622
    +    symbol  623, 624, 625
    +category attributes  626
    +    discardperiod  627, 628, 629, 630, 631
    +    glossdesc  632, 633, 634, 635, 636
    +    glossdescfont  637
    +    glossname  638
    +    glosssymbolfont  639
    +    hyperoutside  640
    +    indexonlyfirst  641
    +    insertdots  642, 643, 644, 645, 646
    +    nohyperfirst  647
    +    noshortplural  648
    +    pluraldiscardperiod  649
    +    retainfirstuseperiod  650
    +    textformat  651
    \cGls  157
    +href="glossaries-user.html#dx1-154011" >652
    \cgls  158
    +href="glossaries-user.html#dx1-154009" >653, 654
    \cGlsformat  159
    +href="glossaries-user.html#dx1-154015" >655
    \cglsformat  160
    +href="glossaries-user.html#dx1-154013" >656
    \cGlspl  161
    +href="glossaries-user.html#dx1-154012" >657
    \cglspl  162
    - - +href="glossaries-user.html#dx1-154010" >658
    \cGlsplformat  163
    +href="glossaries-user.html#dx1-154016" >659
    \cglsplformat  164
    +href="glossaries-user.html#dx1-154014" >660
    +\chapter  661, 662
    +\chapter*  663, 664
    classicthesis package  165, 166, 167, 168, 169
    +href="glossaries-user.html#dx1-49002" >665, 666, 667, 668, 669
    +convertgls2bib  670, 671, 672, 673, 674, 675, 676, 677, 678, 679, 680, 681, 682, 683, 684, 685, 686, 687
    \currentglossary  170
    -

    688
    +

    D datatool package  171, 172, 173, 174, 175
    +href="glossaries-user.html#dx1-12" >689, 690, 691, 692, 693
    + + datatool-base package  176, 177
    +href="glossaries-user.html#dx1-11" >694
    \DeclareAcronymList  178
    +href="glossaries-user.html#dx1-93003" >695, 696, 697, 698
    +\defentryfmt  699
    +\defglsentry  700, 701
    \defglsentryfmt  179
    +href="glossaries-user.html#dx1-132027" >702, 703, 704, 705, 706, 707, 708, 709, 710
    \DefineAcronymSynonyms  180
    +href="glossaries-user.html#dx1-94001" >711
    +\delimN  712
    +\delimR  713
    +\descriptionname  714
    +\dgls  715
    +\dicei  716
    doc package  181, 182, 183, 184
    -

    717, 718, 719, 720
    +\dtlcompare  721
    +\dtlicompare  722
    +\dtlletterindexcompare  723
    +\dtlwordindexcompare  724
    +

    E +\edef  725
    +\emph  726
    encap  185
    +href="glossaries-user.html#dx1-128002" >727
    +\EndAccSupp  728, 729
    +\ensuremath  730, 731
    entry location  186
    +href="glossaries-user.html#dx1-3013" >732
    +\entryname  733
    environments:
        theglossary  187
    +href="glossaries-user.html#dx1-166003" >734
    etoolbox package  188, 189, 190, 191, 192, 193
    +href="glossaries-user.html#dx1-7" >735, 736, 737, 738, 739, 740, 741, 742
    Extended Latin Alphabet  194
    +href="glossaries-user.html#dx1-3014" >743
    extended Latin character  195, 196, 197, 198, 199, 200, 201
    -

    744, 745, 746, 747, 748, 749, 750
    +

    F file types
        .alg  202
    -    .aux  203, 204, 205, 206, 207
    -    .glg  208, 209, 210
    -    .glg2  211
    -    .glo  212, 213, 214
    -    .gls  215, 216
    -    .glsdefs  217, 218, 219, 220
    -    .ist  221, 222, 223, 224, 225, 226
    -    .tex  227, 228, 229, 230
    -    .xdy  231, 232, 233, 234, 235, 236, 237, 238
    +class="cmtt-10">alg  751
    +    aux  752, 753, 754, 755, 756, 757, 758, 759, 760, 761, 762, 763, 764, 765, 766, 767, 768, 769, 770, 771, 772, 773, 774, 775, 776, 777
    +    bib  778, 779, 780, 781, 782, 783, 784, 785, 786, 787, 788, 789, 790, 791, 792, 793, 794, 795, 796, 797, 798, 799, 800, 801, 802, 803, 804, 805, 806, 807, 808, 809, 810, 811, 812, 813, 814, 815, 816, 817, 818, 819, 820, 821, 822, 823, 824
    +    dict  825
    +    docdefs  826, 827, 828
    +    glg  829, 830, 831, 832
    +    glg2  833
    +    glo  834, 835, 836, 837, 838, 839, 840
        glo2  239
    +href="glossaries-user.html#dx1-23" >841
    + + +    gls  842, 843
        gls2  240
    +href="glossaries-user.html#dx1-22" >844
    +    glsdefs  845, 846, 847, 848, 849
    +    glslabels  850
    +    glstex  851, 852
    +    ist  853, 854, 855, 856, 857, 858, 859
    +    ldf  860
    +    lua  861
    +    tex  862, 863, 864, 865, 866, 867, 868, 869, 870
    +    toc  871, 872
    +    xdy  873, 874, 875, 876, 877, 878, 879, 880, 881, 882, 883, 884, 885, 886, 887, 888
    first use  241
    +href="glossaries-user.html#dx1-3021" >889
        flag  242
    +href="glossaries-user.html#dx1-3029" >890
        text  243
    +href="glossaries-user.html#dx1-3030" >891
    \firstacronymfont  244
    +href="glossaries-user.html#dx1-135064" >892, 893, 894, 895, 896, 897, 898
    flowfram package  245
    +href="glossaries-user.html#dx1-161011" >899
    fmtcount package  246, 247, 248, 249
    +href="glossaries-user.html#dx1-144050" >900, 901, 902, 903
    fontspec package  250, 251
    - - +href="glossaries-user.html#dx1-112155" >904, 905
    +\footnote  906, 907, 908, 909, 910, 911, 912, 913, 914, 915
    \forallacronyms  252
    +href="glossaries-user.html#dx1-168002" >916
    \forallglossaries  253
    +href="glossaries-user.html#dx1-168001" >917
    \forallglsentries  254
    +href="glossaries-user.html#dx1-168007" >918
    +\foreignlanguage  919, 920
    \forglsentries  255
    -

    921
    +

    G \Genacrfullformat  256
    +href="glossaries-user.html#dx1-135065" >922
    \genacrfullformat  257
    +href="glossaries-user.html#dx1-135059" >923, 924, 925, 926, 927, 928
    \GenericAcronymFields  258
    +href="glossaries-user.html#dx1-150022" >929, 930, 931
    \Genplacrfullformat  259
    +href="glossaries-user.html#dx1-135066" >932
    \genplacrfullformat  260
    +href="glossaries-user.html#dx1-135061" >933, 934
    +\glolinkprefix  935, 936
    glossaries package  261, 262, 263, 264, 265, 266, 267, 268, 269, 270
    +href="glossaries-user.html#dx1-12001" >937, 938, 939, 940, 941, 942, 943, 944, 945, 946, 947, 948, 949, 950, 951, 952, 953
    glossaries-accsupp package  271, 272, 273, 274
    +href="glossaries-user.html#dx1-30014" >954, 955, 956, 957, 958, 959, 960, 961, 962, 963, 964, 965, 966, 967, 968, 969
    glossaries-babel package  275, 276
    +href="glossaries-user.html#dx1-32008" >970, 971
    glossaries-extra package  277, 278, 279, 280, 281, 282, 283, 284, 285, 286, 287, 288, 289, 290, 291, 292, 293, 294, 295, 296, 297, 298, 299, 300, 301
    +class="cmss-10">glossaries-extra-bib2gls package  972
    glossaries-extra-stylemods package  302
    +href="glossaries-user.html#dx1-60001" >973, 974, 975
    glossaries-polyglossia package  303
    +href="glossaries-user.html#dx1-32010" >976
    glossaries-prefix package  304, 305, 306, 307
    +href="glossaries-user.html#dx1-103001" >977, 978, 979, 980, 981, 982, 983, 984, 985, 986
    glossary counters:
        glossaryentry  308
    +href="glossaries-user.html#dx1-46003" >987
        glossarysubentry  309
    +href="glossaries-user.html#dx1-48003" >988
    glossary package  310, 311, 312, 313, 314, 315
    +href="glossaries-user.html#dx1-16" >989, 990, 991, 992, 993
    glossary styles:
        altlist  316, 317, 318, 319, 320
    +href="glossaries-user.html#dx1-149048" >994, 995, 996, 997, 998, 999
    + +     altlistgroup  321, 322
    +href="glossaries-user.html#dx1-157030" >1000, 1001
        altlisthypergroup  323
    +href="glossaries-user.html#dx1-157032" >1002
        altlong4col  324, 325, 326
    +href="glossaries-user.html#dx1-156024" >1003, 1004, 1005
        altlong4col-booktabs  327
    +href="glossaries-user.html#dx1-160031" >1006
        altlong4colborder  328
    +href="glossaries-user.html#dx1-158043" >1007
        altlong4colheader  329, 330
    +href="glossaries-user.html#dx1-158045" >1008, 1009
        altlong4colheaderborder  331
    +href="glossaries-user.html#dx1-158047" >1010, 1011
        altlongragged4col  332, 333, 334
    +href="glossaries-user.html#dx1-159030" >1012, 1013, 1014
        altlongragged4col-booktabs  335
    +href="glossaries-user.html#dx1-160037" >1015, 1016
        altlongragged4colborder  336
    +href="glossaries-user.html#dx1-159034" >1017
        altlongragged4colheader  337, 338, 339
    +href="glossaries-user.html#dx1-159036" >1018, 1019, 1020
        altlongragged4colheaderborder  340
    +href="glossaries-user.html#dx1-159038" >1021
        altsuper4col  341, 342, 343
    +href="glossaries-user.html#dx1-156025" >1022, 1023, 1024
        altsuper4colborder  344
    +href="glossaries-user.html#dx1-161048" >1025
        altsuper4colheader  345
    +href="glossaries-user.html#dx1-161050" >1026
        altsuper4colheaderborder  346
    +href="glossaries-user.html#dx1-161052" >1027
        altsuperragged4col  347, 348, 349
    +href="glossaries-user.html#dx1-162031" >1028, 1029, 1030
        altsuperragged4colborder  350
    +href="glossaries-user.html#dx1-162033" >1031
        altsuperragged4colheader  351, 352
    +href="glossaries-user.html#dx1-162035" >1032
        altsuperragged4colheaderborder  353
    - - +href="glossaries-user.html#dx1-162037" >1033
        alttree  354, 355, 356, 357, 358, 359, 360, 361
    +href="glossaries-user.html#dx1-156028" >1034, 1035, 1036, 1037, 1038, 1039, 1040, 1041, 1042, 1043
        alttreegroup  362, 363, 364
    +href="glossaries-user.html#dx1-163055" >1044, 1045, 1046
        alttreehypergroup  365, 366
    +href="glossaries-user.html#dx1-163057" >1047, 1048, 1049, 1050
    +    bookindex  1051, 1052, 1053
        index  367, 368, 369, 370, 371, 372, 373, 374, 375, 376, 377, 378
    +href="glossaries-user.html#dx1-53004" >1054, 1055, 1056, 1057, 1058, 1059, 1060, 1061, 1062, 1063, 1064, 1065
        indexgroup  379, 380, 381
    +href="glossaries-user.html#dx1-163024" >1066, 1067, 1068
        indexhypergroup  382, 383, 384
    +href="glossaries-user.html#dx1-163007" >1069, 1070, 1071
        inline  385, 386, 387
    +href="glossaries-user.html#dx1-165002" >1072, 1073, 1074
        list  388, 389, 390, 391, 392, 393, 394, 395, 396, 397, 398, 399, 400
    +href="glossaries-user.html#dx1-52003" >1075, 1076, 1077, 1078, 1079, 1080, 1081, 1082, 1083, 1084, 1085, 1086, 1087
        listdotted  401, 402, 403, 404, 405
    +href="glossaries-user.html#dx1-156038" >1088, 1089, 1090, 1091, 1092
        listgroup  406, 407, 408, 409
    +href="glossaries-user.html#dx1-73020" >1093, 1094, 1095, 1096
        listhypergroup  410, 411, 412, 413, 414, 415, 416, 417
    +href="glossaries-user.html#dx1-157019" >1097, 1098, 1099, 1100, 1101, 1102, 1103, 1104
        long  418, 419, 420, 421, 422, 423
    +href="glossaries-user.html#dx1-156027" >1105, 1106, 1107, 1108, 1109, 1110
        long-booktabs  424, 425
    +href="glossaries-user.html#dx1-160024" >1111, 1112
    +    long-name-desc-sym-loc  1113
        long3col  426, 427, 428, 429, 430
    +href="glossaries-user.html#dx1-156011" >1114, 1115, 1116, 1117, 1118
        long3col-booktabs  431
    +href="glossaries-user.html#dx1-160026" >1119
        long3colborder  432, 433
    +href="glossaries-user.html#dx1-156013" >1120, 1121
        long3colheader  434, 435, 436, 437
    +href="glossaries-user.html#dx1-156012" >1122, 1123, 1124, 1125
        long3colheaderborder  438, 439
    +href="glossaries-user.html#dx1-156014" >1126, 1127
        long4col  440, 441, 442, 443, 444
    +href="glossaries-user.html#dx1-156022" >1128, 1129, 1130, 1131, 1132
        long4col-booktabs  445
    +href="glossaries-user.html#dx1-160029" >1133, 1134
        long4colborder  446, 447
    +href="glossaries-user.html#dx1-158033" >1135, 1136
        long4colheader  448, 449, 450, 451
    +href="glossaries-user.html#dx1-158035" >1137, 1138, 1139, 1140
        long4colheaderborder  452, 453
    +href="glossaries-user.html#dx1-158037" >1141, 1142, 1143
        longborder  454
    +href="glossaries-user.html#dx1-158013" >1144
    + +     longheader  455, 456, 457, 458
    +href="glossaries-user.html#dx1-158015" >1145, 1146, 1147, 1148
        longheaderborder  459, 460
    +href="glossaries-user.html#dx1-158017" >1149, 1150
        longragged  461, 462, 463, 464
    +href="glossaries-user.html#dx1-159010" >1151, 1152, 1153, 1154
        longragged-booktabs  465
    +href="glossaries-user.html#dx1-160033" >1155
        longragged3col  466, 467, 468, 469
    +href="glossaries-user.html#dx1-159019" >1156, 1157, 1158, 1159
        longragged3col-booktabs  470
    +href="glossaries-user.html#dx1-160035" >1160
        longragged3colborder  471
    +href="glossaries-user.html#dx1-159024" >1161
        longragged3colheader  472, 473, 474
    +href="glossaries-user.html#dx1-159026" >1162, 1163, 1164
        longragged3colheaderborder  475
    +href="glossaries-user.html#dx1-159028" >1165
        longraggedborder  476
    +href="glossaries-user.html#dx1-159013" >1166
        longraggedheader  477, 478, 479
    +href="glossaries-user.html#dx1-159015" >1167, 1168, 1169
        longraggedheaderborder  480
    +href="glossaries-user.html#dx1-159017" >1170
        mcolalttree  481
    +href="glossaries-user.html#dx1-164039" >1171
        mcolalttreegroup  482
    +href="glossaries-user.html#dx1-164041" >1172
        mcolalttreehypergroup  483
    +href="glossaries-user.html#dx1-164043" >1173
        mcolalttreespannav  484
    +href="glossaries-user.html#dx1-164044" >1174
        mcolindex  485, 486
    +href="glossaries-user.html#dx1-164005" >1175, 1176
        mcolindexgroup  487
    +href="glossaries-user.html#dx1-164020" >1177
        mcolindexhypergroup  488
    +href="glossaries-user.html#dx1-164022" >1178
        mcolindexspannav  489
    +href="glossaries-user.html#dx1-164023" >1179
        mcoltree  490
    +href="glossaries-user.html#dx1-164025" >1180
        mcoltreegroup  491
    - - +href="glossaries-user.html#dx1-164027" >1181
        mcoltreehypergroup  492, 493
    +href="glossaries-user.html#dx1-164029" >1182, 1183
        mcoltreenoname  494
    +href="glossaries-user.html#dx1-164032" >1184
        mcoltreenonamegroup  495
    +href="glossaries-user.html#dx1-164034" >1185
        mcoltreenonamehypergroup  496
    +href="glossaries-user.html#dx1-164036" >1186
        mcoltreenonamespannav  497
    +href="glossaries-user.html#dx1-164037" >1187
        mcoltreespannav  498
    +href="glossaries-user.html#dx1-164030" >1188
        super  499, 500, 501, 502
    +href="glossaries-user.html#dx1-161012" >1189, 1190, 1191, 1192
        super3col  503, 504, 505, 506
    +href="glossaries-user.html#dx1-161024" >1193, 1194, 1195, 1196
        super3colborder  507
    +href="glossaries-user.html#dx1-161029" >1197
        super3colheader  508, 509
    +href="glossaries-user.html#dx1-161031" >1198, 1199
        super3colheaderborder  510
    +href="glossaries-user.html#dx1-161033" >1200
        super4col  511, 512, 513, 514, 515
    +href="glossaries-user.html#dx1-156023" >1201, 1202, 1203, 1204, 1205
        super4colborder  516, 517
    +href="glossaries-user.html#dx1-161038" >1206, 1207
        super4colheader  518, 519, 520
    +href="glossaries-user.html#dx1-161040" >1208, 1209, 1210
        super4colheaderborder  521, 522
    +href="glossaries-user.html#dx1-161042" >1211, 1212
        superborder  523
    +href="glossaries-user.html#dx1-161018" >1213
        superheader  524, 525
    +href="glossaries-user.html#dx1-161020" >1214, 1215
        superheaderborder  526, 527
    +href="glossaries-user.html#dx1-141079" >1216, 1217
        superragged  528, 529, 530, 531
    +href="glossaries-user.html#dx1-162009" >1218, 1219, 1220, 1221
        superragged3col  532, 533, 534, 535
    +href="glossaries-user.html#dx1-162021" >1222, 1223, 1224, 1225
        superragged3colborder  536
    +href="glossaries-user.html#dx1-162026" >1226
        superragged3colheader  537, 538
    +href="glossaries-user.html#dx1-162028" >1227
        superragged3colheaderborder  539
    +href="glossaries-user.html#dx1-162030" >1228
        superraggedborder  540
    +href="glossaries-user.html#dx1-162015" >1229
    + +     superraggedheader  541, 542
    +href="glossaries-user.html#dx1-162017" >1230, 1231
        superraggedheaderborder  543
    +href="glossaries-user.html#dx1-162019" >1232
    +    topic  1233, 1234, 1235, 1236
        tree  544, 545, 546, 547, 548, 549, 550
    +href="glossaries-user.html#dx1-150067" >1237, 1238, 1239, 1240, 1241, 1242, 1243, 1244
        treegroup  551, 552, 553
    +href="glossaries-user.html#dx1-163035" >1245, 1246, 1247
        treehypergroup  554, 555, 556
    +href="glossaries-user.html#dx1-157024" >1248, 1249, 1250
        treenoname  557, 558, 559, 560
    +href="glossaries-user.html#dx1-163012" >1251, 1252, 1253, 1254
        treenonamegroup  561, 562, 563
    +href="glossaries-user.html#dx1-163042" >1255, 1256, 1257, 1258
        treenonamehypergroup  564, 565
    +href="glossaries-user.html#dx1-163044" >1259, 1260
    glossary-bookindex package  566
    +href="glossaries-user.html#dx1-11073" >1261, 1262, 1263
    glossary-inline package  567, 568
    +href="glossaries-user.html#dx1-165001" >1264, 1265
    glossary-list package  569, 570, 571, 572, 573
    +href="glossaries-user.html#dx1-49004" >1266, 1267, 1268, 1269, 1270, 1271
    glossary-long package  574, 575, 576, 577, 578, 579, 580, 581
    +href="glossaries-user.html#dx1-49005" >1272, 1273, 1274, 1275, 1276, 1277, 1278, 1279, 1280
    glossary-longbooktabs package  582, 583, 584
    +href="glossaries-user.html#dx1-160001" >1281, 1282, 1283, 1284
    +glossary-longextra package  1285, 1286
    glossary-longnoloc package  585
    +href="glossaries-user.html#dx1-156005" >1287
    glossary-longragged package  586, 587, 588, 589
    +href="glossaries-user.html#dx1-159001" >1288, 1289, 1290, 1291
    glossary-mcols package  590, 591, 592, 593, 594, 595, 596
    +href="glossaries-user.html#dx1-54001" >1292, 1293, 1294, 1295, 1296, 1297, 1298
    glossary-ragged package  597
    +href="glossaries-user.html#dx1-160010" >1299
    glossary-super package  598, 599, 600, 601, 602, 603
    +href="glossaries-user.html#dx1-49006" >1300, 1301, 1302, 1303, 1304, 1305
    glossary-superragged package  604, 605, 606
    +href="glossaries-user.html#dx1-162001" >1306, 1307, 1308
    +glossary-topic package  1309, 1310
    +glossary-topic package  1311, 1312
    glossary-tree package  607, 608, 609, 610, 611, 612, 613, 614
    +href="glossaries-user.html#dx1-49007" >1313, 1314, 1315, 1316, 1317, 1318, 1319, 1320, 1321, 1322, 1323, 1324
    glossaryentry (counter)  615, 616, 617, 618
    +href="glossaries-user.html#dx1-46002" >1325, 1326, 1327, 1328
    +\glossaryentrynumbers  1329, 1330, 1331, 1332
    \glossaryheader  619
    - - +href="glossaries-user.html#dx1-166015" >1333, 1334, 1335
    +\glossaryname  1336, 1337
    \glossarypostamble  620
    +href="glossaries-user.html#dx1-141076" >1338, 1339
    \glossarypreamble  621
    +href="glossaries-user.html#dx1-47005" >1340, 1341, 1342, 1343
    +\glossarysection  1344
    +\glossarystyle  1345
    glossarysubentry (counter)  622
    +href="glossaries-user.html#dx1-48002" >1346
    \glossentry  623
    +href="glossaries-user.html#dx1-166038" >1347, 1348, 1349
    \Glossentrydesc  624
    +href="glossaries-user.html#dx1-140028" >1350, 1351
    \glossentrydesc  625
    +href="glossaries-user.html#dx1-11038" >1352, 1353, 1354, 1355, 1356, 1357
    \Glossentryname  626
    +href="glossaries-user.html#dx1-140012" >1358, 1359
    \glossentryname  627
    +href="glossaries-user.html#dx1-140011" >1360, 1361, 1362
    +\glossentrynameother  1363
    \Glossentrysymbol  628
    +href="glossaries-user.html#dx1-140035" >1364
    \glossentrysymbol  629
    +href="glossaries-user.html#dx1-11014" >1365, 1366, 1367, 1368, 1369, 1370
    \GLS  630
    +href="glossaries-user.html#dx1-3024" >1371, 1372, 1373, 1374
    \Gls  631
    +href="glossaries-user.html#dx1-3023" >1375, 1376, 1377, 1378, 1379, 1380, 1381, 1382, 1383, 1384, 1385, 1386
    \gls  632
    +href="glossaries-user.html#dx1-3022" >1387, 1388, 1389, 1390, 1391, 1392, 1393, 1394, 1395, 1396, 1397, 1398, 1399, 1400, 1401, 1402, 1403, 1404, 1405, 1406, 1407, 1408, 1409, 1410, 1411, 1412, 1413, 1414, 1415, 1416, 1417, 1418, 1419
    +\gls*  1420
    + + +\glsabbrvfont  1421
    +\glsaccessibility  1422, 1423, 1424, 1425, 1426
    +\Glsaccesslong  1427
    +\glsaccesslong  1428
    +\Glsaccesslongpl  1429
    +\glsaccesslongpl  1430
    +\glsaccessshort  1431, 1432
    +\glsaccessshortpl  1433, 1434
    +\glsaccsupp  1435, 1436
    +\glsacrpluralsuffix  1437
    \glsacspace  633
    +href="glossaries-user.html#dx1-149029" >1438
    \glsadd  634
    +href="glossaries-user.html#dx1-11015" >1439, 1440, 1441, 1442, 1443, 1444, 1445
    \glsaddall  635
    +href="glossaries-user.html#dx1-127010" >1446, 1447, 1448, 1449
    \glsaddall options
        types  636
    +class="cmtt-10">types  1450
    \glsaddallunused  637
    +href="glossaries-user.html#dx1-137010" >1451
    \glsaddkey  638
    +href="glossaries-user.html#dx1-112108" >1452, 1453, 1454, 1455, 1456
    +\GlsAddLetterGroup  1457
    \glsaddprotectedpagefmt  639
    +href="glossaries-user.html#dx1-129016" >1458
    \glsaddstoragekey  640
    +href="glossaries-user.html#dx1-112109" >1459, 1460, 1461, 1462, 1463, 1464, 1465, 1466
    \GlsAddXdyAttribute  641
    +href="glossaries-user.html#dx1-132051" >1467, 1468, 1469
    \GlsAddXdyCounters  642
    +href="glossaries-user.html#dx1-144009" >1470, 1471
    \GlsAddXdyLocation  643
    +href="glossaries-user.html#dx1-144027" >1472, 1473
    \glsautoprefix  644
    +href="glossaries-user.html#dx1-43006" >1474
    \glsbackslash  645
    +href="glossaries-user.html#dx1-142012" >1475
    \glscapscase  646
    +href="glossaries-user.html#dx1-135021" >1476, 1477, 1478
    +\glscategory  1479
    \glsclearpage  647
    +href="glossaries-user.html#dx1-41008" >1480
    \glsclosebrace  648
    +href="glossaries-user.html#dx1-142008" >1481
    +\glscurrententrylabel  1482, 1483, 1484, 1485, 1486, 1487, 1488
    \glscurrentfieldvalue  649
    +href="glossaries-user.html#dx1-169027" >1489, 1490, 1491
    \glscustomtext  650
    +href="glossaries-user.html#dx1-135015" >1492, 1493, 1494
    +\GlsDeclareNoHyperList  1495, 1496, 1497
    +\glsdefaultshortaccess  1498, 1499
    +\glsdefaulttype  1500, 1501, 1502, 1503, 1504, 1505
    +\glsdefpostdesc  1506, 1507, 1508
    +\glsdefpostlink  1509, 1510, 1511, 1512, 1513
    \GLSdesc  651
    +href="glossaries-user.html#dx1-134054" >1514
    \Glsdesc  652
    +href="glossaries-user.html#dx1-134053" >1515
    \glsdesc  653
    +href="glossaries-user.html#dx1-134050" >1516, 1517, 1518, 1519, 1520, 1521, 1522, 1523, 1524
    \glsdescwidth  654
    +href="glossaries-user.html#dx1-156016" >1525, 1526, 1527, 1528, 1529, 1530, 1531, 1532, 1533, 1534, 1535, 1536
    \glsdisablehyper  655
    +href="glossaries-user.html#dx1-132038" >1537, 1538, 1539, 1540, 1541
    \glsdisp  656
    +href="glossaries-user.html#dx1-3028" >1542, 1543, 1544, 1545, 1546, 1547
    +\glsdisplay  1548, 1549
    +\glsdisplayfirst  1550, 1551
    \glsdisplaynumberlist  657
    +href="glossaries-user.html#dx1-5002" >1552, 1553, 1554, 1555, 1556, 1557, 1558, 1559
    + + \glsdoifexists  658
    +href="glossaries-user.html#dx1-169005" >1560
    \glsdoifexistsordo  659
    +href="glossaries-user.html#dx1-169008" >1561
    \glsdoifexistsorwarn  660
    +href="glossaries-user.html#dx1-169007" >1562
    \glsdoifnoexists  661
    +href="glossaries-user.html#dx1-169006" >1563
    \glsdoifnoexistsordo  662
    +href="glossaries-user.html#dx1-169009" >1564
    \glsdosanitizesort  663
    +href="glossaries-user.html#dx1-73029" >1565, 1566
    \glsenableentrycount  664
    - - +href="glossaries-user.html#dx1-154003" >1567, 1568
    \glsenablehyper  665
    +href="glossaries-user.html#dx1-136006" >1569
    \glsentrycounterlabel  666
    +href="glossaries-user.html#dx1-166048" >1570
    \GlsEntryCounterLabelPrefix  667
    +href="glossaries-user.html#dx1-46005" >1571
    \glsentrycurrcount  668
    +href="glossaries-user.html#dx1-154007" >1572
    \Glsentrydesc  669
    +href="glossaries-user.html#dx1-11007" >1573, 1574, 1575, 1576, 1577
    \glsentrydesc  670
    +href="glossaries-user.html#dx1-11036" >1578, 1579, 1580, 1581, 1582, 1583, 1584, 1585, 1586, 1587
    \Glsentrydescplural  671
    +href="glossaries-user.html#dx1-140030" >1588
    \glsentrydescplural  672
    +href="glossaries-user.html#dx1-140029" >1589
    \Glsentryfirst  673
    +href="glossaries-user.html#dx1-140020" >1590
    \glsentryfirst  674
    +href="glossaries-user.html#dx1-140019" >1591, 1592
    \Glsentryfirstplural  675
    +href="glossaries-user.html#dx1-140023" >1593
    \glsentryfirstplural  676
    +href="glossaries-user.html#dx1-140022" >1594
    \glsentryfmt  677
    +href="glossaries-user.html#dx1-132028" >1595, 1596, 1597, 1598, 1599, 1600, 1601, 1602, 1603, 1604, 1605, 1606
    \Glsentryfull  678
    +href="glossaries-user.html#dx1-147129" >1607
    \glsentryfull  679
    +href="glossaries-user.html#dx1-147128" >1608, 1609, 1610, 1611, 1612, 1613
    \Glsentryfullpl  680
    +href="glossaries-user.html#dx1-147131" >1614
    \glsentryfullpl  681
    +href="glossaries-user.html#dx1-147130" >1615
    \glsentryitem  682
    +href="glossaries-user.html#dx1-166045" >1616, 1617
    \Glsentrylong  683
    +href="glossaries-user.html#dx1-135068" >1618, 1619, 1620, 1621
    \glsentrylong  684
    +href="glossaries-user.html#dx1-147120" >1622, 1623, 1624
    \Glsentrylongpl  685
    +href="glossaries-user.html#dx1-147123" >1625, 1626
    \glsentrylongpl  686
    +href="glossaries-user.html#dx1-147122" >1627, 1628
    \Glsentryname  687
    +href="glossaries-user.html#dx1-140007" >1629, 1630
    \glsentryname  688
    +href="glossaries-user.html#dx1-140006" >1631, 1632, 1633, 1634, 1635
    \glsentrynumberlist  689
    +href="glossaries-user.html#dx1-45003" >1636, 1637, 1638, 1639, 1640
    +\glsentryparent  1641, 1642
    \Glsentryplural  690
    +href="glossaries-user.html#dx1-140017" >1643
    \glsentryplural  691
    +href="glossaries-user.html#dx1-140016" >1644, 1645, 1646
    \Glsentryprefix  692
    +href="glossaries-user.html#dx1-171057" >1647
    \glsentryprefix  693
    +href="glossaries-user.html#dx1-171048" >1648, 1649
    \Glsentryprefixfirst  694
    +href="glossaries-user.html#dx1-171058" >1650
    \glsentryprefixfirst  695
    +href="glossaries-user.html#dx1-171050" >1651
    \Glsentryprefixfirstplural  696
    +href="glossaries-user.html#dx1-171060" >1652
    \glsentryprefixfirstplural  697
    +href="glossaries-user.html#dx1-171054" >1653
    \Glsentryprefixplural  698
    +href="glossaries-user.html#dx1-171059" >1654
    \glsentryprefixplural  699
    +href="glossaries-user.html#dx1-171052" >1655
    \glsentryprevcount  700
    +href="glossaries-user.html#dx1-154008" >1656
    \Glsentryshort  701
    +href="glossaries-user.html#dx1-147125" >1657
    \glsentryshort  702
    +href="glossaries-user.html#dx1-147124" >1658
    + + \Glsentryshortpl  703
    +href="glossaries-user.html#dx1-147127" >1659
    \glsentryshortpl  704
    +href="glossaries-user.html#dx1-147126" >1660
    +\glsentrysort  1661
    \Glsentrysymbol  705
    +href="glossaries-user.html#dx1-140032" >1662
    \glsentrysymbol  706
    +href="glossaries-user.html#dx1-11006" >1663, 1664, 1665, 1666, 1667, 1668
    \Glsentrysymbolplural  707
    +href="glossaries-user.html#dx1-140037" >1669
    \glsentrysymbolplural  708
    +href="glossaries-user.html#dx1-140036" >1670
    \Glsentrytext  709
    +href="glossaries-user.html#dx1-116005" >1671, 1672, 1673, 1674, 1675
    \glsentrytext  710
    - - +href="glossaries-user.html#dx1-116004" >1676, 1677, 1678, 1679, 1680, 1681, 1682, 1683, 1684
    \glsentrytitlecase  711
    +href="glossaries-user.html#dx1-134012" >1685, 1686
    +\glsentrytype  1687
    \Glsentryuseri  712
    +href="glossaries-user.html#dx1-140039" >1688
    \glsentryuseri  713
    +href="glossaries-user.html#dx1-140038" >1689, 1690
    \Glsentryuserii  714
    +href="glossaries-user.html#dx1-140041" >1691
    \glsentryuserii  715
    +href="glossaries-user.html#dx1-140040" >1692
    \Glsentryuseriii  716
    +href="glossaries-user.html#dx1-140043" >1693
    \glsentryuseriii  717
    +href="glossaries-user.html#dx1-140042" >1694
    \Glsentryuseriv  718
    +href="glossaries-user.html#dx1-140045" >1695
    \glsentryuseriv  719
    +href="glossaries-user.html#dx1-140044" >1696
    \Glsentryuserv  720
    +href="glossaries-user.html#dx1-140047" >1697
    \glsentryuserv  721
    +href="glossaries-user.html#dx1-140046" >1698
    \Glsentryuservi  722
    +href="glossaries-user.html#dx1-140049" >1699
    \glsentryuservi  723
    +href="glossaries-user.html#dx1-140048" >1700
    \glsexpandfields  724
    +href="glossaries-user.html#dx1-118022" >1701
    +\glsfieldaccsupp  1702
    \glsfielddef  725
    +href="glossaries-user.html#dx1-170009" >1703
    \glsfieldedef  726
    +href="glossaries-user.html#dx1-170010" >1704
    \glsfieldfetch  727
    +href="glossaries-user.html#dx1-170004" >1705
    \glsfieldgdef  728
    +href="glossaries-user.html#dx1-170011" >1706
    \glsfieldxdef  729
    +href="glossaries-user.html#dx1-136031" >1707, 1708, 1709, 1710
    \glsfindwidesttoplevelname  730
    +href="glossaries-user.html#dx1-163051" >1711, 1712
    +\glsFindWidestUsedLevelTwo  1713
    +\glsFindWidestUsedTopLevelName  1714
    \GLSfirst  731
    +href="glossaries-user.html#dx1-134017" >1715
    \Glsfirst  732
    +href="glossaries-user.html#dx1-134016" >1716
    \glsfirst  733
    +href="glossaries-user.html#dx1-134013" >1717
    +\glsfirstabbrvscfont  1718, 1719, 1720, 1721
    +\glsfirstlongfootnotefont  1722, 1723, 1724, 1725, 1726
    \GLSfirstplural  734
    +href="glossaries-user.html#dx1-134037" >1727
    \Glsfirstplural  735
    +href="glossaries-user.html#dx1-134036" >1728
    \glsfirstplural  736
    +href="glossaries-user.html#dx1-134033" >1729
    +\glsfmtfirst  1730
    +\Glsfmtlong  1731, 1732
    +\glsfmtname  1733, 1734, 1735
    +\glsfmtshort  1736
    +\glsfmttext  1737, 1738, 1739, 1740
    + + \glsgenacfmt  737
    +href="glossaries-user.html#dx1-135050" >1741, 1742, 1743, 1744, 1745, 1746, 1747
    \glsgenentryfmt  738
    +href="glossaries-user.html#dx1-135044" >1748, 1749, 1750, 1751, 1752
    \glsgetgrouptitle  739
    +href="glossaries-user.html#dx1-166026" >1753
    \glsglossarymark  740, 741
    +href="glossaries-user.html#dx1-41003" >1754, 1755, 1756, 1757, 1758
    \glsgroupheading  742
    +href="glossaries-user.html#dx1-166020" >1759, 1760
    \glsgroupskip  743
    +href="glossaries-user.html#dx1-156032" >1761, 1762, 1763
    \glshyperlink  744
    +href="glossaries-user.html#dx1-136022" >1764, 1765, 1766
    \glshypernavsep  745
    +href="glossaries-user.html#dx1-157021" >1767
    +\glsifhyper  1768
    \glsifhyperon  746
    +href="glossaries-user.html#dx1-135022" >1769, 1770, 1771
    \glsIfListOfAcronyms  747
    +href="glossaries-user.html#dx1-93006" >1772
    \glsifplural  748
    +href="glossaries-user.html#dx1-135020" >1773, 1774, 1775, 1776
    +\glsignore  1777
    \glsinlinedescformat  749
    +href="glossaries-user.html#dx1-165020" >1778
    \glsinlineemptydescformat  750
    +href="glossaries-user.html#dx1-165019" >1779
    \glsinlinenameformat  751
    +href="glossaries-user.html#dx1-165016" >1780
    \glsinlineparentchildseparator  752
    +href="glossaries-user.html#dx1-165012" >1781, 1782
    \glsinlineseparator  753
    +href="glossaries-user.html#dx1-165008" >1783, 1784
    \glsinlinesubdescformat  754
    +href="glossaries-user.html#dx1-165021" >1785
    \glsinlinesubnameformat  755
    +href="glossaries-user.html#dx1-165018" >1786
    \glsinlinesubseparator  756
    +href="glossaries-user.html#dx1-165010" >1787, 1788
    \glsinsert  757
    - - +href="glossaries-user.html#dx1-135019" >1789, 1790
    \glslabel  758
    +href="glossaries-user.html#dx1-34017" >1791, 1792, 1793, 1794, 1795, 1796, 1797, 1798, 1799, 1800, 1801, 1802, 1803, 1804
    \glslabeltok  759
    +href="glossaries-user.html#dx1-150024" >1805, 1806
    \glsletentryfield  760
    +href="glossaries-user.html#dx1-140033" >1807
    \glslink  761
    +href="glossaries-user.html#dx1-34008" >1808, 1809, 1810, 1811, 1812, 1813, 1814, 1815, 1816, 1817
    \glslink options
        counter  762, 763
    -    format  764, 765, 766, 767, 768, 769, 770, 771
    -    hyper  772, 773, 774, 775, 776, 777, 778
    -    local  779
    +class="cmtt-10">counter  1818, 1819
    +    format  1820, 1821, 1822, 1823, 1824, 1825, 1826, 1827, 1828, 1829, 1830, 1831, 1832, 1833
    +    hyper  1834, 1835, 1836, 1837, 1838, 1839, 1840, 1841
    +    hyperoutside  1842
    +    local  1843
    +    noindex  1844
    +    prefix  1845
    +    textformat  1846
    +    theHvalue  1847
    +    thevalue  1848
    +    wrgloss  1849
    \glslinkcheckfirsthyperhook  780
    +href="glossaries-user.html#dx1-34015" >1850
    \glslinkpostsetkeys  781
    +href="glossaries-user.html#dx1-34023" >1851, 1852, 1853, 1854, 1855, 1856, 1857, 1858, 1859
    +\glslinkprefix  1860
    +\glslinkpresetkeys  1861
    \glslinkvar  782
    +href="glossaries-user.html#dx1-135028" >1862
    \glslistdottedwidth  783
    +href="glossaries-user.html#dx1-157039" >1863
    \glslistnavigationitem  784
    +href="glossaries-user.html#dx1-157023" >1864
    \glslocalreset  785
    +href="glossaries-user.html#dx1-153004" >1865
    + + \glslocalresetall  786
    +href="glossaries-user.html#dx1-153008" >1866
    \glslocalunset  787
    +href="glossaries-user.html#dx1-153006" >1867
    \glslocalunsetall  788
    +href="glossaries-user.html#dx1-153010" >1868
    +\glslongfont  1869
    \glslongtok  789
    +href="glossaries-user.html#dx1-150025" >1870, 1871, 1872, 1873, 1874
    \glsmcols  790
    +href="glossaries-user.html#dx1-164015" >1875
    \glsmoveentry  791
    +href="glossaries-user.html#dx1-123001" >1876
    \GLSname  792
    +href="glossaries-user.html#dx1-134044" >1877
    \Glsname  793
    +href="glossaries-user.html#dx1-134043" >1878
    \glsname  794
    +href="glossaries-user.html#dx1-134038" >1879
    \glsnamefont  795
    +href="glossaries-user.html#dx1-141084" >1880, 1881, 1882
    \glsnavhypertarget  796
    +href="glossaries-user.html#dx1-166030" >1883
    \glsnavigation  797
    +href="glossaries-user.html#dx1-166031" >1884
    \glsnoexpandfields  798
    +href="glossaries-user.html#dx1-118023" >1885
    \glsnoidxdisplayloc  799
    +href="glossaries-user.html#dx1-130022" >1886
    +\glsnumberformat  1887, 1888, 1889, 1890, 1891, 1892
    \glsnumberlistloop  800
    +href="glossaries-user.html#dx1-130019" >1893
    +\glsnumbersgroupname  1894
    +\glsnumbersgrouptitle  1895
    \glsnumlistlastsep  801
    +href="glossaries-user.html#dx1-140066" >1896
    \glsnumlistsep  802
    +href="glossaries-user.html#dx1-140065" >1897
    \glsopenbrace  803
    +href="glossaries-user.html#dx1-142007" >1898
    \glspagelistwidth  804
    +href="glossaries-user.html#dx1-156017" >1899, 1900, 1901, 1902, 1903, 1904, 1905, 1906
    \glspar  805
    +href="glossaries-user.html#dx1-112022" >1907
    \glspatchtabularx  806
    +href="glossaries-user.html#dx1-133008" >1908
    \glspercentchar  807
    +href="glossaries-user.html#dx1-142009" >1909
    \GLSpl  808
    +href="glossaries-user.html#dx1-3027" >1910, 1911, 1912, 1913, 1914
    \Glspl  809
    +href="glossaries-user.html#dx1-3026" >1915, 1916, 1917, 1918, 1919, 1920, 1921
    \glspl  810
    +href="glossaries-user.html#dx1-3025" >1922, 1923, 1924, 1925, 1926, 1927, 1928, 1929, 1930, 1931, 1932
    \GLSplural  811
    +href="glossaries-user.html#dx1-134032" >1933
    \Glsplural  812
    +href="glossaries-user.html#dx1-134031" >1934
    \glsplural  813
    +href="glossaries-user.html#dx1-134028" >1935
    \glspluralsuffix  814
    +href="glossaries-user.html#dx1-112043" >1936, 1937, 1938, 1939, 1940, 1941
    \glspostdescription  815
    +href="glossaries-user.html#dx1-156039" >1942, 1943, 1944
    \glspostinline  816
    - - +href="glossaries-user.html#dx1-165014" >1945, 1946
    \glspostlinkhook  817
    +href="glossaries-user.html#dx1-135037" >1947, 1948, 1949, 1950, 1951
    +\glsprefixsep  1952
    \glsprestandardsort  818
    +href="glossaries-user.html#dx1-73024" >1953, 1954, 1955
    +\glsps  1956
    +\glspt  1957, 1958, 1959, 1960, 1961
    \glsquote  819
    +href="glossaries-user.html#dx1-142014" >1962
    \glsrefentry  820
    +href="glossaries-user.html#dx1-46004" >1963, 1964, 1965, 1966, 1967, 1968
    \glsreset  821
    +href="glossaries-user.html#dx1-64004" >1969, 1970, 1971
    \glsresetall  822
    +href="glossaries-user.html#dx1-153007" >1972
    \glsresetentrycounter  823
    +href="glossaries-user.html#dx1-47006" >1973
    \glsrestoreLToutput  824
    +href="glossaries-user.html#dx1-160023" >1974
    + + \glssee  825
    +href="glossaries-user.html#dx1-56005" >1975, 1976, 1977, 1978, 1979, 1980
    \glsseeformat  826
    +href="glossaries-user.html#dx1-139002" >1981, 1982
    \glsseeitemformat  827
    +href="glossaries-user.html#dx1-139011" >1983, 1984, 1985, 1986, 1987, 1988, 1989
    \glsseelastsep  828
    +href="glossaries-user.html#dx1-139009" >1990
    +\glsseelist  1991
    \glsseesep  829
    +href="glossaries-user.html#dx1-139008" >1992
    \glsSetAlphaCompositor  830
    +href="glossaries-user.html#dx1-111019" >1993, 1994
    +\glssetcategoryattribute  1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014
    \glsSetCompositor  831
    +href="glossaries-user.html#dx1-111018" >2015, 2016
    \glssetexpandfield  832
    +href="glossaries-user.html#dx1-118007" >2017
    \glssetnoexpandfield  833
    +href="glossaries-user.html#dx1-118008" >2018
    \GlsSetQuote  834
    +href="glossaries-user.html#dx1-7017" >2019, 2020
    \glsSetSuffixF  835
    +href="glossaries-user.html#dx1-130009" >2021
    \glsSetSuffixFF  836
    +href="glossaries-user.html#dx1-130010" >2022
    \glssetwidest  837
    +href="glossaries-user.html#dx1-163049" >2023, 2024, 2025, 2026, 2027
    \GlsSetWriteIstHook  838
    +href="glossaries-user.html#dx1-131002" >2028
    \GlsSetXdyCodePage  839
    +href="glossaries-user.html#dx1-16097" >2029, 2030, 2031
    \GlsSetXdyFirstLetterAfterDigits  840
    +href="glossaries-user.html#dx1-145004" >2032
    \GlsSetXdyLanguage  841
    +href="glossaries-user.html#dx1-16095" >2033, 2034, 2035, 2036
    \GlsSetXdyLocationClassOrder  842
    +href="glossaries-user.html#dx1-144061" >2037
    \GlsSetXdyMinRangeLength  843
    +href="glossaries-user.html#dx1-130004" >2038, 2039
    \GlsSetXdyNumberGroupOrder  844
    +href="glossaries-user.html#dx1-145007" >2040
    +\glsshortaccsupp  2041, 2042
    +\glsshortplaccsupp  2043, 2044
    \glsshorttok  845
    +href="glossaries-user.html#dx1-150026" >2045, 2046, 2047
    +\glsshowaccsupp  2048
    \glsshowtarget  846
    +href="glossaries-user.html#dx1-30008" >2049, 2050
    +\glsshowtargetfont  2051
    +\glsshowtargetouter  2052
    \glssortnumberfmt  847
    +href="glossaries-user.html#dx1-73016" >2053
    \glssubentrycounterlabel  848
    +href="glossaries-user.html#dx1-166067" >2054
    \glssubentryitem  849
    +href="glossaries-user.html#dx1-166064" >2055, 2056
    \GLSsymbol  850
    +href="glossaries-user.html#dx1-134049" >2057
    \Glssymbol  851
    +href="glossaries-user.html#dx1-134048" >2058
    \glssymbol  852
    +href="glossaries-user.html#dx1-134045" >2059, 2060, 2061, 2062, 2063, 2064
    +\glssymbolaccsupp  2065
    +\glssymbolsgroupname  2066, 2067
    \glstarget  853
    +href="glossaries-user.html#dx1-166049" >2068, 2069
    \GLStext  854
    +href="glossaries-user.html#dx1-116008" >2070, 2071
    \Glstext  855
    +href="glossaries-user.html#dx1-116007" >2072, 2073
    \glstext  856
    +href="glossaries-user.html#dx1-34009" >2074, 2075, 2076, 2077
    \glstextformat  857
    +href="glossaries-user.html#dx1-132025" >2078, 2079, 2080, 2081, 2082, 2083
    \glstextup  858
    +href="glossaries-user.html#dx1-150035" >2084
    \glstildechar  859
    +href="glossaries-user.html#dx1-142010" >2085
    \glstocfalse  860
    +href="glossaries-user.html#dx1-39002" >2086
    \glstoctrue  861
    +href="glossaries-user.html#dx1-39001" >2087
    + + \glstreechildpredesc  862
    - - +href="glossaries-user.html#dx1-163014" >2088
    \glstreegroupheaderfmt  863
    +href="glossaries-user.html#dx1-163006" >2089
    \glstreeindent  864
    +href="glossaries-user.html#dx1-163033" >2090
    \glstreeitem  865
    +href="glossaries-user.html#dx1-163019" >2091
    \glstreenamebox  866
    +href="glossaries-user.html#dx1-163054" >2092
    \glstreenamefmt  867
    +href="glossaries-user.html#dx1-163004" >2093
    \glstreenavigationfmt  868
    +href="glossaries-user.html#dx1-163008" >2094
    \glstreepredesc  869
    +href="glossaries-user.html#dx1-163011" >2095
    \glstreesubitem  870
    +href="glossaries-user.html#dx1-163020" >2096
    \glstreesubsubitem  871
    +href="glossaries-user.html#dx1-163021" >2097
    \glstype  872
    +href="glossaries-user.html#dx1-34018" >2098, 2099, 2100
    \glsunset  873
    +href="glossaries-user.html#dx1-153005" >2101
    \glsunsetall  874
    +href="glossaries-user.html#dx1-136016" >2102, 2103
    \GlsUseAcrEntryDispStyle  875
    +href="glossaries-user.html#dx1-150031" >2104
    \GlsUseAcrStyleDefs  876
    +href="glossaries-user.html#dx1-150032" >2105
    \GLSuseri  877
    +href="glossaries-user.html#dx1-134059" >2106
    \Glsuseri  878
    +href="glossaries-user.html#dx1-134058" >2107
    \glsuseri  879
    +href="glossaries-user.html#dx1-134055" >2108
    +\glsuseriaccsupp  2109
    \GLSuserii  880
    +href="glossaries-user.html#dx1-134064" >2110
    \Glsuserii  881
    +href="glossaries-user.html#dx1-134063" >2111
    \glsuserii  882
    +href="glossaries-user.html#dx1-134060" >2112
    \GLSuseriii  883
    +href="glossaries-user.html#dx1-134069" >2113
    \Glsuseriii  884
    +href="glossaries-user.html#dx1-134068" >2114
    \glsuseriii  885
    +href="glossaries-user.html#dx1-134065" >2115
    \GLSuseriv  886
    +href="glossaries-user.html#dx1-134074" >2116
    \Glsuseriv  887
    +href="glossaries-user.html#dx1-134073" >2117
    \glsuseriv  888
    +href="glossaries-user.html#dx1-134070" >2118
    \GLSuserv  889
    +href="glossaries-user.html#dx1-134079" >2119
    \Glsuserv  890
    +href="glossaries-user.html#dx1-134078" >2120
    \glsuserv  891
    +href="glossaries-user.html#dx1-134075" >2121
    \GLSuservi  892
    +href="glossaries-user.html#dx1-134084" >2122
    \Glsuservi  893
    +href="glossaries-user.html#dx1-134083" >2123
    \glsuservi  894
    +href="glossaries-user.html#dx1-134080" >2124
    \glswrallowprimitivemodsfalse  895
    +href="glossaries-user.html#dx1-129028" >2125
    \glswrite  896
    +href="glossaries-user.html#dx1-131003" >2126
    \glswriteentry  897
    -

    2127
    +\glsxtr@makeglossaries  2128
    +\glsxtr@record  2129
    +\glsxtr@record@nameref  2130
    +\glsxtr@recordsee  2131
    +\glsxtr@resource  2132, 2133
    +\glsxtr@texencoding  2134
    +\glsxtrabbrvfootnote  2135, 2136, 2137, 2138, 2139
    +\glsxtrabbrvtype  2140, 2141, 2142
    +\glsxtrbookindexname  2143
    + + +\glsxtrcombiningdiacriticrules  2144, 2145
    +\glsxtrcontrolrules  2146, 2147
    +\glsxtrdigitrules  2148, 2149
    +\glsxtrdopostpunc  2150, 2151
    +\glsxtrequationlocfmt  2152
    +\glsxtrfieldforlistloop  2153
    +\glsxtrfieldformatlist  2154, 2155
    +\glsxtrfmt  2156, 2157, 2158, 2159, 2160, 2161, 2162
    +\GlsXtrFmtField  2163
    +\glsxtrfootnotedescname  2164, 2165
    +\glsxtrfootnotedescsort  2166, 2167
    +\glsxtrfull  2168, 2169, 2170, 2171
    +\glsxtrfullsep  2172, 2173, 2174, 2175, 2176
    +\glsxtrgeneralpuncrules  2177, 2178
    +\glsxtrglossentry  2179, 2180, 2181
    +\glsxtrhyphenrules  2182, 2183
    +\GlsXtrIfFieldEqNum  2184
    +\GlsXtrIfFieldNonZero  2185
    +\glsxtrifhasfield  2186, 2187
    +\glsxtrifwasfirstuse  2188, 2189, 2190, 2191
    +\GlsXtrIfXpFieldEqXpStr  2192, 2193, 2194
    +\Glsxtrinlinefullformat  2195
    +\glsxtrinlinefullformat  2196
    +\Glsxtrinlinefullplformat  2197
    +\glsxtrinlinefullplformat  2198
    +\GlsXtrLoadResources  2199, 2200, 2201, 2202, 2203, 2204, 2205, 2206, 2207, 2208, 2209, 2210, 2211, 2212, 2213, 2214, 2215, 2216, 2217, 2218, 2219, 2220, 2221, 2222, 2223, 2224, 2225, 2226, 2227, 2228, 2229, 2230, 2231, 2232, 2233, 2234, 2235, 2236, 2237, 2238, 2239, 2240, 2241, 2242
    +\GlsXtrLoadResources options
    +    abbreviation-sort-fallback  2243
    +    append-prefix-field  2244
    +    break-at  2245, 2246, 2247, 2248, 2249
    +    category  2250
    +    combine-dual-locations  2251
    +    dual-category  2252
    +    dual-prefix  2253, 2254, 2255
    +    dual-sort  2256
    +    dual-type  2257, 2258, 2259
    +    entry-type-aliases  2260
    +    ext-prefixes  2261
    +    field-aliases  2262
    +    identical-sort-action  2263
    +    ignore-fields  2264
    +    label-prefix  2265
    +    loc-counters  2266
    +    name-case-change  2267
    +    primary-location-formats  2268
    + + +    replicate-fields  2269, 2270
    +    save-child-count  2271
    +    save-locations  2272, 2273, 2274
    +    save-loclist  2275
    +    save-sibling-count  2276, 2277, 2278, 2279
    +    save-locations  2280, 2281
    +    selection  2282, 2283, 2284, 2285, 2286, 2287, 2288
    +    set-widest  2289
    +    sort  2290, 2291, 2292, 2293, 2294, 2295, 2296, 2297, 2298, 2299, 2300, 2301
    +    sort-rule  2302
    +    src  2303, 2304, 2305, 2306, 2307, 2308, 2309, 2310, 2311, 2312, 2313, 2314, 2315, 2316, 2317, 2318, 2319, 2320, 2321, 2322, 2323, 2324, 2325, 2326, 2327, 2328, 2329, 2330, 2331, 2332, 2333, 2334, 2335, 2336, 2337, 2338, 2339, 2340, 2341, 2342, 2343, 2344
    +    type  2345, 2346, 2347
    +\glsxtrlong  2348, 2349, 2350, 2351
    +\glsxtrnewgls  2352
    +\glsxtrnewglslike  2353, 2354, 2355, 2356
    +\glsxtrnewnumber  2357
    +\glsxtrnewsymbol  2358, 2359, 2360, 2361
    +\glsxtrnonprintablerules  2362, 2363
    +\glsxtrnopostpunc  2364, 2365, 2366, 2367, 2368, 2369, 2370, 2371
    +\glsxtrp  2372
    +\glsxtrparen  2373, 2374, 2375, 2376, 2377
    +\glsxtrpostlinkAddSymbolOnFirstUse  2378
    +\glsxtrsectionlocfmt  2379, 2380, 2381
    +\GlsXtrSetAltModifier  2382, 2383
    +\glsxtrshort  2384, 2385, 2386, 2387, 2388
    +\glsxtrspacerules  2389, 2390
    +\GlsXtrUseAbbrStyleFmts  2391
    +\GlsXtrUseAbbrStyleSetup  2392
    +

    H html package  898
    +href="glossaries-user.html#dx1-136002" >2393
    +\hyperbf  2394, 2395, 2396, 2397, 2398, 2399
    +\hyperbfit  2400
    +\hyperbsf  2401
    +\hyperemph  2402
    +\hyperit  2403, 2404, 2405
    +\hyperlink  2406, 2407
    +\hypermd  2408
    +\hyperpage  2409
    hyperref package  899, 900, 901, 902, 903, 904, 905, 906, 907, 908, 909, 910, 911, 912, 913, 914, 915, 916, 917, 918, 919, 920, 921
    -

    2410, 2411, 2412, 2413, 2414, 2415, 2416, 2417, 2418, 2419, 2420, 2421, 2422, 2423, 2424, 2425, 2426, 2427, 2428, 2429, 2430, 2431, 2432, 2433, 2434, 2435, 2436, 2437, 2438, 2439, 2440, 2441, 2442
    +\hyperrm  2443, 2444, 2445
    +\hypersc  2446
    +\hypersf  2447
    + + +\hypersl  2448
    +\hypertarget  2449
    +\hypertt  2450
    +\hyperup  2451
    +

    I \ifglossaryexists  922
    +href="glossaries-user.html#dx1-169001" >2452
    \ifglsdescsuppressed  923
    +href="glossaries-user.html#dx1-169023" >2453
    \ifglsentryexists  924
    - - +href="glossaries-user.html#dx1-169002" >2454
    \ifglsfieldcseq  925
    +href="glossaries-user.html#dx1-169034" >2455
    \ifglsfielddefeq  926
    +href="glossaries-user.html#dx1-169032" >2456
    \ifglsfieldeq  927
    +href="glossaries-user.html#dx1-150085" >2457, 2458
    \ifglshaschildren  928
    +href="glossaries-user.html#dx1-169011" >2459, 2460
    \ifglshasdesc  929
    +href="glossaries-user.html#dx1-169021" >2461
    \ifglshasfield  930
    +href="glossaries-user.html#dx1-169026" >2462
    \ifglshaslong  931
    +href="glossaries-user.html#dx1-34021" >2463, 2464, 2465, 2466, 2467
    \ifglshasparent  932
    +href="glossaries-user.html#dx1-169012" >2468
    \ifglshasprefix  933
    +href="glossaries-user.html#dx1-171041" >2469
    \ifglshasprefixfirst  934
    +href="glossaries-user.html#dx1-171045" >2470
    \ifglshasprefixfirstplural  935
    +href="glossaries-user.html#dx1-171047" >2471
    \ifglshasprefixplural  936
    +href="glossaries-user.html#dx1-171043" >2472
    \ifglshasshort  937
    +href="glossaries-user.html#dx1-150012" >2473, 2474, 2475
    \ifglshassymbol  938
    +href="glossaries-user.html#dx1-11052" >2476, 2477, 2478
    \ifglsucmark  939
    +href="glossaries-user.html#dx1-42011" >2479
    \ifglsused  940, 941
    +href="glossaries-user.html#dx1-34019" >2480, 2481, 2482, 2483, 2484, 2485, 2486, 2487, 2488, 2489
    +\ifglsxtrinsertinside  2490, 2491, 2492, 2493, 2494, 2495, 2496, 2497
    \ifignoredglossary  942
    +href="glossaries-user.html#dx1-146014" >2498
    imakeidx package  943
    +href="glossaries-user.html#dx1-87011" >2499
    +\include  2500
    +\includegraphics  2501, 2502
    +\index  2503, 2504, 2505, 2506
    index package  944
    +href="glossaries-user.html#dx1-87010" >2507
    +\indexname  2508
    +\indexspace  2509, 2510, 2511, 2512
    +\input  2513, 2514
    inputenc package  945, 946, 947, 948, 949, 950, 951
    +href="glossaries-user.html#dx1-13015" >2515, 2516, 2517, 2518, 2519, 2520, 2521
    +\inputencodingname  2522
    internal fields:
    -    location  952
    -

        location  2523, 2524, 2525
    +    loclist  2526
    +    siblingcount  2527, 2528
    +    useri  2529
    +\item  2530, 2531
    +

    J + + +\jobname  2532, 2533
    +

    L +\label  2534
    latex  953, 954
    +href="glossaries-user.html#dx1-28" >2535, 2536
    latexmk  955, 956, 957
    +href="glossaries-user.html#dx1-16019" >2537, 2538, 2539
    Latin alphabet  958, 959, 960
    +href="glossaries-user.html#dx1-3038" >2540, 2541, 2542
    Latin character  961, 962, 963, 964, 965, 966, 967
    +href="glossaries-user.html#dx1-3015" >2543, 2544, 2545, 2546, 2547, 2548, 2549
    link text  968, 969, 970, 971, 972, 973, 974, 975, 976, 977, 978, 979, 980, 981, 982, 983, 984, 985, 986, 987, 988, 989, 990, 991, 992, 993, 994, 995, 996, 997, 998, 999, 1000, 1001, 1002, 1003, 1004, 1005, 1006, 1007, 1008, 1009, 1010, 1011, 1012, 1013, 1014, 1015, 1016
    +href="glossaries-user.html#dx1-3042" >2550, 2551, 2552, 2553, 2554, 2555, 2556, 2557, 2558, 2559, 2560, 2561, 2562, 2563, 2564, 2565, 2566, 2567, 2568, 2569, 2570, 2571, 2572, 2573, 2574, 2575, 2576, 2577, 2578, 2579, 2580, 2581, 2582, 2583, 2584, 2585, 2586, 2587, 2588, 2589, 2590, 2591, 2592, 2593, 2594, 2595, 2596, 2597, 2598, 2599, 2600, 2601, 2602, 2603, 2604, 2605, 2606, 2607, 2608, 2609, 2610, 2611, 2612, 2613, 2614, 2615, 2616
    +\listbreak  2617
    \loadglsentries  1017
    +href="glossaries-user.html#dx1-6003" >2618, 2619, 2620, 2621, 2622, 2623, 2624, 2625, 2626
    location list  see number list
    +href="glossaries-user.html#dx1-127004" >number list
    \longnewglossaryentry  1019
    +href="glossaries-user.html#dx1-112004" >2628, 2629, 2630, 2631
    \longprovideglossaryentry  1020
    +href="glossaries-user.html#dx1-112006" >2632
    longtable package  1021, 1022
    -

    2633, 2634
    +

    M +\makeatletter  2635
    +\makeatother  2636
    +\makefirstuc  2637, 2638, 2639, 2640
    makeglossaries  1023, 1024, 1025, 1026, 1027, 1028, 1029, 1030, 1031, 1032, 1033, 1034, 1035, 1036, 1037, 1038, 1039, 1040, 1041, 1042, 1043, 1044, 1045, 1046, 1047, 1048, 1049, 1050, 1051, 1052, 1053, 1054, 1055, 1056, 1057, 1058, 1059, 1060, 1061, 1062, 1063, 1064, 1065, 1066, 1067, 1068, 1069, 1070, 1071, 1072, 1073, 1074, 1075, 1076, 1077, 1078, 1079, 1080, 1081, 1082, 1083, 1084, 1085, 1086, 1087, 1088, 1089, 1090, 1091, 1092, 1093, 1094, 1095, 1096, 1097, 1098, 1099, 1100, 1101, 1102, 1103
    +href="glossaries-user.html#dx1-3044" >2641, 2642, 2643, 2644, 2645, 2646, 2647, 2648, 2649, 2650, 2651, 2652, 2653, 2654, 2655, 2656, 2657, 2658, 2659, 2660, 2661, 2662, 2663, 2664, 2665, 2666, 2667, 2668, 2669, 2670, 2671, 2672, 2673, 2674, 2675, 2676, 2677, 2678, 2679, 2680, 2681, 2682, 2683, 2684, 2685, 2686, 2687, 2688, 2689, 2690, 2691, 2692, 2693, 2694, 2695, 2696, 2697, 2698, 2699, 2700, 2701, 2702, 2703, 2704, 2705, 2706, 2707, 2708, 2709, 2710, 2711, 2712, 2713, 2714, 2715, 2716, 2717, 2718, 2719, 2720, 2721, 2722, 2723, 2724, 2725, 2726, 2727, 2728, 2729, 2730, 2731, 2732, 2733, 2734, 2735, 2736, 2737, 2738, 2739, 2740
        -d  1104
    +href="glossaries-user.html#dx1-18004" >2741
        -k  1105
    +href="glossaries-user.html#dx1-17015" >2742
        -m  1106
    +href="glossaries-user.html#dx1-17023" >2743
        -Q  1107
    +href="glossaries-user.html#dx1-17014" >2744
        -q  1108
    +href="glossaries-user.html#dx1-17017" >2745
        -x  1109
    - - +href="glossaries-user.html#dx1-17025" >2746
    \makeglossaries  1110
    +href="glossaries-user.html#dx1-7001" >2747, 2748, 2749, 2750, 2751, 2752, 2753, 2754, 2755, 2756, 2757, 2758, 2759, 2760, 2761, 2762, 2763, 2764, 2765, 2766, 2767, 2768, 2769, 2770, 2771, 2772, 2773, 2774, 2775, 2776, 2777, 2778, 2779, 2780, 2781, 2782, 2783
    makeglossaries-lite  1111, 1112, 1113, 1114, 1115, 1116, 1117, 1118, 1119, 1120, 1121, 1122, 1123, 1124, 1125, 1126, 1127
    +href="glossaries-user.html#dx1-3049" >2784, 2785, 2786, 2787, 2788, 2789, 2790, 2791, 2792, 2793, 2794, 2795, 2796, 2797, 2798, 2799, 2800, 2801, 2802, 2803, 2804, 2805, 2806, 2807, 2808, 2809, 2810
    makeglossariesgui  1128, 1129, 1130
    +href="glossaries-user.html#dx1-3047" >2811, 2812, 2813
    makeidx package  1131
    +href="glossaries-user.html#dx1-87009" >2814
    makeindex  1132, 1133, 1134, 1135, 1136, 1137, 1138, 1139, 1140, 1141, 1142, 1143, 1144, 1145, 1146, 1147, 1148, 1149, 1150, 1151, 1152, 1153, 1154, 1155, 1156, 1157, 1158, 1159, 1160, 1161, 1162, 1163, 1164, 1165, 1166, 1167, 1168, 1169, 1170, 1171, 1172, 1173, 1174, 1175, 1176, 1177, 1178, 1179, 1180, 1181, 1182, 1183, 1184, 1185, 1186, 1187, 1188, 1189, 1190, 1191, 1192, 1193, 1194, 1195, 1196, 1197, 1198, 1199, 1200, 1201, 1202, 1203, 1204, 1205, 1206, 1207, 1208, 1209, 1210, 1211, 1212, 1213, 1214, 1215, 1216, 1217, 1218, 1219, 1220, 1221, 1222, 1223, 1224, 1225, 1226, 1227, 1228, 1229, 1230, 1231, 1232, 1233, 1234, 1235, 1236, 1237, 1238, 1239, 1240, 1241, 1242, 1243, 1244, 1245
    +href="glossaries-user.html#dx1-3004" >2815, 2816, 2817, 2818, 2819, 2820, 2821, 2822, 2823, 2824, 2825, 2826, 2827, 2828, 2829, 2830, 2831, 2832, 2833, 2834, 2835, 2836, 2837, 2838, 2839, 2840, 2841, 2842, 2843, 2844, 2845, 2846, 2847, 2848, 2849, 2850, 2851, 2852, 2853, 2854, 2855, 2856, 2857, 2858, 2859, 2860, 2861, 2862, 2863, 2864, 2865, 2866, 2867, 2868, 2869, 2870, 2871, 2872, 2873, 2874, 2875, 2876, 2877, 2878, 2879, 2880, 2881, 2882, 2883, 2884, 2885, 2886, 2887, 2888, 2889, 2890, 2891, 2892, 2893, 2894, 2895, 2896, 2897, 2898, 2899, 2900, 2901, 2902, 2903, 2904, 2905, 2906, 2907, 2908, 2909, 2910, 2911, 2912, 2913, 2914, 2915, 2916, 2917, 2918, 2919, 2920, 2921, 2922, 2923, 2924, 2925, 2926, 2927, 2928, 2929, 2930, 2931, 2932, 2933, 2934, 2935, 2936, 2937, 2938, 2939, 2940, 2941, 2942, 2943, 2944, 2945, 2946, 2947, 2948, 2949, 2950, 2951, 2952, 2953, 2954, 2955, 2956, 2957, 2958, 2959, 2960, 2961, 2962, 2963
        -g  1246, 1247, 1248
    +href="glossaries-user.html#dx1-7016" >2964, 2965, 2966
        -l  1249, 1250, 1251, 1252, 1253
    +href="glossaries-user.html#dx1-7042" >2967, 2968, 2969, 2970, 2971
    \makenoidxglossaries  1254
    +href="glossaries-user.html#dx1-6001" >2972, 2973, 2974, 2975, 2976, 2977, 2978, 2979, 2980, 2981, 2982
    +\MakeTextUppercase  2983, 2984
    +\markboth  2985
    + + memoir class  1255, 1256, 1257, 1258
    +href="glossaries-user.html#dx1-42002" >2986, 2987, 2988, 2989
    +\memUChead  2990
    mfirstuc package  1259, 1260, 1261, 1262, 1263, 1264, 1265, 1266
    +href="glossaries-user.html#dx1-6" >2991, 2992, 2993, 2994, 2995, 2996, 2997
    +\mfirstucMakeUppercase  2998
    +\midrule  2999
    multicol package  1267
    +href="glossaries-user.html#dx1-164004" >3000
    mwe package  1268
    -

    3001, 3002
    +

    N nameref package  1269
    +href="glossaries-user.html#dx1-43014" >3003
    +\newabbreviation  3004, 3005, 3006, 3007, 3008, 3009, 3010, 3011, 3012, 3013, 3014, 3015, 3016, 3017, 3018, 3019, 3020, 3021, 3022, 3023, 3024, 3025, 3026, 3027, 3028, 3029, 3030, 3031, 3032, 3033, 3034, 3035
    +\newabbreviationstyle  3036
    \newacronym  1270
    +href="glossaries-user.html#dx1-12011" >3037, 3038, 3039, 3040, 3041, 3042, 3043, 3044, 3045, 3046, 3047, 3048, 3049, 3050, 3051, 3052, 3053, 3054, 3055, 3056, 3057, 3058, 3059, 3060, 3061, 3062, 3063, 3064, 3065, 3066, 3067, 3068, 3069, 3070, 3071, 3072, 3073, 3074, 3075, 3076, 3077, 3078, 3079, 3080, 3081, 3082, 3083, 3084, 3085, 3086, 3087, 3088, 3089, 3090, 3091, 3092, 3093, 3094, 3095, 3096, 3097, 3098, 3099
    \newacronymstyle  1271
    +href="glossaries-user.html#dx1-150001" >3100, 3101, 3102
    +\newdualentry  3103, 3104
    \newglossary  1272
    +href="glossaries-user.html#dx1-19020" >3105, 3106, 3107, 3108, 3109, 3110, 3111
    \newglossary*  1273
    +href="glossaries-user.html#dx1-146007" >3112, 3113, 3114, 3115
    \newglossaryentry  1274
    +href="glossaries-user.html#dx1-3033" >3116, 3117, 3118, 3119, 3120, 3121, 3122, 3123, 3124, 3125, 3126, 3127, 3128, 3129, 3130, 3131, 3132, 3133, 3134, 3135, 3136, 3137, 3138, 3139, 3140, 3141, 3142, 3143, 3144, 3145, 3146, 3147, 3148
    \newglossaryentry options
        access  1275
    -    description  1276, 1277, 1278, 1279, 1280, 1281, 1282, 1283, 1284, 1285, 1286, 1287, 1288, 1289, 1290, 1291, 1292, 1293
    -    descriptionaccess  1294
    -    descriptionplural  1295, 1296, 1297, 1298
    -    descriptionpluralaccess  1299
    +class="cmtt-10">access  3149, 3150
    +    alias  3151, 3152, 3153, 3154
    +    category  3155, 3156, 3157, 3158, 3159, 3160, 3161, 3162, 3163, 3164, 3165, 3166, 3167, 3168, 3169
    +    description  3170, 3171, 3172, 3173, 3174, 3175, 3176, 3177, 3178, 3179, 3180, 3181, 3182, 3183, 3184, 3185, 3186, 3187, 3188, 3189, 3190, 3191, 3192
    +    descriptionaccess  3193
    +    descriptionplural  3194, 3195, 3196, 3197
    +    descriptionpluralaccess  3198
    +    entrycounter  3199, 3200
    +    first  3201, 3202, 3203, 3204, 3205, 3206, 3207, 3208, 3209, 3210, 3211, 3212, 3213, 3214, 3215, 3216, 3217, 3218, 3219, 3220, 3221, 3222, 3223, 3224, 3225, 3226, 3227, 3228
    +    firstaccess  3229
    +    firstplural  3230, 3231, 3232, 3233, 3234, 3235, 3236, 3237, 3238, 3239, 3240, 3241, 3242, 3243, 3244, 3245, 3246, 3247, 3248, 3249
    +    firstpluralaccess  3250
        entrycounter  1300, 1301
    -    first  1302, 1303, 1304, 1305, 1306, 1307, 1308, 1309, 1310, 1311, 1312, 1313, 1314, 1315, 1316, 1317, 1318, 1319, 1320, 1321, 1322, 1323, 1324, 1325, 1326
    -    firstaccess  1327
    -    firstplural  1328, 1329, 1330, 1331, 1332, 1333, 1334, 1335, 1336, 1337, 1338, 1339, 1340, 1341, 1342, 1343, 1344, 1345
    -    firstpluralaccess  1346
    -    format  1347
    -    long  1348, 1349, 1350, 1351, 1352, 1353, 1354, 1355, 1356, 1357, 1358, 1359, 1360
    -    longaccess  1361
    -    longplural  1362, 1363, 1364, 1365, 1366, 1367, 1368, 1369, 1370, 1371, 1372
    -    longpluralaccess  1373
    -    name  1374, 1375, 1376, 1377, 1378, 1379, 1380, 1381, 1382, 1383, 1384, 1385, 1386, 1387, 1388, 1389, 1390, 1391, 1392, 1393, 1394, 1395, 1396, 1397, 1398, 1399, 1400, 1401, 1402, 1403, 1404, 1405, 1406, 1407, 1408, 1409
    -    nonumberlist  1410
    -    parent  1411, 1412, 1413, 1414
    -    plural  1415, 1416, 1417, 1418, 1419, 1420, 1421, 1422, 1423, 1424, 1425, 1426, 1427, 1428, 1429, 1430, 1431
    -    pluralaccess  1432
    -    prefix  1433, 1434, 1435, 1436, 1437, 1438, 1439
    - - -    prefixfirst  1440, 1441, 1442, 1443, 1444
    -    prefixfirstplural  1445, 1446, 1447, 1448, 1449
    -    prefixplural  1450, 1451, 1452, 1453, 1454, 1455
    -    see  1456, 1457, 1458, 1459, 1460, 1461, 1462, 1463, 1464, 1465, 1466, 1467, 1468, 1469, 1470, 1471, 1472, 1473, 1474
    -    short  1475, 1476, 1477, 1478, 1479, 1480, 1481, 1482, 1483, 1484, 1485
    -    shortaccess  1486
    -    shortplural  1487, 1488, 1489, 1490, 1491, 1492, 1493, 1494, 1495, 1496, 1497, 1498
    -    shortpluralaccess  1499
    -    sort  1500, 1501, 1502, 1503, 1504, 1505, 1506, 1507, 1508, 1509, 1510, 1511, 1512, 1513, 1514, 1515, 1516, 1517, 1518, 1519, 1520, 1521, 1522, 1523, 1524, 1525, 1526, 1527, 1528, 1529, 1530, 1531, 1532, 1533
    -    subentrycounter  1534
    -    symbol  1535, 1536, 1537, 1538, 1539, 1540, 1541, 1542, 1543, 1544, 1545, 1546, 1547
    -    symbolaccess  1548
    -    symbolplural  1549, 1550, 1551
    -    symbolpluralaccess  1552
    -    text  1553, 1554, 1555, 1556, 1557, 1558, 1559, 1560, 1561, 1562, 1563, 1564, 1565, 1566, 1567, 1568, 1569, 1570, 1571, 1572, 1573
    -    textaccess  1574
    -    type  1575, 1576, 1577
    -    user1  1578, 1579, 1580, 1581, 1582, 1583, 1584, 1585, 1586, 1587, 1588
    -    user2  1589, 1590, 1591, 1592
    -    user3  1593, 1594, 1595
    -    user4  1596, 1597, 1598
    -    user5  1599, 1600, 1601
    -    user6  1602, 1603, 1604, 1605
    +class="cmtt-10">long  3251, 3252, 3253, 3254, 3255, 3256, 3257, 3258, 3259, 3260, 3261, 3262, 3263, 3264
    +    longaccess  3265
    +    longplural  3266, 3267, 3268, 3269, 3270, 3271, 3272, 3273, 3274, 3275, 3276
    +    longpluralaccess  3277
    +    name  3278, 3279, 3280, 3281, 3282, 3283, 3284, 3285, 3286, 3287, 3288, 3289, 3290, 3291, 3292, 3293, 3294, 3295, 3296, 3297, 3298, 3299, 3300, 3301, 3302, 3303, 3304, 3305, 3306, 3307, 3308, 3309, 3310, 3311, 3312, 3313, 3314, 3315, 3316, 3317, 3318, 3319, 3320, 3321, 3322, 3323, 3324, 3325, 3326, 3327, 3328, 3329, 3330, 3331, 3332, 3333, 3334, 3335, 3336, 3337, 3338
    +    nonumberlist  3339
    +    parent  3340, 3341, 3342, 3343
    +    plural  3344, 3345, 3346, 3347, 3348, 3349, 3350, 3351, 3352, 3353, 3354, 3355, 3356, 3357, 3358, 3359, 3360, 3361, 3362, 3363, 3364, 3365, 3366
    + + +    pluralaccess  3367
    +    prefix  3368, 3369, 3370, 3371, 3372, 3373, 3374, 3375, 3376
    +    prefixfirst  3377, 3378, 3379, 3380, 3381
    +    prefixfirstplural  3382, 3383, 3384, 3385
    +    prefixplural  3386, 3387, 3388, 3389, 3390, 3391, 3392, 3393
    +    see  3394, 3395, 3396, 3397, 3398, 3399, 3400, 3401, 3402, 3403, 3404, 3405, 3406, 3407, 3408, 3409, 3410, 3411, 3412, 3413, 3414, 3415, 3416, 3417, 3418, 3419, 3420, 3421, 3422
    +    seealso  3423, 3424, 3425, 3426, 3427, 3428, 3429, 3430, 3431, 3432
    +    short  3433, 3434, 3435, 3436, 3437, 3438, 3439, 3440, 3441, 3442, 3443, 3444, 3445, 3446, 3447, 3448
    +    shortaccess  3449, 3450, 3451, 3452, 3453, 3454, 3455
    +    shortplural  3456, 3457, 3458, 3459, 3460, 3461, 3462, 3463, 3464, 3465, 3466, 3467, 3468
    +    shortpluralaccess  3469
    +    sort  3470, 3471, 3472, 3473, 3474, 3475, 3476, 3477, 3478, 3479, 3480, 3481, 3482, 3483, 3484, 3485, 3486, 3487, 3488, 3489, 3490, 3491, 3492, 3493, 3494, 3495, 3496, 3497, 3498, 3499, 3500, 3501, 3502, 3503, 3504, 3505, 3506, 3507, 3508, 3509, 3510, 3511, 3512, 3513, 3514, 3515, 3516, 3517, 3518, 3519, 3520, 3521, 3522, 3523, 3524, 3525, 3526, 3527, 3528, 3529, 3530, 3531
    +    subentrycounter  3532
    +    symbol  3533, 3534, 3535, 3536, 3537, 3538, 3539, 3540, 3541, 3542, 3543, 3544, 3545, 3546, 3547, 3548, 3549, 3550, 3551, 3552
    +    symbolaccess  3553, 3554
    +    symbolplural  3555, 3556, 3557
    +    symbolpluralaccess  3558
    +    text  3559, 3560, 3561, 3562, 3563, 3564, 3565, 3566, 3567, 3568, 3569, 3570, 3571, 3572, 3573, 3574, 3575, 3576, 3577, 3578, 3579, 3580, 3581, 3582, 3583, 3584, 3585, 3586, 3587, 3588, 3589, 3590, 3591, 3592
    +    textaccess  3593
    +    type  3594, 3595, 3596, 3597, 3598, 3599, 3600, 3601, 3602
    +    user1  3603, 3604, 3605, 3606, 3607, 3608, 3609, 3610, 3611, 3612, 3613, 3614, 3615, 3616, 3617, 3618, 3619
    +    user1access  3620, 3621
    +    user2  3622, 3623, 3624, 3625, 3626
    +    user2access  3627
    +    user3  3628, 3629, 3630, 3631
    +    user3access  3632
    +    user4  3633, 3634, 3635, 3636
    +    user4access  3637
    +    user5  3638, 3639, 3640, 3641
    +    user5access  3642
    +    user6  3643, 3644, 3645, 3646, 3647
    +    user6access  3648
    \newglossarystyle  1606
    +href="glossaries-user.html#dx1-156035" >3649, 3650, 3651, 3652
    \newignoredglossary  1607
    +href="glossaries-user.html#dx1-34012" >3653, 3654, 3655, 3656, 3657
    +\newline  3658, 3659
    \newterm  1608
    +href="glossaries-user.html#dx1-87001" >3660, 3661
    ngerman package  1609, 1610, 1611, 1612
    +href="glossaries-user.html#dx1-13029" >3662, 3663, 3664, 3665
    +\nohyperpage  3666
    \noist  1613
    +href="glossaries-user.html#dx1-111008" >3667, 3668, 3669, 3670, 3671, 3672, 3673, 3674, 3675, 3676, 3677, 3678
    Non-Latin Alphabet  1614
    +href="glossaries-user.html#dx1-3054" >3679
    non-Latin character  1615, 1616, 1617, 1618, 1619, 1620, 1621, 1622, 1623, 1624, 1625
    +href="glossaries-user.html#dx1-3020" >3680, 3681, 3682, 3683, 3684, 3685, 3686, 3687, 3688, 3689, 3690
    \nopostdesc  1626
    +href="glossaries-user.html#dx1-87003" >3691, 3692, 3693, 3694, 3695, 3696, 3697, 3698, 3699, 3700, 3701, 3702, 3703
    +\nopostdot  3704
    + + +\null  3705, 3706
    +\number  3707
    number list  1627, 1628, 1629, 1630, 1631, 1632, 1633, 1634, 1635, 1636, 1637, 1638, 1639, 1640, 1641, 1642, 1643, 1644, 1645, 1646, 1647, 1648, 1649, 1650, 1651, 1652, 1653, 1654, 1655, 1656, 1657, 1658, 1659, 1660, 1661, 1662, 1663, 1664, 1665, 1666, 1667, 1668, 1669, 1670, 1671, 1672, 1673, 1674, 1675, 1676, 1677, 1678, 1679, 1680, 1681, 1682, 1683, 1684, 1685, 1686, 1687, 1688, 1689, 1690, 1691, 1692, 1693
    -

    3708, 3709, 3710, 3711, 3712, 3713, 3714, 3715, 3716, 3717, 3718, 3719, 3720, 3721, 3722, 3723, 3724, 3725, 3726, 3727, 3728, 3729, 3730, 3731, 3732, 3733, 3734, 3735, 3736, 3737, 3738, 3739, 3740, 3741, 3742, 3743, 3744, 3745, 3746, 3747, 3748, 3749, 3750, 3751, 3752, 3753, 3754, 3755, 3756, 3757, 3758, 3759, 3760, 3761, 3762, 3763, 3764, 3765, 3766, 3767, 3768, 3769, 3770, 3771, 3772, 3773, 3774, 3775, 3776, 3777, 3778, 3779, 3780, 3781, 3782, 3783, 3784, 3785, 3786, 3787, 3788, 3789, 3790, 3791, 3792, 3793, 3794, 3795
    +\numberline  3796
    +

    O \oldacronym  1694
    -

    3797, 3798
    +

    P package options:
    +    abbreviations  3799, 3800, 3801, 3802, 3803, 3804, 3805, 3806
    +    accsupp  3807, 3808, 3809
        acronym  1695, 1696, 1697, 1698, 1699, 1700, 1701, 1702, 1703, 1704, 1705, 1706, 1707, 1708, 1709, 1710, 1711, 1712, 1713, 1714, 1715, 1716, 1717, 1718
    +href="glossaries-user.html#dx1-14026" >3810, 3811, 3812, 3813, 3814, 3815, 3816, 3817, 3818, 3819, 3820, 3821, 3822, 3823, 3824, 3825, 3826, 3827, 3828, 3829, 3830, 3831, 3832, 3833, 3834, 3835, 3836, 3837, 3838, 3839, 3840, 3841, 3842, 3843, 3844
            true  1719, 1720
    - - +href="glossaries-user.html#dx1-25002" >3845, 3846
        acronymlists  1721, 1722, 1723, 1724, 1725, 1726, 1727
    +href="glossaries-user.html#x1-930002.7" >3847, 3848, 3849, 3850, 3851, 3852, 3853
        acronyms  1728, 1729
    +href="glossaries-user.html#dx1-84003" >3854, 3855, 3856
        automake  1730, 1731, 1732, 1733
    +href="glossaries-user.html#dx1-7010" >3857, 3858, 3859, 3860
            false  1734
    +href="glossaries-user.html#dx1-79021" >3861
            immediate  1735, 1736, 1737
    +href="glossaries-user.html#dx1-79005" >3862, 3863, 3864
            true  1738, 1739
    +href="glossaries-user.html#dx1-79001" >3865, 3866
    +    autoseeindex  3867
    +        false  3868, 3869
        compatible-2.07  1740, 1741, 1742
    +href="glossaries-user.html#x1-1050002.8" >3870, 3871, 3872
        compatible-3.07  1743, 1744, 1745
    +href="glossaries-user.html#dx1-90003" >3873, 3874, 3875
        counter  1746, 1747, 1748, 1749, 1750
    +href="glossaries-user.html#x1-570002.3" >3876, 3877, 3878, 3879, 3880
    +        equation  3881
            page  1751
    +href="glossaries-user.html#dx1-57001" >3882
        counterwithin  1752, 1753, 1754, 1755, 1756
    +href="glossaries-user.html#x1-470002.3" >3883, 3884, 3885, 3886, 3887
        debug  1757, 1758, 1759
    +href="glossaries-user.html#dx1-27002" >3888, 3889, 3890, 3891
    +        all  3892
            false  1760
    +href="glossaries-user.html#dx1-30001" >3893, 3894
    +        showaccsupp  3895, 3896, 3897
            showtargets  1761, 1762, 1763
    +href="glossaries-user.html#dx1-30007" >3898
    +        showwrgloss  3899
    +        true  3900
    +    description (deprecated)  3901, 3902, 3903, 3904, 3905, 3906, 3907, 3908, 3909
    +    disablemakegloss  3910, 3911
    +    docdef  3912
    +        atom  3913, 3914
    +        false  3915
    +        restricted  3916, 3917, 3918, 3919
            true  1764, 1765, 1766
    -    description  1767, 1768, 1769, 1770, 1771, 1772, 1773, 1774, 1775
    -    dua  1776, 1777
    +href="glossaries-user.html#dx1-5011" >3920, 3921
    + + +    dua (deprecated)  3922, 3923
        entrycounter  1778, 1779, 1780, 1781, 1782
    +href="glossaries-user.html#x1-460002.3" >3924, 3925, 3926, 3927, 3928
            false  1783
    +href="glossaries-user.html#dx1-46001" >3929
            true  1784
    +href="glossaries-user.html#dx1-47001" >3930
    +    equations  3931
        esclocations  1785
    +href="glossaries-user.html#x1-630002.4" >3932
            false  1786, 1787, 1788
    +href="glossaries-user.html#dx1-63003" >3933, 3934, 3935
            true  1789
    -    footnote  1790, 1791, 1792, 1793, 1794, 1795
    +href="glossaries-user.html#dx1-63001" >3936
    +    floats  3937
    +    footnote (deprecated)  3938, 3939, 3940, 3941, 3942, 3943
        hyperfirst  1796, 1797, 1798, 1799
    +href="glossaries-user.html#x1-340002.1" >3944, 3945, 3946, 3947
            false  1800, 1801, 1802, 1803, 1804
    +href="glossaries-user.html#dx1-34014" >3948, 3949, 3950, 3951, 3952, 3953, 3954
            true  1805, 1806
    +href="glossaries-user.html#dx1-34001" >3955, 3956
        index  1807, 1808, 1809, 1810, 1811, 1812, 1813
    +href="glossaries-user.html#dx1-84006" >3957, 3958, 3959, 3960, 3961, 3962, 3963
    +    indexcounter  3964
    +    indexcrossrefs  3965
        indexonlyfirst  1814, 1815, 1816
    +href="glossaries-user.html#x1-640002.4" >3966, 3967, 3968, 3969
            false  1817
    +href="glossaries-user.html#dx1-64001" >3970
        kernelglossredefs  1818
    +href="glossaries-user.html#x1-1070002.8" >3971
            false  1819
    +href="glossaries-user.html#dx1-107002" >3972
        makeindex  1820, 1821, 1822
    -    ngerman  1823
    +href="glossaries-user.html#dx1-25004" >3973, 3974, 3975
        noglossaryindex  1824
    +href="glossaries-user.html#x1-880002.6" >3976
        nogroupskip  1825, 1826, 1827, 1828, 1829, 1830, 1831, 1832
    +href="glossaries-user.html#x1-590002.3" >3977, 3978, 3979, 3980, 3981, 3982, 3983, 3984
            false  1833
    +href="glossaries-user.html#dx1-59001" >3985
    +    nohyperfirst  3986
        nohypertypes  1834, 1835, 1836, 1837, 1838, 1839, 1840, 1841, 1842
    +href="glossaries-user.html#dx1-34003" >3987, 3988, 3989, 3990, 3991, 3992, 3993, 3994, 3995
            index  1843
    +href="glossaries-user.html#dx1-87013" >3996
        nolangwarn  1844, 1845
    +href="glossaries-user.html#dx1-3" >3997, 3998
        nolist  1846, 1847, 1848
    +href="glossaries-user.html#x1-520002.3" >3999, 4000, 4001
        nolong  1849, 1850, 1851, 1852
    +href="glossaries-user.html#x1-500002.3" >4002, 4003, 4004, 4005, 4006
        nomain  1853, 1854, 1855, 1856, 1857, 1858, 1859, 1860, 1861
    +href="glossaries-user.html#x1-840002.6" >4007, 4008, 4009, 4010, 4011, 4012, 4013, 4014, 4015, 4016, 4017, 4018
    +    nomissingglstext  4019
        nonumberlist  1862, 1863, 1864, 1865, 1866, 1867, 1868, 1869, 1870, 1871
    +href="glossaries-user.html#dx1-3060" >4020, 4021, 4022, 4023, 4024, 4025, 4026, 4027, 4028, 4029, 4030, 4031, 4032
        nopostdot  1872, 1873
    +href="glossaries-user.html#x1-580002.3" >4033, 4034
            false  1874
    - - +href="glossaries-user.html#dx1-58003" >4035, 4036, 4037, 4038, 4039, 4040
    +        true  4041, 4042, 4043, 4044
        noredefwarn  1875
    +href="glossaries-user.html#x1-290002.1" >4045
        nostyles  1876, 1877, 1878, 1879, 1880, 1881, 1882
    +href="glossaries-user.html#dx1-11021" >4046, 4047, 4048, 4049, 4050, 4051, 4052, 4053, 4054, 4055, 4056, 4057
        nosuper  1883, 1884, 1885, 1886
    +href="glossaries-user.html#x1-510002.3" >4058, 4059, 4060, 4061, 4062
        notranslate  1887, 1888, 1889
    +href="glossaries-user.html#dx1-14010" >4063, 4064, 4065
        notree  1890, 1891, 1892, 1893
    +href="glossaries-user.html#x1-530002.3" >4066, 4067, 4068, 4069
        nowarn  1894, 1895, 1896
    +href="glossaries-user.html#x1-270002.1" >4070, 4071, 4072
        numberedsection  1897, 1898, 1899, 1900, 1901
    +href="glossaries-user.html#dx1-41001" >4073, 4074, 4075, 4076, 4077, 4078
            autolabel  1902, 1903
    +href="glossaries-user.html#dx1-43004" >4079, 4080, 4081
            false  1904
    +href="glossaries-user.html#dx1-43002" >4082
            nameref  1905
    +href="glossaries-user.html#dx1-43010" >4083
    + +         nolabel  1906
    +href="glossaries-user.html#dx1-43003" >4084
        numberline  1907, 1908
    +href="glossaries-user.html#x1-400002.2" >4085, 4086
        numbers  1909, 1910, 1911
    +href="glossaries-user.html#dx1-84005" >4087, 4088, 4089
        order  1912, 1913, 1914
    +href="glossaries-user.html#dx1-71002" >4090, 4091, 4092, 4093
            letter  1915, 1916, 1917, 1918, 1919
    +href="glossaries-user.html#dx1-7047" >4094, 4095, 4096, 4097, 4098, 4099
            word  1920, 1921, 1922
    +href="glossaries-user.html#dx1-16091" >4100, 4101
    +    postdot  4102, 4103, 4104, 4105, 4106, 4107
    +    postpunc  4108
    +    prefix  4109, 4110, 4111, 4112
    +    record  4113, 4114, 4115, 4116, 4117, 4118, 4119, 4120, 4121, 4122, 4123, 4124, 4125, 4126, 4127, 4128, 4129, 4130, 4131, 4132, 4133
    +        alsoindex  4134, 4135
    +        nameref  4136, 4137, 4138, 4139, 4140, 4141, 4142, 4143, 4144, 4145, 4146
    +        only  4147, 4148, 4149, 4150, 4151, 4152
        record  1923
    +href="glossaries-user.html#dx1-214045" >4153, 4154
    +    restoremakegloss  4155, 4156
        sanitizesort  1924, 1925, 1926
    +href="glossaries-user.html#dx1-5006" >4157, 4158, 4159
            false  1927, 1928, 1929, 1930, 1931, 1932
    +href="glossaries-user.html#dx1-6005" >4160, 4161, 4162, 4163, 4164, 4165
            true  1933, 1934, 1935, 1936, 1937, 1938, 1939, 1940, 1941
    +href="glossaries-user.html#dx1-6007" >4166, 4167, 4168, 4169, 4170, 4171, 4172, 4173, 4174
        savenumberlist  1942, 1943
    +href="glossaries-user.html#x1-450002.3" >4175, 4176, 4177, 4178, 4179
            false  1944
    +href="glossaries-user.html#dx1-45002" >4180
        savewrites  1945, 1946, 1947
    +href="glossaries-user.html#x1-310002.1" >4181, 4182, 4183
            false  1948
    +href="glossaries-user.html#dx1-31001" >4184
        section  1949, 1950
    +href="glossaries-user.html#x1-410002.2" >4185, 4186
        seeautonumberlist  1951, 1952, 1953, 1954
    +href="glossaries-user.html#x1-560002.3" >4187, 4188, 4189, 4190
        seenoindex  1955, 1956
    +href="glossaries-user.html#x1-620002.4" >4191, 4192
            ignore  1957
    +href="glossaries-user.html#dx1-62005" >4193
            warn  1958
    +href="glossaries-user.html#dx1-62004" >4194
        shortcuts  1959, 1960
    -    smallcaps  1961, 1962, 1963, 1964, 1965, 1966
    -    smaller  1967, 1968, 1969, 1970, 1971
    +href="glossaries-user.html#x1-940002.7" >4195, 4196
    +    smallcaps (deprecated)  4197, 4198, 4199, 4200, 4201, 4202
    +    smaller (deprecated)  4203, 4204, 4205, 4206, 4207
        sort  1972
    +href="glossaries-user.html#dx1-71001" >4208, 4209
            def  1973, 1974, 1975, 1976, 1977, 1978, 1979, 1980, 1981, 1982, 1983
    +href="glossaries-user.html#dx1-6010" >4210, 4211, 4212, 4213, 4214, 4215, 4216, 4217, 4218, 4219, 4220
            none  1984, 1985, 1986, 1987
    +href="glossaries-user.html#dx1-5008" >4221, 4222, 4223, 4224, 4225, 4226
            standard  1988, 1989, 1990
    +href="glossaries-user.html#dx1-73005" >4227, 4228, 4229
            use  1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001
    +href="glossaries-user.html#dx1-6009" >4230, 4231, 4232, 4233, 4234, 4235, 4236, 4237, 4238, 4239, 4240
        style  2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
    +href="glossaries-user.html#x1-490002.3" >4241, 4242, 4243, 4244, 4245, 4246, 4247, 4248
            index  2010
    +href="glossaries-user.html#dx1-49003" >4249
            list  2011
    +href="glossaries-user.html#dx1-49001" >4250
    +    stylemods  4251, 4252, 4253, 4254, 4255, 4256, 4257, 4258, 4259, 4260, 4261, 4262
        subentrycounter  2012, 2013, 2014, 2015, 2016, 2017
    +href="glossaries-user.html#x1-480002.3" >4263, 4264, 4265, 4266, 4267, 4268
            false  2018
    +href="glossaries-user.html#dx1-48001" >4269
        symbols  2019, 2020, 2021
    +href="glossaries-user.html#dx1-4015" >4270, 4271, 4272, 4273, 4274, 4275, 4276, 4277
        toc  2022, 2023, 2024, 2025, 2026, 2027
    +href="glossaries-user.html#dx1-7051" >4278, 4279, 4280, 4281, 4282, 4283, 4284
    +        false  4285
    +        true  4286, 4287
        translate  2028, 2029, 2030, 2031
    +href="glossaries-user.html#x1-320002.1" >4288, 4289, 4290, 4291
    + +         babel  2032, 2033, 2034, 2035, 2036, 2037
    - - +href="glossaries-user.html#dx1-14012" >4292, 4293, 4294, 4295, 4296, 4297, 4298, 4299
            false  2038, 2039, 2040, 2041
    +href="glossaries-user.html#dx1-14011" >4300, 4301, 4302, 4303
            true  2042, 2043, 2044, 2045
    -    ucfirst  2046
    +href="glossaries-user.html#dx1-32001" >4304, 4305, 4306, 4307
        ucmark  2047, 2048
    +href="glossaries-user.html#dx1-41007" >4308, 4309, 4310
            false  2049
    +href="glossaries-user.html#dx1-42001" >4311
            true  2050
    +href="glossaries-user.html#dx1-42003" >4312
    +    undefaction  4313
    +    writeglslabels  4314, 4315
        xindy  2051, 2052, 2053, 2054, 2055, 2056, 2057, 2058, 2059, 2060, 2061, 2062, 2063, 2064
    +href="glossaries-user.html#dx1-8021" >4316, 4317, 4318, 4319, 4320, 4321, 4322, 4323, 4324, 4325, 4326, 4327, 4328, 4329, 4330, 4331, 4332
        xindygloss  2065, 2066
    +href="glossaries-user.html#x1-770002.5" >4333, 4334
        xindynoglsnumbers  2067, 2068
    +href="glossaries-user.html#x1-780002.5" >4335, 4336
    page (counter)  2069, 2070
    +href="glossaries-user.html#dx1-144039" >4337, 4338
    page type precedence  2071
    +href="glossaries-user.html#dx1-131005" >4339
    +\pagelistname  4340
    pdflatex  2072, 2073
    +href="glossaries-user.html#dx1-27" >4341, 4342
    \PGLS  2074
    +href="glossaries-user.html#dx1-171028" >4343
    \Pgls  2075
    +href="glossaries-user.html#dx1-171024" >4344
    \pgls  2076
    +href="glossaries-user.html#dx1-171021" >4345, 4346
    \PGLSpl  2077
    +href="glossaries-user.html#dx1-171037" >4347
    \Pglspl  2078
    +href="glossaries-user.html#dx1-171033" >4348
    \pglspl  2079
    -pod2man  2080
    +href="glossaries-user.html#dx1-171030" >4349
    +\pi  4350
    polyglossia package  2081, 2082, 2083, 2084, 2085, 2086, 2087
    +href="glossaries-user.html#dx1-14002" >4351, 4352, 4353, 4354, 4355, 4356, 4357
    +\primary  4358
    \printacronyms  2088
    +href="glossaries-user.html#dx1-90001" >4359, 4360, 4361
    \printglossaries  2089
    +href="glossaries-user.html#dx1-123002" >4362, 4363, 4364, 4365, 4366, 4367, 4368, 4369, 4370
    \printglossary  2090
    +href="glossaries-user.html#dx1-7002" >4371, 4372, 4373, 4374, 4375, 4376, 4377, 4378, 4379, 4380, 4381, 4382, 4383, 4384, 4385, 4386
    \printglossary options
        entrycounter  2091
    -    nogroupskip  2092
    -    nonumberlist  2093
    -    nopostdot  2094
    -    numberedsection  2095
    -    style  2096, 2097, 2098, 2099, 2100
    -    subentrycounter  2101
    -    title  2102, 2103, 2104, 2105, 2106
    -    toctitle  2107
    -    type  2108, 2109
    +class="cmtt-10">entrycounter  4387
    +    label  4388
    +    nogroupskip  4389
    +    nonumberlist  4390
    +    nopostdot  4391
    +    numberedsection  4392
    +    prefix  4393
    +    style  4394, 4395, 4396, 4397, 4398
    +    subentrycounter  4399
    +    target  4400, 4401
    +    targetnameprefix  4402
    +    title  4403, 4404, 4405, 4406, 4407
    +    toctitle  4408
    +    type  4409, 4410
    \printindex  2110
    +href="glossaries-user.html#dx1-87004" >4411
    \printnoidxglossaries  2111
    +href="glossaries-user.html#dx1-141002" >4412, 4413
    \printnoidxglossary  2112
    +href="glossaries-user.html#dx1-6002" >4414, 4415, 4416, 4417, 4418, 4419, 4420, 4421, 4422, 4423, 4424, 4425, 4426
    \printnoidxglossary options
    + +     sort  2113, 2114, 2115, 2116
    +class="cmtt-10">sort  4427, 4428, 4429, 4430, 4431
    \printnumbers  2117
    +href="glossaries-user.html#dx1-86001" >4432
    \printsymbols  2118
    +href="glossaries-user.html#dx1-85001" >4433
    +\printunsrtacronyms  4434
    +\printunsrtglossaries  4435, 4436, 4437, 4438, 4439, 4440, 4441, 4442, 4443, 4444, 4445, 4446, 4447, 4448, 4449, 4450, 4451
    +\printunsrtglossary  4452, 4453, 4454, 4455, 4456, 4457, 4458, 4459, 4460, 4461, 4462, 4463, 4464, 4465
    +\providecommand  4466, 4467
    \provideglossaryentry  2119
    -

    4468, 4469
    +\provideignoredglossary  4470
    +

    R relsize package  2120, 2121
    - - -

    4471, 4472, 4473
    +\Roman  4474
    +

    S +\S  4475
    sanitize  2122, 2123, 2124, 2125, 2126
    +href="glossaries-user.html#dx1-3061" >4476, 4477, 4478, 4479, 4480
    scrwfile package  2127
    +href="glossaries-user.html#dx1-31007" >4481
    +\section*  4482, 4483
    +\seealsoname  4484, 4485
    +\seename  4486, 4487, 4488
    +\setabbreviationstyle  4489, 4490, 4491, 4492, 4493, 4494, 4495, 4496, 4497, 4498, 4499, 4500, 4501, 4502, 4503, 4504, 4505, 4506, 4507, 4508, 4509, 4510, 4511, 4512, 4513, 4514, 4515, 4516, 4517, 4518, 4519, 4520, 4521
    +\setabbreviationstyle  4522
    \SetAcronymLists  2128
    +href="glossaries-user.html#dx1-93005" >4523
    \setacronymstyle  2129
    +href="glossaries-user.html#dx1-95001" >4524, 4525, 4526, 4527, 4528, 4529, 4530, 4531, 4532, 4533
    +\setentrycounter  4534, 4535
    \setglossarypreamble  2130
    +href="glossaries-user.html#dx1-47008" >4536, 4537
    \setglossarysection  2131
    +href="glossaries-user.html#dx1-41002" >4538, 4539
    \setglossarystyle  2132
    +href="glossaries-user.html#dx1-54003" >4540, 4541, 4542, 4543, 4544, 4545, 4546
    \setStyleFile  2133
    +href="glossaries-user.html#dx1-19014" >4547, 4548, 4549
    \setupglossaries  2134
    +href="glossaries-user.html#dx1-108001" >4550
    +\Sigma  4551
    +siunitx package  4552, 4553
    +small caps  4554, 4555, 4556, 4557, 4558, 4559, 4560, 4561, 4562, 4563
    +\space  4564
    stix package  2135
    +href="glossaries-user.html#dx1-144038" >4565, 4566
    \subglossentry  2136
    +href="glossaries-user.html#dx1-166062" >4567
    supertabular package  2137, 2138, 2139
    -

    4568, 4569, 4570
    +\symbolname  4571
    +

    T tabularx package  2140, 2141, 2142, 2143
    +href="glossaries-user.html#dx1-133005" >4572, 4573, 4574, 4575
    + + +tagpdf package  4576, 4577, 4578
    +\texorpdfstring  4579, 4580
    +\textbf  4581, 4582
    textcase package  2144, 2145, 2146
    +href="glossaries-user.html#dx1-9" >4583, 4584, 4585
    +\textrm  4586
    +\textsc  4587, 4588, 4589, 4590, 4591, 4592, 4593
    +\textsmaller  4594, 4595, 4596, 4597
    +\textulc  4598
    +\textup  4599
    +\the  4600, 4601
    theglossary (environment)  2147
    +href="glossaries-user.html#dx1-166002" >4602
    +\theHequation  4603
    +\thepage  4604, 4605
    +\toprule  4606
    tracklang package  2148, 2149, 2150
    +href="glossaries-user.html#dx1-5" >4607, 4608, 4609
    translator package  2151, 2152, 2153, 2154, 2155, 2156, 2157, 2158, 2159, 2160, 2161, 2162, 2163, 2164, 2165, 2166, 2167, 2168, 2169, 2170, 2171, 2172, 2173, 2174, 2175
    -

    4610, 4611, 4612, 4613, 4614, 4615, 4616, 4617, 4618, 4619, 4620, 4621, 4622, 4623, 4624, 4625, 4626, 4627, 4628, 4629, 4630, 4631, 4632, 4633, 4634
    +

    U +\usepackage  4635
    +

    W +\write18  4636, 4637
    +\writeist  4638
    +

    X xfor package  2176
    +href="glossaries-user.html#dx1-10" >4639
    +\xGlsXtrSetField  4640
    xindy  2177, 2178, 2179, 2180, 2181, 2182, 2183, 2184, 2185, 2186, 2187, 2188, 2189, 2190, 2191, 2192, 2193, 2194, 2195, 2196, 2197, 2198, 2199, 2200, 2201, 2202, 2203, 2204, 2205, 2206, 2207, 2208, 2209, 2210, 2211, 2212, 2213, 2214, 2215, 2216, 2217, 2218, 2219, 2220, 2221, 2222, 2223, 2224, 2225, 2226, 2227, 2228, 2229, 2230, 2231, 2232, 2233, 2234, 2235, 2236, 2237, 2238, 2239, 2240, 2241, 2242, 2243, 2244, 2245, 2246, 2247, 2248, 2249, 2250, 2251, 2252, 2253, 2254, 2255, 2256, 2257, 2258, 2259, 2260, 2261, 2262, 2263, 2264, 2265, 2266, 2267, 2268, 2269, 2270, 2271, 2272, 2273, 2274, 2275, 2276, 2277, 2278, 2279, 2280, 2281, 2282, 2283, 2284, 2285, 2286, 2287, 2288, 2289, 2290, 2291, 2292, 2293, 2294, 2295, 2296, 2297, 2298, 2299, 2300, 2301, 2302, 2303, 2304, 2305, 2306, 2307, 2308, 2309, 2310, 2311, 2312, 2313, 2314, 2315, 2316, 2317, 2318, 2319, 2320, 2321, 2322, 2323, 2324, 2325, 2326, 2327, 2328, 2329, 2330, 2331, 2332
    +href="glossaries-user.html#dx1-3005" >4641, 4642, 4643, 4644, 4645, 4646, 4647, 4648, 4649, 4650, 4651, 4652, 4653, 4654, 4655, 4656, 4657, 4658, 4659, 4660, 4661, 4662, 4663, 4664, 4665, 4666, 4667, 4668, 4669, 4670, 4671, 4672, 4673, 4674, 4675, 4676, 4677, 4678, 4679, 4680, 4681, 4682, 4683, 4684, 4685, 4686, 4687, 4688, 4689, 4690, 4691, 4692, 4693, 4694, 4695, 4696, 4697, 4698, 4699, 4700, 4701, 4702, 4703, 4704, 4705, 4706, 4707, 4708, 4709, 4710, 4711, 4712, 4713, 4714, 4715, 4716, 4717, 4718, 4719, 4720, 4721, 4722, 4723, 4724, 4725, 4726, 4727, 4728, 4729, 4730, 4731, 4732, 4733, 4734, 4735, 4736, 4737, 4738, 4739, 4740, 4741, 4742, 4743, 4744, 4745, 4746, 4747, 4748, 4749, 4750, 4751, 4752, 4753, 4754, 4755, 4756, 4757, 4758, 4759, 4760, 4761, 4762, 4763, 4764, 4765, 4766, 4767, 4768, 4769, 4770, 4771, 4772, 4773, 4774, 4775, 4776, 4777, 4778, 4779, 4780, 4781, 4782, 4783, 4784, 4785, 4786, 4787, 4788, 4789, 4790, 4791, 4792, 4793, 4794, 4795, 4796, 4797, 4798, 4799, 4800, 4801, 4802, 4803, 4804, 4805, 4806, 4807, 4808, 4809, 4810, 4811, 4812, 4813, 4814, 4815, 4816, 4817, 4818, 4819, 4820, 4821, 4822, 4823, 4824, 4825
        -C  2333, 2334, 2335, 2336, 2337
    +href="glossaries-user.html#dx1-8033" >4826, 4827, 4828, 4829, 4830
        -I  2338, 2339
    +href="glossaries-user.html#dx1-19007" >4831, 4832
        -L  2340, 2341, 2342, 2343
    +href="glossaries-user.html#dx1-8032" >4833, 4834, 4835, 4836
        -M  2344
    +href="glossaries-user.html#dx1-16090" >4837
    +xindy attributes  4838, 4839, 4840, 4841, 4842
    +    :locref  4843
    xkeyval package  2345, 2346, 2347
    +href="glossaries-user.html#dx1-8" >4844, 4845, 4846
    +\xspace  4847
    xspace package  2348, 2349, 2350, 2351, 2352, 2353, 2354
    +href="glossaries-user.html#dx1-152014" >4848, 4849, 4850, 4851, 4852, 4853, 4854

    - - -

    1.1That is, if the term has been referenced using any of the commands described in §That is, if the entry has been referenced using any of the commands described in §6 Links to Glossary -Entries Links to Glossary Entries and §§7 Adding an Entry to the Glossary Without Generating Text Adding +an Entry to the Glossary Without Generating Text or via \glssee (or the seesee key) or -commands such as key) or commands such as \acrshort or +\glsxtrshort.

    -

    1.2Except for Klingon, which is supported by xindy, but not by the CLDR.

    -

    1.3Note that although I’ve written latex in this section, it’s better to use pdflatex, where possible, for -the reasons given earlier.

    -

    You can just use the base glossaries package for the first case, but it’s less convenient. You’d have to manually insert the +entry target before the sectioning command and use \glsentryname{label} or \Glsentryname{label} to display the entry +name.

    1.4\glossentrysymbol is defined by the base glossaries package but is redefined by glossaries-extra.

    +

    1.5deprecated, use babel instead

    -

    1.5

    1.6Added to version makeglossaries 2.18.

    -

    1.6

    1.7As from v3.01 \gls is no longer fragile and doesn’t need protecting.

    -

    1.7

    1.8The batch file makeglossaries.bat has been removed since the TEX distributions for Windows +class="cmr-8"> distributions for Windows provide provide makeglossaries.exe.

    -

    2.1bug fix in v4.16 has corrected the code to ensure this.

    -

    These figures don’t include standard files and registers provided by the kernel or hyperref, such as aux and +out.

    2.2unless memoir is loaded, which case it uses \markboth

    -

    +

    2.3Actually it uses \mfirstucMakeUppercase which is set to textcase’s \MakeTextUppercase by the glossaries +class="cmss-8">glossaries package. This package. This makes it consistent with makes it consistent with \makefirstuc. (The textcase package is automatically loaded by - package is automatically loaded by glossaries.)

    -

    2.4bug fix in v4.16 has corrected the code to ensure this.

    +

    2.5Actually it sets \acronymtype to \glsdefaulttype if the acronym package option is not used, but - package option is not used, but \glsdefaulttype usually has the value usually +has the value main unless the nomain option has been used.

    -

    4.1This is because \acronymtype is set to \glsdefaulttype if the acronym package option is not -used.

    -

    package option is not used.

    +

    6.1See also “Displaying the glossary” in the documented code, glossaries-code.pdf.

    -

    6.2I’ve used \MakeUppercase in all the examples for clarity, but it will actually use \mfirstucMakeUppercase.

    -

    6.3\glsdisplayfirst and \glsdisplay are now deprecated. Backwards compatibility should be preserved + id="dx1-135004"> are now deprecated. Backwards compatibility should be preserved but you may need to but you may need to use the use the compatible-3.07 option

    -

    8.1makeindex will always assign a location number, even if it’s not needed, so it needs to be -discarded.

    will always assign a location number, even if it’s not needed, so it needs to be discarded.

    +

    8.2If you redefine \glsseeformat, keep the default value of the optional argument as \seename as -both see as both see and \glssee \glssee +explicitly write [\seename] in the output file if no optional argument is -given.

    -

    in the output file if no optional argument is given.

    +

    8.3In versions before 3.0, \glsentryname was used, but this could cause problems when the name name key was sanitized.

    .

    9.1versions before 3.0 used \glsentryname as the default, but this could cause problems when name had -been name had been +sanitized.

    .

    10.1you can’t use the longheaderborder style for this example as you can’t use the longtable environment in + id="dx1-141082"> environment in two column two column mode.

    mode.

    11.1see \glsSetCompositor described in §§3 Setting Up

    -

    11.2see \glsSetAlphaCompositor described in §§3 Setting Up

    -

    11.3With glossaries-extra seealso is appended to the end of the list.

    -

    13.1as from version 1.18

    as from version 1.18

    13.2See David Carlisle’sexplanation in http://tex.stackexchange.com/questions/86565/drawbacks-of-xspace

    -

    See David Carlisle’s explanation in Drawbacks of xspace

    +

    15.1These lengths will not be available if you use both the nolong and nosuper package options or if you -use the package options or if you use the nostyles package option unless you explicitly load the relevant package.

    -

    package +option unless you explicitly load the relevant package.

    +

    15.2This style was supplied by Axel Menzel.

    -

    15.3e.g. with the flowfram package.

    -

    17.1Single letter words, such as “a” and “I” should typically not appear at the end of a line, hence the +class="cmr-8">Single letter words, such as “a” and “I” should typically not appear at the end of a line, hence the non-breakable space after non-breakable space after “a” in the prefix “a” in the prefix field.

    -

    17.2The earlier caveats about initial non-Latin characters apply.

    +class="cmr-8">The earlier caveats about initial non-Latin characters apply.

    +

    19.1makeindex assumes that the location is a page number

    +

    19.2If you use babel with a language that makes the colon character : active you will need to change the prefix.

    +

    19.3Requires at least bib2gls v2.0.

    +

    19.4You can either uncompress the PDF file and view it in a text editor or you can use a tool such as the PDFDebugger +provided with PDFBox.

    - + diff --git a/macros/latex/contrib/glossaries/glossaries-user.pdf b/macros/latex/contrib/glossaries/glossaries-user.pdf index 76f4e9569b..91dcdb20a8 100644 Binary files a/macros/latex/contrib/glossaries/glossaries-user.pdf and b/macros/latex/contrib/glossaries/glossaries-user.pdf differ diff --git a/macros/latex/contrib/glossaries/glossaries-user.tex b/macros/latex/contrib/glossaries/glossaries-user.tex index 41dc516ee7..a8465c911f 100644 --- a/macros/latex/contrib/glossaries/glossaries-user.tex +++ b/macros/latex/contrib/glossaries/glossaries-user.tex @@ -1,12 +1,13 @@ -\documentclass[report,inlinetitle,widecs]{nlctdoc} +\documentclass[report,inlinetitle,noprint,wbprompt,x11names]{nlctdoc} -\usepackage[inner=0.5in,includemp]{geometry} +\usepackage[inner=0.25in,outer=0.5in,includemp]{geometry} \usepackage{array} \usepackage{alltt} \usepackage{pifont} \usepackage{textcomp} \usepackage{amssymb} +\usepackage{accsupp} \ifpdf \usepackage{lmodern} \usepackage{mathpazo} @@ -17,10 +18,12 @@ \newcommand{\grimace}{{\fontencoding {U}\fontfamily{futs}\selectfont \char77}} \providecommand{\XeLaTeX}{XeLaTeX} \providecommand{\XeTeX}{XeTeX} + \providecommand{\LuaLaTeX}{LuaLaTeX} \fi \usepackage[colorlinks, bookmarks, linkcolor=blue, + urlcolor=Magenta4, hyperindex=false, pdfauthor={Nicola L.C. Talbot}, pdftitle={User Manual for glossaries.sty}, @@ -58,31 +61,157 @@ \end{ttfamily} } -\ifpdf -\else +\renewcommand{\nlctdocmainencap}{} + +\makeglossaries + +\renewcommand{\importantfmt}{} +\renewcommand{\importantsymbolfont}[1]{\textcolor{red}{\bfseries\Huge#1}} + +\newcommand*{\xtrfont}[1]{\textcolor{teal}{#1}} + +\newcommand*{\codecomment}[1]{\emph{\rmfamily\color{gray}#1}} + +\makeatletter +\@nlctdoc@if@usingtexht +{ % Need an extra line break in the html version % (Don't have time to fiddle with cfg files!) \renewcommand*{\glossentry}[2]{% \item[\glsentryitem{#1}\glstarget{#1}{\glossentryname{#1}}]\mbox{}\newline \glossentrydesc{#1}\glspostdescription\space #2\newline}% -\fi + \newcommand*{\htmldoc}[2]{\href{#2.html}{\qt{#1}}} + \newcommand{\glsxtrnote}{\HCode{
    }\gls{glossaries-extra}\HCode{}} + \newcommand{\bibglsnote}{\HCode{}\gls{bib2gls}\HCode{}} + \newenvironment{xtr}% + {\par + \HCode{
    }}% + {\HCode{
    }\par\noindent} + \newenvironment{bib2gls}% + {\par + \HCode{
    }}% + {\HCode{
    }\par\noindent} + + \newcommand{\commandpromptnote}{} + \newcommand{\maincommandpromptnote}{} + \newenvironment{important*}{\begin{important}\importantpar}{\end{important}} + \renewcommand{\S}{\HCode{&\#167;}} + \newcommand{\strong}[1]{\HCode{}#1\HCode{}} + \newcommand*{\linkanchor}[1]{\HCode{&\#128279;}} +} +{ + \externaldocument{glossaries-code} + \renewcommand{\idxmarker}{\textsuperscript{\xtrfont{\textdagger}}} + \newcommand*{\htmldoc}[2]{\qt{#1}} + \newcommand{\glsxtrnote}{% + \leavevmode\marginpar{\glslink{glossaries-extra}{\xtrfont{\footnotesize\styfmt{glossaries-extra.sty}}}}% + } + \newcommand{\bibglsnote}{% + \leavevmode\marginpar{{\footnotesize\glslink{bib2gls}{\xtrfont{\appfmt{bib2gls}}}}}% + } + \newenvironment{xtr}[1][\glsxtrnote]% + {% + \def\xtrmarginnote{#1}% + \setlength{\fboxrule}{4pt}% + \setlength\defwidth{\linewidth}% + \addtolength\defwidth{-2\fboxsep}% + \addtolength\defwidth{-2\fboxrule}% + \begin{lrbox}{\defsbox}% + \begin{minipage}[t]{\defwidth}% + \setlength\parindent{1em}% + \noindent\ignorespaces + }% + {% + \end{minipage}% + \end{lrbox}% + \par\vskip10pt\noindent + \xtrmarginnote + \fcolorbox{teal}{white}{\usebox{\defsbox}}\par\vskip10pt + \noindent\ignorespacesafterend + } + \newenvironment{bib2gls}{\begin{xtr}[\bibglsnote]}{\end{xtr}} + \newcommand{\commandpromptnote}{The \texttt{\bfseries\$} symbol in the instructions + indicates the command prompt. It should be omitted when copying the text. } + \newcommand{\maincommandpromptnote}{The command prompt is indicated with + \texttt{\bfseries\$} in this documentation. Don't type that character when + copying examples. } + + \def\verbatim@font{\MacroFont} + + \newenvironment{important*}% + {% + \renewcommand{\importantsymbolfont}[1]{\textcolor{red}{\bfseries\huge##1}}% + \begin{important}\importantpar[-2][-1ex]% + }% + {\end{important}} + \newcommand{\strong}{\textbf} + \newcommand{\linkanchor}[1]{} +} +\renewcommand*{\@isty}[1]{\index{#1 package=\styfmt{#1} + package|hyperpage}} +\renewcommand*{\s@isty}[1]{\index{#1 package=\doidxmarker\styfmt{#1} + package|hyperpage}} +\renewcommand*{\@icls}[1]{\index{#1 class=\clsfmt{#1} + class|hyperpage}} +\renewcommand*{\s@icls}[1]{\index{#1 class=\doidxmarker\clsfmt{#1} + class|hyperpage}} -\makeglossaries +\renewrobustcmd*{\iterm}[1]{\index{#1|hyperpage}} +\makeatother \renewcommand*{\main}[1]{\hyperpage{#1}} \newcommand*{\htextbf}[1]{\textbf{\hyperpage{#1}}} \newcommand*{\itermdef}[1]{\index{#1|htextbf}} \newcommand{\itempar}[1]{\item[{#1}]\mbox{}\par} +\newcommand{\Index}[1]{#1\index{#1|hyperpage}} + +\newcommand{\xtrpkgoptdef}[1]{\hypertarget{pkgopt:#1}{\pkgopt*{#1}}} \newcommand{\pkgoptdef}[1]{\hypertarget{pkgopt:#1}{\pkgopt{#1}}} +\newcommand{\deppkgoptdef}[1]{\hypertarget{pkgopt:#1}{\deprecatedpkgopt{#1}}} + +\newcommand{\pkgoptsec}[2][]{% + \pdfbookmark[2]{#2}{pkgopt.#2} + \ifstrempty{#1}% + {\subsection*{\protect\pkgoptdef{#2}}}% + {\subsection*{\protect\pkgoptdef{#2}\pkgoptfmt{=\protect\marg{#1}}}}% +} + +\newcommand{\deppkgoptsec}[2][]{% + \pdfbookmark[2]{#2}{pkgopt.#2} + \ifstrempty{#1}% + {\subsection*{\protect\deppkgoptdef{#2}}}% + {\subsection*{\protect\deppkgoptdef{#2}\pkgoptfmt{=\marg{#1}}}}% +} + +\newcommand{\xtrpkgoptsec}[2][]{% + \pdfbookmark[2]{#2 (glossaries-extra.sty)}{pkgopt.#2} + \ifstrempty{#1}% + {\subsection*{\protect\xtrfont{\protect\xtrpkgoptdef{#2} (glossaries-extra.sty)}}}% + {\subsection*{\protect\xtrfont{\protect\xtrpkgoptdef{#2}\pkgoptfmt{=\protect\marg{#1}} + (glossaries-extra.sty)}}}% +} \newcommand{\glslike}{\hyperref[sec:gls-like]{\cs{gls}-like}} \newcommand{\glstextlike}{\hyperref[sec:glstext-like]{\cs{glstext}-like}} +\newcommand{\gallery}[2]{\href{https://www.dickimaw-books.com/gallery/#1}{#2}} +\newcommand{\galleryurl}[1]{\gallery{#1}{\nolinkurl{https://www.dickimaw-books.com/gallery/#1}}} +\newcommand{\gallerytopic}[1]{\galleryurl{\##1}} + +\newcommand*{\bibglsgallery}[2][\gallerytitle]{% + \def\gallerytitle{#2}% + \gallery{index.php?label=bib2gls-#2}{\appfmt{bib2gls} gallery: \gallerytitle}} + +\newcommand*{\bibglsbegin}{% + \href{http://mirrors.ctan.org/support/bib2gls/bib2gls-begin.pdf}{\styfmt{glossaries-extra} and \appfmt{bib2gls}: An Introductory Guide}} + \IndexPrologue{\chapter*{\indexname} \addcontentsline{toc}{chapter}{\indexname}% - \markboth{\indexname}{\indexname}} + \markboth{\indexname}{\indexname} + \par\idxmarker Requires \gls{glossaries-extra}. +} \longnewglossaryentry{indexingapp}% { @@ -110,7 +239,7 @@ interface. That is, an application that doesn't have any windows, buttons or menus and can be run in \href{http://www.dickimaw-books.com/latex/novices/html/terminal.html}{a command - prompt or terminal}. + prompt or terminal}. \maincommandpromptnote } \longnewglossaryentry{xindy}{% @@ -120,27 +249,44 @@ }% {% A flexible \gls{indexingapp} with multilingual - support written in Perl. + support written in Perl. See \opt3. } \newglossaryentry{makeindex}{% name={\appfmt{makeindex}\index{makeindex=\appfmt{makeindex}|htextbf}},% sort={makeindex},% text={\appfmt{makeindex}\iapp{makeindex}},% -description={An \gls{indexingapp}.} +description={An \gls{indexingapp}. See \opt2.} } \newglossaryentry{bib2gls}{% -name={\appfmt{bib2gls}\index{bib2gls=\appfmt{bib2gls}|htextbf}},% +name={\appfmt{bib2gls}\index{bib2gls=\doidxmarker\appfmt{bib2gls}|htextbf}},% sort={bib2gls},% -text={\appfmt{bib2gls}\iapp{bib2gls}},% +text={\appfmt{bib2gls}\iapp*{bib2gls}},% description={An \gls{indexingapp} that combines two functions in -one: (1) fetches entry definition from a \texttt{.bib} file -based on information provided in the \texttt{.aux} file (similar +one: (1) fetches entry definition from a \filetype{bib} file +based on information provided in the \filetype{aux} file (similar to \appfmt{bibtex}); (2) hierarchically sorts and collates location -lists (similar to \appfmt{makeindex} and \appfmt{xindy}). -This application is designed for use with \styfmt{glossaries-extra} -and can't be used with just the base \styfmt{glossaries} package.} +lists (similar to \gls{makeindex} and \gls{xindy}). +This application is designed for use with \gls{glossaries-extra} +and can't be used with just the base \styfmt{glossaries} package. +See \opt4.} +} + +\newglossaryentry{convertgls2bib}{% +name={\appfmt{convertgls2bib}\index{convertgls2bib=\doidxmarker\appfmt{convertgls2bib}|htextbf}},% +sort={convertgls2bib},% +text={\appfmt{convertgls2bib}\iapp*{convertgls2bib}},% +description={An application provided with \gls{bib2gls} that +converts \filetype{tex} files containing entry definitions to +\filetype{bib} files suitable for use with \gls{bib2gls}. +This application is designed for files that just contain entry +definitions, but it can work on a complete document file. +However, there will be a lot of \qt{undefined command} warnings as +\gls{convertgls2bib} only has a limited set of known commands. You +can limit it so that it only parses the preamble with the +\texttt{-{}-preamble-only} switch (requires at least \gls{bib2gls} +v2.0).} } \newglossaryentry{makeglossaries}{% @@ -162,7 +308,7 @@ text={\appfmt{makeglossaries-lite}\iapp{makeglossaries-lite}},% description={A custom designed Lua script interface to \gls{xindy} and \gls{makeindex} provided with the \styfmt{glossaries} package. This is a cut-down alternative to the Perl -\appfmt{makeglossaries} script. If you have Perl installed, use the +\gls{makeglossaries} script. If you have Perl installed, use the Perl script instead. This script is actually distributed with the file name \texttt{makeglossaries-lite.lua}, but \TeX~Live (on Unix-like systems) creates a symbolic link @@ -215,6 +361,26 @@ description={The text produced by commands such as \ics{gls}. It may or may not be a hyperlink to the glossary.} } +\newglossaryentry{smallcaps}{% + name={Small caps\itermdef{small caps}}, + sort={small caps}, + text={small caps\iterm{small caps}}, + description={Small capitals. The \LaTeX\ kernel provides + \ics{textsc}\marg{text} to produce small capitals. This uses a + font where lowercase letters have a small capital design. + Uppercase letters have the standard height and there's no + noticeable difference with uppercase characters in corresponding non-small caps fonts. + This means that for a small caps appearance, you need to use lowercase letters in the + \meta{text} argument. The \isty{relsize} package provides + \ics{textsmaller}\marg{text} which simulates small caps by reducing the size + of the font, so in this case the contents of \meta{text} should be + uppercase (otherwise the effect is simply smaller lowercase + letters). Some fonts don't support small caps combined with bold or slanted + properties. In this case, there will be a font substitution + warning and one of the properties (such as small caps or slanted) will be + dropped.} +} + \let\glsd\glsuseri \let\glsation\glsuserii @@ -288,7 +454,7 @@ user2={sanitization\protect\iterm{sanitize}}% sort={extended Latin character}, description={A character that's created by combining \glspl{latinchar} to form ligatures (e.g.\ \ae) or by applying diacritical marks - to a~\gls*{latinchar} or characters (e.g.\ \'a or \o). + to a~\gls*{latinchar} or characters (e.g.\ \'a). See also \gls{nonlatinchar}.} } @@ -345,9 +511,6 @@ user2={sanitization\protect\iterm{sanitize}}% \styfmt{glossaries-extra} package installed.} } -\ifpdf -\externaldocument{glossaries-code} -\fi \doxitem{Option}{option}{package options} \doxitem{GlsKey}{key}{glossary keys} @@ -372,17 +535,18 @@ user2={sanitization\protect\iterm{sanitize}}% \newcommand*{\fnsym}[1]{\textsuperscript{\fnsymmark{% \ifcase#1\or \textasteriskcentered \or \textdagger \or \textdaggerdbl \or \textsection - \or $\lozenge$ \or \textparagraph + \or $\lozenge$\or \textparagraph \or \#\or {\fontfamily{cmr}\selectfont\textreferencemark}% \or \@nlctdoc@if@usingtexht{\HCode{&\#x2051;}}{\shortstack{*\\[-1.5ex]*}}% - \or $\star$ + \or $\star$% \or \ding{94}% \else \number#1 \fi }}}% -\newcommand*{\optionlabel}[1]{% - \@glstarget{option#1}{Option~#1}} +\newrobustcmd*{\optionlabel}[1]{\@glstarget{option#1}{Option~#1}} + +\newcommand*{\plabel}[2][]{\linkanchor{#2}\protected@edef\@currentlabelname{#1}\label{#2}} \makeatother \newcounter{option} @@ -390,7 +554,7 @@ user2={sanitization\protect\iterm{sanitize}}% \def\opttitle{\appfmt{#2}}% \refstepcounter{option}% \pdfbookmark[2]{Option~\theoption\space (#2)}{option\theoption}% - \subsection*{\protect\optionlabel{\theoption} (#1)}% + \subsection*{\linkanchor{option\theoption}\optionlabel{\theoption} (#1)}% } \newcommand*{\opt}[1]{\hyperlink{option#1}{Option~#1}} @@ -398,7 +562,9 @@ user2={sanitization\protect\iterm{sanitize}}% or~\hyperlink{option#2}{#2}} \newcommand*{\optsand}[2]{Options~\hyperlink{option#1}{#1} and~\hyperlink{option#2}{#2}} +\newcommand*{\optsto}[2]{Options~\hyperlink{option#1}{#1}--\hyperlink{option#2}{#2}} +\renewcommand*{\idxmarkedfont}{\xtrfont} \newcommand*{\ifirstuse}{\iterm{first use}} \newcommand*{\ifirstuseflag}{\iterm{first use>flag}} @@ -419,42 +585,97 @@ and~\hyperlink{option#2}{#2}} \newcommand*{\mkglsopt}[1]{\texttt{-#1}\index{makeglossaries=\appfmt{makeglossaries}>#1=\texttt{-#1}|hyperpage}} +\newcommand*{\bibglsopt}[1]{\xtrfont{\texttt{-{}#1}}\index{bib2gls=\doidxmarker\appfmt{bib2gls}>#1=\texttt{-{}#1}|hyperpage}} +\newcommand*{\bibglslongopt}[1]{\bibglsopt{-#1}} + +\renewcommand{\csoptfmt}{\texttt} + \newcommand*{\igloskey}[2][newglossaryentry]{\icsopt{#1}{#2}} \newcommand*{\gloskey}[2][newglossaryentry]{\csopt{#1}{#2}} -\newcommand*{\optfmt}[1]{\textsf{#1}} -\newcommand*{\field}[1]{\optfmt{#1}\index{internal fields:>#1=\protect\optfmt{#1}|main}} + +\newcommand*{\ixtrgloskey}[2][newglossaryentry]{\icsopt*{#1}{#2}} +\newcommand*{\xtrgloskey}[2][newglossaryentry]{\xtrfont{\csopt*{#1}{#2}}} + +\newcommand*{\printglosskey}[2][]{\icsopt{printglossary}{#2}% + \ifstrempty{#1}{\csoptfmt{#2}}{\csoptfmt{#2=#1}}% +} + +\newcommand*{\printnoidxglosskey}[2][]{\icsopt{printnoidxglossary}{#2}% + \ifstrempty{#1}{\csoptfmt{#2}}{\csoptfmt{#2=#1}}% +} + +\newcommand*{\xtrprintglosskey}[2][]{\icsopt*{printglossary}{#2}% + \xtrfont{\ifstrempty{#1}{\csoptfmt{#2}}{\csoptfmt{#2=#1}}}% +} + +\newcommand*{\iresourceopt}[1]{\icsopt+{GlsXtrLoadResources}{#1}} +\newcommand*{\resourceopt}[2][]{% + \xtrfont{\csoptfmt{#2}}\ifstrempty{#1}{}{\csoptfmt{\dequals#1}}% + \icsopt+{GlsXtrLoadResources}{#2}% +} + +\newcommand*{\atentry}[1]{\xtrfont{\texttt{@#1}}% + \index{bib2gls entry types=\doidxmarker\appfmt{bib2gls} entry types>#1=\texttt{@#1}|hyperpage}} + +\newcommand*{\xtrcs}[1]{\xtrfont{\cs{#1}}} + +\newcommand*{\field}[1]{\csoptfmt{#1}\index{internal fields:>#1=\protect\csoptfmt{#1}|main}} +\newcommand*{\xtrfield}[1]{\xtrfont{\csoptfmt{#1}}\index{internal fields:>#1=\doidxmarker\protect\csoptfmt{#1}|main}} \newcommand*{\glostyle}[1]{\textsf{#1}\index{glossary styles:>#1={\protect\ttfamily#1}|main}} +\newcommand*{\xtrglostyle}[1]{\xtrfont{\textsf{#1}}\index{glossary styles:>#1=\doidxmarker{\protect\ttfamily#1}|main}} + \newcommand*{\acrstyle}[1]{\textsf{#1}\index{acronym styles:>#1={\protect\ttfamily#1}|main}} +\newcommand*{\abbrstyle}[1]{\xtrfont{\textsf{#1}}\index{abbreviation styles:=\doidxmarker abbreviation styles:>#1={\protect\ttfamily#1}|main}} +\newcommand*{\cat}[1]{\xtrfont{\textsf{#1}}\index{categories=\doidxmarker categories>#1={\protect\ttfamily#1}|main}} + +\makeatletter +\@nlctdoc@if@usingtexht +{ + \newcommand*{\icatattrs}[1][]{\index{category attributes=\doidxmarker category attributes#1|main}} + \newcommand*{\ixindyattrs}[1][]{\index{xindy attributes=xindy attributes#1|main}} + \index{attributes|see{category attributes or xindy attributes}} +} +{ +\newcommand{\icatattrs}[1][]{\index{category attributes=\protect\doidxmarker\protect\glsdohypertarget{catattr}{category attributes}:#1|main}} + +\newcommand*{\ixindyattrs}[1][]{\index{xindy attributes=\protect\glsdohypertarget{xindyattr}{xindy attributes}#1|main}} + +\index{attributes|see{\protect\hyperlink{catattr}{category attributes} (\styfmt{glossaries-extra}) or \protect\hyperlink{xindyattr}{xindy attributes}\protect\hfill}} +} + +\makeatletter + +\newcommand*{\optfmt}[1]{\textsf{#1}} +\newcommand*{\attr}[1]{\xtrfont{\optfmt{#1}}\icatattrs[>#1=\optfmt{#1}]{}} +\newcommand*{\xindyattr}[1]{\texttt{#1}\ixindyattrs[>#1=\texttt{#1}]{}} + +\newrobustcmd{\mirrorsamplefile}[1]{% + \href{http://mirrors.ctan.org/macros/latex/contrib/glossaries/samples/#1}{\nolinkurl{#1}}% +} \newcounter{sample} \newcommand{\exitem}[2][sample]{% - \item[\texttt{#1#2.tex}]% - \refstepcounter{sample}\label{ex:#1#2}} - -\newenvironment{samplelist}% -{\begin{description}}% -{\end{description}} + \par + \pdfbookmark[2]{#1#2.tex}{exfile.#1#2}% + \refstepcounter{sample}% + \subsection*{\plabel[#1#2.tex]{ex:#1#2}\mirrorsamplefile{#1#2.tex}}% +} \newcommand*{\samplefile}[2][sample]{% \hyperref[ex:#1#2]{\texttt{#1#2.tex}}} -\ifpdf - \newcommand*{\htmldoc}[2]{\qt{#1}} -\else - \newcommand*{\htmldoc}[2]{\href{#2.html}{\qt{#1}}} -\fi \begin{document} \MakeShortVerb{"} \DeleteShortVerb{\|} - \title{User Manual for glossaries.sty v4.44} + \title{User Manual for glossaries.sty v4.45} \author{Nicola L.C. Talbot\\% - \url{http://www.dickimaw-books.com/}} + \href{http://www.dickimaw-books.com/contact}{\nolinkurl{dickimaw-books.com/contact}}} - \date{2019-12-06} + \date{2020-02-13} \maketitle \begin{abstract} @@ -462,16 +683,19 @@ The \styfmt{glossaries} package provides a means to define terms or abbreviations or symbols that can be referenced within your document. Sorted lists with collated \glslink{entrylocation}{locations} can be generated either using \TeX\ or using a supplementary \gls{indexingapp}. +Sample documents are provided with the \styfmt{glossaries} package. +These are listed in \sectionref{sec:samples}. +\end{abstract} +\begin{xtr} Additional features not provided here may be available through the extension package \gls{glossaries-extra} which, if required, needs to be installed separately. New features will be added to \gls*{glossaries-extra}. Versions of the \styfmt{glossaries} -package after v4.21 will mostly be just bug fixes. Note that -\gls{glossaries-extra} provides an extra indexing option -(\gls{bib2gls}) which isn't available with just the base -\sty{glossaries} package. -\end{abstract} +package after v4.21 will mostly be just bug fixes or minor +maintenance. Note that \gls{glossaries-extra} provides an extra indexing option +(\gls{bib2gls}) which isn't available with just the base \styfmt{glossaries} package. +\end{xtr} If you require multilingual support you must also separately install the relevant language module. Each language module is distributed @@ -545,35 +769,32 @@ package. \item[\url{glossaries-code.pdf}] Advanced users wishing to know more about the inner workings of all the packages provided in the \styfmt{glossaries} bundle should read -\qt{Documented Code for glossaries v4.44}. +\qt{Documented Code for glossaries v4.45}. \item[INSTALL] Installation instructions. \item[CHANGES] Change log. -\item[README] Package summary. +\item[README.md] Package summary. \end{description} Related resources: \begin{itemize} -\item \styfmt{glossaries-extra} and \gls{bib2gls}: An Introductory -Guide. (\href{http://mirrors.ctan.org/support/bib2gls/bib2gls-begin.pdf}{\texttt{bib2gls-begin.pdf}}). - +\item \bibglsbegin. \item \href{http://www.dickimaw-books.com/faqs/glossariesfaq.html}{\styfmt{glossaries} FAQ} -\item \href{http://www.dickimaw-books.com/gallery/#glossaries}{\styfmt{glossaries} -gallery} +\item \gallerytopic{glossaries}{\styfmt{glossaries} gallery} \item -\href{http://www.dickimaw-books.com/gallery/glossaries-styles/}{a -summary of all glossary styles provided by \styfmt{glossaries}} +\gallery{glossaries-styles/}{a summary of all glossary styles provided by \styfmt{glossaries} and +\gls*{glossaries-extra}} \item -\href{http://www.dickimaw-books.com/gallery/glossaries-performance.shtml}{\styfmt{glossaries} +\gallery{glossaries-performance.shtml}{\styfmt{glossaries} performance} (comparing document build times for the different -options provided by \styfmt{glossaries} and \styfmt{glossaries-extra}). +options provided by \styfmt{glossaries} and \gls{glossaries-extra}). \item \href{http://www.dickimaw-books.com/latex/thesis/}{Using LaTeX to Write a PhD Thesis} (chapter 6). @@ -587,12 +808,13 @@ options provided by \styfmt{glossaries} and \styfmt{glossaries-extra}). \item \href{http://ctan.org/pkg/bib2gls}{\appfmt{bib2gls}} \end{itemize} -\begin{important} +\begin{important*} If you use \sty{hyperref} and \styfmt{glossaries}, you must load -\sty{hyperref} \emph{first}. Similarly the \sty{doc} package must +\sty{hyperref} \emph{first} (although \sty{hyperref} should be +loaded after most other packages). Similarly the \sty{doc} package must also be loaded before \styfmt{glossaries}. (If \sty{doc} is loaded, the file extensions for the default main glossary are changed to -\filetype{gls2}, \filetype{glo2} and \filetype{.glg2} to avoid +\filetype{gls2}, \filetype{glo2} and \filetype{glg2} to avoid conflict with \sty{doc}'s changes glossary.)\hypertarget{pdflatexnote}{}% @@ -603,10 +825,15 @@ encounter problems where you have long hyperlinks or hyperlinks in subscripts or superscripts. This is an issue with the DVI format not with \styfmt{glossaries}. If you really need to use the DVI format and have a problem with hyperlinks in maths mode, I recommend you use -\gls{glossaries-extra} with the \texttt{hyperoutside} and -\texttt{textformat} attributes set to appropriate values +\gls{glossaries-extra} with the \attr{hyperoutside} and +\attr{textformat} attributes set to appropriate values for problematic entries. -\end{important} +\end{important*} + +\strong{The \styfmt{glossaries} package replaces the \styfmt{glossary} +package which is now obsolete.} Please see the document +\qtdocref{Upgrading from the glossary package to the glossaries +package}{glossary2glossaries} for assistance in upgrading. \clearpage \pdfbookmark[0]{Contents}{contents} @@ -628,64 +855,154 @@ for problematic entries. The \styfmt{glossaries} package is provided to assist generating lists of terms, symbols or abbreviations. (For convenience, these -lists are all referred to as glossaries in this manual.) +lists are all referred to as glossaries in this manual. The terms, +symbols and abbreviations are collectively referred to as entries.) The package has a certain amount of flexibility, allowing the user to customize the format of the glossary and define multiple glossaries. It also supports glossary styles that -include symbols (in addition to a name and description) for glossary -entries. There is provision for loading a database of glossary -terms. Only those terms indexed\footnote{That is, if the term has been +include an associated symbol (in addition to a name and description) +for each glossary entry. + +There is provision for loading a database of glossary entries. Only +those entries indexed\footnote{That is, if the entry has been referenced using any of the commands described in \sectionref{sec:glslink} and \sectionref{sec:glsadd} or via \ics{glssee} (or the \gloskey{see} key) or commands such as -\ics{acrshort}.}\ in the document will be added to the glossary. +\ics{acrshort} or \ics*{glsxtrshort}.}\ in the document will be displayed in the glossary. +(Unless you use \opt5, which doesn't use any indexing but will +instead list all defined entries in order of definition.) -The \styfmt{glossaries-extra} package, which is distributed as a -separated bundle, extends the capabilities of -the \styfmt{glossaries} package. The simplest document can be -created with \styfmt{glossaries-extra} (which internally loads the -\styfmt{glossaries} package): +It's not necessary to actually have a glossary in the document. You may be +interested in using this package just as means to consistently +format certain types of terms, such as abbreviations, or you may +prefer to have descriptions scattered about the document and be able +to easily link to the relevant description (\opt6). + +The simplest document is one without a glossary: \begin{verbatim} \documentclass{article} - \usepackage[ - sort=none,% no sorting or indexing required - abbreviations,% create list of abbreviations - symbols,% create list of symbols - postdot % append a full stop after the descriptions -]{glossaries-extra} + sort=none % no sorting or indexing required +] +{glossaries} -\newglossaryentry % provided by glossaries.sty +\newglossaryentry {cafe}% label {% definition: name={caf\'e}, description={small restaurant selling refreshments} } -\newabbreviation % provided by glossaries-extra.sty +\setacronymstyle{long-short} + +\newacronym {html}% label {HTML}% short form {hypertext markup language}% long form -\glsxtrnewsymbol % provided by glossaries-extra.sty 'symbols' option - [description={Archimedes' constant}]% options +\newglossaryentry {pi}% label - {\ensuremath{\pi}}% symbol + {% definition: + name={\ensuremath{\pi}}, + description={Archimedes' Constant} + } + +\newglossaryentry + {distance}% label + {% definition: + name={distance}, + description={the length between two points}, + symbol={m} + } \begin{document} First use: \gls{cafe}, \gls{html}, \gls{pi}. Next use: \gls{cafe}, \gls{html}, \gls{pi}. -\printunsrtglossaries % list all defined entries +\Gls{distance} (\glsentrydesc{distance}) is measured in +\glssymbol{distance}. \end{document} \end{verbatim} +(This is a trivial example. For a real document I recommend you use +\sty{siunitx} for units.) -\textbf{The \styfmt{glossaries} package replaces the \sty{glossary} -package which is now obsolete.} Please see the document -\qtdocref{Upgrading from the glossary package to the glossaries -package}{glossary2glossaries} for assistance in upgrading. +\glsxtrnote +The \gls{glossaries-extra} package, which is distributed as a +separate bundle, extends the capabilities of +the \styfmt{glossaries} package. The simplest document with a glossary can be +created with \gls{glossaries-extra} (which internally loads the +\styfmt{glossaries} package): +\begin{verbatim} +\documentclass{article} +\end{verbatim} +\begin{alltt} +\cs{usepackage}[ + sort=none,% no sorting or indexing required + \xtrfont{abbreviations},% create list of abbreviations + symbols,% create list of symbols + \xtrfont{postdot}, % append a full stop after the descriptions + \xtrfont{stylemods},style=index % set the default glossary style +]\mgroup{glossaries-extra} +\end{alltt} +\begin{verbatim} +\newglossaryentry % provided by glossaries.sty + {cafe}% label + {% definition: + name={caf\'e}, + description={small restaurant selling refreshments} + } +\end{verbatim} +\begin{alltt} +\% provided by glossaries-extra.sty: +\ics*{setabbreviationstyle}\mgroup{long-short} + +\ics*{newabbreviation} \% provided by glossaries-extra.sty + \mgroup{html}\% label + \mgroup{HTML}\% short form + \mgroup{hypertext markup language}\% long form + +\% provided by glossaries-extra.sty 'symbols' option: +\ics*{glsxtrnewsymbol} + [description=\mgroup{Archimedes' constant}]\% options + \mgroup{pi}\% label + \mgroup{\cs{ensuremath}\mgroup{\cs{pi}}}\% symbol +\end{alltt} +\begin{verbatim} +\newglossaryentry % provided by glossaries.sty + {distance}% label + {% definition: + name={distance}, + description={the length between two points}, + symbol={m} + } + +\begin{document} +First use: \gls{cafe}, \gls{html}, \gls{pi}. +Next use: \gls{cafe}, \gls{html}, \gls{pi}. -One of the strengths of this package is its flexibility, however +\Gls{distance} is measured in \glssymbol{distance}. +\end{verbatim} +\begin{alltt} +\ics*{printunsrtglossaries} \% list all defined entries +\cs{end}\mgroup{document} +\end{alltt} +Note the difference in the way the abbreviation (HTML) and symbol +(\ensuremath{\pi}) are defined in the two above examples. The +\pkgopt*{abbreviations}, \pkgopt*{postdot} and \pkgopt*{stylemods} +options are specific to \gls{glossaries-extra}. Other options are +passed to the base \styfmt{glossaries} package. + +\begin{xtr} +In this document, commands and options displayed in teal, such as +\xtrcs{newabbreviation} and \pkgopt*{stylemods}, are only available with +the \gls{glossaries-extra} package. There are also some commands and options (such +as \cs{makeglossaries} and \pkgopt{symbols}) that are provided by the +base \styfmt{glossaries} package but are redefined by the +\gls{glossaries-extra} package. See the \gls{glossaries-extra} user +manual for further details of those commands. +\end{xtr} + +One of the strengths of the \styfmt{glossaries} package is its flexibility, however the drawback of this is the necessity of having a large manual that covers all the various settings. If you are daunted by the size of the manual, try starting off with the much shorter @@ -694,8 +1011,9 @@ size of the manual, try starting off with the much shorter \begin{important} There's a~common misconception that you have to have Perl installed in order to use the \styfmt{glossaries} package. Perl is \emph{not} -a~requirement but it does increase the available options, -particularly if you use an \gls{exlatinalph} or a~\gls{nonlatinalph}. +a~requirement (as demonstrated by the above examples) but it does +increase the available options, particularly if you use an \gls{exlatinalph} +or a~\gls{nonlatinalph}. \end{important} This document uses the \styfmt{glossaries} package. For example, @@ -710,6 +1028,11 @@ which means they can be run directly from a command prompt or terminal, or can be integrated into some text editors, or you can use a build tool such as \app{arara} to run them. +Neither of the above two examples require an \gls{indexingapp}. The +first is just using the \styfmt{glossaries} package for consistent +formatting, and there is no list. The second has lists but they are +unsorted (see \opt5). + The remainder of this introductory section covers the following: \begin{itemize} \item \sectionref{sec:indexingoptions} lists the available indexing @@ -740,11 +1063,17 @@ you can reference these within your document (like \cs{cite} or you have referenced in your document (the glossary). This last part, displaying the glossary, is the part that most new users find difficult. There are three options available with the base -\styfmt{glossaries} package and two further options with the -extension package \gls{glossaries-extra}. -An overview of these options is given in -\tableref{tab:options}. +\styfmt{glossaries} package (\optsto13). The \gls{glossaries-extra} extension +package provides two extra options for lists (\optsand45) as well as an option for +standalone descriptions within the document body (\opt6). + +An overview of \optsto15 is given in \tableref{tab:options}. +\opt6 is omitted from the table as it doesn't produce a list. For a +more detailed comparison of the various methods, see the +\gallery{glossaries-performance.shtml}{\styfmt{glossaries} +performance page}. +\begin{important} If you are developing a class or package that loads \styfmt{glossaries}, I recommend that you don't force the user into a particular indexing method by adding an unconditional \cs{makeglossaries} @@ -753,10 +1082,14 @@ particular indexing method, it means that they're unable to use any commands that must come before \cs{makeglossaries} (such as \cs{newglossary}) and they can't switch off the indexing whilst working on a draft document. +\end{important} -For a comparison of the various methods when used with large entry -sets or when used with symbols such as \cs{alpha}, see the -\href{http://www.dickimaw-books.com/gallery/glossaries-performance.shtml}{\styfmt{glossaries} performance page}. +Strictly speaking, \optsand56 aren't actually indexing options as no +indexing is performed. In the case of \opt5, all defined entries are +listed in order of definition. In the case of \opt6, the entry +hypertargets and descriptions are manually inserted at appropriate +points in the document. These two options are included here for +completeness and for comparison with the actual indexing options. \begin{table}[htbp] \caption{Glossary Options: Pros and Cons} @@ -819,27 +1152,49 @@ sets or when used with symbols such as \cs{alpha}, see the \fnsym{1} Strips standard \LaTeX\ accents (that is, accents generated by core \LaTeX\ commands) so, for example, \ics{AA} is treated the same as A.\par - \fnsym{2} Only with the hybrid method provided with \sty{glossaries-extra}.\par + \fnsym{2} Only with the hybrid method provided with \gls{glossaries-extra}.\par \fnsym{3} Provided \pkgopt[none]{sort} is used.\par \fnsym{4} Entries with the same sort value are merged.\par \fnsym{5} Requires some setting up.\par \fnsym{6} The locations must be set explicitly -through the custom \field{location} field provided by +through the custom \xtrfield{location} field provided by \styfmt{glossaries-extra}.\par \fnsym{7} Unlimited but unreliable.\par - \fnsym{8} Entries are defined in \texttt{.bib} + \fnsym{8} Entries are defined in \filetype{bib} format. \cs{newglossaryentry} should not be used explicitly.\par - \fnsym{9} Provided \pkgoptfmt{docdefs=true} or -\pkgoptfmt{docdefs=restricted} but not recommended.\par - \fnsym{10} Provided \pkgoptfmt{docdefs=false} or -\pkgoptfmt{docdefs=restricted}.\par - \fnsym{11} Irrelevant with \pkgopt[none]{sort}. (The \optfmt{record=only} + \fnsym{9} Provided \pkgopt+{true}{docdef} or + \pkgopt+{restricted}{docdef} but not recommended.\par + \fnsym{10} Provided \pkgopt+{false}{docdef} or + \pkgopt+{restricted}{docdef}.\par + \fnsym{11} Irrelevant with \pkgopt[none]{sort}. (The \pkgopt+{only}{record} option automatically switches this on.) \par \end{table} \optionsec[\TeX]{TeX} +Example Document: +\begin{verbatim} +\documentclass{article} +\usepackage{glossaries} +\end{verbatim} +\begin{alltt} +\strong{\ics{makenoidxglossaries}} \% use TeX to sort +\end{alltt} +\begin{verbatim} +\newglossaryentry{sample}{name={sample}, + description={an example}} +\begin{document} +\gls{sample}. +\end{verbatim} +\begin{alltt} +\strong{\ics{printnoidxglossary}} +\cs{end}\mgroup{document} +\end{alltt} +You can place all your entry definitions in a separate file +and load it in the preamble with \ics{loadglsentries} (\emph{after} +\ics{makenoidxglossaries}). + This option doesn't require an external \gls{indexingapp} but, with the default alphabetic sorting, it's very slow with severe limitations. If you want a sorted list, it doesn't work well for @@ -856,15 +1211,20 @@ such as \cs{alpha} or \cs{si}, then you must use (\pkgopt[use]{sort} or \pkgopt[def]{sort}) in the package options or explicitly set the \gloskey{sort} key when you define the relevant entries. For example: -\begin{verbatim} -\newglossaryentry{alpha}{name={\ensuremath{\alpha}}, - sort={alpha},description={...}} -\end{verbatim} +\begin{alltt} +\ics{newglossaryentry}\mgroup{alpha}\mgroup{name=\mgroup{\cs{ensuremath}\mgroup{\cs{alpha}}}, + \strong{sort=\mgroup{alpha}},description=\mgroup{...}} +\end{alltt} +\begin{xtr} +The \gls{glossaries-extra} package has a modified \pkgopt{symbols} +package option that provides \ics*{glsxtrnewsymbol}, which automatically sets the +\gloskey{sort} key to the entry label (instead of the \gloskey{name}). +\end{xtr} This option works best with the \pkgopt[def]{sort} or \pkgopt[use]{sort} setting. For any other setting, be prepared for a long document build time, -especially if you have a lot of entries defined. \textbf{This +especially if you have a lot of entries defined. \strong{This option is intended as a last resort for alphabetical sorting.} This option allows a mixture of sort methods. (For example, sorting by word order for one glossary and order of use for another.) @@ -896,20 +1256,29 @@ not form ranges in the \glspl{numberlist}. If you really can't use an the \qt{typeset} or \qt{build} or \qt{PDF\LaTeX} button in your editor. \end{enumerate} -Complete example: +\optionsec{makeindex} + +Example document: \begin{verbatim} \documentclass{article} \usepackage{glossaries} -\makenoidxglossaries % use TeX to sort -\newglossaryentry{sample}{name={sample}, - description={an example}} +\end{verbatim} +\begin{alltt} +\strong{\ics{makeglossaries}} \% open glossary files +\end{alltt} +\begin{verbatim} +\newglossaryentry{sample}{name={sample}, + description={an example}} \begin{document} \gls{sample}. -\printnoidxglossary -\end{document} \end{verbatim} - -\optionsec{makeindex} +\begin{alltt} +\strong{\ics{printglossary}} +\cs{end}\mgroup{document} +\end{alltt} +You can place all your entry definitions in a separate file +and load it in the preamble with \ics{loadglsentries} (\emph{after} +\ics{makeglossaries}). This option uses a~\gls{cli} application called \gls{makeindex} to sort the entries. This application comes with all modern \TeX\ distributions, @@ -924,12 +1293,11 @@ to typeset the glossary. Then \cs{printglossary} reads this file in on the next run. This option works best if you want to sort entries according to the -English alphabet and you don't want to install Perl (or Java or -you don't want to use \gls{glossaries-extra}). This method can -also work with the restricted shell escape since \gls{makeindex} -is considered a trusted application. (So you should be able to -use the \pkgopt{automake} package option provided the shell -escape hasn't been completely disabled.) +English alphabet and you don't want to install Perl or Java. This +method can also work with the restricted shell escape since +\gls{makeindex} is considered a trusted application. (So you should +be able to use the \pkgopt{automake} package option provided the +shell escape hasn't been completely disabled.) This method can form ranges in the \gls{numberlist} but only accepts limited number formats: \cs{arabic}, \cs{roman}, @@ -941,10 +1309,15 @@ word\slash letter ordering or order of use or order of definition. If you need word ordering for one glossary and letter ordering for another you'll have to explicitly call \gls{makeindex} for each glossary type. -(The \sty{glossaries-extra} package allows a hybrid mix of + +\begin{xtr} +The \gls{glossaries-extra} package allows a hybrid mix of \optsand12 to provide word\slash letter ordering with \opt2 and order -of use\slash definition with \opt1. See the \sty{glossaries-extra} -documentation for further details.) +of use\slash definition with \opt1. See the \gls{glossaries-extra} +documentation for further details. See also the +\gls{glossaries-extra} alternative to \samplefile{Sort} in +\sectionref{sec:samplessort}. +\end{xtr} \begin{enumerate} \item If you want to use \gls{makeindex}['s] \mkidxopt{g} option @@ -977,74 +1350,109 @@ to your preamble (before you start \end{verbatim} \item Run \LaTeX\ on your document. This creates files with the - extensions \texttt{.glo} and \texttt{.ist} (for example, if your + extensions \filetype{glo} and \filetype{ist} (for example, if your \LaTeX\ document is called \texttt{myDoc.tex}, then you'll have two extra files called \texttt{myDoc.glo} and \texttt{myDoc.ist}). If you look at your document at this point, you won't see the glossary as it hasn't been created yet. (If you use - \sty{glossaries-extra} you'll see the section heading and some + \gls{glossaries-extra} you'll see the section heading and some boilerplate text.) - \item Run \gls{makeindex} with the \texttt{.glo} file as the + If you have used package options such as \pkgopt{symbols} there + will also be other sets of files corresponding to the extra + glossaries that were created by those options. + + \item\plabel{makeindex.run} Run \gls{makeindex} with the \texttt{.glo} file as the input file and the \texttt{.ist} file as the style so that it creates an output file with the extension \texttt{.gls}. If you have access to a terminal or a command prompt (for example, the MSDOS command prompt for Windows users or the bash console for Unix-like users) then you need to run the command: -\begin{verbatim} +\begin{prompt} makeindex -s myDoc.ist -o myDoc.gls myDoc.glo -\end{verbatim} +\end{prompt} (Replace \texttt{myDoc} with the base name of your \LaTeX\ - document file. Avoid spaces in the file name if possible.) If you don't know - how to use the command prompt, then you can probably access + document file. Avoid spaces in the file name if possible. + The \textbf{\ttfamily\$} symbol indicates the command prompt and should be omitted.) + +\begin{important} +The file extensions vary according to the glossary \gloskey{type}. +See \sectionref{sec:makeindexapp} for further details. +\gls{makeindex} must be called for each set of files. +\end{important} + + If you don't know how to use the command prompt, then you can probably access \gls{makeindex} via your text editor, but each editor has a - different method of doing this, so I~can't give a~general - description. You will have to check your editor's manual. The - simplest approach is to use \app{arara} and add the following + different method of doing this. See \href{https://www.dickimaw-books.com/latex/buildglossaries/}{Incorporating +makeglossaries or makeglossaries-lite or bib2gls into the document +build} for some examples. + + Alternatively, run \gls{makeindex} indirectly via the +\gls{makeglossaries} script: +\begin{prompt} +makeglossaries myDoc +\end{prompt} + Note that the file extension isn't supplied in this case. + (Replace \gls{makeglossaries} with \gls{makeglossaries-lite.lua} if + you don't have Perl installed.) + This will pick up all the file extensions from the + \filetype{aux} file and run \gls{makeindex} the appropriate number + of times with all the necessary switches. + + The simplest approach is to use \app{arara} and add the following comment lines to the start of your document: \begin{alltt} -\% arara:\ pdflatex -\% arara:\ makeglossaries -\% arara:\ pdflatex +\% arara: pdflatex +\% arara: makeglossaries +\% arara: pdflatex \end{alltt} - (Replace \texttt{makeglossaries} with - \texttt{makeglossaries-lite} if you don't have Perl installed.) + (Replace \texttt{makeglossaries} with \texttt{makeglossarieslite} in the + second line above if you don't have Perl installed. Note that + there's no hyphen in this case.) The default sort is word order (\qt{sea lion} comes before \qt{seal}). If you want letter ordering you need to add the \mkidxopt{l} switch: -\begin{verbatim} +\begin{prompt} makeindex -l -s myDoc.ist -o myDoc.gls myDoc.glo -\end{verbatim} +\end{prompt} (See \sectionref{sec:makeindexapp} for further details on using \gls*{makeindex} explicitly.) If you use \gls{makeglossaries} or \gls{makeglossaries-lite.lua} then use the \pkgopt[letter]{order} package option and the \mkidxopt{l} option will be added automatically. - \item Once you have successfully completed the previous step, - you can now run \LaTeX\ on your document again. You'll need to - repeat the process if you have used the \pkgopt{toc} option - (unless you're using \sty{glossaries-extra}) to ensure the - section heading is added to the table of contents. You'll also - need to repeat the process if you have any cross-references - which can't be indexed until the glossary file has been created. + \item\plabel{makeindex.relatex} Once you have successfully completed the previous step, + you can now run \LaTeX\ on your document again. \end{enumerate} +You'll need to repeat the last step if you have used the +\pkgopt{toc} option (unless you're using \gls{glossaries-extra}) to +ensure the section heading is added to the table of contents. +You'll also need to repeat steps~\ref{makeindex.run} and~\ref{makeindex.relatex} +if you have any cross-references which can't be indexed until the glossary file has +been created. + +\optionsec{xindy} -Complete example: +Example document: +\begin{alltt} +\cs{documentclass}\mgroup{article} +\cs{usepackage}[\strong{xindy}]\mgroup{glossaries} +\strong{\ics{makeglossaries}} \% open glossary files +\end{alltt} \begin{verbatim} -\documentclass{article} -\usepackage{glossaries} -\makeglossaries % open glossary files \newglossaryentry{sample}{name={sample}, description={an example}} \begin{document} \gls{sample}. -\printglossary -\end{document} \end{verbatim} - -\optionsec{xindy} +\begin{alltt} +\strong{\ics{printglossary}} +\cs{end}\mgroup{document} +\end{alltt} +You can place all your entry definitions in a separate file +and load it in the preamble with \ics{loadglsentries} (\emph{after} +\ics{makeglossaries}). This option uses a~\gls{cli} application called \gls{xindy} to sort the entries. This application is more flexible than @@ -1076,17 +1484,25 @@ some problems with certain sort values: \end{itemize} In these problematic cases, you must set the \gloskey{sort} field explicitly. For example: -\begin{verbatim} -\newglossaryentry{alpha}{name={\ensuremath{\alpha}}, - sort={alpha},description={...}} -\end{verbatim} +\begin{alltt} +\cs{newglossaryentry}\mgroup{alpha}\mgroup{name=\mgroup{\cs{ensuremath}\mgroup{\cs{alpha}}}, + \strong{sort=\mgroup{alpha},}description=\mgroup{...}} +\end{alltt} +\begin{xtr} +The \gls{glossaries-extra} package has a modified \pkgopt{symbols} +package option that provides \ics*{glsxtrnewsymbol}, which automatically sets the +\gloskey{sort} key to the entry label (instead of the \gloskey{name}). +\end{xtr} All glossaries must be sorted according to the same method (word/letter ordering, order of use, or order of definition). -(The \sty{glossaries-extra} package allows a hybrid mix of + +\begin{xtr} +The \gls{glossaries-extra} package allows a hybrid mix of \optsand13 to provide word\slash letter ordering with \opt3 and order -of use\slash definition with \opt1. See the \sty{glossaries-extra} -documentation for further details.) +of use\slash definition with \opt1. See the \gls{glossaries-extra} +documentation for further details. +\end{xtr} \begin{enumerate} \item Add the \pkgopt{xindy} option to the \styfmt{glossaries} @@ -1099,7 +1515,8 @@ package option list: \begin{verbatim} \usepackage[xindy={glsnumbers=false}]{glossaries} \end{verbatim} - or use either \cs{GlsSetXdyFirstLetterAfterDigits}\marg{letter} or + or use either \cs{GlsSetXdyFirstLetterAfterDigits}\marg{letter} (to indicate the +first letter group to follow the digits) or \cs{GlsSetXdyNumberGroupOrder}\marg{spec} to indicate where the number group should be placed (see \sectionref{sec:xindy}). @@ -1107,14 +1524,18 @@ package option list: defining your entries, as described in \sectionref{sec:newglosentry}). \item Run \LaTeX\ on your document. This creates files with the - extensions \texttt{.glo} and \texttt{.xdy} (for example, if your + extensions \filetype{glo} and \filetype{xdy} (for example, if your \LaTeX\ document is called \texttt{myDoc.tex}, then you'll have two extra files called \texttt{myDoc.glo} and \texttt{myDoc.xdy}). If you look at your document at this point, you won't see the glossary as it hasn't been created yet. (If you're using the - extension package \sty{glossaries-extra}, you'll see the section + \gls{glossaries-extra} extension package, you'll see the section header and some boilerplate text.) + If you have used package options such as \pkgopt{symbols} there + will also be other sets of files corresponding to the extra + glossaries that were created by those options. + \item Run \gls{xindy} with the \texttt{.glo} file as the input file and the \texttt{.xdy} file as a~module so that it creates an output file with the extension \texttt{.gls}. You @@ -1123,19 +1544,31 @@ package option list: MSDOS command prompt for Windows users or the bash console for Unix-like users) then you need to run the command (all on one line): -\begin{verbatim} -xindy -L english -C utf8 -I xindy -M myDoc --t myDoc.glg -o myDoc.gls myDoc.glo -\end{verbatim} +\begin{prompt} +xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.glg -o myDoc.gls myDoc.glo +\end{prompt} (Replace \texttt{myDoc} with the base name of your \LaTeX\ document file. Avoid spaces in the file name. If necessary, also replace \texttt{english} with the name of your language and \texttt{utf8} with your input encoding, for example, \xdyopt{L}\texttt{ german }\xdyopt{C}\texttt{ din5007-utf8}.) - Note that it's much simpler to use \gls{makeglossaries} instead: -\begin{verbatim} + +\begin{important} +The file extensions vary according to the glossary \gloskey{type}. +See \sectionref{sec:xindyapp} for further details. +\gls{xindy} must be called for each set of files. +\end{important} + + It's much simpler to use \gls{makeglossaries} instead: +\begin{prompt} makeglossaries myDoc -\end{verbatim} +\end{prompt} + Note that the file extension isn't supplied in this case. + This will pick up all the file extensions from the + \filetype{aux} file and run \gls{xindy} the appropriate number + of times with all the necessary switches. + + There's no benefit in using \gls{makeglossaries-lite.lua} with \gls{xindy}. (Remember that \gls{xindy} is a Perl script so if you can use \gls{xindy} then you can also use \gls{makeglossaries}, and if you don't want to use \gls{makeglossaries} because you don't @@ -1143,14 +1576,16 @@ makeglossaries myDoc If you don't know how to use the command prompt, then you can probably access \gls{xindy} or \gls{makeglossaries} via your text editor, - but each editor has a different method of doing this, so I~can't give - a~general description. You will have to check your editor's manual. Again, - a convenient method is to use \appfmt{arara} and add the follow comment + but each editor has a different method of doing this. See \href{https://www.dickimaw-books.com/latex/buildglossaries/}{Incorporating +makeglossaries or makeglossaries-lite or bib2gls into the document +build} for some examples. + + Again, a convenient method is to use \appfmt{arara} and add the follow comment lines to the start of your document: \begin{alltt} -\% arara:\ pdflatex -\% arara:\ makeglossaries -\% arara:\ pdflatex +\% arara: pdflatex +\% arara: makeglossaries +\% arara: pdflatex \end{alltt} The default sort is word order (\qt{sea lion} comes before \qt{seal}). @@ -1166,139 +1601,193 @@ makeglossaries myDoc \gls*{xindy} explicitly. \item Once you have successfully completed the previous step, - you can now run \LaTeX\ on your document again. As with the - previous option, you may need to repeat the process to ensure - the table of contents and cross-references are resolved. + you can now run \LaTeX\ on your document again. As with + \gls{makeindex} (\opt2), you may need to repeat the previous + step and this step to ensure the table of contents and cross-references are resolved. \end{enumerate} -Complete example: -\begin{verbatim} -\documentclass{article} -\usepackage[xindy]{glossaries} -\makeglossaries % open glossary files -\newglossaryentry{sample}{name={sample}, - description={an example}} -\begin{document} -\gls{sample}. -\printglossary -\end{document} -\end{verbatim} - \optionsec{bib2gls} -This option is only available with the extension package -\gls{glossaries-extra}. This method uses \gls{bib2gls} to both -fetch entry definitions from \texttt{.bib} files and to -hierarchically sort and collate. +\glsxtrnote +This option is only available with the \gls{glossaries-extra} extension package. +This method uses \gls{bib2gls} to both fetch entry definitions from +\filetype{bib} files and to hierarchically sort and collate. + +Example document: +\begin{alltt} +\cs{documentclass}\mgroup{article} +\cs{usepackage}[\xtrfont{record=nameref}]\mgroup{glossaries-extra} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=\mgroup{entries}] +\cs{begin}\mgroup{document} +\cs{gls}\mgroup{sample}, \cs{gls}\mgroup{alpha}, \cs{gls}\mgroup{html}. +\ics*{printunsrtglossary} +\cs{end}\mgroup{document} +\end{alltt} +where the file \texttt{entries.bib} contains: +\begin{alltt} +\atentry{entry}\mgroup{sample, + name=\mgroup{sample}, + description=\mgroup{an example} +} +\atentry{symbol}\mgroup{alpha, + name=\mgroup{\cs{ensuremath}\mgroup{\cs{alpha}}}, + description=\mgroup{...} +} +\atentry{abbreviation}\mgroup{html, + short=\mgroup{HTML}, + long=\mgroup{hypertext markup language} +} +\end{alltt} + +All entries must be provided in one or more \filetype{bib} files. +See the \gls{bib2gls} user manual for the required format. + +\begin{important} +Note that the \gloskey{sort} key should not be used. Each entry type +(\atentry{entry}, \atentry{symbol}, \atentry{abbreviation}) has a +particular field that's used for the sort value by default +(\gloskey{name}, the label, \gloskey{short}). You will break this +mechanism if you explicitly use the \gloskey{sort} key. See +\bibglsgallery{sorting} for examples. +\end{important} + +The \gls{glossaries-extra} package needs to be loaded with the +\pkgopt*{record} package option: +\begin{alltt} +\cs{usepackage}[\xtrfont{record}]\mgroup{glossaries-extra} +\end{alltt} +or (equivalently) +\begin{alltt} +\cs{usepackage}[\xtrfont{record=only}]\mgroup{glossaries-extra} +\end{alltt} +or (with at least \gls{glossaries-extra} v1.37 and \gls{bib2gls} v1.8): +\begin{alltt} +\cs{usepackage}[\xtrfont{record=nameref}]\mgroup{glossaries-extra} +\end{alltt} +The \pkgopt+{nameref}{record} option is the best method. -All entries must be provided in one or more \texttt{.bib} files. -(See the \gls{bib2gls} user manual for the required format.) The -\sty{glossaries-extra} package needs to be loaded with the -\pkgoptfmt{record} package option -\begin{verbatim} -\usepackage[record]{glossaries-extra} -\end{verbatim} -or (equivalently) -\begin{verbatim} -\usepackage[record=only]{glossaries-extra} -\end{verbatim} (It's possible to use a hybrid of this method and \optsor23 with -\pkgoptfmt{record=alsoindex} but in general there is little need +\pkgopt+{alsoindex}{record} but in general there is little need for this and it complicates the build process.) -Each resource set is loaded with \cs{GlsXtrLoadResources}\oarg{options}. +Each resource set is loaded with \ics*{GlsXtrLoadResources}\oarg{options}. For example: -\begin{verbatim} -\GlsXtrLoadResources -[% definitions in entries1.bib and entries2.bib: - src={entries1,entries2}, - sort={de-CH-1996}% sort according to this locale +\begin{alltt} +\ics*{GlsXtrLoadResources} +[\% definitions in entries1.bib and entries2.bib: + \resourceopt{src}=\mgroup{entries1,entries2}, + \resourceopt{sort}=\mgroup{de-CH-1996}\% sort according to this locale ] -\end{verbatim} -You can have multiple resource commands. - -The glossary is displayed using -\begin{verbatim} -\printunsrtglossary -\end{verbatim} +\end{alltt} +The \filetype{bib} files are identified as a comma-separated list in the +value of the \resourceopt{src} key. The \resourceopt{sort} option +identifies the sorting method. This may be a locale identifier for +alphabetic sorting, but there are other sort methods available, such +as character code or numeric. One resource set may cover multiple +glossaries or one glossary may be split across multiple resource +sets, forming logical sub-blocks. + +If you want to ensure that all entries are selected, even if +they haven't been referenced in the document, then add the option +\resourceopt[all]{selection}. (There are also ways of filtering the +selection or you can even have a random selection by shuffling and +truncating the list. See the \gls{bib2gls} user manual for further details.) + +The glossary is displayed using: +\begin{alltt} +\ics*{printunsrtglossary} +\end{alltt} Alternatively all glossaries can be displayed using the iterative command: -\begin{verbatim} -\printunsrtglossaries -\end{verbatim} -The document is build using: -\begin{verbatim} +\begin{alltt} +\ics*{printunsrtglossaries} +\end{alltt} +The document is built using: +\begin{prompt} pdflatex myDoc bib2gls myDoc pdflatex myDoc -\end{verbatim} -If letter groups are required, you need the \verb|--group| switch: -\begin{verbatim} -bib2gls --group myDoc -\end{verbatim} +\end{prompt} +If letter groups are required, you need the \bibglslongopt{group} switch: +\begin{prompt} +bib2gls -{}-group myDoc +\end{prompt} +or with \app{arara}: +\begin{alltt} +\% arara: bib2gls: \mgroup{ group: on } +\end{alltt} +(You will also need an appropriate glossary style.) + Unlike \optsand23, this method doesn't create a file containing the typeset glossary but simply determines which entries are needed for the document, their associated locations and (if required) their associated letter group. This option allows -a mixture of sort methods. (For example, sorting by word order +a mixture of sort methods. For example, sorting by word order for one glossary and order of use for another or even sorting one block of the glossary differently to another block in the -same glossary.) +same glossary. See \bibglsgallery{sorting}. + +This method supports Unicode and uses the Common Locale Data +Repository, which provides more extensive language support than +\gls{xindy}.\footnote{Except for Klingon, which is supported by +\gls{xindy}, but not by the CLDR.}\ The locations in the +\gls{numberlist} may be in any format. If \gls{bib2gls} can deduce a +numerical value it will attempt to form ranges otherwise it will +simply list the locations. + +See \bibglsbegin\ or the \gls{bib2gls} user manual for further +details of this method, and +also \href{https://www.dickimaw-books.com/latex/buildglossaries/}{Incorporating +makeglossaries or makeglossaries-lite or bib2gls into the document +build}. + +\optionsec[no sorting]{no sorting} -This method supports Unicode and (with at least Java~8) uses -the Common Locale Data Repository, which provides more extensive -language support than \gls{xindy}.\footnote{Except for Klingon, -which is supported by \gls{xindy}, but not by the -CLDR.}\ The locations in the -\gls{numberlist} may be in any format. If \gls{bib2gls} can -deduce a numerical value it will attempt to form ranges otherwise -it will simply list the locations. +\glsxtrnote +This option is only available with the extension package +\gls{glossaries-extra}. No \gls{indexingapp} is required. -Complete example: +Example document: \begin{verbatim} \documentclass{article} -\usepackage[record]{glossaries-extra} -\GlsXtrLoadResources[src={entries}] +\usepackage[sort=none]{glossaries-extra} +\newglossaryentry{sample}{name={sample}, + description={an example}} +\newglossaryentry{alpha}{name={\ensuremath{\alpha}}, + description={...}} \begin{document} \gls{sample}. -\printunsrtglossary -\end{document} -\end{verbatim} -where \texttt{entries.bib} contains -\begin{verbatim} -@entry{sample, - name={sample}, - description={an example} -} \end{verbatim} -See the \gls{bib2gls} user manual for further details. - -\optionsec[no sorting]{no sorting} +\begin{alltt} +\ics*{printunsrtglossary} +\cs{end}\mgroup{document} +\end{alltt} -This option is only available with the extension package -\gls{glossaries-extra}. No \gls{indexingapp} is required. This -method is best used with the package option \pkgopt[none]{sort}. -\begin{verbatim} -\usepackage[sort=none]{glossaries-extra} -\end{verbatim} -There's no \qt{activation} command (such as \cs{makeglossaries} +This method is best used with the package option \pkgopt[none]{sort} +(as shown above). There's no \qt{activation} command (such as \cs{makeglossaries} for \optsand23). All entries must be defined before the glossary is displayed (preferably in the preamble) in the required order, and child entries must be defined immediately after their parent entry -if they must be kept together in the glossary - -The glossary is displayed using -\begin{verbatim} -\printunsrtglossary -\end{verbatim} +if they must be kept together in the glossary. (Some glossary styles +indent entries that have a parent but it's the \gls{indexingapp} +that ensures the child entries are listed immediately after the +parent. If you're opting to use this manual approach then it's your +responsibility to define the entries in the correct order.) You can +place all your entry definitions in a separate file +and load it in the preamble with \ics{loadglsentries}. + +The glossary is displayed using: +\begin{alltt} +\ics*{printunsrtglossary} +\end{alltt} Alternatively all glossaries can be displayed using the iterative command: -\begin{verbatim} -\printunsrtglossaries -\end{verbatim} +\begin{alltt} +\ics*{printunsrtglossaries} +\end{alltt} This will display \emph{all} defined entries, regardless of whether or not they have been used in the document. The \glspl{numberlist} have to be set explicitly otherwise they won't @@ -1307,651 +1796,428 @@ glossary as \opt4. This is because \gls{bib2gls} takes advantage of this method by defining the wanted entries in the required order and setting the locations (and letter group information, if required). -This just requires a single \LaTeX\ call -\begin{verbatim} +Therefore, the above example document has a glossary containing the +entries: sample and $\alpha$ (in that order). Note that +the \texttt{alpha} entry has been included even though it wasn't +referenced in the document. + +This just requires a single \LaTeX\ call: +\begin{prompt} pdflatex myDoc -\end{verbatim} +\end{prompt} unless the glossary needs to appear in the table of contents, in which case -a second run is required. -\begin{verbatim} +a second run is required: +\begin{prompt} pdflatex myDoc pdflatex myDoc -\end{verbatim} +\end{prompt} (Naturally if the document also contains citations, and so on, then additional steps are required. Similarly for all the other options above.) -Complete example: +See the \gls{glossaries-extra} documentation for further details of this method. + +\optionsec[standalone]{standalone} + +\glsxtrnote +This option is only available with the \gls{glossaries-extra} +extension package.\footnote{You can just use the base +\styfmt{glossaries} package for the first case, but it's less +convenient. You'd have to manually insert the entry target before +the sectioning command and use \ics{glsentryname}\marg{label} or +\ics{Glsentryname}\marg{label} to display the entry name.} Instead +of creating a list, this has standalone definitions throughout the +document. The entry name may or may not be in a section heading. + +You can either define entries in the document preamble (or in an external file loaded with +\ics{loadglsentries}), as with \opt5, for example: \begin{verbatim} \documentclass{article} -\usepackage[sort=none]{glossaries-extra} -\newglossaryentry{sample}{name={sample}, - description={an example}} -\begin{document} -\gls{sample}. -\printunsrtglossary -\end{document} -\end{verbatim} -See the \sty{glossaries-extra} documentation for -further details. -\section{Sample Documents} -\label{sec:samples} +\usepackage[colorlinks]{hyperref} +\usepackage[sort=none, + nostyles% <- no glossary styles are required + ]{glossaries-extra} -The \styfmt{glossaries} package is provided with some sample -documents that illustrate the various functions. These should -be located in the \texttt{samples} subdirectory (folder) of the -\styfmt{glossaries} documentation directory. This location varies -according to your operating system and \TeX\ distribution. You -can use \texttt{texdoc} to locate the main glossaries documentation. -For example, in a -\href{http://www.dickimaw-books.com/latex/novices/html/terminal.html}{terminal or command prompt}, type: -\begin{prompt} -texdoc -l glossaries -\end{prompt} -This should display a list of all the files in the glossaries -documentation directory with their full pathnames. (The GUI version -of \texttt{texdoc} may also provide you with the information.) +\newglossaryentry{set}{name={set}, + description={a collection of any kind of objects}, + symbol={\ensuremath{\mathcal{S}}} +} -If you can't find the sample files on your computer, they are also available -from your nearest CTAN mirror at -\url{http://mirror.ctan.org/macros/latex/contrib/glossaries/samples/}. +\newglossaryentry{function}{name={function}, + description={a rule that assigns every element in the + domain \gls{set} to an element in the range \gls{set}}, + symbol={\ensuremath{f(x)}} +} +\end{verbatim} +\begin{alltt} +\cs{newcommand}*\mgroup{\cs{termdef}}[1]\mgroup{\% + \cs{section}\mgroup{\ics*{glsxtrglossentry}\mgroup{\#1} \ics{glsentrysymbol}\mgroup{\#1}}\% + \cs{begin}\mgroup{quote}\cs{em}\ics{Glsentrydesc}\mgroup{\#1}.\cs{end}\mgroup{quote}\% +} +\end{alltt} +\begin{verbatim} +\begin{document} +\tableofcontents -The sample documents are listed below\footnote{Note that although I've written -\texttt{latex} in this section, it's better to use \texttt{pdflatex}, where -possible, for the reasons given \hyperlink{pdflatexnote}{earlier}.} -If you prefer to use UTF-8 aware engines (\texttt{xelatex} or -\texttt{lualatex}) remember that you'll need to switch from -\styfmt{fontenc} \& \styfmt{inputenc} to \styfmt{fontspec} where -appropriate. The \gls{glossaries-extra} package provides some -additional sample files. +\section{Introduction} +Sample document about \glspl{function} and \glspl{set}. -\begin{samplelist} -\exitem[minimal]{gls} This document is a -minimal working example. You can test your installation using this -file. To create the complete document you will need to do the -following steps: - \begin{enumerate} - \item Run \texttt{minimalgls.tex} through \LaTeX\ either by - typing -\begin{prompt} -latex minimalgls -\end{prompt} - in a terminal or by using the relevant button or menu item in - your text editor or front-end. This will create the required - associated files but you will not see the glossary. If you use - PDF\LaTeX\ you will also get warnings about non-existent - references that look something like: -\begin{verbatim} -pdfTeX warning (dest): name{glo:aca} has been -referenced but does not exist, -replaced by a fixed one -\end{verbatim} - These warnings may be ignored on the first run. +\termdef{set} - If you get a \verb"Missing \begin{document}" error, then - it's most likely that your version of \sty{xkeyval} is - out of date. Check the log file for a warning of that nature. - If this is the case, you will need to update the \styfmt{xkeyval} - package. +More detailed information about \glspl{set} with examples. - \item If you have Perl installed, run \gls{makeglossaries} on the document (\sectionref{sec:makeglossaries}). This can - be done on a terminal by typing -\begin{prompt} -makeglossaries minimalgls -\end{prompt} - otherwise do -\begin{prompt} -makeglossaries-lite minimalgls -\end{prompt} - If for some reason you want to call \gls{makeindex} explicitly, you can do this - in a terminal by typing (all on one line): -\begin{prompt} -makeindex -s minimalgls.ist -t minimalgls.glg -o minimalgls.gls minimalgls.glo -\end{prompt} - (See \sectionref{sec:makeindexapp} for further details on using - \gls*{makeindex} explicitly.) +\termdef{function} - Note that if the file name contains spaces, you will need to use - the double-quote character to delimit the name. +More detailed information about \glspl{function} with examples. - \item Run \texttt{minimalgls.tex} through \LaTeX\ again (as step~1) - \end{enumerate} -You should now have a complete document. The number following -each entry in the glossary is the location number. By default, this -is the page number where the entry was referenced. +\end{document} +\end{verbatim} +Or you can use \gls{bib2gls} if you want to manage a large +database of terms. For example (requires \gls{glossaries-extra} v1.42, see below): +\begin{alltt} +\cs{documentclass}\mgroup{article} -There are three other files that can be used as a -\href{http://www.dickimaw-books.com/latex/minexample/}{minimal working -example}: \texttt{mwe-gls.tex}, \texttt{mwe-acr.tex} and -\texttt{mwe-acr-desc.tex}. +\cs{usepackage}[colorlinks]\mgroup{hyperref} +\cs{usepackage}[\xtrfont{record}, + nostyles\% <- no glossary styles are required + ]\mgroup{glossaries-extra} -\exitem{-noidxapp} This document illustrates how to use the -\styfmt{glossaries} package without an external \gls{indexingapp} (\opt1). -To create the complete document, you need to do: -\begin{prompt} -latex sample-noidxapp -latex sample-noidxapp -\end{prompt} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=terms,\resourceopt{sort}=none,\resourceopt{save-locations}=false] -\exitem{-noidxapp-utf8} As the previous example, except that it uses -the \sty{inputenc} package. -To create the complete document, you need to do: -\begin{prompt} -latex sample-noidxapp-utf8 -latex sample-noidxapp-utf8 -\end{prompt} +\cs{newcommand}*\mgroup{\cs{termdef}}[1]\mgroup{\% + \cs{section}\mgroup{\ics*{glsxtrglossentry}\mgroup{\#1} \strong{\ics{glossentrysymbol}}\mgroup{\#1}}\% + \ics{glsadd}\mgroup{\#1}\% <- index this entry + \cs{begin}\mgroup{quote}\cs{em}\ics{Glsentrydesc}\mgroup{\#1}.\cs{end}\mgroup{quote}\% +} +\end{alltt} +\begin{verbatim} +\begin{document} +\tableofcontents -\exitem{4col} This document illustrates -a four column glossary where the entries have a symbol in addition -to the name and description. To create the complete document, you -need to do: -\begin{prompt} -latex sample4col -makeglossaries sample4col -latex sample4col -\end{prompt} -or -\begin{prompt} -latex sample4col -makeglossaries-lite sample4col -latex sample4col -\end{prompt} -The vertical gap between entries is the -gap created at the start of each group. This can be suppressed -using the \pkgopt{nogroupskip} package option. +\section{Introduction} +Sample document about \glspl{function} and \glspl{set}. -\exitem{Acr} This document has some -sample abbreviations. It also adds the glossary to the table of contents, -so an extra run through \LaTeX\ is required to ensure the document -is up to date: -\begin{prompt} -latex sampleAcr -makeglossaries sampleAcr -latex sampleAcr -latex sampleAcr -\end{prompt} -(or use \gls{makeglossaries-lite.lua}). +\termdef{set} -\exitem{AcrDesc} This is similar to -the previous example, except that the abbreviations have an associated -description. As with the previous example, the glossary is added to -the table of contents, so an extra run through \LaTeX\ is required: -\begin{prompt} -latex sampleAcrDesc -makeglossaries sampleAcrDesc -latex sampleAcrDesc -latex sampleAcrDesc -\end{prompt} +More detailed information about \glspl{set} with examples. -\exitem{Desc} This is similar to the -previous example, except that it defines the abbreviations using -\ics{newglossaryentry} instead of \ics{newacronym}. As with the -previous example, the glossary is added to the table of contents, so -an extra run through \LaTeX\ is required: -\begin{prompt} -latex sampleDesc -makeglossaries sampleDesc -latex sampleDesc -latex sampleDesc -\end{prompt} +\termdef{function} -\exitem{CustomAcr} This document has some sample abbreviations with a -custom acronym style. It also adds the glossary to the table of -contents, so an extra run through \LaTeX\ is required: -\begin{prompt} -latex sampleCustomAcr -makeglossaries sampleCustomAcr -latex sampleCustomAcr -latex sampleCustomAcr -\end{prompt} +More detailed information about \glspl{function} with examples. -\exitem{FnAcrDesc} This is similar to \samplefile{AcrDesc}, except that it -uses the \acrstyle{footnote-sc-desc} style. As with the previous example, -the glossary is added to the table of contents, so an extra run through -\LaTeX\ is required: +\end{document} +\end{verbatim} +Where the file \texttt{terms.bib} contains: +\begin{alltt} +\atentry{entry}\mgroup{set, + name=\mgroup{set}, + description=\mgroup{a collection of any kind of objects}, + symbol=\mgroup{\cs{ensuremath}\mgroup{\cs{mathcal}\mgroup{S}}} +} +\atentry{entry}\mgroup{function, + name=\mgroup{function}, + description=\mgroup{a rule that assigns every element in the domain + \cs{gls}\mgroup{set} to an element in the range \cs{gls}\mgroup{set}}, + symbol=\mgroup{\cs{ensuremath}\mgroup{f(x)}} +} +\end{alltt} +The advantage in this approach (with \ics{loadglsentries} or +\gls{bib2gls}) is that you can use an existing database of +entries shared across multiple documents, ensuring consistent +notation for all of them. + +In both cases, there's no need to load all the glossary styles +packages, as they're not required, so I've used the +\pkgopt{nostyles} package option to prevent them from being loaded. + +In the first case, you need the \pkgopt[none]{sort} package option +(as in \opt5) and then define the terms in the preamble. No external tool is +required. Just run \LaTeX\ as normal. (Twice to ensure that the +table of contents is up to date.) \begin{prompt} -latex sampleFnAcrDesc -makeglossaries sampleFnAcrDesc -latex sampleFnAcrDesc -latex sampleFnAcrDesc +pdflatex myDoc +pdflatex myDoc \end{prompt} -\exitem{-FnDesc} This example -defines a custom display format that puts the description in a -footnote on first use. -\begin{prompt} -latex sample-FnDesc -makeglossaries sample-FnDesc -latex sample-FnDesc -\end{prompt} +In the second case, you need the \pkgopt*{record} package +option (as in \opt4) since \gls{bib2gls} is needed to select the +required entries, but you don't need a sorted list: +\begin{alltt} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=\mgroup{terms},\strong{\xtrfont{sort}=none}] +\end{alltt} +This will ensure that any entries indexed in the document (through +commands like \ics{gls} or \ics{glsadd}) will be selected by +\gls{bib2gls}, but it will skip the sorting step. +(The chances are you probably also won't need location lists either. +If so, you can add the option \resourceopt[false]{save-locations}.) -\exitem{-custom-acronym} -This document illustrates how to define your own acronym style if -the predefined styles don't suit your requirements. +Remember that for this second case you need to run \gls{bib2gls} as per \opt4: \begin{prompt} -latex sample-custom-acronym -makeglossaries sample-custom-acronym -latex sample-custom-acronym +pdflatex myDoc +bib2gls myDoc +pdflatex myDoc +pdflatex myDoc \end{prompt} -\exitem{-crossref} -This document illustrates how to cross-reference entries in the -glossary. -\begin{prompt} -latex sample-crossref -makeglossaries sample-crossref -latex sample-crossref -\end{prompt} +For both cases (with or without \gls{bib2gls}), instead of listing +all the entries using \xtrcs{printunsrtglossary}, you use +\ics*{glsxtrglossentry}\marg{label} where you want the name (and +anchor with \sty{hyperref}) to appear in the document. This will +allow the \gls{linktext} created by commands like \cs{gls} to link +to that point in the document. The description can simply be +displayed with \ics{glsentrydesc}\marg{label} or +\ics{Glsentrydesc}\marg{label}, as in the above examples. In both +examples, I've defined a custom command \cs{termdef} to simplify the +code and ensure consistency. Extra styling, such as placing the +description in a coloured frame, can be added to this custom +definition as required. + +(Instead of using \cs{glsentrydesc} or \cs{Glsentrydesc}, you can use +\ics{glossentrydesc}\marg{label}, which will obey attributes such as +\attr{glossdesc} and \attr{glossdescfont}. See the \gls{glossaries-extra} +manual for further details.) -\exitem{-dot-abbr} This document illustrates how to use the -post link hook to adjust the space factor after abbreviations. -\begin{prompt} -latex sample-dot-abbr -makeglossaries sampledot-abbrf -latex sample-dot-abbr -\end{prompt} +The symbol (if required) can be displayed with either +\ics{glsentrysymbol}\marg{label} or \ics{glossentrysymbol}\marg{label}. +In the first example, I've used \cs{glsentrysymbol}. In the +second I've used \ics{glossentrysymbol}. The latter is +necessary with \gls{bib2gls} if the symbol needs to go in a +section title as the entries aren't defined on the first \LaTeX\ run. + +In normal document text, \cs{glsentrysymbol} will silently do nothing +if the entry hasn't been defined, but when used in a section heading +it will expand to an undefined internal command when written to the +\filetype{aux} file, which triggers an error. + +The \ics{glossentrysymbol} command performs an existence check, +which triggers a warning if the entry is undefined. (All entries +will be undefined before the first \gls{bib2gls} call.) You need at +least \gls{glossaries-extra} v1.42 to use this command in a section +title.\footnote{\cs{glossentrysymbol} is defined by the base +\styfmt{glossaries} package but is redefined by +\gls{glossaries-extra}.} If \sty{hyperref} has been loaded, this +will use \ics{texorpdfstring} to allow a simple expansion for the +PDF bookmarks (see the \gls{glossaries-extra} user manual for +further details). -\exitem{DB} This document illustrates how -to load external files containing the glossary definitions. It also -illustrates how to define a new glossary type. This document has the -\gls{numberlist} suppressed and uses \ics{glsaddall} to add all -the entries to the glossaries without referencing each one -explicitly. To create the document do: -\begin{prompt} -latex sampleDB -makeglossaries sampleDB -latex sampleDB -\end{prompt} -or -\begin{prompt} -latex sampleDB -makeglossaries-lite sampleDB -latex sampleDB -\end{prompt} -The glossary definitions are stored in the accompanying files -\texttt{database1.tex} and \texttt{database2.tex}. If for some -reason you want to call \gls{makeindex} explicitly you must -have a separate call for each glossary: -\begin{enumerate} -\item Create the main glossary (all on one line): -\begin{prompt}\raggedright -makeindex -s sampleDB.ist -t sampleDB.glg -o sampleDB.gls sampleDB.glo -\end{prompt} -\item Create the secondary glossary (all on one line): -\begin{prompt}\raggedright -makeindex -s sampleDB.ist -t sampleDB.nlg -o sampleDB.not sampleDB.ntn -\end{prompt} -Note that both \gls{makeglossaries} and \gls{makeglossaries-lite.lua} do -this all in one call, so they not only make it easier because you -don't need to supply all the switches and remember all the -extensions but they also call \gls{makeindex} the appropriate number of times. -\end{enumerate} +If you want to test if the \gloskey{symbol} field has been set, you +need to use \ics{ifglshassymbol} outside of the section title. For +example: +\begin{alltt} +\cs{ifglshassymbol}\mgroup{\#1}\% +\mgroup{\cs{section}\mgroup{\xtrcs{glsxtrglossentry}\mgroup{\#1} \cs{glossentrysymbol}\mgroup{\#1}}} +\mgroup{\cs{section}\mgroup{\xtrcs{glsxtrglossentry}\mgroup{\#1}}} +\end{alltt} -\exitem{Eq} This document illustrates how -to change the location to something other than the page number. In -this case, the \texttt{equation} counter is used since all glossary -entries appear inside an \env{equation} environment. To create -the document do: -\begin{prompt} -latex sampleEq -makeglossaries sampleEq -latex sampleEq -\end{prompt} +In both of the above examples, the section titles start with a lowercase +character (because the \gloskey{name} value is all lowercase in +entry definitions). You can apply automatic case-change with the +\attr{glossname} attribute. For example: +\begin{alltt} +\ics*{glssetcategoryattribute}\mgroup{general}\mgroup{glossname}\mgroup{firstuc} +\end{alltt} +or (for title-case) +\begin{alltt} +\ics*{glssetcategoryattribute}\mgroup{general}\mgroup{glossname}\mgroup{title} +\end{alltt} +However, this won't apply the case-change in the table of contents +or bookmarks. -\exitem{EqPg} This is similar to the -previous example, but the \glspl{numberlist} are a -mixture of page numbers and equation numbers. This example adds the -glossary to the table of contents, so an extra \LaTeX\ run is -required: -\begin{prompt} -latex sampleEqPg -makeglossaries sampleEqPg -latex sampleEqPg -latex sampleEqPg -\end{prompt} +In the second example, you can instead use \gls{bib2gls} to apply a +case-change: +\begin{alltt} +\cs{GlsXtrLoadResources}[\resourceopt{src}=terms, + \resourceopt{sort}=none,\resourceopt{save-locations}=false\strong{, + \resourceopt{replicate-fields}=\mgroup{name=text}, + \xtrfont{name-case-change}=firstuc} +] +\end{alltt} +(Or \resourceopt[title]{name-case-change} for title-case.) +This copies the \gloskey{name} value to the \gloskey{text} field and +then applies a case-change to the \gloskey{name} field (leaving the +\gloskey{text} field unchanged). The name in the section titles now +starts with a capital but the \gls{linktext} produced by commands like +\ics{gls} is still lowercase. + +In the first example (without \gls{bib2gls}) you need to do this +manually. For example: +\begin{alltt} +\cs{newglossaryentry}\mgroup{set}\mgroup{name=\mgroup{\strong{S}et},\strong{text=\mgroup{set}}, + description=\mgroup{a collection of any kind of objects}, + symbol=\mgroup{\cs{ensuremath}\mgroup{\cs{mathcal}\mgroup{S}}} +} +\end{alltt} -\exitem{Sec} This document also -illustrates how to change the location to something other than the -page number. In this case, the \texttt{section} counter is used. -This example adds the glossary to the table of contents, so an extra -\LaTeX\ run is required: +Note that if you use the default \resourceopt[true]{save-locations} +with \gls{bib2gls}, it's possible to combine \optsand46 to have both standalone +definitions and an index. Now I do need a glossary style. In this +case I'm going to use \xtrglostyle{bookindex}, which is provided in +the \sty{glossary-bookindex} package (bundled with +\gls{glossaries-extra}). I don't need any of the other style +packages, so I can still keep the \pkgopt{nostyles} option and just +load \sty{glossary-bookindex}: +\begin{alltt} +\cs{usepackage}[\xtrfont{record=nameref},\% <- using bib2gls + nostyles,\% <- don't load default style packages + \xtrfont{stylemods=bookindex},\% <- load glossary-bookindex.sty + style=\xtrfont{bookindex}\% <- set the default style to 'bookindex' +]\mgroup{glossaries-extra} +\end{alltt} +I also need to sort the entries, so the resource command is now: +\begin{alltt} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=terms,\% definitions in terms.bib + \resourceopt{sort}=en-GB,\% sort by this locale + \resourceopt{replicate-fields}=\mgroup{name=text}, + \xtrfont{name-case-change}=\mgroup{firstuc} +] +\end{alltt} +At the end of the document, I can add the glossary: +\begin{alltt} +\ics*{printunsrtglossary}[title=Index,target=false] +\end{alltt} +Note that I've had to switch off the hypertargets with +\xtrprintglosskey[false]{target} (otherwise there would be duplicate +targets). If you want letter group headings you need to use the +\bibglslongopt{group} switch: \begin{prompt} -latex sampleSec -makeglossaries sampleSec -latex sampleSec -latex sampleSec +bib2gls -{}-group myDoc \end{prompt} +or if you are using \app{arara}: +\begin{alltt} +\% arara: bib2gls: \mgroup{ group: on } +\end{alltt} -\exitem{Ntn} This document illustrates -how to create an additional glossary type. This example adds the -glossary to the table of contents, so an extra \LaTeX\ run is -required: -\begin{prompt} -latex sampleNtn -makeglossaries sampleNtn -latex sampleNtn -latex sampleNtn -\end{prompt} -Note that if you want to call \gls{makeindex} explicitly instead of -using \gls{makeglossaries} or \gls{makeglossaries-lite.lua} then you -need to call \gls{makeindex} twice: -\begin{enumerate} -\item Create the main glossary (all on one line): -\begin{prompt}\raggedright -makeindex -s sampleNtn.ist -t sampleNtn.glg -o sampleNtn.gls sampleNtn.glo -\end{prompt} -\item Create the secondary glossary (all on one line): -\begin{prompt}\raggedright -makeindex -s sampleNtn.ist -t sampleNtn.nlg -o sampleNtn.not sampleNtn.ntn -\end{prompt} -\end{enumerate} +The \xtrglostyle{bookindex} style doesn't show the +description, so only the name and location is displayed. Remember +that the name has had a case-conversion so it now starts with an +initial capital. If you feel this is inappropriate for the index, +you can adjust the \xtrglostyle{bookindex} style so that it uses +the \gloskey{text} field instead. For example: +\begin{alltt} +\cs{renewcommand}*\mgroup{\ics*{glsxtrbookindexname}}[1]\mgroup{\% + \ics*{glossentrynameother}\mgroup{\#1}\mgroup{text}} +\end{alltt} +See the \gls{glossaries-extra} user manual for further details about +this style. -\exitem{} This document illustrates some of -the basics, including how to create child entries that use the same -name as the parent entry. This example adds the glossary to the -table of contents and it also uses \ics{glsrefentry}, so an extra \LaTeX\ -run is required: -\begin{prompt} -latex sample -makeglossaries sample -latex sample -latex sample -\end{prompt} -You can see the difference between word and letter ordering if you -substitute \pkgopt[word]{order} with \pkgopt[letter]{order}. (Note -that this will only have an effect if you use -\gls{makeglossaries} or \gls{makeglossaries-lite.lua}. -If you use \gls{makeindex} explicitly, you will need to use the -\mkidxopt{l} switch to indicate letter ordering.) +Note that on the first \LaTeX\ run none of the entries will be +defined. Once they are defined, the page numbers may shift due to +the increased amount of document text. You may therefore need to +repeat the document build to ensure the page numbers are correct. -\exitem{-inline} This document is -like \texttt{sample.tex}, above, but uses the \glostyle{inline} -glossary style to put the glossary in a footnote. +If there are extra terms that need to be included in the index that +don't have a description, you can define them with \atentry{index} +in the \filetype{bib} file. For example: +\begin{alltt} +\atentry{index}\mgroup{element} +\atentry{index}\mgroup{member,\xtrgloskey{alias}=\mgroup{element}} +\end{alltt} +They can be used in the document as usual: +\begin{verbatim} +The objects that make up a set are the \glspl{element} +or \glspl{member}. +\end{verbatim} +See \bibglsbegin\ or the \gls{bib2gls} user manual for further +details. -\exitem{tree} This document illustrates -a hierarchical glossary structure where child entries have different -names to their corresponding parent entry. To create the document -do: -\begin{prompt} -latex sampletree -makeglossaries sampletree -latex sampletree -\end{prompt} +The \styfmt{glossaries} package comes with a number of sample +documents that illustrate the various functions. These are listed in +\sectionref{sec:samples}. -\exitem{-dual} This document -illustrates how to define an entry that both appears in the list of -acronyms and in the main glossary. To create the document do: -\begin{prompt} -latex sample-dual -makeglossaries sample-dual -latex sample-dual -\end{prompt} +\section{Dummy Entries for Testing} +\label{sec:lipsum} -\exitem{-langdict} This document -illustrates how to use the glossaries package to create English -to French and French to English dictionaries. To create the document -do: -\begin{prompt} -latex sample-langdict -makeglossaries sample-langdict -latex sample-langdict -\end{prompt} +In addition to the sample files described above, \sty{glossaries} +also provides some files containing lorum ipsum dummy entries. These +are provided for testing purposes and are on \TeX's path (in +\texttt{tex\slash latex\slash glossaries\slash test-entries}) so +they can be included via \ics{input} or \ics{loadglsentries}. The +\gls{glossaries-extra} package provides \filetype{bib} versions of +all these files for use with \gls{bib2gls}. The files are as +follows: -\exitem{xdy} This document illustrates -how to use the \styfmt{glossaries} package with \gls{xindy} instead -of \gls{makeindex}. The document uses UTF8 encoding (with the -\sty{inputenc} package). The encoding is picked up by -\gls{makeglossaries}. By default, this document will create a -\gls{xindy} style file called \texttt{samplexdy.xdy}, but if you -uncomment the lines +\begin{description} +\item[example-glossaries-brief.tex] These entries all have brief +descriptions. For example: \begin{verbatim} -\setStyleFile{samplexdy-mc} -\noist -\GlsSetXdyLanguage{} +\newglossaryentry{lorem}{name={lorem},description={ipsum}} \end{verbatim} -it will set the style file to \texttt{samplexdy-mc.xdy} instead. -This provides an additional letter group for entries starting with -\qt{Mc} or \qt{Mac}. If you use \gls{makeglossaries} or -\gls{makeglossaries-lite.lua}, you don't -need to supply any additional information. If you don't use -\gls*{makeglossaries}, you will need to specify the required -information. Note that if you set the style file to -\texttt{samplexdy-mc.xdy} you must also specify \ics{noist}, -otherwise the \styfmt{glossaries} package will overwrite -\texttt{samplexdy-mc.xdy} and you will lose the \qt{Mc} letter -group. - -To create the document do: -\begin{prompt} -latex samplexdy -makeglossaries samplexdy -latex samplexdy -\end{prompt} -If you don't have Perl installed then you can't use -\gls{makeglossaries}, but you also can't use \gls{xindy}! -However, if for some reason you want to call -\gls{xindy} explicitly instead of using \gls{makeglossaries} (or -\gls{makeglossaries-lite.lua}): -\begin{itemize} -\item if you are using the default style file \texttt{samplexdy.xdy}, then -do (no line breaks): -\begin{prompt}\raggedright -xindy -L english -C utf8 -I xindy -M samplexdy -t samplexdy.glg -o samplexdy.gls samplexdy.glo -\end{prompt} -\item if you are using \texttt{samplexdy-mc.xdy}, then do -(no line breaks): -\begin{prompt}\raggedright -xindy -I xindy -M samplexdy-mc -t samplexdy.glg -o samplexdy.gls samplexdy.glo -\end{prompt} -\end{itemize} -\exitem{xdy2} This document illustrates -how to use the \styfmt{glossaries} package where the location -numbers don't follow a standard format. This example will only work -with \gls{xindy}. To create the document do: -\begin{prompt} -pdflatex samplexdy2 -makeglossaries samplexdy2 -pdflatex samplexdy2 -\end{prompt} -The explicit \gls{xindy} call is: -\begin{prompt}\raggedright -xindy -L english -C utf8 -I xindy -M samplexdy2 -t samplexdy2.glg -o samplexdy2.gls samplexdy2.glo -\end{prompt} -See \sectionref{sec:xindyloc} for further details. +\item[example-glossaries-long.tex] These entries all have long +descriptions. For example: +\begin{verbatim} +\newglossaryentry{loremipsum}{name={lorem ipsum}, +description={dolor sit amet, consectetuer adipiscing +elit. Ut purus elit, vestibulum ut, placerat ac, +adipiscing vitae, felis. Curabitur dictum gravida +mauris.}} +\end{verbatim} -\exitem{xdy3} This document is like \samplefile{xdy} but uses the -command \cs{Numberstring} from the \sty{fmtcount} package to -format the page numbers. +\item[example-glossaries-multipar.tex] These entries all have +multi-paragraph descriptions. For example: +\begin{verbatim} +\longnewglossaryentry{loremi-ii}{name={lorem 1--2}}% +{% +Lorem ipsum ... -\exitem{utf8} This is another example -that uses \gls{xindy}. Unlike \gls{makeindex}, -\gls{xindy} can cope with \glspl{nonlatinchar}. This -document uses UTF8 encoding. To create the document do: -\begin{prompt} -latex sampleutf8 -makeglossaries sampleutf8 -latex sampleutf8 -\end{prompt} -The explicit \gls{xindy} call is -(no line breaks): -\begin{prompt}\raggedright -xindy -L english -C utf8 -I xindy -M sampleutf8 -t sampleutf8.glg -o sampleutf8.gls sampleutf8.glo -\end{prompt} +Nam dui ligula... +} +\end{verbatim} -If you remove the \pkgopt{xindy} option from \texttt{sampleutf8.tex} -and do: -\begin{prompt} -latex sampleutf8 -makeglossaries sampleutf8 -latex sampleutf8 -\end{prompt} -or -\begin{prompt} -latex sampleutf8 -makeglossaries-lite sampleutf8 -latex sampleutf8 -\end{prompt} -you will see that the entries that start with an \gls{exlatinchar} -now appear in the symbols group, and the word \qt{man\oe uvre} is now -after \qt{manor} instead of before it. If you want to explicitly -call \gls{makeindex} (no line breaks): -\begin{prompt}\raggedright -makeindex -s sampleutf8.ist -t sampleutf8.glg -o sampleutf8.gls sampleutf8.glo -\end{prompt} +\item[example-glossaries-symbols.tex] These entries all use the +\gloskey{symbol} key. For example: +\begin{verbatim} +\newglossaryentry{alpha}{name={alpha}, +symbol={\ensuremath{\alpha}}, +description={Quisque ullamcorper placerat ipsum.}} +\end{verbatim} -\exitem{-index} This document uses -the \styfmt{glossaries} package to create both a glossary and an -index. This requires two \gls{makeglossaries} (or -\gls{makeglossaries-lite.lua}) calls to ensure the -document is up to date: -\begin{prompt} -latex sample-index -makeglossaries sample-index -latex sample-index -makeglossaries sample-index -latex sample-index -\end{prompt} +\item[example-glossaries-symbolnames.tex] Similar to the previous +file but the \gloskey{symbol} key isn't used. Instead the symbol +is stored in the \gloskey{name} key. For example: +\begin{verbatim} +\newglossaryentry{sym.alpha}{sort={alpha}, +name={\ensuremath{\alpha}}, +description={Quisque ullamcorper placerat ipsum.}} +\end{verbatim} -\exitem{-newkeys} This document illustrates how add custom keys -(using \cs{glsaddkey}). +\item[example-glossaries-images.tex] These entries use the +\gloskey{user1} key to store the name of an image file. (The images +are provided by the \sty{mwe} package and should be on \TeX's path.) +One entry doesn't have an associated image to help test for a~missing key. +The descriptions are long to allow for tests with the text wrapping +around the image. For example: +\begin{verbatim} +\longnewglossaryentry{sedfeugiat}{name={sed feugiat}, +user1={example-image}}% +{% +Cum sociis natoque... -\exitem{-storage-abbr} This document illustrates how add custom -storage keys (using \cs{glsaddstoragekey}). - -\exitem{-storage-abbr-desc} An extension of the previous example -where the user needs to provide a~description. - -\exitem{-chap-hyperfirst} This document illustrates how to add -a~custom key using \cs{glsaddstoragekey} and hook into the \glslike\ -and \glstextlike\ mechanism used to determine whether or not to -hyperlink an entry. - -\exitem{-font-abbr} This document illustrates how to different fonts -for abbreviations within the style. - -\exitem{-numberlist} This document illustrates how to reference the -\gls{numberlist} in the document text. This requires an additional -\LaTeX\ run: -\begin{prompt} -latex sample-numberlist -makeglossaries sample-numberlist -latex sample-numberlist -latex sample-numberlist -\end{prompt} - -\exitem{People} This document illustrates how you can hook into the -standard sort mechanism to adjust the way the sort key is set. This -requires an additional run to ensure the table of contents is -up-to-date: -\begin{prompt} -latex samplePeople -makeglossaries samplePeople -latex samplePeople -latex samplePeople -\end{prompt} - -\exitem{Sort} This is another document that illustrates how to hook -into the standard sort mechanism. An additional run is required to -ensure the table of contents is up-to-date: -\begin{prompt} -latex sampleSort -makeglossaries sampleSort -latex sampleSort -latex sampleSort -\end{prompt} - -\exitem{-nomathhyper} This document illustrates how to selectively -enable and disable entry hyperlinks in \ics{glsentryfmt}. - -\exitem{-entryfmt} This document illustrates how to change the -way an entry is displayed in the text. - -\exitem{-prefix} This document illustrates the use of the -\sty{glossaries-prefix} package. An additional run is required to -ensure the table of contents is up-to-date: -\begin{prompt} -latex sample-prefix -makeglossaries sample-prefix -latex sample-prefix -latex sample-prefix -\end{prompt} - -\exitem{accsupp} This document -uses the experimental \sty{glossaries-accsupp} package. The -symbol is set to the replacement text. Note that some PDF -viewers don't use the accessibility support. Information -about the \styfmt{glossaries-accsupp} package can be found in -\sectionref{sec:accsupp}. - -\exitem{-ignored} This document defines an ignored glossary for -common terms that don't need a definition. - -\exitem{-entrycount} This document uses \ics{glsenableentrycount} -and \ics{cgls} (described in \sectionref{sec:enableentrycount}) -so that acronyms only used once don't appear in the list of -acronyms. -\end{samplelist} - -\section{Dummy Entries for Testing} -\label{sec:lipsum} - -In addition to the sample files described above, \sty{glossaries} also provides -some files containing lorum ipsum dummy entries. These are provided -for testing purposes and are on \TeX's path (in -\texttt{tex\slash latex\slash glossaries\slash test-entries}) so they can be included -via \ics{input} or \ics{loadglsentries}. The files are as follows: -\begin{description} -\item[example-glossaries-brief.tex] These entries all have brief -descriptions. For example: -\begin{verbatim} -\newglossaryentry{lorem}{name={lorem},description={ipsum}} -\end{verbatim} - -\item[example-glossaries-long.tex] These entries all have long -descriptions. For example: -\begin{verbatim} -\newglossaryentry{loremipsum}{name={lorem ipsum}, -description={dolor sit amet, consectetuer adipiscing -elit. Ut purus elit, vestibulum ut, placerat ac, -adipiscing vitae, felis. Curabitur dictum gravida -mauris.}} -\end{verbatim} - -\item[example-glossaries-multipar.tex] These entries all have -multi-paragraph descriptions. - -\item[example-glossaries-symbols.tex] These entries all use the -\gloskey{symbol} key. For example: -\begin{verbatim} -\newglossaryentry{alpha}{name={alpha}, -symbol={\ensuremath{\alpha}}, -description={Quisque ullamcorper placerat ipsum.}} -\end{verbatim} - -\item[example-glossaries-symbolnames.tex] Similar to the previous -file but the \gloskey{symbol} key isn't used. Instead the symbol -is stored in the \gloskey{name} key. For example: -\begin{verbatim} -\newglossaryentry{sym.alpha}{sort={alpha}, -name={\ensuremath{\alpha}}, -description={Quisque ullamcorper placerat ipsum.}} +Etiam... +} \end{verbatim} -\item[example-glossaries-images.tex] These entries use the -\gloskey{user1} key to store the name of an image file. (The images -are provided by the \sty{mwe} package and should be on \TeX's path.) -One entry doesn't have an associated image to help test for a~missing key. - \item[example-glossaries-acronym.tex] These entries are all abbreviations. For example: \begin{verbatim} \newacronym[type=\glsdefaulttype]{lid}{LID}{lorem ipsum dolor} \end{verbatim} +\begin{xtr} +If you use the \gls{glossaries-extra} extension package, then +\ics{newacronym} is redefined to use \ics*{newabbreviation} +with the \xtrgloskey{category} key set to \texttt{acronym} (rather +than the default \texttt{abbreviation}). This means that you need to +set the abbreviation style for the \texttt{acronym} category. For +example: +\begin{verbatim} +\setabbreviationstyle[acronym]{long-short} +\end{verbatim} +\end{xtr} -\item[example-glossaries-acronym-desc.tex] These entries are all +\item[example-glossaries-acronym-desc.tex] This file contains +entries that are all abbreviations that use the \gloskey{description} key. For example: \begin{verbatim} @@ -1959,6 +2225,17 @@ For example: description={fringilla a, euismod sodales, sollicitudin vel, wisi}]{ndl}{NDL}{nam dui ligula} \end{verbatim} +\begin{xtr} +If you use the \gls{glossaries-extra} extension package, then +\ics{newacronym} is redefined to use \ics*{newabbreviation} +with the \xtrgloskey{category} key set to \texttt{acronym} (rather +than the default \texttt{abbreviation}). This means that you need to +set the abbreviation style for the \texttt{acronym} category. For +example: +\begin{verbatim} +\setabbreviationstyle[acronym]{long-short-desc} +\end{verbatim} +\end{xtr} \item[example-glossaries-acronyms-lang.tex] These entries are all abbreviations, where some of them have a~translation supplied in the @@ -1968,6 +2245,17 @@ For example: \newacronym[type=\glsdefaulttype,user1={love itself}] {li}{LI}{lorem ipsum} \end{verbatim} +\begin{xtr} +If you use the \gls{glossaries-extra} extension package, then +\ics{newacronym} is redefined to use \ics*{newabbreviation} +with the \xtrgloskey{category} key set to \texttt{acronym} (rather +than the default \texttt{abbreviation}). This means that you need to +set the abbreviation style for the \texttt{acronym} category. For +example: +\begin{verbatim} +\setabbreviationstyle[acronym]{long-short-user} +\end{verbatim} +\end{xtr} \item[example-glossaries-parent.tex] These are hierarchical entries where the child entries use the \gloskey{name} key. @@ -1986,6 +2274,9 @@ For example: \begin{verbatim} \newglossaryentry{scelerisque}{name={scelerisque}, description={at}} + +\newglossaryentry{vestibulum}{parent={scelerisque}, + description={eu, nulla}} \end{verbatim} \item[example-glossaries-cite.tex] These entries use the @@ -2010,22 +2301,52 @@ For example: \end{verbatim} \end{description} -The sample file \texttt{glossary-lipsum-examples.tex} in the +The sample file \mirrorsamplefile{glossary-lipsum-examples.tex} in the \texttt{doc\slash latex\slash glossaries\slash samples} directory -uses all these files. See also -\url{http://www.dickimaw-books.com/gallery/#glossaries}. -The \sty{glossaries-extra} package provides additional test files. +uses all these files. See also \gallerytopic{glossaries}. + +\glsxtrnote +The \gls{glossaries-extra} package provides the additional test +file: +\begin{description} +\item[example-glossaries-xr.tex] These entries use the \gloskey{see} +key provided by the base \styfmt{glossaries} package and also the +\xtrgloskey{alias} and \xtrgloskey{seealso} keys that require +\gls{glossaries-extra}. For example: +\begin{verbatim} +\newglossaryentry{alias-lorem}{name={alias-lorem}, + description={ipsum},alias={lorem}} + +\newglossaryentry{amet}{name={amet},description={consectetuer}, + see={dolor}} + +\newglossaryentry{arcu}{name={arcu},description={libero}, + seealso={placerat,vitae,curabitur}} +\end{verbatim} +\end{description} \section{Multi-Lingual Support} \label{sec:languages} +\begin{important} +The \styfmt{glossaries} package uses the \styfmt{tracklang} package +to determine the document languages. Unfortunately, because there +isn't a standard language identification framework provided with +\LaTeX, \styfmt{tracklang} isn't always able to detect the selected +languages either as a result of using an unknown interface or where +the interface doesn't provide a way of detecting the language. +See +\href{https://www.dickimaw-books.com/latex/tracklang/}{Localisation +with \texttt{tracklang.tex}} for further details. +\end{important} + As from version 1.17, the \styfmt{glossaries} package can be used with \gls{xindy} as well as \gls{makeindex}. If you are writing in a language that uses an \gls{exlatinalph} or \gls{nonlatinalph} it's best to use \opt3 (\gls*{xindy}) or \opt4 (\gls{bib2gls}) as \gls*{makeindex} (\opt2) is hard-coded for the non-extended -\gls{latinalph} and \opt1 can performed limited ASCII comparisons. +\gls{latinalph} and \opt1 can only perform limited ASCII comparisons. This means that with \optsor34 you are not restricted to the A, \ldots, Z letter groups. If you want to use \gls*{xindy}, remember @@ -2038,13 +2359,13 @@ to use the \pkgopt{xindy} package option. For example: \usepackage[xindy]{glossaries} \end{verbatim} If you want to use \gls*{bib2gls}, you need to use the -\pkgopt{record} option with \sty{glossaries-extra} and supply the -definitions in \texttt{.bib} files. (See the \gls{bib2gls} user +\pkgopt*{record} option with \gls{glossaries-extra} and supply the +definitions in \filetype{bib} files. (See the \gls{bib2gls} user manual for further details.) \begin{important} Note that although a~\gls{nonlatinchar}, such as \'e, looks like a plain -character in your \filetype{.tex} file, with standard \LaTeX\ it's actually a~macro and can therefore +character in your \filetype{tex} file, with standard \LaTeX\ it's actually a~macro and can therefore cause expansion problems. You may need to switch off the field expansions with \cs{glsnoexpandfields}. This issue doesn't occur with \XeLaTeX\ or Lua\LaTeX. @@ -2055,17 +2376,15 @@ character at the start of an entry name, you must place it in a group, or it will cause a problem for commands that convert the first letter to upper case (e.g.\ \ics{Gls}). For example: \begin{alltt} -\verb|\newglossaryentry}{elite}{name={{|\'e\verb|}lite},| -description=\verb|{select group or class}}| +\cs{newglossaryentry}\mgroup{elite}\mgroup{name=\mgroup{\mgroup{\'e}lite}, +description=\mgroup{select group or class}} \end{alltt} -(With newer versions of \sty{mfirstuc} and \sty{datatool-base} you -may be able to omit this grouping.) For further details, see the \qt{UTF-8} section in the \sty{mfirstuc} user manual. If you are using \gls{xindy} or \gls{bib2gls}, the application needs -to know the encoding of the \filetype{.tex} file. This information -is added to the \filetype{.aux} file and can be picked up by +to know the encoding of the \filetype{tex} file. This information +is added to the \filetype{aux} file and can be picked up by \gls{makeglossaries} and \gls{bib2gls}. If you use \gls{xindy} explicitly instead of via \gls*{makeglossaries}, you may need to specify the encoding using the \xdyopt{C} @@ -2073,7 +2392,8 @@ option. Read the \gls*{xindy} manual for further details of this option. As from v4.24, if you are writing in German (for example, using the \sty{ngerman} -package\footnote{deprecated, use \styfmt{babel} instead} or \sty{babel} with the \pkgopt{ngerman} package option), +package\footnote{deprecated, use \styfmt{babel} instead} or +\sty{babel} with the \pkgoptfmt{ngerman} package option), and you want to use \gls{makeindex}['s] \mkidxopt{g} option, you'll need to change \gls{makeindex}['s] quote character using: \begin{definition}[\DescribeMacro\GlsSetQuote] @@ -2126,8 +2446,8 @@ in entry definitions. For example: \end{verbatim} The \sty{ngerman} package has the shorthands on in the preamble, so -they can be used if \cs{GlsSetQuote} has changed the \gls{makeindex} -quote character. Example: +they can be used in definitions if \cs{GlsSetQuote} has been used to +change the \gls{makeindex} quote character. Example: \begin{verbatim} \documentclass{article} @@ -2156,7 +2476,7 @@ The fixed names are produced using the commands listed in package such as \sty{babel} or \sty{polyglossia} that uses caption hooks, you can just redefine these commands as appropriate. If you are using \sty{babel} or \sty{polyglossia}, you need to use their -caption hooks to change the defaults. See \urlref{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=latexwords}{changing +caption hooks to change the defaults. See \href{https://texfaq.org/FAQ-latexwords}{changing the words babel uses} or read the \sty{babel} or \sty{polyglossia} documentation. If you have loaded \sty{babel}, then \sty{glossaries} will attempt to load \sty{translator}, unless you have used the @@ -2239,7 +2559,9 @@ Examples of use: \usepackage{babel} \usepackage[translate=babel]{glossaries} \end{verbatim} -(\sty{translator} isn't loaded). +(\sty{translator} isn't loaded). The \gls{glossaries-extra} package +has \pkgopt[babel]{translate} as the default if \sty{babel} has been +loaded. \item Using \sty{polyglossia}: \begin{verbatim} @@ -2254,7 +2576,7 @@ Examples of use: Due to the varied nature of glossaries, it's likely that the predefined translations may not be appropriate. If you are using the \sty{babel} package and the \styfmt{glossaries} package option \pkgopt[babel]{translate}, you need to be familiar with the advice given in -\urlref{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=latexwords}{changing +\href{https://texfaq.org/FAQ-latexwords}{changing the words babel uses}. If you are using the \sty{translator} package, then you can provide your own dictionary with the necessary modifications (using \cs{deftranslation}) and load it using @@ -2326,8 +2648,8 @@ to create a new language module, you should first read the \sty{tracklang} documentation. To create a new language module, you need to at least create two -files: \texttt{glossaries-}\meta{lang}\texttt{.ldf} and -\texttt{glossaries-dictionary-}\meta{Lang}\texttt{.dict} where +files called: \texttt{glossaries\dhyphen}\meta{lang}\texttt{.}\filetype{ldf} and +\texttt{glossaries-dictionary-}\meta{Lang}\texttt{.}\filetype{dict} where \meta{lang} is the root language name (for example, \texttt{english}) and \meta{Lang} is the language name used by \sty{translator} (for example, \texttt{English}). @@ -2348,7 +2670,7 @@ Here's an example of \texttt{glossaries-dictionary-English.dict}: You can use this as a template for your dictionary file. Change \texttt{English} to the \sty{translator} name for your language (so that it matches the file name -\texttt{glossaries-dictionary-}\meta{Lang}\texttt{.dict}) +\texttt{glossaries\dhyphen dictionary\dhyphen }\meta{Lang}\texttt{.dict}) and, for each \cs{providetranslation}, change the second argument to the appropriate translation. @@ -2419,21 +2741,22 @@ definition of \cs{glossariescaptions}\meta{lang}, replace the English text (such as \qt{Glossaries}) with the appropriate translation. +\importantpar \label{pluralsuffix}% -\textbf{Note:} the suffixes used to generate the plural forms when -the plural hasn't been specified are given by -\cs{glspluralsuffix} (for general entries) and -\cs{glsupacrpluralsuffix} for acronyms where the suffix needs to be -set using \cs{glstextup} to counteract the effects of \cs{textsc} -and \cs{glsacrpluralsuffix} for other acronym styles. There's no -guarantee when these commands will be expanded. They may be expanded -on definition or they may be expanded on use, depending on the -\styfmt{glossaries} configuration. +The suffixes used to generate the plural forms when the plural +hasn't been specified are given by \cs{glspluralsuffix} (for general +entries). For abbreviations defined with \cs{newacronym}, +\cs{glsupacrpluralsuffix} is used for acronyms where the suffix +needs to be set using \cs{glstextup} to counteract the effects of +\cs{textsc} and \cs{glsacrpluralsuffix} for other acronym styles. +There's no guarantee when these commands will be expanded. They may +be expanded on definition or they may be expanded on use, depending +on the \styfmt{glossaries} configuration. \begin{important} Therefore these plural suffix command definitions aren't included in the caption mechanism as that's typically not switched on -until the start of the document. \textbf{This means that the suffix in +until the start of the document. \strong{This means that the suffix in effect will be for the last loaded language that redefined these commands.} It's best to initialise these commands to the most common suffix required in your document and use the \gloskey{plural}, @@ -2517,8 +2840,9 @@ The \texttt{glossaries-irish.ldf} file provides this as follows: your root language label and \texttt{Irish} with the \sty{translator} dictionary label.) -There are now two extra files: \texttt{glossaries-irish-noenc.ldf} -and \texttt{glossaries-irish-utf8.ldf}. +There are now two extra files: \nolinkurl{glossaries-irish-noenc.ldf} +(no encoding information) +and \nolinkurl{glossaries-irish-utf8.ldf} (UTF-8). These both define \cs{glossariescaptionsirish} but the \texttt{*-noenc.ldf} uses \LaTeX\ accent commands: @@ -2560,14 +2884,18 @@ the appropriate UTF-8 characters. This section is only applicable if you have chosen \optsor23. You can ignore this section if you have chosen any of the other options. If you want to alphabetically sort your entries always remember to use the -\gloskey{sort} key if the \gloskey{name} contains any \LaTeX\ commands. +\gloskey{sort} key if the \gloskey{name} contains any \LaTeX\ +commands (except if you're using \gls{bib2gls}). \end{important} If this section seriously confuses you, and you can't work out how to run external tools like \gls{makeglossaries} or \gls{makeindex}, you can try using the \pkgopt{automake} package option, described in \sectionref{sec:pkgopts-sort}, but you will need \TeX's shell escape -enabled. +enabled. See also +\href{https://www.dickimaw-books.com/latex/buildglossaries/}{Incorporating +makeglossaries or makeglossaries-lite or bib2gls into the document +build}. In order to generate a sorted glossary with compact \glspl{numberlist}, it is necessary to use an external @@ -2575,14 +2903,14 @@ In order to generate a sorted glossary with compact \opt1, which uses \TeX\ to do the sorting or \opt5, which doesn't perform any sorting). It is this application that creates the file containing the code required to typeset the -glossary. \textbf{If this step is omitted, the glossaries will not +glossary. \strong{If this step is omitted, the glossaries will not appear in your document.} The two \glspl*{indexingapp} that are most commonly used with \LaTeX\ are \gls{makeindex} and \gls{xindy}. As from version 1.17, the \styfmt{glossaries} package can be used with either of these applications. Previous versions were designed to be -used with \gls*{makeindex} only. With the \sty{glossaries-extra} package, you +used with \gls*{makeindex} only. With the \gls{glossaries-extra} package, you can also use \gls{bib2gls} as the indexing application. (See -the \sty{glossaries-extra} and \gls{bib2gls} user manuals for +the \gls{glossaries-extra} and \gls{bib2gls} user manuals for further details.) Note that \gls*{xindy} and \gls*{bib2gls} have much better multi-lingual support than \gls*{makeindex}, so \gls*{xindy} or \gls*{bib2gls} are recommended if you're not writing in English. @@ -2639,8 +2967,8 @@ file and see if you can work it out from the \gls*{makeindex} or problem.\footnote{Added to version \gls{makeglossaries} 2.18.} This correction is only provided by \gls{makeglossaries} when \gls{makeindex} is used since \gls{xindy} uses the order of the -attributes list to determine which format should take precedence. -(See \cs{GlsAddXdyAttribute} in \sectionref{sec:xindyloc}.) +\ixindyattrs attributes list to determine which format should take precedence. +(see \sectionref{sec:xindyloc}.) \end{itemize} @@ -2697,16 +3025,17 @@ of \gls{makeglossaries}, \gls{makeindex} or \gls{xindy}. For example, if the document is called \texttt{myDoc.tex}, then you must do: \begin{prompt} -latex myDoc +pdflatex myDoc makeglossaries myDoc -latex myDoc +pdflatex myDoc makeglossaries myDoc -latex myDoc +pdflatex myDoc \end{prompt} -(Note that if you use \gls{glossaries-extra}, this will be done -automatically for you if the \pkgoptfmt{indexcrossrefs} feature is -enabled. See the \gls*{glossaries-extra} user guide for further -details.) +(In the case of \opt4, \gls{bib2gls} will scan the description for +instances of commands like \cs{gls} to ensure they are selected but +an extra \gls{bib2gls} call is required to ensure the locations are +included, if locations lists are required. See the +and \gls{bib2gls} manual for further details.) Likewise, an additional \gls{makeglossaries} and \LaTeX\ run may be required if the document pages shift with re-runs. For @@ -2729,7 +3058,7 @@ makeglossaries or makeglossaries-lite or bib2gls into the document build}. If any problems occur, remember to check the transcript files -(e.g.\ \filetype{.glg} or \filetype{.alg}) for messages. +(e.g.\ \filetype{glg} or \filetype{alg}) for messages. \begin{table}[htbp] \caption[Commands and package options that have no effect when @@ -2758,16 +3087,16 @@ use \xdyopt{C} \meta{code} \label{sec:makeglossariesapp} The \gls{makeglossaries} script picks up the relevant information -from the auxiliary (\filetype{.aux}) file and will either call +from the auxiliary (\filetype{aux}) file and will either call \gls{xindy} or \gls{makeindex}, depending on the supplied information. Therefore, you only need to pass the document's name without the extension to \gls*{makeglossaries}. For example, if your document is called \texttt{myDoc.tex}, type the following in your terminal: \begin{prompt} -latex myDoc +pdflatex myDoc makeglossaries myDoc -latex myDoc +pdflatex myDoc \end{prompt} You may need to explicitly load \gls{makeglossaries} into Perl: \begin{prompt} @@ -2798,8 +3127,8 @@ that doesn't support this form of redirection, then you can use the the fallback method without attempting the redirection. Without this redirection, the \mkglsopt{q} (quiet) switch doesn't work as well. -You can specify in which directory the \filetype{.aux}, -\filetype{.glo} etc files are located using the \texttt{-d} switch. +You can specify in which directory the \filetype{aux}, +\filetype{glo} etc files are located using the \texttt{-d} switch. For example: \begin{prompt} pdflatex -output-directory myTmpDir myDoc @@ -2836,17 +3165,12 @@ attempt to correct the problem by removing duplicate locations and retrying. There's no similar check for \gls{xindy} as \gls*{xindy} won't produce any warning and will simply discard duplicates. -The \gls{makeglossaries} script contains POD (Plain Old -Documentation). If you want, you can create a man page for -\gls*{makeglossaries} using \app{pod2man} and move the -resulting file onto the man path. Alternatively do -\texttt{makeglossaries -{}-help} for a list of all options or -\texttt{makeglossaries -{}-version} for the version number. +For a complete list of options do \texttt{makeglossaries -{}-help}. \begin{important} When upgrading the \styfmt{glossaries} package, make sure you also upgrade your version of \gls{makeglossaries}. The current version is -4.44. +4.45. \end{important} \subsection{Using the makeglossaries-lite Lua Script} @@ -2865,7 +3189,7 @@ here. (In particular the \mkglsopt{d} option.) \begin{important} Note that \TeX~Live on Unix-like systems creates a symbolic link called \texttt{makeglossaries-lite} (without the -\texttt{.lua} extension) to the actual +\filetype{lua} extension) to the actual \texttt{makeglossaries-lite.lua} script, so you may not need to supply the extension. \end{important} @@ -2881,9 +3205,9 @@ or makeglossaries-lite myDoc \end{prompt} -\emph{Some} of the options available with \gls{makeglossaries} are -also available with \gls{makeglossaries-lite.lua}. For a complete list of -available options, do +\emph{Some} of the options available with the Perl +\gls{makeglossaries} script are also available with the Lua \gls{makeglossaries-lite.lua} +script. For a complete list of available options, do \begin{prompt} makeglossaries-lite.lua -{}-help \end{prompt} @@ -2918,9 +3242,9 @@ xindy -L \meta{language} -C \meta{encoding} -I xindy -M \meta{style} -t \meta{ba \end{prompt} where \meta{language} is the required language name, \meta{encoding} is the encoding, \meta{base} is the name of the document without the -\filetype{.tex} extension and \meta{style} is the name of the -\gls{xindy} style file without the \filetype{.xdy} extension. -The default name for this style file is \meta{base}\filetype{.xdy} +\filetype{tex} extension and \meta{style} is the name of the +\gls{xindy} style file without the \filetype{xdy} extension. +The default name for this style file is \meta{base}\filetype{xdy} but can be changed via \ics{setStyleFile}\marg{style}. You may need to specify the full path name depending on the current working directory. If any of the file names contain spaces, you must delimit @@ -2936,8 +3260,8 @@ xindy -L english -C utf8 -I xindy -M myDoc -t myDoc.glg -o myDoc.gls myDoc.glo Note that this just creates the main glossary. You need to do the same for each of the other glossaries (including the list of acronyms if you have used the \pkgopt{acronym} -package option), substituting \filetype{.glg}, \filetype{.gls} -and \filetype{.glo} with the relevant extensions. For example, +package option), substituting \filetype{glg}, \filetype{gls} +and \filetype{glo} with the relevant extensions. For example, if you have used the \pkgopt{acronym} package option, then you would need to do: \begin{prompt} @@ -2971,9 +3295,9 @@ your terminal: makeindex -s \meta{style}.ist -t \meta{base}.glg -o \meta{base}.gls \meta{base}.glo \end{prompt} where \meta{base} is the name of your document without the -\filetype{.tex} extension and \meta{style}\filetype{.ist} is the +\filetype{tex} extension and \meta{style}\filetype{ist} is the name of the \gls{makeindex} style file. By default, this is -\meta{base}\filetype{.ist}, but may be changed via +\meta{base}\filetype{ist}, but may be changed via \ics{setStyleFile}\marg{style}. Note that there are other options, such as \mkidxopt{l} (letter ordering). See the \gls*{makeindex} manual for further details. @@ -2987,7 +3311,7 @@ Note that this only creates the main glossary. If you have additional glossaries (for example, if you have used the \pkgopt{acronym} package option) then you must call \gls{makeindex} for each glossary, substituting -\filetype{.glg}, \filetype{.gls} and \filetype{.glo} with the +\filetype{glg}, \filetype{gls} and \filetype{glo} with the relevant extensions. For example, if you have used the \pkgopt{acronym} package option, then you need to type the following in your terminal: @@ -3008,18 +3332,19 @@ you use \gls*{makeindex} explicitly instead of using \gls{makeglossaries}. These are listed in \tableref{tab:makeglossariesCmds}. - -\subsection{Note to Front-End and Script Developers} +\section{Note to Front-End and Script Developers} \label{sec:notedev} -The information needed to determine whether to use \gls{xindy} -or \gls{makeindex} and the information needed to call those -applications is stored in the auxiliary file. This information can -be gathered by a front-end, editor or script to make the glossaries -where appropriate. This section describes how the information is -stored in the auxiliary file. +The information needed to determine whether to use \gls{xindy}, +\gls{makeindex} or \gls{bib2gls} is stored in the \filetype{aux} +file. This information can be gathered by a front-end, editor or +script to make the glossaries where appropriate. This section +describes how the information is stored in the auxiliary file. + +\subsection{MakeIndex and Xindy} +\label{sec:notedev.makeindex.xindy} -The file extensions used by each defined glossary are given by +The file extensions used by each defined (but not ignored) glossary are given by \begin{definition}[\DescribeMacro{\@newglossary}] \cs{@newglossary}\marg{label}\marg{log}\marg{out-ext}\marg{in-ext} \end{definition} @@ -3029,24 +3354,45 @@ where \meta{in-ext} is the extension of the extension of the \emph{\gls*{indexingapp}['s]} output file (the input file from the \styfmt{glossaries} package's point of view) and \meta{log} is the extension of the \gls*{indexingapp}['s] transcript -file. The label for the glossary is also given for information -purposes only, but is not required by the \glspl*{indexingapp}. For +file. The label for the glossary is also given. This isn't required +with \gls{makeindex}, but with \gls{xindy} it's needed to pick up +the associated language and encoding (see below). For example, the information for the default main glossary is written as: \begin{verbatim} \@newglossary{main}{glg}{gls}{glo} \end{verbatim} +If \gls{glossaries-extra}['s] hybrid method has been used (with +\cs{makeglossaries}\oarg{sub-list}), then the sub-list +of glossaries that need to be processed will be identified with: +\begin{alltt} +\ics*{glsxtr@makeglossaries}\marg{list} +\end{alltt} The \gls{indexingapp}['s] style file is specified by \begin{definition}[\DescribeMacro{\@istfilename}] \cs{@istfilename}\marg{filename} \end{definition} The file extension indicates whether to use \gls{makeindex} -(\filetype{.ist}) or \gls{xindy} (\filetype{.xdy}). Note that +(\filetype{ist}) or \gls{xindy} (\filetype{xdy}). Note that the glossary information is formatted differently depending on which \gls*{indexingapp} is supposed to be used, so it's important to call the correct one. +For example, with \app{arara} you can easily determine whether to run \gls{makeglossaries}: +\begin{alltt} +\% arara: makeglossaries if found("aux", "@istfilename") +\end{alltt} +It's more complicated if you want to explicitly run \gls{makeindex} +or \gls{xindy} + +\begin{important} +Note that if you choose to explicitly call \gls{makeindex} or +\gls{xindy} then the user will miss out on the diagnostic +information and the encap-clash fix that \gls{makeglossaries} also +provides. +\end{important} + Word or letter ordering is specified by: \begin{definition}[\DescribeMacro{\@glsorder}] \cs{@glsorder}\marg{order} @@ -3064,15 +3410,76 @@ the root language (e.g.\ \texttt{english}) and \meta{code} is the encoding (e.g.\ \texttt{utf8}). These commands are omitted if \gls{makeindex} should be used. -If \opt1 has been used, the \texttt{.aux} file will contain -\begin{definition} +If \opt1 has been used, the \filetype{aux} file will contain +\begin{definition}[\DescribeMacro\@gls@reference] \cs{@gls@reference}\marg{type}\marg{label}\marg{location} \end{definition} -for every time an entry has been referenced. If \opt4 has been -used, the \texttt{.aux} file will contain one or more instances of -\begin{definition} -\cs{glsxtr@resource}\marg{options}\marg{basename} -\end{definition} +for every time an entry has been referenced. + +\subsection{Entry Labels} +\label{sec:notedev.labels} + +If you need to gather labels for auto-completion, the +\pkgopt{writeglslabels} package option will create a file containing +the labels of all defined entries (regardless of whether or not the +entry has been used in the document). The \gls{glossaries-extra} +package also provides \pkgopt+{atom}{docdef}, which will create the +\filetype{glsdefs} file but will act like \pkgopt+{restricted}{docdef}. + +\subsection{Bib2Gls} +\label{sec:notedev.bib2gls} + +\bibglsnote +If \opt4 has been used, the \filetype{aux} file will contain one or more instances of +\begin{alltt} +\ics*{glsxtr@resource}\marg{options}\marg{basename} +\end{alltt} +where \meta{basename} is the basename of the \filetype{glstex} file +that needs to be created by \gls{bib2gls}. If \texttt{src\dequals\marg{bib +list}} isn't present in \meta{options} then \meta{basename} also +indicates the name of the associated \filetype{bib} file. + +For example, with \app{arara} you can easily determine whether or +not to run \gls{bib2gls}: +\begin{alltt} +\% arara: bib2gls if found("aux", "glsxtr@resource") +\end{alltt} +(It gets more complicated if both \ics*{glsxtr@resource} and +\cs{@istfilename} are present as that indicates the hybrid +\pkgopt+{alsoindex}{record} option.) + +Remember that with \gls{bib2gls}, the entries will never be defined +on the first \LaTeX\ call (because their definitions are contained +in the \filetype{glstex} file created by \gls{bib2gls}). You can +also pick up labels from the records in \filetype{aux} file, which +will be in the form: +\begin{alltt} +\ics*{glsxtr@record}\marg{label}\marg{h-prefix}\marg{counter}\marg{format}\marg{loc} +\end{alltt} +or (with \pkgopt+{nameref}{record}) +\begin{alltt} +\ics*{glsxtr@record@nameref}\marg{label}\marg{href prefix}\marg{counter}\marg{format}\marg{location}\marg{title}\marg{href anchor}\marg{href value} +\end{alltt} +or (with \cs{glssee}) +\begin{alltt} +\ics*{glsxtr@recordsee}\marg{label}\marg{xr list} +\end{alltt} +You can also pick up the commands defined with +\ics*{glsxtrnewglslike}, which are added to the \filetype{aux} file +for \gls{bib2gls}['s] benefit: +\begin{alltt} +\ics*{@glsxtr@newglslike}\marg{label-prefix}\marg{cs} +\end{alltt} +If \ics*{GlsXtrSetAltModifier} is used, then the modifier is +identified with: +\begin{alltt} +\ics*{@glsxtr@altmodifier}\marg{character} +\end{alltt} +Label prefixes (for the \ics*{dgls} set of commands) are identified +with: +\begin{alltt} +\ics*{@glsxtr@prefixlabellist}\marg{list} +\end{alltt} \chapter{Package Options} \label{sec:pkgopts} @@ -3080,8 +3487,15 @@ used, the \texttt{.aux} file will contain one or more instances of This section describes the available \styfmt{glossaries} package options. You may omit the \texttt{=true} for boolean options. (For example, \pkgopt{acronym} is equivalent to \pkgopt[true]{acronym}). + +\begin{xtr} The \gls{glossaries-extra} package has additional options described -in the \gls*{glossaries-extra} manual. +in the \gls*{glossaries-extra} manual. The extension package also +has some different default settings to the base package. Those that +are available at the time of writing are included here. Future +versions of \gls{glossaries-extra} may have additional package +options or new values for existing settings that aren't listed here. +\end{xtr} \begin{important} Note that \meta{key}=\meta{value} package options can't be passed via the @@ -3095,63 +3509,90 @@ package. Options that aren't \meta{key}=\meta{value} (such as \section{General Options} \label{sec:pkgopts-general} -\begin{description} -\item[\pkgoptdef{nowarn}] This suppresses all warnings generated by +\pkgoptsec{nowarn} This suppresses all warnings generated by the \styfmt{glossaries} package. Don't use this option if you're new to using \styfmt{glossaries} as the warnings are designed to help detect common mistakes (such as forgetting to use \ics{makeglossaries}). -Note that the \pkgopt[true]{debug} and \pkgopt[showtargets]{debug} will override this option. +Note that if you use \pkgopt{debug} with any value other than +\pkgoptfmt{false} it will override this option. -\item[\pkgoptdef{nolangwarn}] This suppresses the warning generated by +\pkgoptsec{nolangwarn} This suppresses the warning generated by a missing language module. -\item[\pkgoptdef{noredefwarn}] If you load \styfmt{glossaries} with +\pkgoptsec{noredefwarn} If you load \styfmt{glossaries} with a~class or another package that already defines glossary related commands, by default \styfmt{glossaries} will warn you that it's redefining those commands. If you are aware of the consequences of using \styfmt{glossaries} with that class or package and you don't want to be warned about it, use this option to suppress those warnings. Other warnings will still be issued unless you use the -\pkgopt{nowarn} option described above. - -\item[\pkgoptdef{debug}] Introduced in version 4.24. -The default setting is \pkgopt[false]{debug}. -This was a boolean option but as from v4.32 it now accepts the -values: \pkgoptfmt{false}, \pkgoptfmt{true} and -\pkgoptfmt{showtargets}. If no value is given, \pkgopt[true]{debug} is assumed. -Both \pkgopt[true]{debug} and \pkgopt[showtargets]{debug} -switch on the debug mode (and will automatically -cancel the \pkgopt{nowarn} option). The \pkgopt[showtargets]{debug} -option will additionally use +\pkgopt{nowarn} option described above. (This option is +automatically switched on by \gls{glossaries-extra}.) + +\pkgoptsec[value]{debug} Introduced in version 4.24. The default +setting is \pkgopt[false]{debug}. The following values are +available: \pkgoptfmt{false}, \pkgoptfmt{true}, +\pkgoptfmt{showtargets} (v4.32+) and \pkgoptfmt{showaccsupp} +(v4.45+). If no value is given, \pkgopt[true]{debug} is assumed. + +\begin{xtr} +The \gls{glossaries-extra} package provides extra values +\pkgoptval*{showwrgloss}{debug}, that may be used to show where +the indexing is occurring, and \pkgoptval*{all}{debug}, which +switches on all debugging options. See the \gls{glossaries-extra} +manual for further details. +\end{xtr} + +All values other than \pkgopt[false]{debug} switch on the debug mode +(and will automatically cancel the \pkgopt{nowarn} option). The +\pkgopt[showtargets]{debug} option will additionally use: \begin{definition}[\DescribeMacro\glsshowtarget] \cs{glsshowtarget}\marg{target name} \end{definition} -to show the hypertarget or hyperlink name in the margin when +to show the hypertarget or hyperlink name when \cs{glsdohypertarget} is used by commands like \cs{glstarget} and when \cs{glsdohyperlink} is used by commands like \cs{gls}. -This puts the information in the margin using \ics{marginpar} unless -math mode or inner mode are detected, in which case it puts the -information in line enclosed by square brackets. The -\gls{glossaries-extra} package provides an additional setting that -may be used to show where the indexing is occurring. See the -\gls{glossaries-extra} manual for further details. +In math mode or inner mode, this puts the target name in square +brackets just before the link or anchor. In outer mode it uses: +\begin{definition}[\DescribeMacro\glsshowtargetouter] +\cs{glsshowtargetouter}\marg{label} +\end{definition} +which by default places the target name in the margin. The font is +given by: +\begin{definition}[\DescribeMacro\glsshowtargetfont] +\cs{glsshowtargetfont} +\end{definition} +The default definition is \verb|\ttfamily\small|. This command is +included in the definition of \cs{glsshowtargetouter}, so if you +want to redefine that command remember to include the font. For +example: +\begin{verbatim} +\renewcommand*{\glsshowtargetouter}[1]{% + {\glsshowtargetfont [#1]}} +\end{verbatim} + +Similarly, the \pkgopt[showaccsupp]{debug} will add the +accessibility support information using: +\begin{definition}[\DescribeMacro\glsshowaccsupp] +\cs{glsshowaccsupp}\marg{options}\marg{tag}\marg{replacement text} +\end{definition} +This internally uses \ics{glsshowtarget}. This option is provided +for use with \sty{glossaries-accsupp}. The purpose of the debug mode can be demonstrated with the following example document: -\begin{verbatim} -\documentclass{article} -\usepackage{glossaries} -\newglossaryentry{sample1}{name={sample1}, - description={example}} -\newglossaryentry{sample2}{name={sample2}, - description={example}} -\glsadd{sample2} -\makeglossaries -\begin{document} -\gls{sample1}. -\printglossaries -\end{document} -\end{verbatim} +\begin{alltt} +\cs{documentclass}\mgroup{article} +\cs{usepackage}\mgroup{glossaries} +\cs{newglossaryentry}\mgroup{sample1}\mgroup{name=\mgroup{sample1},description=\mgroup{example}} +\cs{newglossaryentry}\mgroup{sample2}\mgroup{name=\mgroup{sample2},description=\mgroup{example}} +\strong{\ics{glsadd}}\mgroup{sample2}\% <- does nothing here +\strong{\ics{makeglossaries}} +\cs{begin}\mgroup{document} +\cs{gls}\mgroup{sample1}. +\cs{printglossaries} +\cs{end}\mgroup{document} +\end{alltt} In this case, only the \texttt{sample1} entry has been indexed, even though \verb|\glsadd{sample2}| appears in the source code. This is because \verb|\glsadd{sample2}| has been used before the @@ -3159,19 +3600,23 @@ associated file is opened by \ics{makeglossaries}. Since the file isn't open yet, the information can't be written to it, which is why the \texttt{sample2} entry doesn't appear in the glossary. +Without \cs{makeglossaries} the indexing is suppressed with \optsand23 but, other +than that, commands like \cs{gls} behave as usual. + This situation doesn't cause any errors or warnings as it's perfectly legitimate for a user to want to use \styfmt{glossaries} to format the entries (e.g.\ abbreviation expansion) but not display -any lists of terms, abbreviations, symbols etc. -Without \cs{makeglossaries} the indexing is suppressed but, other -than that, commands like \cs{gls} behave as usual. It's also -possible that the user may want to temporarily comment out +any lists of terms, abbreviations, symbols etc (or the user may +prefer to use the unsorted \optsor56). +It's also possible that the user may want to temporarily comment out \cs{makeglossaries} in order to suppress the indexing while working -on a draft version to speed compilation. Therefore -\cs{makeglossaries} can't be used to enable \cs{newglossaryentry} -and \cs{glsadd}. They must be enabled by default. (It does, however, -enable the \gloskey{see} key as that's a more common problem. See -below.) +on a draft version to speed compilation, or the user may +prefer to use \optsor14 for indexing, which don't use \cs{makeglossaries}. + +Therefore \cs{makeglossaries} can't be used to enable +\cs{newglossaryentry} and commands like \cs{gls} and \cs{glsadd}. +These commands must be enabled by default. (It does, however, enable +the \gloskey{see} key as that's a more common problem. See below.) The debug mode, enabled with the \pkgopt{debug} option, \begin{verbatim} @@ -3191,99 +3636,28 @@ glossary but you're sure you used commands like \cs{glsadd} or \cs{glsaddall}, try switching on the \pkgopt{debug} option and see if any information has been written to the log file. -\item[\pkgoptdef{seenoindex}] Introduced in version 4.24, this option -may take one of three values: \pkgoptfmt{error}, \pkgoptfmt{warn} or -\pkgoptfmt{ignore}. The \gloskey{see} key automatically indexes the -cross-referenced entry using \cs{glsadd}. This means that it suffers -from the same problem as the above. If used before the relevant -glossary file has been opened, the indexing can't be performed. -Since this is easy to miss, the \styfmt{glossaries} package by -default issues an error message if the \gloskey{see} key is used -before \cs{makeglossaries}. This option allows you to change the -error into just a warning (\pkgopt[warn]{seenoindex}) or -ignore it (\pkgopt[ignore]{seenoindex}) if, for example, you want -to temporarily comment out \cs{makeglossaries} to speed up the -compilation of a draft document by omitting the indexing. - -\item[\pkgoptdef{nomain}] This suppresses the creation of the main -glossary and associated \texttt{.glo} file, if unrequired. Note that -if you use this option, you must create another glossary in which to -put all your entries (either via the \pkgopt{acronym} (or -\pkgopt{acronyms}) package option described in -\sectionref{sec:pkgopts-acronym} or via the \pkgopt{symbols}, -\pkgopt{numbers} or \pkgopt{index} options described in -\sectionref{sec:pkgopts-other} or via \ics{newglossary} described in -\sectionref{sec:newglossary}). - -\begin{important} -If you don't use the main glossary and you don't use this option, -\gls{makeglossaries} will produce a warning. -\end{important} -\begin{alltt} -Warning: File '\emph{filename}.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. -\end{alltt} -If you did actually want to use the main glossary and you see this -warning, check that you have referenced the entries in that glossary -via commands such as \ics{gls}. - -\item[\pkgoptdef{sanitizesort}] This is a boolean option that -determines whether or not to \gls{sanitize} the sort value when -writing to the external glossary file. For example, suppose you -define an entry as follows: -\begin{verbatim} -\newglossaryentry{hash}{name={\#},sort={#}, - description={hash symbol}} -\end{verbatim} -The sort value (\verb|#|) must be sanitized before writing it to the -glossary file, otherwise \LaTeX\ will try to interpret it as a -parameter reference. If, on the other hand, you want the sort value -expanded, you need to switch off the sanitization. For example, -suppose you do: -\begin{verbatim} -\newcommand{\mysortvalue}{AAA} -\newglossaryentry{sample}{% - name={sample}, - sort={\mysortvalue}, - description={an example}} -\end{verbatim} -and you actually want \cs{mysortvalue} expanded, so that the entry -is sorted according to \texttt{AAA}, then use the package option -\pkgopt[false]{sanitizesort}. - -The default for \optsand23 is \pkgopt[true]{sanitizesort}, and the -default for \opt1 is \pkgopt[false]{sanitizesort}. - -\item[\pkgoptdef{esclocations}] This is a boolean option. (The default -is \pkgopt[true]{esclocations}, but \ics{makenoidxglossaries} -changes it to \pkgopt[false]{esclocations}.) Both \gls{makeindex} and \gls{xindy} -are fussy about the location formats (\gls{makeindex} more so than -\gls{xindy}) so the \styfmt{glossaries} package tries to ensure that -special characters are escaped and allows for the location to be -substituted for a format that's more acceptable to the indexing -application. This requires a bit of trickery to circumvent the -problem posed by \TeX's asynchronous output routine, which can go -wrong and also adds to the complexity of the document build. - -If you're sure that your locations will always expand to an -acceptable format (or you're prepared to post-process the glossary -file before passing it to the relevant indexing application) then -use \pkgopt[false]{esclocations} to avoid the complex escaping -of location values. (See \ifpdf section~\ref*{sec:wrgloss}\fi \qt{Writing information to associated files} in the documented -code for further details.) - -\item[\pkgoptdef{savewrites}] This is a boolean option to minimise the +\pkgoptsec[boolean]{savewrites} This is a boolean option to minimise the number of write registers used by the \styfmt{glossaries} package. -(Default is \pkgopt[false]{savewrites}.) There are only a limited -number of write registers, and if you have a large number of -glossaries or if you are using a class or other packages that -create a lot of external files, you may exceed the maximum number -of available registers. If \pkgopt{savewrites} is set, the glossary -information will be stored in token registers until the end of the -document when they will be written to the external files. +The default is \pkgopt[false]{savewrites}. With \optsand23, one +write register is required per (non-ignored) glossary and one for +the style file. + +With all options except \optsand14, another write register is +required if the \filetype{docdefs} file is needed to save document +definitions. With both \optsand14, no write registers are required +(document definitions aren't permitted and indexing information is +written to the \filetype{aux} file). If you really need document +definitions but you want to minimise the number of write registers +then consider using \pkgopt+{restricted}{docdef} with +\gls{glossaries-extra}. + +There are only a limited number of write registers, and if you have +a large number of glossaries or if you are using a class or other +packages that create a lot of external files, you may exceed the +maximum number of available registers. If \pkgopt{savewrites} is +set, the glossary information will be stored in token registers +until the end of the document when they will be written to the +external files. \begin{important} This option can significantly slow document compilation and may @@ -3293,11 +3667,17 @@ output routine. As an alternative, you can use the \sty{scrwfile} package (part of the KOMA-Script bundle) and not use this option. \end{important} -You can also reduce the number of write registers by using -\optsor14 or by ensuring you define all your glossary entries in the -preamble. - -\begin{important} +By way of comparison, \nolinkurl{sample-multi2.tex} +provided with \gls{bib2gls} has a total of 15 glossaries. With +\optsor23, this would require 46 associated files and 16 +write registers.\footnote{These figures don't include standard files +and registers provided by the kernel or \sty{hyperref}, such as +\filetypefmt{aux} and \filetypefmt{out}.} With +\gls{bib2gls}, no write registers are required and there are only 10 +associated files for that particular document (9 resource files and +1 transcript file). + +\importantpar[-2][-1ex] If you want to use \TeX's \ics{write18} mechanism to call \gls{makeindex} or \gls{xindy} from your document and use \pkgopt{savewrites}, you must create the external files with @@ -3310,13 +3690,14 @@ document to avoid rewriting the files. For example: -t \jobname.glg -o \jobname.gls \jobname} \let\glswritefiles\relax \end{verbatim} -\end{important} + +\noindent In general, this package option is best avoided. -\item[\pkgoptdef{translate}] This can take the following values: +\pkgoptsec[value]{translate} This can take the following values: \begin{description} - \item[{\pkgopt[true]{translate}}] If \sty{babel} has been loaded + \item[{\pkgoptval{true}{translate}}] If \sty{babel} has been loaded and the \sty{translator} package is installed, \sty{translator} will be loaded and the translations will be provided by the \sty{translator} package interface. You can modify the @@ -3328,12 +3709,12 @@ In general, this package option is best avoided. \sty{polyglossia} has been loaded, \sty{glossaries-polyglossia} will be loaded. - \item[{\pkgopt[false]{translate}}] Don't provide translations, even + \item[{\pkgoptval{false}{translate}}] Don't provide translations, even if \sty{babel} or \sty{polyglossia} has been loaded. (Note that \sty{babel} provides the command \ics{glossaryname} so that will still be translated if you have loaded \sty{babel}.) - \item[{\pkgopt[babel]{translate}}] Don't load the \sty{translator} + \item[{\pkgoptval{babel}{translate}}] Don't load the \sty{translator} package. Instead load \sty{glossaries-babel}. \begin{important} @@ -3351,32 +3732,19 @@ specified, \pkgopt[true]{translate} is assumed if \sty{babel}, \sty{polyglossia} or \sty{translator} have been loaded. Otherwise \pkgopt[false]{translate} is assumed. +\begin{xtr} +With \gls{glossaries-extra}, if \sty{babel} is detected then +\pkgopt[babel]{translate} is automatically passed to the base +\sty{glossaries} package. +\end{xtr} + See \sectionref{sec:fixednames} for further details. -\item[\pkgoptdef{notranslate}] This is equivalent to +\pkgoptsec{notranslate} This is equivalent to \pkgopt[false]{translate} and may be passed via the document class options. -\item[\pkgoptdef{nohypertypes}] Use this option if you have multiple -glossaries and you want to suppress the entry hyperlinks for a -particular glossary or glossaries. The value of this option should -be a comma-separated list of glossary types where \ics{gls} etc -shouldn't have hyperlinks by default. Make sure you enclose the -value in braces if it contains any commas. Example: -\begin{verbatim} -\usepackage[acronym,nohypertypes={acronym,notation}] - {glossaries} -\newglossary[nlg]{notation}{not}{ntn}{Notation} -\end{verbatim} -The values must be fully expanded, so \textbf{don't} try -\texttt{nohypertypes\discretionary{}{}{}=\ics{acronymtype}}. You may also use -\begin{definition} -\ics{GlsDeclareNoHyperList}\marg{list} -\end{definition} -instead or additionally. -See \sectionref{sec:glslink} for further details. - -\item[\pkgoptdef{hyperfirst}] This is a boolean option that specifies +\pkgoptsec[boolean]{hyperfirst} This is a boolean option that specifies whether each term has a hyperlink on \firstuse. The default is \pkgopt[true]{hyperfirst} (terms on \gls{firstuse} have a hyperlink, unless explicitly suppressed using starred versions of commands @@ -3435,63 +3803,67 @@ Note that this hook isn't used by the commands that don't check the \ics{glslinkpostsetkeys}, which is used by both the \glslike\ and \glstextlike\ commands.) -\item[\pkgoptdef{indexonlyfirst}] This is a boolean option that specifies -whether to only add information to the external glossary file on -\gls{firstuse}. The default is \pkgopt[false]{indexonlyfirst}, -which will add a line to the file every time one of the -\glslike\ or \glstextlike\ commands are used. Note that \ics{glsadd} -will always add information to the external glossary -file\footnote{bug fix in v4.16 has corrected the code to ensure -this.}\ (since that's the purpose of that command). +The \gls{glossaries-extra} package provides a method of disabling +the \gls{firstuse} hyperlink according to the entry's associated +category. For example, if you only to switch off the \gls{firstuse} +hyperlink for abbreviations and acronyms then you simply need to set +the \attr{nohyperfirst} attribute for the \texttt{abbreviation} +and \texttt{acronym} categories. (Instead of using the +\pkgopt{nohyperfirst} package option.) See the +\gls{glossaries-extra} manual for further details. -You can customise this by redefining -\begin{definition}[\DescribeMacro\glswriteentry] -\cs{glswriteentry}\marg{label}\marg{wr-code} -\end{definition} -where \meta{label} is the entry's label and \meta{wr-code} is the -code that writes the entry's information to the external file. -The default definition of \cs{glswriteentry} is: -\begin{verbatim} -\newcommand*{\glswriteentry}[2]{% - \ifglsindexonlyfirst - \ifglsused{#1}{}{#2}% - \else - #2% - \fi -} -\end{verbatim} -This checks the \pkgopt{indexonlyfirst} package option (using -\cs{ifglsindexonlyfirst}) and does \meta{wr-code} if this is -\pkgoptfmt{false} otherwise it only does \meta{wr-code} of the entry -hasn't been used. +\pkgoptsec{writeglslabels} This is a valueless option that +will create a file called \cs{jobname}\texttt{.}\filetype{glslabels} at the end +of the document. This file simply contains a list of all defined +entry labels (including those in any ignored glossaries). It's +provided for the benefit of text editors that need to know labels +for \Index{auto-completion}. (See also \gls{glossaries-extra}['s] +\pkgopt+{atom}{docdef} package option.) -For example, suppose you only want to index the first use for -entries in the \texttt{acronym} glossary and not in the -\texttt{main} (or any other) glossary: -\begin{verbatim} -\renewcommand*{\glswriteentry}[2]{% - \ifthenelse{\equal{\glsentrytype{#1}}{acronym}} - {\ifglsused{#1}{}{#2}}% - {#2}% -} -\end{verbatim} -Here I've used \cs{ifthenelse} to ensure the arguments of -\cs{equal} are fully expanded before the comparison is made. +\begin{bib2gls} +Note that with \gls{bib2gls} the file will only contain the entries +that \gls{bib2gls} has selected from the \filetype{bib} files. +\end{bib2gls} -\item[\pkgoptdef{savenumberlist}] This is a boolean option that -specifies whether or not to gather and store the \gls{numberlist} -for each entry. The default is \pkgopt[false]{savenumberlist}. (See -\ics{glsentrynumberlist} and \ics{glsdisplaynumberlist} in -\sectionref{sec:glsnolink}.) This is always true if you -use \opt1. +\xtrpkgoptsec[value]{undefaction} +The value may be one of: +\begin{description} + \item[\pkgoptfmt{error}] generate an error if a referenced entry is + undefined (default, and only available setting with just + \styfmt{glossaries}); + \item[\pkgoptfmt{warn}] only warn if a referenced entry is + undefined (automatically activated with \opt4). +\end{description} + +\xtrpkgoptsec[value]{docdef} + +This option governs the use of \cs{newglossaryentry}. Available +values: +\begin{description} +\item[\pkgoptfmt{false}] \cs{newglossaryentry} is not permitted in +the \env{document} environment (default with \gls{glossaries-extra} +and for \opt1 with just the base \styfmt{glossaries} package); + +\item[\pkgoptfmt{restricted}] \cs{newglossaryentry} is only permitted in +the \env{document} environment if it occurs before +\cs{printglossary} (not available for some indexing options); + +\item[\pkgoptfmt{atom}] as \pkgoptfmt{restricted} but creates the +\filetype{docdefs} file for use by \app{atom} (without the +limitations of \pkgopt+{true}{docdef}); + +\item[\pkgoptfmt{true}] \cs{newglossaryentry} is permitted in the +\env{document} environment where it would normally be permitted by +the base \styfmt{glossaries} package. This will create the +\filetype{docdefs} file if \cs{newglossaryentry} is found in the +\env{document} environment. \end{description} \section{Sectioning, Headings and TOC Options} \label{sec:pkgopts-sec} -\begin{description} -\item[\pkgoptdef{toc}] Add the glossaries to the table of contents. +\pkgoptsec[boolean]{toc} Add the glossaries to the table of contents. Note that an extra \LaTeX\ run is required with this option. Alternatively, you can switch this function on and off using \begin{definition}[\DescribeMacro{\glstoctrue}] @@ -3501,8 +3873,12 @@ and \begin{definition}[\DescribeMacro{\glstocfalse}] \cs{glstocfalse} \end{definition} +The default value is \pkgopt[false]{toc} for the base +\styfmt{glossaries} package and \pkgopt[true]{toc} for +\gls{glossaries-extra}. -\item[\pkgoptdef{numberline}] When used with \pkgopt{toc}, this will +\pkgoptsec[boolean]{numberline} When used with the above +\pkgopt[true]{toc} option, this will add \ics{numberline}\verb|{}| in the final argument of \ics{addcontentsline}. This will align the table of contents entry with the numbered section titles. Note that this option has no @@ -3510,16 +3886,22 @@ effect if the \pkgopt{toc} option is omitted. If \pkgopt{toc} is used without \pkgopt{numberline}, the title will be aligned with the section numbers rather than the section titles. -\item[\pkgoptdef{section}] This is a \meta{key}=\meta{value} option. Its -value should be the name of a sectional unit (e.g.\ chapter). -This will make the glossaries appear in the named sectional unit, -otherwise each glossary will appear in a chapter, if chapters -exist, otherwise in a section. Unnumbered sectional units will be used -by default. Example: +\pkgoptsec[value]{section} + +This option indicates the sectional unit to use for the glossary. +The value should be the control sequence \emph{name} without the +leading backslash or following star (e.g.\ just \texttt{chapter} +not \cs{chapter} or \texttt{chapter*}). + +The default behaviour is for the glossary heading to use +\cs{chapter}, if that command exists, or \cs{section} otherwise. The +starred or unstarred form is determined by the \pkgopt{numberedsection} option. + +Example: \begin{verbatim} \usepackage[section=subsection]{glossaries} \end{verbatim} -You can omit the value if you want to use sections, i.e.\ +You can omit the value if you want to use \cs{section}, i.e.\ \begin{verbatim} \usepackage[section]{glossaries} \end{verbatim} @@ -3559,10 +3941,11 @@ be fixed by redefining \DescribeMacro\glsclearpage\cs{glsclearpage}: \renewcommand*{\glsclearpage}{\clearpage} \end{verbatim} -\item[\pkgoptdef{ucmark}] This is a boolean option (default: +\pkgoptsec[boolean]{ucmark} This is a boolean option. The default is \pkgopt[false]{ucmark}, unless \cls{memoir} has been loaded, in -which case it defaults to \pkgopt[true]{ucmark}). If -set, \ics{glsglossarymark} uses +which case the default is \pkgopt[true]{ucmark}. + +If set, \ics{glsglossarymark} uses \ics{MakeTextUppercase}\footnote{Actually it uses \ics{mfirstucMakeUppercase} which is set to \sty{textcase}'s \cs{MakeTextUppercase} by the @@ -3570,8 +3953,8 @@ by the \ics{makefirstuc}. (The \sty{textcase} package is automatically loaded by \styfmt{glossaries}.)}. You can test whether this option has been set or not using -\begin{definition}[\DescribeMacro\ifglsucmark] -\cs{ifglsucmark} \meta{true part}\cs{else} \meta{false part}\cs{fi} +\begin{definition} +\ics{ifglsucmark} \meta{true part}\cs{else} \meta{false part}\cs{fi} \end{definition} For example: \begin{verbatim} @@ -3582,10 +3965,10 @@ For example: \markright{#1}% \fi} \end{verbatim} -If \cls{memoir} has been loaded and \pkgopt{ucfirst} is set, then +If \cls{memoir} has been loaded and \pkgopt{ucmark} is set, then \cls{memoir}'s \ics{memUChead} is used. -\item[\pkgoptdef{numberedsection}] +\pkgoptsec[value]{numberedsection} The glossaries are placed in unnumbered sectional units by default, but this can be changed using \pkgopt{numberedsection}. This option can take one of the following values: @@ -3658,13 +4041,26 @@ associated with the \texttt{main} glossary. As above, you can redefine \cs{glsautoprefix} to provide a prefix for the label. \end{itemize} -\end{description} - \section{Glossary Appearance Options} \label{sec:pkgopts-printglos} -\begin{description} -\item[\pkgoptdef{entrycounter}] This is a boolean option. (Default +\pkgoptsec[boolean]{savenumberlist} This is a boolean option that +specifies whether or not to gather and store the \gls{numberlist} +for each entry. The default is \pkgopt[false]{savenumberlist}. (See +\ics{glsentrynumberlist} and \ics{glsdisplaynumberlist} in +\sectionref{sec:glsnolink}.) This is always true if you +use \opt1. + +\begin{bib2gls} +If you use the \pkgopt*{record} option (with either no value or +\pkgopt+{only}{record} or \pkgopt+{nameref}{record}) then this +package option has no effect. With \gls{bib2gls}, the +\glspl{numberlist} are automatically saved with the default +\resourceopt[true]{save-locations} and +\resourceopt[true]{save-loclist} resource settings. +\end{bib2gls} + +\pkgoptsec[boolean]{entrycounter} This is a boolean option. (Default is \pkgopt[false]{entrycounter}.) If set, each main (level~0) glossary entry will be numbered when using the standard glossary styles. This option creates the counter @@ -3690,7 +4086,7 @@ creating the glossary files using \gls{makeglossaries}, up-to-date. \end{important} -\item[\pkgoptdef{counterwithin}] This is a \meta{key}=\meta{value} +\pkgoptsec[value]{counterwithin} This is a \meta{key}=\meta{value} option where \meta{value} is the name of a counter. If used, this option will automatically set \pkgopt[true]{entrycounter} and the \ctr{glossaryentry} counter will be reset every time \meta{value} is @@ -3705,7 +4101,7 @@ counter used in the glossary's sectioning command. \end{important} If you want the counter reset at the start of each glossary, you can -redefine \ics{glossarypreamble} to use +modify the glossary preamble (\ics{glossarypreamble}) to use \begin{definition}[\DescribeMacro{\glsresetentrycounter}] \cs{glsresetentrycounter} \end{definition} @@ -3728,7 +4124,7 @@ glossary preamble, as required. For example: } \end{verbatim} -\item[\pkgoptdef{subentrycounter}] This is a boolean option. (Default +\pkgoptsec[boolean]{subentrycounter} This is a boolean option. (Default is \pkgopt[false]{subentrycounter}.) If set, each level~1 glossary entry will be numbered when using the standard glossary styles. This option creates the counter @@ -3739,7 +4135,7 @@ reference the number within the document using \ics{glsrefentry}\marg{label} where \meta{label} is the label associated with the sub-entry. -\item[\pkgoptdef{style}] This is a \meta{key}=\meta{value} option. +\pkgoptsec[value]{style} This is a \meta{key}=\meta{value} option. (Default is \pkgopt[list]{style}, unless \sty{classicthesis} has been loaded, in which case the default is \pkgopt[index]{style}.) Its value should be the name of the glossary style to use. This key may only be used for styles @@ -3751,7 +4147,7 @@ set the style using \end{definition} (See \sectionref{sec:styles} for further details.) -\item[\pkgoptdef{nolong}] This prevents the \styfmt{glossaries} package +\pkgoptsec{nolong} This prevents the \styfmt{glossaries} package from automatically loading \sty{glossary-long} (which means that the \sty{longtable} package also won't be loaded). This reduces overhead by not defining unwanted styles and commands. Note that if @@ -3759,7 +4155,7 @@ you use this option, you won't be able to use any of the glossary styles defined in the \styfmt{glossary-long} package (unless you explicitly load \sty{glossary-long}). -\item[\pkgoptdef{nosuper}] This prevents the \styfmt{glossaries} package +\pkgoptsec{nosuper} This prevents the \styfmt{glossaries} package from automatically loading \sty{glossary-super} (which means that the \sty{supertabular} package also won't be loaded). This reduces overhead by not defining unwanted styles and commands. Note that if @@ -3767,7 +4163,7 @@ you use this option, you won't be able to use any of the glossary styles defined in the \styfmt{glossary-super} package (unless you explicitly load \sty{glossary-super}). -\item[\pkgoptdef{nolist}] This prevents the \styfmt{glossaries} package +\pkgoptsec{nolist} This prevents the \styfmt{glossaries} package from automatically loading \sty{glossary-list}. This reduces overhead by not defining unwanted styles. Note that if you use this option, you won't be able to use any of the @@ -3778,7 +4174,7 @@ Note that since the default style is \glostyle{list} (unless also need to use the \pkgopt{style} option to set the style to something else. -\item[\pkgoptdef{notree}] This prevents the \styfmt{glossaries} package +\pkgoptsec{notree} This prevents the \styfmt{glossaries} package from automatically loading \sty{glossary-tree}. This reduces overhead by not defining unwanted styles. Note that if you use this option, you won't be able to use any of the @@ -3787,7 +4183,7 @@ glossary styles defined in the \styfmt{glossary-tree} package \sty{classicthesis} has been loaded, the default style is \glostyle{index}, which is provided by \sty{glossary-tree}. -\item[\pkgoptdef{nostyles}] This prevents all the predefined styles +\pkgoptsec{nostyles} This prevents all the predefined styles from being loaded. If you use this option, you need to load a glossary style package (such as \sty{glossary-mcols}). Also if you use this option, you can't use the \pkgopt{style} package option. @@ -3800,7 +4196,7 @@ Instead you must either use \ics{setglossarystyle}\marg{style} or the \setglossarystyle{mcoltree} \end{verbatim} -\item[\pkgoptdef{nonumberlist}] This option will suppress the +\pkgoptsec{nonumberlist} This option will suppress the associated \glspl{numberlist} in the glossaries (see also \sectionref{sec:numberlists}). Note that if you use \optsor23 (\gls{makeindex} or \gls{xindy}) then the locations must still be @@ -3811,7 +4207,7 @@ indexed. Remember that \gls{numberlist} includes any cross-references, so suppressing the \gls{numberlist} will also hide the cross-references (see below). -\item[\pkgoptdef{seeautonumberlist}] If you suppress the +\pkgoptsec{seeautonumberlist} If you suppress the \glspl{numberlist} with \pkgopt{nonumberlist}, described above, this will also suppress any cross-referencing information supplied by the \gloskey{see} key in \ics{newglossaryentry} or \ics{glssee}. If you @@ -3820,30 +4216,252 @@ automatically implement \gloskey{nonumberlist=false} for that entry. (Note this doesn't affect \cs{glssee}.) For further details see \sectionref{sec:crossref}. -\item[\pkgoptdef{counter}] This is a \meta{key}=\meta{value} option. +\pkgoptsec[value]{counter} This is a \meta{key}=\meta{value} option. (Default is \pkgopt[page]{counter}.) The value should be the name of the default counter to use in the \glspl{numberlist} (see \sectionref{sec:numberlists}). -\item[\pkgoptdef{nopostdot}] This is a boolean option. If no value is -specified, \texttt{true} is assumed. When set to \texttt{true}, this -option suppresses the default post description dot used by some of -the predefined styles. The default setting is -\pkgopt[false]{nopostdot}. - -\item[\pkgoptdef{nogroupskip}] This is a boolean option. If no value is -specified, \texttt{true} is assumed. When set to \texttt{true}, this -option suppresses the default vertical gap between groups used by +\pkgoptsec[boolean]{nopostdot} This is a boolean option. If no value is +specified, \pkgoptval{true}{nopostdot} is assumed. When set to +\pkgoptval{true}{nopostdot}, this option suppresses the default post +description dot used by some of the predefined styles. + +The default setting is \pkgopt[false]{nopostdot} for the base +\styfmt{glossaries} package and \pkgopt[true]{nopostdot} for +\gls{glossaries-extra}. + +\begin{xtr} +The \gls{glossaries-extra} package provides \pkgopt*{postdot}, which +is equivalent to \pkgopt[false]{nopostdot}, and also +\pkgopt*{postpunc}, which allows you to choose a different +punctuation character. +\end{xtr} + +\pkgoptsec[boolean]{nogroupskip} This is a boolean option. If no value is +specified, \pkgoptfmt{true} is assumed. When set to \pkgoptfmt{true}, this +option suppresses the default vertical gap between letter groups used by some of the predefined styles. The default setting is \pkgopt[false]{nogroupskip}. +\begin{bib2gls} +If you are using \gls{bib2gls} without the \texttt{-{}-group} (or +\texttt{-g}) switch then you don't need to use +\pkgoptfmt{nogroupskip\dequals true} as there won't be any letter +groups. +\end{bib2gls} + +\xtrpkgoptsec[list]{stylemods} + +Load the \sty{glossaries-extra-stylemods} package and patch the +predefined styles. The \meta{list} argument is optional. If present, +this will also load \styfmt{glossary-\meta{element}.sty} for each +\meta{element} in the comma-separated \meta{list}. + +\section{Indexing Options} +\label{sec:pkgopts-indexing} + +\pkgoptsec[value]{seenoindex} Introduced in version 4.24, this option +may take one of three values: \pkgoptfmt{error}, \pkgoptfmt{warn} or +\pkgoptfmt{ignore}. The \gloskey{see} key automatically indexes the +cross-referenced entry using \cs{glsadd}. This means that if this +key is used in an entry definition before the relevant +glossary file has been opened, the indexing can't be performed. +Since this is easy to miss, the \styfmt{glossaries} package by +default issues an error message if the \gloskey{see} key is used +before \ics{makeglossaries}. This option allows you to change the +error into just a warning (\pkgopt[warn]{seenoindex}) or +ignore it (\pkgopt[ignore]{seenoindex}) if, for example, you want +to temporarily comment out \cs{makeglossaries} to speed up the +compilation of a draft document by omitting the indexing. + +\pkgoptsec[boolean]{esclocations} This is a boolean option. The +default is \pkgopt[true]{esclocations}, which is needed for +\optsand23. With \opt1 \ics{makenoidxglossaries} changes it to +\pkgopt[false]{esclocations}. With \opt4 (\gls{bib2gls}), this +setting is ignored. + +Both \gls{makeindex} and \gls{xindy} are fussy about the location +formats (\gls{makeindex} more so than \gls{xindy}) so the +\styfmt{glossaries} package tries to ensure that special characters +are escaped and allows for the location to be substituted for a +format that's more acceptable to the indexing application. This +requires a bit of trickery to circumvent the problem posed by \TeX's +asynchronous output routine, which can go wrong and also adds to the +complexity of the document build. + +If you're sure that your locations will always expand to an +acceptable format (or you're prepared to post-process the glossary +file before passing it to the relevant indexing application) then +use \pkgopt[false]{esclocations} to avoid the complex escaping of +location values. (See \ifpdf section~\ref*{sec:wrgloss} \fi +\qt{Writing information to associated files} in the documented code +for further details.) + +This isn't an issue for \optsor14 as the locations are written to +the \filetype{aux} file so no syntax conversion is required. + +\pkgoptsec[boolean]{indexonlyfirst} This is a boolean option that specifies +whether to only add information to the external glossary file on +\gls{firstuse}. The default is \pkgopt[false]{indexonlyfirst}, +which will add a line to the file every time one of the +\glslike\ or \glstextlike\ commands are used. Note that \ics{glsadd} +will always add information to the external glossary +file\footnote{bug fix in v4.16 has corrected the code to ensure +this.}\ (since that's the purpose of that command). + +\begin{important} +Resetting the \gls{firstuseflag} with commands like +\ics{glsreset} after an entry has been indexed will cause that entry to be +indexed multiple times if it's used again after the reset. +Likewise unsetting the \gls{firstuseflag} before an entry has been +indexed will prevent it from being indexed (unless specifically +indexed with \cs{glsadd}). +\end{important} + +You can customise this by redefining +\begin{definition}[\DescribeMacro\glswriteentry] +\cs{glswriteentry}\marg{label}\marg{wr-code} +\end{definition} +where \meta{label} is the entry's label and \meta{wr-code} is the +code that writes the entry's information to the external file. +The default definition of \cs{glswriteentry} is: +\begin{verbatim} +\newcommand*{\glswriteentry}[2]{% + \ifglsindexonlyfirst + \ifglsused{#1}{}{#2}% + \else + #2% + \fi +} +\end{verbatim} +This checks the \pkgopt{indexonlyfirst} package option (using +\cs{ifglsindexonlyfirst}) and does \meta{wr-code} if this is +\pkgoptfmt{false} otherwise it only does \meta{wr-code} of the entry +hasn't been used. + +For example, suppose you only want to index the first use for +entries in the \texttt{acronym} glossary and not in the +\texttt{main} (or any other) glossary: +\begin{verbatim} +\renewcommand*{\glswriteentry}[2]{% + \ifthenelse{\equal{\glsentrytype{#1}}{acronym}} + {\ifglsused{#1}{}{#2}}% + {#2}% +} +\end{verbatim} +Here I've used \cs{ifthenelse} to ensure the arguments of +\cs{equal} are fully expanded before the comparison is made. + +With the \gls{glossaries-extra} package it's possible to only index +\gls{firstuse} for particular categories. For example, if you only +want this enabled for abbreviations and acronyms then you can set +the \attr{indexonlyfirst} attribute for the \texttt{abbreviation} +and \texttt{acronym} categories. (Instead of using the +\pkgopt{indexonlyfirst} package option.) See the +\gls{glossaries-extra} manual for further details. + +\xtrpkgoptsec[boolean]{indexcrossrefs} + +If \pkgoptfmt{true}, this will automatically index any +cross-referenced entries that haven't been marked as used at the end +of the document. Increases document build time. See +\gls{glossaries-extra} manual for further details. + +\xtrpkgoptsec[boolean]{autoseeindex} + +If \pkgoptfmt{true}, makes the \gloskey{see} and +\xtrgloskey{seealso} keys automatically index the cross-reference +when the entry is defined (default, and the only option with just +the base \styfmt{glossaries} package). + +\xtrpkgoptsec[value]{record} + +If not \pkgoptfmt{off}, this option indicates that \gls{bib2gls} +is required. If the value is omitted, \pkgoptfmt{only} is assumed. Permitted values: +\begin{description} +\item[\pkgoptfmt{off}] \gls{bib2gls} isn't being used; + +\item[\pkgoptfmt{only}] \gls{bib2gls} is being used to fetch entries +from a \filetype{bib} file, to sort the entries and collate the +\glspl{numberlist}, where the location information is the same as +for \optsto13; + +\item[\pkgoptfmt{nameref}] like \pkgoptfmt{only} but provides extra +information that allows the associated title to be used instead of +the location number; + +\item[\pkgoptfmt{alsoindex}] a hybrid approach where \gls{bib2gls} +is begin used to fetch entries from a \filetype{bib} file but +\gls{makeindex} or \gls{xindy} are used for the indexing. This +requires a more complicated document build and isn't recommended. \end{description} +See \gls{glossaries-extra} manual for further details. + +\xtrpkgoptsec[boolean]{equations} + +If \pkgoptfmt{true}, this option will cause the default location +counter to automatically switch to \texttt{equation} when inside a +numbered equation environment. + +\xtrpkgoptsec[boolean]{floats} + +If \pkgoptfmt{true}, this option will cause the default location +counter to automatically switch to the corresponding counter when inside a +float. (Remember that with floats it's the \cs{caption} command that +increments the counter so the location will be incorrect if an entry +is indexed within the float before the caption.) + +\xtrpkgoptsec{indexcounter} + +This valueless option is primarily intended for use with +\gls{bib2gls} and \sty{hyperref} allowing the page location +hyperlink to the relevant point in the page (rather than the top of +the page). Unexpected results will occur with other indexing +methods. See \gls{glossaries-extra} manual for further details. \section{Sorting Options} \label{sec:pkgopts-sort} -\begin{description} -\item[\pkgoptdef{sort}] If you use \optsor23, this package option is +This section is mostly for \optsand23. Only the \pkgopt{sort} and +\pkgopt{order} options are applicable for \opt1. + +\begin{xtr} +With \optsto46, only \pkgopt[none]{sort} is applicable (and this is +automatically implemented by \pkgopt+{only}{record} and +\pkgopt+{nameref}{record}). With \gls{bib2gls}, the sort method +is provided in the optional argument of \ics*{GlsXtrLoadResources} +not with the \pkgoptfmt{sort} package option. There's no sorting +with \optsand56. +\end{xtr} + +\pkgoptsec[boolean]{sanitizesort} This is a boolean option that +determines whether or not to \gls{sanitize} the sort value when +writing to the external glossary file. For example, suppose you +define an entry as follows: +\begin{verbatim} +\newglossaryentry{hash}{name={\#},sort={#}, + description={hash symbol}} +\end{verbatim} +The sort value (\verb|#|) must be sanitized before writing it to the +glossary file, otherwise \LaTeX\ will try to interpret it as a +parameter reference. If, on the other hand, you want the sort value +expanded, you need to switch off the sanitization. For example, +suppose you do: +\begin{verbatim} +\newcommand{\mysortvalue}{AAA} +\newglossaryentry{sample}{% + name={sample}, + sort={\mysortvalue}, + description={an example}} +\end{verbatim} +and you actually want \cs{mysortvalue} expanded, so that the entry +is sorted according to \texttt{AAA}, then use the package option +\pkgopt[false]{sanitizesort}. + +The default for \optsand23 is \pkgopt[true]{sanitizesort}, and the +default for \opt1 is \pkgopt[false]{sanitizesort}. + +\pkgoptsec[value]{sort} If you use \optsor23, this package option is the only way of specifying how to sort the glossaries. Only \opt1 allows you to specify sort methods for individual glossaries via the \gloskey[printnoidxglossary]{sort} key in the optional @@ -3884,11 +4502,13 @@ and is only for documents that don't use \cs{makeglossaries} (\optsor23) or \cs{makenoidxglossaries} (\opt1). It omits the code used to sanitize or escape the sort value, since it's not required. This can help to improve the document build speed, especially if there are a large -number of entries. This option +number of entries. + +This option can't be used with \cs{printglossary} or \cs{printnoidxglossary} (or the iterative versions \cs{printglossaries} or \cs{printnoidxglossaries}). It may be used with -\sty{glossaries-extra}'s \cs{printunsrtglossary} (\opt5). +\gls{glossaries-extra}'s \cs{printunsrtglossary} (\opt5). \end{itemize} Note that the group styles (such as \glostyle{listgroup}) are incompatible with the \pkgopt[use]{sort} and \pkgopt[def]{sort} @@ -3930,8 +4550,8 @@ I want the \texttt{main} and \texttt{acronym} glossaries to be sorted alphabetically, but the \texttt{notation} type should be sorted in order of definition. -For \opt1, I~just need to set the \gloskey[printnoidxglossary]{sort} key in -the optional argument of \ics{printnoidxglossary}: +For \opt1, the \gloskey[printnoidxglossary]{sort} option can be +used in \ics{printnoidxglossary}: \begin{verbatim} \printnoidxglossary[sort=word] \printnoidxglossary[type=acronym,sort=word] @@ -4021,12 +4641,12 @@ Now the entries can be defined: For a complete document, see the sample file \samplefile{People}. \end{example} -\item[\pkgoptdef{order}] This may take two values: +\pkgoptsec[value]{order} This may take two values: \pkgoptval{word}{order} or \pkgoptval{letter}{order}. The default is word ordering. \begin{important} -Note that the \pkgopt{order} option has no effect if you don't use +Note that with \optsand23, the \pkgopt{order} option has no effect if you don't use \gls{makeglossaries}. \end{important} @@ -4042,24 +4662,29 @@ Alternatively, you can specify the order for individual glossaries: \printnoidxglossary[type=acronym,sort=letter] \end{verbatim} -\item[\pkgoptdef{makeindex}] (\opt2) The glossary information and +\begin{bib2gls} +With \gls{bib2gls}, use the \resourceopt{break-at} option +in \ics*{GlsXtrLoadResources} instead of \pkgoptfmt{order}. +\end{bib2gls} + +\pkgoptsec{makeindex} (\opt2) The glossary information and indexing style file will be written in \gls{makeindex} format. If you use \gls{makeglossaries}, it will automatically detect that it needs to call \gls*{makeindex}. If you don't use \gls*{makeglossaries}, you need to remember to use \gls*{makeindex} not \gls{xindy}. The indexing style file will been given -a~\filetype{.ist} extension. +a~\filetype{ist} extension. You may omit this package option if you are using \opt2 as this is the default. It's available in case you need to override the effect of an earlier occurrence of \pkgopt{xindy} in the package option list. -\item[\pkgoptdef{xindy}] (\opt3) The glossary information and indexing style +\pkgoptsec{xindy} (\opt3) The glossary information and indexing style file will be written in \gls{xindy} format. If you use \gls{makeglossaries}, it will automatically detect that it needs to call \gls*{xindy}. If you don't use \gls*{makeglossaries}, you need to remember to use \gls*{xindy} not \gls{makeindex}. The indexing style -file will been given a \filetype{.xdy} extension. +file will been given a \filetype{xdy} extension. This package option may additionally have a value that is a \meta{key}=\meta{value} comma-separated list to override the @@ -4079,17 +4704,17 @@ language, codepage and number group settings are unchanged. See \sectionref{sec:xindy} for further details on using \gls{xindy} with the \styfmt{glossaries} package. -\item[\pkgoptdef{xindygloss}] (\opt3) This is equivalent to +\pkgoptsec{xindygloss} (\opt3) This is equivalent to \verb|xindy={}| (that is, the \pkgopt{xindy} option without any value supplied) and may be used as a document class option. The language and code page can be set via \ics{GlsSetXdyLanguage} and \ics{GlsSetXdyCodePage} (see \sectionref{sec:langenc}.) -\item[\pkgoptdef{xindynoglsnumbers}] (\opt3) This is equivalent to +\pkgoptsec{xindynoglsnumbers} (\opt3) This is equivalent to \verb|xindy={glsnumbers=false}| and may be used as a document class option. -\item[\pkgoptdef{automake}] This is option was introduced to +\pkgoptsec[value]{automake} This is option was introduced to version 4.08 as a boolean option. As from version 4.42 it may now take three values: \texttt{false} (default), \texttt{true} or \texttt{immediate}. If no option is supplied, \texttt{immediate} @@ -4139,55 +4764,292 @@ those who can't work out how to incorporate the \gls*{indexingapp} into their document build. The default value for this option is \pkgopt[false]{automake}. -\end{description} +\pkgoptsec{disablemakegloss} This valueless option +indicates that \ics{makeglossaries} and \ics{makenoidxglossaries} +should be disabled. This option is provided in the event that you +have to use a class or package that disregards the advice in +\sectionref{sec:indexingoptions} and automatically performs +\ics{makeglossaries} or \ics{makenoidxglossaries} but you don't want +this. (For example, you want to use a different indexing method or +you want to disable indexing while working on a draft +document.) + +This option may be passed in the standard document class option list +or passed using \cs{PassOptionsToPackage} before \sty{glossaries} is +loaded. Note that this does nothing if +\ics{makeglossaries} or \ics{makenoidxglossaries} has already +been used whilst enabled. + +\pkgoptsec{restoremakegloss} Cancels the effect of +\pkgopt{disablemakegloss}. This option may be used in +\cs{setupglossaries}. It issues a warning if \ics{makeglossaries} or +\ics{makenoidxglossaries} has already been used whilst enabled. +For example, suppose the class \clsfmt{customclass.cls} +automatically loads \styfmt{glossaries} and does \cs{makeglossaries} +but you need an extra glossary, which has to be defined before +\cs{makeglossaries}, then you can do: +\begin{verbatim} +\documentclass[disablemakegloss]{customclass} +\newglossary*{functions}{Functions} +\setupglossaries{restoremakegloss} +\makeglossaries +\end{verbatim} +or +\begin{verbatim} +\PassOptionsToPackage{disablemakegloss}{glossaries} +\documentclass{customclass} +\newglossary*{functions}{Functions} +\setupglossaries{restoremakegloss} +\makeglossaries +\end{verbatim} -\section{Acronym Options} -\label{sec:pkgopts-acronym} +Note that restoring these commands doesn't necessarily mean that they can be +used. It just means that their normal behaviour given the current +settings will apply. For example, if you use the \pkgopt+{only}{record} +or \pkgopt+{nameref}{record} options with \gls{glossaries-extra} +then you can't use \cs{makeglossaries} or \cs{makenoidxglossaries} +regardless of \pkgopt{restoremakegloss}. -\begin{description} -\item[\pkgoptdef{acronym}] This creates a new glossary with the -label \texttt{acronym}. This is equivalent to: +\section{Glossary Type Options} +\label{sec:pkgopts-type} + +\pkgoptsec[list]{nohypertypes} Use this option if you have multiple +glossaries and you want to suppress the entry hyperlinks for a +particular glossary or glossaries. The value of this option should +be a comma-separated list of glossary types where \ics{gls} etc +shouldn't have hyperlinks by default. Make sure you enclose the +value in braces if it contains any commas. Example: \begin{verbatim} -\newglossary[alg]{acronym}{acr}{acn}{\acronymname} +\usepackage[acronym,nohypertypes={acronym,notation}] + {glossaries} +\newglossary[nlg]{notation}{not}{ntn}{Notation} \end{verbatim} -It will also define -\begin{definition}[\DescribeMacro\printacronyms] -\cs{printacronyms}\oarg{options} +The values must be fully expanded, so \strong{don't} try +\texttt{nohypertypes\discretionary{}{}{}=\ics{acronymtype}}. You may also use +\begin{definition} +\ics{GlsDeclareNoHyperList}\marg{list} \end{definition} -that's equivalent to -\begin{alltt} -\ics{printglossary}[type=acronym,\meta{options}] -\end{alltt} -(unless that command is already defined before the beginning of the -document or the package option \pkgopt{compatible-3.07} is used). - -If you are using \opt1, you need to use -\begin{alltt} -\ics{printnoidxglossary}[type=acronym,\meta{options}] -\end{alltt} -to display the list of acronyms. +instead or additionally. +See \sectionref{sec:glslink} for further details. -If the \pkgopt{acronym} package option is used, \ics{acronymtype} -is set to \texttt{acronym} otherwise it is set to -\texttt{main}.\footnote{Actually it sets \ics{acronymtype} to -\ics{glsdefaulttype} if the \pkgopt{acronym} package option is -not used, but \ics{glsdefaulttype} usually has the value -\texttt{main} unless the \pkgopt{nomain} option has been used.} -Entries that are defined using \ics{newacronym} are placed in -the glossary whose label is given by \ics{acronymtype}, unless -another glossary is explicitly specified. +\pkgoptsec{nomain} This suppresses the creation of the main +glossary and associated \filetype{glo} file, if unrequired. Note that +if you use this option, you must create another glossary in which to +put all your entries (either via the \pkgopt{acronym} (or +\pkgopt{acronyms}) package option described in +\sectionref{sec:pkgopts-acronym} or via the \pkgopt{symbols}, +\pkgopt{numbers} or \pkgopt{index} options described in +\sectionref{sec:pkgopts-other} or via \ics{newglossary} described in +\sectionref{sec:newglossary}). \begin{important} -Remember to use the \pkgopt{nomain} package option if you're only -interested in using this \texttt{acronym} glossary. (That is, you -don't intend to use the \texttt{main} glossary.) +If you don't use the main glossary and you don't use this option, +\gls{makeglossaries} will produce a warning. +\end{important} +\begin{alltt} +Warning: File '\emph{filename}.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. +\end{alltt} +If you did actually want to use the main glossary and you see this +warning, check that you have referenced the entries in that glossary +via commands such as \ics{gls}. + +\pkgoptsec{symbols} This valueless option defines a new glossary type with +the label \texttt{symbols} via +\begin{verbatim} +\newglossary[slg]{symbols}{sls}{slo}{\glssymbolsgroupname} +\end{verbatim} +It also defines +\begin{definition}[\DescribeMacro\printsymbols] +\cs{printsymbols}\oarg{options} +\end{definition} +which is a synonym for +\begin{alltt} +\ics{printglossary}[type=symbols,\meta{options}] +\end{alltt} + +If you use \opt1, you need to use: +\begin{alltt} +\ics{printnoidxglossary}[type=symbols,\meta{options}] +\end{alltt} +to display the list of symbols. + +\begin{important} +Remember to use the \pkgopt{nomain} package option if you're only +interested in using this \texttt{symbols} glossary and don't intend +to use the \texttt{main} glossary. +\end{important} + +\begin{xtr} +The \gls{glossaries-extra} package has a slightly modified +version of this option which additionally provides \ics*{glsxtrnewsymbol} +as a convenient shortcut method for defining symbols. See the +\gls{glossaries-extra} manual for further details. +\end{xtr} + +\pkgoptsec{numbers} This valueless option defines a new glossary type with +the label \texttt{numbers} via +\begin{verbatim} +\newglossary[nlg]{numbers}{nls}{nlo}{\glsnumbersgroupname} +\end{verbatim} +It also defines +\begin{definition}[\DescribeMacro\printnumbers] +\cs{printnumbers}\oarg{options} +\end{definition} +which is a synonym for +\begin{alltt} +\ics{printglossary}[type=numbers,\meta{options}] +\end{alltt} + +If you use \opt1, you need to use: +\begin{alltt} +\ics{printnoidxglossary}[type=numbers,\meta{options}] +\end{alltt} +to display the list of numbers. + +\begin{important} +Remember to use the \pkgopt{nomain} package option if you're only +interested in using this \texttt{numbers} glossary and don't intend +to use the \texttt{main} glossary. +\end{important} + +\begin{xtr} +The \gls{glossaries-extra} package has a slightly modified +version of this option which additionally provides \ics*{glsxtrnewnumber} +as a convenient shortcut method for defining numbers. See the +\gls{glossaries-extra} manual for further details. +\end{xtr} + +\pkgoptsec{index} This valueless option defines a new glossary type with +the label \texttt{index} via +\begin{verbatim} +\newglossary[ilg]{index}{ind}{idx}{\indexname}% +\end{verbatim} +It also defines +\begin{definition}[\DescribeMacro\newterm] +\cs{newterm}\oarg{options}\marg{term} +\end{definition} +which is a synonym for +\begin{alltt} +\ics{newglossaryentry}\marg{term}[type=index,name=\marg{term},% +description=\ics{nopostdesc},\meta{options}] +\end{alltt} +and +\begin{definition}[\DescribeMacro\printindex] +\cs{printindex}\oarg{options} +\end{definition} +which is a synonym for +\begin{alltt} +\ics{printglossary}[type=index,\meta{options}] +\end{alltt} + +If you use \opt1, you need to use: +\begin{alltt} +\ics{printnoidxglossary}[type=index,\meta{options}] +\end{alltt} +to display this glossary. + +\begin{important} +Remember to use the \pkgopt{nomain} package option if you're only +interested in using this \texttt{index} glossary and don't intend to +use the \texttt{main} glossary. Note that you +can't mix this option with \ics{index}. Either use +\styfmt{glossaries} for the indexing or use a~custom indexing +package, such as \sty{makeidx}, \sty{index} or \sty{imakeidx}. +(You can, of course, load one of those packages and +load \styfmt{glossaries} without the \pkgopt{index} package option.) +\end{important} + +Since the index isn't designed for terms with descriptions, you +might also want to disable the hyperlinks for this glossary using +the package option \pkgopt[index]{nohypertypes} or the command +\begin{display} +\ics{GlsDeclareNoHyperList}\verb|{index}| +\end{display} + +The example file \samplefile{-index} illustrates the use of the +\pkgopt{index} package option. + +\pkgoptsec{noglossaryindex} This valueless option switches off \pkgopt{index} +if \pkgopt{index} has been passed implicitly (for example, +through global document options). This option can't be used +in \cs{setupglossaries}. + + +\section{Acronym and Abbreviation Options} +\label{sec:pkgopts-acronym} + +\pkgoptsec[boolean]{acronym} If true, this creates a new glossary with the +label \texttt{acronym}. This is equivalent to: +\begin{verbatim} +\newglossary[alg]{acronym}{acr}{acn}{\acronymname} +\end{verbatim} +It will also define +\begin{definition}[\DescribeMacro\printacronyms] +\cs{printacronyms}\oarg{options} +\end{definition} +that's equivalent to +\begin{alltt} +\ics{printglossary}[type=acronym,\meta{options}] +\end{alltt} +(unless that command is already defined before the beginning of the +document or the package option \pkgopt{compatible-3.07} is used). + +If you are using \opt1, you need to use +\begin{alltt} +\ics{printnoidxglossary}[type=acronym,\meta{options}] +\end{alltt} +to display the list of acronyms. + +If the \pkgopt{acronym} package option is used, \ics{acronymtype} +is set to \texttt{acronym} otherwise it is set to +\texttt{main}.\footnote{Actually it sets \ics{acronymtype} to +\ics{glsdefaulttype} if the \pkgopt{acronym} package option is +not used, but \ics{glsdefaulttype} usually has the value +\texttt{main} unless the \pkgopt{nomain} option has been used.} +Entries that are defined using \ics{newacronym} are placed in +the glossary whose label is given by \ics{acronymtype}, unless +another glossary is explicitly specified. + +\begin{important} +Remember to use the \pkgopt{nomain} package option if you're only +interested in using this \texttt{acronym} glossary. (That is, you +don't intend to use the \texttt{main} glossary.) \end{important} -\item[\pkgoptdef{acronyms}] This is equivalent to +\begin{xtr} +The \gls{glossaries-extra} extension package comes with an analogous +\pkgopt*{abbreviations} option, which creates a new glossary with +the label \texttt{abbreviations} and sets the command +\ics*{glsxtrabbrvtype} to this. If the \pkgopt{acronym} option hasn't +also been used, then \ics{acronymtype} will be set to +\ics*{glsxtrabbrvtype}. This enables both \ics{newacronym} and +\ics*{newabbreviation} to use the same glossary. + +Make sure you have at least v1.42 of \gls{glossaries-extra} if you +use the \pkgopt{acronym} (or \pkgopt{acronyms}) package option with +the extension package to avoid a bug that interferes with the +abbreviation style. +\end{xtr} + +\pkgoptsec{acronyms} This is equivalent to \pkgopt[true]{acronym} and may be used in the document class option list. -\item[\pkgoptdef{acronymlists}] By default, only the \cs{acronymtype} +\xtrpkgoptsec{abbreviations} + +This valueless option creates a new glossary type using: +\begin{verbatim} +\newglossary[glg-abr]{abbreviations}{gls-abr}{glo-abr}{\abbreviationsname} +\end{verbatim} +The label can be accessed with \ics*{glsxtrabbrvtype}, which is +analogous to \cs{acronymtype}. See \gls{glossaries-extra} manual for +further details. + +\pkgoptsec[value]{acronymlists} By default, only the \cs{acronymtype} glossary is considered to be a list of acronyms. If you have other lists of acronyms, you can specify them as a comma-separated list in the value of \pkgopt{acronymlists}. For example, if you use the @@ -4222,13 +5084,21 @@ of acronyms using: \cs{glsIfListOfAcronyms}\marg{label}\marg{true part}\marg{false part} \end{definition} -\item[\pkgoptdef{shortcuts}] This option provides shortcut commands +\begin{xtr} +This option is incompatible with \gls{glossaries-extra}['s] +abbreviation mechanism. +\end{xtr} + +\pkgoptsec{shortcuts} This option provides shortcut commands for acronyms. See \sectionref{sec:acronyms} for further details. Alternatively you can use: \begin{definition}[\DescribeMacro\DefineAcronymSynonyms] \cs{DefineAcronymSynonyms} \end{definition} -\end{description} + +\begin{xtr} +The \gls{glossaries-extra} package provides additional shortcuts. +\end{xtr} \subsection{Deprecated Acronym Style Options} \label{sec:pkgopts-old-acronym} @@ -4237,54 +5107,53 @@ The package options listed in this section are now deprecated but are kept for backward-compatibility. Use \ics{setacronymstyle} instead. See \sectionref{sec:acronyms} for further details. -\begin{description} -\item[\pkgoptdef{description}] This option changes the definition of +\deppkgoptsec{description} This option changes the definition of \ics{newacronym} to allow a description. This option may be replaced by \begin{verbatim} \setacronymstyle{long-short-desc} \end{verbatim} -or (with \pkgopt{smallcaps}) +or (with \deprecatedpkgopt{smallcaps}) \begin{verbatim} \setacronymstyle{long-sc-short-desc} \end{verbatim} -or (with \pkgopt{smaller}) +or (with \deprecatedpkgopt{smaller}) \begin{verbatim} \setacronymstyle{long-sm-short-desc} \end{verbatim} -or (with \pkgopt{footnote}) +or (with \deprecatedpkgopt{footnote}) \begin{verbatim} \setacronymstyle{footnote-desc} \end{verbatim} -or (with \pkgopt{footnote} and \pkgopt{smallcaps}) +or (with \deprecatedpkgopt{footnote} and \deprecatedpkgopt{smallcaps}) \begin{verbatim} \setacronymstyle{footnote-sc-desc} \end{verbatim} -or (with \pkgopt{footnote} and \pkgopt{smaller}) +or (with \deprecatedpkgopt{footnote} and \deprecatedpkgopt{smaller}) \begin{verbatim} \setacronymstyle{footnote-sm-desc} \end{verbatim} -or (with \pkgopt{dua}) +or (with \deprecatedpkgopt{dua}) \begin{verbatim} \setacronymstyle{dua-desc} \end{verbatim} -\item[\pkgoptdef{smallcaps}] This option changes the definition of +\deppkgoptsec{smallcaps} This option changes the definition of \ics{newacronym} and the way that acronyms are displayed. This option may be replaced by: \begin{verbatim} \setacronymstyle{long-sc-short} \end{verbatim} -or (with \pkgopt{description}) +or (with \deprecatedpkgopt{description}) \begin{verbatim} \setacronymstyle{long-sc-short-desc} \end{verbatim} -or (with \pkgopt{description} and \pkgopt{footnote}) +or (with \deprecatedpkgopt{description} and \deprecatedpkgopt{footnote}) \begin{verbatim} \setacronymstyle{footnote-sc-desc} \end{verbatim} -\item[\pkgoptdef{smaller}] This option changes the definition of +\deppkgoptsec{smaller} This option changes the definition of \ics{newacronym} and the way that acronyms are displayed. \begin{important} If you use this option, you will need to include the \sty{relsize} @@ -4295,193 +5164,86 @@ This option may be replaced by: \begin{verbatim} \setacronymstyle{long-sm-short} \end{verbatim} -or (with \pkgopt{description}) +or (with \deprecatedpkgopt{description}) \begin{verbatim} \setacronymstyle{long-sm-short-desc} \end{verbatim} -or (with \pkgopt{description} and \pkgopt{footnote}) +or (with \deprecatedpkgopt{description} and \deprecatedpkgopt{footnote}) \begin{verbatim} \setacronymstyle{footnote-sm-desc} \end{verbatim} -\item[\pkgoptdef{footnote}] This option changes the definition of +\deppkgoptsec{footnote} This option changes the definition of \ics{newacronym} and the way that acronyms are displayed. This option may be replaced by: \begin{verbatim} \setacronymstyle{footnote} \end{verbatim} -or (with \pkgopt{smallcaps}) +or (with \deprecatedpkgopt{smallcaps}) \begin{verbatim} \setacronymstyle{footnote-sc} \end{verbatim} -or (with \pkgopt{smaller}) +or (with \deprecatedpkgopt{smaller}) \begin{verbatim} \setacronymstyle{footnote-sm} \end{verbatim} -or (with \pkgopt{description}) +or (with \deprecatedpkgopt{description}) \begin{verbatim} \setacronymstyle{footnote-desc} \end{verbatim} -or (with \pkgopt{smallcaps} and \pkgopt{description}) +or (with \deprecatedpkgopt{smallcaps} and \deprecatedpkgopt{description}) \begin{verbatim} \setacronymstyle{footnote-sc-desc} \end{verbatim} -or (with \pkgopt{smaller} and \pkgopt{description}) +or (with \deprecatedpkgopt{smaller} and \deprecatedpkgopt{description}) \begin{verbatim} \setacronymstyle{footnote-sm-desc} \end{verbatim} - -\item[\pkgoptdef{dua}] This option changes the definition of +\deppkgoptsec{dua} This option changes the definition of \ics{newacronym} so that acronyms are always expanded. This option may be replaced by: \begin{verbatim} \setacronymstyle{dua} \end{verbatim} -or (with \pkgopt{description}) +or (with \deprecatedpkgopt{description}) \begin{verbatim} \setacronymstyle{dua-desc} \end{verbatim} -\end{description} - \section{Other Options} \label{sec:pkgopts-other} Other available options that don't fit any of the above categories -are: -\begin{description} -\item[\pkgoptdef{symbols}] This option defines a new glossary type with -the label \texttt{symbols} via -\begin{verbatim} -\newglossary[slg]{symbols}{sls}{slo}{\glssymbolsgroupname} -\end{verbatim} -It also defines -\begin{definition}[\DescribeMacro\printsymbols] -\cs{printsymbols}\oarg{options} -\end{definition} -which is a synonym for -\begin{alltt} -\ics{printglossary}[type=symbols,\meta{options}] -\end{alltt} +are described below. -If you use \opt1, you need to use: -\begin{alltt} -\ics{printnoidxglossary}[type=symbols,\meta{options}] -\end{alltt} -to display the list of symbols. +\xtrpkgoptsec{accsupp} -\begin{important} -Remember to use the \pkgopt{nomain} package option if you're only -interested in using this \texttt{symbols} glossary and don't intend -to use the \texttt{main} glossary. -\end{important} +Load the \sty{glossaries-accsupp} package. -The \styfmt{glossaries-extra} package has a slightly modified -version of this option which additionally provides \ics{glsxtrnewsymbol} -as a convenient shortcut method for defining symbols. See the -\styfmt{glossaries-extra} manual for further details. +\xtrpkgoptsec{prefix} -\item[\pkgoptdef{numbers}] This option defines a new glossary type with -the label \texttt{numbers} via -\begin{verbatim} -\newglossary[nlg]{numbers}{nls}{nlo}{\glsnumbersgroupname} -\end{verbatim} -It also defines -\begin{definition}[\DescribeMacro\printnumbers] -\cs{printnumbers}\oarg{options} -\end{definition} -which is a synonym for -\begin{alltt} -\ics{printglossary}[type=numbers,\meta{options}] -\end{alltt} +Load the \sty{glossaries-prefix} package. -If you use \opt1, you need to use: -\begin{alltt} -\ics{printnoidxglossary}[type=numbers,\meta{options}] -\end{alltt} -to display the list of numbers. +\xtrpkgoptsec[boolean]{nomissingglstext} -\begin{important} -Remember to use the \pkgopt{nomain} package option if you're only -interested in using this \texttt{numbers} glossary and don't intend -to use the \texttt{main} glossary. -\end{important} +This option may be used to suppress the boilerplate text generated +by \cs{printglossary} if the glossary file is missing. -The \styfmt{glossaries-extra} package has a slightly modified -version of this option which additionally provides \ics{glsxtrnewnumber} -as a convenient shortcut method for defining numbers. See the -\styfmt{glossaries-extra} manual for further details. +\pkgoptsec[boolean]{compatible-2.07} Compatibility mode for old documents +created using version 2.07 or below. -\item[\pkgoptdef{index}] This option defines a new glossary type with -the label \texttt{index} via -\begin{verbatim} -\newglossary[ilg]{index}{ind}{idx}{\indexname}% -\end{verbatim} -It also defines -\begin{definition}[\DescribeMacro\newterm] -\cs{newterm}\oarg{options}\marg{term} -\end{definition} -which is a synonym for -\begin{alltt} -\ics{newglossaryentry}\marg{term}[type=index,name=\marg{term},% -description=\ics{nopostdesc},\meta{options}] -\end{alltt} -and -\begin{definition}[\DescribeMacro\printindex] -\cs{printindex}\oarg{options} -\end{definition} -which is a synonym for -\begin{alltt} -\ics{printglossary}[type=index,\meta{options}] -\end{alltt} +\pkgoptsec[boolean]{compatible-3.07} Compatibility mode for old documents +created using version 3.07 or below. -If you use \opt1, you need to use: -\begin{alltt} -\ics{printnoidxglossary}[type=index,\meta{options}] -\end{alltt} -to display this glossary. - -\begin{important} -Remember to use the \pkgopt{nomain} package option if you're only -interested in using this \texttt{index} glossary and don't intend to -use the \texttt{main} glossary. Note that you -can't mix this option with \ics{index}. Either use -\styfmt{glossaries} for the indexing or use a~custom indexing -package, such as \sty{makeidx}, \sty{index} or \sty{imakeidx}. -(You can, of course, load one of those packages and -load \styfmt{glossaries} without the \pkgopt{index} package option.) -\end{important} - -Since the index isn't designed for terms with descriptions, you -might also want to disable the hyperlinks for this glossary using -the package option \pkgopt[index]{nohypertypes} or the command -\begin{display} -\ics{GlsDeclareNoHyperList}\verb|{index}| -\end{display} - -The example file \samplefile{-index} illustrates the use of the -\pkgopt{index} package option. - -\item[\pkgoptdef{noglossaryindex}] This option switches off \pkgopt{index} -if \pkgopt{index} has been passed implicitly (for example, -through global document options). This option can't be used -in \cs{setupglossaries}. - -\item[\pkgoptdef{compatible-2.07}] Compatibility mode for old documents -created using version 2.07 or below. - -\item[\pkgoptdef{compatible-3.07}] Compatibility mode for old documents -created using version 3.07 or below. - -\item[\pkgoptdef{kernelglossredefs}] As a legacy from the precursor -\sty{glossary} package, the standard glossary commands provided -by the \LaTeX\ kernel (\cs{makeglossary} and \cs{glossary}) are -redefined in terms of the \styfmt{glossaries} package's commands. -However, they were never documented in this user manual, and the -conversion guide (\htmldoc{Upgrading from the glossary package to the -glossaries package}{glossary2glossaries}) explicitly discourages -their use. +\pkgoptsec[value]{kernelglossredefs} As a legacy from the precursor +\sty{glossary} package, the standard glossary commands provided +by the \LaTeX\ kernel (\cs{makeglossary} and \cs{glossary}) are +redefined in terms of the \styfmt{glossaries} package's commands. +However, they were never documented in this user manual, and the +conversion guide (\htmldoc{Upgrading from the glossary package to the +glossaries package}{glossary2glossaries}) explicitly discourages +their use. The use of those kernel commands (instead of the appropriate commands documented in this user guide) are deprecated, and you will @@ -4503,7 +5265,7 @@ This option may take one of three values: \pkgoptfmt{true} previous definitions) or \pkgoptfmt{nowarn} (redefine without warnings, not recommended). -Note that the only glossary-related commands provided by the \LaTeX\ +The only glossary-related commands provided by the \LaTeX\ kernel are \cs{makeglossary} and \cs{glossary}. Other packages or classes may provide additional glossary-related commands or environments that conflict with \styfmt{glossaries} (such as @@ -4517,8 +5279,6 @@ In general, if possible, it's best to stick with just one package that provides a glossary mechanism. (The \styfmt{glossaries} package does check for the \sty{doc} package and patches \cs{PrintChanges}.) -\end{description} - \section{Setting Options After the Package is Loaded} \label{sec:setupglossaries} @@ -4527,7 +5287,7 @@ Some of the options described above may also be set after the \begin{definition}[\DescribeMacro{\setupglossaries}] \cs{setupglossaries}\marg{key-val list} \end{definition} -The following package options \textbf{can't} be used in +The following package options \strong{can't} be used in \cs{setupglossaries}: \pkgopt{xindy}, \pkgopt{xindygloss}, \pkgopt{xindynoglsnumbers}, \pkgopt{makeindex}, \pkgopt{nolong}, \pkgopt{nosuper}, \pkgopt{nolist}, @@ -4542,7 +5302,7 @@ using commands like \ics{GlsSetXdyLanguage} (see If you need to use this command, use it as soon as possible after loading \styfmt{glossaries} otherwise you might end up using it too late for the change to take effect. For example, -if you try changing the acronym styles (such as \pkgopt{smallcaps}) +if you try changing the acronym styles (such as \deprecatedpkgopt{smallcaps}) after you have started defining your acronyms, you are likely to get unexpected results. If you try changing the sort option after you have started to define entries, you may get unexpected results. @@ -4566,7 +5326,7 @@ The command \end{definition} must be placed in the preamble. This sets up the internal commands required to make \opt1 work. -\textbf{If you omit \cs{makenoidxglossaries} none of +\strong{If you omit \cs{makenoidxglossaries} none of the glossaries will be displayed.} \section[Options 2 and 3]{\ifpdf\optsand23\else Options 2 and 3\fi} @@ -4577,22 +5337,26 @@ The command \cs{makeglossaries} \end{definition} must be placed in the preamble in order to create the customised -\gls{makeindex} (\filetype{.ist}) or \gls{xindy} (\filetype{.xdy}) +\gls{makeindex} (\filetype{ist}) or \gls{xindy} (\filetype{xdy}) style file (for \optsor23, respectively) and to ensure that glossary entries are written to the appropriate output files. -\textbf{If you omit \cs{makeglossaries} none of +\strong{If you omit \cs{makeglossaries} none of the glossary files will be created.} -\begin{important} +\begin{xtr} +If you are using \gls{glossaries-extra}, \cs{makeglossaries} has an +optional argument that allows you to have a hybrid of \optsor12 or +\optsor13. See \gls{glossaries-extra} manual for further details. +\end{xtr} + +\importantpar Note that some of the commands provided by the \styfmt{glossaries} package must not be used after \cs{makeglossaries} as they are required when creating the customised style file. If you attempt to use those commands after \cs{makeglossaries} you will generate an error. - Similarly, there are some commands that must not be used before \cs{makeglossaries}. -\end{important} You can suppress the creation of the customised \gls{xindy} or \gls{makeindex} style file using @@ -4601,14 +5365,14 @@ or \gls{makeindex} style file using \end{definition} That this command must not be used after \cs{makeglossaries}. \begin{important} -Note that if you have a custom \filetype{.xdy} file created when using +Note that if you have a custom \filetype{xdy} file created when using \styfmt{glossaries} version 2.07 or below, you will need to use the \pkgopt{compatible-2.07} package option with it. \end{important} The default name for the customised style file is given by -\ics{jobname}\filetype{.ist} (\opt2) or -\ics{jobname}\filetype{.xdy} (\opt3). This name may be +\ics{jobname}\filetype{ist} (\opt2) or +\ics{jobname}\filetype{xdy} (\opt3). This name may be changed using: \begin{definition}[\DescribeMacro{\setStyleFile}] \cs{setStyleFile}\marg{name} @@ -4662,8 +5426,8 @@ definitions that avoids some of the issues discussed in \begin{important} \opt1 enforces the preamble-only restriction on \ics{newglossaryentry}. \opt4 requires that definitions are provided -in \texttt{.bib} format. \opt5 requires either preamble-only -definitions or the use of the \sty{glossaries-extra} package option +in \filetype{bib} format. \opt5 requires either preamble-only +definitions or the use of the \gls{glossaries-extra} package option \optfmt{docdef=restricted}. \end{important} @@ -4682,8 +5446,7 @@ New glossary entries are defined using the command: This is a short command, so values in \meta{key-val list} can't contain any paragraph breaks. Take care to enclose values containing any commas (\texttt{,}) or equal signs (\texttt{=}) with braces to hide them -from the key=value list parser. Be careful to ensure that no -spurious spaces are included at the start and end of the braces. +from the key=value list parser. If you have a long description that needs to span multiple paragraphs, use @@ -4694,10 +5457,9 @@ list}\marg{long description} instead. Note that this command may only be used in the preamble. Be careful of unwanted spaces. \cs{longnewglossaryentry} will remove trailing spaces in the description (via \cs{unskip}) -but won't remove leading spaces (otherwise it would interfere with -commands like \cs{Glsentrydesc}). This command also appends +but won't remove leading spaces. This command also appends \cs{nopostdesc} to the end of the description, which suppresses the -post-description hook. The \sty{glossaries-extra} package provides +post-description hook. The \gls{glossaries-extra} package provides a starred version of \cs{longnewglossaryentry} that doesn't append either \cs{unskip} or \cs{nopostdesc}. @@ -4714,7 +5476,7 @@ list}\marg{long description} (These are both preamble-only commands.) For all the above commands, the first argument, \meta{label}, must be -a~unique label with which to identify this entry. \textbf{This can't contain +a~unique label with which to identify this entry. \strong{This can't contain any non-expandable commands or active characters.} The reason for this restriction is that the label is used to construct internal commands that store the associated information (similarly to commands @@ -4759,15 +5521,15 @@ alphabetically, otherwise the entries can't be sorted correctly. \end{important} \item[{\gloskey{description}}] A brief description of this term (to -appear in the glossary). Within this value, you can use +appear in the glossary). Within this value, you can use: \begin{definition}[\DescribeMacro{\nopostdesc}] \cs{nopostdesc} \end{definition} to suppress the description terminator for this entry. For example, if this entry is a parent entry that doesn't require a description, you -can do \verb|description={\nopostdesc}|. If you want a paragraph -break in the description use +can do \texttt{description\dequals\mgroup{\cs{nopostdesc}}}. If you want a paragraph +break in the description use: \begin{definition}[\DescribeMacro{\glspar}] \cs{glspar} \end{definition} @@ -4777,6 +5539,11 @@ descriptions. If you are using one of the tabular-like glossary styles that permit multi-line descriptions, use \ics{newline} not \verb"\\" if you want to force a line break. +\begin{xtr} +With \gls{glossaries-extra}, use \ics*{glsxtrnopostpunc} instead of +\cs{nopostdesc} to suppress the post-description punctuation. +\end{xtr} + \item[{\gloskey{parent}}] The label of the parent entry. Note that the parent entry must be defined before its sub-entries. See \sectionref{sec:subentries} for further details. @@ -4812,7 +5579,8 @@ that if you use \ics{gls}, \ics{Gls}, \ics{GLS}, \cs{glsdisp} before using \ics{glspl}, the \gloskey{firstplural} value won't be used with \ics{glspl}. -\textbf{Note:} prior to version 1.13, the default value of +\importantpar +Note: prior to version 1.13, the default value of \gloskey{firstplural} was always taken by appending \qt{s} to the \gloskey{first} key, which meant that you had to specify both \gloskey{plural} and \gloskey{firstplural}, even if you hadn't @@ -4836,6 +5604,14 @@ general, it's best to use the \gloskey{sort} key if the You can also override the \gloskey{sort} key by redefining \ics{glsprestandardsort} (see \sectionref{sec:pkgopts-sort}). +\begin{bib2gls} +The \gloskey{sort} key shouldn't be used with \gls{bib2gls}. It has +a system of fallbacks that allow different types of entries to +obtain the sort value from the most relevant field. See the +\gls{bib2gls} manual for further details and see also +\bibglsgallery{sorting}. +\end{bib2gls} + \opt1 by default strips the \glslink{latexexlatinchar}{standard \LaTeX\ accents} (that is, accents generated by core \LaTeX\ commands) from the \gloskey{name} key when it sets the \gloskey{sort} key. So with @@ -4868,27 +5644,27 @@ sort value starts with a symbol. Similarly if you use the \sty{inputenc} package: \begin{alltt} -\verb|\newglossaryentry{elite}{%| - name=\verb|{{|\'e\verb|}|lite\verb|}|, - description=\verb|{select group of people}| -\verb|}| +\cs{newglossaryentry}\mgroup{elite}\mgroup{\% + name=\mgroup{\mgroup{\'e}lite}, + description=\mgroup{select group of people} +} \end{alltt} This is equivalent to \begin{alltt} -\verb|\newglossaryentry{elite}{%| - name=\verb|{{|\'e\verb|}|lite\verb|}|, - description=\verb|{select group of people}|, +\cs{newglossaryentry}\mgroup{elite}\mgroup{\% + name=i\mgroup{\mgroup{\'e}lite}, + description=\mgroup{select group of people}, sort=elite -\verb|}| +} \end{alltt} Unless you use the package option \pkgopt[true]{sanitizesort}, in which case it's equivalent to: \begin{alltt} -\verb|\newglossaryentry{elite}{%| - name=\verb|{{|\'e\verb|}|lite\verb|}|, - description=\verb|{select group of people}|, +\cs{newglossaryentry}\mgroup{elite}\mgroup{\% + name=\mgroup{\mgroup{\'e}lite}, + description=\mgroup{select group of people}, sort=\'elite -\verb|}| +} \end{alltt} Again, this will place the entry before the \qt{A} group. @@ -4901,7 +5677,7 @@ will set it to the expansion of the \gloskey{name} key (if Take care with \gls{xindy} (\opt3): if you have entries with the same \gloskey{sort} value they will be treated as the same entry. If you use \gls{xindy} and aren't using the \texttt{def} -or \texttt{use} sort methods, \textbf{always} use the \gloskey{sort} +or \texttt{use} sort methods, \strong{always} use the \gloskey{sort} key for entries where the name just consists of a control sequence (for example \texttt{name=\{\cs{alpha}\}}). @@ -4936,7 +5712,7 @@ glossary}, but will not automatically add the cross-referenced entry. The referenced entry should be supplied as the value to this key. If you want to override the \qt{see} tag, you can supply the new tag in square brackets before the label. For example -\verb|see=[see also]{anotherlabel}|. \textbf{Note that if you have +\verb|see=[see also]{anotherlabel}|. \strong{Note that if you have suppressed the \gls{numberlist}, the cross-referencing information won't appear in the glossary, as it forms part of the \gls*{numberlist}.} You can override this for individual @@ -4966,12 +5742,44 @@ provides a \texttt{seealso} and \texttt{alias} key. If you want to avoid the automatic indexing triggered by the \gloskey{see} key, consider using \opt4. +\item[{\xtrgloskey{seealso}}] +This key is only available with \gls{glossaries-extra} and is +similar to \gloskey{see} but it doesn't allow for the optional tag. +The \gls{glossaries-extra} package provides \ics*{seealsoname} and +\texttt{seealso=\marg{list}} is essentially like +\texttt{see=[\ics*{seealsoname}]\meta{list}} (\optsand34 may treat +these differently). + +\item[{\xtrgloskey{alias}}] +This key is only available with \gls{glossaries-extra} and is +another form of cross-referencing. An entry can be aliased to +another entry with \texttt{alias=\marg{label}}. This behaves like +\texttt{see=\marg{label}} but also alters the behaviour of commands +like \cs{gls} so that they index the entry given by \meta{label} +instead of the original entry. More variations with the key are +available with \gls{bib2gls}. + +\item[\xtrgloskey{category}] +This key is only available with \gls{glossaries-extra} and is used +to assign a category to the entry. The value should be a label that +can be used to identify the category. See +\gls{glossaries-extra} manual for further details. + \end{description} The following keys are reserved for \ics{newacronym} (see -\sectionref{sec:acronyms}): \gloskey{long}, \gloskey{longplural}, +\sectionref{sec:acronyms}) and also for \ics*{newabbreviation} (see the +\gls{glossaries-extra} manual): \gloskey{long}, \gloskey{longplural}, \gloskey{short} and \gloskey{shortplural}. +\begin{bib2gls} +There are also special internal field names used by \gls{bib2gls}. +See the \gls{bib2gls} manual for further details. +\end{bib2gls} + +The supplementary packages \styfmt{glossaries-prefix} (\sectionref{sec:prefix}) and +\styfmt{glossaries-accsupp} (\sectionref{sec:accsupp}) provide additional keys. + \begin{important} Avoid using any of the \glslike\ or \glstextlike\ commands within the \gloskey{text}, \gloskey{first}, \gloskey{short} or @@ -4998,8 +5806,8 @@ description={select group or class}} Note that the same applies if you are using the \sty{inputenc} package: \begin{alltt} -\verb|\newglossaryentry{elite}{name={{|\'e\verb|}lite},| -description=\verb|{select group or class}}| +\cs{newglossaryentry}\mgroup{elite}\mgroup{name=\mgroup{\mgroup{\'e}lite}, +description=\mgroup{select group or class}} \end{alltt} (This doesn't apply for \XeLaTeX\ documents using the \sty{fontspec} package. For further details, see the \qt{UTF-8} section in the @@ -5702,7 +6510,7 @@ automatically at the start of the document, add the \cs{AtBeginDocument} command \emph{before} you load the \sty{glossaries} package (and \sty{babel}, if you are also loading that) to avoid the creation of the -\filetype{.glsdefs} file and any associated problems that are caused +\filetype{glsdefs} file and any associated problems that are caused by defining commands in the \env{document} environment. (See \sectionref{sec:docdefs}.) \end{important} @@ -5731,8 +6539,8 @@ the entry \texttt{perl} will be added to the main glossary, since it explicitly sets the type to \texttt{main}. \end{example} -\textbf{Note:} if you use \ics{newacronym} (see -\sectionref{sec:acronyms}) the type is set as +\importantpar +Note: if you use \ics{newacronym} (see \sectionref{sec:acronyms}) the type is set as \verb|type=\acronymtype| unless you explicitly override it. For example, if my file \texttt{myacronyms.tex} contains: \begin{verbatim} @@ -5875,7 +6683,7 @@ To overcome the first two problems, as from version 4.0 the \styfmt{glossaries} package modifies the definition of \cs{newglossaryentry} at the beginning of the \env{document} environment so that the definitions are written to an external file -(\cs{jobname}\filetype{.glsdefs}) which is then read in at the start +(\cs{jobname}\filetype{glsdefs}) which is then read in at the start of the document on the next run. The entry will then only be defined in the \env{document} environment if it doesn't already exist. This means that the entry can now be looked up in the glossary, even if @@ -5886,12 +6694,12 @@ definition, you need a second run to see the effect of your modification; this method requires an extra \cs{newwrite}, which may exceed \TeX's maximum allocation; unexpected expansion issues could occur; the \gloskey{see} key isn't stored, which means it can't be -added to the \filetype{.glsdefs} file when it's created at the end of the +added to the \filetype{glsdefs} file when it's created at the end of the document (and therefore won't be present on subsequent runs). The \gls{glossaries-extra} package provides a setting (but only for \optsand23) that allows \cs{newglossaryentry} to occur in the -document environment but doesn't create the \filetype{.glsdefs} +document environment but doesn't create the \filetype{glsdefs} file. This circumvents some problems but it means that you can't display any of the glossaries before all the entries have been defined (so it's all right if all the glossaries are at the end of @@ -6035,7 +6843,7 @@ range encaps. (See the \gls{bib2gls} manual for further details.) Neither \opt1 nor \opt4 care about the location syntax as long as it's valid \LaTeX\ code (and doesn't contain fragile commands). In both cases, the indexing is performed by writing a line to the -\texttt{.aux} file. The write operation is deferred to avoid the +\filetype{aux} file. The write operation is deferred to avoid the problems associated with \TeX's asynchronous output routine. (See, for example, \href{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=oddpage}{Finding @@ -6167,7 +6975,10 @@ this provided the inner command is expandable.) If the inner macro (as given by \verb|\|\meta{internal cs name}) contains non-expandable commands then you may need to redefine \cs{gls}\meta{internal cs name}\texttt{page} after using -\cs{glsaddprotectedpagefmt}\marg{internal cs name}. This command doesn't take any arguments +\begin{alltt} +\cs{glsaddprotectedpagefmt}\marg{internal cs name} +\end{alltt} +This command doesn't take any arguments as \emph{the location is assumed to be given by \cs{c@page}} because that's the only occasion this command should be used. For example, suppose now my page counter format uses small caps Roman numerals: @@ -6208,7 +7019,7 @@ combined with will now have lowercase Roman numerals in the location list (see \sectionref{sec:xindyloc} for further details on that command). Take care of the backslashes. The location (which ends up in -the ":locref" attribute) needs \verb|\\| but the location class +the \xindyattr{:locref} attribute) needs \verb|\\| but the location class (identified with \cs{GlsAddXdyLocation}) just has a single backslash. Note that this example will cause problems if your locations should be hyperlinks. @@ -6375,7 +7186,7 @@ information}. For example, if you are using \app{makeindex}: \write\glswrite{line_max 80}% } \end{verbatim} -This changes the page type precedence\index{page type precedence} and the maximum line length +This changes the page type precedence\index{page type precedence|main} and the maximum line length used by \app{makeindex}. Remember that if you switch to \app{xindy}, this will no longer be @@ -6400,7 +7211,7 @@ the page number. For further information on number lists, see post-processed by \gls{makeindex} or \gls{xindy} unless you have chosen \optsor14. If you don't use \ics{makeglossaries} these external files won't be created. (\optsand14 write the information to the -\filetype{.aux} file.) +\filetype{aux} file.) Note that repeated use of these commands for the same entry can cause the \gls{numberlist} to become quite long, which may not be @@ -6587,7 +7398,10 @@ If you are using hyperlinks and you want to change the font of the hyperlinked location, don't use \ics{hyperpage} (provided by the \sty{hyperref} package) as the locations may not refer to a page number. Instead, the \styfmt{glossaries} package provides number -formats listed in \tableref{tab:hyperxx}. +formats listed in \tableref{tab:hyperxx}. These commands are +designed to work with the particular location formats created by +\gls{makeindex} and \gls{xindy} and shouldn't be used in other +contexts. \begin{table}[htbp] \caption{Predefined Hyperlinked Location Formats} @@ -6620,11 +7434,21 @@ sans-serif font, you can define a command called, say, \begin{verbatim} \newcommand{\hyperbsf}[1]{\textbf{\hypersf{#1}}} \end{verbatim} -and then use \texttt{hyperbsf} as the value for the \gloskey{format} +and then use \texttt{hyperbsf} as the value for the \gloskey[glslink]{format} key.\footnote{See also \ifpdf section~\ref*{sec:code:printglos} \fi \qt{Displaying the glossary} in the documented code, -\texttt{glossaries-code.pdf}.} Remember that if you use \gls{xindy}, you -will need to add this to the list of location attributes: +\texttt{glossaries-code.pdf}.} + +\begin{important} +When defining a custom location format command that uses one of the +\csmeta{hyper}{xx}{} commands, make sure that the argument of +\csmeta{hyper}{xx}{} is just the location. Any formatting must be +outside of \csmeta{hyper}{xx}{} (as in the above \cs{hyperbfsf} +example). +\end{important} + +Remember that if you use \gls{xindy}, you +will need to add this to the list of location \ixindyattrs attributes: \begin{verbatim} \GlsAddXdyAttribute{hyperbsf} \end{verbatim} @@ -6639,10 +7463,40 @@ entry's \gls{firstuseflag}. If \texttt{local=true}, the change to the \gls*{firstuseflag} will be localised to the current scope. The default is \texttt{local=false}. +\item[{\xtrgloskey[glslink]{noindex}}] This is a boolean key that +suppresses the indexing. Only available with \gls{glossaries-extra}. + +\item[{\xtrgloskey[glslink]{hyperoutside}}] This is a boolean key that +determines whether to put the hyperlink outside of \ics{glstextformat}. +Only available with \gls{glossaries-extra}. + +\item[{\xtrgloskey[glslink]{wrgloss}}] This key determines +whether to index before (\texttt{wrgloss\dequals before}) or after +(\texttt{wrgloss\dequals after}) the \gls{linktext}. +Only available with \gls{glossaries-extra}. + +\item[{\xtrgloskey[glslink]{textformat}}] This key identifies the +name of the control sequence to encapsulate the \gls{linktext} +instead of the default \ics{glstextformat}. +Only available with \gls{glossaries-extra}. + +\item[{\xtrgloskey[glslink]{prefix}}] This key locally redefines +\ics{glolinkprefix} to the given value. +Only available with \gls{glossaries-extra}. + +\item[{\xtrgloskey[glslink]{thevalue}}] This key explicitly sets the +location. +Only available with \gls{glossaries-extra}. + +\item[{\xtrgloskey[glslink]{theHvalue}}] This key explicitly sets the +hyperlink location. +Only available with \gls{glossaries-extra}. + \end{description} \begin{important} -The \gls{linktext} isn't scoped by default. Any unscoped +The \gls{linktext} isn't scoped by default with just the base +\styfmt{glossaries} package. Any unscoped declarations in the \gls{linktext} may affect subsequent text. \end{important} @@ -6655,7 +7509,6 @@ to determine the text to be displayed. As described above, these commands all have a star-variant (\texttt{hyper=false}) and a plus-variant (\texttt{hyper=true}) and have an optional first argument that is a \meta{key}=\meta{value} list. - These commands use \ics{glsentryfmt} or the equivalent definition provided by \ics{defglsentryfmt} to determine the automatically generated text and its format (see \sectionref{sec:glsdisplay}). @@ -6826,7 +7679,7 @@ Now the \gls{linktext} will be set to: \glsentrytext{\MakeUppercase sample} two \end{verbatim} This will generate an error because there's no entry with the label -given by \verb|\MakeUppercase sample|. The best solution here is to +\qt{\texttt{\cs{MakeUppercase} sample}}. The best solution here is to write the term out in the \gloskey{text} field and use the command in the \gloskey{name} field. If you don't use \cs{glsname} anywhere in your document, you can use \cs{gls} in the \gloskey{name} field: @@ -7175,6 +8028,12 @@ There are also analogous uppercasing commands: \section{Changing the format of the link text} \label{sec:glsdisplay} +\begin{xtr} +The \gls{glossaries-extra} package provides ways of altering the +format according to the category. See the \gls{glossaries-extra} +manual for further details. +\end{xtr} + The default format of the \gls{linktext} for the \glslike\ commands is governed by\footnote{\ics{glsdisplayfirst} and \ics{glsdisplay} are now deprecated. Backwards compatibility should be preserved but @@ -7259,7 +8118,11 @@ is in a glossary type that's had the hyperlinks switched off (using \pkgopt{nohypertypes}) or because it's the \firstuse\ and the hyperlinks have been suppressed on first use. -Note that \ics{glsifhyper} is now deprecated. +\begin{important} +The \cs{glsifhyperon} command should be used instead of +\ics{glsifhyper}, which is now deprecated (and no longer documented). +\end{important} + If you want to know if the command used to reference this entry was used with the star or plus variant, you can use: \begin{definition}[\DescribeMacro\glslinkvar] @@ -7277,7 +8140,7 @@ Note that you can also use commands such as \ics{ifglsused} within the definition of \cs{glsentryfmt} (see \sectionref{sec:glsunset}). The commands \ics{glslabel}, \ics{glstype}, \ics{glsifplural}, -\ics{glscapscase}, \ics{glscustomtext} and \ics{glsinsert} are +\ics{glscapscase}, \ics{glsinsert} and \ics{glscustomtext} are typically updated at the start of the \glslike\ and \glstextlike\ commands so they can usually be accessed in the hook user commands, such as \ics{glspostlinkhook} and \ics{glslinkpostsetkeys}. @@ -7303,7 +8166,7 @@ This uses the above commands to display just the \gloskey{first}, \gloskey{text}, \gloskey{plural} or \gloskey{firstplural} keys (or the custom text) with the insert text appended. -Alternatively, if want to change the entry format for abbreviations +Alternatively, if you want to change the entry format for abbreviations (defined via \ics{newacronym}) you can use: \begin{definition}[\DescribeMacro{\glsgenacfmt}] \cs{glsgenacfmt} @@ -7618,7 +8481,7 @@ To add all entries that have been defined, use: The optional argument is the same as for \cs{glsadd}, except there is also a key \gloskey[glsaddall]{types} which can be used to specify which glossaries to use. This should be a -comma separated list. For example, if you only want to add +comma-separated list. For example, if you only want to add all the entries belonging to the list of acronyms (specified by the glossary type \ics{acronymtype}) and a list of notation (specified by the glossary type \texttt{notation}) then you can @@ -7626,6 +8489,9 @@ do: \begin{verbatim} \glsaddall[types={\acronymtype,notation}] \end{verbatim} +If you are using \gls{bib2gls} with \gls{glossaries-extra}, you +can't use \cs{glsaddall}. Instead use the \optfmt{selection=all} +resource option to select all entries in the given \filetype{bib} files. \begin{important} Note that \cs{glsadd} and \cs{glsaddall} add the current location to @@ -7641,15 +8507,54 @@ that have already been used: \begin{definition}[\DescribeMacro\glsaddallunused] \cs{glsaddallunused}\oarg{list} \end{definition} -This command uses \cs{glsadd}\texttt{[format=@gobble]} which will +This command uses \cs{glsadd}\texttt{[format=glsignore]} which will ignore this location in the number list. The optional argument \meta{list} is a comma-separated list of glossary types. If omitted, it defaults to the list of all defined glossaries. +\begin{important} If you want to use \cs{glsaddallunused}, it's best to place the command at the end of the document to ensure that all the commands you intend to use have already been used. Otherwise you could end up with a spurious comma or dash in the location list. +\end{important} + +With \gls{glossaries-extra} and \gls{bib2gls}, \texttt{glsignore} +indicates an \qt{ignored location} which influences selection but +isn't added to the location list. In this case, if you use +\optfmt{selection=all} then only those entries that have been +explicitly indexed in the document will have location lists. The +other entries that were selected as a result of +\optfmt{selection=all} won't have location lists. + +Base \sty{glossaries} package only: +\begin{verbatim} +\documentclass{article} +\usepackage{glossaries} +\makeglossaries +\newglossaryentry{cat}{name={cat},description={feline}} +\newglossaryentry{dog}{name={dog},description={canine}} +\begin{document} +\gls{cat}. +\printglossaries +\glsaddallunused % <- make sure dog is also listed +\end{document} +\end{verbatim} +Corresponding \gls{glossaries-extra} and \gls{bib2gls} document code: +\begin{verbatim} +\documentclass{article} +\usepackage[record]{glossaries-extra} +\GlsXtrLoadResources[src={entries},selection=all] +\begin{document} +\gls{cat}. +\printunsrtglossaries +\end{document} +\end{verbatim} +With the file \texttt{entries.bib}: +\begin{verbatim} +@entry{cat,name={cat},description={feline}} +@entry{dog,name={dog},description={canine}} +\end{verbatim} \begin{example}{Dual Entries}{ex:dual} The example file \samplefile{-dual} makes use of \cs{glsadd} to @@ -7684,6 +8589,12 @@ You can then define a new dual entry: \end{verbatim} Now you can reference the acronym with \verb|\gls{svm}| or you can reference the entry in the main glossary with \verb|\gls{main-svm}|. + +Note that with \gls{bib2gls}, there are special dual entry types +that implement this behaviour. That is, if an entry is referenced +then its corresponding dual entry will automatically be selected as +well. So there is less need for \cs{glsadd} with \gls{bib2gls}. +(Although it can still be useful, as shown in \opt6.) \end{example} \chapter{Cross-Referencing Entries} @@ -7712,13 +8623,13 @@ description={firm, round fruit. See also \gls{pear}}} Note that with this method, if you don't use the cross-referenced term in the main part of the document, you will need two runs of \gls{makeglossaries}: -\begin{verbatim} -latex filename +\begin{prompt} +pdflatex filename makeglossaries filename -latex filename +pdflatex filename makeglossaries filename -latex filename -\end{verbatim} +pdflatex filename +\end{prompt} \item As described in \sectionref{sec:newglosentry}, you can use the \gloskey{see} key when you define the entry. For example: @@ -7893,7 +8804,8 @@ For example: \glsentrytitlecase{sample}{desc} \end{verbatim} (If you want title-casing in your glossary style, you might want to -investigate the \sty{glossaries-extra} package.) +investigate the \gls{glossaries-extra} package.) This command will +trigger an error if the entry is undefined. Note that this command has the same limitations as \cs{makefirstuc} which is used by commands like \cs{Gls} and \cs{Glsentryname} to upper-case @@ -7999,7 +8911,9 @@ existence of \meta{label}. \cs{Glsentrydesc}\marg{label} \end{definition} These commands display the description for the glossary entry given -by \meta{label}. \cs{Glsentrydesc} makes the first letter upper case. +by \meta{label}. + +\cs{Glsentrydesc} makes the first letter upper case. The first form is expandable (unless the value of that key contains unexpandable commands). The second form is not expandable. Neither checks for the existence of \meta{label}. @@ -8038,7 +8952,9 @@ existence of \meta{label}. \cs{Glsentrysymbol}\marg{label} \end{definition} These commands display the symbol for the glossary entry given by -\meta{label}. \cs{Glsentrysymbol} makes the first letter upper case. +\meta{label}. + +\cs{Glsentrysymbol} makes the first letter upper case. The first form is expandable (unless the value of that key contains unexpandable commands). The second form is not expandable. Neither checks for the existence of \meta{label}. @@ -8131,7 +9047,7 @@ the existence of \meta{label}. \cs{glshyperlink}\oarg{link text}\marg{label} \end{definition} This command provides a hyperlink to the glossary entry given by -\meta{label} \textbf{but does not add any information to the +\meta{label} \strong{but does not add any information to the glossary file}. The link text is given by \ics{glsentrytext}\marg{label} by default\footnote{versions before 3.0 used \ics{glsentryname} as the default, but this could cause @@ -8193,32 +9109,47 @@ glossary} in the documented code (\texttt{glossaries-code.pdf}). All defined glossaries may be displayed using: \begin{description} -\itempar{\opt1:} -\begin{definition}[\DescribeMacro{\printnoidxglossaries}] +\item[\opt1:] +(Must be used with \ics{makenoidxglossaries} in the preamble.) +\begin{definition}[\DescribeMacro\printnoidxglossaries] \cs{printnoidxglossaries} \end{definition} -(Must be used with \ics{makenoidxglossaries} in the preamble.) -\itempar{\optsand23:} -\begin{definition}[\DescribeMacro{\printglossaries}] +\item[\optsand23:] +(Must be used with \ics{makeglossaries} in the preamble.) +\begin{definition}[\DescribeMacro\printglossaries] \cs{printglossaries} \end{definition} -(Must be used with \ics{makeglossaries} in the preamble.) \end{description} These commands will display all the glossaries in the order in which -they were defined. Note that, in the case of \optsand23, no -glossaries will appear until you have either used the Perl script -\gls{makeglossaries} or Lua script \gls{makeglossaries-lite.lua} or -have directly used \gls{makeindex} or \gls{xindy} (as described in -\sectionref{sec:makeglossaries}). (While the external files are -missing, these commands will just do \cs{null} for each missing -glossary to assist dictionary style documents that just use -\cs{glsaddall} without inserting any text. If you use -\gls{glossaries-extra}, it will insert a heading and boilerplate text when the +they were defined. + +Note that, in the case of \optsand23, no glossaries will appear +until you have either used the Perl script \gls{makeglossaries} or +Lua script \gls{makeglossaries-lite.lua} or have directly used +\gls{makeindex} or \gls{xindy} (as described in +\sectionref{sec:makeglossaries}). + +\begin{important} +While the external files are missing, \cs{printglossary} will just do +\ics{null} for each missing glossary to assist dictionary style +documents that just use \cs{glsaddall} without inserting any text. +This use of \ics{null} ensures that all indexing information is +written before the final page is shipped out. Once the external +files are present \cs{null} will no longer be used. This can cause a +spurious blank page on the first \LaTeX\ run before the glossary +files have been created. Once these files are present, \cs{null} +will no longer be used and so shouldn't cause interference for the +final document. +\end{important} + +\begin{xtr} +If you use \gls{glossaries-extra}, it will insert a heading and boilerplate text when the external files are missing. The extension package also provides \cs{printunsrtglossaries} as an alternative. See the -\gls{glossaries-extra} manual for further details.) +\gls{glossaries-extra} manual for further details. +\end{xtr} If the glossary still does not appear after you re-\LaTeX\ your document, check the \gls*{makeindex}\slash\gls*{xindy} log files to @@ -8337,6 +9268,36 @@ If you don't get an error with \texttt{sort=use} and options, then you probably need to use the \pkgopt[true]{sanitizesort} package option or make sure none of the entries have fragile commands in their \gloskey{sort} field. + +\item[{\xtrprintglosskey[\marg{label}]{label}}] +This key is only available with \gls{glossaries-extra} and labels +the glossary with \cs{label}\marg{label}. This is an alternative to +the package option \pkgopt[autolabel]{numberedsection} + +\item[\xtrprintglosskey{target}] This is a boolean key only +available with \gls{glossaries-extra}, which can be used to switch +off the automatic hypertarget for each entry. (This refers to the +target used by commands like \cs{gls} and \cs{glslink}.) + +This option is useful with \ics*{printunsrtglossary} as it allows +the same list (of sub-list) of entries to be displayed multiple +times without causing duplicate hypertarget names. + +\item[{\xtrprintglosskey[\marg{prefix}]{prefix}}] +This key is only available with \gls{glossaries-extra} and provides +another way of avoiding duplicate hypertarget names is to use a +different prefix for those names. This locally redefines +\ics{glolinkprefix} but note this will also affect the target for any entry +referenced within the glossary with commands like \cs{gls}, +\cs{glslink} or \cs{glshypertarget}. + +\item[{\xtrprintglosskey[\marg{prefix}]{targetnameprefix}}] +This key is only available with \gls{glossaries-extra}. +This is similar to the \pkgoptfmt{prefix} option, but it alters the prefix of +the hypertarget anchors without changing \ics{glslinkprefix} (so it +won't change the hyperlinks for any entries referenced in the +glossary). + \end{description} By default, the glossary is started either by \ics{chapter*} or by @@ -8423,7 +9384,7 @@ bold. If you want to change the font for the description, or if you only want to change the name font for some types of entries but not others, you might want to consider using the -\sty{glossaries-extra} package. +\gls{glossaries-extra} package. \begin{example}{Changing the Font Used to Display Entry Names in the Glossary}{ex:glsnamefont} @@ -8449,7 +9410,7 @@ This ensures that the glossary information is written in \gls{indexingapp}, and \sectionref{sec:locationsyntax} covers the issues involved in the location syntax. This section covers the commands provided by the \styfmt{glossaries} package that allow you -to adjust the \gls{xindy} style file (\filetype{.xdy}) and +to adjust the \gls{xindy} style file (\filetype{xdy}) and parameters. To assist writing information to the \gls{xindy} style @@ -8509,7 +9470,7 @@ and encoding used (unless you have written your own custom \gls*{xindy} style file that defines the relevant alphabet and sort rules). If you use \gls{makeglossaries}, this information is obtained from the document's auxiliary -(\filetype{.aux}) file. The \gls{makeglossaries} script attempts to +(\filetype{aux}) file. The \gls{makeglossaries} script attempts to find the root language given your document settings, but in the event that it gets it wrong or if \gls*{xindy} doesn't support that language, then you can specify the required language using: @@ -8575,7 +9536,7 @@ counter in the \gloskey[glslink]{counter} key for commands like \end{definition} where \meta{counter list} is a comma-separated list of counter names. -The most likely attributes used in the \gloskey[glslink]{format} +The most likely \ixindyattrs attributes used in the \gloskey[glslink]{format} key (\locfmt{textrm}, \locfmt{hyperrm} etc) are automatically added to the \gls{xindy} style file, but if you want to use another attribute, you need to add it using: @@ -8587,7 +9548,7 @@ the \gloskey[glslink]{format} key. Take care if you have multiple instances of the same location with different formats. The duplicate locations will be discarded -according to the order in which the attributes are listed. Consider +according to the order in which the \ixindyattrs attributes are listed. Consider defining semantic commands to use for primary references. For example: \begin{verbatim} @@ -8609,7 +9570,7 @@ command that will do this: \newcommand*{\hyperbfit}[1]{\textit{\hyperbf{#1}}} \end{verbatim} but with \gls{xindy}, I also need to add this as an allowed -attribute: +\ixindyattrs attribute: \begin{verbatim} \GlsAddXdyAttribute{hyperbfit} \end{verbatim} @@ -9052,6 +10013,13 @@ glossary type will automatically be added to the the entries in an ignored glossary. (The sample file \samplefile{-entryfmt} defines an ignored glossary.) +\begin{xtr} +The \gls{glossaries-extra} package provides a starred version of +this command that allows hyperlinks (since ignored glossaries can be +useful with \gls{bib2gls}). There is also an analogous +\ics*{provideignoredglossary} command. +\end{xtr} + You can test if a glossary is an ignored one using: \begin{definition}[\DescribeMacro\ifignoredglossary] \cs{ifignoredglossary}\marg{name}\marg{true}\marg{false} @@ -9111,9 +10079,11 @@ change LaTeX’s \qt{fixed names}}. \chapter{Acronyms and Other Abbreviations} \label{sec:acronyms} -The \sty{glossaries-extra} package provides superior +\begin{xtr} +The \gls{glossaries-extra} package provides superior abbreviation handling. You may want to consider using that package instead of the commands described here. +\end{xtr} \begin{important} Note that although this chapter uses the term \qt{acronym}, you can also @@ -9124,8 +10094,8 @@ should be \qt{Abbreviations} rather than \qt{Acronyms}) then you can change the title either by redefining \ics{acronymname} (see \sectionref{sec:languages}) or by using the \gloskey[printglossary]{title} in the optional argument of \ics{printglossary} (or -\ics{printacronym}). Alternatively consider using the -\sty{glossaries-extra} package's \pkgoptfmt{abbreviations} +\ics{printacronyms}). Alternatively consider using the +\gls{glossaries-extra} package's \pkgopt*{abbreviations} option instead. \end{important} @@ -9192,7 +10162,7 @@ changed by the associated language files, but they can't be added to the usual caption hooks as there's no guarantee when they'll be expanded (as \hyperref[pluralsuffix]{discussed earlier}). A different approach is used by \styfmt{glossaries-extra}, which has -category attributes to determine whether or not to append a suffix +\icatattrs category attributes to determine whether or not to append a suffix when forming the default value of \gloskey{shortplural}. Since \ics{newacronym} uses \ics{newglossaryentry}, you can use @@ -9215,7 +10185,7 @@ The following defines the abbreviation IDN: \end{verbatim} \verb|\gls{idn}| will produce \qt{identification number (IDN)} on \firstuse\ and \qt{IDN} on subsequent uses. If you want to use one -of the smallcaps acronym styles, described in +of the \gls{smallcaps} acronym styles, described in \sectionref{sec:setacronymstyle}, you need to use lower case characters for the shortened form: \begin{verbatim} @@ -9246,7 +10216,7 @@ you may be tempted to do: \begin{verbatim} \newacronym{shtml}{S\gls{html}}{\gls{ssi} enabled \gls{html}} \end{verbatim} -\textbf{Don't!} This will break the case-changing commands, such +\strong{Don't!} This will break the case-changing commands, such as \ics{Gls}, it will cause inconsistencies on \firstuse, and, if hyperlinks are enabled, will cause nested hyperlinks. It will also confuse the commands used by the entry formatting (such as @@ -9267,7 +10237,7 @@ or \end{verbatim} Similarly for the \glstextlike\ commands. -Other approaches are available with \sty{glossaries-extra}. +Other approaches are available with \gls{glossaries-extra}. See the section \qt{Nested Links} in the \styfmt{glossaries-extra} user manual. @@ -9357,8 +10327,8 @@ This is a shortcut for which by default does \begin{alltt} \cs{acrfullformat} - \{\cs{acrlong}\oarg{options}\marg{label}\marg{insert}\} - \{\cs{acrshort}\oarg{options}\marg{label}\} + \mgroup{\cs{acrlong}\oarg{options}\marg{label}\marg{insert}} + \mgroup{\cs{acrshort}\oarg{options}\marg{label}} \end{alltt} where \begin{definition}[\DescribeMacro\acrfullformat] @@ -9515,7 +10485,7 @@ using the \gls{glossaries-extra} package, which has better abbreviation management. \end{important} -Note that unlike the default behaviour of \cs{newacronym}, the +Unlike the default behaviour of \cs{newacronym}, the styles used via \cs{setacronymstyle} don't use the \gloskey{first} or \gloskey{text} keys, but instead they use \ics{defglsentryfmt} to set a~custom format that uses the \gloskey{long} and \gloskey{short} @@ -9568,7 +10538,7 @@ in lower case. \ifpdf Remember that \verb|\textsc{abc}| produces \hypertarget{boldsc}{}% \begin{important}% -Some fonts don't support bold smallcaps, so you may need to redefine +Some fonts don't support bold \gls{smallcaps}, so you may need to redefine \ics{glsnamefont} (see \sectionref{sec:printglossary}) to switch to medium weight if you are using a glossary style that displays entry names in bold and you have chosen an acronym style that uses @@ -9737,14 +10707,17 @@ and then redefine \ics{acronymsort} and \ics{acronymentry}: (I've used \cs{space} for extra clarity, but you can just use an actual space instead.) -Since the default Computer Modern fonts don't support bold -smallcaps, I'm also going to redefine \ics{acronymfont} so that it -always switches to medium weight to ensure the smallcaps setting is -used: +Note that the default Computer Modern fonts don't support bold +\gls{smallcaps}, so another font is required. For example: +\begin{verbatim} +\usepackage[T1]{fontenc} +\end{verbatim} +The alternative is to redefine \ics{acronymfont} so that it +always switches to medium weight to ensure the \gls{smallcaps} setting is +used. For example: \begin{verbatim} \renewcommand*{\acronymfont}[1]{\textmd{\scshape #1}} \end{verbatim} -This isn't necessary if you use a font that supports bold smallcaps. The sample file \samplefile{FnAcrDesc} illustrates this example. @@ -10006,7 +10979,7 @@ change the above to: \end{verbatim} The acronym font needs to be set to \ics{textsc} and the plural suffix adjusted so that the \qt{s} suffix in the plural short form -doesn't get converted to smallcaps: +doesn't get converted to \gls{smallcaps}: \begin{verbatim} \renewcommand*{\acronymfont}[1]{\textsc{##1}}% \renewcommand*{\acrpluralsuffix}{\glstextup{\glspluralsuffix}}% @@ -10288,8 +11261,7 @@ before the full stop. The next example shows one way of achieving this. (Note that the supplemental \gls{glossaries-extra} package provides a much simpler way of doing this, which you may prefer to use. See the -\href{http://www.dickimaw-books.com/gallery/sample-initialisms.shtml}{initialisms -example}.) +\gallery{sample-initialisms.shtml}{initialisms example}.) \begin{example}{Abbreviations with Full Stops (Periods)}{ex:dotabbr} As from version 4.16, there's now a hook (\ics{glspostlinkhook}) @@ -10458,7 +11430,8 @@ names consisting of alphabetical characters. This is also true for using \sty{xspace}.\footnotemark \end{important} \footnotetext{See David Carlisle's explanation in -\url{http://tex.stackexchange.com/questions/86565/drawbacks-of-xspace}} +\href{http://tex.stackexchange.com/questions/86565/drawbacks-of-xspace}{Drawbacks +of xspace}} The \styfmt{glossaries} package doesn't load the \sty{xspace} package since there are both advantages and disadvantages to using @@ -10642,6 +11615,13 @@ checks for this. For \sty{tabularx}, you need to explicitly patch it by placing \cs{glspatchtabularx} in the preamble (or anywhere before the problematic use of \envfmt{tabularx}). +\begin{xtr} +If you need to use commands like \cs{gls} in any problematic context +that interferes with the \gls{firstuseflag}, then you can try using +the buffering system provided with \gls{glossaries-extra}. See the +\qt{First Use Flag} section of the \gls{glossaries-extra} manual. +\end{xtr} + \section{Counting the Number of Times an Entry has been Used (First Use Flag Unset)} \label{sec:enableentrycount} @@ -10676,7 +11656,7 @@ to zero (where \cs{glslocalreset} performs a~local change). The \texttt{prevcount} field stores the final value of the \texttt{currcount} field \emph{from the previous run}. This value is -read from the \texttt{.aux} file at the beginning of the +read from the \filetype{aux} file at the beginning of the \env{document} environment. You can access these fields using @@ -10687,8 +11667,11 @@ for the \texttt{currcount} field, and \begin{definition}[\DescribeMacro\glsentryprevcount] \cs{glsentryprevcount}\marg{label} \end{definition} -for the \texttt{prevcount} field. \textbf{These commands are -only defined if you have used \cs{glsenableentrycount}.} +for the \texttt{prevcount} field. + +\begin{important} +These commands are only defined if you have used \cs{glsenableentrycount}. +\end{important} For example: \begin{verbatim} @@ -10866,6 +11849,11 @@ synonym. For example \let\ac\cgls \end{verbatim} +\begin{bib2gls} +With \gls{bib2gls} there's an analogous record counting set of +commands. See \gls{glossaries-extra} and \gls{bib2gls} manuals for further details. +\end{bib2gls} + \chapter{Glossary Styles} \label{sec:styles} @@ -10879,8 +11867,7 @@ with a number of pre-defined glossary styles, described in best suits your type of glossary or, if none of them suit your document, you can defined your own style (see \sectionref{sec:newglossarystyle}). There are some examples -of glossary styles available at -\url{http://www.dickimaw-books.com/gallery/#glossaries}. +of glossary styles available at \gallerytopic{glossaries}. The glossary style can be set using the \gloskey[printglossary]{style} key in the optional argument to \ics{printnoidxglossary} (\opt1) or \ics{printglossary} @@ -10896,9 +11883,15 @@ is automatically loaded by the \styfmt{glossaries} package. You can use the lorum ipsum dummy entries provided in the accompanying -\texttt{example-glossaries-*.tex} files (described in +\texttt{example\dhyphen glossaries\dhyphen *.tex} files (described in \sectionref{sec:lipsum}) to test the different styles. +\begin{xtr} +The \sty{glossaries-extra-stylemods} package provided with +\gls{glossaries-extra} patches the predefined styles. There also +more styles available with \gls{glossaries-extra}. +\end{xtr} + \section{Predefined Styles} \label{sec:predefinedstyles} @@ -10909,7 +11902,7 @@ package options \pkgopt{entrycounter}, \pkgopt{counterwithin} and \sectionref{sec:pkgopts-printglos}. There is a summary of available styles in \tableref{tab:styles}. You can view samples of all the predefined styles at -\url{http://www.dickimaw-books.com/gallery/glossaries-styles/}. +\galleryurl{glossaries-styles/}. Note that \gls{glossaries-extra} provides additional styles in the supplementary packages \sty{glossary-bookindex} and \sty{glossary-longnoloc}. See the \gls{glossaries-extra} manual for @@ -10967,10 +11960,15 @@ be displayed.} \end{table} The tabular-like styles that allow multi-line descriptions and page -lists use the length \DescribeMacro{\glsdescwidth}\cs{glsdescwidth} +lists use the length +\begin{definition}[\DescribeMacro{\glsdescwidth}] +\cs{glsdescwidth} +\end{definition} to set the width of the description column and the length -\DescribeMacro{\glspagelistwidth}\cs{glspagelistwidth} to set the -width of the page list column.\footnote{These lengths will not be +\begin{definition}[\DescribeMacro{\glspagelistwidth}] +\cs{glspagelistwidth} +\end{definition} +to set the width of the page list column.\footnote{These lengths will not be available if you use both the \pkgopt{nolong} and \pkgopt{nosuper} package options or if you use the \pkgopt{nostyles} package option unless you explicitly load the relevant package.} @@ -11033,15 +12031,15 @@ a comma) you will need to redefine \cs{glspostdescription} before the glossary is displayed. Alternatively, you can suppress it for a given entry by placing \ics{nopostdesc} in the entry's description. Note that \ics{longnewglossaryentry} puts \cs{nopostdesc} at the end -of the description. The \sty{glossaries-extra} package provides a +of the description. The \gls{glossaries-extra} package provides a starred version that doesn't. As from version 3.03 you can now use the package option \pkgopt{nopostdot} to suppress this full stop. This is the better -option if you want to use the \sty{glossaries-extra} package. +option if you want to use the \gls{glossaries-extra} package. The \sty{glossaries-extra-stylemods} package provides some adjustments some of to the predefined styles listed here, allowing -for greater flexibility. See the \sty{glossaries-extra} +for greater flexibility. See the \gls{glossaries-extra} documentation for further details. \subsection{List Styles} @@ -11580,7 +12578,7 @@ style is like \glostyle{superragged3col} but has a header row. \item[superragged3colheaderborder] The \glostyle{superragged3colheaderborder} style is like -\glostyle{superragged3colheader} but has horizontal and vertical +the above but has horizontal and vertical lines around it. \item[altsuperragged4col] The \glostyle{altsuperragged4col} style is @@ -11600,7 +12598,7 @@ lines around it. \item[altsuperragged4colheaderborder] The \glostyle{altsuperragged4colheaderborder} style is like -\glostyle{altsuperragged4colheader} but has horizontal and vertical +the above but has horizontal and vertical lines around it. \end{description} @@ -11635,7 +12633,9 @@ the navigation line using \begin{definition}[\DescribeMacro\glstreenavigationfmt] \cs{glstreenavigationfmt}\marg{text} \end{definition} -which defaults to \cs{glstreenamefmt}\marg{text}. Note that this is +which defaults to \cs{glstreenamefmt}\marg{text}. + +Note that this is different from \cs{glslistnavigationitem}, provided with the styles such as \glostyle{listhypergroup}, as that also includes \cs{item}. @@ -11945,7 +12945,7 @@ This is used to format the entry name and defaults to \cs{glstarget}\marg{label}\marg{name}, where \meta{name} is provided in the form \cs{glossentryname}\marg{label} and \meta{label} is the entry's label. For example, if you want the name to appear in -smallcaps: +\gls{smallcaps}: \begin{verbatim} \renewcommand*{\glsinlinenameformat}[2]{\glstarget{#1}{\textsc{#2}}} \end{verbatim} @@ -12001,7 +13001,9 @@ needs to redefine all of the following: \env{theglossary} \end{definition} This environment defines how the main body of the glossary should -be typeset. Note that this does not include the section heading, +be typeset. + +Note that this does not include the section heading, the glossary preamble (defined by \ics{glossarypreamble}) or the glossary postamble (defined by \ics{glossarypostamble}). For example, the \glostyle{list} style uses the \env{description} environment, @@ -12071,8 +13073,10 @@ redefines \cs{glsgroupheading} as follows: \renewcommand*{\glsgroupheading}[1]{% \item[\glsnavhypertarget{##1}{\glsgetgrouptitle{##1}}]} \end{verbatim} -See also \cs{glsgroupskip} below. (Note that command definitions within -\ics{newglossarystyle} must use \verb|##1| instead of \verb|#1| etc.) +See also \cs{glsgroupskip} below. + +Note that command definitions within +\ics{newglossarystyle} must use \verb|##1| instead of \verb|#1| etc. \begin{definition}[\DescribeMacro{\glsgroupskip}] \cs{glsgroupskip} @@ -12334,698 +13338,5846 @@ that displays each entry in a \env{longtable} as follows: This section describes some utility commands. Additional commands can be found in the documented code (glossaries-code.pdf). -\section{Loops} -\label{sec:loops} +\begin{xtr} +The \gls{glossaries-extra} package provides extra utility commands. +See the \qt{Utilities} section of the \gls{glossaries-extra} manual. +\end{xtr} + +\section{Loops} +\label{sec:loops} + +\begin{important} +Some of the commands described here take a comma-separated list as +an argument. As with \LaTeX's \cs{@for} command, make sure your list +doesn't have any unwanted spaces in it as they don't get stripped. +(Discussed in more detail in +\href{http://www.dickimaw-books.com/latex/admin/html/docsvlist.shtml#spacesinlists}{\S2.7.2 of \qt{\LaTeX\ for Administrative +Work}}.) +\end{important} + +\begin{definition}[\DescribeMacro{\forallglossaries}] +\cs{forallglossaries}\oarg{glossary list}\marg{cs}\marg{body} +\end{definition} +This iterates through \meta{glossary list}, a comma-separated list +of glossary labels (as supplied when the glossary was defined). +At each iteration \meta{cs} (which must be a control sequence) is +set to the glossary label for the current iteration and \meta{body} +is performed. If \meta{glossary list} is omitted, the default is to +iterate over all glossaries (except the ignored ones). + +\begin{definition}[\DescribeMacro{\forallacronyms}] +\cs{forallacronyms}\marg{cs}\marg{body} +\end{definition} +This is like \cs{forallglossaries} but only iterates over the +lists of acronyms (that have previously been declared using +\ics{DeclareAcronymList} or the \pkgopt{acronymlists} package +option). This command doesn't have an optional argument. If you want +to explicitly say which lists to iterate over, just use the optional +argument of \cs{forallglossaries}. + +\begin{definition}[\DescribeMacro{\forglsentries}] +\cs{forglsentries}\oarg{glossary label}\marg{cs}\marg{body} +\end{definition} +This iterates through all entries in the glossary given by +\meta{glossary label}. At each iteration \meta{cs} (which must be a +control sequence) is set to the entry label for the current +iteration and \meta{body} is performed. If \meta{glossary label} is +omitted, \ics{glsdefaulttype} (usually the main glossary) is used. + +\begin{definition}[\DescribeMacro{\forallglsentries}] +\cs{forallglsentries}\oarg{glossary list}\marg{cs}\marg{body} +\end{definition} +This is like \cs{forglsentries} but for each glossary in +\meta{glossary list} (a comma-separated list of glossary labels). If +\meta{glossary list} is omitted, the default is the list of all +defined glossaries (except the ignored ones). At each iteration +\meta{cs} is set to the entry label and \meta{body} is performed. +(The current glossary label can be obtained using +\cs{glsentrytype}\marg{cs} within \meta{body}.) + +\section{Conditionals} +\label{sec:conditionals} + +\begin{definition}[\DescribeMacro{\ifglossaryexists}] +\cs{ifglossaryexists}{\meta{label}}{\meta{true part}}{\meta{false +part}} +\end{definition} +This checks if the glossary given by \meta{label} exists. If it +does \meta{true part} is performed, otherwise \meta{false part}. + +\begin{definition}[\DescribeMacro{\ifglsentryexists}] +\cs{ifglsentryexists}{\meta{label}}{\meta{true part}}{\meta{false +part}} +\end{definition} +This checks if the glossary entry given by \meta{label} exists. If it +does \meta{true part} is performed, otherwise \meta{false part}. +(Note that \cs{ifglsentryexists} will always be true after the +containing glossary has been displayed via \ics{printglossary} +or \ics{printglossaries} even if the entry is explicitly defined +later in the document. This is because the entry has to be defined +before it can be displayed in the glossary, see \sectionref{sec:techissues} for +further details.) + +\begin{definition}[\DescribeMacro{\glsdoifexists}] +\cs{glsdoifexists}\marg{label}\marg{code} +\end{definition} +Does \meta{code} if the entry given by \meta{label} exists. If it +doesn't exist, an error is generated. (This command uses +\cs{ifglsentryexists}.) + +\begin{definition}[\DescribeMacro{\glsdoifnoexists}] +\cs{glsdoifnoexists}\marg{label}\marg{code} +\end{definition} +Does the reverse of \cs{glsdoifexists}. (This command uses +\cs{ifglsentryexists}.) + +\begin{definition}[\DescribeMacro{\glsdoifexistsorwarn}] +\cs{glsdoifexistsorwarn}\marg{label}\marg{code} +\end{definition} +As \cs{glsdoifexists} but issues a warning rather than an error if +the entry doesn't exist. + +\begin{definition}[\DescribeMacro{\glsdoifexistsordo}] +\cs{glsdoifexistsordo}\marg{label}\marg{code}\marg{else code} +\end{definition} +Does \meta{code} if the entry given by \meta{label} exists otherwise +generate an error and do \meta{else code}. + +\begin{definition}[\DescribeMacro{\glsdoifnoexistsordo}] +\cs{glsdoifnoexistsordo}\marg{label}\marg{code}\marg{else code} +\end{definition} +Does \meta{code} if the entry given by \meta{label} doesn't exist otherwise +generate an error and do \meta{else code}. + +\begin{definition}[\DescribeMacro{\ifglsused}] +\cs{ifglsused}{\meta{label}}{\meta{true part}}{\meta{false +part}} +\end{definition} +See \sectionref{sec:glsunset}. + +\begin{definition}[\DescribeMacro{\ifglshaschildren}] +\cs{ifglshaschildren}{\meta{label}}{\meta{true part}}{\meta{false +part}} +\end{definition} +This checks if the glossary entry given by \meta{label} has any +sub-entries. If it does, \meta{true part} is performed, otherwise +\meta{false part}. + +\begin{definition}[\DescribeMacro{\ifglshasparent}] +\cs{ifglshasparent}{\meta{label}}{\meta{true part}}{\meta{false +part}} +\end{definition} +This checks if the glossary entry given by \meta{label} has a parent +entry. If it does, \meta{true part} is performed, otherwise +\meta{false part}. + +\begin{definition}[\DescribeMacro{\ifglshassymbol}] +\cs{ifglshassymbol}\marg{label}\marg{true part}\marg{false part} +\end{definition} +This checks if the glossary entry given by \meta{label} has had the +\gloskey{symbol} field set. If it has, \meta{true part} is performed, +otherwise \meta{false part}. + +\begin{definition}[\DescribeMacro{\ifglshaslong}] +\cs{ifglshaslong}\marg{label}\marg{true part}\marg{false part} +\end{definition} +This checks if the glossary entry given by \meta{label} has had the +\gloskey{long} field set. If it has, \meta{true part} is performed, +otherwise \meta{false part}. This should be true for any entry that +has been defined via \ics{newacronym}. +There is no check for the existence of \meta{label}. + +\begin{definition}[\DescribeMacro{\ifglshasshort}] +\cs{ifglshasshort}\marg{label}\marg{true part}\marg{false part} +\end{definition} +This checks if the glossary entry given by \meta{label} has had the +\gloskey{short} field set. If it has, \meta{true part} is performed, +otherwise \meta{false part}. This should be true for any entry that +has been defined via \ics{newacronym}. +There is no check for the existence of \meta{label}. + +\begin{definition}[\DescribeMacro{\ifglshasdesc}] +\cs{ifglshasdesc}\marg{label}\marg{true part}\marg{false part} +\end{definition} +This checks if the \gloskey{description} field is non-empty for +the entry given by \meta{label}. If it has, \meta{true part} is +performed, otherwise \meta{false part}. Compare with: +\begin{definition}[\DescribeMacro{\ifglsdescsuppressed}] +\cs{ifglsdescsuppressed}\marg{label}\marg{true part}\marg{false part} +\end{definition} +This checks if the \gloskey{description} field has been set to just +\ics{nopostdesc} for the entry given by \meta{label}. If it has, +\meta{true part} is performed, otherwise \meta{false part}. +There is no check for the existence of \meta{label}. + +For all other fields you can use: +\begin{definition}[\DescribeMacro\ifglshasfield] +\cs{ifglshasfield}\marg{field}\marg{label}\marg{true part}\marg{false +part} +\end{definition} +This tests the value of the field given by \meta{field} for the entry +identified by \meta{label}. If the value is empty \emph{or the default +value}, then \meta{false part} is performed, otherwise \meta{true +part} is performed. If the field supplied is unrecognised \meta{false part} +is performed and a warning is issued. Unlike the above commands, +such as \cs{ifglshasshort}, an error occurs if the entry is +undefined. + +As from version 4.23, within \meta{true part} you can use +\begin{definition}[\DescribeMacro\glscurrentfieldvalue] +\cs{glscurrentfieldvalue} +\end{definition} +to access the field value. This command is +initially defined to nothing but has +no relevance outside \meta{true part}. This saves re-accessing the +field if the test is true. For example: +\begin{verbatim} +\ifglshasfield{useri}{sample}{, \glscurrentfieldvalue}{} +\end{verbatim} +will insert a comma, space and the field value if the +\gloskey{user1} key has been set for +the entry whose label is \texttt{sample}. + +You can test if the value of the field is equal to a given string +using: +\begin{definition}[\DescribeMacro\ifglsfieldeq] +\cs{ifglsfieldeq}\marg{label}\marg{field}\marg{string}\marg{true}\marg{false} +\end{definition} +In this case the \meta{field} must be the field name not the key +(see \tableref{tab:fieldmap}). If the field isn't recognised, an +error will occur. This command internally uses +\sty{etoolbox}'s \cs{ifcsstring} to perform the comparison. \emph{The +string is not expanded during the test.} + +The result may vary depending on whether or not expansion is on for +the given field (when the entry was defined). For example: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries} + +\newcommand*{\foo}{FOO} + +\newglossaryentry{sample1}{name={sample1},description={an example}, +user1={FOO}} +\newglossaryentry{sample2}{name={sample2},description={an example}, +user1={\foo}} + +\begin{document} +\ifglsfieldeq{sample1}{useri}{FOO}{TRUE}{FALSE}. + +\ifglsfieldeq{sample2}{useri}{FOO}{TRUE}{FALSE}. +\end{document} +\end{verbatim} +This will produce \qt{TRUE} in both cases since expansion is on, so +\cs{foo} was expanded to \qt{FOO} when \texttt{sample2} was defined. +If the tests are changed to: +\begin{verbatim} +\ifglsfieldeq{sample1}{useri}{\foo}{TRUE}{FALSE}. + +\ifglsfieldeq{sample2}{useri}{\foo}{TRUE}{FALSE}. +\end{verbatim} +then this will produce \qt{FALSE} in both cases. Now suppose +expansion is switched off for the \gloskey{user1} key: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries} + +\newcommand*{\foo}{FOO} + +\glssetnoexpandfield{useri} + +\newglossaryentry{sample1}{name={sample1},description={an example}, +user1={FOO}} +\newglossaryentry{sample2}{name={sample2},description={an example}, +user1={\foo}} + +\begin{document} +\ifglsfieldeq{sample1}{useri}{FOO}{TRUE}{FALSE}. + +\ifglsfieldeq{sample2}{useri}{FOO}{TRUE}{FALSE}. +\end{document} +\end{verbatim} +This now produces \qt{TRUE} for the first case (comparing \qt{FOO} +with \qt{FOO}) and \qt{FALSE} for the second case (comparing +\qt{\cs{foo}} with \qt{FOO}). + +The reverse happens in the following: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries} + +\newcommand*{\foo}{FOO} + +\glssetnoexpandfield{useri} + +\newglossaryentry{sample1}{name={sample1},description={an example}, +user1={FOO}} +\newglossaryentry{sample2}{name={sample2},description={an example}, +user1={\foo}} + +\begin{document} +\ifglsfieldeq{sample1}{useri}{\foo}{TRUE}{FALSE}. + +\ifglsfieldeq{sample2}{useri}{\foo}{TRUE}{FALSE}. +\end{document} +\end{verbatim} +This now produces \qt{FALSE} for the first case (comparing \qt{FOO} +with \qt{\cs{foo}}) and \qt{TRUE} for the second case (comparing +\qt{\cs{foo}} with \qt{\cs{foo}}). + +You can test if the value of a field is equal to the replacement +text of a command using: +\begin{definition}[\DescribeMacro\ifglsfielddefeq] +\cs{ifglsfielddefeq}\marg{label}\marg{field}\marg{command}\marg{true}\marg{false} +\end{definition} +This internally uses \sty{etoolbox}'s \cs{ifdefstrequal} command to +perform the comparison. The argument \meta{command} must be a macro. + +For example: +\begin{verbatim} +\documentclass{article} + +\usepackage{glossaries} + +\newcommand*{\foo}{FOO} + +\glssetnoexpandfield{useri} + +\newglossaryentry{sample1}{name={sample1},description={an example}, +user1={FOO}} +\newglossaryentry{sample2}{name={sample2},description={an example}, +user1={\foo}} + +\begin{document} +\ifglsfielddefeq{sample1}{useri}{\foo}{TRUE}{FALSE}. + +\ifglsfielddefeq{sample2}{useri}{\foo}{TRUE}{FALSE}. +\end{document} +\end{verbatim} +Here, the first case produces \qt{TRUE} since the value of the +\texttt{useri} field (\qt{FOO}) is the same as the replacement text +(definition) of \cs{foo} (\qt{FOO}). We have the result +\qt{\texttt{FOO}} is equal to \qt{\texttt{FOO}}. + +The second case produces \qt{FALSE} since the value of the +\texttt{useri} field (\qt{\cs{foo}}) is not the same as the replacement +text (definition) of \cs{foo} (\qt{FOO}). No expansion has been +performed on the value of the \texttt{useri} field. We have the +result \qt{\cs{foo}} is not equal to \qt{\texttt{FOO}}. + +If we add: +\begin{verbatim} +\newcommand{\FOO}{\foo} +\ifglsfielddefeq{sample2}{useri}{\FOO}{TRUE}{FALSE}. +\end{verbatim} +we now get \qt{TRUE} since the value of the +\texttt{useri} field (\qt{\cs{foo}}) is the same as the replacement +text (definition) of \cs{FOO} (\qt{\cs{foo}}). We have the result \qt{\cs{foo}} +is equal to \qt{\cs{foo}}. + +There is a similar command that requires the control sequence name +(without the leading backslash) instead of the actual control sequence: +\begin{definition}[\DescribeMacro\ifglsfieldcseq] +\cs{ifglsfieldcseq}\marg{label}\marg{field}\marg{csname}\marg{true}\marg{false} +\end{definition} +This internally uses \sty{etoolbox}'s \cs{ifcsstrequal} command +instead of \cs{ifdefstrequal}. + +\section{Fetching and Updating the Value of a Field} +\label{sec:fetchset} + +In addition to the commands described in \sectionref{sec:glsnolink}, +the following may also be used to fetch field information. +\begin{definition}[\DescribeMacro\glsentrytype] +\cs{glsentrytype}\marg{label} +\end{definition} +Expands to the entry's glossary type. No existence check is +performed. + +\begin{definition}[\DescribeMacro\glsentryparent] +\cs{glsentryparent}\marg{label} +\end{definition} +Expands to the label of the entry's parent. No existence check is +performed. + +\begin{definition}[\DescribeMacro\glsentrysort] +\cs{glsentrysort}\marg{label} +\end{definition} +Expands to the entry's sort value. No existence check is performed. + +You can fetch the value of a given field and store it in a control +sequence using: +\begin{definition}[\DescribeMacro\glsfieldfetch] +\cs{glsfieldfetch}\marg{label}\marg{field}\marg{cs} +\end{definition} +where \meta{label} is the label identifying the glossary entry, +\meta{field} is the field label (see \tableref{tab:fieldmap}) +and \meta{cs} is the control sequence in which to store the value. +Remember that \meta{field} is the internal label and is not +necessarily the same as the key used to set that field in the +argument of \cs{newglossaryentry} (or the optional argument of +\cs{newacronym}). + +You can change the value of a given field using one of the following +commands. Note that these commands only change the value of the +given field. They have no affect on any related field. For example, +if you change the value of the \gloskey{text} field, it won't modify the +value given by the \gloskey{name}, \gloskey{plural}, \gloskey{first} or any other related key. + +In all the four related commands below, \meta{label} and +\meta{field} are as above and \meta{definition} is the new value +of the field. + +\begin{definition}[\DescribeMacro\glsfielddef] +\cs{glsfielddef}\marg{label}\marg{field}\marg{definition} +\end{definition} +This uses \cs{def} to change the value of the field (so it will be +localised by any grouping). + +\begin{definition}[\DescribeMacro\glsfieldedef] +\cs{glsfieldedef}\marg{label}\marg{field}\marg{definition} +\end{definition} +This uses \cs{edef} to change the value of the field (so it will be +localised by any grouping). Any fragile commands contained in the +\meta{definition} must be protected. + +\begin{definition}[\DescribeMacro\glsfieldgdef] +\cs{glsfieldgdef}\marg{label}\marg{field}\marg{definition} +\end{definition} +This uses \cs{gdef} to change the value of the field. + +\begin{definition}[\DescribeMacro\glsfieldxdef] +\cs{glsfieldxdef}\marg{label}\marg{field}\marg{definition} +\end{definition} +This uses \cs{xdef} to change the value of the field. Any fragile +commands contained in the \meta{definition} must be protected. + + +\chapter{Prefixes or Determiners}\label{sec:prefix} + +The \sty{glossaries-prefix} package that comes with the +\styfmt{glossaries} package provides +additional keys that can be used as prefixes. For example, if you +want to specify determiners (such +as \qt{a}, \qt{an} or \qt{the}). The \styfmt{glossaries-prefix} +package automatically loads the \styfmt{glossaries} package and has +the same package options. + +The extra keys for \ics{newglossaryentry} are as follows: +\begin{description} +\item[\gloskey{prefix}] The prefix associated with the +\gloskey{text} key. This defaults to nothing. + +\item[\gloskey{prefixplural}] The prefix associated with the +\gloskey{plural} key. This defaults to nothing. + +\item[\gloskey{prefixfirst}] The prefix associated with the +\gloskey{first} key. If omitted, this defaults to the value of the +\gloskey{prefix} key. + +\item[\gloskey{prefixfirstplural}] The prefix associated with the +\gloskey{firstplural} key. If omitted, this defaults to the value of +the \gloskey{prefixplural} key. +\end{description} + +\begin{example}{Defining Determiners}{ex:determiners} +Here's the start of my example document: +\begin{verbatim} +\documentclass{article} + +\usepackage[colorlinks]{hyperref} +\usepackage[toc,acronym]{glossaries-prefix} +\end{verbatim} +Note that I've simply replaced \styfmt{glossaries} from previous +sample documents with \styfmt{glossaries-prefix}. Now for a sample +definition\footnote{Single letter words, such as \qt{a} and \qt{I} +should typically not appear at the end of a line, hence the +non-breakable space after \qt{a} in the \gloskey{prefix} field.}: +\begin{verbatim} +\newglossaryentry{sample}{name={sample},% + description={an example},% + prefix={a~},% + prefixplural={the\space}% +} +\end{verbatim} +Note that I've had to explicitly insert a~space after the prefix +since there's no designated separator between the prefix and the +term being referenced. This not only means that you can vary between +a breaking space and non-breaking space, but also +allows for the possibility of prefixes that shouldn't have a~space, +such as: +\begin{verbatim} +\newglossaryentry{oeil}{name={oeil}, + plural={yeux}, + description={eye}, + prefix={l'}, + prefixplural={les\space}} +\end{verbatim} +Where a space is required at the end of the prefix, you must use +a~spacing command, such as \cs{space}, \verb*|\ | (backslash space) or +\verb|~| due to the automatic spacing trimming performed in +\meta{key}=\meta{value} options. + +In the event that you always require a space between the prefix and +the term, then you can instead redefine +\begin{definition}[\DescribeMacro\glsprefixsep] +\cs{glsprefixsep} +\end{definition} +to do a space. (This command does nothing by default.) For example: +\begin{verbatim} +\renewcommand{\glsprefixsep}{\space} +\end{verbatim} + +The prefixes can also be used with acronyms. For example: +\begin{verbatim} +\newacronym + [% + prefix={an\space},prefixfirst={a~}% + ]{svm}{SVM}{support vector machine} +\end{verbatim} +\end{example} + +The \sty{glossaries-prefix} package provides convenient commands to +use these prefixes with commands such as \ics{gls}. Note that the +prefix is not considered part of the \gls{linktext}, so it's not +included in the hyperlink (where hyperlinks are enabled). The +options and any star or plus modifier are passed on to the \glslike\ +command. (See \sectionref{sec:glslink} for further details.) + +\begin{definition}[\DescribeMacro\pgls] +\cs{pgls}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +This is inserts the value of the \gloskey{prefix} key (or +\gloskey{prefixfirst} key, on \gls{firstuse}) in front of +\cs{gls}\oarg{options}\marg{label}\oarg{insert}. + +\begin{definition}[\DescribeMacro\Pgls] +\cs{Pgls}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +If the \gloskey{prefix} key (or \gloskey{prefixfirst}, on +\gls*{firstuse}) has been set, this displays the value of that key +with the first letter converted to upper case followed by +\cs{gls}\oarg{options}\marg{label}\oarg{insert}. If that key hasn't +been set, this is equivalent to +\ics{Gls}\oarg{options}\marg{label}\oarg{insert}. + +\begin{definition}[\DescribeMacro\PGLS] +\cs{PGLS}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +As \cs{pgls} but converts the prefix to upper case and uses +\ics{GLS} instead of \cs{gls}. + +\begin{definition}[\DescribeMacro\pglspl] +\cs{pglspl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +This is inserts the value of the \gloskey{prefixplural} key (or +\gloskey{prefixfirstplural} key, on \gls{firstuse}) in front of +\cs{glspl}\oarg{options}\marg{label}\oarg{insert}. + +\begin{definition}[\DescribeMacro\Pglspl] +\cs{Pglspl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +If the \gloskey{prefixplural} key (or \gloskey{prefixfirstplural}, on +\gls*{firstuse}) has been set, this displays the value of that key +with the first letter converted to upper case followed by +\cs{glspl}\oarg{options}\marg{label}\oarg{insert}. If that key hasn't +been set, this is equivalent to +\ics{Glspl}\oarg{options}\marg{label}\oarg{insert}. + +\begin{definition}[\DescribeMacro\PGLSpl] +\cs{PGLSpl}\oarg{options}\marg{label}\oarg{insert} +\end{definition} +As \cs{pglspl} but converts the prefix to upper case and uses +\ics{GLSpl} instead of \cs{glspl}. + +\begin{example}{Using Prefixes}{ex:prefixes} +Continuing from Example~\ref{ex:determiners}, now that I've defined +my entries, I~can use them in the text via the above commands: +\begin{verbatim} +First use: \pgls{svm}. Next use: \pgls{svm}. +Singular: \pgls{sample}, \pgls{oeil}. +Plural: \pglspl{sample}, \pglspl{oeil}. +\end{verbatim} +which produces: +\begin{quote} +First use: a~support vector machine (SVM). Next +use: an SVM. +Singular: a~sample, l'oeil. Plural: the samples, les yeux. +\end{quote} +For a complete document, see \samplefile{-prefix}. +\end{example} + +This package also provides the commands described below, none of +which perform any check to determine the entry's existence. + +\begin{definition}[\DescribeMacro\ifglshasprefix] +\cs{ifglshasprefix}\marg{label}\marg{true part}\marg{false part} +\end{definition} +Does \meta{true part} if the entry identified by \meta{label} has a +non-empty value for the \gloskey{prefix} key. + +This package also provides the following commands: +\begin{definition}[\DescribeMacro\ifglshasprefixplural] +\cs{ifglshasprefixplural}\marg{label}\marg{true part}\marg{false part} +\end{definition} +Does \meta{true part} if the entry identified by \meta{label} has a +non-empty value for the \gloskey{prefixplural} key. + +\begin{definition}[\DescribeMacro\ifglshasprefixfirst] +\cs{ifglshasprefixfirst}\marg{label}\marg{true part}\marg{false part} +\end{definition} +Does \meta{true part} if the entry identified by \meta{label} has a +non-empty value for the \gloskey{prefixfirst} key. + +\begin{definition}[\DescribeMacro\ifglshasprefixfirstplural] +\cs{ifglshasprefixfirstplural}\marg{label}\marg{true part}\marg{false part} +\end{definition} +Does \meta{true part} if the entry identified by \meta{label} has a +non-empty value for the \csoptfmt{prefix\-first\-plural} key. + +\begin{definition}[\DescribeMacro\glsentryprefix] +\cs{glsentryprefix}\marg{label} +\end{definition} +Displays the value of the \gloskey{prefix} key for the entry given +by \meta{label}. + +\begin{definition}[\DescribeMacro\glsentryprefixfirst] +\cs{glsentryprefixfirst}\marg{label} +\end{definition} +Displays the value of the \gloskey{prefixfirst} key for the entry given +by \meta{label}. + +\begin{definition}[\DescribeMacro\glsentryprefixplural] +\cs{glsentryprefixplural}\marg{label} +\end{definition} +Displays the value of the \gloskey{prefixplural} key for the entry given +by \meta{label}. (No check is performed to determine if the entry +exists.) + +\begin{definition}[\DescribeMacro\glsentryprefixfirstplural] +\cs{glsentryprefixfirstplural}\marg{label} +\end{definition} +Displays the value of the \gloskey{prefixfirstplural} key for the entry given +by \meta{label}. (No check is performed to determine if the entry +exists.) + +There are also variants that convert the first letter to upper +case\footnote{The earlier caveats about initial non-Latin characters +apply.}: +\begin{definition}[\DescribeMacro\Glsentryprefix] +\cs{Glsentryprefix}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro\Glsentryprefixfirst] +\cs{Glsentryprefixfirst}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro\Glsentryprefixplural] +\cs{Glsentryprefixplural}\marg{label} +\end{definition} + +\begin{definition}[\DescribeMacro\Glsentryprefixfirstplural] +\cs{Glsentryprefixfirstplural}\marg{label} +\end{definition} + +\begin{important} +As with analogous commands such as \ics{Glsentrytext}, these +commands aren't expandable so can't be used in PDF bookmarks. +\end{important} + +\begin{example}{Adding Determiner to Glossary Style}{ex:plist} +You can use the above commands to define a new glossary style that +uses the determiner. For example, the following style is a slight +modification of the \glostyle{list} style that inserts the prefix +before the name: +\begin{verbatim} +\newglossarystyle{plist}{% + \setglossarystyle{list}% + \renewcommand*{\glossentry}[2]{% + \item[\glsentryitem{##1}% + \glsentryprefix{##1}% + \glstarget{##1}{\glossentryname{##1}}] + \glossentrydesc{##1}\glspostdescription\space ##2}% +} +\end{verbatim} +If you want to change the prefix separator (\cs{glsprefixsep}) then +the following is better: +\begin{verbatim} +\newglossarystyle{plist}{% + \setglossarystyle{list}% + \renewcommand*{\glossentry}[2]{% + \item[\glsentryitem{##1}% + \ifglshasprefix{##1}{\glsentryprefix{##1}\glsprefixsep}{}% + \glstarget{##1}{\glossentryname{##1}}] + \glossentrydesc{##1}\glspostdescription\space ##2}% +} +\end{verbatim} +The conditional is also useful if you want the style to use an +uppercase letter at the start of the entry item: +\begin{verbatim} +\newglossarystyle{plist}{% + \setglossarystyle{list}% + \renewcommand*{\glossentry}[2]{% + \item[\glsentryitem{##1}% + \glstarget{##1}% + {% + \ifglshasprefix{##1}% + {\Glsentryprefix{##1}\glsprefixsep\glossentryname{##1}}% + {\Glossentryname{##1}}% + }] + \glossentrydesc{##1}\glspostdescription\space ##2}% +} +\end{verbatim} +\end{example} + +\chapter{Accessibility Support}\label{sec:accsupp} + +Limited accessibility support is provided by the accompanying +\sty{glossaries-accsupp} package, but note that this package is +experimental and it requires the \sty{accsupp} package +which is also listed as experimental. This package automatically +loads the \sty{glossaries} package. Any options are passed to +\sty{glossaries} (if it hasn't already been loaded). For example: +\begin{verbatim} +\usepackage[acronym]{glossaries-accsupp} +\end{verbatim} +This will load \sty{glossaries} with the \pkgopt{acronym} package +option as well as loading \sty{glossaries-accsupp}. + +If you are using the \gls{glossaries-extra} extension package, you +need to load \gls{glossaries-extra} with the \pkgopt*{accsupp} +package option. For example: +\begin{verbatim} +\usepackage[abbreviations,accsupp]{glossaries-extra} +\end{verbatim} +This will load \gls{glossaries-extra} (with the +\pkgopt*{abbreviations} option), \sty{glossaries} and +\sty{glossaries-accsupp} and make appropriate patches to integrate +the accessibility support with the extension commands. + +The \sty{glossaries-accsupp} package defines +additional keys that may be used when defining glossary entries. +The keys are as follows: +\begin{description}\raggedright +\item[{\gloskey{access}}] The replacement text corresponding to +the \gloskey{name} key. + +\item[{\gloskey{textaccess}}] The replacement text corresponding +to the \gloskey{text} key. + +\item[{\gloskey{firstaccess}}] The replacement text corresponding +to the \gloskey{first} key. + +\item[{\gloskey{pluralaccess}}] The replacement text corresponding +to the \gloskey{plural} key. + +\item[{\gloskey{firstpluralaccess}}] The replacement text corresponding +to the \gloskey{firstplural} key. + +\item[{\gloskey{symbolaccess}}] The replacement text corresponding +to the \gloskey{symbol} key. + +\item[{\gloskey{symbolpluralaccess}}] The replacement text corresponding +to the \gloskey{symbolplural} key. + +\item[{\gloskey{descriptionaccess}}] The replacement text corresponding +to the \gloskey{description} key. + +\item[{\gloskey{descriptionpluralaccess}}] The replacement text corresponding +to the \gloskey{descriptionplural} key. + +\item[{\gloskey{longaccess}}] The replacement text corresponding to +the \gloskey{long} key (used by \ics{newacronym}). + +\item[{\gloskey{shortaccess}}] The replacement text corresponding to +the \gloskey{short} key (used by \ics{newacronym}). + +\item[{\gloskey{longpluralaccess}}] The replacement text corresponding to +the \gloskey{longplural} key (used by \ics{newacronym}). + +\item[{\gloskey{shortpluralaccess}}] The replacement text corresponding to +the \gloskey{shortplural} key (used by \ics{newacronym}). + +\item[{\gloskey{user1access}}] The replacement text corresponding to +the \gloskey{user1} key. + +\item[{\gloskey{user2access}}] The replacement text corresponding to +the \gloskey{user2} key. + +\item[{\gloskey{user3access}}] The replacement text corresponding to +the \gloskey{user3} key. + +\item[{\gloskey{user4access}}] The replacement text corresponding to +the \gloskey{user4} key. + +\item[{\gloskey{user5access}}] The replacement text corresponding to +the \gloskey{user5} key. + +\item[{\gloskey{user6access}}] The replacement text corresponding to +the \gloskey{user6} key. +\end{description} +For example: +\begin{verbatim} +\newglossaryentry{tex}{name={\TeX},description={Document +preparation language},access={TeX}} +\end{verbatim} +Now the \gls{linktext} produced by \verb|\gls{tex}| will be: +\begin{verbatim} +\BeginAccSupp{ActualText={TeX}}\TeX\EndAccSupp{} +\end{verbatim} +The sample file \samplefile{accsupp} illustrates the +\sty{glossaries-accsupp} package. + +If you prefer to use \sty{accessibility} or \sty{tagpdf} instead of +\sty{accsupp} then you'll need to define \cs{gls@accsupp@engine} and +\cs{gls@accessibility} before loading \sty{glossaries-accsupp}. See +\ifpdf section~\ref*{sec:code:accsupp} \else the section +\qt{Accessibility Support}\fi in the documented code for further +details. + +The PDF specification identifies three different types of +replacement text: +\begin{description} +\item[Alt] Description of some content that's non-textual (for +example, an image). A word break is assumed after the content. +\item[ActualText] A character or sequence of characters that +replaces textual content (for example, a dropped capital, a +ligature or a symbol). No word break is assumed after the content. +\item[E] Expansion of an abbreviation to avoid ambiguity (for +example, \qt{St} could be short for \qt{saint} or \qt{street}). +\end{description} + +\begin{important} +Many PDF viewers don't actually support any type of replacement text. Some may +support \qt{ActualText} but not \qt{Alt} or \qt{E}. +\href{https://pdfbox.apache.org/}{PDFBox}'s \qt{PDFDebugger} tool +can be used to inspect the PDF content to make sure that the +replacement text has been correctly set. +\end{important} + +If you define abbreviations with \ics{newacronym}, the +\gloskey{shortaccess} field will automatically be set to: +\begin{definition}[\DescribeMacro\glsdefaultshortaccess] +\cs{glsdefaultshortaccess}\marg{long}\marg{short} +\end{definition} +With the base \styfmt{glossaries} package this just expands to +\meta{long}. With \gls{glossaries-extra} this expands to \meta{long} +(\meta{short}). This command must be fully expandable. It expands +when the abbreviation is defined. + +As from \sty{glossaries-accsupp} v4.45, the helper command used to +identify the replacement text depends on the field name. Previous +versions just used: +\begin{definition}[\DescribeMacro\glsaccsupp] +\cs{glsaccsupp}\marg{replacement}\marg{content} +\end{definition} +for all fields. This is defined to use \texttt{ActualText}, which is +appropriate for symbols but not for abbreviations. + +As from v4.45, there's a new helper command: +\begin{definition}[\DescribeMacro\glsfieldaccsupp] +\cs{glsfieldaccsupp}\marg{replacement}\marg{content}\marg{field}\marg{label} +\end{definition} +This will use \csmeta{gls}{field}{accsupp} if it's defined otherwise +it will just use \cs{glsaccsupp}. There are just two of these field +commands for \gloskey{short} and \gloskey{shortplural}: +\begin{definition}[\DescribeMacro\glsshortaccsupp] +\cs{glsshortaccsupp}\marg{replacement}\marg{content} +\end{definition} +which is like \cs{glsaccsupp} but uses \texttt{E} instead of +\texttt{ActualText} and +\begin{definition}[\DescribeMacro\glsshortplaccsupp] +\cs{glsshortplaccsupp}\marg{replacement}\marg{content} +\end{definition} +which just does \cs{glsshortaccsupp}\marg{replacement}\marg{content}. +Note that \meta{field} indicates the \emph{internal} field name +(such as \texttt{shortpl}) not the key name (such as +\texttt{shortplural}). See \tableref{tab:fieldmap}. + +Rather than explicitly using \ics{BeginAccSupp}, these helper +commands can use: +\begin{definition}[\DescribeMacro\glsaccessibility] +\cs{glsaccessibility}\oarg{options}\marg{tag}\marg{value}\marg{content} +\end{definition} +where \meta{tag} is one of \texttt{E}, \texttt{Alt} or +\texttt{ActualText}. The replacement text for \meta{content} should be provided in +\meta{value}. +This does: +\begin{alltt} +\ics{BeginAccSupp}\mgroup{\meta{tag}=\marg{value},\meta{options}}\meta{content}\ics{EndAccSupp}\mgroup{} +\end{alltt} +but it also provides debugging information if \pkgopt[showaccsupp]{debug} is used. +If you explicitly use \cs{BeginAccSupp} instead of this command then +the debugging support won't be available. + +You can define your own custom helper commands for specific fields +that require them. For example: +\begin{verbatim} +\newcommand{\glssymbolaccsupp}[2]{% + \glsaccessibility[method=hex,unicode]{ActualText}{#1}{#2}% +} +\end{verbatim} +This definition requires the replacement text to be specified with +the hexadecimal character code. For example: +\begin{verbatim} +\newglossaryentry{int}{name={int},description={integral}, + symbol={\ensuremath{\int}},symbolaccess={222B} +} +\end{verbatim} + +If you are using \gls{glossaries-extra}, then \cs{glsfieldaccsupp} +will first test for the existence of +\csmetameta*{glsxtr}{category}{}{field}{accsupp} +and \csmeta*{glsxtr}{category}{accsupp} and then for +\csmeta{gls}{field}{accsupp}. For example: +\begin{verbatim} +\usepackage{siunitx} +\usepackage[accsupp]{glossaries-extra} + +\glsnoexpandfields + +\newcommand{\glsxtrsymbolaccsupp}[2]{% + \glsaccessibility[method=hex,unicode]{ActualText}{#1}{#2}% +} + +\newcommand{\glsxtrunitaccsupp}[2]{\glsaccessibility{E}{#1}{#2}} + +\newglossaryentry{cm}{name={\si{\centi\metre}}, + access={centimetre}, + description={centimetre}, + category=unit +} + +\newglossaryentry{int}{name={\ensuremath{\int}},access={222B}, + description={integral},category={symbol} +} +\end{verbatim} +The above uses the \csmeta*{glsxtr}{category}{accsupp} form that +doesn't include the field name. Remember that if you want to supply +a command specifically for the \gloskey{name} field then it won't be +picked up by the \gloskey{text}, \gloskey{plural}, \gloskey{firstplural} and +\gloskey{first} fields. You'd need to supply them all. For example: +\begin{verbatim} +\newcommand{\glsnameaccsupp}[2]{% + \glsaccessibility[method=hex,unicode]{ActualText}{#1}{#2}% +} +\newcommand{\glstextaccsupp}{\glsnameaccsupp} +\newcommand{\glspluralaccsupp}{\glsnameaccsupp} +\newcommand{\glsfirstaccsupp}{\glsnameaccsupp} +\newcommand{\glsfirstplaccsupp}{\glsnameaccsupp} +\end{verbatim} + +See \ifpdf section~\ref*{sec:code:accsupp} in \fi the documented code +(\texttt{glossaries-code.pdf}) for further details. I~recommend +that you also read the \sty{accsupp} documentation. See also the +\sty{accessibility} and \sty{tagpdf} packages. + +\chapter{Sample Documents} +\label{sec:samples} + +The \styfmt{glossaries} package is provided with some sample +documents that illustrate the various functions. These should +be located in the \texttt{samples} subdirectory (folder) of the +\styfmt{glossaries} documentation directory. This location varies +according to your operating system and \TeX\ distribution. You +can use \texttt{texdoc} to locate the main glossaries documentation. +For example, in a +\href{http://www.dickimaw-books.com/latex/novices/html/terminal.html}{terminal or command prompt}, type: +\begin{prompt} +texdoc -l glossaries +\end{prompt} +This should display a list of all the files in the \styfmt{glossaries} +documentation directory with their full pathnames. (The GUI version +of \texttt{texdoc} may also provide you with the information.) + +If you can't find the sample files on your computer, they are also available +from your nearest CTAN mirror at +\url{http://mirror.ctan.org/macros/latex/contrib/glossaries/samples/}. +Each sample file listed below has a hyperlink to the file's location on +the CTAN mirror. + +The \gls{glossaries-extra} package and \gls{bib2gls} +provide some additional sample files. There are also examples in the +\gallery{}{Dickimaw Books Gallery}. + +If you prefer to use UTF-8 aware engines (\texttt{xelatex} or +\texttt{lualatex}) remember that you'll need to switch from +\styfmt{fontenc} \& \styfmt{inputenc} to \styfmt{fontspec} where +appropriate. + +\commandpromptnote +If you get any errors or unexpected results, check that you have up-to-date versions of +all the required packages. (Search the log file for lines starting +with \qt{\texttt{Package:\ }}.) Where \sty{hyperref} is loaded you will +get warnings about non-existent references that look something like: +\begin{verbatim} +pdfTeX warning (dest): name{glo:aca} has been +referenced but does not exist, replaced by a fixed one +\end{verbatim} +These warnings may be ignored on the first \LaTeX\ run. (The +destinations won't be defined until the glossary has been created.) + +\section{Basic} +\label{sec:samplesbasic} + +\exitem[minimal]{gls} This document is a +minimal working example. You can test your installation using this +file. To create the complete document you will need to do the +following steps: + \begin{enumerate} + \item Run \texttt{minimalgls.tex} through \LaTeX\ either by + typing +\begin{prompt} +pdflatex minimalgls +\end{prompt} + in a terminal or by using the relevant button or menu item in + your text editor or front-end. This will create the required + associated files but you will not see the glossary in the document. + + \item If you have Perl installed, run \gls{makeglossaries} on the document (\sectionref{sec:makeglossaries}). This can + be done on a terminal by typing: +\begin{prompt} +makeglossaries minimalgls +\end{prompt} + otherwise do: +\begin{prompt} +makeglossaries-lite minimalgls +\end{prompt} + If for some reason you want to call \gls{makeindex} explicitly, you can do this + in a terminal by typing (all on one line): +\begin{prompt} +makeindex -s minimalgls.ist -t minimalgls.glg -o minimalgls.gls minimalgls.glo +\end{prompt} + See \sectionref{sec:makeindexapp} for further details on using + \gls*{makeindex} explicitly. + + Note that if the file name contains spaces, you will need to use + the double-quote character to delimit the name. + + \item Run \texttt{minimalgls.tex} through \LaTeX\ again (as step~1) + \end{enumerate} +You should now have a complete document. The number following +each entry in the glossary is the location number. By default, this +is the page number where the entry was referenced. + +The \pkgopt{acronym} package option creates a second glossary with +the label \texttt{acronym} (which can be referenced with +\cs{acronymtype}). If you decide to enable this option then there +will be a second set of glossary files that need to be processed by +\gls{makeindex}. If you use \gls{makeglossaries} or +\gls{makeglossaries-lite.lua} you don't need to worry about it, as +those scripts automatically detect which files need to be processed +and will run \gls{makeindex} (or \gls{xindy}) the appropriate number +of times. + +If for some reason you don't want to use \gls{makeglossaries} or +\gls{makeglossaries-lite.lua} and you want the \pkgopt{acronym} +package option then the complete build process is: +\begin{prompt} +pdflatex minimalgls +makeindex -s minimalgls.ist -t minimalgls.glg -o minimalgls.gls minimalgls.glo +makeindex -s minimalgls.ist -t minimalgls.alg -o minimalgls.acr minimalgls.acn +pdflatex minimalgls +\end{prompt} + +There are three other files that can be used as +\href{http://www.dickimaw-books.com/latex/minexample/}{minimal working +examples}: \mirrorsamplefile{mwe-gls.tex}, \mirrorsamplefile{mwe-acr.tex} and +\mirrorsamplefile{mwe-acr-desc.tex}. + +\glsxtrnote +If you want to try out the \gls{glossaries-extra} extension package, +you need to replace the package loading line: +\begin{alltt} +\cs{usepackage}[acronym]\mgroup{\strong{glossaries}} +\end{alltt} +with: +\begin{alltt} +\cs{usepackage}[acronym\strong{,\xtrfont{postdot},\xtrfont{stylemods}}]\mgroup{\strong{glossaries-extra}} +\end{alltt} +Note the different default package options. (You may omit the +\pkgopt{acronym} package option in both cases if you only want a +single glossary.) The \gls{glossaries-extra} package internally +loads the base \styfmt{glossaries} package so you don't need to +explicitly load both (in fact, it's better to let +\gls{glossaries-extra} load \styfmt{glossaries}). + +Next, replace: +\begin{alltt} +\cs{setacronymstyle}\mgroup{long-short} +\end{alltt} +with: +\begin{alltt} +\ics*{setabbreviationstyle}[\strong{acronym}]\mgroup{long-short} +\end{alltt} +The optional argument \cat{acronym} identifies the category that +this style should be applied to. The \cs{newacronym} command +provided by the base \styfmt{glossaries} package is redefined by +\gls{glossaries-extra} to use \ics*{newabbreviation} with the category +set to \cat{acronym}. + +If you prefer to replace \cs{newacronym} with \ics*{newabbreviation} +then the default category is \cat{abbreviation} so the style should +instead be: +\begin{alltt} +\ics*{setabbreviationstyle}[\strong{abbreviation}]\mgroup{long-short} +\end{alltt} +This is actually the default category if the optional argument is +omitted, so you can simply do: +\begin{alltt} +\ics*{setabbreviationstyle}\mgroup{long-short} +\end{alltt} +The \abbrstyle{long-short} style is the default for the +\cat{abbreviation} category so you can omit this line completely if +you replace \cs{newacronym}. (The default style for the +\cat{acronym} category is \abbrstyle{short-nolong}, which only shows +the short form on \gls{firstuse}.) + +As mentioned earlier, the \pkgopt{acronym} package option creates a +new glossary with the label \texttt{acronym}. This is independent of +the \cat{acronym} category. You can use the \pkgopt{acronym} +package option with either \cs{newacronym} or \ics*{newabbreviation}. + +You may instead prefer to use the \pkgopt*{abbreviations} package +option, which creates a new glossary with the label \texttt{abbreviations}: +\begin{alltt} +\cs{usepackage}[\strong{\xtrfont{abbreviations}},\xtrfont{postdot},\xtrfont{stylemods}]\mgroup{\strong{glossaries-extra}} +\end{alltt} +This can again be used with either \cs{newacronym} or +\ics*{newabbreviation}, but the file extensions are different. This +isn't a problem if you are using \gls{makeglossaries} or +\gls{makeglossaries-lite.lua}. If you are explicitly calling +\gls{makeindex} (or \gls{xindy}) then you need to modify the file +extensions. +See the \gls{glossaries-extra} user manual for further details. + +If you use both the \pkgopt{acronym} and \pkgopt*{abbreviations} +package options then \cs{newacronym} will default to the +\texttt{acronym} glossary and \ics*{newabbreviation} will default to +the \texttt{abbreviations} glossary. + +\bibglsnote +If you want to try \gls{bib2gls}, you first need to convert the +document to use \gls{glossaries-extra} as described above. Then add +the \pkgopt*{record} package option. For example: +\begin{alltt} +\cs{usepackage}[\strong{\xtrfont{record}},\xtrfont{postdot},\xtrfont{stylemods}]\mgroup{\strong{glossaries-extra}} +\end{alltt} +Next you need to convert the entry definitions into the +\filetype{bib} format required by \gls{bib2gls}. This can easily be +done with \gls{convertgls2bib}. For example: +\begin{prompt} +convertgls2bib -{}-preamble-only minimalgls.tex entries.bib +\end{prompt} +This will create a file called \strong{\nolinkurl{entries.bib}}. Next, replace: +\begin{alltt} +\cs{makeglossaries} +\end{alltt} +with: +\begin{alltt} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=\strong{entries}] +\end{alltt} +Now remove all the entry definitions in the preamble +(\cs{longnewglossaryentry}, \cs{newglossaryentry} and \cs{newacronym} +or \cs{newabbreviation}). + +The abbreviation style command +must go before \ics*{GlsXtrLoadResources}. For example (if you are +using \cs{newacronym}): +\begin{alltt} +\ics*{setabbreviationstyle}[acronym]\mgroup{long-short} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=entries] +\end{alltt} +Finally, replace: +\begin{verbatim} +\printglossaries +\end{verbatim} +with: +\begin{alltt} +\ics*{printunsrtglossaries} +\end{alltt} +The document build is now: +\begin{prompt} +pdflatex minimalgls +bib2gls minimalgls +pdflatex minimalgls +\end{prompt} + +\exitem{DB} This document illustrates how +to load external files containing the glossary definitions. It also +illustrates how to define a new glossary type. This document has the +\gls{numberlist} suppressed and uses \hyperref[sec:glsadd]{\ics{glsaddall}} to add all +the entries to the glossaries without referencing each one +explicitly. (Note that it's more efficient to use +\gls{glossaries-extra} and \gls{bib2gls} if you have a large number +of entries.) To create the document do: +\begin{prompt} +pdflatex sampleDB +makeglossaries sampleDB +pdflatex sampleDB +\end{prompt} +or +\begin{prompt} +pdflatex sampleDB +makeglossaries-lite sampleDB +pdflatex sampleDB +\end{prompt} +The glossary definitions are stored in the accompanying files +\mirrorsamplefile{database1.tex} and \mirrorsamplefile{database2.tex}. If for some +reason you want to call \gls{makeindex} explicitly you must +have a separate call for each glossary: +\begin{enumerate} +\item Create the main glossary (all on one line): +\begin{prompt} +makeindex -s sampleDB.ist -t sampleDB.glg -o sampleDB.gls sampleDB.glo +\end{prompt} +\item Create the secondary glossary (all on one line): +\begin{prompt} +makeindex -s sampleDB.ist -t sampleDB.nlg -o sampleDB.not sampleDB.ntn +\end{prompt} +Note that both \gls{makeglossaries} and \gls{makeglossaries-lite.lua} do +this all in one call, so they not only make it easier because you +don't need to supply all the switches and remember all the +extensions but they also call \gls{makeindex} the appropriate number of times. +\end{enumerate} + +\bibglsnote +If you want to switch to using \gls{bib2gls} with \gls{glossaries-extra}, you can convert +\mirrorsamplefile{database1.tex} and \mirrorsamplefile{database2.tex} to \filetype{bib} +files using \gls{convertgls2bib}: +\begin{prompt} +convertgls2bib database1.tex database1.bib +convertgls2bib database2.tex database2.bib +\end{prompt} +The document code then needs to be: +\begin{alltt} +\cs{documentclass}\mgroup{article} + +\cs{usepackage}[colorlinks,plainpages=false]\mgroup{hyperref} +\cs{usepackage}[\strong{\xtrfont{record}},\xtrfont{postdot}]\mgroup{\strong{glossaries-extra}} + +\strong{\ics{newglossary*}}\mgroup{punc}\mgroup{Punctuation Characters} + +\ics*{GlsXtrLoadResources}[\resourceopt{src}=\mgroup{database1}, + \strong{\xtrfont{selection}=all},\resourceopt{sort}=en] +\ics*{GlsXtrLoadResources}[\resourceopt{src}=\mgroup{database2},\strong{\xtrfont{type}=punc,} + \strong{\xtrfont{selection}=all},\resourceopt{sort}=letter-case] + +\cs{begin}\mgroup{document} +\xtrfont{\cs{print\strong{unsrt}glossaries}} +\cs{end}\mgroup{document} +\end{alltt} +Note that the \pkgopt{nonumberlist} package option has been omitted. +It's not needed because there are no locations in this amended +document (whereas in the original \samplefile{DB} locations are +created with \cs{glsaddall}). The starred \ics{newglossary*} is used +since the \gls{makeindex}/\gls{xindy} extensions are now irrelevant. + +Instead of using \gls{makeglossaries} you need to use \gls{bib2gls} +when you build the document: +\begin{prompt} +pdflatex sampleDB +bib2gls sampleDB +pdflatex sampleDB +\end{prompt} +Note that one \gls{bib2gls} call processes all the indexing (rather +than one call per glossary). Unlike \gls{makeindex} and \gls{xindy}, +\gls{bib2gls} processes each resource set in turn, but the resource +sets aren't linked to a specific glossary. Multiple glossaries may +be processed in a single resource set or sub-blocks of a single +glossary may be processed by multiple resource sets. In this +example, there happens to be one resource set per glossary because +each glossary requires a different sort method. (A locale-sensitive +alphabetical sort for the first and a character code sort for the +second.) + +If you want letter groups, you need to use the \bibglslongopt{group} +switch: +\begin{prompt} +bib2gls -{}-group sampleDB +\end{prompt} +and use an appropriate glossary style. + +See also \bibglsgallery{sorting}, \bibglsbegin\ and the \gls{bib2gls} user manual. + +\section{Acronyms and First Use} +\label{sec:sampleacronyms} + +\exitem{Acr} This document has some +sample abbreviations. It also adds the glossary to the table of contents, +so an extra run through \LaTeX\ is required to ensure the document +is up to date: +\begin{prompt} +pdflatex sampleAcr +makeglossaries sampleAcr +pdflatex sampleAcr +pdflatex sampleAcr +\end{prompt} +(or use \gls{makeglossaries-lite.lua}). + +Note that if the glossary is at the start of the document +and spans across multiple pages, then this can cause the locations +to be shifted. In that case, an extra \gls{makeglossaries} and +\LaTeX\ call are required. In this particular example, the glossary +is at the end of the document so it's not a problem. It's also not a +problem for a glossary at the start of the document if the page +numbering is reset at the end of the glossary. For example, if the +glossary is at the end of the front matter in a book-style document. + +This document uses \ics{ifglsused} to determine whether to use +\qt{a} or \qt{an} in: +\begin{alltt} +\ldots\ is \ics{ifglsused}\mgroup{svm}\mgroup{an}\mgroup{a} \cs{gls}\mgroup{svm} \ldots +\end{alltt} +This clumsy bit of code can be tidied up with the +\sty{glossaries-prefix} package. Since that package automatically +loads \styfmt{glossaries} and passes all its options to the base +package it's possible to do a simple replacement of: +\begin{verbatim} +\usepackage[style=long,toc]{glossaries} +\end{verbatim} +with: +\begin{alltt} +\cs{usepackage}[style=long,toc]\mgroup{\strong{glossaries-prefix}} +\end{alltt} +The definition of \texttt{svm} now needs an adjustment: +\begin{alltt} +\ics{newacronym}[description=\mgroup{statistical pattern recognition +technique\string~\cs{protect}\cs{cite}\mgroup{svm}}, +\strong{prefixfirst=\mgroup{a\string~},prefix=\mgroup{an\ics{space}}} +]\mgroup{svm}\mgroup{svm}\mgroup{support vector machine} +\end{alltt} +The clumsy text can now simply be changed to: +\begin{alltt} +\ldots\ is \ics{pgls}\mgroup{svm} \ldots +\end{alltt} + +\glsxtrnote +If you want to convert this sample document to use \gls{glossaries-extra}, +you may want the patched version of the styles provided in \sty{glossary-long}, +in which case you can also add \pkgopt*{stylemods}: +\begin{alltt} +\cs{usepackage}[\strong{\xtrfont{stylemods},}style=long]\mgroup{\strong{glossaries-extra}} +\end{alltt} +If you want to suppress all the other glossary style packages with +\pkgopt{nostyles}, then you need to specify exactly which package +(or packages) that you do want: +\begin{alltt} +\cs{usepackage}[\strong{nostyles,}\xtrfont{stylemods\strong{=long}},style=long]\mgroup{glossaries-extra} +\end{alltt} +(Now that \gls{glossaries-extra} is being used, there are more +available \qt{long} styles in the \sty*{glossary-longextra} package, +which you may prefer.) + +If you want to use \sty{glossaries-prefix}, you can either load it +after \gls{glossaries-extra} or (with at least +\gls{glossaries-extra} v1.42) you can simply use the +\pkgopt*{prefix} package option. + +Note that the \pkgopt{toc} package option has been dropped. This is +the default with \gls{glossaries-extra}, so it doesn't need to be +specified now. The document build is now shorter: +\begin{prompt} +pdflatex sampleAcr +makeglossaries sampleAcr +pdflatex sampleAcr +\end{prompt} +The third \LaTeX\ call is no longer required to make the table of +contents up-to-date. This is because \gls{glossaries-extra} provides +boilerplate text on the first \LaTeX\ call when the glossary files +are missing. This means that the glossary header is added to the +\filetype{toc} file on the first \LaTeX\ call, whereas with just the +base \styfmt{glossaries} package, the header isn't present until the +second \LaTeX\ call. (As with just the base \styfmt{glossaries} +package, if the glossary occurs at the start of the document without +a page reset after it then part of the build process needs repeating +to ensure all referenced page numbers are up-to-date. This problem isn't +specific to the \sty{glossaries} package.) + +The other different default setting is the post-description +punctuation. The base package has \pkgopt[false]{nopostdot} as the +default. This means that a full stop (period) is automatically +inserted after the description in the glossary. The extension +package has \pkgopt[true]{nopostdot} as the default. If you want the +original behaviour then you can use \pkgopt[false]{nopostdot} or the +shorter synonym \pkgopt*{postdot}. + +The \gls{glossaries-extra} package has different +abbreviation handling that's far more flexible than that provided by +the base \styfmt{glossaries} package. The style now needs to be set with +\ics*{setabbreviationstyle} instead of \ics{setacronymstyle}: +\begin{alltt} +\strong{\ics*{setabbreviationstyle}[acronym]\mgroup{long-short-sc}} +\ics{newacronym}\mgroup{svm}\mgroup{svm}\mgroup{support vector machine} +\end{alltt} +(Note the different style name \abbrstyle{long-short-sc} instead of +\acrstyle{long-sc-short} and the optional argument \cat{acronym}.) If you +prefer to replace \ics{newacronym} with \ics*{newabbreviation} then +omit the optional argument: +\begin{alltt} +\ics*{setabbreviationstyle}\mgroup{long-short-sc} +\ics*{newabbreviation}\mgroup{svm}\mgroup{svm}\mgroup{support vector machine} +\end{alltt} +(The optional argument of \ics*{setabbreviationstyle} is the +category to which the style should be applied. If it's omitted, +\cat{abbreviation} is assumed. You can therefore have different +styles for different categories.) + +Finally, you need to replace \ics{acrshort}, \ics{acrlong} and +\ics{acrfull} and their variants with \ics*{glsxtrshort}, \ics*{glsxtrlong} and +\ics*{glsxtrfull} etc. + +\exitem{AcrDesc} This is similar to +the previous example, except that the abbreviations have an associated +description. As with the previous example, the glossary is added to +the table of contents, so an extra run through \LaTeX\ is required: +\begin{prompt} +pdflatex sampleAcrDesc +makeglossaries sampleAcrDesc +pdflatex sampleAcrDesc +pdflatex sampleAcrDesc +\end{prompt} +This document uses the \pkgopt{acronym} package option, which +creates a new glossary used by \cs{newacronym}. This leaves the +default \texttt{main} glossary available for general terms. However, +in this case there are no general terms so the \texttt{main} +glossary is redundant. The \pkgopt{nomain} package option will +prevent its creation. Obviously, if you decide to add some terms +with \cs{newglossaryentry} you will need to remove the +\pkgopt{nomain} option as the \texttt{main} glossary will now be +required. + +\glsxtrnote +As with the previous example, if you want to convert this document +to use \gls{glossaries-extra} you need to make a few modifications. +The most obvious one is to replace \texttt{glossaries} with +\texttt{glossaries-extra} in the \cs{usepackage} argument. Again you +can omit \pkgopt{toc} as this is the default for +\gls{glossaries-extra}. As in the previous example, you may want to +use the patched styles. This document uses \glostyle{altlist} which +is provided by \sty{glossary-list}, so the style can be patched with +\pkgopt*{stylemods}. +\begin{alltt} +\cs{usepackage}[acronym,nomain,style=altlist\strong{,\xtrfont{stylemods}}]\mgroup{\strong{glossaries-extra}} +\end{alltt} +You may prefer to replace the \pkgopt{acronym} option with +\pkgopt*{abbreviations}, but this will change the file extensions. +If you use \gls{makeglossaries} or \gls{makeglossaries-lite.lua} you +don't need to worry about it. + +Again the style command needs to be changed: +\begin{alltt} +\ics*{setabbreviationstyle}[acronym]\mgroup{long-short-sc-desc} +\end{alltt} +(Note the change in style name \abbrstyle{long-short-sc-desc} +instead of \acrstyle{long-sc-short-desc} and the optional argument \cat{acronym}.) + +As with the previous example, if +you prefer to use \ics*{newabbreviation} instead of \ics{newacronym} +then you need to omit the optional argument: +\begin{alltt} +\ics*{setabbreviationstyle}\mgroup{long-short-sc-desc} +\end{alltt} +The original document uses: +\begin{alltt} +\cs{renewcommand}*\mgroup{\ics{glsseeitemformat}}[1]\mgroup{\% + \ics{acronymfont}\mgroup{\ics{glsentrytext}\mgroup{\#1}}} +\end{alltt} +to ensure that the cross-references (from the \gloskey{see} key) use +the acronym font. The new abbreviation styles don't +use \ics{acronymfont} so this isn't appropriate with +\gls{glossaries-extra}. If you're using at least version 1.42 of +\gls{glossaries-extra}, you don't need to do anything as it +automatically redefines \ics{glsseeitemformat} to take the style +formatting into account. If you have an earlier version you can +redefine this command as follows: +\begin{alltt} +\cs{renewcommand}*\mgroup{\ics{glsseeitemformat}}[1]\mgroup{\% + \ics{ifglshasshort}\mgroup{\#1}\mgroup{\ics*{glsfmttext}\mgroup{\#1}}\mgroup{\ics*{glsfmtname}\mgroup{\#1}}\% +} +\end{alltt} +This will just show the short form in the cross-reference. If you +prefer the name instead (which includes the short and long form) you can use: +\begin{alltt} +\cs{renewcommand}*\mgroup{\ics{glsseeitemformat}}[1]\mgroup{\ics*{glsfmtname}\mgroup{\#1}} +\end{alltt} + +The \gls{glossaries-extra} package provides two additional +cross-referencing keys \xtrgloskey{seealso} and \xtrgloskey{alias}, +so \texttt{\gloskey{see}=\mgroup{[see also]\mgroup{svm}}} +can be replaced with a more appropriate key: +\begin{alltt} +\ics{newacronym}[description=\mgroup{Statistical pattern recognition +technique using the ``kernel trick''}, +\strong{\xtrgloskey{seealso}=\mgroup{svm}}, +]\mgroup{ksvm}\mgroup{ksvm}\mgroup{kernel support vector machine} +\end{alltt} + +Finally, as with the previous example, you need to replace +\ics{acrshort}, \ics{acrlong} and \ics{acrfull} etc with +\ics*{glsxtrshort}, \ics*{glsxtrlong} and \ics*{glsxtrfull} etc. + +\bibglsnote +If you want to convert this document so that it uses \gls{bib2gls}, +you first need to convert it to use \gls{glossaries-extra}, as above, +but remember that you now need the \pkgopt*{record} option: +\begin{alltt} +\cs{usepackage}[acronym,nomain,style=altlist,\strong{\xtrfont{record},\xtrfont{postdot},\xtrfont{stylemods}}] +\mgroup{\strong{glossaries-extra}} +\end{alltt} +Now you need to convert the abbreviation definitions to the \filetype{bib} +format required by \gls{bib2gls}. This can be done with: +\begin{prompt} +convertgls2bib -{}-preamble-only sampleAcrDesc.tex entries.bib +\end{prompt} +If you retained \ics{newacronym} from the original example file, +then the new \nolinkurl{entries.bib} file will contain entries +defined with \atentry{acronym}. For example: +\begin{alltt} +\atentry{acronym}\mgroup{ksvm, + description = \mgroup{Statistical pattern recognition technique + using the ``kernel trick''}, + \xtrfont{seealso} = \mgroup{svm}, + short = \mgroup{ksvm}, + long = \mgroup{kernel support vector machine} +} +\end{alltt} +If you switched to \ics*{newabbreviation} then the entries will +instead be defined with \atentry{abbreviation}. + +Next replace \cs{makeglossaries} with the resource command, but note +that the abbreviation style must be set first: +\begin{alltt} +\strong{\ics*{setabbreviationstyle}[acronym]\mgroup{long-short-sc-desc}} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=entries,\% terms defined in entries.bib + \strong{\xtrfont{abbreviation-sort-fallback}=long}] +\end{alltt} +Another possibility is to make \atentry{acronym} behave as though it +was actually \atentry{abbreviation}: +\begin{alltt} +\strong{\ics*{setabbreviationstyle}\mgroup{long-short-sc-desc}} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=entries,\resourceopt{abbreviation-sort-fallback}=long\strong{, + entry-type-aliases=\mgroup{acronym=abbreviation}}] +\end{alltt} +Note that the category is now \cat{abbreviation} not \cat{acronym} so the optional +argument of \ics*{setabbreviationstyle} needs adjusting. + +If the \gloskey{sort} field is missing (which should usually be the +case), then both \atentry{acronym} and \atentry{abbreviation} will +fallback on the \gloskey{short} field (not the \gloskey{name} field, +which is usually set by the style and therefore not visible to +\gls{bib2gls}). For some styles, as in this example, it's more +appropriate to sort by the long form so the fallback is changed. +(Remember that you will break this fallback mechanism if you +explicitly set the sort value.) See the \gls{bib2gls} manual for +further details and other examples. + +Remember to delete any \cs{newacronym} or \cs{newabbreviation} in +the \filetype{tex} file. +Finally replace \cs{printglossary} with \ics*{printunsrtglossary}. +The document build is now: +\begin{prompt} +pdflatex sampleAcrDesc +bib2gls sampleAcrDesc +pdflatex sampleAcrDesc +\end{prompt} + +Note that it's now much easier to revert back to the descriptionless +style used in \samplefile{Acr}: +\begin{alltt} +\ics*{setabbreviationstyle}[acronym]\mgroup{\strong{long-short-sc}} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=entries\strong{,\resourceopt{ignore-fields}=description}] +\end{alltt} +With the other options it would be necessary to delete all the +\gloskey{description} fields from the abbreviation definitions in +order to omit them, but with \gls{bib2gls} you can simply instruct +\gls{bib2gls} to ignore the description. This makes it much easier +to have a large database of abbreviations for use across multiple +documents that may or may not require the description. + +\exitem{Desc} This is similar to the +previous example, except that it defines the abbreviations using +\ics{newglossaryentry} instead of \ics{newacronym}. As with the +previous example, the glossary is added to the table of contents, so +an extra run through \LaTeX\ is required: +\begin{prompt} +pdflatex sampleDesc +makeglossaries sampleDesc +pdflatex sampleDesc +pdflatex sampleDesc +\end{prompt} +This sample file demonstrates the use of the \gloskey{first} and +\gloskey{text} keys but in general it's better to use +\ics{newacronym} instead as it's more flexible. For even greater +flexibility use \ics*{newabbreviation} provided by \gls{glossaries-extra}. +For other variations, such as showing the symbol on \gls{firstuse}, +you may prefer to make use of the post-link category hook. For +examples, see the section \qt{Changing the Formatting} in \bibglsbegin. + +\exitem{FnAcrDesc} This document has some sample abbreviations that +use the \acrstyle{footnote-sc-desc} acronym style. As with the previous example, +the glossary is added to the table of contents, so an extra run through +\LaTeX\ is required: +\begin{prompt} +pdflatex sampleFnAcrDesc +makeglossaries sampleFnAcrDesc +pdflatex sampleFnAcrDesc +pdflatex sampleFnAcrDesc +\end{prompt} +\glsxtrnote +If you want to convert this sample document to use +\gls{glossaries-extra}, then you just need to follow the same steps +as for \samplefile{Acr} with a slight modification. This time the +\abbrstyle{short-sc-footnote-desc} abbreviation style is needed: +\begin{alltt} +\ics*{setabbreviationstyle}[acronym]\mgroup{short-sc-footnote-desc} +\end{alltt} +The command redefinitions (performed with \cs{renewcommand}) should +now all be deleted as they are no longer applicable. + +You may prefer to use the \abbrstyle{short-sc-postfootnote-desc} +style instead. There are subtle differences between the \abbrstyle{postfootnote} and +\abbrstyle{footnote} set of styles. Try changing the abbreviation style to +\abbrstyle{short-sc-footnote} and compare the location of the footnote marker +with the two styles. + +This modified sample file now has a shorter build: +\begin{prompt} +pdflatex sampleFnAcrDesc +makeglossaries sampleFnAcrDesc +pdflatex sampleFnAcrDesc +\end{prompt} +This is because the \gls{glossaries-extra} package produces +boilerplate text when the glossary file is missing (on the first +\LaTeX\ run) which adds the glossary title to the table of contents +(\filetype{toc}) file. + +\exitem{CustomAcr} This document has some sample abbreviations with a +custom acronym style. It also adds the glossary to the table of +contents, so an extra run through \LaTeX\ is required: +\begin{prompt} +pdflatex sampleCustomAcr +makeglossaries sampleCustomAcr +pdflatex sampleCustomAcr +pdflatex sampleCustomAcr +\end{prompt} +This is a slight variation on the previous example where the name is +in the form \meta{long} (\meta{short}) instead of \meta{short} +(\meta{long}), and the \gloskey{sort} key is set to the long form +instead of the short form. On \gls{firstuse}, the footnote text is +in the form \meta{long}: \meta{description} (instead of just the +long form). This requires defining a new acronym +style that inherits from the \acrstyle{footnote-sc-desc} style. + +\glsxtrnote +The conversion to \gls{glossaries-extra} starts in much the same way +as the previous examples: +\begin{alltt} +\cs{usepackage}[acronym,nomain,\strong{\xtrfont{postdot},\xtrfont{stylemods},}style=altlist] +\mgroup{\strong{glossaries-extra}} +\end{alltt} +The abbreviation styles have associated helper commands that may be +redefined to make minor modifications. These redefinitions should be +done before the abbreviations are defined. + +The \abbrstyle{short-sc-footnote-desc} abbreviation style is the closest match +to the requirement, so replace the \cs{setacronymstyle} command +with: +\begin{alltt} +\ics*{setabbreviationstyle}[acronym]\mgroup{short-sc-footnote-desc} +\end{alltt} +Again, you may prefer \abbrstyle{short-sc-postfootnote-desc}. Both +styles use the same helper commands. + +Next some adjustments need to be made to fit the new requirements. +The name needs to be \meta{long} (\meta{short}): +\begin{alltt} +\cs{renewcommand}*\mgroup{\ics*{glsxtrfootnotedescname}}\mgroup{\% + \cs{protect}\strong{\ics*{glslongfont}\mgroup{\cs{the}\ics{glslongtok}}}\% + \cs{protect}\ics*{glsxtrfullsep}\mgroup{\cs{the}\ics{glslabeltok}}\% + \cs{protect}\ics*{glsxtrparen}\mgroup{\cs{protect}\strong{\ics*{glsabbrvfont}\mgroup{\cs{the}\ics{glsshorttok}}}}\% +} +\end{alltt} +This command expands when the abbreviations are defined so take care +to \cs{protect} commands that shouldn't be expanded at that point, +and make sure that the token registers that store the label, long +and short values are able to expand. Similarly the sort value needs +adjusting: +\begin{alltt} +\cs{renewcommand}*\mgroup{\ics*{glsxtrfootnotedescsort}}\mgroup{\strong{\cs{the}\ics{glslongtok}}} +\end{alltt} +The footnote for all the footnote abbreviation styles is produced +with: +\begin{alltt} +\ics*{glsxtrabbrvfootnote}\marg{label}\marg{text} +\end{alltt} +where \meta{text} is the singular or plural long form, depending on +what command was used to reference the abbreviation (\cs{gls}, +\cs{glspl} etc). This can simply be redefined as: +\begin{alltt} +\cs{renewcommand}*\mgroup{\ics*{glsxtrabbrvfootnote}}[2]\mgroup{\ics{footnote}\mgroup{\% + \#2: \ics{glsentrydesc}\mgroup{\#1}}} +\end{alltt} +This will mimic the result from the original sample document. + +You may prefer to replace \verb|#2| with a reference to a +specific field (or fields). For example: +\begin{alltt} +\cs{renewcommand}*\mgroup{\ics*{glsxtrabbrvfootnote}}[2]\mgroup{\ics{footnote}\mgroup{\% + \ics*{Glsfmtlong}\mgroup{\#1} (\ics*{glsfmtshort}\mgroup{\#1}): \ics{glsentrydesc}\mgroup{\#1}.}} +\end{alltt} +As with the earlier \samplefile{AcrDesc}, you need to remove or change the redefinition of +\ics{glsseeitemformat} since \cs{acronymfont} is no longer appropriate. + +In the original \texttt{sampleCustomAcr.tex} source code, I started +the description with a capital: +\begin{verbatim} +\newacronym[description={Statistical pattern recognition +technique using the ``kernel trick''}, +see={[see also]{svm}}, +]{ksvm}{ksvm}{kernel support vector machine} +\end{verbatim} +This leads to a capital letter after the colon in the footnote, +which is undesirable, but I would like to have the description start +with a capital in the glossary. The solution to this problem is +easy with \gls{glossaries-extra}. I start the description with a +lowercase letter and set the \attr{glossdesc} attribute to +\optfmt{firstuc}: +\begin{alltt} +\ics*{glssetcategoryattribute}\mgroup{acronym}\mgroup{glossdesc}\mgroup{firstuc} +\end{alltt} +The abbreviation definitions are modified slightly: +\begin{alltt} +\ics{newacronym}[description=\mgroup{\strong{s}tatistical pattern recognition +technique using the ``kernel trick''}, +\strong{\xtrgloskey{seealso}=\mgroup{svm}}, +]\mgroup{ksvm}\mgroup{ksvm}\mgroup{kernel support vector machine} +\end{alltt} +Note the use of the \xtrgloskey{seealso} key, which is only +available with \gls{glossaries-extra}. + +If you prefer to use \ics*{newabbreviation} instead of +\ics{newacronym}, then the category needs to be +\cat{abbreviation} rather than \cat{acronym}: +\begin{alltt} +\ics*{glssetcategoryattribute}\mgroup{\strong{abbreviation}}\mgroup{glossdesc}\mgroup{firstuc} +\end{alltt} +and the style command needs to be adjusted so that it omits the +optional argument. For example: +\begin{alltt} +\ics*{setabbreviationstyle}\mgroup{short-sc-postfootnote-desc} +\end{alltt} + +\exitem{-FnDesc} This example +defines a custom display format that puts the description in a +footnote on \gls{firstuse}. +\begin{prompt} +pdflatex sample-FnDesc +makeglossaries sample-FnDesc +pdflatex sample-FnDesc +\end{prompt} +In order to prevent nested hyperlinks, this document uses the +\pkgopt[false]{hyperfirst} package option (otherwise the footnote +marker hyperlink would be inside the hyperlink around the +\gls{linktext} which would result in a nested hyperlink). + +\glsxtrnote +The \gls{glossaries-extra} package has category post-link hooks that +make it easier to adjust the formatting. The post-link hook is +placed after the hyperlink around the \gls{linktext}, so a hyperlink +created by \ics{footnote} in the post-link hook won't cause a nested +link. This means that the \pkgopt[false]{hyperfirst} option isn't +required: +\begin{alltt} +\cs{usepackage}[\xtrfont{postdot},\xtrfont{stylemods}]\mgroup{\strong{glossaries-extra}} +\end{alltt} + +\begin{important} +Never use commands like \cs{gls} or \cs{glsdesc} in the post-link +hook as you can end up with infinite recursion. Use commands that +don't themselves have a post-link hook, such as \cs{glsentrydesc} or +\cs{glossentrydesc}, instead. +\end{important} + +In the original \texttt{sample-FnDesc.tex} file, the format was +adjusted with: +\begin{alltt} +\cs{renewcommand}*\mgroup{\ics{glsentryfmt}}\mgroup{\% + \ics{glsgenentryfmt} + \ics{ifglsused}\mgroup{\ics{glslabel}}\mgroup{}\mgroup{\ics{footnote}\mgroup{\ics{glsentrydesc}\mgroup{\ics{glslabel}}}}% +} +\end{alltt} +This can be changed to: +\begin{alltt} +\ics*{glsdefpostlink} +\mgroup{general}\% category label +\mgroup{\ics*{glsxtrifwasfirstuse}\mgroup{\ics{footnote}\mgroup{\ics{glsentrydesc}\mgroup{\ics{glslabel}}}}\mgroup{}} +\end{alltt} +This sets the post-link hook for the \cat{general} category +(which is the default category for entries defined with \ics{newglossaryentry}). If I +added some abbreviations (which have a different category) then this +change wouldn't apply to them. + +The first paragraph in the document is: +\begin{verbatim} +First use: \gls{sample}. +\end{verbatim} +So the PDF will have the word \qt{sample} (the \gls{linktext} +created by \verb|\gls{sample}|) as a hyperlink to the entry in the +glossary followed by the footnote marker, which is a hyperlink to +the footnote. This is then followed by the sentence terminator. +\qt{First use: sample\textsuperscript{1}.} + +It would look tidier if the footnote marker could be shifted after +the full stop. \qt{First use: sample.\textsuperscript{1}} +This can easily be achieved with a minor modification: +\begin{alltt} +\ics*{glsdefpostlink} +\mgroup{general}\% category label +\mgroup{\ics*{glsxtrifwasfirstuse} + \mgroup{\ics*{glsxtrdopostpunc}\mgroup{\ics{footnote}\mgroup{\ics{glsentrydesc}\mgroup{\ics{glslabel}}}}}\% + \mgroup{}\% +} +\end{alltt} +You may prefer to use \ics{glossentrydesc} instead of +\ics{glsentrydesc}. This will obey the \attr{glossdesc} attribute. +If you append \ics{glspostdescription}, you can also pick up the +\pkgopt*{postdot} package option. For example: +\begin{alltt} +\ics*{glssetcategoryattribute}\mgroup{general}\mgroup{glossdesc}\mgroup{firstuc} + +\ics*{glsdefpostlink} +\mgroup{general}\% category label +\mgroup{\ics*{glsxtrifwasfirstuse} + \mgroup{\ics*{glsxtrdopostpunc}\mgroup{\ics{footnote}\mgroup{\% + \strong{\ics{glossentrydesc}}\mgroup{\ics{glslabel}}\strong{\ics{glspostdescription}}}}}\% + \mgroup{}\% +} +\end{alltt} +Alternatively, you could just use \ics{Glsentrydesc} and explicitly +append the full stop. + +\exitem{-custom-acronym} +This document illustrates how to define your own acronym style if +the predefined styles don't suit your requirements. +\begin{prompt} +pdflatex sample-custom-acronym +makeglossaries sample-custom-acronym +pdflatex sample-custom-acronym +\end{prompt} +In this case, a style is defined to show the short form in the text +with the long form and description in a footnote on \gls{firstuse}. +The long form is used for the \gloskey{sort} value. +The short form is displayed in \gls{smallcaps} in the main part of the +document but in uppercase in the list of acronyms. (So it's a slight +variation of some of the examples above.) The \gloskey{name} is set +to the long form (starting with an initial capital) followed by the +all caps short form in parentheses. The final requirement is that +the inline form should show the long form followed by the short form +in parentheses. + +\glsxtrnote +As with \samplefile{FnAcrDesc}, the \abbrstyle{short-sc-footnote-desc} +and \abbrstyle{short-sc-postfootnote-desc} abbreviation styles produce +almost the required effect so one of those can be used as a starting point. +However the final requirement doesn't fit. It's now necessary to actually define a custom +abbreviation style, but it can mostly inherit from the +\abbrstyle{short-sc-footnote-desc} or \abbrstyle{short-sc-postfootnote-desc} style: +\begin{alltt} +\ics*{newabbreviationstyle}\mgroup{custom-fn}\% +\mgroup{\% + \ics*{GlsXtrUseAbbrStyleSetup}\mgroup{short-sc-footnote-desc}\% +}\% +\mgroup{\% + \ics*{GlsXtrUseAbbrStyleFmts}\mgroup{short-sc-footnote-desc}\% + \cs{renewcommand}*\mgroup{\ics*{glsxtrinlinefullformat}}[2]\mgroup{\% + \strong{\ics*{glsfirstlongfootnotefont}}\mgroup{\strong{\ics*{glsaccesslong}\mgroup{\#\#1}}\% + \ics*{ifglsxtrinsertinside}\#\#2\cs{fi}}\% + \ics*{ifglsxtrinsertinside}\cs{else}\#\#2\cs{fi}\ics*{glsxtrfullsep}\mgroup{\#\#1}\% + \ics*{glsxtrparen}\mgroup{\strong{\ics*{glsfirstabbrvscfont}\mgroup{\ics*{glsaccessshort}\mgroup{\#\#1}}}}\% + }\% + \cs{renewcommand}*\mgroup{\ics*{glsxtrinlinefullplformat}}[2]\mgroup{\% + \strong{\ics*{glsfirstlongfootnotefont}}\mgroup{\strong{\ics*{glsaccesslongpl}\mgroup{\#\#1}}\% + \ics*{ifglsxtrinsertinside}\#\#2\cs{fi}}% + \ics*{ifglsxtrinsertinside}\cs{else}\#\#2\cs{fi}\ics*{glsxtrfullsep}\mgroup{\#\#1}\% + \ics*{glsxtrparen}\mgroup{\strong{\ics*{glsfirstabbrvscfont}\mgroup{\ics*{glsaccessshortpl}\mgroup{\#\#1}}}}\% + }% + \cs{renewcommand}*\mgroup{\ics*{Glsxtrinlinefullformat}}[2]\mgroup{\% + \strong{\ics*{glsfirstlongfootnotefont}}\mgroup{\strong{\ics*{Glsaccesslong}\mgroup{\#\#1}}\% + \ics*{ifglsxtrinsertinside}\#\#2\cs{fi}}\% + \ics*{ifglsxtrinsertinside}\cs{else}\#\#2\cs{fi}\ics*{glsxtrfullsep}\mgroup{\#\#1}\% + \ics*{glsxtrparen}\mgroup{\strong{\ics*{glsfirstabbrvscfont}\mgroup{\ics*{glsaccessshort}\mgroup{\#\#1}}}}\% + }\% + \cs{renewcommand}*\mgroup{\ics*{Glsxtrinlinefullplformat}}[2]\mgroup{\% + \strong{\ics*{glsfirstlongfootnotefont}}\mgroup{\strong{\ics*{Glsaccesslongpl}\mgroup{\#\#1}}\% + \ics*{ifglsxtrinsertinside}\#\#2\cs{fi}}\% + \ics*{ifglsxtrinsertinside}\cs{else}\#\#2\cs{fi}\ics*{glsxtrfullsep}\mgroup{\#\#1}\% + \ics*{glsxtrparen}\mgroup{\strong{\ics*{glsfirstabbrvscfont}\mgroup{\ics*{glsaccessshortpl}\mgroup{\#\#1}}}}\% + }\% +} +\end{alltt} +(See the \gls{glossaries-extra} user manual for further details.) + +This new custom style now needs to be set: +\begin{alltt} +\ics*{setabbreviationstyle}[acronym]\mgroup{custom-fn} +\end{alltt} +Remember that if you decide to use \ics*{newabbreviation} instead +of \ics{newacronym} then the category will be \cat{abbreviation} not \cat{acronym}: +\begin{alltt} +\ics*{setabbreviationstyle}\mgroup{custom-fn} +\end{alltt} +This custom style simply adjusts the inline full form. There are other +adjustments to be made that apply to the inherited style. (The alternative is to +design a new style from scratch.) The footnote contains the long form followed by the +description. This is the same as the modification to an earlier +example: +\begin{alltt} +\cs{renewcommand}*\mgroup{\ics*{glsxtrabbrvfootnote}}[2]\mgroup{\ics{footnote}\mgroup{\#2: +\ics{glsentrydesc}\mgroup{\#1}.}} +\end{alltt} +As with \samplefile{CustomAcr}, if you specifically +want the singular long form then you can ignore the second argument. +For example: +\begin{alltt} +\cs{renewcommand}*\mgroup{\ics*{glsxtrabbrvfootnote}}[2]\mgroup{\ics{footnote} + \mgroup{\ics*{Glsfmtlong}\mgroup{\#1}: \ics{glsentrydesc}\mgroup{\#1}.}} +\end{alltt} + +The \gloskey{name} now needs to be the long form followed by the +short form in parentheses, but note the new requirement that the +short form should now be in all capitals not \gls{smallcaps} and the +long form should start with a capital letter. +\begin{alltt} +\cs{renewcommand}*\mgroup{\ics*{glsxtrfootnotedescname}}\mgroup{\% + \cs{protect}\ics*{glsfirstlongfootnotefont} + \mgroup{\ics{makefirstuc}\mgroup{\cs{the}\ics{glslongtok}}} + (\cs{protect}\ics{MakeTextUppercase}\mgroup{\cs{the}\ics{glsshorttok}})\% +} +\end{alltt} +The inherited abbreviation style uses the short form as the +\gloskey{sort} value by default. This needs to be changed to the long form: +\begin{alltt} +\cs{renewcommand}*\mgroup{\ics*{glsxtrfootnotedescsort}}\mgroup{\cs{the}\strong{\ics{glslongtok}}} +\end{alltt} + +\begin{bib2gls} +If you want to switch to using \gls{bib2gls}, remember to set the +abbreviation style before the resource command and change the +default sort fallback field to \gloskey{long}, as with +\samplefile{AcrDesc}. +\end{bib2gls} + +\exitem{-dot-abbr} This document illustrates how to use the base +post link hook to adjust the space factor after abbreviations. +\begin{prompt} +pdflatex sample-dot-abbr +makeglossaries sampledot-abbrf +pdflatex sample-dot-abbr +\end{prompt} +This example creates a custom storage key that provides a similar +function to \gls{glossaries-extra}['s] \xtrgloskey{category} key. + +\glsxtrnote +This example is much simpler with \gls{glossaries-extra}. The custom +storage key, which is defined using: +\begin{alltt} +\ics{glsaddstoragekey}\mgroup{abbrtype}\mgroup{word}\mgroup{\cs{abbrtype}} +\end{alltt} +can now be removed. + +The \xtrgloskey{category} key is set to \texttt{initials} for +the initialisms (which are defined with the custom \cs{newacr} +command). The abbreviation styles can be set with: +\begin{alltt} +\ics*{setabbreviationstyle}[acronym]\mgroup{long-short} +\ics*{setabbreviationstyle}[initials]\mgroup{long-short} +\end{alltt} +The \attr{discardperiod} attribute will discard any full stop +(period) following commands like \cs{gls}: +\begin{alltt} +\ics*{glssetcategoryattribute}\mgroup{initials}\mgroup{discardperiod}\mgroup{true} +\end{alltt} +(If you want to use the \attr{noshortplural} attribute then you will +also need to set the \attr{pluraldiscardperiod} attribute.) + +The \gls{firstuse} is governed by the \attr{retainfirstuseperiod} +attribute. If set, the period won't be discarded if it follows the +\gls{firstuse} of commands like \cs{gls}. This is useful for styles +where the \gls{firstuse} doesn't end with the short form. In this +case, the \gls{firstuse} of the \abbrstyle{long-short} style ends +with a closing parenthesis, so the end of sentence might be clearer +if the period is retained: +\begin{alltt} +\ics*{glssetcategoryattribute}\mgroup{initials}\mgroup{retainfirstuseperiod}\mgroup{true} +\end{alltt} + +The \attr{insertdots} attribute can automatically insert dots into +the short form with a final space factor adjustment: +\begin{alltt} +\ics*{glssetcategoryattribute}\mgroup{initials}\mgroup{insertdots}\mgroup{true} +\end{alltt} + +The custom helper command defined in the example needs to be +slightly modified: +\begin{alltt} +\cs{newcommand}*\mgroup{\cs{newabbr}}[1][]\mgroup{\% + \strong{\ics*{newabbreviation}}[\strong{\xtrfont{category}}=initials,\#1]} +\end{alltt} +The definitions need to be slightly modified to work with the +\attr{insertdots} attribute: +\begin{alltt} +\cs{newabbr}\mgroup{eg}\mgroup{\strong{eg}}\mgroup{eg} +\cs{newabbr}\mgroup{ie}\mgroup{\strong{ie}}\mgroup{ie} +\cs{newabbr}\mgroup{bsc}\mgroup{\strong{B\mgroup{Sc}}}\mgroup{Bachelor of Science} +\cs{newabbr}\mgroup{ba}\mgroup{\strong{BA}}\mgroup{BA} +\cs{newabbr}\mgroup{agm}\mgroup{\strong{AGM}}\mgroup{AGM} +\end{alltt} +(This makes it much easier to change your mind if you decide at a +later date to omit the dots, especially if you are storing all your +definitions in a file that's shared across multiple documents, but +note the need to group \qt{Sc}.) + +The \qt{laser} definition remains unchanged: +\begin{verbatim} +\newacronym{laser}{laser}{light amplification by stimulated +emission of radiation} +\end{verbatim} +The remaining code in the preamble must now be removed. (It will +interfere with \gls{glossaries-extra}['s] category post-link hooks.) +No change is required in the document body. + +See the \gls{glossaries-extra} user manual for further details about +category attributes and post-link hooks. + +\exitem{-font-abbr} This document illustrates how to have different fonts +for abbreviations within the style. The document build is: +\begin{prompt} +pdflatex sample-font-abbr +makeglossaries sample-font-abbr +pdflatex sample-font-abbr +\end{prompt} +The acronym mechanism provided by the base \styfmt{glossaries} +package isn't well suited to having a mixture of styles. This +example provides a workaround that involves defining a new storage +key with \ics{glsaddstoragekey} that's used to hold the font +declaration (such as \cs{em}). +\begin{verbatim} +\glsaddstoragekey{font}{}{\entryfont} +\end{verbatim} +A new custom acronym style is defined that fetches the font +information from this new key so that it can be applied to the +abbreviation. Some helper commands are also provided to define the +different types of abbreviation: +\begin{verbatim} +\newcommand*{\newitabbr}[1][]{\newacronym[font=\em,#1]} +\newcommand*{\newupabbr}{\newacronym} + +\newitabbr{eg}{e.g.}{exempli gratia} +\newupabbr{bsc}{BSc}{Bachelor of Science} +\end{verbatim} +This makes the \gls{firstuse} of \verb|\gls{eg}| appear as \qt{exempli +gratia (\emph{e.g.})} whereas the \gls{firstuse} of \verb|\gls{bsc}| +is \qt{Bachelor of Science (BSc)}. + +\glsxtrnote +This example document is much simpler with \gls{glossaries-extra}. +First the \cs{usepackage} command needs adjusting: +\begin{alltt} +\cs{usepackage}[\xtrfont{postdot},\xtrfont{stylemods}]\mgroup{\strong{glossaries-extra}} +\end{alltt} +The custom storage key can now be removed and also the custom +acronym style. Now replace the \ics{setacronymstyle} line with: +\begin{alltt} +\ics*{setabbreviationstyle}[acronym]\mgroup{long-short-em} +\end{alltt} +and change the definition of the helper commands: +\begin{alltt} +\cs{newcommand}*\mgroup{\cs{newitabbr}}\mgroup{\ics{newacronym}} +\cs{newcommand}*\mgroup{\cs{newupabbr}}\mgroup{\strong{\ics*{newabbreviation}}} +\end{alltt} +Note that the \verb|font=\em,| part has been removed from the +definition of the first command and the second command uses +\ics*{newabbreviation} instead of \ics{newacronym}. This means that +\cs{newitabbr} will default to +\xtrgloskey{category}\csoptfmt{=acronym} and \cs{newupabbr} will +default to \xtrgloskey{category}\csoptfmt{=abbreviation}. The +default style for the \cat{abbreviation} category is +\abbrstyle{long-short}, which is the required style for this +example. This just means that only the \cat{acronym} category needs +to have the style set (with the above \ics*{setabbreviationstyle} +command). + +Finally, the \ics{acrshort}, \ics{acrlong} and \cs{acrfull} commands +need to be replaced with \ics*{glsxtrshort}, \ics*{glsxtrlong} and +\ics*{glsxtrfull}. + +You may notice that the spacing after \qt{e.g\@.} and \qt{i.e\@.} +isn't correct. This is similar to the \samplefile{-dot-abbr} example +where the space factor needs adjusting. In this case I've inserted +the dots manually (rather than relying on the \attr{insertdots} +attribute). You can either remove the dots and use \attr{insertdots} +with \attr{discardperiod}: +\begin{alltt} +\ics*{glssetcategoryattribute}\mgroup{acronym}\mgroup{insertdots}\mgroup{true} +\ics*{glssetcategoryattribute}\mgroup{acronym}\mgroup{discardperiod}\mgroup{true} + +\cs{newitabbr}\mgroup{eg}\mgroup{\strong{eg}}\mgroup{exempli gratia} +\cs{newitabbr}\mgroup{ie}\mgroup{\strong{ie}}\mgroup{id est} +\end{alltt} +Or you can manually insert the space factor adjustment and only use +the \attr{discardperiod} attribute: +\begin{alltt} +\ics*{glssetcategoryattribute}\mgroup{acronym}\mgroup{discardperiod}\mgroup{true} + +\cs{newitabbr}\mgroup{eg}\mgroup{e.g.\strong{\ics{@}}}\mgroup{exempli gratia} +\cs{newitabbr}\mgroup{ie}\mgroup{i.e.\strong{\ics{@}}}\mgroup{id est} +\end{alltt} + +You don't have to use the \cat{acronym} category. You may prefer a +different label that fits better semantically. For example: +\begin{alltt} +\ics*{setabbreviationstyle}[\strong{latinabbr}]\mgroup{long-short-em} +\cs{newcommand}*\mgroup{\cs{new\strong{latin}abbr}}[1][]\mgroup{\ics*{newabbreviation}[\xtrfont{category}=\strong{latinabbr},\#1]} +\ics*{glssetcategoryattribute}\mgroup{\strong{latinabbr}}\mgroup{insertdots}\mgroup{true} +\ics*{glssetcategoryattribute}\mgroup{\strong{latinabbr}}\mgroup{discardperiod}\mgroup{true} + +\cs{new\strong{latin}abbr}\mgroup{eg}\mgroup{e.g.\strong{\ics{@}}}\mgroup{exempli gratia} +\cs{new\strong{latin}abbr}\mgroup{ie}\mgroup{i.e.\strong{\ics{@}}}\mgroup{id est} +\end{alltt} + +\section{Non-Page Locations} +\label{sec:samplecounter} + +\exitem{Eq} This document illustrates how +to change the location to something other than the page number. In +this case, the \ctrfmt{equation} counter is used since all glossary +entries appear inside an \env{equation} environment. To create +the document do: +\begin{prompt} +pdflatex sampleEq +makeglossaries sampleEq +pdflatex sampleEq +\end{prompt} +The \styfmt{glossaries} package provides some location formats, such +as \ics{hyperrm} and \ics{hyperbf}, that allow the locations in the \gls{numberlist} +to hyperlink to the appropriate place in the document (if +\sty{hyperref} has been used). Since it's not possible to include +the hyperlink name in the indexing information with \gls{makeindex} +and \gls{xindy}, the \styfmt{glossaries} package has to reform the +name from a prefix and the location value. + +Unfortunately it's not always possible to split the link name into a +prefix and location. That happens with the \ctrfmt{equation} +counter in certain classes, such as the \clsfmt{report} class (which +is used in this example). This means that it's necessary to redefine +\ics{theHequation} so that it has a format that fits the requirement: +\begin{verbatim} +\renewcommand*\theHequation{\theHchapter.\arabic{equation}} +\end{verbatim} +If you don't do this, the equation locations in the glossary won't +form valid hyperlinks. + +Each glossary entry represents a mathematical symbol. This means +that with \optsto13 it's necessary to use the \gloskey{sort} key. +For example: +\begin{alltt} +\cs{newglossaryentry}\mgroup{Gamma}\mgroup{name=\cs{ensuremath}\mgroup{\cs{Gamma}(z)}, +description=Gamma function,\strong{sort=Gamma}} +\end{alltt} + +\bibglsnote +If you want to switch to using \gls{bib2gls}, the first change you +need to make is to switch from explicitly loading +\styfmt{glossaries} to loading \gls{glossaries-extra} with the +\pkgopt*{record} package option. If \pkgopt+{only}{record} (or +\pkgopt*{record} without a value) is used, then the above +redefinition of \cs{theHequation} is still required. If +\pkgopt+{nameref}{record} is used instead then the redefinition of +\cs{theHequation} isn't required. You may also want to use the +\pkgopt*{stylemods} and \pkgopt*{postdot} options: +\begin{alltt} +\cs{usepackage}[\strong{\strong{\xtrfont{record=nameref}},\xtrfont{stylemods},\xtrfont{postdot}}, + ucmark,style=long3colheader,counter=equation]\mgroup{\strong{glossaries-extra}} +\end{alltt} +The entries now need to be converted into the \filetype{bib} format required +by \gls{bib2gls}, which can be done with \gls{convertgls2bib}: +\begin{prompt} +convertgls2bib -{}-preamble-only sampleEq.tex entries.bib +\end{prompt} +This will create a file called \nolinkurl{entries.bib} that starts: +\begin{alltt} +\% Encoding: UTF-8 +\atentry{entry}\mgroup{Gamma, + name = \mgroup{\cs{ensuremath}\mgroup{\cs{Gamma}(z)}}, + description = \mgroup{Gamma function} +} +\end{alltt} +You may prefer to change \atentry{entry} to \atentry{symbol}. (This +should be easy to do with your text editor's search and replace +function.) + +Note that the \gloskey{sort} key has been omitted. This is because +it typically shouldn't be used. The difference between using +\atentry{entry} and \atentry{symbol} is that with \atentry{entry} +the sort value will be obtained from the \gloskey{name} but with +\atentry{symbol} the sort value will be obtained from the label. +If you explicitly use the \gloskey{sort} key then you will break +this behaviour. (If you try this example out, notice the difference +in the ordering if you switch between \atentry{entry} and +\atentry{symbol}. See also \bibglsgallery{sorting}.) + +Next replace \cs{makeglossaries} with: +\begin{alltt} +\strong{\ics*{GlsXtrLoadResources}[\resourceopt{src}=entries]} +\end{alltt} +If you have used \pkgopt+{nameref}{record} then you can remove the +redefinition of \cs{theHequation}. Next remove all the lines +defining the glossary entries (since they're now defined in the +\filetype{bib} file). + +Finally, replace \ics{printglossary} with \ics*{printunsrtglossary}: +\begin{alltt} +\strong{\ics*{printunsrtglossary}}[title=\mgroup{Index of Special Functions and +Notations}] +\end{alltt} +The rest of the document remains unchanged (unless you want to use +\ics*{glsxtrfmt} as described in the following example). + +\exitem{EqPg} This is similar to the previous example, but the \glspl{numberlist} are a +mixture of page numbers and equation numbers. This example adds the +glossary to the table of contents, so an extra \LaTeX\ run is +required: +\begin{prompt} +pdflatex sampleEqPg +makeglossaries sampleEqPg +pdflatex sampleEqPg +pdflatex sampleEqPg +\end{prompt} +As with the previous example, entries are defined like this: +\begin{verbatim} +\newglossaryentry{Gamma}{name=\ensuremath{\Gamma(z)}, +description=Gamma function,sort=Gamma} +\end{verbatim} +The \pkgopt[equation]{counter} package option is used to set the +default indexing counter to \ctrfmt{equation}. This means that it +has to be changed for indexing outside of any numbered equation. For +example: +\begin{verbatim} +\glslink[format=hyperbf,counter=page]{Gamma}{gamma function} +\end{verbatim} +I've set the \gloskey[glslink]{format} to \locfmt{hyperbf} to indicate that +this is a primary reference. (Note that I'm using \ics{hyperbf} not +\ics{textbf} in order to include a hyperlink in the location.) + +The \gls{linktext} here is almost identical to the +description. The only difference is that the description starts with +a capital. If it started with a lowercase character instead, I could +simply use \ics{glsdesc} instead of \ics{glslink}. If I change the +entry descriptions so that they all start with a lowercase letter +then I would need to create a custom glossary style that used +\ics{Glossentrydesc} instead of \ics{glossentrydesc}. + +\glsxtrnote +If I switch to using \gls{glossaries-extra} I wouldn't need a new +glossary style. Instead I could just use the \attr{glossdesc} +attribute to perform the case change. Remember that the first change +to make is to replace \styfmt{glossaries} with +\gls{glossaries-extra}: +\begin{alltt} +\cs{usepackage}[style=long3colheader,\strong{\xtrfont{postdot},\xtrfont{stylemods}}, + counter=equation]\mgroup{\strong{glossaries-extra}} +\end{alltt} +The entries are now all defined so that the description starts with +a lowercase letter (except for the descriptions that start with a +proper noun). For example: +\begin{alltt} +\ics{newglossaryentry}\mgroup{Gamma}\mgroup{name=\cs{ensuremath}\mgroup{\cs{Gamma}(z)}, +description=\strong{g}amma function,sort=Gamma} +\end{alltt} +The \attr{glossdesc} attribute needs setting: +\begin{alltt} +\ics*{glssetcategoryattribute}\mgroup{general}\mgroup{glossdesc}\mgroup{firstuc} +\end{alltt} +This means that I can now use \ics{glsdesc} instead of \ics{glslink}. + +It's a bit cumbersome typing \texttt{[format=hyperbf,counter=page]} +for each primary reference, but \gls{glossaries-extra} provides a +convenient way of having a third modifier for commands like \cs{gls} +and \cs{glstext}. This needs to be a single punctuation character +(but not \texttt{*} or \texttt{+} which are already in use). For +example: +\begin{alltt} +\ics*{GlsXtrSetAltModifier}\mgroup{\strong{!}}\mgroup{format=hyperbf,counter=page} +\end{alltt} +Now \texttt{\ics{glsdesc}\strong{!}\mgroup{Gamma}} is equivalent to: +\begin{alltt} +\ics{glsdesc}[format=hyperbf,counter=page]\mgroup{Gamma} +\end{alltt} +So the text at the start of the \qt{Gamma Functions} chapter is now +just: +\begin{alltt} +The \ics{glsdesc}!\mgroup{Gamma} is defined as +\end{alltt} +which is much more compact. Similar changes can be made for the +other instance of \ics{glslink} where the \gls{linktext} is just +the description: +\begin{alltt} +The \ics{glsdesc}!\mgroup{erf} is defined as +\end{alltt} + +There are three other instances of \ics{glslink}, such as: +\begin{alltt} +\ics{glslink}\mgroup{Gamma}\mgroup{\cs{Gamma}(x+1)} +\end{alltt} +If I just use \verb|\gls{Gamma}| then I would get $\Gamma(z)$ as the +\gls{linktext}. For entries like this that represent functions with +variable parameters it would be more convenient (and help with +consistency) if a command was available to easily replace the +parameters. + +With the base \styfmt{glossaries} package, one simple solution that +works for this example is to save just the function symbol in the +\gloskey{symbol} field, for example: +\begin{alltt} +\ics{newglossaryentry}\mgroup{Gamma}\mgroup{name=\cs{ensuremath}\mgroup{\cs{Gamma}(z)}, +\strong{symbol=\mgroup{\cs{ensuremath}\mgroup{\cs{Gamma}}},} +description=gamma function,sort=Gamma} +\end{alltt} +and then use: +\begin{alltt} +\strong{\ics{glssymbol}}\mgroup{Gamma}\strong[(\cs{Gamma}(x+1))\strong] +\end{alltt} +(which includes the function parameter inside the \gls{linktext}) or just: +\begin{alltt} +\ics{glssymbol}\mgroup{Gamma}(\cs{Gamma}(x+1)) +\end{alltt} +(which has the function parameter after the \gls{linktext}). +This is a convenient approach where the extra material can simply +follow the symbol, and it can also be used with \gls{glossaries-extra}. + +The \gls{glossaries-extra} package provides another possibility. It +requires a command that takes a single argument, for example: +\begin{verbatim} +\newcommand{\Gammafunction}[1]{\Gamma(#1)} +\end{verbatim} +The control sequence name (the command name without the leading +backslash) is stored in the field identified by the command \ics*{GlsXtrFmtField} +(this should be the internal field name not the key name, see \tableref{tab:fieldmap}). The +default is \field{useri} which corresponds to the \gloskey{user1} +key. This means that the \texttt{Gamma} entry would need to be +defined with \texttt{user1=Gammafunction}. With this approach, each +function entry would need a separate associated command. + +Another approach is to store the parameterless function in the +\gloskey{symbol} key (as earlier) and have a more generic command that uses this +symbol. This requires the entry label, which can be obtained with +\cs{glslabel} within the \gls{linktext}: +\begin{alltt} +\cs{newcommand}\mgroup{\cs{entryfunc}}[1]\mgroup{\ics{glsentrysymbol}\mgroup{\ics{glslabel}}(\#1)} +\end{alltt} +(Obviously, this command can't be used outside of the \gls{linktext} +or post-link hooks since it uses \ics{glslabel}.) + +So the entry now needs the parameterless function in +\gloskey{symbol} and the control sequence name of this generic +command in \gloskey{user1}. For example: +\begin{alltt} +\ics{newglossaryentry}\mgroup{Gamma}\mgroup{name=\cs{ensuremath}\mgroup{\cs{Gamma}(z)}, +\strong{symbol=\mgroup{\cs{ensuremath}\mgroup{\cs{Gamma}}},user1=entryfunc,} +description=gamma function,sort=Gamma} +\end{alltt} +(This doesn't need to be done for the \texttt{C} and \texttt{G} +entries since they're constants not functions.) + +You may want to consider providing helper commands to make the +functions easier to define. For example: +\begin{verbatim} +\newcommand{\func}[2]{#1(#2)} +\newcommand{\entryfunc}[1]{\func{\glsentrysymbol{\glslabel}}{#1}} +\newcommand{\newfunc}[5][]{% + \newglossaryentry{#2}{name={\ensuremath{\func{#3}{#4}}}, + symbol={#3}, + user1={entryfunc}, + description={#5}, + sort={#2},#1 + }% +} +\end{verbatim} +The entries can now be defined using this custom \cs{newfunc} +command. For example: +\begin{verbatim} +\newfunc{Gamma}{\Gamma}{z}{gamma function} +\newfunc[sort=gamma1]{gamma}{\gamma}{\alpha,x}{lower + incomplete gamma function} +\newfunc[sort=Gamma2]{iGamma}{\Gamma}{\alpha,x}{upper + incomplete gamma function} +\end{verbatim} + +Note that in \cs{newfunc} the \gloskey{symbol} key doesn't have its value +encapsulated with \ics{ensuremath} so \cs{glssymbol} will need to explicitly be +placed in math mode. If you switch to a glossary style that displays +the symbol, you will either need to adjust the definition of +\cs{newfunc} to use \ics{ensuremath} in the \gloskey{symbol} field +or you can add the encapsulation with the \attr{glosssymbolfont} +attribute. + +Now \verb|\glslink{Znu}{Z_\nu}| can simply be replaced with +\texttt{\ics{glssymbol}\mgroup{Znu}} (no parameter is required in +this case). For the other cases, where the parameter is different +from that given in the \gloskey{text} field (which is obtained from +the \gloskey{name}), you can use \ics*{glsxtrfmt}. For example, +\texttt{\cs{glslink}\mgroup{Gamma}\mgroup{\cs{Gamma}(x+1)}} can now be replaced with: +\begin{alltt} +\ics*{glsxtrfmt}\mgroup{Gamma}\mgroup{x+1} +\end{alltt} +This effectively works like \cs{glslink} but omits the post-link hook. +(See the \gls{glossaries-extra} user manual for further details.) + +\begin{important} +Don't use \ics*{glsxtrfmt} within the argument of another \ics*{glsxtrfmt} command +(or inside any other \gls{linktext}). +\end{important} + +Similarly \verb|\glslink{Gamma}{\Gamma(\alpha)}| +can now be replaced with: +\begin{alltt} +\ics*{glsxtrfmt}\mgroup{Gamma}\mgroup{\cs{alpha}} +\end{alltt} +Note that it's still possible to use: +\begin{alltt} +\ics{glssymbol}\mgroup{Gamma}[(\cs{alpha})] +\end{alltt} +You may prefer to define a helper command that makes it easier to +switch between your preferred method. For example: +\begin{verbatim} +\newcommand*{\Fn}[3][]{\glssymbol[#1]{#2}[(#3)]} +\end{verbatim} +or: +\begin{alltt} +\cs{newcommand}*\mgroup{\cs{Fn}}[3][]\mgroup{\ics*{glsxtrfmt}[\#1]\mgroup{\#2}\mgroup{\#3}} +\end{alltt} + +\bibglsnote +If you want to convert this example so that it works with \gls{bib2gls}, first +convert it to use \gls{glossaries-extra} (as described above), and +then follow the instructions from \samplefile{Eq}. The +\gls{convertgls2bib} application recognises \cs{newcommand} so it +will be able to parse the custom \cs{newfunc} commands. + +Note that \gls{bib2gls} allows you to separate the locations in the \gls{numberlist} +into different groups according to the counter used for the +location. This can be done with the \resourceopt{loc-counters} +resource option. It's also possible to identify primary formats +(such as \locfmt{hyperbf} used in this example) using the +\resourceopt{primary-location-formats} option. The primary locations +can then be given a more prominent position in the +\gls{numberlist}. See the \gls{bib2gls} user manual for further +details. + +\exitem{Sec} This document also +illustrates how to change the location to something other than the +page number. In this case, the \texttt{section} counter is used. +This example adds the glossary to the table of contents, so an extra +\LaTeX\ run is required: +\begin{prompt} +pdflatex sampleSec +makeglossaries sampleSec +pdflatex sampleSec +pdflatex sampleSec +\end{prompt} +Note that there are conflicting location formats, which trigger a +warning from \gls{makeindex}: +\begin{verbatim} +## Warning (input = sampleSec.glo, line = 6; output = +sampleSec.gls, line = 9): + -- Conflicting entries: multiple encaps for the same page +under same key. + +## Warning (input = sampleSec.glo, line = 2; output = +sampleSec.gls, line = 10): + -- Conflicting entries: multiple encaps for the same page +under same key. +\end{verbatim} +This is the result of indexing an entry multiple times for the same +location\footnote{\gls{makeindex} assumes that the location is a +page number} with different values of the \gloskey[glslink]{format} key. In this case, +it's caused by three references to the \texttt{ident} entry in section~2.1: +\begin{verbatim} +\gls[format=hyperit]{ident} +\glspl{ident} % default format=glsnumberformat +\gls*[format=hyperbf]{ident} +\end{verbatim} + +If you use the \gls{makeglossaries} Perl script it will detect the warnings in the +\gls{makeindex} transcript file and attempt to fix the conflict by +removing entries from the \filetype{glo} file: +\begin{verbatim} +Multiple encaps detected. Attempting to remedy. +Reading sampleSec.glo... +Writing sampleSec.glo... +Retrying +\end{verbatim} +(Range formats have highest precedence. The default \locfmt{glsnumberformat} +has the lowest precedence.) + +If you use \gls{makeglossaries-lite.lua} or call +\gls{makeindex} directly then the problem won't be fixed and the +glossary will end up with the rather odd \gls{numberlist} for the +identity matrix entry consisting of three references to section 2.1: +the first in the default font, followed by bold (\locfmt{hyperbf}) +and then italic (\locfmt{hyperit}), which results in 2.1, +\textbf{2.1}, \textit{2.1}. If you use \gls{makeglossaries} then +only the bold entry (\textbf{2.1}) will be present. + +If you switch to \gls{xindy}: +\begin{alltt} +\cs{usepackage}[\strong{xindy},style=altlist,toc,counter=section]\mgroup{glossaries} +\end{alltt} +then the conflict will be resolved using the number format attribute +list order of priority. In this case, \locfmt{glsnumberformat} has +the highest priority. This means that only the upright medium weight entry +(2.1) will be present. The simplest way of altering this is to +provide your own custom format. For example: +\begin{alltt} +\cs{newcommand}*\mgroup{\strong{\cs{primary}}}[1]\mgroup{\ics{hyperit}\mgroup{\#1}} +\ics{GlsAddXdyAttribute}\mgroup{\strong{primary}} +\end{alltt} +and change \verb|\gls[format=hyperit]| to \texttt{\cs{gls}[format=\strong{primary}]} etc. +This will give \csoptfmt{\gloskey[glslink]{format}=\locfmt{primary}} the highest priority. +(It's also better practice to provide this kind of semantic command.) + +With \gls{bib2gls}, you can supply rules to deal with location format +conflicts, as illustrated below. + +\bibglsnote +In order to switch to \gls{bib2gls}, first replace +\styfmt{glossaries} with \gls{glossaries-extra}, and add the \pkgopt*{record} +package option. Remember that \gls{glossaries-extra} has a different +set of defaults and you may also want to patch the predefined base styles. +For example: +\begin{alltt} +\cs{usepackage}[style=altlist,\strong{\xtrfont{postdot},\xtrfont{stylemods}},counter=section] +\mgroup{\strong{glossaries-extra}} +\end{alltt} + +The entry definitions now need to be converted into \gls{bib2gls} +format and saved in a \filetype{bib} file (say, \texttt{entries.bib}). You can use +\gls{convertgls2bib}: +\begin{prompt} +convertgls2bib -{}-preamble-only sampleSec.tex entries.bib +\end{prompt} + +Next replace \ics{makeglossaries} with: +\begin{alltt} +\ics*{GlsXtrLoadResources}[src=entries] +\end{alltt} +and remove all the \cs{newglossaryentry} commands. + +Finally, replace \ics{printglossaries} with \ics*{printunsrtglossaries}. +The document build is now: +\begin{prompt} +pdflatex sampleSec +bib2gls sampleSec +pdflatex sampleSec +\end{prompt} +As with the original example, there's still a location format +conflict, which \gls{bib2gls} warns about: +\begin{verbatim} +Warning: Entry location conflict for formats: hyperbf and hyperit +Discarding: {ident}{}{section}{hyperbf}{2.1} +Conflicts with: {ident}{}{section}{hyperit}{2.1} +\end{verbatim} +This means that it has discarded the bold location and kept the +italic one. (As with \gls{makeglossaries}, range formats have the +highest priority and \locfmt{glsnumberformat} has the lowest.) + +It would be better if the conflict could be merged into +a single location that was both bold and italic. To achieve this, +it's first necessary to define a command that produces this effect: +\begin{alltt} +\cs{newcommand}*\mgroup{\ics{hyperbfit}}[1]\mgroup{\cs{textbf}\mgroup{\cs{hyperit}\mgroup{\#1}}} +\end{alltt} +Now \gls{bib2gls} needs to be invoked with the appropriate mapping +with the \bibglslongopt{map-format} or \bibglsopt{m} switch: +\begin{prompt} +bib2gls -m \glsquote{hyperbf:hyperbfit,hyperit:hyperbfit} sampleSec +\end{prompt} +If you are using \app{arara} the directive should be: +\begin{alltt} +\% arara: bib2gls: \mgroup{ mapformats: [ [hyperbf, hyperbfit], +\% arara: -{}-> [hyperit, hyperbfit] ] } +\end{alltt} + +If you try out this example, notice the difference between +\pkgopt+{only}{record} and \pkgopt+{nameref}{record}. If you use the +latter, the locations will now be the section titles rather than the +section numbers. If you use the \optfmt{nameref} setting you can customize the +location by defining the command: +\begin{alltt} +\csmeta*{glsxtr}{counter}{locfmt}\marg{location}\marg{title} +\end{alltt} + +In this case the counter is \ctrfmt{section}, so the command should be +\ics*{glsxtrsectionlocfmt}. It takes two arguments: the first is the +location and the second is the title. For example: +\begin{alltt} +\cs{newcommand}*\mgroup{\ics*{glsxtrsectionlocfmt}}[2]\mgroup{\ics{S}\#1 \#2} +\end{alltt} +(The only command of this type that is defined by default is the one +for the \ctrfmt{equation} counter, \ics*{glsxtrequationlocfmt}.) Make sure +that you have at least version 1.42 of \gls{glossaries-extra}. + +\section{Multiple Glossaries} +\label{sec:samplestype} + +See also \samplefile{Sort} in \sectionref{sec:samplessort}, which +has three glossaries. + +\exitem{Ntn} This document illustrates +how to create an additional glossary type. This example adds the +glossary to the table of contents, so an extra \LaTeX\ run is +required: +\begin{prompt} +pdflatex sampleNtn +makeglossaries sampleNtn +pdflatex sampleNtn +pdflatex sampleNtn +\end{prompt} +Note that if you want to call \gls{makeindex} explicitly instead of +using the \gls{makeglossaries} or \gls{makeglossaries-lite.lua} +scripts then you need to call \gls{makeindex} twice: +\begin{enumerate} +\item Create the main glossary (all on one line): +\begin{prompt} +makeindex -s sampleNtn.ist -t sampleNtn.glg -o sampleNtn.gls sampleNtn.glo +\end{prompt} +\item Create the secondary glossary (all on one line): +\begin{prompt} +makeindex -s sampleNtn.ist -t sampleNtn.nlg -o sampleNtn.not sampleNtn.ntn +\end{prompt} +\end{enumerate} +This document creates a new glossary using: +\begin{alltt} +\ics{newglossary}[nlg]\mgroup{notation}\mgroup{not}\mgroup{ntn}\mgroup{Notation} +\end{alltt} +This defines a glossary that can be identified with the label +\texttt{notation} with the default title \qt{Notation}. The other +arguments are the file extensions required with \optsand23. For those +two options, the \styfmt{glossaries} package needs to know the input +and output files required by \gls{makeindex} or \gls{xindy}. + +(The optional argument is the file extension of the indexing transcript +file, which \styfmt{glossaries} doesn't need to know about, but it +writes the information to the \filetype{aux} file for the benefit of +\gls{makeglossaries} and \gls{makeglossaries-lite.lua}.) + +If you switch to a different indexing option then these file extensions +aren't required, in which case it's simpler to use the starred form: +\begin{alltt} +\ics{newglossary*}\mgroup{notation}\mgroup{Notation} +\end{alltt} + +This example uses a label prefixing system\footnote{If you use +\sty{babel} with a language that makes the colon character +\texttt{:} active you will need to change the prefix.}\ to differentiate +between the different types of entries. For example, the term +\qt{set} is defined as: +\begin{verbatim} +\newglossaryentry{gls:set}{name=set, +description={A collection of distinct objects}} +\end{verbatim} +and the set notation is defined as: +\begin{verbatim} +\newglossaryentry{not:set}{type=notation, +name={\ensuremath{\mathcal{S}}}, +description={A \gls{gls:set}},sort={S}} +\end{verbatim} +Notice that the latter description contains \cs{gls}. This means +you shouldn't use \ics{glsdesc} with this entry otherwise you will +end up with nested links. + +\glsxtrnote +The \gls{glossaries-extra} package provides a command for use in +within field values to prevent nested \gls{linktext}: +\begin{alltt} +\ics*{glsxtrp}\marg{field}\marg{label} +\end{alltt} +There are convenient shortcuts for common fields: +\texttt{\ics*{glsps}\marg{label}} (for the \gloskey{short} field) and +\texttt{\ics*{glspt}\marg{label}} (for the \gloskey{text} +field). So the set notation definition can be modified: +\begin{alltt} +\cs{newglossaryentry}\mgroup{not:set}\mgroup{type=notation, +name=\mgroup{\cs{ensuremath}\mgroup{\cs{mathcal}\mgroup{S}}}, +description=\mgroup{A \strong{\ics*{glspt}\mgroup{gls:set}}},sort={S}} +\end{alltt} +This will stop the inner reference from causing interference if you use \ics{glsdesc}. +It will also suppress indexing within the glossary but will have a +hyperlink (if \styfmt{hyperref} is used). + +The \gls{glossaries-extra} package provides a way of defining +commands like \cs{gls} that automatically insert a prefix. For +example: +\begin{alltt} +\ics*{glsxtrnewgls}\mgroup{not:}\mgroup{\cs{sym}} +\ics*{glsxtrnewglslike}\mgroup{gls:}\mgroup{\cs{term}}\mgroup{\cs{termpl}}\mgroup{\cs{Term}}\mgroup{\cs{Termpl}} +\end{alltt} +(there's no point providing commands for plural or case-changing with +symbols). Now \verb|\gls{not:set}| can be replaced with \verb|\sym{set}| and +\verb|\gls{gls:set}| can be replaced with \verb|\term{set}|. + +\bibglsnote +These two commands are primarily provided for the benefit of \gls{bib2gls} as +the information is written to the \filetype{aux} file. This allows +\gls{bib2gls} to recognise the custom commands if they have been +used in the \filetype{bib} files. When combined with +\resourceopt{label-prefix} and \resourceopt{ext-prefixes} (see +below) this makes it much simpler to change the prefixes if +necessary. + +If you want to convert this document to use \gls{bib2gls}, remember +that you need the \pkgopt*{record} or \pkgopt+{nameref}{record} +option. For example: +\begin{alltt} +\cs{usepackage}[\strong{\xtrfont{record},}\xtrfont{postdot},\xtrfont{stylemods}]\mgroup{glossaries-extra} +\end{alltt} +As with earlier examples, \gls{convertgls2bib} can be used to +convert the entry definitions into the required \filetype{bib} format. +You may prefer to split the entries into separate files according to +type.\footnote{Requires at least \gls{bib2gls} v2.0.} This is useful +if you want to reuse a large database of +entries across multiple documents as it doesn't lock you into using +a specific glossary. For example: +\begin{prompt} +convertgls2bib -{}-split-on-type -{}-preamble-only sampleNtn.tex entries.bib +\end{prompt} +This will create a file called \nolinkurl{entries.bib} that contains +the entries that didn't have a \gloskey{type} assigned in the original +file, such as: +\begin{alltt} +\atentry{entry}\mgroup{gls:set, + name = \mgroup{set}, + description = \mgroup{A collection of distinct objects} +} +\end{alltt} +It will also create a file called \nolinkurl{notation.bib} that +contains the entries that had the \gloskey{type} set to +\texttt{notation} in the original file, such as: +\begin{alltt} +\atentry{entry}\mgroup{not:set, + name = \mgroup{\cs{ensuremath}\mgroup{\cs{mathcal}\mgroup{S}}}, + description = \mgroup{A \ics*{glspt}\mgroup{gls:set}} +} +\end{alltt} +Note that the \gloskey{type} field has been removed. The above entry +in the \nolinkurl{notation.bib} file references a term in the +\nolinkurl{entries.bib} file. It's possible to strip all the +prefixes from the \filetype{bib} files and get \gls{bib2gls} to +automatically insert them. In which case, this cross-reference needs +adjusting to indicate that it's referring to an entry in another +file. This can be done with one of the special +\xtrfont{\texttt{ext\meta{n}.}}\ prefixes: +\begin{alltt} +\atentry{entry}\mgroup{\strong{set}, + name = \mgroup{\cs{ensuremath}\mgroup{\cs{mathcal}\mgroup{S}}}, + description = \mgroup{A \ics*{glspt}\mgroup{\strong{\xtrfont{ext1.}}set}} +} +\end{alltt} +The corresponding term in the \nolinkurl{entries.bib} file is now: +\begin{alltt} +\atentry{entry}\mgroup{\strong{set}, + name = \mgroup{set}, + description = \mgroup{A collection of distinct objects} +} +\end{alltt} + +Now you can replace \cs{makeglossaries} with: +\begin{alltt} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=\mgroup{entries},\strong{\xtrfont{label-prefix}=\mgroup{gls:}}] +\ics*{GlsXtrLoadResources}[\resourceopt{src}=\mgroup{notation},\resourceopt{type}=notation, + \strong{\xtrfont{label-prefix}=\mgroup{not:},\xtrfont{ext-prefixes}=\mgroup{gls:}}] +\end{alltt} +Remove all the \cs{newglossaryentry} definitions and replace \cs{printglossaries} with +\ics*{printunsrtglossaries}. + +Regardless of how many resource sets the document contains, only one +\gls{bib2gls} call is required: +\begin{prompt} +pdflatex sampleNtn +bib2gls sampleNtn +pdflatex sampleNtn +\end{prompt} + +You may notice that the ordering in the notations list has changed +from the original. This is because the \gloskey{sort} field was +automatically removed by \gls{convertgls2bib}, so the entries are +now sorted according to the \gloskey{name} field (since they are +defined with \atentry{entry}). You can use your text editor's search +and replace function to replace all instances of \atentry{entry} +with \atentry{symbol} in the \nolinkurl{notations.bib} file so that, +for example, the \texttt{set} definition becomes: +\begin{alltt} +\strong{\atentry{symbol}}\mgroup{set, + name = \mgroup{\cs{ensuremath}\mgroup{\cs{mathcal}\mgroup{S}}}, + description = \mgroup{A \ics*{glspt}\mgroup{\xtrfont{ext1.}set}} +} +\end{alltt} +Now these \atentry{symbol} entries will be sorted according to their +label. (The original label in the \filetype{bib} file, not the +prefixed label.) This will put them in the same order as the original +document. (See the \qt{Examples} chapter of +the \gls{bib2gls} user manual for examples of varying the sorting +and also \bibglsgallery{sorting}.) + +\exitem{-dual} This document +illustrates how to define an entry that both appears in the list of +acronyms and in the main glossary. To create the document do: +\begin{prompt} +pdflatex sample-dual +makeglossaries sample-dual +pdflatex sample-dual +\end{prompt} +This defines a custom command \ics{newdualentry} that defines two entries at once (a +normal entry and an abbreviation). It uses \ics{glsadd} to ensure +that if one is used then the other is automatically indexed: +\begin{verbatim} +\newcommand*{\newdualentry}[5][]{% + % main entry: + \newglossaryentry{main-#2}{name={#4},% + text={#3\glsadd{#2}},% + description={#5},% + #1% additional options for main entry + }% + % abbreviation: + \newacronym{#2}{#3\glsadd{main-#2}}{#4}% +} +\end{verbatim} +A sample dual entry is defined with this command: +\begin{verbatim} +\newdualentry{svm}% label + {SVM}% abbreviation + {support vector machine}% long form + {Statistical pattern recognition technique}% description +\end{verbatim} +This defines an acronym with the label \texttt{svm} that can be +referenced with \verb|\gls{svm}| but it also defines an entry with +the label \texttt{main-svm}. This isn't used in the document with +\cs{gls} but it's automatically added from the +\texttt{\cs{glsadd}\mgroup{main-svm}} in the short form of +\texttt{svm}. + +For this trivial document, this kind of dual entry is redundant and +unnecessarily leads the reader down a trail, first to the list of +acronyms and from there the reader then has to go to the main +glossary to look up the description. It's better to simply include +the description in the list of acronyms. + +\bibglsnote +If you want to switch over to \gls{bib2gls}, first change to +\gls{glossaries-extra}: +\begin{alltt} +\cs{usepackage}[\strong{\xtrfont{record}},\xtrfont{postdot},\xtrfont{stylemods},acronym]\mgroup{\strong{glossaries-extra}} +\end{alltt} +Next, the definition needs to be converted to the \filetype{bib} +format required by \gls{bib2gls}. If you do: +\begin{prompt} +convertgls2bib -{}-preamble-only sample-dual.tex entries.bib +\end{prompt} +then \gls{convertgls2bib} will report the following: +\begin{verbatim} +Overriding default definition of \newdualentry with custom +definition. (Change \newcommand to \providecommand if you want +\newdualentry[options]{label}{short}{long}{description} +converted to @dualabbreviationentry.) +\end{verbatim} +This is because \gls{convertgls2bib} has its own internal definition +of \cs{newdualentry}, but if it encounters a new definition that +will override its default. If you want to retain +\gls{convertgls2bib}['s] definition (recommended) then just replace +\cs{newcommand} with \cs{providecommand} in the document source and +rerun \gls{convertgls2bib}. + +With \cs{providecommand}, the new \nolinkurl{entries.bib} file +created by \gls{convertgls2bib} contains: +\begin{alltt} +\atentry{dualabbreviationentry}\mgroup{svm, + short = \mgroup{SVM}, + description = \mgroup{Statistical pattern recognition technique}, + long = \mgroup{support vector machine} +} +\end{alltt} +If \cs{newcommand} is retained, it will instead contain: +\begin{alltt} +\atentry{entry}\mgroup{main-svm, + name = \mgroup{support vector machine}, + description = \mgroup{Statistical pattern recognition technique}, + text = \mgroup{SVM\cs{glsadd}\mgroup{svm}} +} + +\atentry{acronym}\mgroup{svm, + short = \mgroup{SVM\cs{glsadd}\mgroup{main-svm}}, + long = \mgroup{support vector machine} +} +\end{alltt} +In the first case, \gls{bib2gls} creates two linked entries using +its primary-dual mechanism. In the second case, \gls{bib2gls} +creates two entries that simply reference each other. + +Assuming that your \nolinkurl{entries.bib} file just contains +\atentry{dualabbreviationentry}, +now replace \cs{makeglossaries} with: +\begin{alltt} +\cs{GlsXtrLoadResources}[\resourceopt{src}=entries,\% entries.bib + \resourceopt{type}=acronym,\resourceopt{dual-type}=main,\resourceopt{dual-prefix}=\mgroup{main-}] +\end{alltt} + +Then remove the definition of \cs{newdualentry} and the entry +definition. Finally, replace \cs{printglossaries} with +\ics*{printunsrtglossaries}. +The document build is: +\begin{prompt} +pdflatex sample-dual +bib2gls sample-dual +pdflatex sample-dual +\end{prompt} + +If, instead, your \nolinkurl{entries.bib} file contains separate +\atentry{entry} and \atentry{acronym}, then you need: +\begin{alltt} +\ics*{setabbreviationstyle}[acronym]\mgroup{long-short} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=entries] +\end{alltt} +If you need \glspl{numberlist}, the document build is now +\begin{prompt} +pdflatex sample-dual +bib2gls sample-dual +pdflatex sample-dual +bib2gls sample-dual +pdflatex sample-dual +\end{prompt} +and this time \gls{bib2gls} complains about the use of \ics{glsadd} +within the \gloskey{short} and \gloskey{text} fields as this can be +problematic. (The extra \gls{bib2gls} and \LaTeX\ calls are +to ensure the \gls{numberlist} is up to date for the +\texttt{main-svm} entry, which can only be indexed with \cs{glsadd} +after \texttt{svm} has been defined.) + +Dual entries make much more sense when one entry is for a glossary +with the description displayed but no \gls{numberlist}, and the +other is for the index without the description but with a +\gls{numberlist}. This can be created with by replacing +\atentry{dualabbreviationentry} with \atentry{dualindexabbreviation}: +\begin{alltt} +\atentry{dualindexabbreviation}\mgroup{svm, + description = \mgroup{Statistical pattern recognition technique}, + short = \mgroup{SVM}, + long = \mgroup{support vector machine} +} +\end{alltt} +This can be mixed with \atentry{index} terms for example: +\begin{alltt} +\atentry{index}\mgroup{machlearn, + name=\mgroup{machine learning} +} +\end{alltt} +The document needs modifying: +\begin{alltt} +\cs{documentclass}\mgroup{article} + +\ics{usepackage}[\xtrfont{record},\xtrfont{postdot}, + nostyles,\xtrfont{stylemods}=\mgroup{\xtrfont{bookindex},list},\% only want bookindex and list styles + acronym]\mgroup{glossaries-extra} + +\ics*{setabbreviationstyle}\mgroup{long-short-desc} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=entries,\% entries.bib + \resourceopt{dual-type}=acronym, + \xtrfont{label-prefix}=\mgroup{\strong{idx.}},\resourceopt{dual-prefix}=\mgroup{}, + \resourceopt{combine-dual-locations}=\mgroup{primary}] + +\ics*{glsxtrnewglslike}\mgroup{\strong{idx.}}\mgroup{\strong{\cs{idx}}}\mgroup{\cs{idxpl}}\mgroup{\cs{Idx}}\mgroup{\cs{Idxpl}} + +\cs{begin}\mgroup{document} +\cs{gls}\mgroup{svm} and \strong{\cs{idx}}\mgroup{machlearn}. + +\ics*{printunsrtglossary}[type=\acronymtype,style=altlist] +\ics*{printunsrtglossary}[style=bookindex,title=\mgroup{Index}] +\cs{end}\mgroup{document} +\end{alltt} +See the \gls{bib2gls} manual for further details. + +\exitem{-langdict} This document +illustrates how to use the glossaries package to create English +to French and French to English dictionaries. To create the document +do: +\begin{prompt} +pdflatex sample-langdict +makeglossaries sample-langdict +pdflatex sample-langdict +\end{prompt} +This example uses the \pkgopt{nomain} package option to prevent the +creation of the \texttt{main} glossary. This means that the document +must provide its own glossaries: +\begin{verbatim} +\newglossary[glg]{english}{gls}{glo}{English to French} +\newglossary[flg]{french}{flx}{flo}{French to English} +\end{verbatim} +This means that if you want to call \gls{makeindex} explicitly +you need to take these new extensions into account: +\begin{prompt} +makeindex -s sample-langdict.ist -t sample-langdict.glg -o sample-langdict.gls sample-langdict.glo +makeindex -s sample-langdict.ist -t sample-langdict.flg -o sample-langdict.flx sample-langdict.flo +\end{prompt} +As with the previous example, this document provides a custom +command that defines two related entries: +\begin{verbatim} +\newcommand*{\newword}[4]{% + \newglossaryentry{en-#1}{type=english,name={#2},description={#3 #4}}% + \newglossaryentry{fr-#1}{type=french,name={#3 #4},text={#4},sort={#4}, + description={#2}}% +} +\end{verbatim} +This has the syntax: +\begin{alltt} +\cs{newword}\marg{label}\marg{english}\marg{determiner}\marg{french} +\end{alltt} +(Note that this trivial example doesn't take plurals into account.) +This custom command will define two terms with labels \texttt{en-\meta{label}} (for +the English term) and \texttt{fr-\meta{label}} (for the French term). +So +\begin{verbatim} +\newword{cat}{cat}{le}{chat} +\end{verbatim} +is equivalent to: +\begin{verbatim} +\newglossaryentry{en-cat}{type=english,name={cat},description={le chat}} +\newglossaryentry{fr-cat}{type=french,name={le chat},sort={chat}, + description={cat}} +\end{verbatim} + +Unlike the previous example (\samplefile{-dual}), there's no link +between these two entries. If the document only uses +\verb|\gls{en-cat}|, then the \texttt{en-cat} entry will appear in the +\texttt{english} glossary but the \texttt{fr-cat} entry won't +appear in the \texttt{french} one. + +\bibglsnote +If you want to switch to \gls{bib2gls} then you first need to +convert the document so that it uses \gls{glossaries-extra}, but +include the \pkgopt*{prefix} option to ensure that +\sty{glossaries-prefix} is also loaded: +\begin{alltt} +\cs{usepackage}[\strong{\xtrfont{record},\xtrfont{prefix}},\xtrfont{postdot},\xtrfont{stylemods},nomain]\mgroup{\strong{glossaries-extra}} +\end{alltt} +You don't need to worry about file extensions now, so it's simpler +to use the starred form of \cs{newglossary}: +\begin{alltt} +\cs{newglossary}\strong{*}\mgroup{english}\mgroup{English to French} +\cs{newglossary}\strong{*}\mgroup{french}\mgroup{French to English} +\end{alltt} +Next the entries need to be converted to the \filetype{bib} format +required by \gls{bib2gls}: +\begin{prompt} +convertgls2bib -{}-only-preamble sample-langdict.tex entries.bib +\end{prompt} +This creates the file \nolinkurl{entries.bib} that contains entries +defined like: +\begin{alltt} +\atentry{entry}\mgroup{en-cat, + name = \mgroup{cat}, + description = \mgroup{le chat}, + type = \mgroup{english} +} + +\atentry{entry}\mgroup{fr-cat, + name = \mgroup{le chat}, + description = \mgroup{cat}, + text = \mgroup{chat}, + type = \mgroup{french} +} +\end{alltt} +(Note that the \gloskey{sort} field has been omitted.) + +This would be more flexible, and much briefer, if these entries were +defined using \gls{bib2gls}['s] dual entry system combined with the +\sty{glossaries-prefix} package: +\begin{alltt} +\atentry{dualentry}\mgroup{cat, + name = \mgroup{chat}, + description = \mgroup{cat}, + \gloskey{prefix} = \mgroup{le}, + \gloskey{prefixplural} = \mgroup{les} +} +\end{alltt} +Similarly for the \qt{chair} entry: +\begin{alltt} +\atentry{dualentry}\mgroup{chair, + name = \mgroup{chaise}, + description = \mgroup{chair}, + \gloskey{prefix} = \mgroup{la}, + \gloskey{prefixplural} = \mgroup{les} +} +\end{alltt} + +With \atentry{dualentry}, the English and French terms are now +automatically linked from \gls{bib2gls}['s] point of view. If only one +is referenced in the document, the other will also be added by default. + +Now that the determiner has been moved out of the description, it +won't show in the glossary. However, it's possible to include it by +providing a command to encapsulate the description (which can also +apply the language change as well). + +\begin{alltt} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=entries,\% entries.bib + \xtrfont{append-prefix-field}=\mgroup{space}, + \resourceopt{category}=\mgroup{same as type},\resourceopt{dual-category}=\mgroup{same as type}, + \xtrfont{label-prefix}=\mgroup{en-},\resourceopt{dual-prefix}=\mgroup{fr-}, + \resourceopt{type}=english,\resourceopt{dual-type}=french, + \resourceopt{sort}=en,\resourceopt{dual-sort}=fr] + +\cs{newcommand}\mgroup{\cs{FrEncap}}[1]\mgroup{\% + \ics{foreignlanguage}\mgroup{french}\mgroup{\ics{glsentryprefix}\mgroup{\ics{glscurrententrylabel}}\#1}} +\cs{newcommand}\mgroup{\cs{EnEncap}}[1]\mgroup{\ics{foreignlanguage}\mgroup{english}\mgroup{\#1}} + +\ics*{glssetcategoryattribute}\mgroup{english}\mgroup{glossnamefont}\mgroup{EnEncap} +\ics*{glssetcategoryattribute}\mgroup{english}\mgroup{glossdescfont}\mgroup{FrEncap} +\ics*{glssetcategoryattribute}\mgroup{french}\mgroup{glossnamefont}\mgroup{FrEncap} +\ics*{glssetcategoryattribute}\mgroup{french}\mgroup{glossdescfont}\mgroup{EnEncap} +\end{alltt} + +Remember to remove \cs{makeglossaries}, the definition of \cs{newword} and +the entry definitions from the document preamble, and +replace \cs{printglossary} with: +\begin{alltt} +\ics*{printunsrtglossary} +\end{alltt} + +Other refinements that you might like to make include using +\ics*{glsxtrnewglslike} so you don't have to worry about the label +prefix (\qt{en-} and \qt{fr-}). + +\exitem{-index} This document uses +the \styfmt{glossaries} package to create both a glossary and an +index. This requires two \gls{makeglossaries} (or +\gls{makeglossaries-lite.lua}) calls to ensure the +document is up to date: +\begin{prompt} +pdflatex sample-index +makeglossaries sample-index +pdflatex sample-index +makeglossaries sample-index +pdflatex sample-index +\end{prompt} + +\section{Sorting} +\label{sec:samplessort} + +\exitem{People} This document illustrates how you can hook into the +standard sort mechanism to adjust the way the sort key is set. This +requires an additional run to ensure the table of contents is +up-to-date: +\begin{prompt} +pdflatex samplePeople +makeglossaries samplePeople +pdflatex samplePeople +pdflatex samplePeople +\end{prompt} +This provides two commands for typesetting a name: +\begin{verbatim} +\newcommand{\sortname}[2]{#2, #1} +\newcommand{\textname}[2]{#1 #2} +\end{verbatim} +where the first argument contains the forenames and the second is the +surname. The first command is the one required for sorting the name +and the second is the one required for displaying the name in the +document. A synonym is then defined: +\begin{verbatim} +\let\name\textname +\end{verbatim} +This command defaults to the display name command (\cs{textname}) +but is temporarily redefined to the sort name command (\cs{sortname}) +within the \gloskey{sort} field assignment hook: +\begin{alltt} +\cs{renewcommand}\mgroup{\ics{glsprestandardsort}}[3]\mgroup{\% + \strong{\cs{let}\cs{name}\cs{sortname}} + \cs{edef}\#1\mgroup{\cs{expandafter}\cs{expandonce}\cs{expandafter}\mgroup{#1}}\% + \strong{\cs{let}\cs{name}\cs{textname}} + \ics{glsdosanitizesort} +} +\end{alltt} +The people are defined using the custom \cs{name} command: +\begin{alltt} +\cs{newglossaryentry}\mgroup{joebloggs}\mgroup{name=\mgroup{\strong{\cs{name}}\mgroup{Joe}\mgroup{Bloggs}}, + description=\mgroup{\cs{nopostdesc}}} +\end{alltt} +Since \cs{name} is temporarily changed while the \gloskey{sort} key +is being assigned, the sort value for this entry ends up as +\qt{Bloggs, Joe}, but the name appears in the document as \qt{Joe Bloggs}. + +\bibglsnote +If you want to use \gls{bib2gls}, you first need to convert the +document to use \gls{glossaries-extra} but make sure you include the +\pkgopt*{record} option: +\begin{alltt} +\cs{usepackage}[\strong{\xtrfont{record}},\xtrfont{stylemods},style=listgroup]\mgroup{\strong{glossaries-extra}} +\end{alltt} +Next it's necessary to convert the entry definitions to the +\filetype{bib} format required by \gls{bib2gls}. You can simply do: +\begin{prompt} +convertgls2bib -{}-preamble-only samplePeople people.bib +\end{prompt} +which will create a file called \nolinkurl{people.bib} that contains +definitions like: +\begin{alltt} +\atentry{entry}\mgroup{joebloggs, + name = \mgroup{\cs{name}\mgroup{Joe}\mgroup{Bloggs}}, + description = \mgroup{\ics{nopostdesc}} +} +\end{alltt} +However, you may prefer to use the \texttt{-{}-index-conversion} +(\texttt{-i}) switch: +\begin{prompt} +convertgls2bib -i -{}-preamble-only samplePeople people.bib +\end{prompt} +This will discard the \gloskey{description} field and use +\atentry{index} instead of \atentry{entry} if the +\gloskey{description} is either empty or simply set to \ics{nopostdesc} or +\ics*{glsxtrnopostpunc}. The \nolinkurl{people.bib} file now +contains definitions like: +\begin{alltt} +\atentry{index}\mgroup{joebloggs, + name = \mgroup{\cs{name}\mgroup{Joe}\mgroup{Bloggs}} +} +\end{alltt} +Regardless of which approach you used to create the \filetype{bib} +file, you now need to edit it to provide a definition of the custom +\cs{name} command for \gls{bib2gls}['s] use: +\begin{alltt} +\atentry{preamble}\mgroup{"\strong{\ics{providecommand}}\mgroup{\cs{name}}[2]\mgroup{\#2, \#1}"} +\end{alltt} +Note the use of \cs{providecommand} instead of \cs{newcommand}. + +In the document (\nolinkurl{samplePeople.tex}) you now need to +delete \cs{makeglossaries}, the definitions of \cs{sortname}, +\cs{textname}, \cs{name}, \cs{glsprestandardsort}, and all the entry +definitions. Then add the following to the document preamble: +\begin{alltt} +\cs{newcommand}\mgroup{\cs{name}}[2]\mgroup{\#1 \#2} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=people] +\end{alltt} +Next, use your text editor's search and replace function to +subsitute all instances of \cs{glsentrytext} in the chapter +headings with \ics*{glsfmttext}. For example: +\begin{alltt} +\ics{chapter}\mgroup{\strong{\ics*{glsfmttext}}\mgroup{joebloggs}} +\end{alltt} +Finally, replace \cs{printunsrtglossaries} with: +\begin{alltt} +\ics*{printunsrtglossaries} +\end{alltt} +The document build is now: +\begin{prompt} +pdflatex samplePeople +bib2gls samplePeople +pdflatex samplePeople +pdflatex samplePeople +\end{prompt} +The third \LaTeX\ call is required to ensure that the PDF bookmarks +are up to date, as the entries aren't defined until after the +\gls{bib2gls} run (which is why you have to use \ics*{glsfmttext} +instead of \cs{glsentrytext}). + +This again leads to a list sorted by surname. The reason this works +is because \gls{bib2gls} only sees the definition of \cs{name} +provided in \atentry{preamble}, but the document uses the definition +of \cs{name} provided before \cs{GlsXtrLoadResources}. The use of +\ics{providecommand} in \atentry{preamble} prevents \cs{name} from +being redefined within the document. + +See also the \qt{Examples} chapter of the \gls{bib2gls} user manual, +which provides another \qt{people} example. + +\exitem{Sort} This is another document that illustrates how to hook +into the standard sort mechanism. An additional run is required to +ensure the table of contents is up-to-date: +\begin{prompt} +pdflatex sampleSort +makeglossaries sampleSort +pdflatex sampleSort +pdflatex sampleSort +\end{prompt} +This document has three glossaries (\texttt{main}, \texttt{acronym} +and a custom \texttt{notation}), so if you want to use +\gls{makeindex} explicitly you will need to have three +\gls{makeindex} calls with the appropriate file extensions: +\begin{prompt} +pdflatex sampleSort +makeindex -s sampleSort.ist -t sampleSort.alg -o sampleSort.acr sampleSort.acn +makeindex -s sampleSort.ist -t sampleSort.glg -o sampleSort.gls sampleSort.glo +makeindex -s sampleSort.ist -t sampleSort.nlg -o sampleSort.not sampleSort.ntn +pdflatex sampleSort +pdflatex sampleSort +\end{prompt} +It's much simpler to just use \gls{makeglossaries} or \gls{makeglossaries-lite.lua}. + +In this example, the sort hook is adjusted to ensure the list of +notation is sorted according to the order of definition. A new +counter is defined to keep track of the entry number: +\begin{verbatim} +\newcounter{sortcount} +\end{verbatim} +The sort hook is then redefined to increment this counter and assign +the sort key to that numerical value, but only for the +\texttt{notation} glossary. The other two glossaries have their sort +keys assigned as normal: +\begin{verbatim} +\renewcommand{\glsprestandardsort}[3]{% + \ifdefstring{#2}{notation}% + {% + \stepcounter{sortcount}% + \edef#1{\glssortnumberfmt{\arabic{sortcount}}}% + }% + {% + \glsdosanitizesort + }% +} +\end{verbatim} +This means that \gls{makeindex} will sort the notation in numerical order. + +\glsxtrnote +If you want to convert this document to use \gls{glossaries-extra}, +a much simpler approach is available with its hybrid method. First +change the package loading line to: +\begin{alltt} +\cs{usepackage}[\xtrfont{postdot},\xtrfont{stylemods},acronym]\mgroup{\strong{glossaries-extra}} +\end{alltt} +Either remove \cs{setacronymstyle} and replace all instances of +\cs{newacronym} with \ics*{newabbreviation} or replace: +\begin{verbatim} +\setacronymstyle{long-short} +\end{verbatim} +with: +\begin{alltt} +\ics*{setabbreviationstyle}[acronym]\mgroup{long-short} +\end{alltt} + +The custom counter and redefinition of \cs{glsprestandardsort} can now +be removed. The file extensions for the custom \texttt{notation} +glossary are no longer relevant so the glossary definition can be +changed to: +\begin{alltt} +\cs{newglossary\strong{*}}\mgroup{notation}\mgroup{Notation} +\end{alltt} +The \ics{makeglossaries} command now needs to be adjusted to +indicate which glossaries need to be processed by \gls{makeindex}: +\begin{alltt} +\cs{makeglossaries}\strong{[main,acronym]} +\end{alltt} +Finally, \ics{printglossaries} needs to be replaced with: +\begin{alltt} +\cs{printglossary} +\cs{printacronyms} +\cs{print\strong{noidx}glossary}[type=notation\strong{,sort=def}] +\end{alltt} +Note that the \texttt{notation} glossary, which hasn't been listed in the optional +argument of \cs{makeglossaries}, must be displayed with \ics{printnoidxglossary}. + +This means that \gls{makeindex} only needs to process the +\texttt{main} and \texttt{acronym} glossaries. No actual sorting is +performed for the \texttt{notation} glossary because, when used with +\printnoidxglosskey[def]{sort}, \cs{printnoidxglossary} simply +iterates over the list of entries that have been indexed. + +The document build doesn't need the third \LaTeX\ call now (since +none of the glossaries extend beyond a page break): +\begin{prompt} +pdflatex sampleSort +makeglossaries sampleSort +pdflatex sampleSort +\end{prompt} +This time \gls{makeglossaries} will include the message: +\begin{verbatim} +only processing subset 'main,acronym' +\end{verbatim} +This means that although \gls{makeglossaries} has noticed the \texttt{notation} glossary, +it will be skipped. + +If you are explicitly calling \gls{makeindex} then you need to drop the call +for the \texttt{notation} glossary: +\begin{prompt} +pdflatex sampleSort +makeindex -s sampleSort.ist -t sampleSort.alg -o sampleSort.acr sampleSort.acn +makeindex -s sampleSort.ist -t sampleSort.glg -o sampleSort.gls sampleSort.glo +pdflatex sampleSort +\end{prompt} + +\bibglsnote +If you prefer to use \gls{bib2gls}, the package loading line needs +to be changed to: +\begin{alltt} +\cs{usepackage}[\strong{\xtrfont{record}},\xtrfont{postdot},\xtrfont{stylemods},acronym]\mgroup{\strong{glossaries-extra}} +\end{alltt} +Next the entry definitions need to be convert to the \filetype{bib} +format required by \gls{bib2gls}. + +For this example, it's simpler to split the entries into different files according +to the glossary type. This can be done with the +\texttt{-{}-split-on-type} or \texttt{-t} switch: +\begin{prompt} +convertgls2bib -t -{}-preamble-only sampleSort.tex entries.bib +\end{prompt} +This will create three files: +\begin{description} +\item[\nolinkurl{entries.bib}] which contains the entries that were +defined with \ics{newglossaryentry}. For example: +\begin{alltt} +\atentry{entry}\mgroup{gls:set, + name = {set}, + description = {A collection of distinct objects} +} +\end{alltt} + +\item[\nolinkurl{abbreviations.bib}] which contains the entries that +were defined with \ics{newacronym}. For example: +\begin{alltt} +\atentry{acronym}\mgroup{zfc, + short = \mgroup{ZFC}, + long = \mgroup{Zermelo-Fraenkel set theory} +} +\end{alltt} +If you changed \ics{newacronym} to \ics*{newabbreviation} then +\atentry{abbreviation} will be used instead: +\begin{alltt} +\atentry{abbreviation}\mgroup{zfc, + short = \mgroup{ZFC}, + long = \mgroup{Zermelo-Fraenkel set theory} +} +\end{alltt} + +\item[\nolinkurl{notation.bib}] which contains the entries that were +defined with \texttt{\gloskey{type}=notation}. For example: +\begin{alltt} +\atentry{entry}\mgroup{not:set, + name = \mgroup{\$\cs{mathcal}\mgroup{S}\$}, + description = \mgroup{A set}, + text = \mgroup{\cs{mathcal}\mgroup{S}} +} +\end{alltt} +You may prefer to replace \atentry{entry} with \atentry{symbol} +in this file. +\end{description} +\emph{After} the definition of the \texttt{notation} glossary +(\cs{newglossary}), add: +\begin{alltt} +\% abbreviation style must be set first: +\ics*{setabbreviationstyle}[acronym]\mgroup{long-short} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=\mgroup{entries,abbreviations}] +\ics*{GlsXtrLoadResources}[\resourceopt{src}=\mgroup{notation},\% notation.bib + \strong{\xtrfont{type}=notation},\resourceopt{sort}=\strong{unsrt}] +\end{alltt} +Delete the remainder of the preamble (\cs{makeglossaries} and entry +definitions). + +Finally, replace the lines that display the glossaries with: +\begin{alltt} +\ics*{printunsrtglossaries} +\end{alltt} +The build process is now: +\begin{prompt} +pdflatex sampleSort +bib2gls sampleSort +pdflatex sampleSort +\end{prompt} + +In this case, I have one resource command that processes two +glossaries (\texttt{main} and \texttt{acronym}) at the same time. +The entries in these glossaries are ordered alphabetically. +The second resource command processes the \texttt{notation} glossary but +the entries in this glossary aren't sorted (and so will appear in +the order of definition within the \filetype{bib} file). + +See also \samplefile{Ntn}, \bibglsgallery{sorting} and the \gls{bib2gls} user manual +for more examples. + +\section{Child Entries} +\label{sec:samplesparent} + +\exitem{} This document illustrates some of +the basics, including how to create child entries that use the same +name as the parent entry. This example adds the glossary to the +table of contents and it also uses \ics{glsrefentry}, so an extra \LaTeX\ +run is required: +\begin{prompt} +pdflatex sample +makeglossaries sample +pdflatex sample +pdflatex sample +\end{prompt} +You can see the difference between word and letter ordering if you +add the package option \pkgopt[letter]{order}. (Note +that this will only have an effect if you use +\gls{makeglossaries} or \gls{makeglossaries-lite.lua}. +If you use \gls{makeindex} explicitly, you will need to use the +\mkidxopt{l} switch to indicate letter ordering.) + +One of the entries has its name encapsulated with a semantic command: +\begin{alltt} +\cs{newcommand}\mgroup{\strong{\cs{scriptlang}}}[1]\mgroup{\cs{textsf}\mgroup{\#1}} + +\cs{newglossaryentry}\mgroup{Perl}\mgroup{name=\strong{\cs{scriptlang}}\mgroup{Perl},\strong{sort=Perl,} +description=\mgroup{A scripting language}} +\end{alltt} +This means that this entry needs to have the \gloskey{sort} key set +otherwise \gls{makeindex} will assign it to the \qt{symbol} letter +group, since it starts with a backslash (which \gls{makeindex} +simply treats as punctuation). + +The homograph entries \qt{glossary} and \qt{bravo} are defined as +sub-entries that inherit the name from the parent entry. The parent +entry doesn't have a description, but with the default +\pkgopt[false]{nopostdot} setting this will lead to a spurious dot. +This can be removed by adding \ics{nopostdesc} to the description, +which suppresses the post-description hook for that entry. + +Since the child entries have the same name as the parent, this means +that the child entries will have duplicate sort values unless the +default is changed with the \gloskey{sort} key: +\begin{alltt} +\cs{newglossaryentry}\mgroup{glossary}\mgroup{name=glossary, + description=\mgroup{\strong{\ics{nopostdesc}}},plural=\mgroup{glossaries}} + +\ics{newglossaryentry}\mgroup{glossarycol}\mgroup{ + description=\mgroup{collection of glosses}, + \strong{sort=\mgroup{2},} + parent=\mgroup{glossary}\% parent \emph{label} +} + +\cs{newglossaryentry}\mgroup{glossarylist}\mgroup{ + description=\mgroup{list of technical words}, + \strong{sort=\mgroup{1},} + parent=\mgroup{glossary}\% parent \emph{label} +} +\end{alltt} +(Remember that the entries are sorted hierarchically.) This will +place \texttt{glossarylist} before \texttt{glossarycol}, but both +will come immediately after their parent \texttt{glossary} entry. + +\glsxtrnote +If you switch to using \gls{glossaries-extra}, remember that the +default package options are different: +\begin{alltt} +\cs{usepackage}[\strong{\xtrfont{postdot},\xtrfont{stylemods}},style=treenonamegroup,order=word, + subentrycounter]\mgroup{\strong{glossaries-extra}} +\end{alltt} + +You may now want to consider replacing \ics{nopostdesc} in the +descriptions with \ics*{glsxtrnopostpunc} (using your +text editor's search and replace function). This suppresses the +post-description punctuation but not the category post-description +hook. + +You may have noticed that some of the descriptions include the +plural form, but it's not done very consistently. For example: +\begin{verbatim} +\newglossaryentry{cow}{name=cow, + plural=cows,% not required as this is the default + user1=kine, + description={(\emph{pl.}\ cows, \emph{archaic} kine) an adult +female of any bovine animal} +} +\end{verbatim} +which has the parenthetical material at the start of the +description with emphasis, +\begin{verbatim} +\newglossaryentry{bravocry}{ + description={cry of approval (pl.\ bravos)}, + sort={1}, + parent={bravo} +} +\end{verbatim} +which has the parenthetical material at the end of the +description without emphasis even though it's a regular plural, +\begin{verbatim} +\newglossaryentry{bravoruffian}{ + description={hired ruffian or killer (pl.\ bravoes)}, + sort={2}, + plural={bravoes}, + parent=bravo} +\end{verbatim} +which has the parenthetical material at the end of the +description without emphasis, and +\begin{verbatim} +\newglossaryentry{glossary}{name=glossary, + description={\nopostdesc}, + plural={glossaries}} +\end{verbatim} +which doesn't show the plural in the description. + +With \gls{glossaries-extra}, you can remove this parenthetical +material and implement it using the category post-description hook instead. +For example, the above definitions become: +\begin{verbatim} +\newglossaryentry{cow}{name=cow, + user1=kine, + description={an adult female of any bovine animal} +} + +\newglossaryentry{bravocry}{ + description={cry of approval}, + sort={1}, + parent={bravo} +} + +\newglossaryentry{bravoruffian}{ + description={hired ruffian or killer}, + sort={2}, + plural={bravoes}, + parent=bravo} +\end{verbatim} +\begin{alltt} +\cs{newglossaryentry}\mgroup{glossary}\mgroup{name=glossary, + description=\mgroup{\strong{\ics*{glsxtrnopostpunc}}}, + plural=\mgroup{glossaries}} +\end{alltt} +The post-description hook for the \cat{general} category can now be +set: +\begin{alltt} +\ics*{glsdefpostdesc}\mgroup{general}\mgroup{\% +\codecomment{\% Has the user1 key been set?} + \ics*{glsxtrifhasfield}\mgroup{useri}\mgroup{\ics{glscurrententrylabel}}\% + \mgroup{\cs{space}(\cs{emph}\mgroup{pl.}\cs{ }\ics{glsentryplural}\mgroup{\ics{glscurrententrylabel}}, + \cs{emph}\mgroup{archaic} \ics{glscurrentfieldvalue})\% + }\% + \mgroup{\% +\codecomment{\% The user1 key hasn't been set. Is the plural the same as the +\% singular form with the plural suffix appended?} + \ics*{GlsXtrIfXpFieldEqXpStr}\mgroup{plural}\mgroup{\ics{glscurrententrylabel}}\% + \mgroup{\ics{glsentrytext}\mgroup{\ics{glscurrententrylabel}}\ics{glspluralsuffix}}\% + \mgroup{\% +\codecomment{\% Sibling check with \gls{bib2gls} (see below)} + }\% + \mgroup{\% +\codecomment{\% The plural isn't the default. Does this entry have a parent?} + \cs{ifglshasparent}\mgroup{\cs{glscurrententrylabel}}% + \mgroup{\% +\codecomment{\% This entry has a parent. +\% Are the plurals for the child and parent the same?} + \ics*{GlsXtrIfXpFieldEqXpStr}\mgroup{plural}\mgroup{\cs{glscurrententrylabel}}\% + \mgroup{\cs{glsentryplural}\mgroup{\cs{glsentryparent}\mgroup{\cs{glscurrententrylabel}}}}\% + \mgroup{}\% \codecomment{child and parent plurals the same} + \mgroup{\% + \cs{space}(\cs{emph}\mgroup{pl.}\cs{ }\cs{glsentryplural}\mgroup{\cs{glscurrententrylabel}})\% + }\% + }% + \mgroup{\cs{space}(\cs{emph}\mgroup{pl.}\cs{ }\ics{glsentryplural}\mgroup{\ics{glscurrententrylabel}})}\% + }\% + }\% +} +\end{alltt} +(If you try this example out, notice the difference for the +\texttt{glossary} entry if you use \cs{nopostdesc} and then +replace it with \ics*{glsxtrnopostpunc}.) +See the \gls{glossaries-extra} user manual for further details and +also \bibglsbegin. + +The \qt{bravo} homographs are an oddity where the singular form is +identical but the plural is different (\qt{bravos} and +\qt{bravoes}). In the original, both descriptions included the +plural term. The above modifications drop the display of the regular +\qt{bravos} plural (for the \texttt{bravocry} term) and only show +the \qt{bravoes} plural (for the \texttt{bravoruffian} term). In this +particular case it might be useful to show the regular plural in +order to highlight the difference. + +While it's straightforward to access an entry's parent label (with +\ics{glsentryparent}) it's much harder to access entry's children or +siblings. The \ics{ifglshaschildren} command has to iterate over all +entries to determine if any have a parent that matches the given +label. This is obviously very time-consuming if you have a large +database of entries. It also doesn't provide a way of determining +whether or not the child entries have been indexed. + +With \gls{bib2gls}, it's possible to save this information with the +\resourceopt{save-child-count} and \resourceopt{save-sibling-count}, +which not only save the total but also save the child or sibling +labels in an \sty{etoolbox} internal list. This makes the +information much faster to access and also only includes the labels of +those entries that have actually been indexed. + +In the above, the comment line: +\begin{alltt} +\codecomment{\% Sibling check with \gls{bib2gls} (see below)} +\end{alltt} +indicates where to put the extra code. If you switch to +\gls{bib2gls} and make sure to use \resourceopt{save-sibling-count} +then you can insert the following code in the block above where that +comment is: +\begin{alltt} +\ics*{GlsXtrIfFieldNonZero}\mgroup{siblingcount}\mgroup{\cs{glscurrententrylabel}}\% +\mgroup{\% \codecomment{\xtrfield{siblingcount} field value non-zero} + \ics*{glsxtrfieldforlistloop} \% \codecomment{iterate over internal list} + \mgroup{\cs{glscurrententrylabel}}\% \codecomment{entry label} + \mgroup{siblinglist}\% \codecomment{label of field containing list} + \mgroup{\cs{siblinghandler}}\% \codecomment{loop handler} +}\% +\mgroup{}\% \codecomment{\xtrfield{siblingcount} field value 0 or empty or missing} +\end{alltt} +This uses a custom handler that's defined as follows: +\begin{alltt} +\cs{newcommand}\mgroup{\cs{siblinghandler}}[1]\mgroup{\% + \ics*{GlsXtrIfXpFieldEqXpStr}*\mgroup{plural}\mgroup{\cs{glscurrententrylabel}}\% + \mgroup{\cs{glsentryplural}\mgroup{\#1}}\% + \mgroup{}\% \codecomment{current entry's plural same as sibling's plural} + \mgroup{\% + \cs{space}(\cs{emph}\mgroup{pl.}\cs{ }\cs{glsentryplural}\mgroup{\cs{glscurrententrylabel}})\% + \ics{listbreak} + }% +} +\end{alltt} +The \cs{listbreak} command is provided by \sty{etoolbox} and is used +for prematurely exiting a loop. The handler tests if the sibling's +\gloskey{plural} field is identical to the current entry's \gloskey{plural} +field. If they are the same, it does nothing. If they are different, +it displays the current entry's plural and breaks the loop. + +Note that this assumes that the parent entry hasn't had the plural +form explicitly set to \qt{bravoes} instead of the default +\qt{bravos}. In that case, the parent entry would show the plural +but the \texttt{bravoruffian} child entry wouldn't show the plural (since +this case would led to the empty code block identified with the +comment \qt{child and parent plurals the same}). The \qt{bravoes} +plural form would instead be shown for the parent, which wouldn't +look right. + +If you don't use \gls{bib2gls} or if you use it without the +\resourceopt{save-sibling-count} resource option then the sibling +information won't be available. + +\bibglsnote +In order to switch to using \gls{bib2gls}, it's first necessary to +switch to using \gls{glossaries-extra} (as above). Remember that the +\pkgopt*{record} option is required: +\begin{alltt} +\cs{usepackage}[\strong{\xtrfont{record},}\xtrfont{postdot},\xtrfont{stylemods},style=treenonamegroup, +subentrycounter]\mgroup{glossaries-extra} +\end{alltt} +Next the entry definitions need to be converted to the +\filetype{bib} format required by \gls{bib2gls}. This can be done +with \gls{convertgls2bib}: +\begin{alltt} +convertgls2bib -{}-preamble-only sample.tex entries. +\end{alltt} +The semantic command may be moved to the \filetype{bib} file to +ensure it's defined: +\begin{alltt} +\atentry{preamble}\mgroup{"\cs{providecommand}\mgroup{\cs{scriptlang}}[1]\mgroup{\cs{textsf}\mgroup{\#1}}"} +\end{alltt} + +The \gloskey{sort} field typically shouldn't be set when using +\gls{bib2gls}, so \gls{convertgls2bib} strips it. +If the \gloskey{sort} field is missing, \gls{bib2gls} will obtain it +from the sort fallback for that entry type. In this case, +\atentry{entry} has the \gloskey{name} field as the sort fallback. +If this is also missing then its value is obtained from the parent's +\gloskey{name} field (see \bibglsgallery{sorting} for other examples). + +Therefore the \qt{Perl} entry is simply defined as: +\begin{alltt} +\atentry{entry}\mgroup{Perl, + name = \mgroup{\cs{scriptlang}\mgroup{Perl}}, + description = \mgroup{A scripting language} +} +\end{alltt} +This isn't a problem for \gls{bib2gls}. In this case, the command +has been provided in the \atentry{preamble}, but \gls{bib2gls} +strips font information so the sort value becomes \texttt{Perl}. +If the definition isn't placed in \atentry{preamble} then +\gls{bib2gls} will simply ignore the command (as \gls{xindy} does) +so the sort value will still end up as \texttt{Perl}. + +The homograph entries have also had their \gloskey{sort} fields omitted: +\begin{alltt} +\atentry{entry}\mgroup{glossarycol, + parent = \mgroup{glossary}, + description = \mgroup{collection of glosses} +} + +\atentry{entry}\mgroup{glossarylist, + parent = \mgroup{glossary}, + description = \mgroup{list of technical words} +} +\end{alltt} + +This means that the sort value for both these child entries is +\qt{glossary}. When \gls{bib2gls} encounters identical sort values +it acts according to its \resourceopt{identical-sort-action} setting. +The default action is to sort by the label using a simple string +comparison. In this case, it would put \texttt{glossarycol} before +\texttt{glossarylist}. In the original document, the \gloskey{sort} +value was manually chosen to ensure that the entries are ordered +according to \gls{firstuse}. This ordering can easily be obtained +by changing \gls{bib2gls}['s] identical sort action (requires at +least \gls{bib2gls} v2.0): +\begin{alltt} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=\mgroup{entries},\strong{\xtrfont{identical-sort-action}=use}] +\end{alltt} +This command should replace \cs{makeglossaries}. If you want the +sibling information (see earlier), then you need to remember to add +\resourceopt{save-sibling-count} to the list of options. + +Note that this is a better solution than in the original example. If +I edit the document so that \texttt{glossarycol} is used first, then +the ordering will be updated accordingly, but with the original +example, the \gloskey{sort} keys would need to be manually changed. + +The remainder of the preamble (that is, the definition of +\cs{scriptlang} and all the entry definitions) should now be +removed. + +Finally, replace \cs{printglossaries} with \ics*{printunsrtglossaries}. +The document build is now: +\begin{prompt} +pdflatex sample +bib2gls -{}-group sample +pdflatex sample +pdflatex sample +\end{prompt} +Note use of the \bibglslongopt{group} (or \bibglsopt{g}) switch, which is needed +to support the \glostyle{treenonamegroup} style. The third \LaTeX\ +call is needed because the document contains \ics{glsrefentry}. + +Note that you can't use the \pkgopt[letter]{order} package option +with \gls{bib2gls}. Instead use the \resourceopt[none]{break-at} +resource option: +\begin{alltt} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=\mgroup{entries},\xtrfont{identical-sort-action}=use, + \strong{\xtrfont{break-at}=none} +] +\end{alltt} + +\exitem{-inline} This document is +like \texttt{sample.tex}, above, but uses the \glostyle{inline} +glossary style to put the glossary in a footnote. The document build +is: +\begin{prompt} +pdflatex sample-inline +makeglossaries sample-inline +pdflatex sample-inline +pdflatex sample-inline +\end{prompt} +If you want to convert this document to \gls{glossaries-extra}, +follow the same procedure as above. If you want to use \gls{bib2gls} +then you don't need the \bibglslongopt{group} switch since no letter +groups are required. + +\exitem{tree} This document illustrates +a hierarchical glossary structure where child entries have different +names to their corresponding parent entry. To create the document +do: +\begin{prompt} +pdflatex sampletree +makeglossaries sampletree +pdflatex sampletree +\end{prompt} +The document uses the \glostyle{alttreehypergroup} glossary style, +which needs to know the widest name for each hierarchical level. +This has been assigned manually in the preamble with +\ics{glssetwidest}: +\begin{verbatim} +\glssetwidest{Roman letters} % level 0 widest name +\glssetwidest[1]{Sigma} % level 1 widest name +\end{verbatim} +(Level~0 is the top-most level. That is, entries that don't have a +parent.) It's possible to get \styfmt{glossaries} to compute the +widest top-level entry with \ics{glsfindwidesttoplevelname} but this +will iterate over all top-level entries, regardless of whether or +not they appear in the glossary. If you have a large database of +entries, this will firstly take time and secondly the width may be +too large due to an unindexed entry with a big name. + +This sample document doesn't require any of the tabular styles so I've +prevented those packages from being loaded with \pkgopt{nolong} and +\pkgopt{nosuper}. The reduces the overall package loading. +\begin{alltt} +\cs{usepackage}[style=alttreehypergroup,\strong{nolong,nosuper}] +\mgroup{glossaries} +\end{alltt} +(This example glossary is actually better suited for one of the +topic styles provided with \sty*{glossary-topic}, see below.) + +This is obviously a contrived example since it's strange to have the +symbol names (such as \qt{Sigma}) in the glossary. The purpose is to +demonstrate the \glostyle{alttreehypergroup} with an entry that's +noticeably wider than the others in the same hierarchical level. A +more sensible document would have the symbol in the \gloskey{name} +key. + +\glsxtrnote +If you want to switch to \gls{glossaries-extra}, then you can +instead use a combination of \pkgopt{nostyles} and +\pkgopt*{stylemods}: +\begin{alltt} +\cs{usepackage}[style=alttreehypergroup,\xtrfont{postdot},\strong{nostyles, +\xtrfont{stylemods=tree}}]\mgroup{\strong{glossaries-extra}} +\end{alltt} +The \pkgopt*{stylemods} package not only patches the original styles +provided by the base \styfmt{glossaries} package (such as +\sty{glossary-tree} used in this example) but also provides extra +helper commands. In this case, it provides additional commands to +calculate the widest name. For example, instead of manually setting +the widest entry with \ics{glssetwidest}, you could add the +following before the glossary: +\begin{alltt} +\ics*{glsFindWidestUsedTopLevelName} +\ics*{glsFindWidestUsedLevelTwo} +\end{alltt} +This will only take into account the entries that have actually been +used in the document, but it can still be time-consuming if you have +a large number of entries. + +\begin{important} +Note that the glossary must be at the end of the document (after all +required entries have been used) with this method. The alternative +is to perform the calculation at the end of the document and save +the results in the \filetype{aux} file for the next run. +\end{important} + +This example document is using top-level entries for topics without +descriptions. This means that the descriptions simply contain +\ics{nopostdesc} to prevent the post-description punctuation from +being automatically inserted. For example: +\begin{verbatim} +\newglossaryentry{greekletter}{name={Greek letters}, +text={Greek letter}, +description={\nopostdesc}} +\end{verbatim} +With \gls{glossaries-extra}, you can convert this to +\ics*{glsxtrnopostpunc} which will prevent the post-description +punctuation without interfering with the category post-description +hook. + +In order to distinguish between the child entries, which are +symbols, and the parent entries, which are topics, it's useful to +give these two different types of entries different categories. The +topics can use the default \cat{general} category, but the symbol +entries can be assigned to a different category. The value of the +\xtrgloskey{category} key must be a label. For example: +\begin{alltt} +\cs{newglossaryentry}\mgroup{C}\mgroup{name=\mgroup{C}, +description=\mgroup{Euler's constant}, +\strong{\xtrfont{category}=symbol,} +parent=romanletter} +\end{alltt} + +There is some redundancy caused by a parenthetical note after the \gls{firstuse} in some +of the symbol entries. For example: +\begin{verbatim} +\newglossaryentry{pi}{name={pi}, +text={\ensuremath{\pi}}, +first={\ensuremath{\pi} (lowercase pi)}, +description={Transcendental number}, +parent=greekletter} +\end{verbatim} +With \gls{glossaries-extra} this can be dealt with through the category post-link hook: +\begin{alltt} +\ics*{glsdefpostlink}\mgroup{symbol}\mgroup{\% + \ics*{glsxtrifwasfirstuse} + \mgroup{\% first use + \ics*{glsxtrifhasfield}\mgroup{useri}\mgroup{\ics{glslabel}}\% + \mgroup{ (\ics{glscurrentfieldvalue})}\mgroup{}\% + }\% + \mgroup{}\% not first use +} +\end{alltt} +The parenthetical material is now stored in the \gloskey{user1} key. +For example: +\begin{alltt} +\cs{newglossaryentry}\mgroup{sigma}\mgroup{name={Sigma}, +text=\mgroup{\cs{ensuremath}{\cs{Sigma}}}, +\strong{user1=\mgroup{uppercase sigma},} +description=\mgroup{Used to indicate summation}, +parent=greekletter} +\end{alltt} +The category post-description link is also set to ensure that the symbol is +displayed after the description in the glossary: +\begin{alltt} +\ics*{glsdefpostdesc}\mgroup{symbol}\mgroup{\cs{space} + (\$\ics{glsentrytext}\mgroup{\ics{glscurrententrylabel}}\$)} +\end{alltt} +These modifications only affect entries with the +\xtrgloskey{category} set to \cat{symbol}. + +With \gls{glossaries-extra}, it's now possible to use the topic +styles provided with the \sty*{glossary-topic} package: +\begin{alltt} +\cs{usepackage}[style=\strong{\xtrfont{topic}},\xtrfont{postdot},\strong{nostyles,\xtrfont{stylemods=\mgroup{tree\strong{,topic}}}}] +\mgroup{\strong{glossaries-extra}} +\end{alltt} +The \xtrglostyle{topic} style is designed for this kind of hierarchy +where all the top-level entries don't have descriptions. This means +that the \ics{nopostdot} and \ics*{glsxtrnopostpunc} commands aren't +required. The top-level entries can simply be defined as: +\begin{alltt} +\cs{newglossaryentry}\mgroup{greekletter}\mgroup{name=\mgroup{Greek letters}, +text=\mgroup{Greek letter}, description=\mgroup{}} + +\cs{newglossaryentry}\mgroup{romanletter}\mgroup{name=\mgroup{Roman letters}, +text=\mgroup{Roman letter}, description=\mgroup{}} +\end{alltt} +I've now loaded both the \sty{glossary-tree} and +\sty{glossary-topic} packages +(via \pkgopt*{stylemods}\optfmt{\dequals\mgroup{tree\dcomma topic}}). The +\sty{glossary-topic} package can be used without +\sty{glossary-tree}, in which case it will behave more like the +normal \glostyle{tree} rather than \glostyle{alttree} styles (but +with different indentation and no description in the top-level). +However, if you use \ics{glssetwidest} (provided by +\sty{glossary-tree}) then the \xtrglostyle{topic} style will behave +more like \glostyle{alttree}. + +Since there's no description for the top-level entries, the +\xtrglostyle{topic} style ignores the widest name setting for the +top-level, so I can just have the level~1 setting: +\begin{verbatim} +\glssetwidest[1]{Sigma} +\end{verbatim} + +\bibglsnote +If you want to convert this document so that it uses \gls{bib2gls}, +you first need to convert it to using \gls{glossaries-extra}, as +described above, but remember that you now need the \pkgopt*{record} +option. +\begin{alltt} +\cs{usepackage}[\strong{\xtrfont{record},}style=topic,\xtrfont{postdot},nostyles,\xtrfont{stylemods=\mgroup{tree,topic}}] +\mgroup{\strong{glossaries-extra}} +\end{alltt} +Next convert the entries to the \filetype{bib} format required by +\gls{bib2gls}: +\begin{prompt} +convertgls2bib -{}-preamble-only sampletree.tex entries.bib +\end{prompt} +Now replace \cs{makeglossaries} with: +\begin{alltt} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=entries,\strong{\xtrfont{set-widest}}] +\end{alltt} +I've used the \resourceopt{set-widest} option here to get +\gls{bib2gls} to compute the widest name. (Obviously, it can only do +this if it can correctly interpret any commands contained in the +\gloskey{name} field.) + +This means that the \ics{glssetwidest} commands can now be removed +completely. All the \cs{newglossaryentry} commands also need to be removed from +the preamble. Finally, \cs{printunsrtglossaries} needs to be +replaced with \ics*{printunsrtglossaries}. The document build is now: +\begin{prompt} +pdflatex sampletree +bib2gls sampletree +pdflatex sampletree +\end{prompt} + +This produces the same result as with just \gls{glossaries-extra} +and \gls{makeglossaries}. However, there are some modifications that +can be made to the \filetype{bib} file to make it neater. + +The top-level entries are defined as: +\begin{alltt} +\atentry{entry}\mgroup{greekletter, + name = \mgroup{Greek letters}, + description = \mgroup{}, + text = \mgroup{Greek letter} +} + +\atentry{entry}\mgroup{romanletter, + name = \mgroup{Roman letters}, + description = \mgroup{}, + text = \mgroup{Roman letter} +} +\end{alltt} +This is a direct translation from the \cs{newglossaryentry} commands +(after switching to the \xtrglostyle{topic} style). There's a more +appropriate entry type: +\begin{alltt} +\atentry{indexplural}\mgroup{greekletter, + text = \mgroup{Greek letter} +} + +\atentry{indexplural}\mgroup{romanletter, + text = \mgroup{Roman letter} +} +\end{alltt} +The \atentry{indexplural} entry type doesn't require the +\gloskey{description} and will set the \gloskey{name} field to the +same as the \gloskey{plural} field. Since the \gloskey{plural} field +hasn't been set it's obtained by appending \qt{s} to the +\gloskey{text} field. + +Now let's assume that the symbol entries are defined in a more +rational manner, with the actual symbol in the \gloskey{name} field. +For example: +\begin{alltt} +\atentry{entry}\mgroup{sigma, + user1 = \mgroup{uppercase sigma}, + parent = \mgroup{greekletter}, + description = \mgroup{Used to indicate summation}, + \strong{name = \mgroup{\cs{ensuremath}\mgroup{\cs{Sigma}}}}, + category = \mgroup{symbol} +} + +\atentry{entry}\mgroup{C, + parent = \mgroup{romanletter}, + name = \mgroup{\cs{ensuremath}\mgroup{C}}, + description = \mgroup{Euler's constant}, + category = \mgroup{symbol} +} +\end{alltt} +The category post-description hook (provided with +\ics*{glsdefpostdesc}) should now be removed from the document. + +If you make these changes and rebuild the document, you'll find that +the order has changed. Now the \texttt{sigma} entry is before the +\texttt{pi} entry. This is because \gls{bib2gls} is obtaining the +sort values from the \gloskey{name} field, which is the sort +fallback for \atentry{entry}. This means that the sort values end up +as $\Sigma$ and $\pi$ (\gls{bib2gls} recognises the commands +\ics{Sigma} and \ics{pi} and converts them to the Unicode characters +0x1D6F4 and 0x1D70B). + +If you change \atentry{entry} to \atentry{symbol} then you will once +again get the order from the original example (\texttt{pi} before +\texttt{Sigma}). This is because the sort fallback for +\atentry{symbol} is the label not the \gloskey{name}. (Remember that +the sort fallback is only used if the \gloskey{sort} field isn't +set. If you explicitly set the \gloskey{sort} field then no fallback +is required. See \bibglsgallery{sorting}.) + +You can further tidy the \filetype{bib} file by removing the +\xtrgloskey{category} fields. For example: +\begin{alltt} +\atentry{symbol}\mgroup{sigma, + user1 = \mgroup{uppercase sigma}, + parent = \mgroup{greekletter}, + description = \mgroup{Used to indicate summation}, + name = \mgroup{\cs{ensuremath}\mgroup{\cs{Sigma}}} +} +\end{alltt} +You can then assign the \xtrgloskey{category} in the resource set: +\begin{alltt} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=entries,\xtrfont{set-widest},\strong{\xtrfont{category}=\mgroup{same as entry}}] +\end{alltt} +This means that all the entries defined with \atentry{symbol} will +have the \xtrgloskey{category} set to \texttt{symbol} and all the +entries defined with \atentry{indexplural} will have the +\xtrgloskey{category} set to \texttt{indexplural}. (Only the +\cat{symbol} category is significant in this example.) + +You can make the \filetype{bib} files even more flexible by +introducing field and entry aliases with \resourceopt{field-aliases} +and \resourceopt{entry-type-aliases}. See the \gls{bib2gls} manual +for further details. -\begin{important} -Some of the commands described here take a comma-separated list as -an argument. As with \LaTeX's \cs{@for} command, make sure your list -doesn't have any unwanted spaces in it as they don't get stripped. -(Discussed in more detail in -\href{http://www.dickimaw-books.com/latex/admin/html/docsvlist.shtml#spacesinlists}{\S2.7.2 of \qt{\LaTeX\ for Administrative -Work}}.) -\end{important} +\section{Cross-Referencing} +\label{sec:samplescrossref} -\begin{definition}[\DescribeMacro{\forallglossaries}] -\cs{forallglossaries}\oarg{glossary list}\marg{cs}\marg{body} -\end{definition} -This iterates through \meta{glossary list}, a comma-separated list -of glossary labels (as supplied when the glossary was defined). -At each iteration \meta{cs} (which must be a control sequence) is -set to the glossary label for the current iteration and \meta{body} -is performed. If \meta{glossary list} is omitted, the default is to -iterate over all glossaries (except the ignored ones). +\exitem{-crossref} +This document illustrates how to cross-reference entries in the +glossary. +\begin{prompt} +pdflatex sample-crossref +makeglossaries sample-crossref +pdflatex sample-crossref +\end{prompt} +The document provides a command \ics{alsoname} to produce some fixed text, which can be +changed as appropriate (usually within a language hook): +\begin{verbatim} +\providecommand{\alsoname}{see also} +\end{verbatim} +I've used \cs{providecommand} as some packages define this command. +This is used to create a \qt{see also} cross-reference with the +\gloskey{see} key: +\begin{verbatim} +\newglossaryentry{apple}{name=apple,description={firm, round fruit}, +see=[\alsoname]{pear}} -\begin{definition}[\DescribeMacro{\forallacronyms}] -\cs{forallacronyms}\marg{cs}\marg{body} -\end{definition} -This is like \cs{forallglossaries} but only iterates over the -lists of acronyms (that have previously been declared using -\ics{DeclareAcronymList} or the \pkgopt{acronymlists} package -option). This command doesn't have an optional argument. If you want -to explicitly say which lists to iterate over, just use the optional -argument of \cs{forallglossaries}. +\newglossaryentry{marrow}{name={marrow}, + description={long vegetable with thin green skin and white flesh}, + see={[\alsoname]courgette}} +\end{verbatim} -\begin{definition}[\DescribeMacro{\forglsentries}] -\cs{forglsentries}\oarg{glossary label}\marg{cs}\marg{body} -\end{definition} -This iterates through all entries in the glossary given by -\meta{glossary label}. At each iteration \meta{cs} (which must be a -control sequence) is set to the entry label for the current -iteration and \meta{body} is performed. If \meta{glossary label} is -omitted, \ics{glsdefaulttype} (usually the main glossary) is used. +Note that \qt{marrow} is included in the glossary even though it +hasn't been referenced in the text. This is because the +\gloskey{see} key automatically triggers \ics{glssee} which indexes +the term. This behaviour is intended for documents where only the +terms that are actually required in the document are defined. It's +not suitable for a large database of terms shared across multiple +documents that may or may not be used in a particular document. In +that case, you may want to consider using \gls{glossaries-extra} +(see below). -\begin{definition}[\DescribeMacro{\forallglsentries}] -\cs{forallglsentries}\oarg{glossary list}\marg{cs}\marg{body} -\end{definition} -This is like \cs{forglsentries} but for each glossary in -\meta{glossary list} (a comma-separated list of glossary labels). If -\meta{glossary list} is omitted, the default is the list of all -defined glossaries (except the ignored ones). At each iteration -\meta{cs} is set to the entry label and \meta{body} is performed. -(The current glossary label can be obtained using -\cs{glsentrytype}\marg{cs} within \meta{body}.) +\glsxtrnote +This example is quite simple to convert to \gls{glossaries-extra}. +If you want the dot after the description, you need the +\pkgopt[false]{nopostdot} or \pkgopt*{postdot} package option. You +may also want to consider using the \pkgopt*{stylemods} option. -\section{Conditionals} -\label{sec:conditionals} +In order to prevent the \qt{marrow} entry from being automatically +being added to the glossary as a result of the cross-reference, you +can use \pkgopt+{false}{autoseeindex} to prevent the automatic +indexing triggered by the \gloskey{see} key (or the +\xtrgloskey{seealso} key provided by \gls{glossaries-extra}). -\begin{definition}[\DescribeMacro{\ifglossaryexists}] -\cs{ifglossaryexists}{\meta{label}}{\meta{true part}}{\meta{false -part}} -\end{definition} -This checks if the glossary given by \meta{label} exists. If it -does \meta{true part} is performed, otherwise \meta{false part}. +\begin{alltt} +\cs{usepackage}[\strong{\xtrfont{autoseeindex}=false},\xtrfont{postdot},\xtrfont{stylemods}]\mgroup{glossaries-extra} +\end{alltt} +The document build is the same, but now the \qt{marrow} and +\qt{zucchini} entries aren't present in the document. -\begin{definition}[\DescribeMacro{\ifglsentryexists}] -\cs{ifglsentryexists}{\meta{label}}{\meta{true part}}{\meta{false -part}} -\end{definition} -This checks if the glossary entry given by \meta{label} exists. If it -does \meta{true part} is performed, otherwise \meta{false part}. -(Note that \cs{ifglsentryexists} will always be true after the -containing glossary has been displayed via \ics{printglossary} -or \ics{printglossaries} even if the entry is explicitly defined -later in the document. This is because the entry has to be defined -before it can be displayed in the glossary, see \sectionref{sec:techissues} for -further details.) +Note that the \qt{fruit} entry is still included even though it +hasn't been used in the document. This is because it was explicitly +indexed with \ics{glssee} not via the \gloskey{see} key. -\begin{definition}[\DescribeMacro{\glsdoifexists}] -\cs{glsdoifexists}\marg{label}\marg{code} -\end{definition} -Does \meta{code} if the entry given by \meta{label} exists. If it -doesn't exist, an error is generated. (This command uses -\cs{ifglsentryexists}.) +The entries that contains \texttt{see=[\cs{alsoname}]} +can be converted to use the \xtrgloskey{seealso} key: +\begin{alltt} +\cs{newglossaryentry}\mgroup{apple}\mgroup{name=apple,description=\mgroup{firm, round fruit}, +\strong{\xtrfont{seealso}=\mgroup{pear}}} -\begin{definition}[\DescribeMacro{\glsdoifnoexists}] -\cs{glsdoifnoexists}\marg{label}\marg{code} -\end{definition} -Does the reverse of \cs{glsdoifexists}. (This command uses -\cs{ifglsentryexists}.) +\cs{newglossaryentry}\mgroup{marrow}\mgroup{name=\mgroup{marrow}, + description=\mgroup{long vegetable with thin green skin and white flesh}, + \strong{\xtrfont{seealso}=\mgroup{courgette}}} +\end{alltt} +(The provided \cs{alsoname} definition may be removed.) -\begin{definition}[\DescribeMacro{\glsdoifexistsorwarn}] -\cs{glsdoifexistsorwarn}\marg{label}\marg{code} -\end{definition} -As \cs{glsdoifexists} but issues a warning rather than an error if -the entry doesn't exist. +The original example redefines the cross-referencing format to use +\gls{smallcaps}: +\begin{alltt} +\cs{renewcommand}\mgroup{\ics{glsseeitemformat}}[1]\mgroup{\cs{textsc}\mgroup{\ics{glsentryname}\mgroup{\#1}}} +\end{alltt} +This will still produce the desired effect with \gls{glossaries-extra} for +this simple example but, as with \samplefile{AcrDesc}, +this redefinition isn't necessary if you have at least +\gls{glossaries-extra} v1.42. + +\bibglsnote +If you want to switch to \gls{bib2gls} then you first need to switch +to \gls{glossaries-extra}, as described above, but you now need the +\pkgopt*{record} option but no longer need the +\pkgopt+{false}{autoseeindex} option: +\begin{alltt} +\cs{usepackage}[\strong{\xtrfont{record}},\xtrfont{postdot},\xtrfont{stylemods}]\mgroup{glossaries-extra} +\end{alltt} +Next the entry definitions need to be converted to the +\filetype{bib} format required by \gls{bib2gls}. +\begin{prompt} +convertgls2bib sample-crossref.tex entries.bib +\end{prompt} +If you have at least v2.0 then \gls{convertgls2bib} will absorb the +cross-referencing information supplied by: +\begin{verbatim} +\glssee{fruit}{pear,apple,banana} +\end{verbatim} +into the \texttt{fruit} definition: +\begin{alltt} +\atentry{entry}\mgroup{fruit, + see = \mgroup{pear,apple,banana}, + name = \mgroup{fruit}, + description = \mgroup{sweet, fleshy product of plant containing seed} +} +\end{alltt} +Now remove \cs{makeglossaries} and all the entry definition commands +(including \cs{glssee} from the preamble) and add: +\begin{alltt} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=entries.bib] +\end{alltt} +Finally, replace \cs{printglossaries} with +\ics*{printunsrtglossaries}. The document build is now: +\begin{prompt} +pdflatex sample-crossref +bib2gls sample-crossref +pdflatex sample-crossref +\end{prompt} +The glossary now contains: apple, banana, courgette and pear. Note +that it doesn't contain fruit, zucchini or marrow. -\begin{definition}[\DescribeMacro{\glsdoifexistsordo}] -\cs{glsdoifexistsordo}\marg{label}\marg{code}\marg{else code} -\end{definition} -Does \meta{code} if the entry given by \meta{label} exists otherwise -generate an error and do \meta{else code}. +Now change the selection criteria: +\begin{alltt} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=entries.bib, + \strong{\xtrfont{selection}=\mgroup{recorded and deps and see}}] +\end{alltt} +The glossary now includes fruit, zucchini and marrow. -\begin{definition}[\DescribeMacro{\glsdoifnoexistsordo}] -\cs{glsdoifnoexistsordo}\marg{label}\marg{code}\marg{else code} -\end{definition} -Does \meta{code} if the entry given by \meta{label} doesn't exist otherwise -generate an error and do \meta{else code}. +The fruit and zucchini use the \gloskey{see} key which is a simple +redirection for the reader. There's no \gls{numberlist} for either +of these entries. Whereas marrow uses the \xtrgloskey{seealso} key, +which is typically intended as a supplement to a \gls{numberlist} +but in this case there are no locations as marrow hasn't been used +in the text. -\begin{definition}[\DescribeMacro{\ifglsused}] -\cs{ifglsused}{\meta{label}}{\meta{true part}}{\meta{false -part}} -\end{definition} -See \sectionref{sec:glsunset}. +With at least v2.0, there's an alternative: +\begin{alltt} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=entries.bib, + \resourceopt{selection}=\mgroup{recorded and deps and see\strong{ not also}}] +\end{alltt} +In this case, the glossary includes fruit and zucchini but not marrow. -\begin{definition}[\DescribeMacro{\ifglshaschildren}] -\cs{ifglshaschildren}{\meta{label}}{\meta{true part}}{\meta{false -part}} -\end{definition} -This checks if the glossary entry given by \meta{label} has any -sub-entries. If it does, \meta{true part} is performed, otherwise -\meta{false part}. -\begin{definition}[\DescribeMacro{\ifglshasparent}] -\cs{ifglshasparent}{\meta{label}}{\meta{true part}}{\meta{false -part}} -\end{definition} -This checks if the glossary entry given by \meta{label} has a parent -entry. If it does, \meta{true part} is performed, otherwise -\meta{false part}. +\section{Custom Keys} +\label{sec:samplescustomkeys} -\begin{definition}[\DescribeMacro{\ifglshassymbol}] -\cs{ifglshassymbol}\marg{label}\marg{true part}\marg{false part} -\end{definition} -This checks if the glossary entry given by \meta{label} has had the -\gloskey{symbol} field set. If it has, \meta{true part} is performed, -otherwise \meta{false part}. +\exitem{-newkeys} This document illustrates how add custom keys +(using \ics{glsaddkey}). There are two custom keys \texttt{ed}, where +the default value is the \gloskey{text} field with \qt{ed} appended, +and \texttt{ing}, where the default value is the \gloskey{text} +field with \qt{ing} appended. Since the default value in both cases +references the \gloskey{text} field, the starred version +\cs{glsaddkey*} is required to ensure that the default value is expanded on +definition if no alternative has been provided. -\begin{definition}[\DescribeMacro{\ifglshaslong}] -\cs{ifglshaslong}\marg{label}\marg{true part}\marg{false part} -\end{definition} -This checks if the glossary entry given by \meta{label} has had the -\gloskey{long} field set. If it has, \meta{true part} is performed, -otherwise \meta{false part}. This should be true for any entry that -has been defined via \ics{newacronym}. -There is no check for the existence of \meta{label}. +The entries are then defined as follows: +\begin{verbatim} +\newglossaryentry{jump}{name={jump},description={}} -\begin{definition}[\DescribeMacro{\ifglshasshort}] -\cs{ifglshasshort}\marg{label}\marg{true part}\marg{false part} -\end{definition} -This checks if the glossary entry given by \meta{label} has had the -\gloskey{short} field set. If it has, \meta{true part} is performed, -otherwise \meta{false part}. This should be true for any entry that -has been defined via \ics{newacronym}. -There is no check for the existence of \meta{label}. +\newglossaryentry{run}{name={run},% + ed={ran},% + ing={running}, + description={}} -\begin{definition}[\DescribeMacro{\ifglshasdesc}] -\cs{ifglshasdesc}\marg{label}\marg{true part}\marg{false part} -\end{definition} -This checks if the \gloskey{description} field is non-empty for -the entry given by \meta{label}. If it has, \meta{true part} is -performed, otherwise \meta{false part}. Compare with: -\begin{definition}[\DescribeMacro{\ifglsdescsuppressed}] -\cs{ifglsdescsuppressed}\marg{label}\marg{true part}\marg{false part} -\end{definition} -This checks if the \gloskey{description} field has been set to just -\ics{nopostdesc} for the entry given by \meta{label}. If it has, -\meta{true part} is performed, otherwise \meta{false part}. -There is no check for the existence of \meta{label}. +\newglossaryentry{waddle}{name={waddle},% + ed={waddled},% + ing={waddling},% + description={}} +\end{verbatim} -For all other fields you can use: -\begin{definition}[\DescribeMacro\ifglshasfield] -\cs{ifglshasfield}\marg{field}\marg{label}\marg{true part}\marg{false -part} -\end{definition} -This tests the value of the field given by \meta{field} for the entry -identified by \meta{label}. If the value is empty \emph{or the default -value}, then \meta{false part} is performed, otherwise \meta{true -part} is performed. If the field supplied is unrecognised \meta{false part} -is performed and a warning is issued. Unlike the above commands, -such as \cs{ifglshasshort}, an error occurs if the entry is -undefined. +Each custom key is provided a set of commands analogous to +\cs{glsentrytext}, that allows the key value to be accessed, and +\cs{glstext} that allows the key value to be access with indexing +and hyperlinking (where applicable). -As from version 4.23, within \meta{true part} you can use -\begin{definition}[\DescribeMacro\glscurrentfieldvalue] -\cs{glscurrentfieldvalue} -\end{definition} -to access the field value. This command is -initially defined to nothing but has -no relevance outside \meta{true part}. This saves re-accessing the -field if the test is true. For example: +If you find yourself wanting to create a lot of custom keys that +produce minor variations of existing keys (such as different tenses) +you may find it simpler to just use \cs{glsdisp}. When editing the +document source, it's usually simpler to read: \begin{verbatim} -\ifglshasfield{useri}{sample}{, \glscurrentfieldvalue}{} +The dog \glsdisp{jump}{jumped} over the duck. +\end{verbatim} +than +\begin{verbatim} +The dog \glsed{jump} over the duck. \end{verbatim} -will insert a comma, space and the field value if the -\gloskey{user1} key has been set for -the entry whose label is \texttt{sample}. -You can test if the value of the field is equal to a given string -using: -\begin{definition}[\DescribeMacro\ifglsfieldeq] -\cs{ifglsfieldeq}\marg{label}\marg{field}\marg{string}\marg{true}\marg{false} -\end{definition} -In this case the \meta{field} must be the field name not the key -(see \tableref{tab:fieldmap}). If the field isn't recognised, an -error will occur. This command internally uses -\sty{etoolbox}'s \cs{ifcsstring} to perform the comparison. \emph{The -string is not expanded during the test.} +\bibglsnote +If you want to convert this document to use \gls{bib2gls}, you first +need to switch to \gls{glossaries-extra}, but remember that you need +the \pkgopt*{record} option: +\begin{alltt} +\cs{usepackage}[\strong{\xtrfont{record}}]{\strong{glossaries-extra}} +\end{alltt} +Next convert the entry definitions to the \filetype{bib} format +required by \gls{bib2gls}: +\begin{prompt} +convertgls2bib -{}-index-conversion -{}-preamble-only sample-newkeys.tex entries.bib +\end{prompt} +The \texttt{-{}-index-conversion} switch requires at least v2.0 and +will convert entries without a description (or where the description +is simply \ics{nopostdesc} or \ics*{glsxtrnopostpunc}) to +\atentry{index} instead of \atentry{entry}. This means that the +new \nolinkurl{entries.bib} file will contain: +\begin{alltt} +\atentry{index}\mgroup{jump, + name = \mgroup{jump} +} -The result may vary depending on whether or not expansion is on for -the given field (when the entry was defined). For example: -\begin{verbatim} -\documentclass{article} +\atentry{index}\mgroup{run, + ing = \mgroup{running}, + name = \mgroup{run}, + ed = \mgroup{ran} +} -\usepackage{glossaries} +\atentry{index}\mgroup{waddle, + ing = \mgroup{waddling}, + name = \mgroup{waddle}, + ed = \mgroup{waddled} +} +\end{alltt} +Now replace \cs{makeglossaries} with +\begin{alltt} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=entries] +\end{alltt} +and delete the \cs{newglossaryentry} commands. Finally replace +\cs{printglossaries} with \ics*{printunsrtglossaries}. -\newcommand*{\foo}{FOO} +The document build is now: +\begin{prompt} +pdflatex sample-newkeys +bib2gls sample-newkeys +pdflatex sample-newkeys +\end{prompt} +Note that there's no need for the \pkgopt{nonumberlist} package +option when you don't use \gls{bib2gls}['s] \texttt{-{}-group} +switch. + +\exitem{-storage-abbr} This document illustrates how add custom +storage keys (using \cs{glsaddstoragekey}). The document build is: +\begin{prompt} +pdflatex sample-storage-abbr +makeglossaries sample-storage-abbr +pdflatex sample-storage-abbr +\end{prompt} + +The custom storage key is called \texttt{abbrtype} which defaults +to \texttt{word} if not explicitly set. Its value can be accessed +with the provided custom command \cs{abbrtype}. +\begin{alltt} +\ics{glsaddstoragekey}\mgroup{abbrtype}\mgroup{word}\mgroup{\cs{abbrtype}} +\end{alltt} +A custom abbreviation style is then defined that checks the value of +this key and makes certain adjustments depending on whether or not +its value is the default \texttt{word}. + +This essentially forms a very similar function to the +\gls{glossaries-extra} package's \xtrgloskey{category} key, which is +also defined as a storage key: +\begin{alltt} +\cs{glsaddstoragekey}\mgroup{category}\mgroup{general}\mgroup{\ics*{glscategory}} +\end{alltt} + +\glsxtrnote +This document is much simpler with the \gls{glossaries-extra} +package: +\begin{alltt} +\cs{documentclass}\mgroup{article} +\cs{usepackage}[\xtrfont{postdot}]\mgroup{\strong{glossaries-extra}} +\cs{makeglossaries} +\ics*{setabbreviationstyle}[\strong{acronym}]\mgroup{short-long} +\ics{newacronym}\mgroup{radar}\mgroup{radar}\mgroup{radio detecting and ranging} +\ics{newacronym}\mgroup{laser}\mgroup{laser}\mgroup{light amplification by stimulated +emission of radiation} +\ics{newacronym}\mgroup{scuba}\mgroup{scuba}\mgroup{self-contained underwater breathing +apparatus} -\newglossaryentry{sample1}{name={sample1},description={an example}, -user1={FOO}} -\newglossaryentry{sample2}{name={sample2},description={an example}, -user1={\foo}} +\ics*{newabbreviation}\mgroup{dsp}\mgroup{DSP}\mgroup{digital signal processing} +\ics*{newabbreviation}\mgroup{atm}\mgroup{ATM}\mgroup{automated teller machine} -\begin{document} -\ifglsfieldeq{sample1}{useri}{FOO}{TRUE}{FALSE}. +\cs{begin}\mgroup{document} -\ifglsfieldeq{sample2}{useri}{FOO}{TRUE}{FALSE}. -\end{document} -\end{verbatim} -This will produce \qt{TRUE} in both cases since expansion is on, so -\cs{foo} was expanded to \qt{FOO} when \texttt{sample2} was defined. -If the tests are changed to: -\begin{verbatim} -\ifglsfieldeq{sample1}{useri}{\foo}{TRUE}{FALSE}. +First use: \cs{gls}\mgroup{radar}, \cs{gls}\mgroup{laser}, \cs{gls}\mgroup{scuba}, \cs{gls}\mgroup{dsp}, +\cs{gls}\mgroup{atm}. -\ifglsfieldeq{sample2}{useri}{\foo}{TRUE}{FALSE}. -\end{verbatim} -then this will produce \qt{FALSE} in both cases. Now suppose -expansion is switched off for the \gloskey{user1} key: -\begin{verbatim} -\documentclass{article} +Next use: \cs{gls}\mgroup{radar}, \cs{gls}\mgroup{laser}, \cs{gls}\mgroup{scuba}, \cs{gls}\mgroup{dsp}, +\cs{gls}\mgroup{atm}. -\usepackage{glossaries} +\cs{printglossaries} +\cs{end}\mgroup{document} +\end{alltt} -\newcommand*{\foo}{FOO} +\exitem{-storage-abbr-desc} An extension of the previous example +where the user needs to provide a~description. -\glssetnoexpandfield{useri} +\exitem{-chap-hyperfirst} This document illustrates how to add +a~custom key using \cs{glsaddstoragekey} and hook into the \glslike\ +and \glstextlike\ mechanism used to determine whether or not to +hyperlink an entry. +The document build is: +\begin{prompt} +pdflatex sample-chap-hyperfirst +makeglossaries sample-chap-hyperfirst +pdflatex sample-chap-hyperfirst +\end{prompt} +This example creates a storage key called \texttt{chapter} used to store the chapter +number. +\begin{alltt} +\ics{glsaddstoragekey}\mgroup{\strong{chapter}}\mgroup{0}\mgroup{\strong{\cs{glschapnum}}} +\end{alltt} +It's initialised to 0 and the \ics{glslinkpostsetkeys} hook is used +to check this value against the current chapter number. If the +values are the same then the hyperlink is switched off, otherwise +the key value is updated unless the hyperlink has been switched off +(through the optional argument of commands like \cs{gls} and \cs{glstext}). +\begin{alltt} +\cs{renewcommand}*\mgroup{\ics{glslinkpostsetkeys}}\mgroup{\% + \cs{edef}\cs{currentchap}\mgroup{\cs{arabic}\mgroup{chapter}}\% + \cs{ifnum}\cs{currentchap}=\strong{\cs{glschapnum}}\mgroup{\cs{glslabel}}\cs{relax} + \cs{setkeys}\mgroup{glslink}\mgroup{hyper=false}\% + \cs{else} + \ics{glsifhyperon}\mgroup{\ics{glsfieldxdef}\mgroup{\cs{glslabel}}\mgroup{\strong{chapter}}\mgroup{\cs{currentchap}}}\mgroup{}\% + \cs{fi} +} +\end{alltt} +Since this key isn't intended for use when the entry is being +defined, it would be more appropriate to simply use an internal +field that doesn't have an associated key or helper command, but +\ics{glsfieldxdef} requires the existence of the field. The +\gls{glossaries-extra} package provides utility commands designed to +work on internal fields that don't have an associated key and may +not have had a value assigned. + +\glsxtrnote +If you want to switch to \gls{glossaries-extra} you need to change +the package loading line: +\begin{alltt} +\cs{usepackage}[\xtrfont{postdot}]\mgroup{\strong{glossaries-extra}} +\end{alltt} +The custom storage key (provided with \cs{glsaddstoragekey}) can be +removed, and the \ics{glslinkpostsetkeys} hook can be changed to: +\begin{alltt} +\cs{renewcommand}*\mgroup{\ics{glslinkpostsetkeys}}\mgroup{\% + \cs{edef}\cs{currentchap}\mgroup{\cs{arabic}\mgroup{chapter}}\% + \strong{\ics*{GlsXtrIfFieldEqNum}*}\mgroup{\strong{chapter}}\mgroup{\cs{glslabel}}\mgroup{\cs{currentchap}} + \mgroup{\% + \cs{setkeys}\mgroup{glslink}\mgroup{hyper=false}\% + }\% + \mgroup{% + \ics{glsifhyperon}\mgroup{\strong{\ics*{xGlsXtrSetField}}\mgroup{\cs{glslabel}}\mgroup{\strong{chapter}}\mgroup{\cs{currentchap}}}\mgroup{}\% + }% +} +\end{alltt} +The field name is still called \texttt{chapter} but there's no +longer an associated key or command. -\newglossaryentry{sample1}{name={sample1},description={an example}, -user1={FOO}} -\newglossaryentry{sample2}{name={sample2},description={an example}, -user1={\foo}} +\section{Xindy (Option 3)} +\label{sec:samplesxindy} -\begin{document} -\ifglsfieldeq{sample1}{useri}{FOO}{TRUE}{FALSE}. +Most of the earlier \gls{makeindex} sample files can be adapted to +use \gls{xindy} instead by adding the \pkgopt{xindy} package option. +Situations that you need to be careful about are when the sort value +(obtained from the \gloskey{name} if the \gloskey{sort} key is +omitted) contains commands (such as \verb|name={\pi}|) or is identical +to another value (or is identical after \gls{xindy} has stripped all +commands and braces). This section describes sample documents that +use features which are unavailable with \gls{makeindex}. -\ifglsfieldeq{sample2}{useri}{FOO}{TRUE}{FALSE}. -\end{document} -\end{verbatim} -This now produces \qt{TRUE} for the first case (comparing \qt{FOO} -with \qt{FOO}) and \qt{FALSE} for the second case (comparing -\qt{\cs{foo}} with \qt{FOO}). +\exitem{xdy} The document uses UTF8 encoding (with the +\sty{inputenc} package). This is information that needs to be passed +to \gls{xindy}, so the encoding is picked up by \gls{makeglossaries} +from the \filetype{aux} file. -The reverse happens in the following: +By default, this document will create a \gls{xindy} style file called +\nolinkurl{samplexdy.xdy}, but if you uncomment the lines \begin{verbatim} -\documentclass{article} - -\usepackage{glossaries} +\setStyleFile{samplexdy-mc} +\noist +\GlsSetXdyLanguage{} +\end{verbatim} +it will set the style file to \texttt{samplexdy-mc.xdy} instead. +This provides an additional letter group for entries starting with +\qt{Mc} or \qt{Mac}. If you use \gls{makeglossaries} or +\gls{makeglossaries-lite.lua}, you don't +need to supply any additional information. If you don't use +\gls*{makeglossaries}, you will need to specify the required +information. Note that if you set the style file to +\nolinkurl{samplexdy-mc.xdy} you must also specify \ics{noist}, +otherwise the \styfmt{glossaries} package will overwrite +\nolinkurl{samplexdy-mc.xdy} and you will lose the \qt{Mc} letter +group. -\newcommand*{\foo}{FOO} +To create the document do: +\begin{prompt} +pdflatex samplexdy +makeglossaries samplexdy +pdflatex samplexdy +\end{prompt} +If you don't have Perl installed then you can't use +\gls{makeglossaries}, but you also can't use \gls{xindy}! +However, if for some reason you want to call +\gls{xindy} explicitly instead of using \gls{makeglossaries} (or +\gls{makeglossaries-lite.lua}): +\begin{itemize} +\item if you are using the default style file \nolinkurl{samplexdy.xdy}, then +do (no line breaks): +\begin{prompt} +xindy -L english -C utf8 -I xindy -M samplexdy -t samplexdy.glg -o samplexdy.gls samplexdy.glo +\end{prompt} +\item if you are using \nolinkurl{samplexdy-mc.xdy}, then do +(no line breaks): +\begin{prompt} +xindy -I xindy -M samplexdy-mc -t samplexdy.glg -o samplexdy.gls samplexdy.glo +\end{prompt} +\end{itemize} -\glssetnoexpandfield{useri} +This document creates a new command to use with the +\gloskey[glslink]{format} key in the optional argument of commands +like \cs{gls} to format the location in the \gls{numberlist}. +The usual type of definition when a hyperlinked location is required +should use one of the \csmeta{hyper}{xx}{} commands listed in +\tableref{tab:hyperxx}: +\begin{verbatim} +\newcommand*{\hyperbfit}[1]{\textit{\hyperbf{#1}}} +\end{verbatim} +Unfortunately, this definition doesn't work for this particular +document and some adjustments are needed (see below). As a result of +the adjustments, this command doesn't actually get used by \TeX, +even though \texttt{hyperbfit} is used in the +\gloskey[glslink]{format} key. It does, however, need to be +identified as an attribute so that \gls{xindy} can recognise it: +\begin{verbatim} +\GlsAddXdyAttribute{hyperbfit} +\end{verbatim} +This will add information to the \filetype{xdy} file when it's +created by \cs{makeglossaries}. If you prevent the creation of this +file with \ics{noist} then you will need to add the attribute to +your custom \filetype{xdy} file (see the provided +\nolinkurl{samplexdy-mc.xdy} file). -\newglossaryentry{sample1}{name={sample1},description={an example}, -user1={FOO}} -\newglossaryentry{sample2}{name={sample2},description={an example}, -user1={\foo}} +In order to illustrate unusual location formats, this sample +document provides a command called \cs{tallynum}\marg{n} that represents its +numerical argument with a die or dice where the dots add up to \meta{n}: +\begin{verbatim} +\newrobustcmd*{\tallynum}[1]{% + \ifnum\number#1<7 + $\csname dice\romannumeral#1\endcsname$% + \else + $\dicevi$% + \expandafter\tallynum\expandafter{\numexpr#1-6}% + \fi +} +\end{verbatim} +This command needs to be robust to prevent it from being expanded +when it's written to any of the auxiliary files. The \ics{dicei}, +\ldots, \cs{dicevi} commands are provided by the \sty{stix} +package, so that needs to be loaded. -\begin{document} -\ifglsfieldeq{sample1}{useri}{\foo}{TRUE}{FALSE}. +An associated command \cs{tally}\marg{counter} is defined that +formats the value of the named \meta{counter} according to +\cs{tallynum}: +\begin{verbatim} +\newcommand*{\tally}[1]{\tallynum{\arabic{#1}}} +\end{verbatim} +(This shouldn't be robust as it needs the counter value to expand.) +The page numbers are altered to use this format (by redefining \ics{thepage}). -\ifglsfieldeq{sample2}{useri}{\foo}{TRUE}{FALSE}. -\end{document} +This custom location format also needs to be identified in the +\filetype{xdy} file so that \gls{xindy} can recognise it and +determine how to form ranges if required. +\begin{verbatim} +\GlsAddXdyLocation{tally}{% tally location format + :sep "\string\tallynum\space\glsopenbrace" + "arabic-numbers" + :sep "\glsclosebrace" +} \end{verbatim} -This now produces \qt{FALSE} for the first case (comparing \qt{FOO} -with \qt{\cs{foo}}) and \qt{TRUE} for the second case (comparing -\qt{\cs{foo}} with \qt{\cs{foo}}). +Again this information is written to the \filetype{xdy} file by +\cs{makeglossaries} so if you use \cs{noist} then you need to +manually add it to your custom \filetype{xdy} file. -You can test if the value of a field is equal to the replacement -text of a command using: -\begin{definition}[\DescribeMacro\ifglsfielddefeq] -\cs{ifglsfielddefeq}\marg{label}\marg{field}\marg{command}\marg{true}\marg{false} -\end{definition} -This internally uses \sty{etoolbox}'s \cs{ifdefstrequal} command to -perform the comparison. The argument \meta{command} must be a macro. +When \gls{xindy} creates the associated glossary files, the +locations will be written using: +\begin{alltt} +\csmetameta{glsX}{counter}{X}{format}{}\marg{hyper-prefix}\marg{location} +\end{alltt} +In this case: +\begin{alltt} +\cs{glsXpageXglsnumberformat}\mgroup{}\mgroup{\cs{tallynum}\marg{number}} +\end{alltt} +or +\begin{alltt} +\cs{glsXpageXhyperbfit}\mgroup{}\mgroup{\cs{tallynum}\marg{number}} +\end{alltt} +This means that although \cs{hyperbf} is designed to create +hyperlinked locations, the presence of \cs{tallynum} interferes with +it. +In order to make the hyperlinks work correctly, the definitions of +\cs{glsXpageXhyperbfit} need to be redefined in order to grab the +number part in order to work out the location's numeric value. If +the value of \cs{tally} is changed so that it expands differently +then these modifications won't work. + +Remember that in both cases, the second argument \verb|#2| is in the +form \cs{tally}\marg{n}: +\begin{verbatim} +\renewcommand{\glsXpageXglsnumberformat}[2]{% + \linkpagenumber#2% +} +\renewcommand{\glsXpageXhyperbfit}[2]{% + \textbf{\em\linkpagenumber#2}% +} +\end{verbatim} +These need a command that can grab the actual number and correctly encapsulate +it: +\begin{verbatim} +\newcommand{\linkpagenumber}[2]{\hyperlink{page.#2}{#1{#2}}} +\end{verbatim} -For example: +If you want to try out the \nolinkurl{samplexdy-mc.xdy} file, the +entries starting with \qt{Mac} or \qt{Mc} will be placed in their +own \qt{Mc} letter group. Ideally it should be possible to do this +simply with \ics{GlsAddLetterGroup} (and not require a custom +\filetype{xdy} file) but unfortunately the \qt{M} letter +group will have already been defined and take precedence over +\qt{Mc}, which is why a custom file is required and the normal +language module must be suppressed: \begin{verbatim} -\documentclass{article} +\setStyleFile{samplexdy-mc} +\noist +\GlsSetXdyLanguage{} +\end{verbatim} -\usepackage{glossaries} +This \qt{Mc} group is suitable for names like +\qt{Maclaurin} but not for \qt{Mach}. To prevent this, the +\gloskey{sort} key for that value is set to lower case: +\begin{verbatim} +\newglossaryentry{mach}{name={Mach, Ernst}, +first={Ernst Mach},text={Mach}, +sort={mach, Ernst}, +description={Czech/Austrian physicist and philosopher}} +\end{verbatim} -\newcommand*{\foo}{FOO} +\bibglsnote +If you want to convert this document so that it uses \gls{bib2gls}, +you first need to switch to \gls{glossaries-extra} and use the +\pkgopt*{record} package option: +\begin{alltt} +\cs{usepackage}[\strong{\xtrfont{record}},\xtrfont{postdot}]\mgroup{\strong{glossaries-extra}} +\end{alltt} +The \gls{xindy}-only commands can now all be removed +(attribute \cs{GlsAddXdyAttribute}, location \cs{GlsAddXdyLocation}, +language \cs{GlsSetXdyLanguage}, location encapsulators +\csmetameta{glsX}{counter}{X}{format}{} +and the custom helper \cs{linkpagenumber}). +Also \cs{noist} and \cs{setStyleFile} aren't relevant with +\gls{bib2gls} and so should be removed. + +The definitions of \cs{hyperbfit} should be retained (as well as +\cs{tallynum}, \cs{tally} and the redefinition of \cs{thepage}). + +The entries all need to be converted to the \filetype{bib} format +required by \gls{bib2gls}. +\begin{prompt} +convertgls2bib -{}-preamble-only samplexdy.tex entries.bib +\end{prompt} +Next replace \cs{makeglossaries} with: +\begin{alltt} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=entries] +\end{alltt} +and remove all the entry definitions from the preamble. Use the +search and replace function on your text editor to replace all +instances of \ics{glsentryfirst} with \ics*{glsfmtfirst}, and all +instances of \ics{glsentryname} with \ics*{glsfmtname}. -\glssetnoexpandfield{useri} +Finally, replace \ics{printglossaries} with \ics*{printunsrtglossaries}. +The document build is now: +\begin{prompt} +pdflatex samplexdy +bib2gls -{}-group samplexdy +pdflatex samplexdy +\end{prompt} -\newglossaryentry{sample1}{name={sample1},description={an example}, -user1={FOO}} -\newglossaryentry{sample2}{name={sample2},description={an example}, -user1={\foo}} +This results in a slightly different ordering from the original +document (without the \qt{Mc} letter group). In the original +example, \qt{Mach number} was listed before \qt{Mach, Ernest}. The +modified document now has \qt{Mach, Ernest} before \qt{Mach number}. +This difference is due to \gls{bib2gls}['s] default +\resourceopt[word]{break-at} setting, which marks word boundaries +with the pipe (\texttt{|}) character, so the sort values for +\gls{bib2gls} are \texttt{Mach|Earnest|} and \texttt{Mach|number|}. +See the \gls{bib2gls} manual for further details of this option, and +also see the examples chapter of that manual for alternative +approaches when creating entries that contain people's names. + +If you want the \qt{Mc} letter group, it can be obtained by +providing a custom sort rule: +\begin{alltt} +\ics*{GlsXtrLoadResources}[\resourceopt{src}=entries, + \resourceopt{sort}=\strong{custom}, + \strong{\xtrfont{sort-rule}}=\mgroup{\ics*{glsxtrcontrolrules} + ;\ics*{glsxtrspacerules};\ics*{glsxtrnonprintablerules} + ;\ics*{glsxtrcombiningdiacriticrules},\ics*{glsxtrhyphenrules} + <\ics*{glsxtrgeneralpuncrules}<\ics*{glsxtrdigitrules} + > BDC + BT + /F8 9.9626 Tf + 73.102 697.123 Td + [ (Dr) ] TJ + ET +EMC +\end{verbatim} +This shows that \qt{ActualText} was used for \verb|\gls{Doctor}|. +The integral symbol ($\int$) created with \verb|\glssymbol{int}| is: +\begin{verbatim} +/Span << /ActualText (\376\377"+) >> BDC + BT + /F1 9.9626 Tf + 97.732 650.382 Td + [ (R) ] TJ + ET +EMC +\end{verbatim} +Again, \qt{ActualText} has been used, but the character code has +been supplied. The image created with \verb|\glsuseri{sampleimage}| is: +\begin{verbatim} +/Span << /Alt (a boilerplate image used in examples) >> BDC + 1 0 0 1 106.588 618.391 cm + q + 0.08301 0 0 0.08301 0 0 cm + q + 1 0 0 1 0 0 cm + /Im1 Do + Q + Q +EMC +\end{verbatim} +This shows that \qt{Alt} has been used. + +The first use of \verb|\gls{eg}| produces the long form (not +reproduced here) followed by the short form: +\begin{verbatim} +/Span << /E (for example) >> BDC + BT + /F8 9.9626 Tf + 161.687 563.624 Td + [ (e.g.) ] TJ + ET +EMC +\end{verbatim} +The subsequent use also has the \qt{E} element: +\begin{verbatim} +/Span << /E (for example) >> BDC + BT + /F8 9.9626 Tf + 118.543 551.669 Td + [ (e.g.) ] TJ + ET +EMC +\end{verbatim} +Similarly for \verb|\acrshort{eg}|. You can also use the +\pkgopt[showaccsupp]{debug} package option. This will show the +replacement text in the document, but note that this is the content before +it's processed by \cs{BeginAccSupp}. + +If the \ics{setacronymstyle} command is removed (or commented out) +then the result would be different. The \gls{firstuse} of \cs{gls} uses \qt{E} for +the short form but the subsequent use has \qt{ActualText} instead. +This is because without \ics{setacronymstyle} the original acronym +mechanism is used, which is less sophisticated than the newer +acronym mechanism that's triggered with \ics{setacronymstyle}. -\item[{\gloskey{descriptionpluralaccess}}] The replacement text corresponding -to the \gloskey{descriptionplural} key. +\begin{important} +If you want to convert this example so that it uses +\gls{glossaries-extra}, make sure you have at least version 1.42 of +the extension package. +\end{important} -\item[{\gloskey{longaccess}}] The replacement text corresponding to -the \gloskey{long} key (used by \ics{newacronym}). +\glsxtrnote +If you want to convert this example so that it uses +\gls{glossaries-extra}, you need to replace the explicit loading of +\sty{glossaries-accsupp} with an implicit load through the +\pkgopt*{accsupp} package option: +\begin{alltt} +\cs{usepackage}[\xtrfont{abbreviations},\strong{\xtrfont{accsupp}}]\mgroup{\strong{glossaries-extra}} +\end{alltt} +I'm switching from \ics{newacronym} to \ics*{newabbreviation}, which +means that the default category is \cat{abbreviation} and also the +file extensions are different. If you are using \gls{makeglossaries} +or \gls{makeglossaries-lite.lua} you don't need to worry about it. +However, if you're not using those helper scripts then you will need +to adjust the file extensions in your document build process. + +The style command \texttt{\cs{setacronymstyle}\mgroup{long-short}} needs +to be replaced with: +\begin{alltt} +\ics{setabbreviationstyle}\mgroup{long-short} +\end{alltt} +This is actually the default so you can simply delete the +\cs{setacronymstyle} line. Substitute the two instances of +\ics{newacronym} with \ics*{newabbreviation}. For example: +\begin{alltt} +\strong{\ics*{newabbreviation}}\mgroup{eg}\mgroup{e.g.}\mgroup{for example} +\end{alltt} +Note that for the \texttt{tikz} entry you can now remove the explicit assignment of +\gloskey{shortaccess} with \gls{glossaries-extra} v1.42 as it will +strip formatting commands like \cs{emph}: +\begin{alltt} +\ics*{newabbreviation} + \mgroup{tikz}\mgroup{Ti\cs{emph}\mgroup{k}Z}\mgroup{Ti\cs{emph}\mgroup{k}Z ist \cs{emph}\mgroup{kein} Zeichenprogramm} +\end{alltt} +It's also necessary to replace \cs{acrshort}, \cs{acrlong} and \cs{acrfull} with +\ics*{glsxtrshort}, \ics*{glsxtrlong} and \ics*{glsxtrfull}. + +You may notice a slight difference from the original example. The +\gloskey{shortaccess} field now shows \meta{long} (\meta{short}) +instead of just \meta{long}. This is because \gls{glossaries-extra} +redefines \ics{glsdefaultshortaccess} to include the short form. + +Now that the extension package is being used, there are some other +modifications that would tidy up the code and fix a few issues. + +The \qt{Doctor} and \qt{Drive} entries should really be defined as +abbreviations but they shouldn't be expanded on first use. The +\abbrstyle{short-nolong} style can achieve this and it happens to be +the default style for the \cat{acronym} category. This means that +you can simply replace the \qt{Doctor} definition with: +\begin{alltt} +\ics{newacronym}\mgroup{Doctor}\mgroup{Dr}\mgroup{Doctor} +\end{alltt} +The \gls{firstuse} of \verb|\gls{Doctor}| is just \qt{Dr}. This +means that the \qt{E} element will be used instead of \qt{ActualText}. +Now I don't need to supply the accessibility text as its obtained +from the long form. + +The \qt{Drive} entry can be similarly defined but it has the awkward +terminating full stop. This means that I had to omit the end of +sentence terminator in: +\begin{verbatim} +\gls{Doctor} Smith lives at 2, Blueberry \gls{Drive} +\end{verbatim} +This looks odd when reading the document source and it's easy to +forgot. This is very similar to the situation in the +\samplefile{-dot-abbr} example. I can again use the +\attr{discardperiod} attribute, but I need to assign a different +category so that it doesn't interfere with the \qt{Doctor} entry. + +The category is simply a label that's used in the construction of +some internal command names. This means that it must be fully +expandable, but I can choose whatever label I like (\cat{general}, +\cat{abbreviation}, \cat{acronym}, \cat{index}, \cat{symbol} and +\cat{number} are used by various commands provided by +\gls{glossaries-extra}). + +In this case, I've decided to have a category called \texttt{shortdotted} +to indicate an abbreviation that ends with a +dot but only the short form is shown on \gls{firstuse}: +\begin{alltt} +\ics*{setabbreviationstyle}[shortdotted]\mgroup{short-nolong-noreg} +\ics*{glssetcategoryattribute}\mgroup{shortdotted}\mgroup{discardperiod}\mgroup{true} +\ics*{newabbreviation}[category=shortdotted]\mgroup{Drive}\mgroup{Dr.\cs{@}}\mgroup{Drive} +\end{alltt} +In the \samplefile{-dot-abbr} example, I also used the +\attr{insertdots} attribute to automatically insert the dots and add +the space factor (which is adjusted if \attr{discardperiod} discards +a period). In this case I'm inserting the dot manually so I've also +added the space factor with \ics{@} in case the abbreviation is used +mid-sentence. For example: +\begin{verbatim} +\gls{Doctor} Smith lives at 2, Blueberry \gls{Drive}. Next sentence. + +\gls{Doctor} Smith lives at 2, Blueberry \gls{Drive} end of sentence. +\end{verbatim} +(The spacing is more noticeable if you first switch to a monospaced +font with \cs{ttfamily}.) + +The \qt{e.g.}\ abbreviation similarly ends with a dot. It's not +usual to write \qt{for example (e.g.)}\ in a document, so it really +ought to have the same \texttt{shortdotted} category, but it has a +long-short form for illustrative purposes in this test document. In +this case I need to choose another category so that I can apply a +different style. For example: +\begin{alltt} +\ics*{setabbreviationstyle}[longshortdotted]\mgroup{long-short} +\ics*{glssetcategoryattribute}\mgroup{longshortdotted}\mgroup{discardperiod}\mgroup{true} +\ics*{newabbreviation}[category=longshortdotted]\mgroup{e.g.}\mgroup{e.g.\cs{@}}\mgroup{for +example} +\end{alltt} -\item[{\gloskey{shortaccess}}] The replacement text corresponding to -the \gloskey{short} key (used by \ics{newacronym}). +To further illustrate categories, let's suppose the symbol and image +should be in the \gloskey{name} field instead of the +\gloskey{symbol} and \gloskey{user1} fields. Now the +\cs{glssymbolaccsupp} and \cs{glsuseriaccsupp} commands won't be +used. I can't deal with both cases if I just provide +\cs{glsnameaccsupp}. + +I could provide category-field versions, such as +\xtrfont{\cs{glsxtrsymbolnameaccsupp}}, but remember that this only covers +accessing the \gloskey{name} field, which is typically only done in +the glossary. I would also need similar commands for the +\gloskey{first}, \gloskey{firstplural}, \gloskey{text} and +\gloskey{plural} keys. This is quite complicated, but since I don't +need to worry about any of the other fields it's simpler to just +provide the \csmeta*{glsxtr}{category}{accsupp} version: +\begin{alltt} +\cs{newcommand}\mgroup{\xtrfont{\cs{glsxtr\strong{symbol}accsupp}}}[2]\mgroup{\% + \ics{glsaccessibility}[method=hex,unicode]\mgroup{ActualText}\mgroup{\#1}\mgroup{#2}\% +} +\cs{newcommand}\mgroup{\xtrfont{\cs{glsxtr\strong{image}accsupp}}}[2]\mgroup{\% + \ics{glsaccessibility}\mgroup{Alt}\mgroup{\#1}\mgroup{\#2}\% +} -\item[{\gloskey{longpluralaccess}}] The replacement text corresponding to -the \gloskey{longplural} key (used by \ics{newacronym}). +\cs{newglossaryentry}\mgroup{int}\mgroup{\strong{\xtrfont{category}=symbol}, + \strong{name}=\mgroup{\cs{ensuremath}\mgroup{\cs{int}}},\strong{access}=\mgroup{222B}, + description=\mgroup{integral} +} -\item[{\gloskey{shortpluralaccess}}] The replacement text corresponding to -the \gloskey{shortplural} key (used by \ics{newacronym}). +\cs{newglossaryentry}\mgroup{sampleimage}\mgroup{\strong{\xtrfont{category}=image}, + description=\mgroup{an example image}, + \strong{name}=\mgroup{\cs{protect}\cs{includegraphics}[height=20pt]\mgroup{example-image}}, + \strong{access}=\mgroup{a boilerplate image used in examples} +} +\end{alltt} +If it's necessary to provide support for additional fields, then the +category-field command \csmetameta*{glsxtr}{category}{}{field}{accsupp} could be used to +override the more general category command \csmeta*{glsxtr}{category}{accsupp}. -\end{description} -For example: -\begin{verbatim} -\newglossaryentry{tex}{name={\TeX},description={Document -preparation language},access={TeX}} -\end{verbatim} -Now \verb|\gls{tex}| will be equivalent to +\exitem{-ignored} This document defines an ignored glossary for +common terms that don't need a definition. The document build is: +\begin{prompt} +pdflatex sample-ignored +makeglossaries sample-ignored +pdflatex sample-ignored +\end{prompt} +A new \qt{ignored} glossary is defined with: +\begin{alltt} +\ics{newignoredglossary}\mgroup{common} +\end{alltt} +There are no associated files with an ignored glossary. An entry is defined with +this as its glossary type: \begin{verbatim} -\BeginAccSupp{ActualText=TeX}\TeX\EndAccSupp{} +\newglossaryentry{commonex}{type=common,name={common term}} \end{verbatim} -The sample file \samplefile{accsupp} illustrates the -\sty{glossaries-accsupp} package. +Note that the \gloskey{description} key isn't required. This term +may be referenced with \cs{gls} (which is useful for consistent +formatting) but it won't be indexed. -See \ifpdf section~\ref*{sec:code:accsupp} in \fi the documented code -(\texttt{glossaries-code.pdf}) for further details. I~recommend -that you also read the \sty{accsupp} documentation. +\exitem{-entrycount} This document uses \ics{glsenableentrycount} +and \ics{cgls} (described in \sectionref{sec:enableentrycount}) +so that acronyms only used once don't appear in the list of +acronyms. The document build is: +\begin{prompt} +pdflatex sample-entrycount +pdflatex sample-entrycount +makeglossaries sample-entrycount +pdflatex sample-entrycount +\end{prompt} +Note the need to call \LaTeX\ twice before \gls{makeglossaries}, and +then a final \LaTeX\ call is required at the end. + +\begin{xtr} +The \gls{glossaries-extra} package has additions that extend this +mechanism and comes with some other sample files related to entry counting. +\end{xtr} + +\begin{bib2gls} +If you switch to \gls{bib2gls} you can use record counting instead. +See the \gls{bib2gls} manual for further details. +\end{bib2gls} \chapter{Troubleshooting} \label{sec:trouble} diff --git a/macros/latex/contrib/glossaries/glossaries.dtx b/macros/latex/contrib/glossaries/glossaries.dtx index 37f589e208..bd6811d320 100644 --- a/macros/latex/contrib/glossaries/glossaries.dtx +++ b/macros/latex/contrib/glossaries/glossaries.dtx @@ -1,11 +1,11 @@ %\iffalse % glossaries.dtx generated using makedtx version 1.2 (c) Nicola Talbot % Command line args: -% -codetitle "Main Package Code" -% -doc "glossaries-manual.tex" % -section "chapter" -% -setambles ".*\.perl=>\nopreamble\nopostamble" -% -setambles ".*\.tex=>\nopreamble\nopostamble" +% -macrocode ".*\.perl" +% -macrocode ".*\.tex" +% -doc "glossaries-manual.tex" +% -codetitle "Main Package Code" % -author "Nicola Talbot" % -src "glossaries\.sty\Z=>glossaries.sty" % -src "glossaries-prefix.sty\Z=>glossaries-prefix.sty" @@ -17,12 +17,12 @@ % -src "(glossaries-polyglossia)\.(sty)\Z=>\1.\2" % -src "(example-glossaries-.*\.tex)\Z=>\1" % -src "(.*\.perl)\Z=>\1" -% -macrocode ".*\.perl" -% -macrocode ".*\.tex" % -comment ".*\.perl" % -comment ".*\.tex" +% -setambles ".*\.perl=>\nopreamble\nopostamble" +% -setambles ".*\.tex=>\nopreamble\nopostamble" % glossaries -% Created on 2019/12/6 14:57 +% Created on 2020/2/14 0:32 %\fi %\iffalse %<*package> @@ -45,7 +45,7 @@ %\fi % \iffalse % Doc-Source file to use with LaTeX2e -% Copyright (C) 2019 Nicola Talbot, all rights reserved. +% Copyright (C) 2020 Nicola Talbot, all rights reserved. % \fi % \iffalse %<*driver> @@ -68,7 +68,7 @@ glossaries.dtx pdfauthor={Nicola L.C. Talbot}, pdftitle={glossaries.sty: LaTeX2e Package to Assist Generating Glossaries}, pdfkeywords={LaTeX,package,glossary,acronyms}]{hyperref} -\usepackage[toc]{glossaries} +\usepackage{glossaries-extra} \RecordChanges \setlength\IndexMin{100pt} @@ -136,7 +136,7 @@ governed by the \gloskey{first} and \gloskey{firstplural} keys of \setcounter{IndexColumns}{2} -\CheckSum{19669} +\CheckSum{20333} \newcommand*{\ifirstuse}{\iterm{first use}} \newcommand*{\firstuse}{\gls{firstuse}} @@ -163,12 +163,12 @@ governed by the \gloskey{first} and \gloskey{firstplural} keys of %\fi %\MakeShortVerb{"} % -% \title{Documented Code For glossaries v4.44} +% \title{Documented Code For glossaries v4.45} % \author{Nicola L.C. Talbot\\[10pt] %Dickimaw Books\\ %\url{http://www.dickimaw-books.com/}} % -% \date{2019-12-06} +% \date{2020-02-13} % \maketitle % %This is the documented code for the \styfmt{glossaries} package. @@ -184,7 +184,7 @@ governed by the \gloskey{first} and \gloskey{firstplural} keys of %glossaries package}. % %\item[\url{glossaries-user.pdf}] -%For the main user guide, read \qt{glossaries.sty v4.44: +%For the main user guide, read \qt{glossaries.sty v4.45: %\LaTeX2e\ Package to Assist Generating Glossaries}. % %\item[\url{mfirstuc-manual.pdf}] @@ -199,7 +199,7 @@ governed by the \gloskey{first} and \gloskey{firstplural} keys of % %\item[CHANGES] Change log. % -%\item[README] Package summary. +%\item[README.md] Package summary. % %\end{description} % @@ -239,7 +239,7 @@ governed by the \gloskey{first} and \gloskey{firstplural} keys of % This package requires \LaTeXe. % \begin{macrocode} \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{glossaries}[2019/12/06 v4.44 (NLCT)] +\ProvidesPackage{glossaries}[2020/02/13 v4.45 (NLCT)] % \end{macrocode} %\changes{4.18}{2015-09-09}{split mfirstuc into separate bundle} % Required packages: @@ -339,13 +339,15 @@ governed by the \gloskey{first} and \gloskey{firstplural} keys of %\changes{4.24}{2016-05-27}{new} % Switch on debug mode. This will also cancel the \pkgopt{nowarn} % option. This is now a choice key. +%\changes{4.45}{2020-02-13}{added debug=showaccsupp} %\changes{4.41}{2018-07-23}{changed \cs{val} and \cs{nr} to %\cs{gls@debug@val} and \cs{gls@debug@nr}} % \begin{macrocode} \newif\if@gls@debug \define@choicekey{glossaries.sty}{debug}[\gls@debug@val\gls@debug@nr]% - {true,false,showtargets}[true]{% + {true,false,showtargets,showaccsupp}[true]{% \ifcase\gls@debug@nr\relax + % debug=true \@gls@debugtrue \renewcommand*{\GlossariesWarning}[1]{% \PackageWarning{glossaries}{##1}% @@ -356,10 +358,24 @@ governed by the \gloskey{first} and \gloskey{firstplural} keys of \let\@glsshowtarget\@gobble \PackageInfo{glossaries}{debug mode ON (nowarn option disabled)}% \or + % debug=false \@gls@debugfalse \let\@glsshowtarget\@gobble + \let\@glsshowaccsupp\@gobblethree \PackageInfo{glossaries}{debug mode OFF}% \or + % debug=showtargets + \@gls@debugtrue + \renewcommand*{\GlossariesWarning}[1]{% + \PackageWarning{glossaries}{##1}% + }% + \renewcommand*{\GlossariesWarningNoLine}[1]{% + \PackageWarningNoLine{glossaries}{##1}% + }% + \PackageInfo{glossaries}{debug mode ON (nowarn option disabled)}% + \renewcommand{\@glsshowtarget}{\@@glsshowtarget}% + \or + % debug=showaccsupp \@gls@debugtrue \renewcommand*{\GlossariesWarning}[1]{% \PackageWarning{glossaries}{##1}% @@ -368,7 +384,7 @@ governed by the \gloskey{first} and \gloskey{firstplural} keys of \PackageWarningNoLine{glossaries}{##1}% }% \PackageInfo{glossaries}{debug mode ON (nowarn option disabled)}% - \renewcommand{\@glsshowtarget}{\glsshowtarget}% + \renewcommand{\@glsshowaccsupp}{\glsshowaccsupp}% \fi } % \end{macrocode} @@ -381,17 +397,44 @@ governed by the \gloskey{first} and \gloskey{firstplural} keys of % \begin{macrocode} \newcommand*{\glsshowtarget}[1]{% \ifmmode - \nfss@text{\ttfamily\small [#1]}% + \nfss@text{\glsshowtargetfont [#1]}% \else \ifinner - \texttt{\small [#1]}% +% \end{macrocode} +% Grouping no longer required as new \cs{@@glsshowtarget} adds +% scoping but retained here in case any existing documents are using +% \cs{glsshowtarget} elsewhere. +% \begin{macrocode} + {\glsshowtargetfont [#1]}% \else - \marginpar{\texttt{\small #1}}% + \glsshowtargetouter{#1}% \fi \fi } % \end{macrocode} %\end{macro} +%\begin{macro}{\glsshowtargetouter} +%\changes{4.45}{2020-02-13}{new} +% \begin{macrocode} +\newcommand*{\glsshowtargetouter}[1]{% + \glsshowtargetsymbol\marginpar{\glsshowtargetsymbol\glsshowtargetfont #1}} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\glsshowtargetsymbol} +%\changes{4.45}{2020-02-13}{new} +% \begin{macrocode} +\newcommand*{\glsshowtargetsymbol}{{\tiny$\triangleright$}} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\glsshowtargetfont} +%\changes{4.45}{2020-02-13}{new} +% \begin{macrocode} +\newcommand*{\glsshowtargetfont}{\ttfamily\footnotesize} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\@glsshowtarget} %\changes{4.32}{2017-08-24}{new} %\pkgopt[showtargets]{debug} will redefine this. @@ -400,6 +443,42 @@ governed by the \gloskey{first} and \gloskey{firstplural} keys of % \end{macrocode} %\end{macro} % +%\begin{macro}{\@@glsshowtarget} +%\changes{4.45}{2020-02-13}{new} +%Need to detokenize the label in the event that it contains awkward +%characters like underscores. +% \begin{macrocode} +\newrobustcmd*{\@@glsshowtarget}[1]{% + \begingroup + \protected@edef\@gls@tmp{#1}% + \@onelevel@sanitize\@gls@tmp + \expandafter\glsshowtarget\expandafter{\@gls@tmp}% + \endgroup +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@glsshowaccsupp} +%\changes{4.45}{2020-02-13}{new} +%\pkgopt[showaccsupp]{debug} will redefine this. +% \begin{macrocode} +\newcommand*{\@glsshowaccsupp}[3]{} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\glsshowaccsupp} +%\changes{4.45}{2020-02-13}{new} +%Just use \cs{@@glsshowtarget} since it basically needs to do the +%same thing. +% \begin{macrocode} +\newrobustcmd*{\glsshowaccsupp}[3]{% + \ifstrempty{#1}% + {\@@glsshowtarget{/#2 (#3)}}% + {\@@glsshowtarget{/#2 (#3) [#1]}}% +} +% \end{macrocode} +%\end{macro} +% %Determine what to do if the \gloskey{see} key is used before %\cs{makeglossaries}. The default is to produce an error. %\begin{macro}{\@gls@see@noindex} @@ -1289,7 +1368,10 @@ false,nolabel,autolabel,nameref}[nolabel]{% % \begin{macrocode} \@gls@declareoption{acronyms}{% \glsacronymtrue - \renewcommand{\@gls@do@acronymsdef}{% +% \end{macrocode} +%\changes{4.45}{2020-02-13}{changed \cs{renewcommand} to \cs{def}} +% \begin{macrocode} + \def\@gls@do@acronymsdef{% \DeclareAcronymList{acronym}% \newglossary[alg]{acronym}{acr}{acn}{\acronymname}% \renewcommand*{\acronymtype}{acronym}% @@ -1353,9 +1435,9 @@ false,nolabel,autolabel,nameref}[nolabel]{% % \begin{macrocode} \newcommand{\@gls@islistofacronyms}[4]{% \def\gls@islistofacronyms##1,#1,##2\end@gls@islistofacronyms{% - \def\@before{##1}\def\@after{##2}}% + \def\@gls@before{##1}\def\@gls@after{##2}}% \gls@islistofacronyms,#2,#1,\@nil\end@gls@islistofacronyms - \ifx\@after\@nnil + \ifx\@gls@after\@nnil % \end{macrocode} % Not found % \begin{macrocode} @@ -2243,6 +2325,100 @@ false,nolabel,autolabel,nameref}[nolabel]{% % \end{macrocode} %\end{option} % +%\begin{macro}{\@domakeglossaries} +%\changes{4.45}{2020-02-13}{new} +% \begin{macrocode} +\providecommand{\@domakeglossaries}[1]{#1} +% \end{macrocode} +%\end{macro} +% +%\begin{option}{disablemakegloss} +%\changes{4.45}{2020-02-13}{new} +%Provide a way of disabling \cs{makeglossaries}. For example, if a +%class or package explicitly uses \cs{makeglossaries}. This is a +%valueless option to allow it to be passed through the document +%class option list. +% \begin{macrocode} +\@gls@declareoption{disablemakegloss}{% + \ifdefequal\makeglossaries\@no@makeglossaries + {% + \GlossariesWarning{Option `disablemakegloss' has no effect + (\string\makenoidxglossaries\space has already been used)}% + }% + {% + \ifdefequal\@makeglossary\@gobble + {% + \GlossariesWarning{Option `disablemakegloss' has no effect + (\string\makeglossaries\space has already been used)}% + }% + {% + \renewcommand{\@domakeglossaries}[1]{% + \PackageInfo{glossaries}{\string\makeglossaries\space and + \string\makenoidxglossaries\space have been disabled}% + }% + }% + }% +} +% \end{macrocode} +%\end{option} +%\begin{option}{restoremakegloss} +%\changes{4.45}{2020-02-13}{new} +%Cancel the effect of \pkgopt{disablemakegloss}. +% \begin{macrocode} +\@gls@declareoption{restoremakegloss}{% + \ifdefequal\makeglossaries\@no@makeglossaries + {% + \GlossariesWarning{Option `restoremakegloss' has no effect + (\string\makenoidxglossaries\space has already been used)}% + }% + {% + \ifdefequal\@makeglossary\@gobble + {% + \GlossariesWarning{Option `restoremakegloss' has no effect + (\string\makeglossaries\space has already been used)}% + }% + {% + \PackageInfo{glossaries}{\string\makeglossaries\space and + \string\makenoidxglossaries\space have been restored}% + \let\@domakeglossaries\@firstofone + }% + }% +} +% \end{macrocode} +%\end{option} +% +%\begin{macro}{\@do@write@glslabels} +%\changes{4.45}{2020-02-13}{new} +% \begin{macrocode} +\newcommand*{\@do@write@glslabels}{% + \AtEndDocument{\@@do@write@glslabels}% + \let\@do@write@glslabels\relax +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@@do@write@glslabels} +%\changes{4.45}{2020-02-13}{new} +% \begin{macrocode} +\newcommand*{\@@do@write@glslabels}{% + \newwrite\@gls@labelsfile + \immediate\openout\@gls@labelsfile=\jobname.glslabels + \forallglsentries[\@glo@types,\@ignored@glossaries]{\@glsentry}% + {\ifdefempty{\@glsentry}{}{\immediate\write\@gls@labelsfile{\@glsentry}}}% + \immediate\closeout\@gls@labelsfile +} +% \end{macrocode} +%\end{macro} +% +%\begin{option}{writeglslabels} +%\changes{4.45}{2020-02-13}{new} +%This option will write all entry labels (including those in ignored +%glossaries) to the file \cs{jobname}\texttt{.glslabels}. This file +%may be used by text editors for label auto-completion. +% \begin{macrocode} +\@gls@declareoption{writeglslabels}{\@do@write@glslabels} +% \end{macrocode} +%\end{option} %\begin{macro}{\ifglsautomake} %\changes{4.42}{2019-01-06}{now defined explicitly instead of through %boolean key} @@ -4292,11 +4468,18 @@ false,nolabel,autolabel,nameref}[nolabel]{% %\end{macro} % %\begin{macro}{\ifglshaschildren} -% \cs{ifglshaschildren}\marg{label}\marg{true part}\marg{false part} +%\begin{definition} +%\cs{ifglshaschildren}\marg{label}\marg{true part}\marg{false part} +%\end{definition} +%This is inefficient as it has to search through all entries to find +%out which ones have the given entry as its parent. It's much easier +%to use \app{bib2gls} and get it to store the list of children that +%have been indexed (which is likely to be more useful). %\changes{3.02}{2012-05-21}{new} %\changes{4.03}{2014-01-20}{added \cs{glsdetoklabel}} +%\changes{4.45}{2020-02-13}{made robust} % \begin{macrocode} -\newcommand{\ifglshaschildren}[3]{% +\newrobustcmd{\ifglshaschildren}[3]{% \glsdoifexists{#1}% {% \def\do@glshaschildren{#3}% @@ -4376,8 +4559,9 @@ false,nolabel,autolabel,nameref}[nolabel]{% %\changes{4.03}{2014-01-20}{added \cs{glsdetoklabel}} %\changes{4.03}{2014-01-20}{replaced \cs{ifcsempty} with %\cs{ifdefempty} and replaced \cs{ifx} with \cs{ifdefequal}} +%\changes{4.45}{2020-02-13}{made robust} % \begin{macrocode} -\newcommand*{\ifglshassymbol}[3]{% +\newrobustcmd*{\ifglshassymbol}[3]{% \letcs{\@glo@symbol}{glo@\glsdetoklabel{#1}@symbol}% \ifdefempty\@glo@symbol {#3}% @@ -4394,8 +4578,9 @@ false,nolabel,autolabel,nameref}[nolabel]{% %\cs{ifglshaslong}\marg{label}\marg{true part}\marg{false part} %\changes{3.11a}{2013-10-15}{new} %\changes{4.03}{2014-01-20}{added \cs{glsdetoklabel}} +%\changes{4.45}{2020-02-13}{made robust} % \begin{macrocode} -\newcommand*{\ifglshaslong}[3]{% +\newrobustcmd*{\ifglshaslong}[3]{% \letcs{\@glo@long}{glo@\glsdetoklabel{#1}@long}% \ifdefempty\@glo@long {#3}% @@ -4412,8 +4597,9 @@ false,nolabel,autolabel,nameref}[nolabel]{% %\cs{ifglshasshort}\marg{label}\marg{true part}\marg{false part} %\changes{3.11a}{2013-10-15}{new} %\changes{4.03}{2014-01-20}{added \cs{glsdetoklabel}} +%\changes{4.45}{2020-02-13}{made robust} % \begin{macrocode} -\newcommand*{\ifglshasshort}[3]{% +\newrobustcmd*{\ifglshasshort}[3]{% \letcs{\@glo@short}{glo@\glsdetoklabel{#1}@short}% \ifdefempty\@glo@short {#3}% @@ -4432,8 +4618,9 @@ false,nolabel,autolabel,nameref}[nolabel]{% %\cs{ifglshasfield}\marg{field}\marg{label}\marg{true part}\marg{false %part} %\end{definition} +%\changes{4.45}{2020-02-13}{made robust} % \begin{macrocode} -\newcommand*{\ifglshasfield}[4]{% +\newrobustcmd*{\ifglshasfield}[4]{% \glsdoifexists{#2}% {% \letcs{\@glo@thisvalue}{glo@\glsdetoklabel{#2}@#1}% @@ -11467,6 +11654,10 @@ false,nolabel,autolabel,nameref}[nolabel]{% \ifglshaslong{#1}% {% \letcs\@glo@text{glo@\glsdetoklabel{#1}@name}% +% \end{macrocode} +%\cs{@gls@getbody} is defined by \sty{mfirstuc} (which used to be +%part of \styfmt{glossaries}). +% \begin{macrocode} \expandafter\@gls@getbody\@glo@text{}\@nil \expandafter\ifx\@gls@body\glsentrylong\relax \expandafter\Glsentrylong\@gls@rest @@ -11487,7 +11678,17 @@ false,nolabel,autolabel,nameref}[nolabel]{% \@glo@text }% \else - \xmakefirstuc{\@glo@text}% +% \end{macrocode} +%\changes{4.45}{2020-02-13}{added check for \cs{glsshortaccessdisplay}} +% \begin{macrocode} + \expandafter\ifx\@gls@body\glsshortaccessdisplay\relax + {% + \let\glsentryshort\Glsentryshort + \@glo@text + }% + \else + \xmakefirstuc{\@glo@text}% + \fi \fi \fi \fi @@ -11650,10 +11851,14 @@ false,nolabel,autolabel,nameref}[nolabel]{% % %\begin{macro}{\glsentrytitlecase} %\changes{4.22}{2016-04-19}{new} +%\changes{4.45}{2020-02-13}{added existence check} % \begin{macrocode} \newrobustcmd*{\@glsentrytitlecase}[2]{% - \glsfieldfetch{#1}{#2}{\@gls@value}% - \xcapitalisewords{\@gls@value}% + \glsdoifexists{#1}% + {% + \glsfieldfetch{#1}{#2}{\@gls@value}% + \xcapitalisewords{\@gls@value}% + }% } \ifdef\texorpdfstring { @@ -11689,6 +11894,16 @@ false,nolabel,autolabel,nameref}[nolabel]{% % \end{macrocode} %\end{macro} % +%\begin{macro}{\glsentryparent} +%Expands to the label of the entry's parent. +%\changes{4.45}{2020-02-13}{new} +% \begin{macrocode} +\newcommand*{\glsentryparent}[1]{% + \@gls@entry@field{#1}{parent}% +} +% \end{macrocode} +%\end{macro} +% %\begin{macro}{\glsentryuseri} % Get the first user key (as specified by the % \gloskey{user1} when the entry was defined). The argument @@ -12879,11 +13094,11 @@ false,nolabel,autolabel,nameref}[nolabel]{% % style file). % % Note that you can't use \cs{@makeglossary} for only some of the -% defined glossaries. You either need to have a \cs{makeglossary} -% for all glossaries or none (otherwise you will end up with a -% situation where \TeX\ is trying to write to a non-existant -% file). The relevant glossary must be -% defined prior to using \cs{@makeglossary}. +% defined glossaries (with just the base \styfmt{glossaries} package). You either need +% to have a \cs{makeglossaries} for all glossaries or none (otherwise +% you will end up with a situation where \TeX\ is trying to write to a non-existant +% file). The relevant glossary must be defined prior to using \cs{@makeglossary}. +% \sty{glossaries-extra} allows for a hybrid approach. %\begin{macro}{\@makeglossary} % \begin{macrocode} \newcommand*{\@makeglossary}[1]{% @@ -13084,6 +13299,8 @@ false,nolabel,autolabel,nameref}[nolabel]{% %\begin{macro}{\makeglossaries} % \begin{macrocode} \newcommand*{\makeglossaries}{% + \@domakeglossaries + {% % \end{macrocode} %If automake=immediate setting is on, use the shell escape now. % \begin{macrocode} @@ -13142,8 +13359,10 @@ false,nolabel,autolabel,nameref}[nolabel]{% % implements \cs{makeglossaries} or has been restored to its original % definition (in which case it shouldn't be changed). %\changes{4.41}{2018-07-23}{removed redefinition of \cs{makeglossary}} +%\changes{4.45}{2020-02-13}{let \cs{@makeglossary} to \cs{@gobble} +%instead of \cs{relax}} % \begin{macrocode} - \let\@makeglossary\relax + \let\@makeglossary\@gobble \let\makeglossaries\relax % \end{macrocode} % Disable all commands that have no effect after \cs{makeglossaries} @@ -13207,6 +13426,7 @@ false,nolabel,autolabel,nameref}[nolabel]{% % Check the sort setting: % \begin{macrocode} \@glo@check@sortallowed\makeglossaries + }% } % \end{macrocode} %\changes{4.02}{2013-13-05}{made preamble only} @@ -13236,6 +13456,8 @@ false,nolabel,autolabel,nameref}[nolabel]{% % needed for \cs{printnoidxglossary} % \begin{macrocode} \newcommand*{\makenoidxglossaries}{% + \@domakeglossaries + {% % \end{macrocode} % Redefine empty glossary warning: % \begin{macrocode} @@ -13405,6 +13627,7 @@ false,nolabel,autolabel,nameref}[nolabel]{% % Check sort option allowed. % \begin{macrocode} \@glo@check@sortallowed\makenoidxglossaries + }% } % \end{macrocode} % Preamble-only command: @@ -14176,8 +14399,9 @@ you %\cs{glssee}\marg{label}\marg{cross-ref list} %\changes{1.17}{2008-12-26}{new} %\changes{3.08a}{2013-09-28}{made robust} +%\changes{4.45}{2020-02-13}{switched to \cs{newrobustcmd}} % \begin{macrocode} -\DeclareRobustCommand*{\glssee}[3][\seename]{% +\newrobustcmd*{\glssee}[3][\seename]{% \@do@seeglossary{#2}{[#1]{#3}}} \newcommand*{\@glssee}[3][\seename]{% \glssee[#1]{#3}{#2}} @@ -14190,16 +14414,18 @@ you % The first argument specifies what tag to use (e.g.\ ``see''), % the second argument is a comma-separated list of labels. % The final argument (the location) is ignored. +%\changes{4.45}{2020-02-13}{switched to \cs{newrobustcmd}} % \begin{macrocode} -\DeclareRobustCommand*{\glsseeformat}[3][\seename]{% +\newrobustcmd*{\glsseeformat}[3][\seename]{% \emph{#1} \glsseelist{#2}} % \end{macrocode} %\end{macro} %\begin{macro}{\glsseelist} %\cs{glsseelist}\marg{list} formats list of entry labels. %\changes{3.08a}{2013-09-28}{made robust} +%\changes{4.45}{2020-02-13}{switched to \cs{newrobustcmd}} % \begin{macrocode} -\DeclareRobustCommand*{\glsseelist}[1]{% +\newrobustcmd*{\glsseelist}[1]{% % \end{macrocode} % If there is only one item in the list, set the last separator % to do nothing. @@ -14257,8 +14483,9 @@ you %\changes{3.0}{2011-04-02}{hyperlink uses \cs{glsseeitemformat} instead %of \cs{glsentryname}} %\changes{3.08a}{2013-09-28}{made robust} +%\changes{4.45}{2020-02-13}{switched to \cs{newrobustcmd}} % \begin{macrocode} -\DeclareRobustCommand*{\glsseeitem}[1]{\glshyperlink[\glsseeitemformat{#1}]{#1}} +\newrobustcmd*{\glsseeitem}[1]{\glshyperlink[\glsseeitemformat{#1}]{#1}} % \end{macrocode} %\end{macro} %\begin{macro}{\glsseeitemformat} @@ -19187,7 +19414,7 @@ you % \cs{gls}\marg{label}} on subsequent use. % \begin{macrocode} \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{glossaries-prefix}[2019/12/06 v4.44 (NLCT)] +\ProvidesPackage{glossaries-prefix}[2020/02/13 v4.45 (NLCT)] % \end{macrocode} % Pass all options to \sty{glossaries}: % \begin{macrocode} @@ -19250,55 +19477,64 @@ you % % Define commands to access these fields: %\begin{macro}{\glsentryprefixfirst} +%\changes{4.45}{2020-02-13}{added \cs{glsdetoklabel}} % \begin{macrocode} -\newcommand*{\glsentryprefixfirst}[1]{\csuse{glo@#1@prefixfirst}} +\newcommand*{\glsentryprefixfirst}[1]{\csuse{glo@\glsdetoklabel{#1}@prefixfirst}} % \end{macrocode} %\end{macro} %\begin{macro}{\glsentryprefixfirstplural} +%\changes{4.45}{2020-02-13}{added \cs{glsdetoklabel}} % \begin{macrocode} -\newcommand*{\glsentryprefixfirstplural}[1]{\csuse{glo@#1@prefixfirstplural}} +\newcommand*{\glsentryprefixfirstplural}[1]{% + \csuse{glo@\glsdetoklabel{#1}@prefixfirstplural}} % \end{macrocode} %\end{macro} %\begin{macro}{\glsentryprefix} +%\changes{4.45}{2020-02-13}{added \cs{glsdetoklabel}} % \begin{macrocode} -\newcommand*{\glsentryprefix}[1]{\csuse{glo@#1@prefix}} +\newcommand*{\glsentryprefix}[1]{\csuse{glo@\glsdetoklabel{#1}@prefix}} % \end{macrocode} %\end{macro} %\begin{macro}{\glsentryprefixplural} +%\changes{4.45}{2020-02-13}{added \cs{glsdetoklabel}} % \begin{macrocode} -\newcommand*{\glsentryprefixplural}[1]{\csuse{glo@#1@prefixplural}} +\newcommand*{\glsentryprefixplural}[1]{\csuse{glo@\glsdetoklabel{#1}@prefixplural}} % \end{macrocode} %\end{macro} % % Now for the initial upper case variants: %\begin{macro}{\Glsentryprefixfirst} +%\changes{4.45}{2020-02-13}{added \cs{glsdetoklabel}} % \begin{macrocode} \newrobustcmd*{\Glsentryprefixfirst}[1]{% - \protected@edef\@glo@text{\csname glo@#1@prefixfirst\endcsname}% + \protected@edef\@glo@text{\csname glo@\glsdetoklabel{#1}@prefixfirst\endcsname}% \xmakefirstuc\@glo@text } % \end{macrocode} %\end{macro} %\begin{macro}{\Glsentryprefixfirstplural} +%\changes{4.45}{2020-02-13}{added \cs{glsdetoklabel}} % \begin{macrocode} \newrobustcmd*{\Glsentryprefixfirstplural}[1]{% - \protected@edef\@glo@text{\csname glo@#1@prefixfirstplural\endcsname}% + \protected@edef\@glo@text{\csname glo@\glsdetoklabel{#1}@prefixfirstplural\endcsname}% \xmakefirstuc\@glo@text } % \end{macrocode} %\end{macro} %\begin{macro}{\Glsentryprefix} +%\changes{4.45}{2020-02-13}{added \cs{glsdetoklabel}} % \begin{macrocode} \newrobustcmd*{\Glsentryprefix}[1]{% - \protected@edef\@glo@text{\csname glo@#1@prefix\endcsname}% + \protected@edef\@glo@text{\csname glo@\glsdetoklabel{#1}@prefix\endcsname}% \xmakefirstuc\@glo@text } % \end{macrocode} %\end{macro} %\begin{macro}{\Glsentryprefixplural} +%\changes{4.45}{2020-02-13}{added \cs{glsdetoklabel}} % \begin{macrocode} \newrobustcmd*{\Glsentryprefixplural}[1]{% - \protected@edef\@glo@text{\csname glo@#1@prefixplural\endcsname}% + \protected@edef\@glo@text{\csname glo@\glsdetoklabel{#1}@prefixplural\endcsname}% \xmakefirstuc\@glo@text } % \end{macrocode} @@ -19306,36 +19542,40 @@ you % % Define commands to determine if the prefix keys have been set: %\begin{macro}{\ifglshasprefix} +%\changes{4.45}{2020-02-13}{added \cs{glsdetoklabel}} % \begin{macrocode} \newcommand*{\ifglshasprefix}[3]{% - \ifcsempty{glo@#1@prefix}% + \ifcsempty{glo@\glsdetoklabel{#1}@prefix}% {#3}% {#2}% } % \end{macrocode} %\end{macro} %\begin{macro}{\ifglshasprefixplural} +%\changes{4.45}{2020-02-13}{added \cs{glsdetoklabel}} % \begin{macrocode} \newcommand*{\ifglshasprefixplural}[3]{% - \ifcsempty{glo@#1@prefixplural}% + \ifcsempty{glo@\glsdetoklabel{#1}@prefixplural}% {#3}% {#2}% } % \end{macrocode} %\end{macro} %\begin{macro}{\ifglshasprefixfirst} +%\changes{4.45}{2020-02-13}{added \cs{glsdetoklabel}} % \begin{macrocode} \newcommand*{\ifglshasprefixfirst}[3]{% - \ifcsempty{glo@#1@prefixfirst}% + \ifcsempty{glo@\glsdetoklabel{#1}@prefixfirst}% {#3}% {#2}% } % \end{macrocode} %\end{macro} %\begin{macro}{\ifglshasprefixfirstplural} +%\changes{4.45}{2020-02-13}{added \cs{glsdetoklabel}} % \begin{macrocode} \newcommand*{\ifglshasprefixfirstplural}[3]{% - \ifcsempty{glo@#1@prefixfirstplural}% + \ifcsempty{glo@\glsdetoklabel{#1}@prefixfirstplural}% {#3}% {#2}% } @@ -19356,6 +19596,14 @@ you % \end{macrocode} %\end{macro} % +%\begin{macro}{\glsprefixsep} +%\changes{4.45}{2020-02-13}{new} +%Separator between prefix and term. Does nothing by default. +% \begin{macrocode} +\newcommand{\glsprefixsep}{} +% \end{macrocode} +%\end{macro} +% % Define commands that insert the prefix before commands like \ics{gls}: %\begin{macro}{\pgls} %\changes{4.08}{2014-07-30}{changed to use \cs{@gls@hyp@opt}} @@ -19384,10 +19632,10 @@ you {% \ifglsused{#2}% {% - \glsentryprefix{#2}% + \ifglshasprefix{#2}{\glsentryprefix{#2}\glsprefixsep}{}% }% {% - \glsentryprefixfirst{#2}% + \ifglshasprefixfirst{#2}{\glsentryprefixfirst{#2}\glsprefixsep}{}% }% \@gls@{#1}{#2}[#3]% }% @@ -19423,10 +19671,11 @@ you {% \ifglsused{#2}% {% - \glsentryprefixplural{#2}% + \ifglshasprefixplural{#2}{\glsentryprefixplural{#2}\glsprefixsep}{}% }% {% - \glsentryprefixfirstplural{#2}% + \ifglshasprefixfirstplural{#2}% + {\glsentryprefixfirstplural{#2}\glsprefixsep}{}% }% \@glspl@{#1}{#2}[#3]% }% @@ -19465,6 +19714,7 @@ you \ifglshasprefix{#2}% {% \Glsentryprefix{#2}% + \glsprefixsep \@gls@{#1}{#2}[#3]% }% {\@Gls@{#1}{#2}[#3]}% @@ -19473,6 +19723,7 @@ you \ifglshasprefixfirst{#2}% {% \Glsentryprefixfirst{#2}% + \glsprefixsep \@gls@{#1}{#2}[#3]% }% {\@Gls@{#1}{#2}[#3]}% @@ -19513,6 +19764,7 @@ you \ifglshasprefixplural{#2}% {% \Glsentryprefixplural{#2}% + \glsprefixsep \@glspl@{#1}{#2}[#3]% }% {\@Glspl@{#1}{#2}[#3]}% @@ -19521,6 +19773,7 @@ you \ifglshasprefixfirstplural{#2}% {% \Glsentryprefixfirstplural{#2}% + \glsprefixsep \@glspl@{#1}{#2}[#3]% }% {\@Glspl@{#1}{#2}[#3]}% @@ -19558,10 +19811,12 @@ you {% \ifglsused{#2}% {% - \mfirstucMakeUppercase{\glsentryprefix{#2}}% + \ifglshasprefix{#2}% + {\mfirstucMakeUppercase{\glsentryprefix{#2}\glsprefixsep}}{}% }% {% - \mfirstucMakeUppercase{\glsentryprefixfirst{#2}}% + \ifglshasprefixfirst{#2}% + {\mfirstucMakeUppercase{\glsentryprefixfirst{#2}\glsprefixsep}}{}% }% \@GLS@{#1}{#2}[#3]% }% @@ -19597,10 +19852,12 @@ you {% \ifglsused{#2}% {% - \mfirstucMakeUppercase{\glsentryprefixplural{#2}}% + \ifglshasprefixplural{#2}% + {\mfirstucMakeUppercase{\glsentryprefixplural{#2}\glsprefixsep}}{}% }% {% - \mfirstucMakeUppercase{\glsentryprefixfirstplural{#2}}% + \ifglshasprefixfirstplural{#2}% + {\mfirstucMakeUppercase{\glsentryprefixfirstplural{#2}\glsprefixsep}}{}% }% \@GLSpl@{#1}{#2}[#3]% }% @@ -19622,7 +19879,7 @@ you %\label{sec:code:hypernav} % Package Definition: % \begin{macrocode} -\ProvidesPackage{glossary-hypernav}[2019/12/06 v4.44 (NLCT)] +\ProvidesPackage{glossary-hypernav}[2020/02/13 v4.45 (NLCT)] % \end{macrocode} % % The commands defined in this package are provided to @@ -19632,8 +19889,9 @@ you % set \cs{@glo@type} to the label of the current % glossary. This is used to create a unique hypertarget in % the event of multiple glossaries. -%\\[10pt] -% \cs{glsnavhyperlink}\oarg{type}\marg{label}\marg{text}\\[10pt] +%\begin{definition} +% \cs{glsnavhyperlink}\oarg{type}\marg{label}\marg{text} +%\end{definition} % This command makes \meta{text} a hyperlink to the glossary group % whose label is given by \meta{label} for the glossary given % by \meta{type}. @@ -19655,14 +19913,16 @@ you \newcommand*{\glsnavhyperlinkname}[2]{glsn:#1@#2} % \end{macrocode} %\end{macro} -%\vskip5pt -% \cs{glsnavhypertarget}\oarg{type}\marg{label}\marg{text}\\[10pt] +% +%\begin{macro}{\glsnavhypertarget} +%\begin{definition} +% \cs{glsnavhypertarget}\oarg{type}\marg{label}\marg{text} +%\end{definition} % This command makes \meta{text} a hypertarget for the glossary group % whose label is given by \meta{label} in the glossary given % by \meta{type}. If \meta{type} is omitted, \cs{@glo@type} is % used which is set by \ics{printglossary} to the current % glossary label. -%\begin{macro}{\glsnavhypertarget} %\changes{1.14}{2008-06-17}{added write to aux file} %\changes{1.15}{2008-08-15}{added check if rerun required} %\changes{1.17}{2008-12-26}{replaced \cs{hypertarget} to @@ -19815,7 +20075,7 @@ you % This defines an in-line style where the entries are % comma-separated with just the name and description displayed. % \begin{macrocode} -\ProvidesPackage{glossary-inline}[2019/12/06 v4.44 (NLCT)] +\ProvidesPackage{glossary-inline}[2020/02/13 v4.45 (NLCT)] % \end{macrocode} % %\begin{style}{inline} @@ -20006,7 +20266,7 @@ you % \ics{item} command, it will appear in a bold font by % default. % \begin{macrocode} -\ProvidesPackage{glossary-list}[2019/12/06 v4.44 (NLCT)] +\ProvidesPackage{glossary-list}[2020/02/13 v4.45 (NLCT)] % \end{macrocode} %\begin{macro}{\indexspace} %\changes{4.13}{2015-02-03}{new} @@ -20288,7 +20548,7 @@ you % The glossary styles defined in the \isty{glossary-long} package % used the \env{longtable} environment in the glossary. % \begin{macrocode} -\ProvidesPackage{glossary-long}[2019/12/06 v4.44 (NLCT)] +\ProvidesPackage{glossary-long}[2020/02/13 v4.45 (NLCT)] % \end{macrocode} % Requires the \isty{longtable} package: % \begin{macrocode} @@ -20785,7 +21045,7 @@ you % \url{http://tex.stackexchange.com/a/56890} % % \begin{macrocode} -\ProvidesPackage{glossary-longbooktabs}[2019/12/06 v4.44 (NLCT)] +\ProvidesPackage{glossary-longbooktabs}[2020/02/13 v4.45 (NLCT)] % \end{macrocode} % Requires \sty{booktabs} package: % \begin{macrocode} @@ -21126,7 +21386,7 @@ you % used the \env{longtable} environment in the glossary and use % ragged right formatting for the multiline columns. % \begin{macrocode} -\ProvidesPackage{glossary-longragged}[2019/12/06 v4.44 (NLCT)] +\ProvidesPackage{glossary-longragged}[2020/02/13 v4.45 (NLCT)] % \end{macrocode} % Requires the \isty{array} package: % \begin{macrocode} @@ -21559,7 +21819,7 @@ you %use the \sty{multicol} package. These use the tree-like glossary %styles in a multicol environment. % \begin{macrocode} -\ProvidesPackage{glossary-mcols}[2019/12/06 v4.44 (NLCT)] +\ProvidesPackage{glossary-mcols}[2020/02/13 v4.45 (NLCT)] % \end{macrocode} % Required packages: % \begin{macrocode} @@ -21996,7 +22256,7 @@ you % The glossary styles defined in the \isty{glossary-super} package % use the \env{supertabular} environment. % \begin{macrocode} -\ProvidesPackage{glossary-super}[2019/12/06 v4.44 (NLCT)] +\ProvidesPackage{glossary-super}[2020/02/13 v4.45 (NLCT)] % \end{macrocode} % Requires the \isty{supertabular} package: % \begin{macrocode} @@ -22528,7 +22788,7 @@ you % are like those provided by the \isty{glossary-super} package, % except that the multiline columns have ragged right justification. % \begin{macrocode} -\ProvidesPackage{glossary-superragged}[2019/12/06 v4.44 (NLCT)] +\ProvidesPackage{glossary-superragged}[2020/02/13 v4.45 (NLCT)] % \end{macrocode} % Requires the \isty{array} package: % \begin{macrocode} @@ -22968,7 +23228,7 @@ you % that have a tree-like structure. These are designed for % hierarchical glossaries. % \begin{macrocode} -\ProvidesPackage{glossary-tree}[2019/12/06 v4.44 (NLCT)] +\ProvidesPackage{glossary-tree}[2020/02/13 v4.45 (NLCT)] % \end{macrocode} % %\begin{macro}{\indexspace} @@ -23689,7 +23949,7 @@ you % hyperlinks may not work properly. % \begin{macrocode} \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{glossaries-compatible-207}[2019/12/06 v4.44 (NLCT)] +\ProvidesPackage{glossaries-compatible-207}[2020/02/13 v4.45 (NLCT)] % \end{macrocode} %\begin{macro}{\GlsAddXdyAttribute} % Adds an attribute in old format. @@ -24050,7 +24310,7 @@ you %\section{glossaries-compatible-307} % \begin{macrocode} \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{glossaries-compatible-307}[2019/12/06 v4.44 (NLCT)] +\ProvidesPackage{glossaries-compatible-307}[2020/02/13 v4.45 (NLCT)] % \end{macrocode} % % Compatibility macros for predefined glossary styles: @@ -24858,7 +25118,7 @@ you % \end{macrocode} % Package version number now in line with main glossaries package number. % \begin{macrocode} -\ProvidesPackage{glossaries-accsupp}[2019/12/06 v4.44 (NLCT) +\ProvidesPackage{glossaries-accsupp}[2020/02/13 v4.45 (NLCT) Experimental glossaries accessibility] % \end{macrocode} % Pass all options to \sty{glossaries}: @@ -24936,8 +25196,54 @@ you % Required packages: % \begin{macrocode} \RequirePackage{glossaries} -\RequirePackage{accsupp} % \end{macrocode} +% +%\begin{macro}{\gls@accsupp@engine} +%\changes{4.45}{2020-02-13}{new} +%There's currently only support for \sty{accsupp}, but if you +%define \cs{gls@accsupp@engine} before loading +%\sty{glossaries-accsupp}, you can prevent \sty{accsupp} from being +%loaded. Redefining this command after \sty{glossaries-accsupp} has loaded +%obviously won't do anything (and so is an internal command to +%deter casual use). If it is defined to something other than +%"accsupp" then \cs{gls@accessibility} will need to be defined to +%something appropriate. +% \begin{macrocode} +\providecommand{\gls@accsupp@engine}{accsupp} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\gls@accessibility} +%\changes{4.45}{2020-02-13}{new} +%\begin{definition} +%\cs{gls@accessibility}\marg{options}\marg{PDF element}\marg{value}\marg{content} +%\end{definition} +% \begin{macrocode} +\providecommand{\gls@accessibility}[4]{#4} +\ifdefstring\gls@accsupp@engine{accsupp} +{ + \RequirePackage{accsupp} + \renewcommand{\gls@accessibility}[4]{% + \BeginAccSupp{#1,#2={#3}}#4\EndAccSupp{}% + } +} +{} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\glsaccessibility} +%\changes{4.45}{2020-02-13}{new} +%\begin{definition} +%\cs{glsaccessibility}\oarg{options}\marg{PDF element}\marg{value}\marg{content} +%\end{definition} +%User-level command that includes debug info if required. +% \begin{macrocode} +\newcommand{\glsaccessibility}[4][]{% + \@glsshowaccsupp{#1}{#2}{#3}% + \gls@accessibility{#1}{#2}{#3}{#4}% +} +% \end{macrocode} +%\end{macro} % %\section{Defining Replacement Text} % The version 0.1 stored the replacement text in the @@ -25050,10 +25356,69 @@ you } % \end{macrocode} %\end{key} -% There are no equivalent keys for the \gloskey{user1}\ldots -%\gloskey{user6} keys. The replacement text would have to be +%There are now also keys that correspond to the user keys: +%\begin{key}{user1access} +%\changes{4.45}{2020-02-13}{new} +% The replacement text corresponding to the \gloskey{user1} key: +% \begin{macrocode} +\define@key{glossentry}{user1access}{% + \def\@glo@useriaccess{#1}% +} +% \end{macrocode} +%\end{key} +%\begin{key}{user2access} +%\changes{4.45}{2020-02-13}{new} +% The replacement text corresponding to the \gloskey{user2} key: +% \begin{macrocode} +\define@key{glossentry}{user2access}{% + \def\@glo@useriiaccess{#1}% +} +% \end{macrocode} +%\end{key} +% +%\begin{key}{user3access} +%\changes{4.45}{2020-02-13}{new} +% The replacement text corresponding to the \gloskey{user3} key: +% \begin{macrocode} +\define@key{glossentry}{user3access}{% + \def\@glo@useriiiaccess{#1}% +} +% \end{macrocode} +%\end{key} +% +%\begin{key}{user4access} +%\changes{4.45}{2020-02-13}{new} +% The replacement text corresponding to the \gloskey{user4} key: +% \begin{macrocode} +\define@key{glossentry}{user4access}{% + \def\@glo@userivaccess{#1}% +} +% \end{macrocode} +%\end{key} +% +%\begin{key}{user5access} +%\changes{4.45}{2020-02-13}{new} +% The replacement text corresponding to the \gloskey{user5} key: +% \begin{macrocode} +\define@key{glossentry}{user5access}{% + \def\@glo@uservaccess{#1}% +} +% \end{macrocode} +%\end{key} +% +%\begin{key}{user6access} +%\changes{4.45}{2020-02-13}{new} +% The replacement text corresponding to the \gloskey{user6} key: +% \begin{macrocode} +\define@key{glossentry}{user6access}{% + \def\@glo@userviaccess{#1}% +} +% \end{macrocode} +%\end{key} +% +% For any custom keys, the replacement text would have to be % explicitly put in the value, e.g., -% "user1={\glsaccsupp{inches}{in}}". +% "user1={\glsshortaccsupp{inches}{in}}". % % Append these new keys to \cs{@gls@keymap}: % \begin{macrocode} @@ -25070,7 +25435,13 @@ you {shortaccess}{shortaccess},% {shortpluralaccess}{shortpluralaccess},% {longaccess}{longaccess},% - {longpluralaccess}{longpluralaccess}% + {longpluralaccess}{longpluralaccess},% + {user1access}{useriaccess},% + {user2access}{useriiaccess},% + {user3access}{useriiiaccess},% + {user4access}{userivaccess},% + {user5access}{uservaccess},% + {user6access}{userviaccess}% } % \end{macrocode} % @@ -25081,14 +25452,18 @@ you % \end{macrocode} %\end{macro} % -% Add to the start hook (the \gloskey{access} key is initialised to +% Previously, the \gloskey{access} key was initialised to % the value of the \gloskey{symbol} key at the start for backwards -% compatibility): +% compatibility. This causes a problem for situations where the +% replacement text is provided for \gloskey{symbol} but not for +% \gloskey{name} so this behaviour has been removed. +%\changes{4.45}{2020-02-13}{removed backward compatibility use of +%symbol key} % \begin{macrocode} \let\@gls@oldnewglossaryentryprehook\@newglossaryentryprehook \renewcommand*{\@newglossaryentryprehook}{% \@gls@oldnewglossaryentryprehook - \def\@glo@access{\@glo@symbol}% + \def\@glo@access{\relax}% % \end{macrocode} % Initialise the other keys: % \begin{macrocode} @@ -25104,6 +25479,12 @@ you \def\@glo@shortpluralaccess{\@glo@shortaccess}% \def\@glo@longaccess{\relax}% \def\@glo@longpluralaccess{\@glo@longaccess}% + \def\@glo@useriaccess{\relax}% + \def\@glo@useriiaccess{\relax}% + \def\@glo@useriiiaccess{\relax}% + \def\@glo@userivaccess{\relax}% + \def\@glo@uservaccess{\relax}% + \def\@glo@userviaccess{\relax}% } % \end{macrocode} % Add to the end hook: @@ -25153,6 +25534,24 @@ you \expandafter \protected@xdef\csname glo@\@glo@label @longpluralaccess\endcsname{% \@glo@longpluralaccess}% + \expandafter + \protected@xdef\csname glo@\@glo@label @useriaccess\endcsname{% + \@glo@useriaccess}% + \expandafter + \protected@xdef\csname glo@\@glo@label @useriiaccess\endcsname{% + \@glo@useriiaccess}% + \expandafter + \protected@xdef\csname glo@\@glo@label @useriiiaccess\endcsname{% + \@glo@useriiiaccess}% + \expandafter + \protected@xdef\csname glo@\@glo@label @userivaccess\endcsname{% + \@glo@userivaccess}% + \expandafter + \protected@xdef\csname glo@\@glo@label @uservaccess\endcsname{% + \@glo@uservaccess}% + \expandafter + \protected@xdef\csname glo@\@glo@label @userviaccess\endcsname{% + \@glo@userviaccess}% } % \end{macrocode} % @@ -25198,11 +25597,12 @@ you % \end{macrocode} %\end{macro} %\begin{macro}{\glsentryfirstpluralaccess} +%\changes{4.45}{2020-02-13}{switched to using \cs{@gls@entry@field}} % Get the value of the \gloskey{firstpluralaccess} key for the entry with % the given label: % \begin{macrocode} \newcommand*{\glsentryfirstpluralaccess}[1]{% - \csname glo@#1@firstpluralaccess\endcsname + \@gls@entry@field{#1}{firstpluralaccess}% } % \end{macrocode} %\end{macro} @@ -25240,9 +25640,10 @@ you % Get the value of the \gloskey{descriptionpluralaccess} key for the entry with % the given label: %\changes{4.03}{2014-01-20}{switched to using \cs{@gls@entry@field}} +%\changes{4.45}{2020-02-13}{corrected field reference} % \begin{macrocode} \newcommand*{\glsentrydescpluralaccess}[1]{% - \@gls@entry@field{#1}{descaccess}% + \@gls@entry@field{#1}{descpluralaccess}% } % \end{macrocode} %\end{macro} @@ -25288,159 +25689,433 @@ you % \end{macrocode} %\end{macro} % -%\begin{macro}{\glsaccsupp} -%\changes{4.38}{2018-05-10}{added braces around actual text argument} -%\begin{definition} -%\cs{glsaccsupp}\marg{replacement text}\marg{text} -%\end{definition} -% This can be redefined to use "E" or "Alt" instead of -% "ActualText". (I don't have the software to test the "E" or -% "Alt" options.) +%\begin{macro}{\glsentryuseriaccess} +% Get the value of the \gloskey{user1access} key for the entry with +% the given label: +%\changes{4.45}{2020-02-13}{new} % \begin{macrocode} -\newcommand*{\glsaccsupp}[2]{% - \BeginAccSupp{ActualText={#1}}#2\EndAccSupp{}% +\newcommand*{\glsentryuseriaccess}[1]{% + \@gls@entry@field{#1}{useriaccess}% } % \end{macrocode} %\end{macro} -%\begin{macro}{\xglsaccsupp} -% Fully expands replacement text before calling \cs{glsaccsupp} +% +%\begin{macro}{\glsentryuseriiaccess} +% Get the value of the \gloskey{user2access} key for the entry with +% the given label: +%\changes{4.45}{2020-02-13}{new} % \begin{macrocode} -\newcommand*{\xglsaccsupp}[2]{% - \protected@edef\@gls@replacementtext{#1}% - \expandafter\glsaccsupp\expandafter{\@gls@replacementtext}{#2}% +\newcommand*{\glsentryuseriiaccess}[1]{% + \@gls@entry@field{#1}{useriiaccess}% } % \end{macrocode} %\end{macro} % -%\begin{macro}{\@gls@access@display} -%\changes{4.03}{2014-01-20}{new} +%\begin{macro}{\glsentryuseriiiaccess} +% Get the value of the \gloskey{user3access} key for the entry with +% the given label: +%\changes{4.45}{2020-02-13}{new} % \begin{macrocode} -\newcommand*{\@gls@access@display}[2]{% - \protected@edef\@glo@access{#2}% - \ifx\@glo@access\@gls@noaccess - #1% - \else - \xglsaccsupp{\@glo@access}{#1}% - \fi +\newcommand*{\glsentryuseriiiaccess}[1]{% + \@gls@entry@field{#1}{useriiiaccess}% } % \end{macrocode} %\end{macro} % -%\begin{macro}{\glsnameaccessdisplay} -% Displays the first argument with the accessibility text for -% the entry with the label given by the second argument (if set). +%\begin{macro}{\glsentryuserivaccess} +% Get the value of the \gloskey{user4access} key for the entry with +% the given label: +%\changes{4.45}{2020-02-13}{new} % \begin{macrocode} -\DeclareRobustCommand*{\glsnameaccessdisplay}[2]{% - \@gls@access@display{#1}{\glsentryaccess{#2}}% +\newcommand*{\glsentryuserivaccess}[1]{% + \@gls@entry@field{#1}{userivaccess}% } % \end{macrocode} %\end{macro} -%\begin{macro}{\glstextaccessdisplay} -% As above but for the \gloskey{textaccess} replacement text. +% +%\begin{macro}{\glsentryuservaccess} +% Get the value of the \gloskey{user5access} key for the entry with +% the given label: +%\changes{4.45}{2020-02-13}{new} % \begin{macrocode} -\DeclareRobustCommand*{\glstextaccessdisplay}[2]{% - \@gls@access@display{#1}{\glsentrytextaccess{#2}}% +\newcommand*{\glsentryuservaccess}[1]{% + \@gls@entry@field{#1}{uservaccess}% } % \end{macrocode} %\end{macro} -%\begin{macro}{\glspluralaccessdisplay} -% As above but for the \gloskey{pluralaccess} replacement text. +% +%\begin{macro}{\glsentryuserviaccess} +% Get the value of the \gloskey{user6access} key for the entry with +% the given label: +%\changes{4.45}{2020-02-13}{new} % \begin{macrocode} -\DeclareRobustCommand*{\glspluralaccessdisplay}[2]{% - \@gls@access@display{#1}{\glsentrypluralaccess{#2}}% +\newcommand*{\glsentryuserviaccess}[1]{% + \@gls@entry@field{#1}{userviaccess}% } % \end{macrocode} %\end{macro} -%\begin{macro}{\glsfirstaccessdisplay} -% As above but for the \gloskey{firstaccess} replacement text. -% \begin{macrocode} -\DeclareRobustCommand*{\glsfirstaccessdisplay}[2]{% - \@gls@access@display{#1}{\glsentryfirstaccess{#2}}% +% +%There are three types of replacement text: +%\begin{description} +%\item[Alt] Description of some content that's non-textual (for +%example, an image). A word break is assumed after the content. +%\item[ActualText] A character or sequence of characters that +%replaces textual content (for example, a dropped capital, a +%ligature or a symbol). No word break is assumed after the content. +%\item[E] Expansion of an abbreviation to avoid ambiguity (for +%example, ``St'' could be short for ``saint'' or ``street''). +%\end{description} +%Therefore, rather than having one command for all fields, it's +%better to have a command dependent on the field type. For example, +%the \gloskey{short} and \gloskey{shortpl} keys would require "E", +%the \gloskey{symbol} key would require "ActualText", and a field +%that contains an image would require "Alt". +% +%\begin{macro}{\glsfieldaccsupp} +%\begin{definition} +%\cs{glsfieldaccsupp}\marg{replacement}\marg{content}\marg{field}\marg{label} +%\end{definition} +%\changes{4.45}{2020-02-13}{new} +%Test if there's a command called \cs{gls\meta{field}accsupp}. If +%there is then use that otherwise use \cs{glsaccsupp}. The first +%argument should be the internal field label (not the key). The +%final argument is the entry label. If \sty{glossaries-extra} has +%been loaded, this first checks for +%\cs{glsxtr\meta{category}\meta{field}accsupp} and \cs{glsxtr\meta{category}accsupp}. +% \begin{macrocode} +\newcommand{\glsfieldaccsupp}[4]{% + \ifdef\glscategory + {% + \ifcsdef{glsxtr\glscategory{#4}#3accsupp}% + {\csname glsxtr\glscategory{#4}#3accsupp\endcsname{#1}{#2}}% + {% + \ifcsdef{glsxtr\glscategory{#4}accsupp}% + {\csname glsxtr\glscategory{#4}accsupp\endcsname{#1}{#2}}% + {% + \ifcsdef{gls#3accsupp}% + {\csname gls#3accsupp\endcsname{#1}{#2}}% + {\glsaccsupp{#1}{#2}}% + }% + }% + }% + {% + \ifcsdef{gls#3accsupp}% + {\csname gls#3accsupp\endcsname{#1}{#2}}% + {\glsaccsupp{#1}{#2}}% + }% } % \end{macrocode} %\end{macro} -%\begin{macro}{\glsfirstpluralaccessdisplay} -% As above but for the \gloskey{firstpluralaccess} replacement text. +% +%\begin{macro}{\xglsfieldaccsupp} +%\begin{definition} +%\cs{xglsfieldaccsupp}\marg{replacement}\marg{content}\marg{field}\marg{label} +%\end{definition} +%\changes{4.45}{2020-02-13}{new} +%As \cs{glsfieldaccsupp} but fully expand replacement text. % \begin{macrocode} -\DeclareRobustCommand*{\glsfirstpluralaccessdisplay}[2]{% - \@gls@access@display{#1}{\glsentryfirstpluralaccess{#2}}% +\newcommand{\xglsfieldaccsupp}[1]{% + \protected@edef\@gls@replacementtext{#1}% + \expandafter\glsfieldaccsupp\expandafter{\@gls@replacementtext}% } % \end{macrocode} %\end{macro} -%\begin{macro}{\glssymbolaccessdisplay} -% As above but for the \gloskey{symbolaccess} replacement text. +% +%\begin{macro}{\glsshortaccsupp} +%\changes{4.45}{2020-02-13}{new} +%\begin{definition} +%\cs{glsshortaccsupp}\marg{replacement text}\marg{text} +%\end{definition} % \begin{macrocode} -\DeclareRobustCommand*{\glssymbolaccessdisplay}[2]{% - \@gls@access@display{#1}{\glsentrysymbolaccess{#2}}% -} +\newcommand*{\glsshortaccsupp}[2]{\glsaccessibility{E}{#1}{#2}} % \end{macrocode} %\end{macro} -%\begin{macro}{\glssymbolpluralaccessdisplay} -% As above but for the \gloskey{symbolpluralaccess} replacement text. -% \begin{macrocode} -\DeclareRobustCommand*{\glssymbolpluralaccessdisplay}[2]{% - \@gls@access@display{#1}{\glsentrysymbolpluralaccess{#2}}% +%\begin{macro}{\glsshortplaccsupp} +%\changes{4.45}{2020-02-13}{new} +%\begin{definition} +%\cs{glsshortplaccsupp}\marg{replacement text}\marg{text} +%\end{definition} +% \begin{macrocode} +\newcommand*{\glsshortplaccsupp}{\glsshortaccsupp} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glsaccsupp} +%\changes{4.38}{2018-05-10}{added braces around actual text argument} +%\begin{definition} +%\cs{glsaccsupp}\marg{replacement text}\marg{text} +%\end{definition} +% \begin{macrocode} +\newcommand*{\glsaccsupp}[2]{\glsaccessibility{ActualText}{#1}{#2}} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\xglsaccsupp} +% Fully expands replacement text before calling \cs{glsaccsupp} +% \begin{macrocode} +\newcommand*{\xglsaccsupp}[2]{% + \protected@edef\@gls@replacementtext{#1}% + \expandafter\glsaccsupp\expandafter{\@gls@replacementtext}{#2}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@gls@access@display} +%\changes{4.03}{2014-01-20}{new} +%Deprecated. Use \cs{@gls@fieldaccess@display} instead. +% \begin{macrocode} +\newcommand*{\@gls@access@display}[2]{% + \protected@edef\@glo@access{#2}% + \ifx\@glo@access\@gls@noaccess + #1% + \else + \xglsaccsupp{\@glo@access}{#1}% + \fi +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@gls@fieldaccess@display} +%\begin{definition} +%\cs{@gls@fieldaccess@display}\marg{label}\marg{field}\marg{content}\marg{replacement} +%\end{definition} +%\changes{4.45}{2020-02-13}{new} +% \begin{macrocode} +\newcommand*{\@gls@fieldaccess@display}[4]{% + \protected@edef\@glo@access{#4}% + \ifdefequal\@glo@access\@gls@noaccess + {#3}% + {\expandafter\glsfieldaccsupp\expandafter{\@glo@access}{#3}{#2}{#1}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\glsnameaccessdisplay} +%\changes{4.45}{2020-02-13}{added check for existence} +% Displays the first argument with the accessibility text for +% the entry with the label given by the second argument (if set). +% \begin{macrocode} +\newrobustcmd*{\glsnameaccessdisplay}[2]{% + \ifcsundef{glo@\glsdetoklabel{#2}@access}% + {#1}% + {\@gls@fieldaccess@display{#2}{name}{#1}{\glsentryaccess{#2}}}% +} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glstextaccessdisplay} +%\changes{4.45}{2020-02-13}{added check for existence} +% As above but for the \gloskey{textaccess} replacement text. +% \begin{macrocode} +\newrobustcmd*{\glstextaccessdisplay}[2]{% + \ifcsundef{glo@\glsdetoklabel{#2}@textaccess}% + {#1}% + {\@gls@fieldaccess@display{#2}{text}{#1}{\glsentrytextaccess{#2}}}% +} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glspluralaccessdisplay} +%\changes{4.45}{2020-02-13}{added check for existence} +% As above but for the \gloskey{pluralaccess} replacement text. +% \begin{macrocode} +\newrobustcmd*{\glspluralaccessdisplay}[2]{% + \ifcsundef{glo@\glsdetoklabel{#2}@pluralaccess}% + {#1}% + {\@gls@fieldaccess@display{#2}{plural}{#1}{\glsentrypluralaccess{#2}}}% +} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glsfirstaccessdisplay} +%\changes{4.45}{2020-02-13}{added check for existence} +% As above but for the \gloskey{firstaccess} replacement text. +% \begin{macrocode} +\newrobustcmd*{\glsfirstaccessdisplay}[2]{% + \ifcsundef{glo@\glsdetoklabel{#2}@firstaccess}% + {#1}% + {\@gls@fieldaccess@display{#2}{first}{#1}{\glsentryfirstaccess{#2}}}% +} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glsfirstpluralaccessdisplay} +%\changes{4.45}{2020-02-13}{added check for existence} +% As above but for the \gloskey{firstpluralaccess} replacement text. +% \begin{macrocode} +\newrobustcmd*{\glsfirstpluralaccessdisplay}[2]{% + \ifcsundef{glo@\glsdetoklabel{#2}@firstpluralaccess}% + {#1}% + {\@gls@fieldaccess@display{#2}{firstpl}{#1}{\glsentryfirstpluralaccess{#2}}}% +} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glssymbolaccessdisplay} +%\changes{4.45}{2020-02-13}{added check for existence} +% As above but for the \gloskey{symbolaccess} replacement text. +% \begin{macrocode} +\newrobustcmd*{\glssymbolaccessdisplay}[2]{% + \ifcsundef{glo@\glsdetoklabel{#2}@symbolaccess}% + {#1}% + {\@gls@fieldaccess@display{#2}{symbol}{#1}{\glsentrysymbolaccess{#2}}}% +} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\glssymbolpluralaccessdisplay} +%\changes{4.45}{2020-02-13}{added check for existence} +% As above but for the \gloskey{symbolpluralaccess} replacement text. +% \begin{macrocode} +\newrobustcmd*{\glssymbolpluralaccessdisplay}[2]{% + \ifcsundef{glo@\glsdetoklabel{#2}@symbolpluralaccess}% + {#1}% + {\@gls@fieldaccess@display{#2}{symbolplural}{#1}{\glsentrysymbolpluralaccess{#2}}}% } % \end{macrocode} %\end{macro} %\begin{macro}{\glsdescriptionaccessdisplay} +%\changes{4.45}{2020-02-13}{added check for existence} % As above but for the \gloskey{descriptionaccess} replacement text. % \begin{macrocode} -\DeclareRobustCommand*{\glsdescriptionaccessdisplay}[2]{% - \@gls@access@display{#1}{\glsentrydescaccess{#2}}% +\newrobustcmd*{\glsdescriptionaccessdisplay}[2]{% + \ifcsundef{glo@\glsdetoklabel{#2}@descaccess}% + {#1}% + {\@gls@fieldaccess@display{#2}{desc}{#1}{\glsentrydescaccess{#2}}}% } % \end{macrocode} %\end{macro} %\begin{macro}{\glsdescriptionpluralaccessdisplay} +%\changes{4.45}{2020-02-13}{added check for existence} % As above but for the \gloskey{descriptionpluralaccess} replacement text. % \begin{macrocode} -\DeclareRobustCommand*{\glsdescriptionpluralaccessdisplay}[2]{% - \@gls@access@display{#1}{\glsentrydescpluralaccess{#2}}% +\newrobustcmd*{\glsdescriptionpluralaccessdisplay}[2]{% + \ifcsundef{glo@\glsdetoklabel{#2}@descpluralaccess}% + {#1}% + {\@gls@fieldaccess@display{#2}{descplural}{#1}{\glsentrydescpluralaccess{#2}}}% } % \end{macrocode} %\end{macro} %\begin{macro}{\glsshortaccessdisplay} +%\changes{4.45}{2020-02-13}{added check for existence} % As above but for the \gloskey{shortaccess} replacement text. % \begin{macrocode} -\DeclareRobustCommand*{\glsshortaccessdisplay}[2]{% - \@gls@access@display{#1}{\glsentryshortaccess{#2}}% +\newrobustcmd*{\glsshortaccessdisplay}[2]{% + \ifcsundef{glo@\glsdetoklabel{#2}@shortaccess}% + {#1}% + {\@gls@fieldaccess@display{#2}{short}{#1}{\glsentryshortaccess{#2}}}% } % \end{macrocode} %\end{macro} % %\begin{macro}{\glsshortpluralaccessdisplay} +%\changes{4.45}{2020-02-13}{added check for existence} % As above but for the \gloskey{shortpluralaccess} replacement text. % \begin{macrocode} -\DeclareRobustCommand*{\glsshortpluralaccessdisplay}[2]{% - \@gls@access@display{#1}{\glsentryshortpluralaccess{#2}}% +\newrobustcmd*{\glsshortpluralaccessdisplay}[2]{% + \ifcsundef{glo@\glsdetoklabel{#2}@shortpluralaccess}% + {#1}% + {\@gls@fieldaccess@display{#2}{shortpl}{#1}{\glsentryshortpluralaccess{#2}}}% } % \end{macrocode} %\end{macro} %\begin{macro}{\glslongaccessdisplay} +%\changes{4.45}{2020-02-13}{added check for existence} % As above but for the \gloskey{longaccess} replacement text. % \begin{macrocode} -\DeclareRobustCommand*{\glslongaccessdisplay}[2]{% - \@gls@access@display{#1}{\glsentrylongaccess{#2}}% +\newrobustcmd*{\glslongaccessdisplay}[2]{% + \ifcsundef{glo@\glsdetoklabel{#2}@longaccess}% + {#1}% + {\@gls@fieldaccess@display{#2}{long}{#1}{\glsentrylongaccess{#2}}}% } % \end{macrocode} %\end{macro} % %\begin{macro}{\glslongpluralaccessdisplay} +%\changes{4.45}{2020-02-13}{added check for existence} % As above but for the \gloskey{longpluralaccess} replacement text. % \begin{macrocode} -\DeclareRobustCommand*{\glslongpluralaccessdisplay}[2]{% - \@gls@access@display{#1}{\glsentrylongpluralaccess{#2}}% +\newrobustcmd*{\glslongpluralaccessdisplay}[2]{% + \ifcsundef{glo@\glsdetoklabel{#2}@longpluralaccess}% + {#1}% + {\@gls@fieldaccess@display{#2}{longpl}{#1}{\glsentrylongpluralaccess{#2}}}% } % \end{macrocode} %\end{macro} % +%\begin{macro}{\glsuseriaccessdisplay} +%\changes{4.45}{2020-02-13}{new} +% As above but for the \gloskey{user1access} replacement text. +% \begin{macrocode} +\newrobustcmd*{\glsuseriaccessdisplay}[2]{% + \ifcsundef{glo@\glsdetoklabel{#2}@useriaccess}% + {#1}% + {\@gls@fieldaccess@display{#2}{useri}{#1}{\glsentryuseriaccess{#2}}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\glsuseriiaccessdisplay} +%\changes{4.45}{2020-02-13}{new} +% As above but for the \gloskey{user2access} replacement text. +% \begin{macrocode} +\newrobustcmd*{\glsuseriiaccessdisplay}[2]{% + \ifcsundef{glo@\glsdetoklabel{#2}@useriiaccess}% + {#1}% + {\@gls@fieldaccess@display{#2}{userii}{#1}{\glsentryuseriiaccess{#2}}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\glsuseriiiaccessdisplay} +%\changes{4.45}{2020-02-13}{new} +% As above but for the \gloskey{user3access} replacement text. +% \begin{macrocode} +\newrobustcmd*{\glsuseriiiaccessdisplay}[2]{% + \ifcsundef{glo@\glsdetoklabel{#2}@useriiiaccess}% + {#1}% + {\@gls@fieldaccess@display{#2}{useriii}{#1}{\glsentryuseriiiaccess{#2}}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\glsuserivaccessdisplay} +%\changes{4.45}{2020-02-13}{new} +% As above but for the \gloskey{user4access} replacement text. +% \begin{macrocode} +\newrobustcmd*{\glsuserivaccessdisplay}[2]{% + \ifcsundef{glo@\glsdetoklabel{#2}@userivaccess}% + {#1}% + {\@gls@fieldaccess@display{#2}{useriv}{#1}{\glsentryuserivaccess{#2}}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\glsuservaccessdisplay} +%\changes{4.45}{2020-02-13}{new} +% As above but for the \gloskey{user5access} replacement text. +% \begin{macrocode} +\newrobustcmd*{\glsuservaccessdisplay}[2]{% + \ifcsundef{glo@\glsdetoklabel{#2}@uservaccess}% + {#1}% + {\@gls@fieldaccess@display{#2}{userv}{#1}{\glsentryuservaccess{#2}}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\glsuserviaccessdisplay} +%\changes{4.45}{2020-02-13}{new} +% As above but for the \gloskey{user6access} replacement text. +% \begin{macrocode} +\newrobustcmd*{\glsuserviaccessdisplay}[2]{% + \ifcsundef{glo@\glsdetoklabel{#2}@userviaccess}% + {#1}% + {\@gls@fieldaccess@display{#2}{uservi}{#1}{\glsentryuserviaccess{#2}}}% +} +% \end{macrocode} +%\end{macro} +% +%\changes{4.25}{??}{changed \cs{DeclareRobustCommand} to +%\cs{newrobustcmd} and changed \cs{@ifundefined} to \cs{ifcsundef}} %\begin{macro}{\glsaccessdisplay} % Gets the replacement text corresponding to the named key given % by the first argument and calls the appropriate command % defined above. % \begin{macrocode} -\DeclareRobustCommand*{\glsaccessdisplay}[3]{% - \@ifundefined{gls#1accessdisplay}% +\newrobustcmd*{\glsaccessdisplay}[3]{% + \ifcsundef{gls#1accessdisplay}% {% \PackageError{glossaries-accsupp}{No accessibility support for key `#1'}{}% @@ -26244,6 +26919,441 @@ you % \end{macrocode} %\end{macro} % +%\begin{macro}{\@glstext@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@glstext@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glstextaccessdisplay{\glsentrytext{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@Glstext@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@Glstext@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glstextaccessdisplay{\Glsentrytext{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@GLStext@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@GLStext@#1#2[#3]{% + \@gls@field@link{#1}{#2}% + {\glstextaccessdisplay{\mfirstucMakeUppercase{\glsentrytext{#2}}}{#2}% + \mfirstucMakeUppercase{#3}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@glsfirst@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@glsfirst@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsfirstaccessdisplay{\glsentryfirst{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@Glsfirst@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@Glsfirst@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsfirstaccessdisplay{\Glsentryfirst{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@GLSfirst@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@GLSfirst@#1#2[#3]{% + \@gls@field@link{#1}{#2}% + {\glsfirstaccessdisplay{\mfirstucMakeUppercase{\glsentryfirst{#2}}}{#2}% + \mfirstucMakeUppercase{#3}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@glsplural@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@glsplural@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glspluralaccessdisplay{\glsentryplural{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@Glsplural@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@Glsplural@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glspluralaccessdisplay{\Glsentryplural{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@GLSplural@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@GLSplural@#1#2[#3]{% + \@gls@field@link{#1}{#2}% + {\glspluralaccessdisplay{\mfirstucMakeUppercase{\glsentryplural{#2}}}{#2}% + \mfirstucMakeUppercase{#3}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@glsfirstplural@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@glsfirstplural@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsfirstpluralaccessdisplay{\glsentryfirstplural{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@Glsfirstplural@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@glsfirstplural@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsfirstpluralaccessdisplay{\Glsentryfirstplural{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@GLSfirstplural@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@GLSfirstplural@#1#2[#3]{% + \@gls@field@link{#1}{#2}% + {\glsfirstpluralaccessdisplay{\mfirstucMakeUppercase{\glsentryfirstplural{#2}}}{#2}% + \mfirstucMakeUppercase{#3}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@glsname@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@glsname@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsnameaccessdisplay{\glsentryname{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@Glsname@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@Glsname@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsnameaccessdisplay{\Glsentryname{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@GLSname@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@GLSname@#1#2[#3]{% + \@gls@field@link{#1}{#2}% + {\glsnameaccessdisplay{\mfirstucMakeUppercase{\glsentryname{#2}}}{#2}% + \mfirstucMakeUppercase{#3}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@glsdesc@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@glsdesc@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsdescriptionaccessdisplay{\glsentrydesc{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@Glsdesc@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@Glsdesc@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsdescriptionaccessdisplay{\Glsentrydesc{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@GLSdesc@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@GLSdesc@#1#2[#3]{% + \@gls@field@link{#1}{#2}% + {\glsdescriptionaccessdisplay{\mfirstucMakeUppercase{\glsentrydesc{#2}}}{#2}% + \mfirstucMakeUppercase{#3}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@glsdescplural@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@glsdescplural@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsdescriptionpluralaccessdisplay{\glsentrydescplural{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@Glsdescplural@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@Glsdescplural@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsdescriptionpluralaccessdisplay{\Glsentrydescplural{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@GLSdescplural@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@GLSdescplural@#1#2[#3]{% + \@gls@field@link{#1}{#2}% + {\glsdescriptionpluralaccessdisplay{\mfirstucMakeUppercase{\glsentrydescplural{#2}}}{#2}% + \mfirstucMakeUppercase{#3}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@glssymbol@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@glssymbol@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glssymbolaccessdisplay{\glsentrysymbol{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@Glssymbol@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@Glssymbol@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glssymbolaccessdisplay{\Glsentrysymbol{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@GLSsymbol@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@GLSsymbol@#1#2[#3]{% + \@gls@field@link{#1}{#2}% + {\glssymbolaccessdisplay{\mfirstucMakeUppercase{\glsentrysymbol{#2}}}{#2}% + \mfirstucMakeUppercase{#3}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@glssymbolplural@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@glssymbolplural@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glssymbolpluralaccessdisplay{\glsentrysymbolplural{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@Glssymbolplural@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@Glssymbolplural@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glssymbolpluralaccessdisplay{\Glsentrysymbolplural{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@GLSsymbolplural@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@GLSsymbolplural@#1#2[#3]{% + \@gls@field@link{#1}{#2}% + {\glssymbolpluralaccessdisplay{\mfirstucMakeUppercase{\glsentrysymbolplural{#2}}}{#2}% + \mfirstucMakeUppercase{#3}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@glsuseri@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@glsuseri@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsuseriaccessdisplay{\glsentryuseri{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@Glsuseri@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@Glsuser@i#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsuseriaccessdisplay{\Glsentryuseri{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@GLSuseri@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@GLSuseri@#1#2[#3]{% + \@gls@field@link{#1}{#2}% + {\glsuseriaccessdisplay{\mfirstucMakeUppercase{\glsentryuseri{#2}}}{#2}% + \mfirstucMakeUppercase{#3}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@glsuserii@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@glsuserii@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsuseriiaccessdisplay{\glsentryuserii{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@Glsuserii@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@Glsuser@i#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsuseriiaccessdisplay{\Glsentryuserii{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@GLSuserii@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@GLSuserii@#1#2[#3]{% + \@gls@field@link{#1}{#2}% + {\glsuseriiaccessdisplay{\mfirstucMakeUppercase{\glsentryuserii{#2}}}{#2}% + \mfirstucMakeUppercase{#3}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@glsuseriii@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@glsuseriii@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsuseriiiaccessdisplay{\glsentryuseriii{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@Glsuseriii@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@Glsuser@i#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsuseriiiaccessdisplay{\Glsentryuseriii{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@GLSuseriii@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@GLSuseriii@#1#2[#3]{% + \@gls@field@link{#1}{#2}% + {\glsuseriiiaccessdisplay{\mfirstucMakeUppercase{\glsentryuseriii{#2}}}{#2}% + \mfirstucMakeUppercase{#3}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@glsuseriv@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@glsuseriv@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsuserivaccessdisplay{\glsentryuseriv{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@Glsuseriv@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@Glsuser@i#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsuserivaccessdisplay{\Glsentryuseriv{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@GLSuseriv@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@GLSuseriv@#1#2[#3]{% + \@gls@field@link{#1}{#2}% + {\glsuserivaccessdisplay{\mfirstucMakeUppercase{\glsentryuseriv{#2}}}{#2}% + \mfirstucMakeUppercase{#3}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@glsuserv@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@glsuserv@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsuservaccessdisplay{\glsentryuserv{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@Glsuserv@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@Glsuser@i#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsuservaccessdisplay{\Glsentryuserv{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@GLSuserv@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@GLSuserv@#1#2[#3]{% + \@gls@field@link{#1}{#2}% + {\glsuservaccessdisplay{\mfirstucMakeUppercase{\glsentryuserv{#2}}}{#2}% + \mfirstucMakeUppercase{#3}}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@glsuservi@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@glsuservi@#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsuserviaccessdisplay{\glsentryuservi{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@Glsuservi@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@Glsuser@i#1#2[#3]{% + \@gls@field@link{#1}{#2}{\glsuserviaccessdisplay{\Glsentryuservi{#2}}{#2}#3}% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\@GLSuservi@} +%\changes{4.45}{2020-02-13}{added accessibility support} +% \begin{macrocode} +\def\@GLSuservi@#1#2[#3]{% + \@gls@field@link{#1}{#2}% + {\glsuserviaccessdisplay{\mfirstucMakeUppercase{\glsentryuservi{#2}}}{#2}% + \mfirstucMakeUppercase{#3}}% +} +% \end{macrocode} +%\end{macro} +% %\section{Displaying the Glossary} %\changes{3.08a}{2013-09-28}{removed definition of \cs{@glossaryentryfield}} %\changes{3.08a}{2013-09-28}{removed definition of \cs{@glossarysubentryfield}} @@ -26906,11 +28016,24 @@ you % \end{macrocode} %\end{acrstyle} % +%\begin{macro}{\glsdefaultshortaccess} +%\changes{4.45}{2020-02-13}{new} +%\begin{definition} +%\cs{glsdefaultshortaccess}\marg{long}\marg{short} +%\end{definition} +%Default \gloskey{shortaccess} value. +% \begin{macrocode} +\newcommand*{\glsdefaultshortaccess}[2]{#1} +% \end{macrocode} +%\end{macro} +% % Use \cs{newacronymhook} to modify the key list to set % the access text to the long version by default. % \begin{macrocode} \renewcommand*{\newacronymhook}{% - \edef\@gls@keylist{shortaccess=\the\glslongtok,% + \edef\@gls@keylist{% + shortaccess={\glsdefaultshortaccess{\the\glslongtok}{\the\glsshorttok}},% + shortpluralaccess={\glsdefaultshortaccess{\the\glslongtok}{\the\glsshorttok}},% \the\glskeylisttok}% \expandafter\glskeylisttok\expandafter{\@gls@keylist}% } @@ -26931,7 +28054,7 @@ you sort={\the\glsshorttok},% short={\the\glsshorttok},% shortplural={\the\glsshorttok\noexpand\acrpluralsuffix},% - shortaccess={\the\glslongtok},% + shortaccess={\glsdefaultshortaccess{\the\glslongtok}{\the\glsshorttok}},% long={\the\glslongtok},% longplural={\the\glslongtok\noexpand\acrpluralsuffix},% descriptionplural={\the\glslongtok\noexpand\acrpluralsuffix},% @@ -26981,7 +28104,7 @@ you text={\the\glsshorttok},% short={\the\glsshorttok},% shortplural={\the\glsshorttok\noexpand\acrpluralsuffix},% - shortaccess={\the\glslongtok},% + shortaccess={\glsdefaultshortaccess{\the\glslongtok}{\the\glsshorttok}},% long={\the\glslongtok},% longplural={\the\glslongtok\noexpand\acrpluralsuffix},% access={\noexpand\@glo@textaccess},% @@ -27025,7 +28148,7 @@ you sort={\the\glsshorttok},% short={\the\glsshorttok},% shortplural={\the\glsshorttok\noexpand\acrpluralsuffix},% - shortaccess={\the\glslongtok},% + shortaccess={\glsdefaultshortaccess{\the\glslongtok}{\the\glsshorttok}},% long={\the\glslongtok},% longplural={\the\glslongtok\noexpand\acrpluralsuffix},% first={\the\glslongtok},% @@ -27113,7 +28236,7 @@ you sort={\the\glsshorttok},% short={\the\glsshorttok},% shortplural={\the\glsshorttok\noexpand\acrpluralsuffix},% - shortaccess={\the\glslongtok},% + shortaccess={\glsdefaultshortaccess{\the\glslongtok}{\the\glsshorttok}},% long={\the\glslongtok},% longplural={\the\glslongtok\noexpand\acrpluralsuffix},% text={\noexpand\@glo@short},% @@ -27301,7 +28424,7 @@ you % modules. % \begin{macrocode} \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{glossaries-babel}[2019/12/06 v4.44 (NLCT)] +\ProvidesPackage{glossaries-babel}[2020/02/13 v4.45 (NLCT)] % \end{macrocode} % Load \sty{tracklang} to obtain language settings. % \begin{macrocode} @@ -27345,7 +28468,7 @@ you % modules. % \begin{macrocode} \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{glossaries-polyglossia}[2019/12/06 v4.44 (NLCT)] +\ProvidesPackage{glossaries-polyglossia}[2020/02/13 v4.45 (NLCT)] % \end{macrocode} % Load \sty{tracklang} to obtain language settings. % \begin{macrocode} @@ -27386,8 +28509,10 @@ you %\fi %\iffalse % \begin{macrocode} - % This file is part of the glossaries bundle - % These are test acronym entries with descriptions. +%<

    The glossaries package v4.44: a guide for +class="cmr-17">The glossaries package v4.45: a guide for beginners

    @@ -274,7 +276,7 @@ class="td11"> Nicola L.C. Talbot

    2019-12-06

    +class="cmr-12">2020-02-13

    @@ -670,7 +672,9 @@ them all in the document, so “turnip” appears in the glossary even t \gls{turnip} (or similar) in the document.

    The sort=nonesort=none option isn’t essential in this case (there’s no other sort option available for this document), but it prevents the automatic construction of the sort value and so slightly improves the document build time. @@ -1740,7 +1744,7 @@ package. These are also available with the extension package glossaries-extra along with a fourth option. These four options are listed below in a little more detail. Table 1 summarises the main advantages and disadvantages. +href="#tab:optionsp+c">Table 1 summarises the main advantages and disadvantages. (There’s a more detailed summary in the main glossaries user manual.) See also .



    @@ -1956,9 +1960,13 @@ class="cmtt-10">sort value must be supplied) unless you have the package option sanitizesort or sort=defsort=def or sort=usesort=use.

    1. \printglossaries

    command doesn’t have any arguments.

    All glossaries are sorted using the same method which may be identified with one of the package options: sort=standardsort=standard (default), sort=usesort=use or sort=defsort=def.

    @@ -2197,7 +2211,9 @@ class="cmss-10">automake

    The default sort is word order (“sea lion” comes before “seal”). If you want letter ordering you need to add the order=letterorder=letter package option @@ -2324,12 +2340,18 @@ class="cmtt-10">\printglossaries


    All glossaries are sorted using the same method which may be identified with one of the package options: sort=standardsort=standard (default), sort=usesort=use or sort=defsort=def.

    @@ -2708,7 +2730,9 @@ class="description">By default, the accent command will be stripped so the sort will be elite. This will put the entry in the “E” letter group. However if you use the sanitizesort=truesanitizesort=true package option, the sort value will be interpreted as the sequence of characters: { :
    By default the sort value will be interpreted as elite so the entry will be put in the “E” letter group. If you use the sanitizesort=truesanitizesort=true package option, the sort value will be interpreted as é

    If you want the hyperlinks suppressed the first time an entry is used, but you want hyperlinks for subsequence references then use the hyperfirst=falsehyperfirst=false package option: diff --git a/macros/latex/contrib/glossaries/glossariesbegin.pdf b/macros/latex/contrib/glossaries/glossariesbegin.pdf index b541ca9147..bfdff9d737 100644 Binary files a/macros/latex/contrib/glossaries/glossariesbegin.pdf and b/macros/latex/contrib/glossaries/glossariesbegin.pdf differ diff --git a/macros/latex/contrib/glossaries/glossariesbegin.tex b/macros/latex/contrib/glossaries/glossariesbegin.tex index 03ab7be4ab..e0793626a8 100644 --- a/macros/latex/contrib/glossaries/glossariesbegin.tex +++ b/macros/latex/contrib/glossaries/glossariesbegin.tex @@ -31,10 +31,10 @@ \texorpdfstring{{\frenchspacing\obeyspaces\ttfamily#1}}{#1}} \newcommand*{\file}[1]{\texorpdfstring{\texttt{#1}}{#1}} -\title{The glossaries package v4.44: +\title{The glossaries package v4.45: a guide for beginners} \author{Nicola L.C. Talbot} -\date{2019-12-06} +\date{2020-02-13} \ifpdf \externaldocument{glossaries-user} diff --git a/macros/latex/contrib/glossaries/glossary2glossaries.html b/macros/latex/contrib/glossaries/glossary2glossaries.html index 38391e1d5a..e733386eb1 100644 --- a/macros/latex/contrib/glossaries/glossary2glossaries.html +++ b/macros/latex/contrib/glossaries/glossary2glossaries.html @@ -55,10 +55,11 @@ .cmtt-9{font-family: monospace;} .cmtt-9{font-family: monospace;} .cmti-8{font-size:80%; font-style: italic;} -p.noindent { text-indent: 0em } -td p.noindent { text-indent: 0em; margin-top:0em; } -p.nopar { text-indent: 0em; } -p.indent{ text-indent: 1.5em } +p{margin-top:0;margin-bottom:0} +p.indent{text-indent:0;} +p + p{margin-top:1em;} +p + div, p + pre {margin-top:1em;} +div + p, pre + p {margin-top:1em;} @media print {div.crosslinks {visibility:hidden;}} a img { border-top: 0; border-left: 0; border-right: 0; } center { margin-top:1em; margin-bottom:1em; } @@ -81,7 +82,7 @@ div.obeylines-v p { margin-top:0; margin-bottom:0; } td.displaylines {text-align:center; white-space:nowrap;} .centerline {text-align:center;} .rightline {text-align:right;} -div.verbatim {font-family: monospace; white-space: nowrap; text-align:left; clear:both; } +div.verbatim {font-family: monospace,monospace; white-space: nowrap; text-align:left; clear:both; } .fbox {padding-left:3.0pt; padding-right:3.0pt; text-indent:0pt; border:solid black 0.4pt; } div.fbox {display:table} div.center div.fbox {text-align:center; clear:both; padding-left:3.0pt; padding-right:3.0pt; text-indent:0pt; border:solid black 0.4pt; } @@ -166,6 +167,7 @@ div.thanks{text-align:left; margin-left:10%; font-size:85%; font-style:italic; } .quotation {margin-bottom:0.25em; margin-top:0.25em; margin-left:1em; } .abstract p {margin-left:5%; margin-right:5%;} div.abstract {width:100%;} +.warningsymbol { color: red; font-weight: bold;} div.important { border : solid red; } div.verbatim { font-family: monospace; white-space: nowrap; text-align:left; clear:both; padding-top: 2ex; padding-bottom: 2ex;} /* end css.sty */ @@ -203,7 +205,7 @@ class="td11">Nicola L.C. Talbot

    2019-12-06

    +class="cmr-12">2020-02-13

    @@ -1725,7 +1727,7 @@ href="glossary2glossaries.html#dx1-17001" >2
    class="cmbx-10">G glossaries-extra package  3
    +href="glossary2glossaries.html#dx1-17007" >3
    \gls options
         % -\def\ExplFileDate{2020-02-11}% +\def\ExplFileDate{2020-02-14}% %<*driver> \documentclass[full]{l3doc} \usepackage{graphicx} @@ -51,7 +51,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/expl3.pdf b/macros/latex/contrib/l3kernel/expl3.pdf index c13e809ce6..1b960ecfeb 100644 Binary files a/macros/latex/contrib/l3kernel/expl3.pdf and b/macros/latex/contrib/l3kernel/expl3.pdf differ diff --git a/macros/latex/contrib/l3kernel/interface3.pdf b/macros/latex/contrib/l3kernel/interface3.pdf index 78a1518ad7..409fe8a4a0 100644 Binary files a/macros/latex/contrib/l3kernel/interface3.pdf and b/macros/latex/contrib/l3kernel/interface3.pdf differ diff --git a/macros/latex/contrib/l3kernel/interface3.tex b/macros/latex/contrib/l3kernel/interface3.tex index b7f21aba37..978ae8c047 100644 --- a/macros/latex/contrib/l3kernel/interface3.tex +++ b/macros/latex/contrib/l3kernel/interface3.tex @@ -54,7 +54,7 @@ for those people who are interested. {latex-team@latex-project.org}% }% } -\date{Released 2020-02-11} +\date{Released 2020-02-14} \pagenumbering{roman} \maketitle diff --git a/macros/latex/contrib/l3kernel/l3alloc.dtx b/macros/latex/contrib/l3kernel/l3alloc.dtx index d9f5640f97..57febba398 100644 --- a/macros/latex/contrib/l3kernel/l3alloc.dtx +++ b/macros/latex/contrib/l3kernel/l3alloc.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3basics.dtx b/macros/latex/contrib/l3kernel/l3basics.dtx index d03785c5de..af0a47b3c2 100644 --- a/macros/latex/contrib/l3kernel/l3basics.dtx +++ b/macros/latex/contrib/l3kernel/l3basics.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3bootstrap.dtx b/macros/latex/contrib/l3kernel/l3bootstrap.dtx index cecfdeeff9..20da5f69c4 100644 --- a/macros/latex/contrib/l3kernel/l3bootstrap.dtx +++ b/macros/latex/contrib/l3kernel/l3bootstrap.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3box.dtx b/macros/latex/contrib/l3kernel/l3box.dtx index 13a870890d..fd426abaa4 100644 --- a/macros/latex/contrib/l3kernel/l3box.dtx +++ b/macros/latex/contrib/l3kernel/l3box.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3candidates.dtx b/macros/latex/contrib/l3kernel/l3candidates.dtx index c490fc4e3e..1191a45bd5 100644 --- a/macros/latex/contrib/l3kernel/l3candidates.dtx +++ b/macros/latex/contrib/l3kernel/l3candidates.dtx @@ -44,7 +44,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3clist.dtx b/macros/latex/contrib/l3kernel/l3clist.dtx index 97a1da29cf..5d2354960e 100644 --- a/macros/latex/contrib/l3kernel/l3clist.dtx +++ b/macros/latex/contrib/l3kernel/l3clist.dtx @@ -44,7 +44,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3coffins.dtx b/macros/latex/contrib/l3kernel/l3coffins.dtx index e8d23fd991..2689143b69 100644 --- a/macros/latex/contrib/l3kernel/l3coffins.dtx +++ b/macros/latex/contrib/l3kernel/l3coffins.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3color-base.dtx b/macros/latex/contrib/l3kernel/l3color-base.dtx index bc4a100cad..39c172e86c 100644 --- a/macros/latex/contrib/l3kernel/l3color-base.dtx +++ b/macros/latex/contrib/l3kernel/l3color-base.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3debug.dtx b/macros/latex/contrib/l3kernel/l3debug.dtx index 1b14f809de..cbb8978962 100644 --- a/macros/latex/contrib/l3kernel/l3debug.dtx +++ b/macros/latex/contrib/l3kernel/l3debug.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3deprecation.dtx b/macros/latex/contrib/l3kernel/l3deprecation.dtx index 21d6709a0a..3153236733 100644 --- a/macros/latex/contrib/l3kernel/l3deprecation.dtx +++ b/macros/latex/contrib/l3kernel/l3deprecation.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3doc.dtx b/macros/latex/contrib/l3kernel/l3doc.dtx index 4ba2ebd5f0..77064b0c22 100644 --- a/macros/latex/contrib/l3kernel/l3doc.dtx +++ b/macros/latex/contrib/l3kernel/l3doc.dtx @@ -79,7 +79,7 @@ and all files in that bundle must be distributed together. % % \title{The \cls{l3doc} class} % \author{\Team} -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % \maketitle % \tableofcontents % diff --git a/macros/latex/contrib/l3kernel/l3docstrip.dtx b/macros/latex/contrib/l3kernel/l3docstrip.dtx index 6b160328a5..014ce1cdfe 100644 --- a/macros/latex/contrib/l3kernel/l3docstrip.dtx +++ b/macros/latex/contrib/l3kernel/l3docstrip.dtx @@ -63,7 +63,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3docstrip.pdf b/macros/latex/contrib/l3kernel/l3docstrip.pdf index c0b71f6359..deea285c8e 100644 Binary files a/macros/latex/contrib/l3kernel/l3docstrip.pdf and b/macros/latex/contrib/l3kernel/l3docstrip.pdf differ diff --git a/macros/latex/contrib/l3kernel/l3expan.dtx b/macros/latex/contrib/l3kernel/l3expan.dtx index ce01cac326..dfd69c140b 100644 --- a/macros/latex/contrib/l3kernel/l3expan.dtx +++ b/macros/latex/contrib/l3kernel/l3expan.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3file.dtx b/macros/latex/contrib/l3kernel/l3file.dtx index 978b6d78c5..700542c8e8 100644 --- a/macros/latex/contrib/l3kernel/l3file.dtx +++ b/macros/latex/contrib/l3kernel/l3file.dtx @@ -44,7 +44,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3final.dtx b/macros/latex/contrib/l3kernel/l3final.dtx index 07d59e992f..4fcfa233a0 100644 --- a/macros/latex/contrib/l3kernel/l3final.dtx +++ b/macros/latex/contrib/l3kernel/l3final.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3flag.dtx b/macros/latex/contrib/l3kernel/l3flag.dtx index 91c48a52d0..20e4a536ae 100644 --- a/macros/latex/contrib/l3kernel/l3flag.dtx +++ b/macros/latex/contrib/l3kernel/l3flag.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-assign.dtx b/macros/latex/contrib/l3kernel/l3fp-assign.dtx index 4dbc9d8ce2..3dd85c77dd 100644 --- a/macros/latex/contrib/l3kernel/l3fp-assign.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-assign.dtx @@ -40,7 +40,7 @@ % {latex-team@latex-project.org}^^A % }^^A % } -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % \maketitle % % \begin{documentation} diff --git a/macros/latex/contrib/l3kernel/l3fp-aux.dtx b/macros/latex/contrib/l3kernel/l3fp-aux.dtx index 4137dde05b..de6ecdb2df 100644 --- a/macros/latex/contrib/l3kernel/l3fp-aux.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-aux.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-basics.dtx b/macros/latex/contrib/l3kernel/l3fp-basics.dtx index aba86520eb..87083fb6ff 100644 --- a/macros/latex/contrib/l3kernel/l3fp-basics.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-basics.dtx @@ -40,7 +40,7 @@ % {latex-team@latex-project.org}^^A % }^^A % } -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-convert.dtx b/macros/latex/contrib/l3kernel/l3fp-convert.dtx index 1f67ce5a0d..38398f5c98 100644 --- a/macros/latex/contrib/l3kernel/l3fp-convert.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-convert.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-expo.dtx b/macros/latex/contrib/l3kernel/l3fp-expo.dtx index f4b1fd9a16..c409db18b7 100644 --- a/macros/latex/contrib/l3kernel/l3fp-expo.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-expo.dtx @@ -40,7 +40,7 @@ % {latex-team@latex-project.org}^^A % }^^A % } -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-extended.dtx b/macros/latex/contrib/l3kernel/l3fp-extended.dtx index fe67c391f4..a59acfbd22 100644 --- a/macros/latex/contrib/l3kernel/l3fp-extended.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-extended.dtx @@ -40,7 +40,7 @@ % {latex-team@latex-project.org}^^A % }^^A % } -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-logic.dtx b/macros/latex/contrib/l3kernel/l3fp-logic.dtx index 17fb80e10c..315b21d543 100644 --- a/macros/latex/contrib/l3kernel/l3fp-logic.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-logic.dtx @@ -40,7 +40,7 @@ % {latex-team@latex-project.org}^^A % }^^A % } -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-parse.dtx b/macros/latex/contrib/l3kernel/l3fp-parse.dtx index 75d1f9db4c..7118c0bad2 100644 --- a/macros/latex/contrib/l3kernel/l3fp-parse.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-parse.dtx @@ -40,7 +40,7 @@ % {latex-team@latex-project.org}^^A % }^^A % } -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-random.dtx b/macros/latex/contrib/l3kernel/l3fp-random.dtx index 99bf9e5d97..4b46f545fb 100644 --- a/macros/latex/contrib/l3kernel/l3fp-random.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-random.dtx @@ -40,7 +40,7 @@ % {latex-team@latex-project.org}^^A % }^^A % } -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-round.dtx b/macros/latex/contrib/l3kernel/l3fp-round.dtx index fbcd25c2f0..a787adfb94 100644 --- a/macros/latex/contrib/l3kernel/l3fp-round.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-round.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-traps.dtx b/macros/latex/contrib/l3kernel/l3fp-traps.dtx index 9defc471b7..4eb0387a16 100644 --- a/macros/latex/contrib/l3kernel/l3fp-traps.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-traps.dtx @@ -40,7 +40,7 @@ % {latex-team@latex-project.org}^^A % }^^A % } -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % \maketitle % % \begin{documentation} diff --git a/macros/latex/contrib/l3kernel/l3fp-trig.dtx b/macros/latex/contrib/l3kernel/l3fp-trig.dtx index 38a91e91c3..2be7c7805e 100644 --- a/macros/latex/contrib/l3kernel/l3fp-trig.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-trig.dtx @@ -40,7 +40,7 @@ % {latex-team@latex-project.org}^^A % }^^A % } -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp.dtx b/macros/latex/contrib/l3kernel/l3fp.dtx index ea1d998bc7..2cfa4be072 100644 --- a/macros/latex/contrib/l3kernel/l3fp.dtx +++ b/macros/latex/contrib/l3kernel/l3fp.dtx @@ -49,7 +49,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fparray.dtx b/macros/latex/contrib/l3kernel/l3fparray.dtx index d9e82ecf14..8b5f336004 100644 --- a/macros/latex/contrib/l3kernel/l3fparray.dtx +++ b/macros/latex/contrib/l3kernel/l3fparray.dtx @@ -44,7 +44,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3int.dtx b/macros/latex/contrib/l3kernel/l3int.dtx index ccf83c2be4..d08ea5e3da 100644 --- a/macros/latex/contrib/l3kernel/l3int.dtx +++ b/macros/latex/contrib/l3kernel/l3int.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3intarray.dtx b/macros/latex/contrib/l3kernel/l3intarray.dtx index bff15a9db0..6409bf8579 100644 --- a/macros/latex/contrib/l3kernel/l3intarray.dtx +++ b/macros/latex/contrib/l3kernel/l3intarray.dtx @@ -44,7 +44,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3kernel-functions.dtx b/macros/latex/contrib/l3kernel/l3kernel-functions.dtx index b31ebb26fa..349cfdcbf3 100644 --- a/macros/latex/contrib/l3kernel/l3kernel-functions.dtx +++ b/macros/latex/contrib/l3kernel/l3kernel-functions.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3keys.dtx b/macros/latex/contrib/l3kernel/l3keys.dtx index eedd06ad24..6d4dccb440 100644 --- a/macros/latex/contrib/l3kernel/l3keys.dtx +++ b/macros/latex/contrib/l3kernel/l3keys.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3legacy.dtx b/macros/latex/contrib/l3kernel/l3legacy.dtx index b1732bbc99..dbbcf14802 100644 --- a/macros/latex/contrib/l3kernel/l3legacy.dtx +++ b/macros/latex/contrib/l3kernel/l3legacy.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3luatex.dtx b/macros/latex/contrib/l3kernel/l3luatex.dtx index b002ea7dfe..eadbf4d826 100644 --- a/macros/latex/contrib/l3kernel/l3luatex.dtx +++ b/macros/latex/contrib/l3kernel/l3luatex.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3msg.dtx b/macros/latex/contrib/l3kernel/l3msg.dtx index 89155d2ae9..9066ec39e5 100644 --- a/macros/latex/contrib/l3kernel/l3msg.dtx +++ b/macros/latex/contrib/l3kernel/l3msg.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3names.dtx b/macros/latex/contrib/l3kernel/l3names.dtx index 93f1d4904c..c914e08887 100644 --- a/macros/latex/contrib/l3kernel/l3names.dtx +++ b/macros/latex/contrib/l3kernel/l3names.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3news.pdf b/macros/latex/contrib/l3kernel/l3news.pdf index b234745283..ef955b569a 100644 Binary files a/macros/latex/contrib/l3kernel/l3news.pdf and b/macros/latex/contrib/l3kernel/l3news.pdf differ diff --git a/macros/latex/contrib/l3kernel/l3news01.pdf b/macros/latex/contrib/l3kernel/l3news01.pdf index 01c0852c90..bd8217c205 100644 Binary files a/macros/latex/contrib/l3kernel/l3news01.pdf and b/macros/latex/contrib/l3kernel/l3news01.pdf differ diff --git a/macros/latex/contrib/l3kernel/l3news02.pdf b/macros/latex/contrib/l3kernel/l3news02.pdf index 2c229749bf..62cb931491 100644 Binary files a/macros/latex/contrib/l3kernel/l3news02.pdf and b/macros/latex/contrib/l3kernel/l3news02.pdf differ diff --git a/macros/latex/contrib/l3kernel/l3news03.pdf b/macros/latex/contrib/l3kernel/l3news03.pdf index d5456adce5..b9971d0fb1 100644 Binary files a/macros/latex/contrib/l3kernel/l3news03.pdf and b/macros/latex/contrib/l3kernel/l3news03.pdf differ diff --git a/macros/latex/contrib/l3kernel/l3news04.pdf b/macros/latex/contrib/l3kernel/l3news04.pdf index aa30e6aa86..37eb05cbad 100644 Binary files a/macros/latex/contrib/l3kernel/l3news04.pdf and b/macros/latex/contrib/l3kernel/l3news04.pdf differ diff --git a/macros/latex/contrib/l3kernel/l3news05.pdf b/macros/latex/contrib/l3kernel/l3news05.pdf index 058e0c45b9..ed45c33482 100644 Binary files a/macros/latex/contrib/l3kernel/l3news05.pdf and b/macros/latex/contrib/l3kernel/l3news05.pdf differ diff --git a/macros/latex/contrib/l3kernel/l3news06.pdf b/macros/latex/contrib/l3kernel/l3news06.pdf index e479c35606..5ccb5e70dd 100644 Binary files a/macros/latex/contrib/l3kernel/l3news06.pdf and b/macros/latex/contrib/l3kernel/l3news06.pdf differ diff --git a/macros/latex/contrib/l3kernel/l3news07.pdf b/macros/latex/contrib/l3kernel/l3news07.pdf index e092ae8377..d43423b14c 100644 Binary files a/macros/latex/contrib/l3kernel/l3news07.pdf and b/macros/latex/contrib/l3kernel/l3news07.pdf differ diff --git a/macros/latex/contrib/l3kernel/l3news08.pdf b/macros/latex/contrib/l3kernel/l3news08.pdf index 250a8a3a3a..10eae77dbd 100644 Binary files a/macros/latex/contrib/l3kernel/l3news08.pdf and b/macros/latex/contrib/l3kernel/l3news08.pdf differ diff --git a/macros/latex/contrib/l3kernel/l3news09.pdf b/macros/latex/contrib/l3kernel/l3news09.pdf index 74fdd89c3d..f442fd3232 100644 Binary files a/macros/latex/contrib/l3kernel/l3news09.pdf and b/macros/latex/contrib/l3kernel/l3news09.pdf differ diff --git a/macros/latex/contrib/l3kernel/l3news10.pdf b/macros/latex/contrib/l3kernel/l3news10.pdf index 609892abd9..87c46fbcfc 100644 Binary files a/macros/latex/contrib/l3kernel/l3news10.pdf and b/macros/latex/contrib/l3kernel/l3news10.pdf differ diff --git a/macros/latex/contrib/l3kernel/l3news11.pdf b/macros/latex/contrib/l3kernel/l3news11.pdf index 7b2ce92e2e..f09f28d744 100644 Binary files a/macros/latex/contrib/l3kernel/l3news11.pdf and b/macros/latex/contrib/l3kernel/l3news11.pdf differ diff --git a/macros/latex/contrib/l3kernel/l3news12.pdf b/macros/latex/contrib/l3kernel/l3news12.pdf index ee01652891..dbe64d89de 100644 Binary files a/macros/latex/contrib/l3kernel/l3news12.pdf and b/macros/latex/contrib/l3kernel/l3news12.pdf differ diff --git a/macros/latex/contrib/l3kernel/l3prefixes.pdf b/macros/latex/contrib/l3kernel/l3prefixes.pdf index 2efaba3920..16ad9c07bd 100644 Binary files a/macros/latex/contrib/l3kernel/l3prefixes.pdf and b/macros/latex/contrib/l3kernel/l3prefixes.pdf differ diff --git a/macros/latex/contrib/l3kernel/l3prg.dtx b/macros/latex/contrib/l3kernel/l3prg.dtx index 5a6cb86293..db1d872e98 100644 --- a/macros/latex/contrib/l3kernel/l3prg.dtx +++ b/macros/latex/contrib/l3kernel/l3prg.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3prop.dtx b/macros/latex/contrib/l3kernel/l3prop.dtx index 5206bb972e..b8fc20d3a1 100644 --- a/macros/latex/contrib/l3kernel/l3prop.dtx +++ b/macros/latex/contrib/l3kernel/l3prop.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3quark.dtx b/macros/latex/contrib/l3kernel/l3quark.dtx index f5cef864af..bea3d69c65 100644 --- a/macros/latex/contrib/l3kernel/l3quark.dtx +++ b/macros/latex/contrib/l3kernel/l3quark.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3regex.dtx b/macros/latex/contrib/l3kernel/l3regex.dtx index 2576bfdcbe..d35f1b4be0 100644 --- a/macros/latex/contrib/l3kernel/l3regex.dtx +++ b/macros/latex/contrib/l3kernel/l3regex.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3seq.dtx b/macros/latex/contrib/l3kernel/l3seq.dtx index 38a051fdb6..296d40ee58 100644 --- a/macros/latex/contrib/l3kernel/l3seq.dtx +++ b/macros/latex/contrib/l3kernel/l3seq.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3skip.dtx b/macros/latex/contrib/l3kernel/l3skip.dtx index 6003981e29..96f6ceb9a9 100644 --- a/macros/latex/contrib/l3kernel/l3skip.dtx +++ b/macros/latex/contrib/l3kernel/l3skip.dtx @@ -44,7 +44,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3sort.dtx b/macros/latex/contrib/l3kernel/l3sort.dtx index 95b676436c..989645cd9d 100644 --- a/macros/latex/contrib/l3kernel/l3sort.dtx +++ b/macros/latex/contrib/l3kernel/l3sort.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3str-convert.dtx b/macros/latex/contrib/l3kernel/l3str-convert.dtx index a064fdd17e..db1a146602 100644 --- a/macros/latex/contrib/l3kernel/l3str-convert.dtx +++ b/macros/latex/contrib/l3kernel/l3str-convert.dtx @@ -44,7 +44,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3str.dtx b/macros/latex/contrib/l3kernel/l3str.dtx index f215feca48..3d1003d8ac 100644 --- a/macros/latex/contrib/l3kernel/l3str.dtx +++ b/macros/latex/contrib/l3kernel/l3str.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3styleguide.pdf b/macros/latex/contrib/l3kernel/l3styleguide.pdf index e99b023c32..5568185999 100644 Binary files a/macros/latex/contrib/l3kernel/l3styleguide.pdf and b/macros/latex/contrib/l3kernel/l3styleguide.pdf differ diff --git a/macros/latex/contrib/l3kernel/l3styleguide.tex b/macros/latex/contrib/l3kernel/l3styleguide.tex index 353cbd6c28..0123ba1d29 100644 --- a/macros/latex/contrib/l3kernel/l3styleguide.tex +++ b/macros/latex/contrib/l3kernel/l3styleguide.tex @@ -32,7 +32,7 @@ The released version of this bundle is available from CTAN. {latex-team@latex-project.org}% }% } -\date{Released 2020-02-11} +\date{Released 2020-02-14} \begin{document} diff --git a/macros/latex/contrib/l3kernel/l3syntax-changes.pdf b/macros/latex/contrib/l3kernel/l3syntax-changes.pdf index 8d7ad7840e..e4a99021d1 100644 Binary files a/macros/latex/contrib/l3kernel/l3syntax-changes.pdf and b/macros/latex/contrib/l3kernel/l3syntax-changes.pdf differ diff --git a/macros/latex/contrib/l3kernel/l3syntax-changes.tex b/macros/latex/contrib/l3kernel/l3syntax-changes.tex index 190821227a..57ecdc80f2 100644 --- a/macros/latex/contrib/l3kernel/l3syntax-changes.tex +++ b/macros/latex/contrib/l3kernel/l3syntax-changes.tex @@ -32,7 +32,7 @@ The released version of this bundle is available from CTAN. {latex-team@latex-project.org}% }% } -\date{Released 2020-02-11} +\date{Released 2020-02-14} \newcommand{\TF}{\textit{(TF)}} diff --git a/macros/latex/contrib/l3kernel/l3sys.dtx b/macros/latex/contrib/l3kernel/l3sys.dtx index 58665dab83..7c8820426c 100644 --- a/macros/latex/contrib/l3kernel/l3sys.dtx +++ b/macros/latex/contrib/l3kernel/l3sys.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3term-glossary.pdf b/macros/latex/contrib/l3kernel/l3term-glossary.pdf index 0b365b28ad..917b1fcedd 100644 Binary files a/macros/latex/contrib/l3kernel/l3term-glossary.pdf and b/macros/latex/contrib/l3kernel/l3term-glossary.pdf differ diff --git a/macros/latex/contrib/l3kernel/l3term-glossary.tex b/macros/latex/contrib/l3kernel/l3term-glossary.tex index 4cfc01af9e..a2a0af321f 100644 --- a/macros/latex/contrib/l3kernel/l3term-glossary.tex +++ b/macros/latex/contrib/l3kernel/l3term-glossary.tex @@ -32,7 +32,7 @@ The released version of this bundle is available from CTAN. {latex-team@latex-project.org}% }% } -\date{Released 2020-02-11} +\date{Released 2020-02-14} \newcommand{\TF}{\textit{(TF)}} diff --git a/macros/latex/contrib/l3kernel/l3text-case.dtx b/macros/latex/contrib/l3kernel/l3text-case.dtx index 4b39343bd4..0bdeab6210 100644 --- a/macros/latex/contrib/l3kernel/l3text-case.dtx +++ b/macros/latex/contrib/l3kernel/l3text-case.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % @@ -103,7 +103,12 @@ % \end{macro} % % \begin{macro}[EXP]{\@@_change_case:nnn, \@@_change_case_aux:nnn} -% \begin{macro}[EXP]{\@@_change_case_store:n} +% \begin{macro}[EXP] +% { +% \@@_change_case_store:n, \@@_change_case_store:o, +% \@@_change_case_store:V, \@@_change_case_store:v, +% \@@_change_case_store:e +% } % \begin{macro}[EXP]{\@@_change_case_store:nw} % \begin{macro}[EXP]{\@@_change_case_result:n} % \begin{macro}[EXP]{\@@_change_case_end:w} @@ -648,9 +653,10 @@ % \end{macro} % % \begin{macro}[EXP]{\@@_change_case_upper_de-alt:nnnN} +% \begin{macro}[EXP]{\@@_change_case_upper_de-alt:nnnNN} % A simple alternative version for German. % \begin{macrocode} -\bool_lazy_or:nnT +\bool_lazy_or:nnTF { \sys_if_engine_luatex_p: } { \sys_if_engine_xetex_p: } { @@ -659,15 +665,36 @@ \int_compare:nNnTF { `#4 } = { "00DF } { \@@_change_case_store:e - { \char_generate:nn { "1E9E } { \@@_char_catcode:N #4 } } + { \char_generate:nn { "1E9E } { \@@_char_catcode:N #4 } } \use:c { @@_change_case_char_next_ #2 :nn } {#2} {#3} } { \@@_change_case_char:nnnN {#1} {#2} {#3} #4 } } } + { + \cs_new:cpx { @@_change_case_upper_de-alt:nnnN } #1#2#3#4 + { + \exp_not:N \int_compare:nNnTF { `#4 } = { "00C3 } + { + \exp_not:c { @@_change_case_upper_de-alt:nnnNN } + {#1} {#2} {#3} #4 + } + { \exp_not:N \@@_change_case_char:nnnN {#1} {#2} {#3} #4 } + } + \cs_new:cpn { @@_change_case_upper_de-alt:nnnNN } #1#2#3#4#5 + { + \int_compare:nNnTF { `#5 } = { "009F } + { + \@@_change_case_store:V \c_@@_grosses_Eszett_tl + \use:c { @@_change_case_char_next_ #2 :nn } {#2} {#3} + } + { \@@_change_case_char:nnnN {#1} {#2} {#3} #4#5 } + } + } % \end{macrocode} % \end{macro} +% \end{macro} % % \begin{macro}[EXP]{\@@_change_case_upper_el:nnnN} % \begin{macro}[EXP]{\@@_change_case_upper_el:nnnn} @@ -1161,7 +1188,8 @@ % \c_@@_dotless_i_tl , % \c_@@_dotted_I_tl , % \c_@@_i_ogonek_tl , -% \c_@@_I_ogonek_tl +% \c_@@_I_ogonek_tl , +% \c_@@_grosses_Eszett_tl % } % For cases where there is an $8$-bit option in the |T1| font set up, % a variant is provided in both cases. @@ -1182,16 +1210,22 @@ \exp_not:N \char_generate:nn {##1} { 13 } \exp_after:wN \exp_after:wN \exp_after:wN \exp_not:N \char_generate:nn {##2} { 13 } + \tl_if_blank:nF {##3} + { + \exp_after:wN \exp_after:wN \exp_after:wN + \exp_not:N \char_generate:nn {##3} { 13 } + } } } \use:x { \@@_tmp:w \char_to_utfviii_bytes:n { "#2 } } \group_end: } - \@@_tmp:w \c_@@_dotless_i_tl { 0131 } - \@@_tmp:w \c_@@_dotted_I_tl { 0130 } - \@@_tmp:w \c_@@_i_ogonek_tl { 012F } - \@@_tmp:w \c_@@_I_ogonek_tl { 012E } + \@@_tmp:w \c_@@_dotless_i_tl { 0131 } + \@@_tmp:w \c_@@_dotted_I_tl { 0130 } + \@@_tmp:w \c_@@_i_ogonek_tl { 012F } + \@@_tmp:w \c_@@_I_ogonek_tl { 012E } + \@@_tmp:w \c_@@_grosses_Eszett_tl { 1E9E } } \group_end: % \end{macrocode} @@ -1421,22 +1455,29 @@ \AtBeginDocument { \group_begin: - \cs_set_protected:Npn \@@_change_case_setup:NN #1#2 + \cs_set_protected:Npn \@@_change_case_setup:Nn #1#2 { \quark_if_recursion_tail_stop:N #1 - \cs_if_exist:cF { c_@@_uppercase_ \token_to_str:N #1 _tl } - { - \tl_const:cn { c_@@_uppercase_ \token_to_str:N #1 _tl } - { #2 } - } - \cs_if_exist:cF { c_@@_lowercase_ \token_to_str:N #2 _tl } + \tl_if_single_token:nT {#2} { - \tl_const:cn { c_@@_lowercase_ \token_to_str:N #2 _tl } - { #1 } + \cs_if_exist:cF + { c_@@_uppercase_ \token_to_str:N #1 _tl } + { + \tl_const:cn + { c_@@_uppercase_ \token_to_str:N #1 _tl } + { #2 } + } + \cs_if_exist:cF + { c_@@_lowercase_ \token_to_str:N #2 _tl } + { + \tl_const:cn + { c_@@_lowercase_ \token_to_str:N #2 _tl } + { #1 } + } } - \@@_change_case_setup:NN + \@@_change_case_setup:Nn } - \exp_after:wN \@@_change_case_setup:NN \@uclclist + \exp_after:wN \@@_change_case_setup:Nn \@uclclist \q_recursion_tail ? \q_recursion_stop \group_end: diff --git a/macros/latex/contrib/l3kernel/l3text.dtx b/macros/latex/contrib/l3kernel/l3text.dtx index 8940ce5af0..e1e507f222 100644 --- a/macros/latex/contrib/l3kernel/l3text.dtx +++ b/macros/latex/contrib/l3kernel/l3text.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % @@ -64,14 +64,13 @@ % \begin{syntax} % \cs{text_expand:n} \Arg{text} % \end{syntax} -% Takes user input \meta{text} and transforms expandable and implicit -% content to the explicit equivalent. Protected commands (typically +% Takes user input \meta{text} and expands the content. +% Protected commands (typically % formatting) are left in place, and no processing takes place of % math mode material (as delimited by pairs given in % \cs{l_text_math_delims_tl} or as the argument to commands listed % in \cs{l_text_math_arg_tl}). Commands which are neither engine- -% nor \LaTeX{} protected are expanded exhaustively. Implicit tokens, -% including implicit groups, are converted to their explicit equivalent. +% nor \LaTeX{} protected are expanded exhaustively. % Any commands listed in \cs{l_text_expand_exclude_tl}, % \cs{l_text_accents_tl} and \cs{l_text_letterlike_tl} are excluded from % expansion. @@ -157,7 +156,9 @@ % I-dot and introduced when upper casing i-dotless. % \item German (\texttt{de-alt}). % An alternative mapping for German in which the lowercase -% \emph{Eszett} maps to a \emph{gro\ss{}es Eszett}. +% \emph{Eszett} maps to a \emph{gro\ss{}es Eszett}. This transformation +% is available using \pdfTeX{} as there is a |T1| slot for the +% result. % \item Greek (\texttt{el}). % Removes accents from Greek letters when uppercasing; titlecasing % leaves accents in place. @@ -697,7 +698,7 @@ \cs_new:Npn \@@_expand_math_search:NNN #1#2#3 { \quark_if_recursion_tail_stop_do:Nn #2 - { \@@_expand_implicit:N #1 } + { \@@_expand_explicit:N #1 } \token_if_eq_meaning:NNTF #1 #2 { \use_i_delimit_by_q_recursion_stop:nw @@ -740,16 +741,6 @@ \@@_expand_math_loop:Nw #1 } % \end{macrocode} -% Conversion of implicit to explicit tokens does not have to account for -% spaces or brace groups: they are already fixed above. So we can assume that -% the result of this conversion is still an \texttt{N}-type token. -% \begin{macrocode} -\cs_new:Npn \@@_expand_implicit:N #1 - { - \exp_args:NNe \use:nn \@@_expand_explicit:N - { \@@_token_to_explicit:N #1 } - } -% \end{macrocode} % At this stage, either we have a control sequence or a simple character: % split and handle. % \begin{macrocode} diff --git a/macros/latex/contrib/l3kernel/l3tl-analysis.dtx b/macros/latex/contrib/l3kernel/l3tl-analysis.dtx index 23d8bc5fe0..f878bd1e49 100644 --- a/macros/latex/contrib/l3kernel/l3tl-analysis.dtx +++ b/macros/latex/contrib/l3kernel/l3tl-analysis.dtx @@ -44,7 +44,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3tl.dtx b/macros/latex/contrib/l3kernel/l3tl.dtx index 084875362e..76ee3fbfcd 100644 --- a/macros/latex/contrib/l3kernel/l3tl.dtx +++ b/macros/latex/contrib/l3kernel/l3tl.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3token.dtx b/macros/latex/contrib/l3kernel/l3token.dtx index bf0f21a761..aa34d2b072 100644 --- a/macros/latex/contrib/l3kernel/l3token.dtx +++ b/macros/latex/contrib/l3kernel/l3token.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3unicode.dtx b/macros/latex/contrib/l3kernel/l3unicode.dtx index 8613e01612..5354b5b4f9 100644 --- a/macros/latex/contrib/l3kernel/l3unicode.dtx +++ b/macros/latex/contrib/l3kernel/l3unicode.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2020-02-11} +% \date{Released 2020-02-14} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/source3.pdf b/macros/latex/contrib/l3kernel/source3.pdf index 11152d7267..d2ac209b5f 100644 Binary files a/macros/latex/contrib/l3kernel/source3.pdf and b/macros/latex/contrib/l3kernel/source3.pdf differ diff --git a/macros/latex/contrib/l3kernel/source3.tex b/macros/latex/contrib/l3kernel/source3.tex index 4e333e569f..417674d9a8 100644 --- a/macros/latex/contrib/l3kernel/source3.tex +++ b/macros/latex/contrib/l3kernel/source3.tex @@ -53,7 +53,7 @@ for those people who are interested. {latex-team@latex-project.org}% }% } -\date{Released 2020-02-11} +\date{Released 2020-02-14} \pagenumbering{roman} \maketitle diff --git a/macros/latex/contrib/l3packages/CHANGELOG.md b/macros/latex/contrib/l3packages/CHANGELOG.md index 73d98156b1..363bbf7cdd 100644 --- a/macros/latex/contrib/l3packages/CHANGELOG.md +++ b/macros/latex/contrib/l3packages/CHANGELOG.md @@ -7,6 +7,11 @@ this project uses date-based 'snapshot' version identifiers. ## [Unreleased] +## [2020-02-14] + +### Fixed +- Grabbing `r`-type arguments by expandable commands (issse #672) + ## [2020-02-08] ### Changed @@ -71,7 +76,8 @@ this project uses date-based 'snapshot' version identifiers. - Switch to ISO date format - Improve cross-module use of internal functions -[Unreleased]: https://github.com/latex3/latex3/compare/2020-02-08...HEAD +[Unreleased]: https://github.com/latex3/latex3/compare/2020-02-14...HEAD +[2020-02-14]: https://github.com/latex3/latex3/compare/2020-02-08...2020-02-14 [2020-02-08]: https://github.com/latex3/latex3/compare/2020-02-03...2020-02-08 [2020-02-03]: https://github.com/latex3/latex3/compare/2020-01-12...2020-02-03 [2020-01-12]: https://github.com/latex3/latex3/compare/2019-10-11...2020-01-12 diff --git a/macros/latex/contrib/l3packages/README.md b/macros/latex/contrib/l3packages/README.md index b221eec8a1..4aea7fed22 100644 --- a/macros/latex/contrib/l3packages/README.md +++ b/macros/latex/contrib/l3packages/README.md @@ -1,7 +1,7 @@ LaTeX3 High-Level Concepts ========================== -Release 2020-02-08 +Release 2020-02-14 Overview -------- @@ -102,6 +102,6 @@ the [LaTeX-L list](#Discussion) should be used. ----- -

    Copyright (C) 1998-2011,2015-2020 The LaTeX3 Project
    +

    Copyright (C) 1998-2012,2015-2020 The LaTeX3 Project
    http://latex-project.org/
    All rights reserved.

    diff --git a/macros/latex/contrib/l3packages/l3keys2e.dtx b/macros/latex/contrib/l3packages/l3keys2e.dtx index 5753e388c9..6d932b4126 100644 --- a/macros/latex/contrib/l3packages/l3keys2e.dtx +++ b/macros/latex/contrib/l3packages/l3keys2e.dtx @@ -62,7 +62,7 @@ % }^^A % } % -% \date{Released 2020-02-08} +% \date{Released 2020-02-14} % % \maketitle % @@ -139,7 +139,7 @@ % \end{macrocode} % % \begin{macrocode} -\ProvidesExplPackage{l3keys2e}{2020-02-08}{} +\ProvidesExplPackage{l3keys2e}{2020-02-14}{} {LaTeX2e option processing using LaTeX3 keys} % \end{macrocode} % diff --git a/macros/latex/contrib/l3packages/l3keys2e.pdf b/macros/latex/contrib/l3packages/l3keys2e.pdf index 542dc679c6..c40b0ca21e 100644 Binary files a/macros/latex/contrib/l3packages/l3keys2e.pdf and b/macros/latex/contrib/l3packages/l3keys2e.pdf differ diff --git a/macros/latex/contrib/l3packages/xfp.dtx b/macros/latex/contrib/l3packages/xfp.dtx index 854a306709..c976197b91 100644 --- a/macros/latex/contrib/l3packages/xfp.dtx +++ b/macros/latex/contrib/l3packages/xfp.dtx @@ -64,7 +64,7 @@ % }^^A % } % -% \date{Released 2020-02-08} +% \date{Released 2020-02-14} % % \maketitle % @@ -167,7 +167,7 @@ % \end{macrocode} % % \begin{macrocode} -\ProvidesExplPackage{xfp}{2020-02-08}{} +\ProvidesExplPackage{xfp}{2020-02-14}{} {L3 Floating point unit} % \end{macrocode} % diff --git a/macros/latex/contrib/l3packages/xfp.pdf b/macros/latex/contrib/l3packages/xfp.pdf index fd2d9d0765..9680389654 100644 Binary files a/macros/latex/contrib/l3packages/xfp.pdf and b/macros/latex/contrib/l3packages/xfp.pdf differ diff --git a/macros/latex/contrib/l3packages/xfrac.dtx b/macros/latex/contrib/l3packages/xfrac.dtx index 9765c75eb1..3229465d5d 100644 --- a/macros/latex/contrib/l3packages/xfrac.dtx +++ b/macros/latex/contrib/l3packages/xfrac.dtx @@ -65,7 +65,7 @@ % }^^A % } % -% \date{Released 2020-02-08} +% \date{Released 2020-02-14} % % \maketitle % @@ -535,7 +535,7 @@ % \end{macrocode} % % \begin{macrocode} -\ProvidesExplPackage{xfrac}{2020-02-08}{} +\ProvidesExplPackage{xfrac}{2020-02-14}{} {L3 Experimental split-level fractions} % \end{macrocode} % diff --git a/macros/latex/contrib/l3packages/xfrac.ins b/macros/latex/contrib/l3packages/xfrac.ins index 1b02e49b54..9126baaab7 100644 --- a/macros/latex/contrib/l3packages/xfrac.ins +++ b/macros/latex/contrib/l3packages/xfrac.ins @@ -24,7 +24,8 @@ The released version of this bundle is available from CTAN. \preamble -Copyright (C) 2011-2020 The LaTeX3 Project +Copyright (C) 2004,2008-2010 Morten Hoegholm + (C) 2011-2020 The LaTeX3 Project It may be distributed and/or modified under the conditions of the LaTeX Project Public License (LPPL), either version 1.3c of diff --git a/macros/latex/contrib/l3packages/xfrac.pdf b/macros/latex/contrib/l3packages/xfrac.pdf index f02a8829d9..4696d0e129 100644 Binary files a/macros/latex/contrib/l3packages/xfrac.pdf and b/macros/latex/contrib/l3packages/xfrac.pdf differ diff --git a/macros/latex/contrib/l3packages/xparse.dtx b/macros/latex/contrib/l3packages/xparse.dtx index 1f0f483271..fa5e6e301d 100644 --- a/macros/latex/contrib/l3packages/xparse.dtx +++ b/macros/latex/contrib/l3packages/xparse.dtx @@ -67,7 +67,7 @@ % }^^A % } % -% \date{Released 2020-02-08} +% \date{Released 2020-02-14} % % \maketitle % @@ -916,7 +916,7 @@ % \end{macrocode} % % \begin{macrocode} -\ProvidesExplPackage{xparse}{2020-02-08}{} +\ProvidesExplPackage{xparse}{2020-02-14}{} {L3 Experimental document command parser} % \end{macrocode} % @@ -3932,10 +3932,10 @@ % the delimiters are different. % \begin{macrocode} \cs_new:Npn \@@_expandable_grab_R_alt:w #1 \q_@@ #2#3 - { #2 { \@@_expandable_grab_R_alt_aux:NNnwNn #1 \q_@@ #2#3 } } + { #2 { \@@_expandable_grab_R_alt_aux:NNwNNn #1 \q_@@ #2#3 } } \cs_set_protected:Npn \@@_tmp:w #1 { - \cs_new:Npn \@@_expandable_grab_R_alt_aux:NNwNn ##1##2##3 \q_@@ ##4##5##6 + \cs_new:Npn \@@_expandable_grab_R_alt_aux:NNwNNn ##1##2##3 \q_@@ ##4##5##6 { \str_if_eq:nnTF {##6} {##2} { diff --git a/macros/latex/contrib/l3packages/xparse.pdf b/macros/latex/contrib/l3packages/xparse.pdf index c176bacedc..eb6a61e0b6 100644 Binary files a/macros/latex/contrib/l3packages/xparse.pdf and b/macros/latex/contrib/l3packages/xparse.pdf differ diff --git a/macros/latex/contrib/l3packages/xtemplate.dtx b/macros/latex/contrib/l3packages/xtemplate.dtx index 32e8fbbd33..27ad45e22f 100644 --- a/macros/latex/contrib/l3packages/xtemplate.dtx +++ b/macros/latex/contrib/l3packages/xtemplate.dtx @@ -63,7 +63,7 @@ % }^^A % } % -% \date{Released 2020-02-08} +% \date{Released 2020-02-14} % % \maketitle % @@ -682,7 +682,7 @@ % \end{macrocode} % % \begin{macrocode} -\ProvidesExplPackage{xtemplate}{2020-02-08}{} +\ProvidesExplPackage{xtemplate}{2020-02-14}{} {L3 Experimental prototype document functions} % \end{macrocode} % diff --git a/macros/latex/contrib/l3packages/xtemplate.pdf b/macros/latex/contrib/l3packages/xtemplate.pdf index 839e221f6c..148db5798f 100644 Binary files a/macros/latex/contrib/l3packages/xtemplate.pdf and b/macros/latex/contrib/l3packages/xtemplate.pdf differ diff --git a/macros/latex/contrib/subfiles/README b/macros/latex/contrib/subfiles/README index f527f73452..45595bc671 100644 --- a/macros/latex/contrib/subfiles/README +++ b/macros/latex/contrib/subfiles/README @@ -12,4 +12,4 @@ subfiles.sty and put them somewhere on the search path of TeX. Documentation: -Run 'pdflatex subfiles.dtx' to generate subfiles.pdf. +Run 'pdflatex subfiles.dtx' twice to generate subfiles.pdf. diff --git a/macros/latex/contrib/subfiles/subfiles.dtx b/macros/latex/contrib/subfiles/subfiles.dtx index 201cfd6010..1e81e488db 100644 --- a/macros/latex/contrib/subfiles/subfiles.dtx +++ b/macros/latex/contrib/subfiles/subfiles.dtx @@ -2,7 +2,7 @@ % % subfiles - class and package for multi-file projects in LaTeX % Copyright 2002, 2012 Federico Garcia (feg8@pitt.edu, fedegarcia@hotmail.com) -% Copyright 2018, 2019 Gernot Salzer (salzer@logic.at) +% Copyright 2018-2020 Gernot Salzer (salzer@logic.at) % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 @@ -17,20 +17,20 @@ % The Current Maintainer of this work is Gernot Salzer. % % This work consists of the files subfiles.dtx and subfiles.ins -% and the derived files subfiles.sty and subfiles.pdf +% and the derived files subfiles.cls, subfiles.sty and subfiles.pdf % % ------------------------------------------- % %<*driver> % \fi -\ProvidesFile{subfiles.dtx}[2019/10/30 v1.5 Multi-file projects] +\ProvidesFile{subfiles.dtx}[2020/02/14 v1.6 Multi-file projects] % \iffalse \documentclass{ltxdoc} \GetFileInfo{subfiles.dtx} \title{A Document Class and a Package\\for Handling Multi-File Projects} -\date{v1.5 2019/10/30} +\date{2020/02/14 v1.6} \author{Federico Garcia, Gernot Salzer} - +\usepackage{hyperref} \begin{document} \maketitle \DocInput{\filename} @@ -41,6 +41,7 @@ % The |subfiles| package allows authors to split a document into one main file and one and more subsidiary files (subfiles) akin to the |\input| command, with the added benefit of making the subfiles compilable by themselves. % This is achieved by reusing the preamble of the main file also for the subfiles. % \end{abstract} +% \tableofcontents % \section{Introduction} % The \LaTeX\ commands |\include| and |\input| allow the user to split the \TeX\ source of a document into several input files. % This is useful when creating documents with many chapters, but also for handling large tables, figures, and code samples, which require a considerable amount of trial-and-errors. @@ -61,6 +62,7 @@ % % \section{Basic usage} % +% \DescribeMacro{subfiles.sty} % The main file, i.e., the file with the preamble to be shared with the subfiles, has to load the package |subfiles| \emph{at the end of the preamble}: % \begin{center} % \begin{tabular}{l} @@ -68,10 +70,12 @@ % |\begin{document}| % \end{tabular} % \end{center} +% \DescribeMacro{\subfile} % Subordinate files (subfiles) are loaded from the main file or from other subfiles with the command % \begin{center} % |\subfile{|\meta{subfile\_name}|}| % \end{center} +% \DescribeMacro{subfiles.cls} % The subfiles have to start with the line % \begin{center} % |\documentclass[|\meta{main\_file\_name}|]{subfiles}| @@ -174,6 +178,7 @@ % % \subsection{Including files instead of inputting them} % +% \DescribeMacro{\subfileinclude} % In plain \LaTeX, you can use either |\input| or |\include| to load a file. % In most cases the first is appropriate, but sometimes there are reasons to prefer the latter. % Internally, the |\subfile| command uses |\input|. @@ -185,30 +190,50 @@ % \subsection{Bibliographies} % % Manual bibliographies with the |thebibliography| environment work as usual. -% Problems may arise if external programs like |bibtex| or |biber| are used to generate the bibliography, in particular when the bibliographies are distributed over subfiles. -% Here are some hints on how it may work. +% Problems may arise if external programs like |bibtex| or |biber| are used to generate the bibliography. +% Here are some hints on how to make it work. % \begin{itemize} -% \item Make sure the command |\bibliography| is executed after loading the |subfiles| package. +% \item +% \DescribeMacro{\bibliography} +% Make sure the command |\bibliography| is executed after loading the |subfiles| package. % Put the command between |\usepackage{subfiles}| and |\begin{document}| or somewhere into the text part. -% \item When you use the package |biblatex|, and programs like |biber| complain about not being able to find the bibliography files, use |\bibliography| instead of |\addbibresource| for local files (observing the hint above). +% \item When you use the package |biblatex|, and programs like |biber| complain about not being able to find the bibliography files, use |\bibliography| instead of |\addbibresource| (see above), or the command |\subfix| (see below). +% \item +% \DescribeMacro{\subfix} +% Whenever an external program complains that a file specified in the \LaTeX\ document cannot be found, wrap the command |\subfix| around the filename. +% Here are some examples. +% \begin{center} +% \begin{tabular}{ll} +% package & command when used with |subfiles| \\ +% \hline +% |biblatex| & |\addbibresource{\subfix{|\meta{file}|}}| \\ +% |bibunits| & |\putbib[\subfix{|\meta{file1}|},\subfix{|\meta{file2}|},|\dots|]|\\ +% & |\defaultbibliography{\subfix{|\meta{file1}|},|\dots|}| +% \end{tabular} +% \end{center} +% % \end{itemize} -% The |subfiles| package has been tested with the packages |biblatex|, |bibunits|, and |chapterbib| as well as the external programs |bibtex| and |biber|. +% The |subfiles| package has been tested with the packages |biblatex|, |bibunits|, and |chapterbib| as well as with the external programs |bibtex| and |biber|. % % \subsection{Unusual locations for placing definitions and text} % % Usually all definitions and packages required by the subfiles should go into the preamble of the main file. % There are some further locations, though, where one might consider adding definitions and text. +% Put negatively, apparently irrelevant stuff in these locations may become unexpectedly visible in the document or cause errors. % % \paragraph{Code after the end of the main document} is added to the preamble of the subfiles, but is ignored when typesetting the main file. % This happens because a subfile typeset by itself does not really take the preamble of the main file, but \emph{everything outside} of |\begin{document}| and |\end{document}|. -% This has two consequences: \emph{a)}~the user can add some commands to be processed as part of the preamble only when the subfiles are typeset by themselves; but also \emph{b)}~the user has to be careful even \emph{after} |\end{document}| in the main file, for any syntax error there will ruin the \LaTeX ing of the subfile(s). +% This has two consequences: \emph{a)}~the user can add some commands that are to be processed as part of the preamble only when the subfiles are typeset by themselves; but also \emph{b)}~the user has to be careful even \emph{after} |\end{document}| in the main file, for any syntax error there will ruin the \LaTeX ing of the subfile(s). +% \bigskip +% +% Similarly, when typesetting the main document, the |\subfile| command does not really load the stuff within the |document| environment, but \emph{everything except} the three commands |\documentclass[...]{...}|, |\begin{document}|, and |\end{document}|. +% This has the following consequences. % % \paragraph{Code in the preamble of a subfile} is processed as part of the text when typesetting the main file, but as part of the preamble when typesetting the subfile. % This means that the preamble of a subfile can only contain stuff that is acceptable for both, the preamble and the text area. % One should also keep in mind that each subfile is input within a group, so definitions made within may not work outside. -% A good practice when using |subfiles| (and also when not using it) is to make any definitions in the preamble of the main file, avoiding confusion and allowing the reader to find them easily. % -% \paragraph{Code after the end of a subfile} is treated like the code preceding it when the subfile is loaded from the main file, but is ignored when typesetting the subfile. +% \paragraph{Code after \texttt{\textbackslash end\{document\}} in a subfile} is treated like the code preceding it when the subfile is loaded from the main file, but is ignored when typesetting the subfile. % The code after |\end{document}| behaves as if following the |\subfile| command in the main file, except that it is still part of the group enclosing the subfile. % As a consequence, empty lines at the end of the subfile lead to a new paragraph in the main document, even if the |\subfile| command is immediately followed by text. % @@ -247,6 +272,26 @@ % |contents of subfile\end{document}| % \end{center} % +% \section{Troubleshooting} +% +% Here are some hints that solve most problems. +% +% \begin{enumerate} +% \item +% Make sure to use the most recent version of the |subfiles| package, available from CTAN\footnote{\url{https://ctan.org/pkg/subfiles}} and Github\footnote{\url{https://github.com/gsalzer/subfiles}}. +% \item +% Make sure that |\usepackage{subfiles}| comes last in the preamble +% of the main document. +% \item +% If some external program that cooperates with \TeX, like |bibtex| or |biber|, complains about not being able to find a file, locate the name of the file in the \LaTeX\ source and replace \meta{filename} by |\subfix{|\meta{filename}|}|. +% \item +% Make sure that there is no stuff after |\end{document}|, neither in the main file nor in the subfiles. +% \item +% If there is anything in the preambles of the subfiles, make sure that it is admissible for both, the preamble and the document area. +% \item +% If nothing of the above helps and you are stuck, ask the people on tex.stackexchange\footnote{\url{https://tex.stackexchange.com/}}. +% \end{enumerate} +% % \section{Dependencies} % % The |subfiles| package requires the |verbatim| package, whose |comment| environment is used to ignore the text area of the main file when typesetting subfiles separately. @@ -266,7 +311,7 @@ % \begin{itemize} % \item Use of |import| package to handle directory hierarchies. % \item |\ignorespaces| added to avoid spurious spaces. -% \item Incompatibility with commands removed that expect |\document| to be equal to |\@onlypreamble| after the preamble (thanks to Eric Domenjoud for analysing the problem). +% \item Incompatibility with commands removed that expect |\document| to be equal to |\@onlypreamble| after the preamble. Thanks to Eric Domenjoud for analysing the problem. % \end{itemize} % \item[v1.4:] \mbox{} % \begin{itemize} @@ -280,6 +325,13 @@ % Seems to suffice also for sub-bibliographies with the package |chapterbib|. % \item Support for sub-bibliographies with package |bibunits| added. % \end{itemize} +% \item[v1.6:] \mbox{} +% \begin{itemize} +% \item Support for sub-bibliographies with package |bibunits| dropped, in favor of |\subfix|. +% \item Command |\subfix| added. +% \item Incompatibility with |standalone| class removed. +% \item The options of the main class are now also processed when typesetting a subfile; before they were ignored. Thanks to J\'an Kl'uka for analysing the problem. +% \end{itemize} % \end{description} % %\section{The Implementation} @@ -287,13 +339,17 @@ % \begin{macrocode} %<*class> \NeedsTeXFormat{LaTeX2e} -\ProvidesClass{subfiles}[2019/10/30 v1.5 Multi-file projects (class)] +\ProvidesClass{subfiles}[2020/02/14 v1.6 Multi-file projects (class)] \DeclareOption*{\typeout{Preamble taken from file `\CurrentOption'}% \let\preamble@file\CurrentOption} \ProcessOptions % \end{macrocode} +% After processing the option of the |subfiles| class, we reset |\@classoptionslist| such that the options in the main file will be processed. % -% We start by saving the regular \LaTeX\ definition of |\documentclass|: +% \begin{macrocode} +\let\@classoptionslist\relax +% \end{macrocode} +% Then we save the original definition of |\documentclass| to be able to reset it later to this definition: % % \begin{macrocode} \let\subfiles@documentclass\documentclass @@ -326,42 +382,34 @@ \RequirePackage{import} % \end{macrocode} % -% The |\subimport| command requires the path and the basename of the file to be loaded in separate arguments. -% Therefore we have to split file names into these two components. +% The |\subimport| command requires path and filename as separate arguments, so we have to split file locations into these two components. +% The internal \LaTeX\ command |\filename@parse| almost fits the bill, except that it additionally splits the filename into basename and extension. +% Unfortunately, concatenating basename and extension to recover the filename is not clean: +% Under Unix/Linux, the filenames |base| and |base.| denote different entities, but after |\filename@parse| both have the same basename and an empty extension. +% Therefore we redefine the command |\filename@simple| temporarily; it is responsible for this unwanted split. % % \begin{macrocode} \def\subfiles@split#1{% - \edef\subfiles@filename{#1}% - \def\subfiles@dir{}% - \def\subfiles@base{}% - \def\subfiles@sep{}% - \expandafter\subfiles@split@\subfiles@filename/\@nil/% -} -\def\subfiles@split@#1/{% - \def\tmp{#1}% - \ifx\tmp\@nnil - \let\subfiles@next\relax - \else - \edef\subfiles@dir{\subfiles@dir\subfiles@base\subfiles@sep}% - \def\subfiles@base{#1}% - \def\subfiles@sep{/}% - \let\subfiles@next\subfiles@split@ - \fi - \subfiles@next + \let\subfiles@filename@simple\filename@simple + \def\filename@simple##1.\\{\edef\filename@base{##1}}% + \filename@parse{#1}% + \let\filename@simple\subfiles@filename@simple } % \end{macrocode} % -% After executing e.g.\ |\subfiles@split{../dir1/dir2/file.tex}|, the commands |\subfiles@dir| and |\subfiles@base| expand to |../dir1/dir2/| and |file.tex|, respectively. +% E.g., after executing |\subfiles@split{../dir1/dir2/file.tex}| the macros |\filename@area| and |\filename@base| expand to |../dir1/dir2/| and |file.tex|, respectively. % % Now we split the name of the main file that has been provided as optional argument of the document class, and |\subimport| the main file. % % \begin{macrocode} \subfiles@split{\preamble@file} -\subimport{\subfiles@dir}{\subfiles@base} +\subimport{\filename@area}{\filename@base} % \end{macrocode} % % The main file loads the package |subfiles| as part of the preamble, which saves the contents of |\document| and |\enddocument| as |\subfiles@document| and |\subfiles@enddocument|, respectively. -% Then we restore the original values of |\document|, |\enddocument|, and |\documentclass|. The backup commands are |\undefined| to save memory. That's it. +% We use these macors now to restore the original values of |\document|, |\enddocument|, and |\documentclass|. +% The backup commands are |\undefined| to save memory. +% That's it. % % \begin{macrocode} {\catcode`\@=11 @@ -387,7 +435,7 @@ % \begin{macrocode} %<*package> \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{subfiles}[2019/10/30 v1.5 Multi-file projects (package)] +\ProvidesPackage{subfiles}[2020/02/14 v1.6 Multi-file projects (package)] \DeclareOption*{\PackageWarning{\CurrentOption ignored}} \ProcessOptions % \end{macrocode} @@ -410,36 +458,26 @@ % This happens e.g.\ with the class |revtex4| and the package |pythontex|. % % We use the |import| package to handle subfiles in separate directories. -% The |\subimport| command requires the path and the basename of files as separate arguments. -% Therefore we split file names into these two components using a macro |\subfiles@split|. -% Both things, loading the package and defining the command, is also done in |subfiles.cls|, so we have to execute this code only if we are typesetting the main file. +% The |\subimport| command requires path and filename as separate arguments, so we have to split file locations into these two components. +% The internal \LaTeX\ command |\filename@parse| almost fits the bill, except that it additionally splits the filename into basename and extension. +% Unfortunately, concatenating basename and extension to recover the filename is not clean: +% Under Unix/Linux, the filenames |base| and |base.| denote different entities, but after |\filename@parse| both have the same basename and an empty extension. +% Therefore we redefine the command |\filename@simple| temporarily; it is responsible for this unwanted split. +% Both things, loading the package and defining the command, are also done in |subfiles.cls|, so we have to execute this code only if we are typesetting the main file. % % \begin{macrocode} -}{% subfiles class not loaded +}{% subfiles class not loaded, we typeset the main document \RequirePackage{import} \def\subfiles@split#1{% - \edef\subfiles@filename{#1}% - \def\subfiles@dir{}% - \def\subfiles@base{}% - \def\subfiles@sep{}% - \expandafter\subfiles@split@\subfiles@filename/\@nil/% - }% - \def\subfiles@split@#1/{% - \def\tmp{#1}% - \ifx\tmp\@nnil - \let\subfiles@next\relax - \else - \edef\subfiles@dir{\subfiles@dir\subfiles@base\subfiles@sep}% - \def\subfiles@base{#1}% - \def\subfiles@sep{/}% - \let\subfiles@next\subfiles@split@ - \fi - \subfiles@next - }% + \let\subfiles@filename@simple\filename@simple + \def\filename@simple##1.\\{\edef\filename@base{##1}}% + \filename@parse{#1}% + \let\filename@simple\subfiles@filename@simple + } } % \end{macrocode} % -% After executing e.g.\ |\subfiles@split{../dir1/dir2/file.tex}|, the commands |\subfiles@dir| and |\subfiles@base| expand to |../dir1/dir2/| and |file.tex|, respectively. +% E.g., after executing |\subfiles@split{../dir1/dir2/file.tex}| the macros |\filename@area| and |\filename@base| expand to |../dir1/dir2/| and |file.tex|, respectively. % % \DescribeMacro{\subfile} % The command |\subfile| specifies the command |\subimport| for |\input|ing the subfile, and then calls |\subfiles@subfile|. @@ -460,17 +498,24 @@ % \end{macrocode} % % The main functionality of the two |\subfile| commands is implemented in |\subfiles@subfile|. -% It redefines |\documentclass| and the |document| environment to do nothing except avoiding spurious spaces. -% Moreover, |\document| has to be set to the value it usually has after the end of the preamble, since some commands check this value and may raise an error otherwise. +% It redefines |\documentclass| and the |document| environment to do nothing but reverting these command to their original meaning and avoiding spurious spaces. +% Reverting |\documentclass| and |\document| to their original definition is important for being compatible with classes like |standalone| or packages like |bibentry|, which rely on this definition. % % \begin{macrocode} \newcommand\subfiles@subfile[1]{% \begingroup - \renewcommand\documentclass[2][subfiles]{\ignorespaces}% + \let\subfiles@documentclass\documentclass + \let\subfiles@document\document + \let\subfiles@enddocument\enddocument + \renewcommand\documentclass[2][subfiles]{% + \let\documentclass\subfiles@documentclass + \ignorespaces + }% \renewenvironment{document}{% - \let\document\@onlypreamble + \let\document\subfiles@document \ignorespaces }{% + \let\enddocument\subfiles@enddocument \@ignoretrue }% % \end{macrocode} @@ -478,13 +523,11 @@ % % \begin{macrocode} \subfiles@split{#1}% - \subfiles@loadfile{\subfiles@dir}{\subfiles@base}% + \subfiles@loadfile{\filename@area}{\filename@base}% \endgroup } % \end{macrocode} % -% Note that the changes to |\documentclass| and the |document| environment happen \emph{within a group}, so they are undone after inclusion of the subfile. -% % To let external programs find files, we have to add the |\import@path| to file names. % This is accomplished with the command |\subfiles@addimportpath|. % \begin{macrocode} @@ -492,12 +535,18 @@ \def\subfiles@filelist{}% \def\subfiles@sep{}% \@for\subfiles@filename:=#1\do{% - \edef\subfiles@filelist{\subfiles@filelist\subfiles@sep\import@path\subfiles@filename}% + \edef\subfiles@filelist{% + \subfiles@filelist + \subfiles@sep + \import@path + \subfiles@filename + }% \def\subfiles@sep{,}% } } % \end{macrocode} % +% \DescribeMacro{\bibliography} % We redefine the |\bibliography| command such that the import path is added to the file names before the original command is called. % \begin{macrocode} \let\subfiles@bibliography\bibliography @@ -507,13 +556,8 @@ } % \end{macrocode} % -% The |bibunits| package uses its own command to specify bib files, we have to patch it separately. +% \DescribeMacro{\subfix} +% Instead of adding further fixes for other packages that write filenames to external files (like |bibunits|), we provide a command for adding the |\import@path| to a filename. % \begin{macrocode} -\@ifpackageloaded{bibunits}{% - \let\subfiles@putbib\@putbib - \def\@putbib[#1]{% - \subfiles@addimportpath{#1}% - \expandafter\subfiles@putbib\expandafter[\subfiles@filelist]% - }% -}{} +\def\subfix#1{\import@path#1} % \end{macrocode} diff --git a/macros/latex/contrib/subfiles/subfiles.pdf b/macros/latex/contrib/subfiles/subfiles.pdf index 33f39c049e..0925cb83b9 100644 Binary files a/macros/latex/contrib/subfiles/subfiles.pdf and b/macros/latex/contrib/subfiles/subfiles.pdf differ diff --git a/macros/latex/required/babel/base/README.md b/macros/latex/required/babel/base/README.md index 897bbee2be..9b15c73a61 100644 --- a/macros/latex/required/babel/base/README.md +++ b/macros/latex/required/babel/base/README.md @@ -1,4 +1,4 @@ -## Babel 3.39 +## Babel 3.40 This package manages culturally-determined typographical (and other) rules, and hyphenation patterns for a wide range of languages. Many @@ -7,9 +7,9 @@ lualatex out of the box. A few even work with plain formats. The latest stable version is available on . -Changes in version 3.39 are described in: +Changes in version 3.40 are described in: -https://github.com/latex3/babel/wiki/What's-new-in-babel-3.39 +https://github.com/latex3/babel/wiki/What's-new-in-babel-3.40 Included is a set of ini files for about 200 languages. @@ -44,6 +44,15 @@ respective authors. ### Latest changes ``` +3.40 2020-02-14 + - New ini files for Latin and Greek (xe/lua). + - Add 'other' characters used in hyphenation patters (eg, + apostrophes). + - Fix - Old Plain TeX and Plain XeTeX raised an error. + - Fix - Option T1 in fontenc was not recognized to set + \latinencoding with LaTeX 2020-02-02. + - Fix - Locale names were hardcoded in some babel-...tex files. + 3.39 2020-02-03 - Languages can now be loaded on the fly (via \babelprovide). - With \babelposthyphenation captured chars can now be mapped in @@ -57,6 +66,7 @@ respective authors. - Thai and turkish raised and error without import in \babelprovide. - Cleaned up some ini/tex locale files (de, zh, sa). +See https://github.com/latex3/babel/wiki/What's-new-in-babel-3.39 3.38 2020-01-15 - Automatic switching of ids (\language and \localeid), and fonts diff --git a/macros/latex/required/babel/base/babel.dtx b/macros/latex/required/babel/base/babel.dtx index d0a6314f27..d0c45fd23c 100644 --- a/macros/latex/required/babel/base/babel.dtx +++ b/macros/latex/required/babel/base/babel.dtx @@ -31,7 +31,7 @@ % % \iffalse %<*filedriver> -\ProvidesFile{babel.dtx}[2020/02/03 v3.39 The Babel package] +\ProvidesFile{babel.dtx}[2020/02/14 v3.40 The Babel package] \documentclass{ltxdoc} \GetFileInfo{babel.dtx} \usepackage{fontspec} @@ -2408,10 +2408,12 @@ _\telugucounter{section}_ \end{document} \end{verbatim} -Languages providing native digits in all or some variants are -\textit{ar, as, bn, bo, brx, ckb, dz, fa, gu, hi, km, kn, kok, ks, lo, -lrc, ml, mr, my, mzn, ne, or, pa, ps, ta, te, th, ug, ur, uz, vai, yue, -zh.} +Languages providing native digits in all or some variants are Arabic, +Assamese, Bangla, Tibetar, Bodo, Central Kurdish, Dzongkha, Persian, +Gujarati, Hindi, Khmer, Kannada, Konkani, Kashmiri, Lao, Northern Luri, +Malayalam, Marathi, Burmese, Mazanderani, Nepali, Odia, Punjabi, +Pashto, Tamil, Telugu, Thai, Uyghur, Urdu, Uzbek, Vai, Cantonese, +Chinese. \New{3.30} With \luatex{} there is an alternative approach for mapping digits, namely, |mapdigits|. Conversion is based on the language and it @@ -4231,11 +4233,6 @@ help from Bernd Raichle, for which I am grateful. % % \fi % -% \changes{babel~3.9c}{2013/04/04}{Added the ``modifiers'' mechanism} -% \changes{babel~3.9g}{2013/06/01}{bbplain merged} -% \changes{babel~3.9k}{2014/03/23}{Code and doc reorganized, and some -% minor enhancements} -% %\begingroup % \catcode`<=\active% % \catcode`>=\active @@ -4330,8 +4327,8 @@ help from Bernd Raichle, for which I am grateful. % \section{Tools} % % \begin{macrocode} -%<> -%<> +%<> +%<> % \end{macrocode} % % \textbf{Do not use the following macros in \texttt{ldf} files. They @@ -4339,10 +4336,6 @@ help from Bernd Raichle, for which I am grateful. % added for replacing, trimming and looping. The older ones, like % |\bbl@afterfi|, will not change. % -% \changes{babel~3.9t}{2017/04/22}{Added new helper macros. Not all are -% currently used, but will be in 3.10 -- \cs{bbl@trim}, -% \cs{bbl@ifunset}, \cs{bbl@exp}, \cs{bbl@stripslash}} -% % We define some basic macros which just make the code cleaner. % |\bbl@add| is now used internally instead of |\addto| because of % the unpredictable behavior of the latter. Used in @@ -4351,11 +4344,6 @@ help from Bernd Raichle, for which I am grateful. % \file{babel.def} cannot be load until options have been defined. % This does not hurt, but should be fixed somehow. % -% \changes{babel~3.9i}{2014/02/16}{\cs{@for} didn't work with -% Plain. Added \cs{bbl@loop}} -% \changes{babel~3.15}{2017/10/30}{New convenience macros -% \cs{bbl@xin@} and \cs{bbl@cs}} -% % \begin{macrocode} %<<*Basic macros>> \bbl@trace{Basic macros} @@ -4376,18 +4364,12 @@ help from Bernd Raichle, for which I am grateful. \def\bbl@for#1#2#3{\bbl@loopx#1{#2}{\ifx#1\@empty\else#3\fi}} % \end{macrocode} % -% \changes{babel~3.9t}{2017/04/22}{Use \cs{bbl@ifunset} instead of -% \cs{@ifundefined}.} -% % \begin{macro}{\bbl@add@list} % This internal macro adds its second argument to a comma % separated list in its first argument. When the list is not % defined yet (or empty), it will be initiated. It presumes % expandable character strings. % -% \changes{babel~3.9t}{2017/04/22}{Redefined to avoid infinite loops -% if the macro is \cs{relax}.} -% % \begin{macrocode} \def\bbl@add@list#1#2{% \edef#1{% @@ -4469,9 +4451,6 @@ help from Bernd Raichle, for which I am grateful. % it is based on |\ifcsname|, which is more efficient, and do not % waste memory. % -% \changes{babel~3.35}{2019/09/22}{Inside a group, so that \cs{ifcsname} -% is still undefined.} -% % \begin{macrocode} \begingroup \gdef\bbl@ifunset#1{% @@ -4566,40 +4545,38 @@ help from Bernd Raichle, for which I am grateful. % because it is not a general purpose macro, and it is used by \babel{} % only when it works (an example where it does \textit{not} work is in % |\bbl@TG@@date|, and also fails if there are macros with spaces, -% because they retokenized). It may change! (or even merged with +% because they are retokenized). It may change! (or even merged with % |\bbl@replace|; I'm not sure ckecking the replacement is really % necessary or just paranoia). % -% \changes{babel~3.34}{2019/07/23}{Take into account prefixes like -% \cs{long} and macros with trailing spaces. Don't touch original if -% not necessary.} -% % \begin{macrocode} -\bbl@exp{\def\\\bbl@parsedef##1\detokenize{macro:}}#2->#3\relax{% - \def\bbl@tempa{#1}% - \def\bbl@tempb{#2}% - \def\bbl@tempe{#3}} -\def\bbl@sreplace#1#2#3{% - \begingroup - \expandafter\bbl@parsedef\meaning#1\relax - \def\bbl@tempc{#2}% - \edef\bbl@tempc{\expandafter\strip@prefix\meaning\bbl@tempc}% - \def\bbl@tempd{#3}% - \edef\bbl@tempd{\expandafter\strip@prefix\meaning\bbl@tempd}% - \bbl@xin@{\bbl@tempc}{\bbl@tempe}% If not in macro, do nothing - \ifin@ - \bbl@exp{\\\bbl@replace\\\bbl@tempe{\bbl@tempc}{\bbl@tempd}}% - \def\bbl@tempc{% Expanded an executed below as 'uplevel' - \\\makeatletter % "internal" macros with @ are assumed - \\\scantokens{% - \bbl@tempa\\\@namedef{\bbl@stripslash#1}\bbl@tempb{\bbl@tempe}}% - \catcode64=\the\catcode64\relax}% Restore @ - \else - \let\bbl@tempc\@empty % Not \relax - \fi - \bbl@exp{% For the 'uplevel' assignments - \endgroup - \bbl@tempc}} % empty or expand to set #1 with changes +\ifx\detokenize\@undefined\else % Unused macros if old Plain TeX + \bbl@exp{\def\\\bbl@parsedef##1\detokenize{macro:}}#2->#3\relax{% + \def\bbl@tempa{#1}% + \def\bbl@tempb{#2}% + \def\bbl@tempe{#3}} + \def\bbl@sreplace#1#2#3{% + \begingroup + \expandafter\bbl@parsedef\meaning#1\relax + \def\bbl@tempc{#2}% + \edef\bbl@tempc{\expandafter\strip@prefix\meaning\bbl@tempc}% + \def\bbl@tempd{#3}% + \edef\bbl@tempd{\expandafter\strip@prefix\meaning\bbl@tempd}% + \bbl@xin@{\bbl@tempc}{\bbl@tempe}% If not in macro, do nothing + \ifin@ + \bbl@exp{\\\bbl@replace\\\bbl@tempe{\bbl@tempc}{\bbl@tempd}}% + \def\bbl@tempc{% Expanded an executed below as 'uplevel' + \\\makeatletter % "internal" macros with @ are assumed + \\\scantokens{% + \bbl@tempa\\\@namedef{\bbl@stripslash#1}\bbl@tempb{\bbl@tempe}}% + \catcode64=\the\catcode64\relax}% Restore @ + \else + \let\bbl@tempc\@empty % Not \relax + \fi + \bbl@exp{% For the 'uplevel' assignments + \endgroup + \bbl@tempc}} % empty or expand to set #1 with changes +\fi % \end{macrocode} % \end{macro} % @@ -4745,21 +4722,11 @@ help from Bernd Raichle, for which I am grateful. % is used as a flag. Otherwise, we need to use the second part, so % |\orig@dump| is not defined (\file{plain.def} undefines it). % -% \changes{babel~3.9a}{2012/12/21}{Use \cs{orig@dump} as flag instead -% of \cs{adddialect}} -% % Check if the current version of \file{switch.def} has been % previously loaded (mainly, \file{hyphen.cfg}). If not, load it % now. We cannot load |babel.def| here because we first need to % declare and process the package options. % -% \changes{babel~3.9a}{2012/08/11}{Now switch.def is loaded always, so -% that there is no need to rebuild formats just to update babel} -% \changes{babel~3.9a}{2012/12/13}{But switch.def is loaded only if -% loaded in a different version (or not loaded)} -% \changes{babel~3.9a}{2013/01/14}{Added the debug option} -% \changes{babel~3.9a}{2013/02/05}{Added \cs{bbl@add}} -% % \section{The Package File (\LaTeX, \texttt{babel.sty})} % % In order to make use of the features of \LaTeXe, the \babel\ @@ -4785,19 +4752,6 @@ help from Bernd Raichle, for which I am grateful. % \LaTeX forgets about the first loading. After |switch.def| has % been loaded (above) and |\AfterBabelLanguage| defined, exits. % -% \changes{babel~3.9a}{2012/10/05}{preset option started, -% party stolen from fontenc} -% \changes{babel~3.9a}{2012/10/17}{Hooks started} -% \changes{babel~3.9a}{2013/02/07}{Rejected preset, and replaced by -% base} -% \changes{babel~3.9q}{2016/02/11}{Load patterns with option base. -% To be improved. Moved showlanguages before base} -% \changes{babel~3.18}{2018/02/14}{Fix - prevent doble input of -% switch.def} -% \changes{babel~3.19}{2018/04/23}{Split callback - vertical and -% horizontal} -% \changes{babel~3.19}{2018/04/23}{Added bidi=basic, here and passim} -% % \begin{macrocode} %<*package> \NeedsTeXFormat{LaTeX2e}[2005/12/01] @@ -4821,9 +4775,6 @@ help from Bernd Raichle, for which I am grateful. % |\bbl@languages|), get the name of the 0-th to show the actual % language used. % -% \changes{babel~3.30}{2019/04/22}{Callbacks aren't specific to -% bidi any more, so they are moved.} -% % \begin{macrocode} \ifx\bbl@languages\@undefined\else \begingroup @@ -4931,9 +4882,6 @@ help from Bernd Raichle, for which I am grateful. % modifiers are handled are left to language styles; they can use % |\in@|, loop them with |\@for| or load |keyval|, for example. % -% \changes{babel~3.9e}{2013/04/15}{Bug fixed - a dot was added in -% key=value pairs} -% % \begin{macrocode} \bbl@trace{key=value and another general options} \bbl@csarg\let{tempa\expandafter}\csname opt@babel.sty\endcsname @@ -4961,13 +4909,6 @@ help from Bernd Raichle, for which I am grateful. % to use the shorthand characters in the preamble of their documents % this can help. % -% \changes{babel~3.9a}{2012/08/14}{Implemented the \texttt{noconfigs} -% option} -% \changes{babel~3.9a}{2012/09/26}{Implemented the -% \texttt{showlanguages} option} -% \changes{babel~3.9g}{2013/08/07}{Options for hyphenmap} -% \changes{babel~3.9l}{2014/07/29}{Option \texttt{silent}} -% % \begin{macrocode} \DeclareOption{KeepShorthandsActive}{} \DeclareOption{activeacute}{} @@ -4991,9 +4932,6 @@ help from Bernd Raichle, for which I am grateful. % set with the key |main|, and the third one loads the latter. First, % we ``flag'' valid keys with a nil value. % -% \changes{babel~3.9a}{2012/08/10}{Added the `safe' key, including code -% below for selecting the redefined macros} -% % \begin{macrocode} \let\bbl@opt@shorthands\@nnil \let\bbl@opt@config\@nnil @@ -5052,8 +4990,6 @@ help from Bernd Raichle, for which I am grateful. % |shorthands| is empty. Also, some code makes sense only with % |shorthands=...|. % -% \changes{babel~3.9c}{2013/04/07}{Added t and c for tilde and comma} -% % \begin{macrocode} \bbl@trace{Conditional loading of shorthands} \def\bbl@sh@string#1{% @@ -5103,9 +5039,6 @@ help from Bernd Raichle, for which I am grateful. \fi\fi % \end{macrocode} % -% \changes{babel~3.9a}{2012/07/30}{Code setting language in -% head/foots. Related to babel/3796} -% % With |headfoot=lang| we can set the language used in heads/foots. % For example, in babel/3796 just adds |headfoot=english|. It % misuses \cs{@resetactivechars} but seems to work. @@ -5137,9 +5070,6 @@ help from Bernd Raichle, for which I am grateful. % For |layout| an auxiliary macro is provided, available for packages % and language styles. % -% \changes{babel~3.16}{2018/01/02}{Added the basic layout stuff and the -% macro \cs{IfBabelLayout}} -% % \begin{macrocode} \bbl@trace{Defining IfBabelLayout} \ifx\bbl@opt@layout\@nnil @@ -5157,13 +5087,6 @@ help from Bernd Raichle, for which I am grateful. % % \subsection{Language options} % -% \changes{babel~3.9a}{2012/06/15}{Rewritten the loading mechanism, so -% that languages not declared are also correctly recognized, even -% if given as global options} -% \changes{babel~3.9a}{2012/08/12}{Revised the loading mechanism} -% \changes{babel~3.9i}{2014/03/01}{Removed German options, because -% they are now loaded directly} -% % Languages are loaded when processing the corresponding option % \textit{except} if a |main| language has been set. In such a % case, it is not loaded until all options has been processed. @@ -5193,11 +5116,6 @@ help from Bernd Raichle, for which I am grateful. % % Now, we set language options whose names are different from |ldf| files. % -% \changes{babel~3.9t}{2017/04/23}{Removed options for English, Indonesian and -% Malay, now handled with proxy files} -% \changes{babel~3.13}{2017/08/24}{Removed options for French, -% too. ldf files now takes priority if exist, except Hebrew (to do)} -% % \begin{macrocode} \def\bbl@try@load@lang#1#2#3{% \IfFileExists{\CurrentOption.ldf}% @@ -5228,11 +5146,6 @@ help from Bernd Raichle, for which I am grateful. % of the file with the package option |config=|, which will % load |.cfg| instead. % -% \changes{babel~3.9a}{2012/06/28}{Added the \cs{AfterBabelLanguage} -% mechanism, to be used mainly with the local cfg file.} -% \changes{babel~3.9a}{2012/06/31}{Now you can set the name of the -% local cfg file.} -% % \begin{macrocode} \ifx\bbl@opt@config\@nnil \@ifpackagewith{babel}{noconfigs}{}% @@ -5300,8 +5213,6 @@ help from Bernd Raichle, for which I am grateful. % declared. Those already processed in the first pass are just % ignored. % -% \changes{babel~3.9a}{2012/12/22}{Default option does nothing} -% % The options have to be processed in the order in which the user % specified them (except, of course, global options, which \LaTeX{} % processes before): @@ -5355,11 +5266,6 @@ help from Bernd Raichle, for which I am grateful. % defined. If not, no language has been loaded and an error % message is displayed. % -% \changes{babel~3.9a}{2012/06/24}{Now babel is not loaded to prevent -% the document from raising errors after fixing it} -% \changes{babel~3.21}{2018/05/09}{Requesting a language is no required -% any more, in case you only need \cs{babelprovide}.} -% % \begin{macrocode} \ifx\bbl@main@language\@undefined \bbl@info{% @@ -5398,23 +5304,8 @@ help from Bernd Raichle, for which I am grateful. % |language.def| exists and it is the same file used when formats were % created. % -% \changes{babel~3.9a}{2013/01/11}{Added \cs{bbl@for} for loops -% ignoring empties} -% \changes{babel~3.9c}{2013/04/06}{Normalize \cs{bbl@afterlang} to -% relax} -% \changes{babel~3.9i}{2014/03/10}{Make sure \cs{bbl@language@opts} -% is defined.} -% \changes{babel~3.9i}{2014/03/11}{Define \cs{l@} values from -% \cs{lang@} values set in Plain etex/xetex/luatex} -% % \subsection{Tools} % -% \changes{babel~3.9k}{2014/03/24}{Added definition for -% \cs{uselanguage}} -% \changes{babel~3.9n}{2015/12/21}{Define a few macros for 2.09} -% \changes{babel~3.9p}{2016/02/05}{Added a test for lua(e)tex.} -% \changes{babel~3.9q}{2016/02/12}{Load lua patterns if not lualatex.} -% % \begin{macrocode} \ifx\ldf@quit\@undefined \else @@ -5525,15 +5416,10 @@ help from Bernd Raichle, for which I am grateful. % % \end{macro} % -% \changes{babel~3.9a}{2012/08/10}{Removed the \cs{peek@token} and -% \textsc{test@token} stuff} -% % The macro |\initiate@active@char| takes all the necessary actions % to make its argument a shorthand character. The real work is % performed once for each character. % -% \changes{babel~3.9a}{1999/04/30}{Added \cs{bbl@withactive}} -% % \begin{macrocode} \def\bbl@withactive#1#2{% \begingroup @@ -5616,8 +5502,6 @@ help from Bernd Raichle, for which I am grateful. % for developpers, after all. |\bbl@usehooks| is the commands used by % babel to execute hooks defined for an event. % -% \changes{babel~3.33}{2019/07/16}{Optional argument for languages.} -% % \begin{macrocode} \bbl@trace{Hooks} \newcommand\AddBabelHook[3][]{% @@ -5675,17 +5559,6 @@ help from Bernd Raichle, for which I am grateful. % macro (1) is not restricted to the preamble, and (2) changes are % local. % -% \changes{babel~3.9i}{2014/02/14}{Macro \cs{babelensure} added} -% \changes{babel~3.9k}{2014/03/23}{Encapsulate \cs{foreignlanguage} in -% \cs{bbl@ensure@}language, to "protect" strings} -% \changes{babel~3.9s}{2017/04/10}{Bug fix - extra spaces because a -% missing percent} -% \changes{babel~3.9s}{2017/04/10}{\cs{bbl@ensure@lang} defined only -% once} -% \changes{babel~3.10}{2017/05/06}{\cs{bbl@ensured} renamed to -% \cs{bbl@captionslist} (for \cs{babelprovide}), which means -% \cs{today} must be given explicitly in \cs{babelensure}} -% % \begin{macrocode} \bbl@trace{Defining babelensure} \newcommand\babelensure[2][]{% TODO - revise test files @@ -5783,12 +5656,6 @@ help from Bernd Raichle, for which I am grateful. % |string|. When it is equal to |\@backslashchar| we are dealing % with a control sequence which we can compare with |\@undefined|. % -% \changes{babel~3.9a}{2012/08/11}{\cs{ldf@quit} is not delayed any -% more after \cs{fi} , since \cs{endinput} is not executed -% immediately} -% \changes{babel~3.9g}{2012/08/11}{Preset the ``family'' of macros -% \cs{Babel}...} -% % If so, we call |\ldf@quit| to set the main language, restore the % category code of the @-sign and call |\endinput| % @@ -5851,9 +5718,6 @@ help from Bernd Raichle, for which I am grateful. % a control sequence that needs to be expanded) and reset the % category code of the @-sign. % -% \changes{babel~3.9a}{2012/10/01}{Added \cs{bbl@afterlang} which -% executes the code delayed with \cs{AfterBabelLanguage}} -% % \begin{macrocode} \def\bbl@afterldf#1{% \bbl@afterlang @@ -5899,8 +5763,6 @@ help from Bernd Raichle, for which I am grateful. % beginning of the document. Languages do not set |\pagedir|, so % we set here for the whole document to the main |\bodydir|. % -% \changes{babel~3.34}{2019/09/20}{New hook beforestart.} -% % \begin{macrocode} \def\bbl@beforestart{% \bbl@usehooks{beforestart}{}% @@ -5949,8 +5811,6 @@ help from Bernd Raichle, for which I am grateful. % the original catcode. It does not hurt, but should be fixed. It's % already done with |\nfss@catcodes|, added in 3.10. % -% \changes{babel~3.10}{2017/05/14}{Refactored. Add to \cs{nfss@catcodes} too.} -% % \begin{macrocode} \bbl@trace{Shorhands} \def\bbl@add@special#1{% 1:a macro like \", \?, etc. @@ -6025,9 +5885,6 @@ help from Bernd Raichle, for which I am grateful. % |\@group|, |@active| and |@active| % (except in |system|). % -% \changes{babel~3.9a}{2012/08/18}{New macro, with code from -% \cs{@initiate@active@char}} -% % \begin{macrocode} \def\bbl@active@def#1#2#3#4{% \@namedef{#3#1}{% @@ -6051,9 +5908,6 @@ help from Bernd Raichle, for which I am grateful. \fi}}% % \end{macrocode} % -% \changes{babel~3.9a}{2012/08/18}{Removed an extra hash. Now calls -% \cs{@initiate@active@char} with 3 arguments.} -% % |\initiate@active@char| calls |\@initiate@active@char| with 3 % arguments. All of them are the same character with different % catcodes: active, other (|\string|'ed) and the original one. @@ -6067,17 +5921,6 @@ help from Bernd Raichle, for which I am grateful. {}} % \end{macrocode} % -% \changes{babel~3.9e}{2012/08/18}{Introduced the 3-argument -% \cs{@initiate@active@char}, with different catcodes: active, -% string'ed, and original. Reorganized} -% \changes{babel~3.9a}{2012/08/19}{The catcode is saved} -% \changes{babel~3.9a}{2012/09/09}{The original definition is saved, -% too} -% \changes{babel~3.9a}{2012/12/27}{Take into account mathematically -% active chars, to avoid infinite loops} -% \changes{babel~3.34}{2019/09/23}{Math active in lua has a different -% value} -% % The very first thing to do is saving the original catcode and the % original definition, even if not active, which is possible % (undefined characters require a special treatement to avoid @@ -6150,10 +5993,6 @@ help from Bernd Raichle, for which I am grateful. % the search of a definition in the user, language and system % levels (or eventually |normal@char|\m{char}). % -% \changes{babel~3.9a}{2012/12/27}{Added code for option math=normal} -% \changes{babel~3.9i}{2014/02/03}{Don't call directly -% \cs{user@active}, but with an intermediate step} -% % \begin{macrocode} \let\bbl@tempa\@firstoftwo \if\string^#2% @@ -6177,9 +6016,6 @@ help from Bernd Raichle, for which I am grateful. \expandafter\noexpand\csname user@active#2\endcsname}% % \end{macrocode} % -% \changes{babel~3.9a}{2012/12/27}{Shorthands are not defined -% directly, but with a couple of intermediate macros} -% % We now define the default values which the shorthand is set to % when activated or deactivated. It is set to the deactivated form % (globally), so that the character expands to @@ -6203,9 +6039,6 @@ help from Bernd Raichle, for which I am grateful. % single character shorthand. If that doesn't exist we check for a % shorthand with an argument. % -% \changes{babel~3.9a}{2012/08/18}{Instead of the ``copy-paste pattern'' -% a new macro is used} -% % \begin{macrocode} \bbl@active@def#2\user@group{user@active}{language@active}% \bbl@active@def#2\language@group{language@active}{system@active}% @@ -6220,9 +6053,6 @@ help from Bernd Raichle, for which I am grateful. % would see |\protect'\protect'|. To prevent this from happening a % couple of shorthand needs to be defined at user level. % -% \changes{babel~3.9a}{2012/8/18}{Use \cs{user@group}, as above, -% instead of the hardwired \texttt{user}} -% % \begin{macrocode} \expandafter\edef\csname\user@group @sh@#2@@\endcsname {\expandafter\noexpand\csname normal@char#2\endcsname}% @@ -6238,21 +6068,6 @@ help from Bernd Raichle, for which I am grateful. % works. Therefore an extra level of expansion is introduced with a % check for math mode on the upper level. % -% \changes{babel~3.9a}{2012/09/11}{The output routine resets the quote -% to \cs{active@math@prime}, so we redefine the latter with the new -% ``normal'' value} -% \changes{babel~3.9a}{2012/06/20}{Added a couple of missing -% comment characters (PR 4146)} -% \changes{babel~3.9a}{2012/07/29}{Use \cs{textormath} instead of -% \cs{ifmath}} -% \changes{babel~3.9a}{2012/11/26}{Compare the char, irrespective of -% its catcode.} -% \changes{babel~3.9a}{2012/12/27}{Removed the redeclaration of -% \cs{normal@char'} because it is handled in a generic way above} -% \changes{babel~3.9a}{2012/12/29}{Removed the intermediate step of -% \cs{bbl@act@caret} and moved above} -% \changes{babel~3.9i}{2012/12/29}{Added the event \cs{initiateactive}} -% % \begin{macrocode} \if\string'#2% \let\prim@s\bbl@prim@s @@ -6276,12 +6091,6 @@ help from Bernd Raichle, for which I am grateful. % compatibility. So we need to restore the original catcode at the % end of package \textit{and} and the end of the |ldf|. % -% \changes{babel~3.9a}{2012/07/04}{Catcodes are also restored after -% each language, to prevent incompatibilities. Use \cs{string} instead -% of \cs{noexpand} and add \cs{relax}} -% \changes{babel~3.9a}{2012/10/18}{Catcodes are deactivated in a separate -% macro, which is made no-op when babel exits} -% % \begin{macrocode} \@ifpackagewith{babel}{KeepShorthandsActive}% {\let\bbl@restoreactive\@gobble}% @@ -6307,9 +6116,6 @@ help from Bernd Raichle, for which I am grateful. % will expand to either |\bbl@firstcs| or |\bbl@scndcs|. Hence two % more arguments need to follow it. % -% \changes{babel~3.9a}{2012/08/18}{Removed \cs{string}s, because the -% char are already string'ed} -% % \begin{macrocode} \def\bbl@sh@select#1#2{% \expandafter\ifx\csname#1@sh@#2@sel\endcsname\relax @@ -6331,8 +6137,6 @@ help from Bernd Raichle, for which I am grateful. % depending of |\ifincsname| is available. If there is, the % expansion will be more robust. % -% \changes{babel 3.35}{2019/09/18}{Added \cs{ifincsname} test.} -% % \begin{macrocode} \begingroup \bbl@ifunset{ifincsname}% @@ -6395,9 +6199,6 @@ help from Bernd Raichle, for which I am grateful. % \begin{macro}{\bbl@activate} % \begin{macro}{\bbl@deactivate} % -% \changes{babel~3.9a}{2013/01/11}{\cs{bbl@withactive} makes sure the -% catcode is active} -% % Both macros take one argument, like |\initiate@active@char|. The % macro is used to change the definition of an active character to % expand to |\active@char|\m{char} in the case of |\bbl@activate|, @@ -6440,8 +6241,6 @@ help from Bernd Raichle, for which I am grateful. % \item the code to be executed when the shorthand is encountered. % \end{enumerate} % -% \changes{babel~3.9a}{2012/07/03}{Check if shorthands are redefined} -% % \begin{macrocode} \def\declare@shorthand#1#2{\@decl@short{#1}#2\@nil} \def\@decl@short#1#2#3\@nil#4{% @@ -6478,9 +6277,6 @@ help from Bernd Raichle, for which I am grateful. % definition files have to be usable in both text and mathmode. To % achieve this the helper macro |\textormath| is provided. % -% \changes{babel~3.9a}{2012/12/29}{Failed if an argument had a -% condicional. Use the more robust mechanism of \cs{XXXoftwo}} -% % \begin{macrocode} \def\textormath{% \ifmmode @@ -6521,11 +6317,6 @@ help from Bernd Raichle, for which I am grateful. % version is also provided which activates them always after the % language has been switched. % -% \changes{babel~3.9a}{2012/08/05}{Now \cs{bbl@activate} makes sure -% the catcode is active, so this part is simplified} -% \changes{babel~3.9a}{2012/08/12}{User shorhands can be -% defined even with shorthands=off} -% % \begin{macrocode} \def\useshorthands{% \@ifstar\bbl@usesh@s{\bbl@usesh@x{}}} @@ -6549,11 +6340,6 @@ help from Bernd Raichle, for which I am grateful. % % \begin{macro}{\defineshorthand} % -% \changes{babel~3.9a}{2012/08/05}{Added optional argument, to provide -% a way to (re)define language shorthands} -% \changes{babel~3.9a}{2012/08/25}{Extended for language-dependent -% user macros, with two new auxiliary macros} -% % Currently we only support two groups of user level shorthands, % named internally |user| and |user@| (language-dependent % user shorthands). By default, only the first one is taken into @@ -6612,12 +6398,6 @@ help from Bernd Raichle, for which I am grateful. \initiate@active@char{#2}% % \end{macrocode} % -% \changes{babel~3.9a}{2012/08/06}{Instead of letting the new shorthand to -% the original char, which very often didn't work, we define it -% directly} -% \changes{babel~3.9a}{2012/08/20}{Make sure both characters (old an -% new) are active} -% % Then, we define the new shorthand in terms of the original % one, but note with |\aliasshorthands{"}{/}| is % |\active@prefix /\active@char/|, so we still need to let the @@ -6668,8 +6448,6 @@ help from Bernd Raichle, for which I am grateful. % % \begin{macro}{\bbl@switch@sh} % -% \changes{babel~3.9a}{2013/02/21}{Code revised} -% % The macro |\bbl@switch@sh| takes the list of characters apart one % by one and subsequently switches the category code of the % shorthand character according to the first argument of @@ -6709,8 +6487,6 @@ help from Bernd Raichle, for which I am grateful. % \end{macro} % \end{macro} % -% \changes{babel~3.9a}{2012/06/16}{Added code} -% % Note the value is that at the expansion time, eg, in the preample % shorhands are usually deactivated. % @@ -6742,8 +6518,6 @@ help from Bernd Raichle, for which I am grateful. \fi % \end{macrocode} % -% \changes{babel~3.23}{2018/08/26}{Added \cs{ifbabelshorthand}} -% % You may want to test if a character is a shorthand. Note it does not % test whether the shorthand is on or off. % @@ -6751,14 +6525,9 @@ help from Bernd Raichle, for which I am grateful. \newcommand\ifbabelshorthand[3]{\bbl@ifunset{bbl@active@\string#1}{#3}{#2}} % \end{macrocode} % -% \changes{babel~3.9a}{2012/12/27}{Removed redundant system declarations} -% % \begin{macro}{\bbl@prim@s} % \begin{macro}{\bbl@pr@m@s} % -% \changes{babel~3.9a}{2012/07/29}{\cs{bbl@pr@m@s} rewritten to -% take into account catcodes for both the quote and the hat} -% % One of the internal macros that are involved in substituting |\prime| % for each right quote in mathmode is |\prim@s|. This checks if the % next character is a right quote. When the right quote is active, the @@ -6800,10 +6569,6 @@ help from Bernd Raichle, for which I am grateful. % however, for backward compatibility it is maintained (some % existing documents may rely on the \babel{} value). % -% \changes{babel~3.9i}{2014/02/06}{Moved from above, after -% \cs{bbl@usehook} has been defined} -% \changes{babel~3.9k}{2014/02/06}{Moved again at the original place} -% % \begin{macrocode} \initiate@active@char{~} \declare@shorthand{system}{~}{\leavevmode\nobreak\ } @@ -6841,9 +6606,6 @@ help from Bernd Raichle, for which I am grateful. % enable. % \begin{macro}{\languageattribute} % -% \changes{babel~3.9a}{2012/09/07}{Use \cs{@expandtwoargs} with -% \cs{in@}} -% % The macro |\languageattribute| checks whether its arguments are % valid and then activates the selected language attribute. % First check whether the language is known, and then process each @@ -7133,8 +6895,6 @@ help from Bernd Raichle, for which I am grateful. % |\|\m{tag}. Definitions are first expanded so that they don't % contain |\csname| but the actual macro. % -% \changes{babel~3.9i}{2014/02/21}{Macro \cs{babeltags} added} -% % \begin{macrocode} \bbl@trace{Short tags} \def\babeltags#1{% @@ -7165,8 +6925,6 @@ help from Bernd Raichle, for which I am grateful. % above for further details. We make sure there is a space between % words when multiple commands are used. % -% \changes{babel~3.9a}{2012/08/28}{Macro added} -% % \begin{macrocode} \bbl@trace{Hyphens} \@onlypreamble\babelhyphenation @@ -7200,13 +6958,6 @@ help from Bernd Raichle, for which I am grateful. % % \begin{macro}{\bbl@allowhyphens} % -% \changes{babel-3.9a}{2012/07/28}{Replaced many \cs{allowhyphens} by -% \cs{bbl@allowhyphen}. They were either no-op or executed always.} -% \changes{babel-3.9i}{2014/01/29}{\cs{bbl@allowhyphens} must be -% ignored at the beginning of a paragraph or table cell.} -% \changes{babel-3.9t}{2017/04/26}{Fixed misplaced \cs{nobreak} - -% sx366454 - soft hyphens could vanish.} -% % This macro makes hyphenation possible. Basically its definition % is nothing more than |\nobreak| |\hskip| \texttt{0pt plus % 0pt}\footnote{\TeX\ begins and ends a word for hyphenation at a @@ -7220,9 +6971,6 @@ help from Bernd Raichle, for which I am grateful. % % \end{macro} % -% \changes{babel-3.9a}{2012/08/27}{Added \cs{babelhyphen} and related -% macros} -% % \begin{macro}{\babelhyphen} % % Macros to insert common hyphens. Note the space before |@| in @@ -7310,10 +7058,6 @@ help from Bernd Raichle, for which I am grateful. % % \subsection{Multiencoding strings} % -% \changes{babel~3.9a}{2012/09/05}{Added tentative code for string -% declarations} -% \changes{babel~3.9a}{2012/12/24}{Added hooks} -% % The aim following commands is to provide a commom interface for % strings in several encodings. They also contains several hooks which % can be ued by \luatex{} and \xetex. The code is organized here with @@ -7353,9 +7097,6 @@ help from Bernd Raichle, for which I am grateful. %\end{verbatim} % and starts over (and similarly when lowercasing). % -% \changes{babel~3.9l}{2014/07/29}{Now tries to catch the parsing -% macro. Removed some redundant code. Option |nocase|.} -% % \begin{macrocode} \@ifpackagewith{babel}{nocase}% {\let\bbl@patchuclc\relax}% @@ -7395,11 +7136,6 @@ help from Bernd Raichle, for which I am grateful. % blocks. We make sure strings contain actual letters in the range % 128-255, not active characters. % -% \changes{babel~3.9g}{2013/07/29}{Added starred variant. A bit of -% clean up. Removed \cs{UseString}, which didn't work.} -% \changes{babel~3.9g}{2013/08/01}{Now several languages can be -% processed with \cs{BabelLanguages}, if set in the ldf.} -% % \begin{macrocode} \@onlypreamble\StartBabelCommands \def\StartBabelCommands{% @@ -7453,11 +7189,6 @@ help from Bernd Raichle, for which I am grateful. % these macros are redefined if necessary according to several % parameters. % -% \changes{babel~3.9g}{2013/08/04}{Use \cs{ProvideTextCommand}, which -% does with encoded strings what the manual says.} -% \changes{babel~3.9h}{2013/11/08}{Tidied up code related to -% \cs{bbl@scswitch}} -% % \begin{macrocode} \newcommand\bbl@startcmds@ii[1][\@empty]{% \let\SetString\@gobbletwo @@ -7574,9 +7305,6 @@ help from Bernd Raichle, for which I am grateful. % hooks assigned to this event, preprocessing is done in the same % order as defined. Finally, the string is set. % -% \changes{babel~3.9g}{2013/07/29}{Added \cs{bbl@forlang} to ignore in -% the preamble unknown languages, as described in the doc.} -% % \begin{macrocode} \def\bbl@setstring#1#2{% \bbl@forlang\bbl@tempa{% @@ -7598,9 +7326,6 @@ help from Bernd Raichle, for which I am grateful. % in |\MakeUppercase| and |\MakeLowercase| its value is a modified % expandable |\@changed@cmd|. % -% \changes{babel~3.9i}{2014/03/13}{Added code to expand captions in -% case transformations.} -% % \begin{macrocode} \ifx\bbl@opt@strings\relax \def\bbl@scset#1#2{\def#1{\bbl@encoded#2}} @@ -7629,9 +7354,6 @@ help from Bernd Raichle, for which I am grateful. % Instead of defining a dedicated count, we just ``pre-expand'' % its value. % -% \changes{babel~3.9h}{2013/10/16}{Tidied up and bug fixed - first -% element expanded prematurely.} -% % \begin{macrocode} %<<*Macros local to BabelCommands>> \def\SetStringLoop##1##2{% @@ -7661,9 +7383,6 @@ help from Bernd Raichle, for which I am grateful. % |\MakeUppercase| and |\MakeLowercase|. |\bbl@tempa| is set by the % patched |\@uclclist| to the parsing command. % -% \changes{babel~3.9h}{2013/11/08}{Use \cs{bbl@encstrings} - they -% should be defined always, even if no `strings'} -% % \begin{macrocode} %<<*Macros local to BabelCommands>> \newcommand\SetCase[3][]{% @@ -7725,9 +7444,6 @@ help from Bernd Raichle, for which I am grateful. % The following package options control the behavior of % hyphenation mapping. % -% \changes{babel~3.9t}{2017/04/28}{Renamed \cs{bbl@hymapopt} to -% \cs{bbl@opt@hyphenmap} for consistency} -% % \begin{macrocode} %<<*More package options>> \DeclareOption{hyphenmap=off}{\chardef\bbl@opt@hyphenmap\z@} @@ -7905,9 +7621,6 @@ help from Bernd Raichle, for which I am grateful. % \texttt{T1} encoded fonts, but not in the \texttt{OT1} encoded % fonts. Therefore we fake it for the \texttt{OT1} encoding. % -% \changes{babel~3.9a}{2012/07/28}{Removed the first \cs{allowhyphens}. -% Moved the second one just after the kern.} -% % \begin{macrocode} \DeclareTextCommand{\ij}{OT1}{% i\kern-0.02em\bbl@allowhyphens j} @@ -7995,9 +7708,6 @@ help from Bernd Raichle, for which I am grateful. % very likely not required because their definitions are based on % encoding-dependent macros. % -% \changes{babel~3.16}{2018/01/02}{Adapted to TU and refactored - -% redundant code.} -% % \begin{macro}{\glq} % \begin{macro}{\grq} % @@ -8189,9 +7899,6 @@ help from Bernd Raichle, for which I am grateful. % % Finally, the default is to use English as the main language. % -% \changes{babel~3.9a}{2012-05-17}{Languages are best assigned with -% \cs{chardef}, not \cs{let}} -% % \begin{macrocode} \ifx\l@english\@undefined \chardef\l@english\z@ @@ -8257,9 +7964,6 @@ help from Bernd Raichle, for which I am grateful. \fi % \end{macrocode} % -% \changes{babel~3.18}{2018/02/14}{Moved \cs{babelprovide}, also for -% plain} -% % \subsection{Creating languages} % % |\babelprovide| is a general purpose tool for creating and modifying @@ -8267,32 +7971,6 @@ help from Bernd Raichle, for which I am grateful. % requested, an |ini| file. It may be used in conjunction to previouly % loaded |ldf| files. % -% \changes{babel~3.10}{2017/05/19}{Added \cs{babelprovide}} -% \changes{babel~3.13}{2017/08/30}{Added \cs{import}, which also reads -% dates. Some refactoring in the ini reader.} -% \changes{babel~3.15}{2017/10/30}{New keys script, language} -% \changes{babel~3.16}{2018/01/02}{Make sure ensuring works even before -% the language is selected} -% \changes{babel~3.19}{2018/04/23}{New option - mapfont. Currently -% only with direction} -% \changes{babel~3.20}{2018/05/01}{Handle native digits (TeX level). -% New option - maparabic.} -% \changes{babel~3.23}{2018/09/01}{Valueless import} -% \changes{babel~3.26}{2018/10/16}{Quick fix for xetex - test the -% script for intraspace} -% \changes{babel~3.30}{2019/04/22}{Read some basic parameters from ini -% even without import.} -% \changes{babel~3.30}{2019/04/22}{Native digits (lua level).} -% \changes{babel~3.30}{2019/04/22}{New attribute in luatex for `locale'. Also -% \cs{localeid}} -% \changes{babel~3.32}{2019/05/30}{Activate CJK line breaking with an explicit -% intraspace.} -% \changes{babel~3.34}{2019/09/20}{Fix - with main the language must not -% be restored.} -% \changes{babel~3.37}{2019/12/07}{SEA and CJK linebreaking activated -% by default.} -% \changes{babel~3.38}{2020/01/15}{Code for the onchar option.} -% % \begin{macrocode} \bbl@trace{Creating languages and reading ini files} \newcommand\babelprovide[2][]{% @@ -8367,6 +8045,7 @@ help from Bernd Raichle, for which I am grateful. \bbl@exportkey{dgnat}{numbers.digits.native}{}% \bbl@exportkey{lnbrk}{typography.linebreaking}{h}% \bbl@exportkey{hyphr}{typography.hyphenrules}{}% + \bbl@exportkey{hyoth}{typography.hyphenate.other}{}% \bbl@exportkey{intsp}{typography.intraspace}{}% \endinput \endgroup}% boxed, to avoid extra spaces: @@ -8468,6 +8147,19 @@ help from Bernd Raichle, for which I am grateful. \bbl@csarg\edef{intsp@#2}{\bbl@KVP@intraspace}% \fi \bbl@provide@intraspace + % == hyphenate.other == + \bbl@ifunset{bbl@hyoth@\languagename}{}% + {\bbl@csarg\bbl@replace{hyoth@\languagename}{ }{,}% + \bbl@startcommands*{\languagename}{}% + \bbl@csarg\bbl@foreach{hyoth@\languagename}{% + \ifcase\bbl@engine + \ifnum##1<257 + \SetHyphenMap{\BabelLower{##1}{##1}}% + \fi + \else + \SetHyphenMap{\BabelLower{##1}{##1}}% + \fi}% + \bbl@endcommands} % == maparabic == % Native digits, if provided in ini (TeX level, xe and lua) \ifcase\bbl@engine\else @@ -8580,8 +8272,6 @@ help from Bernd Raichle, for which I am grateful. % % Depending on whether or not the language exists, we define two macros. % -% \changes{babel~3.22}{2018/06/05}{Fix - Error with \cs{chapter} if empty in ini.}- -% % \begin{macrocode} \def\bbl@provide@new#1{% \@namedef{date#1}{}% marks lang exists - required by \StartBabelCommands @@ -8639,9 +8329,6 @@ help from Bernd Raichle, for which I am grateful. % % The |hyphenrules| option is handled with an auxiliary macro. % -% \changes{babel~3.14}{2017/10/03}{Take into account ini settings for -% hyphenrules if `import'.} -% % \begin{macrocode} \def\bbl@provide@hyphens#1{% \let\bbl@tempa\relax @@ -8684,11 +8371,6 @@ help from Bernd Raichle, for which I am grateful. % (in the form |[...]|), a comment (starting with |;|) and a % key/value pair. % -% \changes{babel~3.37}{2019/12/07}{Allow to define key/values -% (added \cs{bbl@renewlist}).} -% \changes{babel~3.38}{2020/01/15}{Read numbers are not hardcoded -% (passim); use \cs{bbl@readstream}.} -% % \begin{macrocode} \ifx\bbl@readstream\@undefined \csname newread\endcsname\bbl@readstream @@ -8745,7 +8427,6 @@ help from Bernd Raichle, for which I am grateful. % section is not ended). By default, key=val pairs are ignored. The % |secpost| ``hook'' is used only by `identification', while |secpre| % only by |date.gregorian.licr|. -% % % \begin{macrocode} \def\bbl@iniskip#1\@@{}% if starts with ; @@ -8800,12 +8481,23 @@ help from Bernd Raichle, for which I am grateful. % is called always (via |\bbl@inisec|), while |\bbl@after@ini| must be % called explicitly after |\bbl@read@ini| if necessary. % -% \changes{babel~3.36}{2019/10/30}{New fields for CJK, because OpenType -% and the CLDR follow different models.} -% % \begin{macrocode} +\def\bbl@iniwarning#1{% + \bbl@ifunset{bbl@@kv@identification.warning#1}{}% + {\bbl@warning{% + From babel-\@nameuse{bbl@lini@\languagename}.ini:\\% + \@nameuse{bbl@@kv@identification.warning#1}\\% + Reported }}} \let\bbl@inikv@identification\bbl@inikv \def\bbl@secpost@identification{% + \bbl@iniwarning{}% + \ifcase\bbl@engine + \bbl@iniwarning{.pdflatex}% + \or + \bbl@iniwarning{.lualatex}% + \or + \bbl@iniwarning{.xelatex}% + \fi% \bbl@exportkey{elname}{identification.name.english}{}% \bbl@exp{\\\bbl@exportkey{lname}{identification.name.opentype}% {\csname bbl@elname@\languagename\endcsname}}% @@ -8825,25 +8517,12 @@ help from Bernd Raichle, for which I am grateful. \bbl@exportkey{prehc}{typography.prehyphenchar}{}% \bbl@exportkey{lnbrk}{typography.linebreaking}{h}% \bbl@exportkey{hyphr}{typography.hyphenrules}{}% + \bbl@exportkey{hyoth}{typography.hyphenate.other}{}% \bbl@exportkey{intsp}{typography.intraspace}{}% \bbl@exportkey{jstfy}{typography.justify}{w}% \bbl@exportkey{chrng}{characters.ranges}{}% \bbl@exportkey{dgnat}{numbers.digits.native}{}% \bbl@exportkey{rqtex}{identification.require.babel}{}% - \bbl@xin@{0.5}{\@nameuse{bbl@@kv@identification.version}}% - \ifin@ - \bbl@warning{% - There are neither captions nor date in `\languagename'.\\% - It may not be suitable for proper typesetting, and it\\% - could change. Reported}% - \fi - \bbl@xin@{0.9}{\@nameuse{bbl@@kv@identification.version}}% - \ifin@ - \bbl@warning{% - The `\languagename' date format may not be suitable\\% - for proper typesetting, and therefore it very likely will\\% - change in a future release. Reported}% - \fi \bbl@toglobal\bbl@savetoday \bbl@toglobal\bbl@savedate} % \end{macrocode} @@ -8883,9 +8562,6 @@ help from Bernd Raichle, for which I am grateful. % % TODO. Remove copypaste pattern. % -% \changes{babel~3.16}{2018/01/02}{Fix - dates were severely broken.} -% \changes{babel~3.28}{2019/04/01}{Start work on calendars.} -% % \begin{macrocode} \bbl@csarg\def{inikv@date.gregorian}#1=#2\@@{% for defaults \bbl@inidate#1...\relax{#2}{}} @@ -8999,10 +8675,6 @@ help from Bernd Raichle, for which I am grateful. % file named as the language (which means any code in it must be % skipped, too. % -% \changes{babel~3.16}{2018/01/02}{Load ids inside a box, to prevent extra -% spaces.} -% \changes{babel~3.34}{2019/08/05}{Added \cs{endinput}.} -% % \begin{macrocode} \def\bbl@ini@basic#1{% \def\BabelBeforeIni##1##2{% @@ -9018,8 +8690,6 @@ help from Bernd Raichle, for which I am grateful. % The information in the identification section can be useful, so the % following macro just exposes it with a user command. % -% \changes{babel~3.38}{2020/01/14}{Added \cs{localeinfo}.} -% % \begin{macrocode} \newcommand\localeinfo[1]{% \bbl@ifunset{bbl@\csname bbl@info@#1\endcsname @\languagename}% @@ -9048,8 +8718,6 @@ help from Bernd Raichle, for which I am grateful. % % \section{Adjusting the Babel bahavior} % -% \changes{babel~3.36}{2019/10/30}{New macro \cs{babeladjust}} -% % A generic high level inteface is provided to adjust some global % and general settings. % @@ -9461,11 +9129,6 @@ help from Bernd Raichle, for which I am grateful. % with the text that is put into them. To achieve this we need to % adapt the definition of |\markright| and |\markboth| somewhat. % -% \changes{babel~3.9t}{2017/04/23}{Refactored \cs{markright} and -% \cs{markboth}} -% \changes{babel~3.23}{2018/09/01}{Trick to isolate the bidi in page -% numbers} -% % We check whether the argument is empty; if it is, we just make % sure the scratch token register is empty. Next, we store the % argument to |\markright| in the scratch token register. This way @@ -9475,9 +9138,6 @@ help from Bernd Raichle, for which I am grateful. % the mark are not disabled by the output routine kicking in while % \cs{@safe@activestrue} is in effect. % -% \changes{babel~3.35}{2019/10/11}{Now \cs{markboth} is protected. -% Consider this case.} -% % \begin{macrocode} \bbl@trace{Marks} \IfBabelLayout{sectioning} @@ -9545,9 +9205,6 @@ help from Bernd Raichle, for which I am grateful. % % \begin{macro}{\ifthenelse} % -% \changes{babel~3.9a}{2012/09/07}{Redefine only if `ref' is `safe'} -% \changes{babel~3.9a}{2013/01/03}{Moved to babel.def} -% % Sometimes a document writer wants to create a special effect % depending on the page a certain fragment of text appears on. This % can be achieved by the following piece of code: @@ -9575,10 +9232,6 @@ help from Bernd Raichle, for which I am grateful. % % Then we can redefine |\ifthenelse|: % -% \changes{babel~3.9a}{2012/06/22}{\cs{ref} is also taken into account} -% \changes{babel~3.9n}{2015/12/14}{Don't use generic temp -% macros. babel/4441} -% % \begin{macrocode} \bbl@redefine@long\ifthenelse#1#2#3{% % \end{macrocode} @@ -9786,13 +9439,6 @@ help from Bernd Raichle, for which I am grateful. % % \begin{macro}{\ensureascii} % -% \changes{babel~3.9i}{2014/02/14}{Macro added, to replace -% \cs{textlatin} and friends} -% \changes{babel~3.9j}{2014/03/17}{Moved misplaced code - it should be -% executed only with LaTeX} -% \changes{babel~3.23}{2018/08/28}{Added TS1, T3, TS3} -% \changes{babel~3.35}{2019/10/01}{Added PU, PD1} -% % \begin{macrocode} \bbl@trace{Encoding and fonts} \newcommand\BabelNonASCII{LGR,X2,OT2,OT3,OT6,LHE,LWN,LMA,LMC,LMS,LMU,PU,PD1} @@ -9857,12 +9503,6 @@ help from Bernd Raichle, for which I am grateful. % internal macro |\@filelist| which contains all the filenames % loaded. % -% \changes{babel~3.9l}{2014/08/02}{fontspec used to set -% \cs{latinencoding} to EUx, but now it doesn't. So, it's done -% here.} -% \changes{babel~3.9o}{2016/01/27}{With fontspec, first check if -% \cs{UTFencname} exists.} -% % \begin{macrocode} \AtBeginDocument{% \@ifpackageloaded{fontspec}% @@ -9876,7 +9516,16 @@ help from Bernd Raichle, for which I am grateful. \ifx\cf@encoding\bbl@t@one \xdef\latinencoding{\bbl@t@one}% \else - \@ifl@aded{def}{t1enc}{\xdef\latinencoding{\bbl@t@one}}{}% + \ifx\@fontenc@load@list\@undefined + \@ifl@aded{def}{t1enc}{\xdef\latinencoding{\bbl@t@one}}{}% + \else + \def\@elt#1{,#1,}% + \edef\bbl@tempa{\expandafter\@gobbletwo\@fontenc@load@list}% + \bbl@xin@{,T1,}\bbl@tempa + \ifin@ + \xdef\latinencoding{\bbl@t@one}% + \fi + \fi \fi}} % \end{macrocode} % @@ -9944,12 +9593,6 @@ help from Bernd Raichle, for which I am grateful. % shows, vertical typesetting is possible, too. % \end{itemize} % -% \changes{babel~3.15}{2017/10/30}{Use an attribute instead of tex language -% (reserved for hyphenation).} -% \changes{babel~3.15}{2017/10/30}{Store direction in @wdir@.} -% \changes{babel~3.28}{2019/04/01}{Dir in boxes within math and other -% contexts (passim).} -% % \begin{macrocode} \bbl@trace{Basic (internal) bidi support} \def\bbl@alscripts{,Arabic,Syriac,Thaana,} @@ -10083,9 +9726,6 @@ help from Bernd Raichle, for which I am grateful. % properly handle the par direction. Note text and par dirs are % decoupled to some extent (although not completely). % -% \changes{babel~3.16}{2018/01/02}{Fix - the direction prevented the removal -% of the indent to be re-placed} -% % \begin{macrocode} \def\bbl@xebidipar{% \let\bbl@xebidipar\relax @@ -10120,8 +9760,6 @@ help from Bernd Raichle, for which I am grateful. % A tool for weak L (mainly digits). We also disable warnings with % \textsf{hyperref}. % -% \changes{babel~3.16}{2018/01/02}{New macro \cs{babelsublr}} -% % \begin{macrocode} \DeclareRobustCommand\babelsublr[1]{\leavevmode{\bbl@textdir\z@#1}} \AtBeginDocument{% @@ -10199,9 +9837,6 @@ help from Bernd Raichle, for which I am grateful. % or variant language, for which an already defined hyphenation % table can be used. % -% \changes{babel~3.36}{2019/11/07}{Improved message, now showing the -% language name} -% % \begin{macrocode} \def\bbl@version{<@version@>} \def\bbl@date{<@date@>} @@ -10216,16 +9851,12 @@ help from Bernd Raichle, for which I am grateful. (\string\language\the\count@)}% \def\bbl@elt####1####2####3####4{}% \fi}% - \bbl@languages + \@nameuse{bbl@languages}% \endgroup} % \end{macrocode} % % \end{macro} % -% \changes{babel~3.9a}{2012/09/07}{Added macro} -% \changes{babel~3.9a}{2013/01/23}{New macro to normalize -% a macro (eg, \cs{languagename}) to lowercase if necessary} -% % |\bbl@iflanguage| executes code only if the language |l@| % exists. Otherwise raises and error. % @@ -10309,9 +9940,6 @@ help from Bernd Raichle, for which I am grateful. % If the user gives an empty argument, we provide a default % argument for |\string|. This argument should expand to nothing. % -% \changes{babel~3.9a}{2012/11/16}{\cs{bbl@select@type} keep tracks of -% the selection method: 0 is select, 1 is foreign} -% % \begin{macrocode} \let\bbl@select@type\z@ \edef\selectlanguage{% @@ -10477,17 +10105,6 @@ help from Bernd Raichle, for which I am grateful. % We also write a command to change the current language in the % auxiliary files. % -% \changes{babel~3.9a}{2012/09/09}{Added hook} -% \changes{babel~3.9a}{2012/11/07}{Use a loop for contents files, with -% the help of \cs{BabelContentsFiles}} -% \changes{babel~3.9a}{2013/03/08}{Don't write to aux if language is -% unknown} -% \changes{babel~3.9h}{2013/11/20}{Error with a more helpful text } -% \changes{babel~3.16}{2018/01/02}{New mechanism to pass the language -% to aux, toc, etc.} -% \changes{babel~3.22}{2018/06/05}{Unknown languages in aux files do -% not raise an error any more (only a warning).} -% % \begin{macrocode} \def\BabelContentsFiles{toc,lof,lot} \def\bbl@set@language#1{% from selectlanguage, pop@ @@ -10561,12 +10178,6 @@ help from Bernd Raichle, for which I am grateful. % update the value of |\language| and call |\originalTeX| % to bring \TeX\ in a certain pre-defined state. % -% \changes{babel~3.9a}{2012/07/27}{Moved \cs{bbl@patterns} to the -% correct place, after setting the extras for the current -% language} -% \changes{babel~3.9a}{2012/08/01}{Created \cs{bbl@switch} with code -% shared by \cs{select@language} and \cs{foreing@language}} -% % The name of the language is stored in the control sequence % |\languagename|. % @@ -10589,19 +10200,6 @@ help from Bernd Raichle, for which I am grateful. % defined. If it is not, we set default values (2 and 3), otherwise % the values in |\|\langvar|hyphenmins| will be used. % -% \changes{babel~3.9a}{2012/08/01}{Adddd \cs{bbl@iflanguagename} and -% \cs{select@language@x}, which is no-op if the language is the same} -% \changes{babel~3.9a}{2013/01/23}{\cs{select@language} sets -% \textsc{languagename} so that it has the correct value in the aux -% file (eg, shorthand expansion was wrong)} -% \changes{babel~3.9a}{2012/08/14}{Make sure the save counter is reset -% even if \cs{originalTeX} is used in other contexts} -% \changes{babel~3.9c}{2013/04/08}{Removed an extra empty line} -% \changes{babel~3.9h}{2013/11/29}{Use \cs{def} instead of -% \cs{renewcommand} for \cs{BabelLower}} -% \changes{babel~3.9i}{2014/03/04}{Added `afterreset' hook} -% \changes{babel~3.15}{2017/10/30}{Remove spaces inside captions and date.} -% % \begin{macrocode} \newif\ifbbl@usedategroup \def\bbl@switch#1{% from select@, foreign@ @@ -10684,8 +10282,6 @@ help from Bernd Raichle, for which I am grateful. % The |\ignorespaces| command is necessary to hide the environment % when it is entered in horizontal mode. % -% \changes{babel~3.9a}{2012/07/31}{Removed \cs{originalTeX}} -% % \begin{macrocode} \long\def\otherlanguage#1{% \ifnum\bbl@hymapsel=\@cclv\let\bbl@hymapsel\thr@@\fi @@ -10764,16 +10360,6 @@ help from Bernd Raichle, for which I am grateful. % enters into hmode with the surrounding lang, and with % |\foreignlanguage*| with the new lang. % -% \changes{babel~3.9a}{2012/07/30}{Removed unnecesary \cs{noextras} -% just before closing the group} -% \changes{babel~3.9a}{2012/07/31}{Moved \cs{originalTeX} to -% \cs{foreing@language} so that it's also used in -% \texttt{otherlanguage*}} -% \changes{babel~3.9a}{2012/12/24}{\cs{foreignlanguage} defined -% similarly to \cs{selectlanguage}, protecting the whole macro} -% \changes{babel~3.11}{2017/03/04}{\cs{foreignlanguage*}, -% \cs{bbl@beforeforeign} and hooks} -% % \begin{macrocode} \providecommand\bbl@beforeforeign{} \edef\foreignlanguage{% @@ -10810,9 +10396,6 @@ help from Bernd Raichle, for which I am grateful. % check that it is a known language. Then it just calls % |bbl@switch|. % -% \changes{babel~3.9h}{2013/11/29}{The warning shows the language -% actually selected (with fixed case)} -% % \begin{macrocode} \def\foreign@language#1{% % set name @@ -10843,11 +10426,6 @@ help from Bernd Raichle, for which I am grateful. % % \begin{macro}{\bbl@patterns} % -% \changes{babel~3.9a}{2012/08/28}{Extended to set hyphenation -% exceptions as defined with \cs{babelhyphenation}} -% \changes{babel~3.9m}{2015/07/25}{Preset \cs{bbl@pttnlist} and -% \cs{bbl@patterns@} to relax, for luatex.} -% % This macro selects the hyphenation patterns by changing the % \cs{language} register. If special hyphenation patterns % are available specifically for the current font encoding, @@ -10903,9 +10481,6 @@ help from Bernd Raichle, for which I am grateful. % |\lccode|'s and font encodings are not set at all, so in most % cases you should use |otherlanguage*|. % -% \changes{babel~3.15}{2017/10/30}{Don't set language name. Use temp macro.} -% \changes{babel~3.15}{2018/02/14}{Fix - didn't work with polyglossia} -% % \begin{macrocode} \def\hyphenrules#1{% \edef\bbl@tempf{#1}% @@ -10962,10 +10537,6 @@ help from Bernd Raichle, for which I am grateful. % Depending on the format, ie, on if the former is defined, we use % a similar definition or not. % -% \changes{babel~3.9a}{2012/12/09}{Save info about the babel -% version in the format (switch.def) so that it can be checked -% later if necessary} -% % \begin{macrocode} \ifx\ProvidesFile\@undefined \def\ProvidesLanguage#1[#2 #3 #4]{% @@ -11031,8 +10602,6 @@ help from Bernd Raichle, for which I am grateful. % A few macro names are reserved for future releases of \babel, which % will use the concept of `locale': % -% \changes{babel~3.9s}{2017/04/13}{Reserved macro names for `locale'} -% % \begin{macrocode} \providecommand\setlocale{% \bbl@error @@ -11070,13 +10639,6 @@ help from Bernd Raichle, for which I am grateful. % people think warnings are errors, so a further message type is % defined: an important info which is sent to the console. % -% \changes{babel~3.9a}{2012/07/30}{\cs{newcommand}s replaced by -% \cs{def}'s, so that the file can be loaded twice} -% \changes{babel~3.9a}{2013/01/26}{Define generic variants instead of -% duplicating each predefined message} -% \changes{babel~3.37}{2019/12/07}{New message type: an into written to -% the console.} -% % \begin{macrocode} \edef\bbl@nulllanguage{\string\language=0} \ifx\PackageError\@undefined @@ -11172,8 +10734,6 @@ help from Bernd Raichle, for which I am grateful. % this code in the file \file{hyphen.cfg}. Code is written with lower % level macros. % -% \changes{babel~3.9g}{2013/05/30}{Code moved from plain.def} -% % We want to add a message to the message \LaTeX$\:$2.09 puts in % the |\everyjob| register. This could be done by the following % code: @@ -11245,9 +10805,6 @@ help from Bernd Raichle, for which I am grateful. % |\process@synonym| is called; otherwise the macro % |\process@language| will continue. % -% \changes{babel~3.9a}{2012/12/12}{Use spaces as delimiters, to avoid -% extra spaces. Once parsed, pass them in the traditional way} -% % \begin{macrocode} \def\process@line#1#2 #3 #4 {% \ifx=#1% @@ -11281,8 +10838,6 @@ help from Bernd Raichle, for which I am grateful. % % We also need to copy the hyphenmin parameters for the synonym. % -% \changes{babel~3.9a}{2012/06/25}{Added \cs{bbl@languages}} -% % \begin{macrocode} \def\process@synonym#1{% \ifnum\last@language=\m@ne @@ -11311,10 +10866,6 @@ help from Bernd Raichle, for which I am grateful. % register and to make that register `active'. Then the pattern file % is read. % -% \changes{babel~3.9a}{2012/12/10}{Removed \cs{selectfont} (I presume -% it was intended to catch wrong encoding codes, but I don't think -% this is necessary and as a side effect it might preload fonts)} -% % For some hyphenation patterns it is needed to load them with a % specific font encoding selected. This can be specified in the % file \file{language.dat} by adding for instance `\texttt{:T1}' to @@ -11344,10 +10895,6 @@ help from Bernd Raichle, for which I am grateful. % not contain a space token. (Note however there is no need to save % hyphenation exceptions into the format.) % -% \changes{babel~3.9a}{2012/06/25}{Added \cs{bbl@languages}} -% \changes{babel~3.9f}{2013/05/16}{Restored code to set default -% hyphenmins, which was deleted mistakenly} -% % \cs{bbl@languages} saves a snapshot of the loaded languages in the % form \cs{bbl@elt}\marg{language-name}\marg{number}% % \marg{patterns-file}\marg{exceptions-file}. Note the last 2 @@ -11397,8 +10944,6 @@ help from Bernd Raichle, for which I am grateful. % % \begin{macro}{\bbl@get@enc} % -% \changes{babel~3.9a}{2012/12/11}{Code much simplified} -% % \begin{macro}{\bbl@hyph@enc} % The macro |\bbl@get@enc| extracts the font encoding from the % language name and stores it in |\bbl@hyph@enc|. It uses delimited @@ -11416,9 +10961,6 @@ help from Bernd Raichle, for which I am grateful. % here in a special way. Besides \luatex, format-specific % configuration files are taken into account. % -% \changes{babel~3.9b}{2013/03/25}{Fixed an idiot slip: \cs{def} -% intead of \cs{let}} -% % \begin{macrocode} \def\bbl@hook@everylanguage#1{} \def\bbl@hook@loadpatterns#1{\input #1\relax} @@ -11496,10 +11038,6 @@ help from Bernd Raichle, for which I am grateful. \endlinechar`\^^M % \end{macrocode} % -% \changes{babel~3.9a}{2012/12/14}{Test simplified and moved} -% \changes{babel~3.9a}{2012/12/12}{Use only spaces as delimiters and -% not /, as previouly done} -% % If the file has reached its end, exit from the loop here. If not, % empty lines are skipped. Add 3 space characters to the end of % |\bbl@line|. This is needed to be able to recognize the arguments @@ -11539,15 +11077,6 @@ help from Bernd Raichle, for which I am grateful. % format and with which language patterns to the \cs{everyjob} % register. % -% \changes{babel~3.9a}{2012/09/25}{The list of languages is not -% printed every job any more (it is saved in \cs{bbl@languages}).} -% \changes{babel~3.9g}{2013/07/28}{In non-LaTeX formats the number of -% languages were not printed. Moved from \cs{dump} and cleaned up: -% now \cs{toks}8 is expanded here.} -% \changes{babel~3.9o}{2016/01/25}{The number of languages loaded was -% off by 1.} -% \changes{babel~3.21}{2018/05/09}{The message is not printed any more.} -% % \begin{macrocode} \if/\the\toks@/\else \errhelp{language.dat loads no language, only synonyms} @@ -11560,9 +11089,6 @@ help from Bernd Raichle, for which I am grateful. % latter is not required and the line inputting it may be commented % out. % -% \changes{babel~3.9a}{2012/12/11}{Raise error if there are synonyms -% without languages} -% % \begin{macrocode} \let\bbl@line\@undefined \let\process@line\@undefined @@ -11583,15 +11109,10 @@ help from Bernd Raichle, for which I am grateful. % % \section{Font handling with fontspec} % -% \changes{babel~3.15}{2017/10/30}{New way to select fonts, with \cs{babelfont}} -% % Add the bidi handler just before luaoftload, which is loaded by default % by LaTeX. Just in case, consider the possibility it has not been % loaded. First, a couple of definitions related to bidi [misplaced]. % -% \changes{babel~3.30}{2019/04/22}{Ensure the current textdir inside -% boxes within math.} -% % \begin{macrocode} %<<*More package options>> \ifodd\bbl@engine @@ -11659,9 +11180,6 @@ help from Bernd Raichle, for which I am grateful. % |bbl@font| replaces hardcoded font names inside |\..family| by the % corresponding macro |\..default|. % -% \changes{babel~3.34}{2019/08/29}{Better checks for fonts, and improved -% compatibility with fontspec.} -% % \begin{macrocode} %<<*Font selection>> \bbl@trace{Font handling with fontspec} @@ -11803,9 +11321,6 @@ help from Bernd Raichle, for which I am grateful. % |\bbl@mapselect| because |\selectfont| is called internally when a % font is defined. % -% \changes{babel~3.28}{2019/04/01}{\cs{babelfont} now based on -% \cs{newfontfamily}.} -% % \begin{macrocode} \def\bbl@font@set#1#2#3{% eg \bbl@rmdflt@lang \rmdefault \rmfamily \bbl@xin@{<>}{#1}% @@ -11922,11 +11437,6 @@ help from Bernd Raichle, for which I am grateful. % changes done by \LaTeX. Anyway, for consistency Lua\TeX{} also % resets the catcodes. % -% \changes{bbunicode~1.0c}{2014/03/10}{Reset ``codes'' set by \cs{LaTeX} -% to what xetex expects. Used also in luatex.} -% \changes{bbunicode~1.0f}{2015/12/06}{This block was assigned to -% xetex, even in luatex. Fixed here and below.} -% % \begin{macrocode} %<<*Restore Unicode catcodes before loading patterns>> \begingroup @@ -11962,8 +11472,6 @@ help from Bernd Raichle, for which I am grateful. % % Some more common code. % -% \changes{babel 3.17}{2018/01/24}{Tools for bidi footnote} -% % \begin{macrocode} %<<*Footnote changes>> \bbl@trace{Bidi footnotes} @@ -12076,9 +11584,6 @@ help from Bernd Raichle, for which I am grateful. % % \subsection{Layout} % -% \changes{babel~3.16}{2018/01/02}{Option layout - first available options: -% sectioning, counters, lists, columns, contents} -% % \textit{In progress.} % % Note elements like headlines and margins can be modified easily with @@ -12093,9 +11598,6 @@ help from Bernd Raichle, for which I am grateful. % Consider |txtbabel| as a shorthand for \textit{tex--xet babel}, % which is the bidi model in both \pdftex{} and \xetex{}. % -% \changes{babel~3.32}{2019/05/04}{\cs{@tabular}, \cs{list}, etc., are -% patched, instead of redefined.} -% % \begin{macrocode} %<*texxet> \providecommand\bbl@provide@intraspace{} @@ -12231,29 +11733,6 @@ help from Bernd Raichle, for which I am grateful. % complicate things, \textsf{etex.sty} changes the way languages are % allocated. % -% \changes{bbunicode~1.0b}{2013/04/22}{luatex-hyphen is loaded with -% require. Changes supplied by \'{E}lie Roux.} -% \changes{bbunicode~1.0c}{2014/03/10}{Defined hook for -% `initiateactive', to fetch the next token and continue only if -% letter or other.} -% \changes{bbunicode~1.0d}{2014/03/21}{Removed the `misfeature' for -% `initiateactive'.} -% \changes{bbunicode~1.0e}{2015/05/10}{Use brackets instead of -% \cs{luaescapestring}.} -% \changes{bbunicode~1.0e}{2015/07/26}{Added function addpattern -% and modified the patterns hook.} -% \changes{bbunicode~1.1a}{2016/01/26}{New hyphenation loader for -% luatex.} -% \changes{bbunicode~1.1b}{2016/02/05}{Also lua(e)tex.} -% \changes{bbunicode~1.1c}{2016/02/08}{Base reading of patterns on -% number, not in name.} -% \changes{bbunicode~1.1c}{2016/02/08}{Some hacks for polyglossia. To -% be improved.} -% \changes{bbunicode~1.1c}{2016/02/23}{Thoroughly revised.} -% \changes{bbunicode~1.1d}{2016/4/22}{Lua: Fixed a line break at -% \cs{foreignlanguage} with unloaded patterns. Added -% \cs{babelcatcodetablenum}, just in case.} -% % \begin{macrocode} %<*luatex> \ifx\AddBabelHook\@undefined @@ -12521,7 +12000,6 @@ help from Bernd Raichle, for which I am grateful. % |\bbl@patterns@| for the global ones and |\bbl@patterns@| % for language ones. We make sure there is a space between words % when multiple commands are used. -% \changes{bbunicode~1.0e}{2015/07/26}{Macro \cs{babelpatterns} added} % % \begin{macrocode} \@onlypreamble\babelpatterns @@ -12554,12 +12032,6 @@ help from Bernd Raichle, for which I am grateful. % % \subsection{Southeast Asian scripts} % -% \changes{babel~3.24}{2018/09/24}{Lua code for interword spacing -% in Southeast Asian scripts.} -% \changes{babel~3.32}{2019/05/25}{Don't break with CJK if nohyphenation.} -% \changes{babel~3.37}{2019/12/07}{Added code for non-standard -% hyphenation.} -% % First, some general code for line breaking, used by % |\babelposthyphenation|. % @@ -12791,8 +12263,6 @@ help from Bernd Raichle, for which I am grateful. % (fullwidth \textit{vs.} halfwidth), not yet used. There is a separate % file, defined below. % -% \changes{babel~3.31}{2019/05/04}{Simple CJK line breaking.} -% % \textit{Work in progress.} % % Common stuff. @@ -12820,8 +12290,6 @@ help from Bernd Raichle, for which I am grateful. % from the global one (the key) to the local one (the value). Maths are % skipped and discretionaries are handled in a special way. % -% \changes{babel~3.38}{2020/01/15}{Automatic fonts and ids switching} -% % \begin{macrocode} \directlua{ Babel.script_blocks = { @@ -12918,8 +12386,6 @@ end } % \end{macrocode} % -% \changes{babel~3.32}{2019/05/23}{New - \cs{babelcharproperty}.} -% % The code for |\babelcharproperty| is straightforward. Just note the % modified lua table can be different. % @@ -13282,14 +12748,6 @@ end % \textsf{hhline}, \textsf{colortbl}, \textsf{longtable}, % \textsf{booktabs}, etc. However, \textsf{dcolumn} still fails. % -% \changes{babel~3.18}{2018/02/14}{\cs{bbl@nextfake}, similar to the old -% \cs{nextfakemath} in Omega} -% \changes{babel~3.19}{2018/04/23}{Patch \cs{@eqnnum}, somewhat ad hoc. To be -% improved.} -% \changes{babel~3.21}{2018/05/09}{The ad hoc \cs{@eqnnum} was buggy. Fixed.} -% \changes{babel~3.31}{2019/05/04}{\cs{@tabular} and \cs{list} are patched, -% instead of redefined.} -% % \begin{macrocode} \bbl@trace{Redefinitions for bidi layout} \ifx\@eqnnum\@undefined\else @@ -13409,8 +12867,6 @@ end % formatting. They have very little in common and are grouped here, as % a single option. % -% \changes{babel~3.19}{2018/04/23}{New option extras for layout} -% % \begin{macrocode} \IfBabelLayout{extras}% {\let\bbl@OL@underline\underline @@ -13426,10 +12882,6 @@ end % % \subsection{Auto bidi with \texttt{basic} and \texttt{basic-r}} % -% \changes{babel~3.14}{2017/09/30}{LuaTeX - support for R/AL texts - basic-r} -% \changes{babel~3.35}{2019/10/11}{Hack for unboxed boxes - The PUAs -% are `on'.} -% % The file \textsf{babel-data-bidi.lua} currently only contains data. It is % a large and boring file and it is not shown here (see the generated file), % but here is a sample: @@ -19575,10 +19027,6 @@ Babel.characters={ % excels, because everything related to bidi writing is under our % control. % -% \changes{babel~3.20}{2018/05/01}{Adapted to exhyphens in luatex >= -% 1.07. Fix - now attr@dir is mod 3.} -% \changes{babel~3.30}{2019/04/22}{Switch to enable/disable bidi.} -% % \begin{macrocode} %<*basic-r> Babel = Babel or {} @@ -19846,8 +19294,6 @@ end % \end{macrocode} % % And here the Lua code for |bidi=basic|: -% \changes{babel~3.20}{2018/05/01}{Adapted to exhyphens in luatex >= -% 1.07. Fix - nsm in mapfont (eg, Arabic vowels)} % % \begin{macrocode} %<*basic> @@ -20530,10 +19976,6 @@ Babel.cjk_breaks = { % command, \texttt{nil} could be an `unknown' language in which % case we have to make it known. % -% \changes{babel-3.32}{2019/05/21}{Don't set it to -% \cs{l@nohyphenation}, best reserved fo special uses.} -% \changes{babel~3.36}{2019/10/30}{Add nil to the language list.} -% % \begin{macrocode} \ifx\l@nil\@undefined \newlanguage\l@nil @@ -20684,9 +20126,6 @@ Babel.cjk_breaks = { % The following code duplicates or emulates parts of \LaTeXe\ that % are needed for \babel. % -% \changes{bbplain-1.0s}{2012/12/21}{\cs{loadlocalcfg} not loaded in -% the format} -% % \begin{macrocode} %<*plain> \def\@empty{} @@ -20709,12 +20148,6 @@ Babel.cjk_breaks = { % % A number of \LaTeX\ macro's that are needed later on. % -% \changes{bbplain-1.0t}{2013/04/10}{Added \cs{@expandtwoargs}} -% \changes{babel~3.9h}{2013/12/02}{Added \cs{zap@space}} -% \changes{babel~3.9k}{2014/03/22}{Added \cs{@nnil}} -% \changes{babel~3.9k}{2014/03/22}{Added \cs{@gobbletwo}} -% \changes{babel~3.9k}{2014/03/22}{Added \cs{protected@edef}} -% % \begin{macrocode} \long\def\@firstofone#1{#1} \long\def\@firstoftwo#1#2{#1} @@ -20791,9 +20224,6 @@ Babel.cjk_breaks = { % replacement macro is much simpler; it stores its argument in % |\@endofldf|. % -% \changes{babel~3.9h}{2013/11/28}{Set \cs{bbl@opt@hyphenmap} to 0 - we -% presume hyphenmap=off in plain} -% % \begin{macrocode} \def\AtEndOfPackage#1{\g@addto@macro\@endofldf{#1}} \@onlypreamble\AtEndOfPackage @@ -20888,9 +20318,6 @@ Babel.cjk_breaks = { % inside conditionally executed code is not possible, hence the % construct with the temporary definition of |\bbl@tempa|. % -% \changes{bbplain-1.0s}{2013/01/15}{Use \cs{bbl@tempa} as -% documented} -% % \begin{macrocode} \def\bbl@tempa{\csname newif\endcsname\ifin@} \ifx\in@\@undefined diff --git a/macros/latex/required/babel/base/babel.ins b/macros/latex/required/babel/base/babel.ins index 86e70a5fc6..ad993d6a1e 100644 --- a/macros/latex/required/babel/base/babel.ins +++ b/macros/latex/required/babel/base/babel.ins @@ -26,7 +26,7 @@ %% and covered by LPPL is defined by the unpacking scripts (with %% extension .ins) which are part of the distribution. %% -\def\filedate{2020/02/03} +\def\filedate{2020/02/14} \def\batchfile{babel.ins} \input docstrip.tex diff --git a/macros/latex/required/babel/base/babel.pdf b/macros/latex/required/babel/base/babel.pdf index fd66d129fc..d511adc135 100644 Binary files a/macros/latex/required/babel/base/babel.pdf and b/macros/latex/required/babel/base/babel.pdf differ diff --git a/macros/latex/required/babel/base/bbcompat.dtx b/macros/latex/required/babel/base/bbcompat.dtx index 610eb84045..be409112ab 100644 --- a/macros/latex/required/babel/base/bbcompat.dtx +++ b/macros/latex/required/babel/base/bbcompat.dtx @@ -30,7 +30,7 @@ % % \iffalse %<*dtx> -\ProvidesFile{bbcompat.dtx}[2020/02/03 v3.39] +\ProvidesFile{bbcompat.dtx}[2020/02/14 v3.40] % % %% File 'bbcompat.dtx' diff --git a/macros/xetex/latex/xecjk/xeCJK.dtx b/macros/xetex/latex/xecjk/xeCJK.dtx index 1f66d8cff1..1d528a3997 100644 --- a/macros/xetex/latex/xecjk/xeCJK.dtx +++ b/macros/xetex/latex/xecjk/xeCJK.dtx @@ -194,7 +194,7 @@ Copyright and Licence %<*package|config|fntef|listings|xunicode|xunextra> %\NeedsTeXFormat{LaTeX2e} %\RequirePackage{expl3} -%<+!driver>\GetIdInfo$Id: xeCJK.dtx 06a6ce4 2020-02-10 22:37:50 +0800 Qing Lee $ +%<+!driver>\GetIdInfo$Id: xeCJK.dtx 2628481 2020-02-14 20:30:07 +0800 Qing Lee $ % {Typesetting CJK scripts with XeLaTeX} % {Configuration file for xeCJK package} % {xeCJK font effect} @@ -207,7 +207,7 @@ Copyright and Licence %\ProvidesExplPackage{xeCJK-listings} %\ProvidesExplPackage{xunicode-addon} %\ProvidesExplFile{xunicode-extra.def} -% {\ExplFileDate}{3.8.0}{\ExplFileDescription} +% {\ExplFileDate}{3.8.1}{\ExplFileDescription} % %<*driver> \documentclass{ctxdoc} @@ -225,6 +225,8 @@ Copyright and Licence \newcommand\PSKeyVal[2]{% \item[#1]\makebox[4em][l]{\meta{#2}}\ignorespaces} \newcommand\tokslink[1]{\hyperlink{#1}{\ding{51}}} +\newcommand\ghissue[1]{% + \href{https://github.com/CTeX-org/ctex-kit/issues/#1}{\##1}} \AtBeginDocument{\DeleteShortVerb{\"}} \ExplSyntaxOn \NewDocumentCommand \PrintPunctList { O{7} m m } @@ -283,7 +285,7 @@ Copyright and Licence % \changes{v3.8.0}{2020/02/09}{兼容 \LaTeXe\ 2020/02/02 对 \pkg{NFSS} 的修改。} % \changes{v3.8.0}{2020/02/09}{清理过时的兼容性补丁代码。} % -% \CheckSum{10751} +% \CheckSum{10752} % \GetFileId{xeCJK.sty} % % \title{\bfseries\pkg{xeCJK} 宏包} @@ -6606,11 +6608,8 @@ Copyright and Licence } \cs_new_protected_nopar:Npn \@@_select_font:Nn #1#2 { - \cs_if_exist_use:NF #1 - { - \@@_family_use:n {#2} - \xeCJK_font_gset_to_current:N #1 - } + \cs_if_exist:NF #1 { \@@_font_initial:Nn #1 {#2} } + #1 } \cs_generate_variant:Nn \@@_select_font:Nn { c } \tl_new:N \l_@@_current_coor_tl @@ -6619,6 +6618,22 @@ Copyright and Licence % \end{variable} % \end{macro} % +% \changes{v3.8.1}{2020/02/14}{修复 \cs{l_xeCJK_current_font_tl} 标记错误。} +% +% \begin{macro}{\@@_font_initial:Nn} +% 注意要将 \tn{selectfont} 放在分组中调用,防止 \tn{f@series} 等字体参数被修改, +% 导致 \cs{l_xeCJK_current_font_tl} 标记前后不一致,引发错误(见~\ghissue{486})。 +% \begin{macrocode} +\cs_new_protected_nopar:Npn \@@_font_initial:Nn #1#2 + { + \group_begin: + \@@_family_use:n {#2} + \xeCJK_font_gset_to_current:N #1 + \group_end: + } +% \end{macrocode} +% \end{macro} +% % \begin{macro}[int]{\xeCJK_select_punct_font:} % \begin{variable}[int]{\l_xeCJK_current_punct_font_tl} % 切换标点符号字体。 @@ -6676,8 +6691,7 @@ Copyright and Licence \cs_if_exist_use:NF #1 { \xeCJK_block_family:nn {#2} {#3} - \@@_family_use:n { #2/#3 } - \xeCJK_font_gset_to_current:N #1 + \@@_font_initial:Nn #1 { #2/#3 } } } \cs_generate_variant:Nn \@@_select_font:Nnn { c } @@ -6704,30 +6718,27 @@ Copyright and Licence { xeCJK/family/#1 } \cs_new_nopar:Npn \@@_family_nfss_csname:n #1 { xeCJK/family/nfss/#1 } -\cs_new_nopar:Npn \@@_family_use:n #1 +\cs_new_protected_nopar:Npn \@@_family_use:n #1 { \use:c { \@@_family_nfss_csname:n {#1} } } \cs_new_protected_nopar:Npn \@@_gset_family_nfss_cs:nn #1#2 { \prop_gput:Nnn \g_@@_family_name_prop {#1} {#2} \cs_gset_protected_nopar:cpx { \@@_family_nfss_csname:n {#1} } - { - \exp_not:N \fontencoding { \c_@@_encoding_tl } - \@@_nfss_family:n {#2} - \exp_not:N \selectfont - } + { \@@_nfss_family:nn { \c_@@_encoding_tl } {#2} } } \cs_generate_variant:Nn \@@_gset_family_nfss_cs:nn { xx } % \end{macrocode} % \end{macro} % % \begin{macro}{\@@_nfss_family:n} -% 用于处理 \LaTeXe\ 2020/02/02 中 \tn{bfseries@rm} 等与 \tn{\bfdefault} 不一致可能导致的问题。 +% 用于处理 \LaTeXe\ 2020/02/02 中 \tn{bfseries@rm} 等与 \tn{bfdefault} 不一致可能导致的问题。 % \begin{macrocode} \cs_if_exist:NTF \fontseriesforce { - \cs_new_protected_nopar:Npn \@@_nfss_family:n #1 + \cs_new_protected_nopar:Npn \@@_nfss_family:nn #1#2 { + \fontencoding {#1} \str_if_eq:eeF { \f@series } { \bfdefault } { \str_case_e:nn { \f@family } @@ -6737,7 +6748,8 @@ Copyright and Licence { \ttdefault } { \@@_nfss_series:n { tt } } } } - \fontfamily {#1} + \fontfamily {#2} + \selectfont } \cs_new_protected_nopar:Npn \@@_nfss_series:n #1 { @@ -6746,8 +6758,12 @@ Copyright and Licence } } { - \cs_new_protected_nopar:Npn \@@_nfss_family:n #1 - { \tl_set:Nn \f@family {#1} } + \cs_new_protected_nopar:Npn \@@_nfss_family:nn #1#2 + { + \fontencoding {#1} + \tl_set:Nn \f@family {#2} + \selectfont + } } % \end{macrocode} % \end{macro} @@ -7358,17 +7374,22 @@ Copyright and Licence % \end{macrocode} % \end{macro} % +% \changes{v3.8.1}{2020/02/14}{应用 \tn{shapedefault}。} +% % \begin{macro}[int]{\xeCJK_declare_mathfont:nn} +% 注意从 \LaTeXe\ 2020/02/02 开始,\tn{shapedefault} 初始值是 \texttt{n}, +% 而 \tn{updefault} 初始值是 \texttt{up},两者并不一致。 +% \pkg{fontspec} 包定义字体使用的是 \tn{shapedefault}。 % \begin{macrocode} \cs_new_protected_nopar:Npn \xeCJK_declare_mathfont:nn #1#2 { \xeCJK_declare_symbol_font:nnnnn {#1} { \c_@@_encoding_tl } - {#2} { \mddefault } { \updefault } + {#2} { \mddefault } { \shapedefault } \cs_if_free:cF - { \c_@@_encoding_tl/#2/\bfdefault/\updefault } + { \c_@@_encoding_tl/#2/\bfdefault/\shapedefault } { \SetSymbolFont {#1} { bold } { \c_@@_encoding_tl } - {#2} { \bfdefault } { \updefault } + {#2} { \bfdefault } { \shapedefault } } \prop_gput:Nnx \g_@@_fam_prop {#2} { \exp_not:c { sym #1 } } } @@ -8285,11 +8306,10 @@ Copyright and Licence \g@addto@macro \@rmfamilyhook { \xeCJK@family { \CJKrmdefault } } \g@addto@macro \@sffamilyhook { \xeCJK@family { \CJKsfdefault } } \g@addto@macro \@ttfamilyhook { \xeCJK@family { \CJKttdefault } } - \exp_args:Nx \g@addto@macro + \exp_args:Nc \g@addto@macro { \cs_if_exist:NTF \@defaultfamilyhook - { \exp_not:N \@defaultfamilyhook } - { \exp_not:c { normalfont ~ } } + { @defaultfamilyhook } { normalfont ~ } } { \xeCJK@family { \CJKfamilydefault } } } diff --git a/macros/xetex/latex/xecjk/xeCJK.pdf b/macros/xetex/latex/xecjk/xeCJK.pdf index 336b30eb32..5b2afe4299 100644 Binary files a/macros/xetex/latex/xecjk/xeCJK.pdf and b/macros/xetex/latex/xecjk/xeCJK.pdf differ diff --git a/macros/xetex/latex/xecjk/xunicode-symbols.pdf b/macros/xetex/latex/xecjk/xunicode-symbols.pdf index e1bdc6f1d9..e4bb1ff146 100644 Binary files a/macros/xetex/latex/xecjk/xunicode-symbols.pdf and b/macros/xetex/latex/xecjk/xunicode-symbols.pdf differ -- cgit v1.2.3