diff options
| author | Karl Berry <karl@freefriends.org> | 2017-09-10 22:10:52 +0000 |
|---|---|---|
| committer | Karl Berry <karl@freefriends.org> | 2017-09-10 22:10:52 +0000 |
| commit | 23056da81dd216ac377e040b70c9b78e01c94186 (patch) | |
| tree | 2ef9d4754fb21d2e16390741fb5d8fcb2045a095 | |
| parent | 17ae18d7db87b958fb98d507710e615be1d4cc17 (diff) | |
bib2gls (10sep17)
git-svn-id: svn://tug.org/texlive/trunk@45266 c570f23f-e606-0410-a88d-b1316a301751
60 files changed, 8216 insertions, 3 deletions
diff --git a/Build/source/texk/texlive/linked_scripts/Makefile.am b/Build/source/texk/texlive/linked_scripts/Makefile.am index b240e051c17..32804d0c3a8 100644 --- a/Build/source/texk/texlive/linked_scripts/Makefile.am +++ b/Build/source/texk/texlive/linked_scripts/Makefile.am @@ -46,6 +46,7 @@ installdirs-local: ## ## WIN_WRAPPER is w32_wrapper for 32-bit or w64_wrapper for 64-bit. ## +## The "shell" list aren't just shell scripts, in either direction. ## Some /bin/sh scripts are listed as `other' or `context' ## scripts because they are correctly handled by the wrapper binaries. ## Conversely, some non-sh scripts are listed as `shell' because they @@ -90,6 +91,8 @@ texmf_other_scripts = \ accfonts/vpl2vpl \ arara/arara.sh \ authorindex/authorindex \ + bib2gls/bib2gls.sh \ + bib2gls/convertgls2bib.sh \ bundledoc/arlatex \ bundledoc/bundledoc \ cachepic/cachepic.tlu \ diff --git a/Build/source/texk/texlive/linked_scripts/Makefile.in b/Build/source/texk/texlive/linked_scripts/Makefile.in index 7b8a70f307a..5274a34bb18 100644 --- a/Build/source/texk/texlive/linked_scripts/Makefile.in +++ b/Build/source/texk/texlive/linked_scripts/Makefile.in @@ -305,6 +305,8 @@ texmf_other_scripts = \ accfonts/vpl2vpl \ arara/arara.sh \ authorindex/authorindex \ + bib2gls/bib2gls.sh \ + bib2gls/convertgls2bib.sh \ bundledoc/arlatex \ bundledoc/bundledoc \ cachepic/cachepic.tlu \ diff --git a/Build/source/texk/texlive/linked_scripts/bib2gls/bib2gls.sh b/Build/source/texk/texlive/linked_scripts/bib2gls/bib2gls.sh new file mode 100755 index 00000000000..5f9d7f71e60 --- /dev/null +++ b/Build/source/texk/texlive/linked_scripts/bib2gls/bib2gls.sh @@ -0,0 +1,12 @@ +#!/bin/sh + +kernel=`uname -s` +if test "${kernel#*CYGWIN}" != "$kernel" +then + jarpath=`cygpath -w $(kpsewhich --progname=bib2gls --format=texmfscripts bib2gls.jar)` +else + jarpath=`kpsewhich --progname=bib2gls --format=texmfscripts bib2gls.jar` +fi + +java -Djava.locale.providers=CLDR,JRE -jar "$jarpath" "$@" + diff --git a/Build/source/texk/texlive/linked_scripts/bib2gls/convertgls2bib.sh b/Build/source/texk/texlive/linked_scripts/bib2gls/convertgls2bib.sh new file mode 100755 index 00000000000..3e7370b0ca7 --- /dev/null +++ b/Build/source/texk/texlive/linked_scripts/bib2gls/convertgls2bib.sh @@ -0,0 +1,12 @@ +#!/bin/sh + +kernel=`uname -s` +if test "${kernel#*CYGWIN}" != "$kernel" +then + jarpath=`cygpath -w $(kpsewhich --progname=convertgls2bib --format=texmfscripts convertgls2bib.jar)` +else + jarpath=`kpsewhich --progname=convertgls2bib --format=texmfscripts convertgls2bib.jar` +fi + +java -jar "$jarpath" "$@" + diff --git a/Build/source/texk/texlive/linked_scripts/scripts.lst b/Build/source/texk/texlive/linked_scripts/scripts.lst index 3f7d35ce3c9..b10451b30e8 100644 --- a/Build/source/texk/texlive/linked_scripts/scripts.lst +++ b/Build/source/texk/texlive/linked_scripts/scripts.lst @@ -35,6 +35,8 @@ accfonts/vpl2ovp accfonts/vpl2vpl arara/arara.sh authorindex/authorindex +bib2gls/bib2gls.sh +bib2gls/convertgls2bib.sh bundledoc/arlatex bundledoc/bundledoc cachepic/cachepic.tlu diff --git a/Master/bin/amd64-freebsd/bib2gls b/Master/bin/amd64-freebsd/bib2gls new file mode 120000 index 00000000000..689d4421a47 --- /dev/null +++ b/Master/bin/amd64-freebsd/bib2gls @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/bib2gls.sh
\ No newline at end of file diff --git a/Master/bin/amd64-freebsd/convertgls2bib b/Master/bin/amd64-freebsd/convertgls2bib new file mode 120000 index 00000000000..e099e33b8e7 --- /dev/null +++ b/Master/bin/amd64-freebsd/convertgls2bib @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/convertgls2bib.sh
\ No newline at end of file diff --git a/Master/bin/amd64-netbsd/bib2gls b/Master/bin/amd64-netbsd/bib2gls new file mode 120000 index 00000000000..689d4421a47 --- /dev/null +++ b/Master/bin/amd64-netbsd/bib2gls @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/bib2gls.sh
\ No newline at end of file diff --git a/Master/bin/amd64-netbsd/convertgls2bib b/Master/bin/amd64-netbsd/convertgls2bib new file mode 120000 index 00000000000..e099e33b8e7 --- /dev/null +++ b/Master/bin/amd64-netbsd/convertgls2bib @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/convertgls2bib.sh
\ No newline at end of file diff --git a/Master/bin/armel-linux/bib2gls b/Master/bin/armel-linux/bib2gls new file mode 120000 index 00000000000..689d4421a47 --- /dev/null +++ b/Master/bin/armel-linux/bib2gls @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/bib2gls.sh
\ No newline at end of file diff --git a/Master/bin/armel-linux/convertgls2bib b/Master/bin/armel-linux/convertgls2bib new file mode 120000 index 00000000000..e099e33b8e7 --- /dev/null +++ b/Master/bin/armel-linux/convertgls2bib @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/convertgls2bib.sh
\ No newline at end of file diff --git a/Master/bin/armhf-linux/bib2gls b/Master/bin/armhf-linux/bib2gls new file mode 120000 index 00000000000..689d4421a47 --- /dev/null +++ b/Master/bin/armhf-linux/bib2gls @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/bib2gls.sh
\ No newline at end of file diff --git a/Master/bin/armhf-linux/convertgls2bib b/Master/bin/armhf-linux/convertgls2bib new file mode 120000 index 00000000000..e099e33b8e7 --- /dev/null +++ b/Master/bin/armhf-linux/convertgls2bib @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/convertgls2bib.sh
\ No newline at end of file diff --git a/Master/bin/i386-cygwin/bib2gls b/Master/bin/i386-cygwin/bib2gls new file mode 120000 index 00000000000..689d4421a47 --- /dev/null +++ b/Master/bin/i386-cygwin/bib2gls @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/bib2gls.sh
\ No newline at end of file diff --git a/Master/bin/i386-cygwin/convertgls2bib b/Master/bin/i386-cygwin/convertgls2bib new file mode 120000 index 00000000000..e099e33b8e7 --- /dev/null +++ b/Master/bin/i386-cygwin/convertgls2bib @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/convertgls2bib.sh
\ No newline at end of file diff --git a/Master/bin/i386-darwin/bib2gls b/Master/bin/i386-darwin/bib2gls new file mode 120000 index 00000000000..689d4421a47 --- /dev/null +++ b/Master/bin/i386-darwin/bib2gls @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/bib2gls.sh
\ No newline at end of file diff --git a/Master/bin/i386-darwin/convertgls2bib b/Master/bin/i386-darwin/convertgls2bib new file mode 120000 index 00000000000..e099e33b8e7 --- /dev/null +++ b/Master/bin/i386-darwin/convertgls2bib @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/convertgls2bib.sh
\ No newline at end of file diff --git a/Master/bin/i386-freebsd/bib2gls b/Master/bin/i386-freebsd/bib2gls new file mode 120000 index 00000000000..689d4421a47 --- /dev/null +++ b/Master/bin/i386-freebsd/bib2gls @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/bib2gls.sh
\ No newline at end of file diff --git a/Master/bin/i386-freebsd/convertgls2bib b/Master/bin/i386-freebsd/convertgls2bib new file mode 120000 index 00000000000..e099e33b8e7 --- /dev/null +++ b/Master/bin/i386-freebsd/convertgls2bib @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/convertgls2bib.sh
\ No newline at end of file diff --git a/Master/bin/i386-linux/bib2gls b/Master/bin/i386-linux/bib2gls new file mode 120000 index 00000000000..689d4421a47 --- /dev/null +++ b/Master/bin/i386-linux/bib2gls @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/bib2gls.sh
\ No newline at end of file diff --git a/Master/bin/i386-linux/convertgls2bib b/Master/bin/i386-linux/convertgls2bib new file mode 120000 index 00000000000..e099e33b8e7 --- /dev/null +++ b/Master/bin/i386-linux/convertgls2bib @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/convertgls2bib.sh
\ No newline at end of file diff --git a/Master/bin/i386-netbsd/bib2gls b/Master/bin/i386-netbsd/bib2gls new file mode 120000 index 00000000000..689d4421a47 --- /dev/null +++ b/Master/bin/i386-netbsd/bib2gls @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/bib2gls.sh
\ No newline at end of file diff --git a/Master/bin/i386-netbsd/convertgls2bib b/Master/bin/i386-netbsd/convertgls2bib new file mode 120000 index 00000000000..e099e33b8e7 --- /dev/null +++ b/Master/bin/i386-netbsd/convertgls2bib @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/convertgls2bib.sh
\ No newline at end of file diff --git a/Master/bin/i386-solaris/bib2gls b/Master/bin/i386-solaris/bib2gls new file mode 120000 index 00000000000..689d4421a47 --- /dev/null +++ b/Master/bin/i386-solaris/bib2gls @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/bib2gls.sh
\ No newline at end of file diff --git a/Master/bin/i386-solaris/convertgls2bib b/Master/bin/i386-solaris/convertgls2bib new file mode 120000 index 00000000000..e099e33b8e7 --- /dev/null +++ b/Master/bin/i386-solaris/convertgls2bib @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/convertgls2bib.sh
\ No newline at end of file diff --git a/Master/bin/powerpc-darwin/bib2gls b/Master/bin/powerpc-darwin/bib2gls new file mode 120000 index 00000000000..689d4421a47 --- /dev/null +++ b/Master/bin/powerpc-darwin/bib2gls @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/bib2gls.sh
\ No newline at end of file diff --git a/Master/bin/powerpc-darwin/convertgls2bib b/Master/bin/powerpc-darwin/convertgls2bib new file mode 120000 index 00000000000..e099e33b8e7 --- /dev/null +++ b/Master/bin/powerpc-darwin/convertgls2bib @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/convertgls2bib.sh
\ No newline at end of file diff --git a/Master/bin/powerpc-linux/bib2gls b/Master/bin/powerpc-linux/bib2gls new file mode 120000 index 00000000000..689d4421a47 --- /dev/null +++ b/Master/bin/powerpc-linux/bib2gls @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/bib2gls.sh
\ No newline at end of file diff --git a/Master/bin/powerpc-linux/convertgls2bib b/Master/bin/powerpc-linux/convertgls2bib new file mode 120000 index 00000000000..e099e33b8e7 --- /dev/null +++ b/Master/bin/powerpc-linux/convertgls2bib @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/convertgls2bib.sh
\ No newline at end of file diff --git a/Master/bin/sparc-solaris/bib2gls b/Master/bin/sparc-solaris/bib2gls new file mode 120000 index 00000000000..689d4421a47 --- /dev/null +++ b/Master/bin/sparc-solaris/bib2gls @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/bib2gls.sh
\ No newline at end of file diff --git a/Master/bin/sparc-solaris/convertgls2bib b/Master/bin/sparc-solaris/convertgls2bib new file mode 120000 index 00000000000..e099e33b8e7 --- /dev/null +++ b/Master/bin/sparc-solaris/convertgls2bib @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/convertgls2bib.sh
\ No newline at end of file diff --git a/Master/bin/win32/bib2gls.exe b/Master/bin/win32/bib2gls.exe Binary files differnew file mode 100755 index 00000000000..5777d90a17a --- /dev/null +++ b/Master/bin/win32/bib2gls.exe diff --git a/Master/bin/win32/convertgls2bib.exe b/Master/bin/win32/convertgls2bib.exe Binary files differnew file mode 100755 index 00000000000..5777d90a17a --- /dev/null +++ b/Master/bin/win32/convertgls2bib.exe diff --git a/Master/bin/x86_64-cygwin/bib2gls b/Master/bin/x86_64-cygwin/bib2gls new file mode 120000 index 00000000000..689d4421a47 --- /dev/null +++ b/Master/bin/x86_64-cygwin/bib2gls @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/bib2gls.sh
\ No newline at end of file diff --git a/Master/bin/x86_64-cygwin/convertgls2bib b/Master/bin/x86_64-cygwin/convertgls2bib new file mode 120000 index 00000000000..e099e33b8e7 --- /dev/null +++ b/Master/bin/x86_64-cygwin/convertgls2bib @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/convertgls2bib.sh
\ No newline at end of file diff --git a/Master/bin/x86_64-darwin/bib2gls b/Master/bin/x86_64-darwin/bib2gls new file mode 120000 index 00000000000..689d4421a47 --- /dev/null +++ b/Master/bin/x86_64-darwin/bib2gls @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/bib2gls.sh
\ No newline at end of file diff --git a/Master/bin/x86_64-darwin/convertgls2bib b/Master/bin/x86_64-darwin/convertgls2bib new file mode 120000 index 00000000000..e099e33b8e7 --- /dev/null +++ b/Master/bin/x86_64-darwin/convertgls2bib @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/convertgls2bib.sh
\ No newline at end of file diff --git a/Master/bin/x86_64-darwinlegacy/bib2gls b/Master/bin/x86_64-darwinlegacy/bib2gls new file mode 120000 index 00000000000..689d4421a47 --- /dev/null +++ b/Master/bin/x86_64-darwinlegacy/bib2gls @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/bib2gls.sh
\ No newline at end of file diff --git a/Master/bin/x86_64-darwinlegacy/convertgls2bib b/Master/bin/x86_64-darwinlegacy/convertgls2bib new file mode 120000 index 00000000000..e099e33b8e7 --- /dev/null +++ b/Master/bin/x86_64-darwinlegacy/convertgls2bib @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/convertgls2bib.sh
\ No newline at end of file diff --git a/Master/bin/x86_64-linux/bib2gls b/Master/bin/x86_64-linux/bib2gls new file mode 120000 index 00000000000..689d4421a47 --- /dev/null +++ b/Master/bin/x86_64-linux/bib2gls @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/bib2gls.sh
\ No newline at end of file diff --git a/Master/bin/x86_64-linux/convertgls2bib b/Master/bin/x86_64-linux/convertgls2bib new file mode 120000 index 00000000000..e099e33b8e7 --- /dev/null +++ b/Master/bin/x86_64-linux/convertgls2bib @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/convertgls2bib.sh
\ No newline at end of file diff --git a/Master/bin/x86_64-solaris/bib2gls b/Master/bin/x86_64-solaris/bib2gls new file mode 120000 index 00000000000..689d4421a47 --- /dev/null +++ b/Master/bin/x86_64-solaris/bib2gls @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/bib2gls.sh
\ No newline at end of file diff --git a/Master/bin/x86_64-solaris/convertgls2bib b/Master/bin/x86_64-solaris/convertgls2bib new file mode 120000 index 00000000000..e099e33b8e7 --- /dev/null +++ b/Master/bin/x86_64-solaris/convertgls2bib @@ -0,0 +1 @@ +../../texmf-dist/scripts/bib2gls/convertgls2bib.sh
\ No newline at end of file diff --git a/Master/texmf-dist/doc/support/bib2gls/CHANGES b/Master/texmf-dist/doc/support/bib2gls/CHANGES new file mode 100644 index 00000000000..9b72a4b6c44 --- /dev/null +++ b/Master/texmf-dist/doc/support/bib2gls/CHANGES @@ -0,0 +1,3 @@ +v1.0 (2017-09-09): + + * initial release diff --git a/Master/texmf-dist/doc/support/bib2gls/README.md b/Master/texmf-dist/doc/support/bib2gls/README.md new file mode 100644 index 00000000000..29c9a4a3477 --- /dev/null +++ b/Master/texmf-dist/doc/support/bib2gls/README.md @@ -0,0 +1,212 @@ +# bib2gls + +Command line application to convert `.bib` files to +`glossaries-extra.sty` resource files. + +This application may be used to extract glossary information +stored in a `.bib` file and convert it into glossary entry +definition commands. This application should be used +with `glossaries-extra`'s `record` package option. It performs +two functions: + + - selects entries according to records found in the `.aux` file + (similar to `bibtex`) + + - hierarchically sorts entries and collates location lists + (similar to `makeindex` or `xindy`) + +This means that the glossary entries can now be managed +in a system such as JabRef, and only the entries that are +actually required will be defined, reducing the resources +required by TeX. + +The supplementary application `convertgls2bib` can be used +to convert existing `.tex` files containing definitions +(`\newglossaryentry` etc) to the `.bib` format +required by `bib2gls`. + +For example, if `entries.tex` contains: +```latex +\newglossaryentry{bird}{name={bird},description={feathered animal}} + +\newabbreviation{html}{HTML}{Hypertext Markup Language} + +\newterm[plural=geese]{goose} + +\newdualentry{svm}{SVM}{support vector machine} + {Statistical pattern recognition technique} +``` +Then do: +```bash +convertgls2tex entries.tex entries.bib +``` +to create `entries.bib`. + +# Example + +File `entries.bib`: + +```bibtex +@entry{bird, + name={bird}, + description = {feathered animal} +} + +@abbreviation{html, + short="HTML", + long={hypertext markup language} +} + +@dualentryabbreviation{svm, + long = {support vector machine}, + short = {SVM}, + description = {statistical pattern recognition technique} +} + +@symbol{v, + name={$\vec{v}$}, + text={\vec{v}}, + description={a vector} +} + +@index{goose,plural="geese"} +``` + +File `myDoc.tex`: + +```latex +\documentclass{article} + +\usepackage[record,abbreviations]{glossaries-extra} + +\GlsXtrLoadResources[ + src={entries},% data in entries.bib + sort={en-GB}% sort according to 'en-GB' locale +] + +\begin{document} +\Gls{bird} and \gls{goose}. + +First: \gls{svm}. Next: \gls{svm}. + +\printunsrtglossaries +\end{document} +``` + +Document build: +```bash +pdflatex myDoc +bib2gls myDoc +pdflatex myDoc +``` +(Replace `pdflatex` with `latex`, `xelatex` or `lualatex` as +appropriate.) + +# Installation + +The files should be installed as follows where *TEXMF* indicates +your local or home TEXMF path (for example, `~/texmf/`): + + - *TEXMF*`/scripts/bib2gls/bib2gls.jar` (Java application.) + - *TEXMF*`/scripts/bib2gls/convertgls2bib.jar` (Java application.) + - *TEXMF*`/scripts/bib2gls/texparserlib.jar` (Java library.) + - *TEXMF*`/scripts/bib2gls/resources/bib2gls-en.xml` (English + resource file.) + - *TEXMF*`/scripts/bib2gls/bib2gls.sh` (Unix-like systems only.) + - *TEXMF*`/scripts/bib2gls/convertgls2bib.sh` (Unix-like systems + only.) + - *TEXMF*`/doc/support/bib2gls/bib2gls.pdf` (User manual.) + +Note that `texparserlib.jar` isn't an application. It's +a library used by `bib2gls.jar` and `convertgls2bib.jar` +and so needs to be on the same class path as them. + +The bash `.sh` scripts are provided for Unix-like users. +They're not required for Windows. + +To test installation: +```bash +bib2gls --version +convertgls2bib --version +``` +These should display the version details. + +#Licence + +License GPLv3+: GNU GPL version 3 or later +http://gnu.org/licenses/gpl.html +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +#Source Code + +#User Manual + +The documentation `bib2gls.pdf` is compiled using: + +```bash +pdflatex bib2gls +makeindex -s bib2gls.ist bib2gls +pdflatex bib2gls +``` + +#JAR Files + +Create the following directories: + +`lib` +`lib/resources` +`java` +`classes/com/dickimawbooks/bib2gls` +`classes/com/dickimawbooks/gls2bib` +`classes/com/dickimawbooks/texparserlib` + +Unpack the zip files: + +```bash +unzip -d java bib2gls-src.zip +unzip -d java gls2bib-src.zip +unzip -d java texparserlib-src.zip +``` + +Copy the `.xml` language file to `lib/resources/` + +Compile `texparserlib.jar`: + +```bash +cd java/lib +javac -d ../../classes +-Xlint:unchecked -Xlint:deprecation *.java */*.java */*/*.java +cd ../../classes +jar cf ../lib/texparserlib.jar +com/dickimawbooks/texparserlib/*.class \ +com/dickimawbooks/texparserlib/*/*.class \ +com/dickimawbooks/texparserlib/*/*/*.class +``` + +Compile `bib2gls.jar`: + +```bash +cd java/bib2gls +javac -d ../../classes -cp ../../lib/texparserlib.jar *.java +cd ../classes +jar cmf ../java/bib2gls/Manifest.txt ../lib/bib2gls.jar +com/dickimawbooks/bib2gls/*.class +``` + +Compile `convertgls2bib.jar`: + +```bash +cd java/gls2bib +javac -d ../../classes -cp ../../lib/texparserlib.jar *.java +cd ../classes +jar cmf ../java/gls2bib/Manifest.txt ../lib/convertgls2bib.jar +com/dickimawbooks/gls2bib/*.class +``` + +GitHub: + + - https://github.com/nlct/bib2gls + - https://github.com/nlct/texparserlib + +Home Page: http://www.dickimaw-books.com/software/bib2gls diff --git a/Master/texmf-dist/doc/support/bib2gls/bib2gls.pdf b/Master/texmf-dist/doc/support/bib2gls/bib2gls.pdf Binary files differnew file mode 100644 index 00000000000..c0f20a256f4 --- /dev/null +++ b/Master/texmf-dist/doc/support/bib2gls/bib2gls.pdf diff --git a/Master/texmf-dist/scripts/bib2gls/bib2gls.jar b/Master/texmf-dist/scripts/bib2gls/bib2gls.jar Binary files differnew file mode 100755 index 00000000000..5e4610756f9 --- /dev/null +++ b/Master/texmf-dist/scripts/bib2gls/bib2gls.jar diff --git a/Master/texmf-dist/scripts/bib2gls/bib2gls.sh b/Master/texmf-dist/scripts/bib2gls/bib2gls.sh new file mode 100755 index 00000000000..5f9d7f71e60 --- /dev/null +++ b/Master/texmf-dist/scripts/bib2gls/bib2gls.sh @@ -0,0 +1,12 @@ +#!/bin/sh + +kernel=`uname -s` +if test "${kernel#*CYGWIN}" != "$kernel" +then + jarpath=`cygpath -w $(kpsewhich --progname=bib2gls --format=texmfscripts bib2gls.jar)` +else + jarpath=`kpsewhich --progname=bib2gls --format=texmfscripts bib2gls.jar` +fi + +java -Djava.locale.providers=CLDR,JRE -jar "$jarpath" "$@" + diff --git a/Master/texmf-dist/scripts/bib2gls/convertgls2bib.jar b/Master/texmf-dist/scripts/bib2gls/convertgls2bib.jar Binary files differnew file mode 100755 index 00000000000..1ccf50f5771 --- /dev/null +++ b/Master/texmf-dist/scripts/bib2gls/convertgls2bib.jar diff --git a/Master/texmf-dist/scripts/bib2gls/convertgls2bib.sh b/Master/texmf-dist/scripts/bib2gls/convertgls2bib.sh new file mode 100755 index 00000000000..3e7370b0ca7 --- /dev/null +++ b/Master/texmf-dist/scripts/bib2gls/convertgls2bib.sh @@ -0,0 +1,12 @@ +#!/bin/sh + +kernel=`uname -s` +if test "${kernel#*CYGWIN}" != "$kernel" +then + jarpath=`cygpath -w $(kpsewhich --progname=convertgls2bib --format=texmfscripts convertgls2bib.jar)` +else + jarpath=`kpsewhich --progname=convertgls2bib --format=texmfscripts convertgls2bib.jar` +fi + +java -jar "$jarpath" "$@" + diff --git a/Master/texmf-dist/scripts/bib2gls/resources/bib2gls-en.xml b/Master/texmf-dist/scripts/bib2gls/resources/bib2gls-en.xml new file mode 100644 index 00000000000..c48375fee45 --- /dev/null +++ b/Master/texmf-dist/scripts/bib2gls/resources/bib2gls-en.xml @@ -0,0 +1,373 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> +<properties> +<comment>English language file for bib2gls</comment> + +<entry key="about.version">{0} version {1} ({2})</entry> +<entry key="about.license">License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law.</entry> + +<entry key="syntax.usage">Usage: {0} [<option>]+ <aux file></entry> +<entry key="syntax.info">Helper application for the glossaries-extra package. +See the manual for further details.</entry> +<entry key="syntax.use.help">(Use --help or -h for help.)</entry> +<entry key="syntax.options">Options:</entry> +<entry key="syntax.version">{0} (or {1}) Display version and exit.</entry> +<entry key="syntax.help">{0} (or {1}) Display this help message and exit.</entry> +<entry key="syntax.debug">{0} [<n>] Switch on debug mode (optionally with the + given level).</entry> +<entry key="syntax.nodebug">{0} Switch off debug mode. (Default.)</entry> +<entry key="syntax.nodebug">{0} Switch off debug mode. (Default.) + Synonym: {1}</entry> +<entry key="syntax.verbose">{0} Switch on verbose mode.</entry> +<entry key="syntax.noverbose">{0} Switch off verbose mode. (Default.) + Some messages are displayed. + Synonym: {1}</entry> +<entry key="syntax.silent">{0} Only display error messages.</entry> +<entry key="syntax.locale">{0} <lang> (or {1} <lang>) + Use language resource file for <lang>.</entry> +<entry key="syntax.log">{0} <file> (or {1} <file>) + Set transcript file name.</entry> +<entry key="syntax.dir">{0} <directory> (or {1} <directory>) + Files relative to <directory>. + (This doesn''t change the current working + directory.)</entry> +<entry key="syntax.interpret">{0} Switch on interpret mode (default).</entry> +<entry key="syntax.no.interpret">{0} Switch off interpret mode.</entry> + +<entry key="syntax.mfirstuc">{0} <fields>|all (or {1} <fields>|all) + Insert an empty group if fields start + with certain problematic commands + to protect against case-changing commands + like \Gls. + + The default is to do this for all fields. + To do this for only a subset of fields, + set <fields> to a comma-separated + list of fields (e.g. 'name,short,long'). + The keyword 'all' indicates all fields.</entry> +<entry key="syntax.no.mfirstuc">{0} + Switch off the auto-insertion of an empty + group for all fields.</entry> + +<entry key="syntax.no.math.mfirstuc">{0} + Switch off the auto-insertion of an empty + group for math-shift ($).</entry> + +<entry key="syntax.math.mfirstuc">{0} + Switch on the auto-insertion of an empty + group for math-shift ($). + This option will be overriden by + {1}</entry> + + +<entry key="syntax.check.shortcuts">{0} <option> + Check for the shortcut commands when + search for dependencies. + Permitted values of <option>: + ''acronyms'' (or ''acro'') + ''abbreviations'' (or ''abbr'') + ''all'' (or ''true'') + ''none'' (or ''false'')</entry> +<entry key="syntax.check.nested">{0} <list>|"none" + Check each field listed in <list> + for potentially problematic nested link + text. (Default list: name, text, plural, + first, firstplural, short, shortplural, + long, longplural, symbol). + + If "none", disable check.</entry> +<entry key="syntax.nocheck.nested">{0} + Don''t check for potentially problematic + nested link text. (Equivalent to + {1} "none")</entry> +<entry key="syntax.format.map">{0} <key>=<value>[,<key>=<value>]* (or {1} <key>=<value>[,<key>=<value>]*) + Set location format mappings.</entry> +<entry key="syntax.group">{0} or {1} + Add ''group'' field to entries.</entry> +<entry key="syntax.no.group">{0} + Don''t add ''group'' field to entries.</entry> +<entry key="syntax.trim.fields">{0} + Trim leading and trailing spaces from fields.</entry> +<entry key="syntax.no.trim.fields">{0} + Don''t trim leading and trailing spaces from fields (default).</entry> +<entry key="syntax.tex.encoding">{0} <name> + Set the character encoding for the output files.</entry> + +<entry key="message.reading">Reading {0}</entry> +<entry key="message.writing">Writing {0}</entry> +<entry key="message.no.read">No read access for {0}</entry> +<entry key="message.no.write">No write access for {0}</entry> +<entry key="message.running">Running {0}</entry> +<entry key="message.processing">Processing {0}</entry> +<entry key="message.copying">Copying {0} -> {1}</entry> +<entry key="message.moving">Moving {0} -> {1}</entry> +<entry key="message.added.dep">Added dependent: {0}</entry> +<entry key="message.added.parent">Adding parent: {0}</entry> +<entry key="message.selection.mode">Selection mode: {0}</entry> +<entry key="message.ignore.fields">Ignoring fields:</entry> +<entry key="message.sort.mode">Sort mode: {0}</entry> +<entry key="message.sort.field">Sort field: {0}</entry> +<entry key="message.label.prefix">Label prefix: {0}</entry> +<entry key="message.dual.label.prefix">Dual label prefix: {0}</entry> +<entry key="message.dual.sort.mode">Dual sort mode: {0}</entry> +<entry key="message.dual.sort.field">Dual sort field: {0}</entry> +<entry key="message.dual.entry.mappings">Dual entry mappings:</entry> +<entry key="message.dual.symbol.mappings">Dual symbol mappings:</entry> +<entry key="message.dual.abbreviation.mappings">Dual abbreviation mappings:</entry> +<entry key="message.dual.entryabbreviation.mappings">Dual entry-abbreviation mappings:</entry> +<entry key="message.process.result">Processed returned: {0}</entry> + +<entry key="message.log.file">Transcript written to {0}.</entry> +<entry key="message.written">{0} written to {1}.</entry> +<entry key="message.written.total">{0} written in total.</entry> + +<entry key="message.0.entry">No entries</entry> +<entry key="message.1.entry">1 entry</entry> +<entry key="message.2.entry">{0,number} entries</entry> + +<entry key="message.1.sty">1 recognised package:</entry> +<entry key="message.2.sty">{0,number} recognised packages:</entry> + +<entry key="message.checking.read">Checking read access for {0}</entry> +<entry key="message.checking.write">Checking write access for {0}</entry> +<entry key="message.setting.sort">Initialising collation keys (strength={0}, decomposition={1})</entry> +<entry key="message.no.fallback">Entry type ''{0}'' has no fallback for field: {1}</entry> +<entry key="message.inconsistent.range">Inconsistent location format {0} +with range started by {1}</entry> +<entry key="message.merge.range">Merging location {0} +into explicit range {1}</entry> +<entry key="message.uc.protecting">Inserting empty group in front of {0} to protect it from mfirstuc.</entry> +<entry key="message.discarding.entry">Discarding entry {0}</entry> +<entry key="message.pattern.info">Pattern: {0}. Field: {1}. Value: {2}. Matches: {3}.</entry> +<entry key="message.calc.text.width">Calculating width of name field for entry ''{0}''</entry> +<entry key="message.calc.text.width.result">Calculated width of ''{0}'': {1,number}</entry> +<entry key="message.parsing.code">Parsing code block:</entry> +<entry key="message.unknown.tex.charset">Unable to detect character encoding for TeX file. +Defaulting to: {0}. +(Use {1} if this is incorrect.)</entry> +<entry key="message.tex.charset">TeX character encoding: {0}</entry> +<entry key="message.adding.target.record">Adding record {0} from aliased entry {1}.</entry> +<entry key="message.ignored.record">Ignoring record {0}.</entry> +<entry key="message.normalizing">Normalising {0} to {1}.</entry> +<entry key="message.norm.distinct">Normalized {0} distinct from {1}.</entry> +<entry key="message.no.norm">Can''t normalize {0}.</entry> +<entry key="message.collator.rules">Collator rules: {0}.</entry> +<entry key="message.no.collation.element">No collation element for: {0}.</entry> +<entry key="message.break.points">Break points: {0}.</entry> + +<entry key="tag.page">Page</entry> +<entry key="tag.pages">Pages</entry> +<entry key="tag.passim">passim</entry> + +<!-- + Letter groups usually only have the first character converted to upper case + (for example, the digraph 'dz' is converted to 'Dz'). This doesn't apply + to the Dutch digraph 'ij', which should be converted to 'IJ'. Other + exceptions may be added as appropriate. + --> +<entry key="grouptitle.case.ij">IJ</entry> + +<entry key="warning.title">Warning: {0}</entry> +<entry key="warning.substituting">Substituting {0} with {1}</entry> +<entry key="warning.removing">Removing {0}</entry> +<entry key="warning.ignoring.unknown.entry.type">Ignoring unknown entry type: {0}</entry> +<entry key="warning.ignoring.unknown.encoding">Ignoring unknown encoding: {0}</entry> +<entry key="warning.can.find.arg">Can't detect argument for: \{0}</entry> +<entry key="warning.no.default.sort">Can't determine sort value for: {0} +(Using sort field ''{1}''.)</entry> +<entry key="warning.missing.field">Entry ''{0}'' missing required field: {1}</entry> +<entry key="warning.potential.nested.link">Entry ''{0}'' has potentially nested link text in field: {1} +Consider using \glsps'{'{3}'}' or \glspt'{'{3}'}' instead of {2}'{'{3}'}'</entry> +<entry key="warning.dir.no.write">Directory not writable: {0} +Using TEXMFOUTPUT instead: {1}</entry> +<entry key="warning.conflicting.range.format">Entry location conflict for formats: {0} and {1} +Replacing {1} with {2}</entry> +<entry key="warning.discarding.conflicting.record">Entry location conflict for formats: {0} and {1} +Discarding: {2} +Conflicts with: {3}</entry> +<entry key="warning.discarding.conflicting.record.using.map">Entry location conflict. +Obeying requested mapping {0} -> {1} +Discarding: {2} +Keeping: {3}</entry> +<entry key="warning.discarding.conflicting.record.using.map2">Entry location conflict. +Obeying requested mapping {0} -> {1} and {2} -> {3} +Discarding: {4} +Discarding: {5} +Replacement: {6}</entry> +<entry key="warning.cant.find.parent">Parent ''{0}'' not found for entry {1}</entry> +<entry key="warning.cant.find.parent.name">Can''t determine parent name for entry {0}</entry> +<entry key="warning.field.clash">Field clash: {0} and {1} +Ignoring {1}</entry> +<entry key="warning.field.unsupported">Unsupported field: {0} +(Update glossaries-extra.sty to at least version {1})</entry> +<entry key="warning.option.clash">Option clash: {0} and {1} +Ignoring {1}</entry> +<entry key="warning.option.pair.required">Resource option {0} requires option {1}</entry> +<entry key="warning.group.option.required">Resource option {0} requires application switch {1}</entry> +<entry key="warning.parent.missing">Parent {0} does not occur before entry {1} so removing relationship.</entry> +<entry key="warning.unknown.field.pattern">Ignoring pattern for unknown field: {0}</entry> +<entry key="warning.notbasiclatin.id">Problematic entry label: {0} +You document doesn''t seem to have used fontspec which +suggests it''s not using XeLaTeX or LuaLaTeX, so you need +to restrict your labels to the Basic Latin set (or +switch TeX engines).</entry> +<entry key="warning.spchars.id">Problematic entry label: {0} +Contains one or more special characters.</entry> +<entry key="warning.alias.not.found">Can''t find target {0} for aliased entry {1}. +Aliased entries must be in the same resource set as their target entries with option {2}={3}.</entry> +<entry key="warning.deprecated">''{0}'' deprecated. Use ''{1}'' instead.</entry> + +<entry key="error.title">Error: {0}</entry> +<entry key="error.alias.map.forbidden">The 'alias' field can't be mapped.</entry> +<entry key="error.no.sty.version">Unable to read version date for package {0}</entry> +<entry key="error.sty.too.old">Package {0} version {1} is too old. +Minimum version {2} required.</entry> +<entry key="error.unknown.tex.charset">Unknown TeX charset: {0} +Defaulting to {1}. Use {2} to set another encoding.</entry> +<entry key="error.missing.aux.cs.require_cs">Missing \{0} in aux file. (Have you used \{1}?)</entry> +<entry key="error.missing.aux.cs.require_cs_or">Missing \{0} in aux file. (Have you used \{1} or \{2}?)</entry> +<entry key="error.missing.records">No records found in aux file. +Have you used the glossaries-extra.sty ''record'' option? +Have you indexed your entries using commands like \gls?</entry> +<entry key="error.missing.aux.new.cs">Missing \{0} in aux file (make sure glossaries-extra.sty is at least {1}).</entry> +<entry key="error.only.one.aux">Only one aux file permitted.</entry> +<entry key="error.no.aux">Missing aux file. Use --help for help.</entry> +<entry key="error.file.not.found">File not found: {0}</entry> +<entry key="error.missing.src">File not found: {0} +(Did you forget to use the ''src'' key?)</entry> +<entry key="error.dir.not.found">Directory not found: {0}</entry> +<entry key="error.not.dir">Not a directory: {0}</entry> +<entry key="error.cant.open.log">Can't open log file: {0}</entry> +<entry key="error.invalid.opt.value">Invalid ''{0}'' value: {1}</entry> +<entry key="error.invalid.opt.int.value">Invalid ''{0}'' value: {1} (number required)</entry> +<entry key="error.invalid.opt.minint.value">Invalid ''{0}'' value: {1} (can''t be less than {2,number})</entry> +<entry key="error.invalid.choice.value">Invalid ''{0}'' value: {1} (allowed values: {2})</entry> +<entry key="error.invalid.opt.list.size">Invalid value for: {0} +Value must be a list of size {2,number}</entry> +<entry key="error.invalid.opt.keylist.value">Invalid ''{0}'' value ''{1}'' (within option ''{2}'')</entry> +<entry key="error.invalid.opt.keylist.key">Invalid key ''{0}'' within option ''{1}''</entry> +<entry key="error.invalid.opt.keylist.pattern">Invalid pattern ''{1}'' in {0}='{'{1}'}' (within option ''{2}'')</entry> +<entry key="error.missing.value">Missing value for: {0}</entry> +<entry key="error.option.clash">Option clash: {0} and {1}</entry> +<entry key="error.invalid.dual.map">Invalid mapping: {0}={1} +The size of the first list ({2,number}) is not the same as the size of +the second list ({3,number}).</entry> +<entry key="error.invalid.field">Invalid field ''{0}'' provided by option ''{1}''</entry> +<entry key="error.openin.forbidden">Read access forbidden for file: {0}</entry> +<entry key="error.openout.forbidden">Write access forbidden for file: {0}</entry> +<entry key="error.forbidden.ext">Write access forbidden for extension: {0}</entry> +<entry key="error.cant.open.process.stream">Unable to open input stream from process: {0}</entry> +<entry key="error.cyclic.hierarchy">Cyclical hierarchy for entry: {0}</entry> +<entry key="error.duplicate.resource">Duplicate resource: {0}</entry> +<entry key="error.nested.range">Nested location range: {0} +Outer range started with: {1}</entry> +<entry key="error.range.missing.start">Unmatched end location range {0}</entry> +<entry key="error.inconsistent.range">Inconsistent location format {0} +with range started by {1}</entry> +<entry key="error.range.missing.end">Unmatched start location range {0}</entry> +<entry key="error.bib.contents.parse">Syntax error parsing @{0}: +{1} +</entry> +<entry key="error.bib.contents.parse.before">Syntax error parsing @{0}: +{1} +Error occurred before: {2} +</entry> +<entry key="error.bib.contents.parse.data">Syntax error parsing @{0} ({1}): +{2} +</entry> +<entry key="error.bib.contents.parse.data.before">Syntax error parsing @{0} ({1}): +{2} +Error occurred before: {3} +</entry> +<entry key="error.invalid.sort.rule">Invalid syntax in sort rule: +{0}</entry> + +<!-- + The following messages are used by convertgls2bib +--> + +<entry key="gls2bib.override.newdualentry">Overriding default definition of \\newdualentry with custom +definition. (Change \\newcommand to \\providecommand if you want +\\newdualentry[options]'{'label'}{'short'}{'long'}{'description'}' +converted to @dualentryabbreviation.)</entry> + +<!-- + The following messages are used by various parts of + texparserlib.jar only a few of them may actually be generated by + bib2gls which is just using that library to parse the aux and bib files. + --> + +<entry key="error.line">Line {0}: {1}.</entry> +<entry key="error.line_with_code">Line {0}: {1} (error code {2}).</entry> +<entry key="error.unknown">Unknown error</entry> +<entry key="error.exec_failed">Failed to execute: {0}</entry> +<entry key="error.app_failed">{0} failed with exit code {1}</entry> +<entry key="error.interrupted">Process interrupted</entry> +<entry key="error.syntax">Syntax error: {0}</entry> +<entry key="error.syntax.unknown_option">Unknown option: {0}</entry> +<entry key="error.syntax.only_one">Only one {0} permitted</entry> +<entry key="error.syntax.only_one_input">Only one input file permitted</entry> +<entry key="error.syntax.missing_filename">Filename expected after {0}</entry> +<entry key="error.syntax.missing_input">File name expected after {0}</entry> +<entry key="error.syntax.batch.missing_in">Input file required for batch mode</entry> +<entry key="error.syntax.batch.missing_out">Output directory required for batch mode</entry> +<entry key="error.syntax.batch.unknown_format">Unknown format ''{0}''</entry> +<entry key="error.exists">{0} already exists</entry> + +<entry key="tex.error.bad_param">Parameter digit 1 to 9 expected. Found ''{0}''</entry> +<entry key="tex.error.no_eg">Missing end group</entry> +<entry key="tex.error.par_before_eg">Paragraph break found before end group</entry> +<entry key="tex.error.unexpected_eg">Unexpected end group found</entry> +<entry key="tex.error.missing_endmath">Missing end math</entry> +<entry key="tex.error.dollar2_ended_with_dollar">$$ ended with $</entry> +<entry key="tex.error.not_found">Expected ''{0}'' but not found</entry> +<entry key="tex.error.missing_param">Argument expected for ''{0}'' but not found</entry> +<entry key="tex.error.empty_stack">Argument expected but not found (empty stack)</entry> +<entry key="tex.error.not_math_mode">{0} is only permitted in math mode</entry> +<entry key="tex.error.invalid_accent">{0} is not a recognised accent </entry> +<entry key="tex.error.ambiguous_midcs">Ambiguous use of {0}</entry> +<entry key="tex.error.missing_closing">Missing closing {0}</entry> +<entry key="tex.error.dimen_expected">Dimension expected</entry> +<entry key="tex.error.missing_unit">Missing unit</entry> +<entry key="tex.error.expected">Expected {0}</entry> +<entry key="tex.error.undefined">Undefined command {0}</entry> +<entry key="tex.error.undefined_char">Undefined active character ''{0}''</entry> +<entry key="tex.error.cs_expected">Control sequence expected (found ''{0}'')</entry> +<entry key="tex.error.number_expected">Number expected (found ''{0}'')</entry> +<entry key="tex.error.register_undef">Unknown register ''{0}''</entry> +<entry key="tex.error.syntax">Invalid syntax for {0}</entry> +<entry key="tex.error.extra">Extra {0}</entry> +<entry key="tex.error.extra_or_forgotten">Extra {0}, or forgotten {1}</entry> +<entry key="tex.error.double_subscript">Double subscript _{0}_ (replaced with _{0}'{}'_)</entry> +<entry key="tex.error.double_superscript">Double superscript ^{0}^ (replaced with ^{0}'{}'^)</entry> +<entry key="tex.error.illegal_align">Illegal alignment {0}</entry> +<entry key="tex.error.misplaced_omit">Misplaced \omit</entry> +<entry key="tex.error.improper_alphabetic_constant">Improper alphabetic constant {0}</entry> + +<entry key="latex.error.no_alignment">No alignment specifiers found</entry> +<entry key="latex.error.undefined_counter">No counter ''{0}'' defined</entry> +<entry key="latex.error.multi_begin_doc">Only one \begin'{document}' permitted</entry> +<entry key="latex.error.no_begin_doc">No \begin'{document}' found</entry> +<entry key="latex.error.multi_cls">Only one \documentclass permitted</entry> +<entry key="latex.error.missing_key">Missing ''{0}'' key</entry> +<entry key="latex.error.extra_end">Extra \end'{'{0}'}' found</entry> +<entry key="latex.error.unaccessible">Unaccessible ''{0}''</entry> +<entry key="latex.error.defined">''{0}'' already defined</entry> +<entry key="latex.error.illegal_array_arg_char">Illegal character ''{0}'' in array arg</entry> +<entry key="latex.error.lonely_item">Lonely \item</entry> + +<entry key="bibtex.error.missing_value">Missing value</entry> +<entry key="bibtex.error.expecting">Expecting ''{0}''</entry> +<entry key="bibtex.error.expecting_or">Expecting ''{0}'' or ''{1}''</entry> +<entry key="bibtex.error.missing_field_part">Missing field part</entry> +<entry key="bibtex.error.missing_field_name">Missing field name</entry> +<entry key="bibtex.error.unbalanced_braces">Unbalanced braces</entry> +<entry key="bibtex.error.immediately_follows_entry_type">''{0}'' immediately follows entry type</entry> +<entry key="bibtex.error.immediately_follows_field_name">''{0}'' immediately follows field name</entry> +<entry key="bibtex.error.illegal_end">Illegal end</entry> +<entry key="bibtex.error.missing">Missing</entry> +<entry key="bibtex.error.too_many_commas">Too many commas in name ''{0}''</entry> +<entry key="bibtex.error.string_name_undefined">String name ''{0}'' undefined</entry> +</properties> diff --git a/Master/texmf-dist/scripts/bib2gls/texparserlib.jar b/Master/texmf-dist/scripts/bib2gls/texparserlib.jar Binary files differnew file mode 100755 index 00000000000..70561ba72dc --- /dev/null +++ b/Master/texmf-dist/scripts/bib2gls/texparserlib.jar diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip Binary files differnew file mode 100644 index 00000000000..8fdaf076b08 --- /dev/null +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex new file mode 100644 index 00000000000..b26599e0a0e --- /dev/null +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex @@ -0,0 +1,7517 @@ +% arara: pdflatex +% arara: makeindex: {style: bib2gls.ist} +% arara: pdflatex +\documentclass[titlepage=false,index=totoc,12pt]{scrreprt} + +\usepackage[T1]{fontenc} +\usepackage{tgtermes} +\usepackage[x11names]{xcolor} +\usepackage{alltt} +\usepackage{upquote} +\usepackage{etoolbox} +\usepackage{filecontents} + +\newcommand*{\actual}{=} + +\begin{filecontents*}{\jobname.ist} +actual '=' +\end{filecontents*} + +\usepackage{xcolor} +\usepackage{amsmath} +\usepackage{accents} +\usepackage{makeidx} +\usepackage{datetime2} +\usepackage[hidelinks]{hyperref} +\usepackage{glossaries-extra} +\glsdisablehyper + +\makeindex + +\newabbreviation{IETF}{IETF}{Internet Engineering Task Force} + +\DTMsavetimestamp{creation}{2017-01-20T15:39:00Z} + +\IfFileExists{../java/Bib2Gls.java} +{ + \DTMsavefilemoddate{moddate}{../java/Bib2Gls.java} +} +{ + \DTMsavenow{moddate} +} + +\newif\ifmainmatter + +\newcommand{\frontmatter}{% + \clearpage\pagenumbering{roman}% + \mainmatterfalse +} +\newcommand{\mainmatter}{% + \clearpage\pagenumbering{arabic}% + \mainmattertrue +} + +\newcommand{\bibgls}{\appfmt{bib2gls}} + +\newcommand*{\sectionref}[1]{\hyperref[#1]{section~\ref*{#1}}} +\newcommand*{\Sectionref}[1]{\hyperref[#1]{Section~\ref*{#1}}} + +\newcommand{\langxml}{\hyperref[sec:lang.xml]{language resource file}} + +\newcommand{\qt}[1]{``#1''} + +\newcommand{\qtt}[1]{\qt{\,\texttt{#1}\,}} + +\newcommand{\dequals}{% + \texorpdfstring + {\discretionary{}{}{}\texttt{=}\discretionary{}{}{}}% + {=}% +} + +\newcommand{\dcomma}{% + \texorpdfstring + {\texttt{,}\discretionary{}{}{}}% + {,}% +} + +\newcommand{\dcolon}{% + \texorpdfstring + {\texttt{:}\discretionary{}{}{}}% + {:}% +} + +% put page break before dash to avoid confusion with a hyphen +\newcommand{\dhyphen}{% + \texorpdfstring + {\discretionary{}{}{}\texttt{-}}% + {-}% +} + +\pdfstringdefDisableCommands{% + \def\dhyphen{-}% + \def\dcolon{:}% + \def\dcomma{,}% + \def\dequals{,}% +} + +\newcommand*{\filefmt}[1]{\texorpdfstring{\nolinkurl{#1}}{#1}} +\newcommand*{\metafilefmt}[3]{% + \filefmt{#1}\discretionary{}{}{}\meta{#2}\discretionary{}{}{}\filefmt{#3}% +} + +\newcommand*{\primaryresourcefmt}{% + \texorpdfstring + {\texttt{\char`\\ jobname.glstex}}% + {\string\\jobname.glstex}% +} + +\newcommand*{\suppresourcefmt}[1]{% + \texorpdfstring + {\texttt{\char`\\ jobname-#1.glstex}}% + {\string\\jobname-1.glstex}% +} + + +\newcommand*{\appfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}} +\newcommand*{\styfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} +\newcommand*{\csfmt}[1]{\texorpdfstring{\texttt{\char`\\ #1}}{\string\\#1}} +\newcommand*{\envfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} +\newcommand*{\optfmt}[1]{\texorpdfstring{\texttt{#1}}{#1}} +\newcommand*{\csoptfmt}[1]{\texorpdfstring{\textcolor{DarkSeaGreen4}{\optfmt{#1}}}{#1}} +\newcommand*{\styoptfmt}[1]{\texorpdfstring{\textcolor{DarkOrchid4}{\optfmt{#1}}}{#1}} +\newcommand*{\fieldfmt}[1]{\texorpdfstring{\texttt{\color{DarkSlateGray4}#1}}{#1}} +\newcommand*{\entryfmt}[1]{\texorpdfstring{\texttt{\color{SteelBlue4}#1}}{#1}} +\newcommand*{\abbrstylefmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} +\newcommand*{\glostylefmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} +\newcommand*{\catattrfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} +\newcommand*{\counterfmt}[1]{\texorpdfstring{\textsf{#1}}{#1}} +\newcommand*{\idprefixfmt}[1]{% + \texorpdfstring{\texttt{#1\spacefactor999 .}}{#1.}} + +\newcommand*{\argor}{\texorpdfstring{\protect\textbar}{\string\|}} + +\newrobustcmd*{\texmeta}[1]{{\normalfont\normalcolor$\langle$\emph{#1}$\rangle$}} + +\newcommand*{\meta}[1]{% + \texorpdfstring{\texmeta{#1}}{#1}% +} + +\newcommand*{\oarg}[1]{[#1]} +\newcommand*{\oargm}[1]{\oarg{\meta{#1}}} + +\newcommand*{\marg}[1]{\texorpdfstring + {\discretionary{}{}{}\char`\{#1\char`\} }% + {\{#1\}}% +} + +\newcommand*{\margm}[1]{\marg{\meta{#1}}} + +\newcommand*{\file}[1]{% + \texorpdfstring + {\filefmt{#1}\index{#1\actual\filefmt{#1}}}% + {#1}% +} + +\newcommand*{\ext}[1]{% + \texorpdfstring + {\filefmt{.#1}\index{file formats!#1\actual\filefmt{.#1}}}% + {.#1}% +} + +\newcommand*{\app}[1]{% + \texorpdfstring + {\appfmt{#1}\index{#1\actual\appfmt{#1}}}% + {#1}% +} + +\newcommand*{\sty}[1]{% + \texorpdfstring + {\styfmt{#1}\index{#1\actual\styfmt{#1}}}% + {#1}% +} + +\newcommand*{\env}[1]{% + \texorpdfstring + {\envfmt{#1}\index{#1 environment\actual\envfmt{#1} environment}}% + {#1}% +} + +\newcommand*{\abbrstyle}[1]{% + \texorpdfstring + {\abbrstylefmt{#1}\index{abbreviation style!#1\actual\abbrstylefmt{#1}}}% + {#1}% +} + +\newcommand*{\glostyle}[1]{% + \texorpdfstring + {\glostylefmt{#1}\index{glossary style!#1\actual\glostylefmt{#1}}}% + {#1}% +} + +\newcommand*{\catattr}[1]{% + \texorpdfstring + {\catattrfmt{#1}\index{category attributes!#1\actual\catattrfmt{#1}}}% + {#1}% +} + +\newcommand*{\counter}[1]{% + \texorpdfstring + {\counterfmt{#1}\index{#1 counter\actual\counterfmt{#1} counter}}% + {#1}% +} + +\newcommand*{\idprefix}[1]{% + \texorpdfstring + {\idprefixfmt{#1}\index{label prefixes!#1\actual\protect\idprefixfmt{#1}}}% + {#1}% +} + +\newcommand*{\cs}[1]{% + \texorpdfstring + {\csfmt{#1}\index{#1\actual\protect\csfmt{#1}}} + {\string\\#1}% +} + +\newcommand*{\styopt}[2][]{% + \texorpdfstring% + {% + \styoptfmt{#2\ifblank{#1}{}{\dequals\marg{#1}}}% + \index{package options!#2\actual\protect\styoptfmt{#2}}% + \index{#2\actual\protect\styoptfmt{#2}}% + }% + {#2\ifblank{#1}{}{=#1}}% +} + +\newcommand*{\keyvallist}{% + \texorpdfstring + {key\dequals value list}% + {key=value list}% +} + +\newcommand*{\csopt}[2][]{\gencsopt[#1]{glsxtrresourcefile}{#2}}% +\newcommand*{\glsopt}[2][]{\gencsopt[#1]{gls}{#2}}% +\newcommand*{\glsaddopt}[2][]{\gencsopt[#1]{glsadd}{#2}}% + +\newcommand*{\csoptnv}[1]{% + \texorpdfstring + {\protect\gencsopt{glsxtrresourcefile}{#1}}% + {#1}% +}% + +\newcommand*{\csopteqval}[1]{\csoptfmt{=\margm{#1}}} + +\newcommand*{\gencsopt}[3][]{% + \texorpdfstring% + {% + \csoptfmt{#3\ifblank{#1}{}{\dequals\marg{#1}}}% + \ifmainmatter + {\def\dhyphen{-}\index{#2\actual\protect\csfmt{#2}!#3\actual\protect\csoptfmt{#3}}}% + \fi + }% + {#3\ifblank{#1}{}{=#1}}% +} + +\newcommand*{\field}[1]{% + \texorpdfstring + {\fieldfmt{#1}% + \index{fields!#1\actual\protect\fieldfmt{#1}}% + \index{#1 field\actual\protect\fieldfmt{#1} field}% + }% + {#1}% +} + +\newcommand*{\entry}[1]{% + \texorpdfstring + {\entryfmt{#1}% + \index{entry types!#1\actual\protect\entryfmt{@#1}}% + \index{#1 entry type\actual\protect\entryfmt{@#1} entry type}% + }% + {#1}% +} + +\newcommand*{\atentry}[1]{% + \texorpdfstring + {\entryfmt{@#1}% + \index{entry types!#1\actual\protect\entryfmt{@#1}}% + \index{#1 entry type\actual\protect\entryfmt{@#1} entry type}% + }% + {@#1}% +} + +\newrobustcmd{\longswitch}{\string-{}\string-} + +\newcommand*{\longargfmt}[1]{% + \texorpdfstring{\texttt{\longswitch #1}}% + {\string-\string-#1}% +} + +\newcommand*{\shortargfmt}[1]{% + \texorpdfstring{\texttt{\string-#1}}% + {\string-#1}% +} + +\newrobustcmd{\longargindex}[1]{% + \ifmainmatter + {\def\dhyphen{-}% + \index{command line options!#1\actual\protect\longargfmt{#1}}% + }% + \fi +} + +\newcommand*{\longarg}[1]{% + \texorpdfstring + {\longargfmt{#1}\longargindex{#1}}% + {\string-\string-#1}% +} + +\newrobustcmd{\shortargindex}[1]{% + \ifmainmatter + {\def\dhyphen{-}% + \index{command line options!#1\actual\protect\shortargfmt{#1}}% + }% + \fi +} + +\newcommand*{\shortarg}[1]{% + \texorpdfstring + {\shortargfmt{#1}\shortargindex{#1}}% + {\string-#1}% +} + +\newcommand*{\keyword}[1]{% + \texorpdfstring{\emph{#1}\index{#1}}{#1}% +} + +\definecolor{defbackground}{rgb}{1,1,0.75} +\newsavebox\defsbox +\newlength\defwidth + +\newenvironment{definition}% +{% + \setlength{\fboxsep}{4pt}\setlength{\fboxrule}{1.25pt}% + \begin{lrbox}{\defsbox}% + \setlength\defwidth\linewidth + \addtolength\defwidth{-2\fboxrule}% + \addtolength\defwidth{-2\fboxsep}% + \begin{minipage}{\defwidth} + \flushleft\ttfamily\ignorespaces +}% +{% + \end{minipage}% + \end{lrbox}\par\medskip\noindent + \fcolorbox{black}{defbackground}{\usebox\defsbox}% + \medskip\par\noindent + \ignorespacesafterend +} + +% This is a bit fiddly. Need to represent \vec{v} in typewriter +% font for the interpreter examples. ($\mathtt{\vec{v}}$ doesn't +% work) +\newsavebox\varrow +\sbox\varrow{$\mathtt{\accentset{\to}{v}}$} + +\newcommand*{\mtx}[1]{\boldsymbol{#1}} +\newcommand*{\set}[1]{\mathcal{#1}} +\newcommand*{\card}[1]{|\set{#1}|} +\newcommand*{\imaginary}{i} + +\newcommand{\addr}[1]{\\\url{#1}} +\title{\appfmt{bib2gls}: a command line Java application to convert +\filefmt{.bib} files to \filefmt{glossaries-extra.sty} resource +files} +\author{Nicola Talbot\addr{http://www.dickimaw-books.com/}} +\date{\DTMusedate{moddate}} + +\makeatletter +\begingroup + \renewcommand{\addr}[1]{} + \let\texorpdfstring\@secondoftwo + \DTMsetstyle{pdf} + \protected@edef\x{\endgroup + \noexpand\hypersetup{% + pdftitle={\@title}, + pdfauthor={\@author}}% + \noexpand\pdfinfo{/CreationDate (\DTMuse{creation}) + /ModDate (\DTMuse{moddate}) + }% + }\x + +\newcommand*{\labelarg}[1]{% + {\def\@currentlabelname{\protect\longarg{#1}}\label{arg.#1}}% +} +\newcommand*{\argref}[1]{\nameref{arg.#1}} + +\newcommand*{\labelopt}[1]{% + {\def\dhyphen{\string\dhyphen\space}% + \protected@edef\@currentlabelname{\protect\csoptfmt{#1}}% + \def\dhyphen{-}\label{opt.#1}}% +} +\newrobustcmd*{\optref}[2][]{% + \nameref{opt.#2}% + \ifblank{#1}{}{\csoptfmt{\dequals\marg{#1}}}} + +\newcommand*{\labelatentry}[1]{% + {\def\@currentlabelname{\protect\atentry{#1}}\label{at.#1}}% +} +\newcommand*{\atentryref}[1]{\nameref{at.#1}} + +\newcommand*{\labelcs}[1]{% + {\def\@currentlabelname{\protect\cs{#1}}\label{cs.#1}}% +} +\newcommand*{\csref}[1]{\nameref{cs.#1}} + +\newcounter{phantom} +\newcommand*{\plabel}[2][]{\refstepcounter{phantom}% + {\def\@currentlabelname{#1}\label{#2}}% +} +\newcommand{\plabelcs}[1]{\plabel[\protect\cs{#1}]{cs.#1}} + +\makeatother + +\begin{document} +\maketitle +\pagenumbering{alph} +\thispagestyle{empty} + +\begin{abstract} +The \bibgls\ command line application can be used to extract +glossary information stored in a \filefmt{.bib} file and convert it +into glossary entry definition commands that can be read using +\styfmt{glossaries-extra}'s \csfmt{GlsXtrLoadResources} command. When used +in combination with the \styopt{record} package option, \bibgls\ +can select only those entries that have been used in the document, +as well as any dependent entries, which reduces the \TeX\ resources +required by not defining unnecessary commands. + +Since \bibgls\ can also sort and collate the recorded locations +present in the \filefmt{.aux} file, it can simultaneously by-pass the +need to use \appfmt{makeindex} or \appfmt{xindy}, although \bibgls\ +can be used together with an external indexing application if required. (For +example, if a custom \appfmt{xindy} rule is needed.) + +An additional build may be required to ensure the locations are +up-to-date as the page-breaking may be slightly different on the +first \LaTeX\ run due to the unknown references being replaced with +?? which can be significantly shorter than the actual text produced +when the reference is known. + +Note that \bibgls\ is a Java application, so it requires the +Java Runtime Environment (at least JRE~7). Additionally, +\styfmt{glossaries-extra} must be at least version 1.12. +(Although the latest version is recommended.) +This application was developed in response to the question +\href{http://tex.stackexchange.com/q/342544}{Is there a program for +managing glossary tags?} on \TeX\ on StackExchange. The \ext{bib} +file can be managed in an application such as JabRef. + +If you already have a \ext{tex} file containing +entry definitions using commands like \cs{newglossaryentry} +then you can use the supplementary tool \appfmt{convertgls2bib} +to convert the entries to the \ext{bib} format required by +\bibgls. See \sectionref{sec:gls2bib} for further details. +\end{abstract} + +\frontmatter + +\tableofcontents + +\mainmatter +\chapter{Introduction} + +If you have extensively used the \styfmt{glossaries} or +\styfmt{glossaries-extra} package, you may have found yourself +creating a large \ext{tex} file containing many definitions that +you frequently use in documents. This file can then simply be +loaded using \cs{input} or \cs{loadglsentries}, but a large file +like this can be difficult to maintain and if the document only +actually uses a small proportion of those entries, the document +build is unnecessarily slow due to the time and resources taken on +defining the unwanted entries. + +The aim of \bibgls\ is to allow the entries to be stored in a +\ext{bib} file, which can be maintained using a reference system +such as JabRef. The document build process +can now be analogous to that used with \app{bibtex} (or +\appfmt{biber}), where only those entries that have been recorded in the +document (and possibly their dependent entries) will be extracted +from the \ext{bib} file. Since \bibgls\ can also perform +hierarchical sorting and can collate location lists, it doubles as +an indexing application, which means that the \app{makeglossaries} +step can be skipped. + +You can't use \cs{glsaddall} with this method as that command works +by iterating over all defined entries and calling +\cs{glsadd}\margm{label}. On the first \LaTeX\ run there are no +entries defined, so \cs{glsaddall} does nothing. If you want to +select all entries, just use \optref[all]{selection} instead (which +has the advantage over \cs{glsaddall} in that it doesn't create a +redundant location for each entry). + +Note that \bibgls\ requires the extension package +\sty{glossaries-extra} and can't be used with just the base +\sty{glossaries} package, since it requires some of the extension +commands. See the \sty{glossaries-extra} user manual for information +on the differences between the basic package and the extended +package, as some of the default settings are different. + +Since the information used by \bibgls\ is +written to the \ext{aux} file, it's not possible to run \bibgls\ +through \TeX's shell escape while the \ext{aux} file is open for +write access. (The \ext{aux} file is closed \emph{after} the end +document hook, so it can't be deferred with \cs{AtEndDocument}.) +This means that if you really want to run \bibgls\ +through \cs{write18} it must be done in the preamble with +\cs{immediate}. For example: +\begin{verbatim} +\immediate\write18{bib2gls \jobname} +\end{verbatim} +As from version 1.14 of \sty{glossaries-extra}, this can be done +automatically with the \styopt{automake} option if the \ext{aux} +file exists. (Remember that this will require the shell escape to be +enabled.) + +\section{Example Use} +The glossary entries are stored in a \ext{bib} file. For +example, the file \filefmt{entries.bib} might contain: +\begin{verbatim} +@entry{bird, + name={bird}, + description = {feathered animal} +} + +@abbreviation{html, + short="html", + long={hypertext markup language} +} + +@symbol{v, + name={$\vec{v}$}, + text={\vec{v}}, + description={a vector} +} + +@index{goose,plural="geese"} +\end{verbatim} +Here's an example document that uses this data: +\begin{verbatim} +\documentclass{article} + +\usepackage[record]{glossaries-extra} + +\GlsXtrLoadResources[ + src={entries},% data in entries.bib + sort={en-GB}% sort according to 'en-GB' locale +] + +\begin{document} +\Gls{bird} and \gls{goose}. +Symbol: $\gls{v}$. +Abbreviation: \gls{html}. + +\printunsrtglossaries +\end{document} +\end{verbatim} +If this document is called \filefmt{myDoc.tex}, the build +process is: +\begin{verbatim} +pdflatex myDoc +bib2gls myDoc +pdflatex myDoc +\end{verbatim} +(This manual assumes \appfmt{pdflatex} for simplicity. Replace +with \appfmt{latex}, \appfmt{xelatex} or \appfmt{lualatex} as +appropriate.) + +You can have multiple instances of \cs{GlsXtrLoadResources}. For +example: +\begin{verbatim} +\documentclass{article} + +\usepackage[record,index,abbreviations,symbols]{glossaries-extra} + +\GlsXtrLoadResources[ + src={entries},% data in entries.bib + sort={en-GB},% sort according to 'en-GB' locale + match={entrytype={entry}},% only select @entry + type={main}% put these entries in the 'main' glossary +] + +\GlsXtrLoadResources[ + src={entries},% data in entries.bib + sort={en-GB},% sort according to 'en-GB' locale + match={entrytype={abbreviation}},% only select @abbreviation + type={abbreviations}% put these entries in the 'abbreviations' glossary +] + +\GlsXtrLoadResources[ + src={entries},% data in entries.bib + sort={letter-case},% case-sensitive letter sort + match={entrytype={symbol}},% only select @symbol + type={symbols}% put these entries in the 'symbols' glossary +] + +\GlsXtrLoadResources[ + src={entries},% data in entries.bib + sort={en-GB},% sort according to 'en-GB' locale + match={entrytype={index}},% only select @index + type={index}% put these entries in the 'index' glossary +] + +\begin{document} +\Gls{bird} and \gls{goose}. +Symbol: $\gls{v}$. +Abbreviation: \gls{html}. + +\printunsrtglossaries +\end{document} +\end{verbatim} + +Note that there's no need to called \app{xindy} or \app{makeindex} +since \bibgls\ automatically sorts the entries and collates the locations +after selecting the required entries from the \ext{bib} file and +before writing the temporary file that's input with \cs{glsxtrresourcefile} +(or the more convenient shortcut +\cs{GlsXtrLoadResources}).\footnote{This document will mostly use +the more convenient \cs{GlsXtrLoadResources}.} This +means the entries are already defined in the correct order, and only +those entries that are required in the document are defined, so +\cs{printunsrtglossary} (or \cs{printunsrtglossaries}) may be used. +(The \qtt{unsrt} part of the command name indicates that all +defined entries should be listed in the order of definition from +\sty{glossaries-extra}'s point of view.) + +If you additionally want to use an indexing application, such +as \app{xindy}, you need the package option +\styopt[alsoindex]{record} and use \cs{makeglossaries} +and \cs{printglossary} (or the iterative \cs{printglossaries}) as usual. +This requires a more complicated build process: +\begin{verbatim} +pdflatex myDoc +bib2gls myDoc +pdflatex myDoc +makeglossaries myDoc +pdflatex myDoc +\end{verbatim} +(The entries aren't defined until the second \LaTeX\ run, so the +indexing files required by \app{makeindex} or \app{xindy} can't be +created until then.) + +\section{Security} + +\TeX\ Live come with security settings +\texttt{openin\_any} and \texttt{openout\_any} that, respectively, +govern read and write file access (in addition to the operating +system's file permissions). \bibgls\ uses \app{kpsewhich} to +determine these values and honours them. MikTeX doesn't use these +settings, so if these values are unset, \bibgls\ will default to +\texttt{a} (any) for \texttt{openin\_any} and \texttt{p} (paranoid) for +\texttt{openout\_any}. + +\section{Localisation} +\label{sec:lang.xml} + +The messages produced by \bibgls\ are fetched from a resource file +called \metafilefmt{bib2gls-}{lang}{.xml}, where \meta{lang} is a +valid \gls{IETF} language tag. + +The appropriate file is searched for in the following order, where +\meta{locale} is the operating system's locale or the value supplied +by the \argref{locale} switch: +\begin{enumerate} +\item \meta{lang} exactly matches \meta{locale}. +For example, my locale is \texttt{en-GB}, so \bibgls\ will first search +for \filefmt{bib2gls-en-GB.xml}. This file doesn't exist, so it will +try again. + +\item If \meta{locale} has an associated script, the +next try is with \meta{lang} set to \meta{lang +code}\texttt{-}\meta{script} where \meta{lang code} is the two +letter ISO language code and \meta{script} is the script code. +For example, if \meta{locale} is \texttt{sr-RS-Latn} +then \bibgls\ will search for \filefmt{bib2gls-sr-Latn.xml} if +\filefmt{bib2gls-sr-RS-Latn.xml} doesn't exist. + +\item The final attempt is with \meta{lang} set to just the two +letter ISO language code. For example, \filefmt{bib2gls-sr.xml}. +\end{enumerate} + +If there is no match, \bibgls\ will fallback on the English resource file +\file{bib2gls-en.xml}. +(Currently only \file{bib2gls-en.xml} exists as my language skills aren't up +to translating it. Any volunteers who want to provide other language +resource files would be much appreciated.) + +Note that if you use the \optref[true]{loc-prefix} option, the +textual labels (\qt{Page} and \qt{Pages} in English) will be taken +from the resource file. In the event that the loaded resource file +doesn't match the document language, you will have to manually set +the correct translation (in English, this would be +\csopt[Page\dcomma Pages]{loc-prefix}). The default definition of +\csref{bibglspassim} is also obtained from the resource file. + +\section{Manual Installation} + +If you are unable to install \bibgls\ through your \TeX\ package +manager, you can install manually using the instructions below. +Replace \meta{TEXMF} with the path to your local or home TEXMF tree +(for example, \filefmt{~/texmf}). + +Copy the files provided to the following locations: +\begin{itemize} +\item \meta{TEXMF}\filefmt{/scripts/bib2gls/bib2gls.jar} +(Java application.) +\item \meta{TEXMF}\filefmt{/scripts/bib2gls/convertgls2bib.jar} +(Java application.) +\item \meta{TEXMF}\filefmt{/scripts/bib2gls/texparserlib.jar} +(Java library.) +\item \meta{TEXMF}\filefmt{/scripts/bib2gls/resources/bib2gls-en.xml} +(English resource file.) +\item \meta{TEXMF}\filefmt{/doc/support/bib2gls/bib2gls.pdf} +(This document.) +\end{itemize} + +If you are using a Unix-like system, there are also bash scripts +provided called \file{bib2gls.sh} and \file{convertgls2bib.sh}. +Either copy then directly to somewhere on your path without the \ext{sh} +extension, for example: +\begin{verbatim} +cp bib2gls.sh ~/bin/bib2gls +cp convertgls2bib.sh ~/bin/convertgls2bib +\end{verbatim} +or copy the files to +\meta{TEXMF}\filefmt{/scripts/bib2gls/} and create a +symbolic link to them called just \filefmt{bib2gls} and +\filefmt{convertgls2bib} from somewhere on +your path, for example: +\begin{verbatim} +cp bib2gls.sh ~/texmf/scripts/bib2gls/ +cp convertgls2bib.sh ~/texmf/scripts/bib2gls/ +cd ~/bin +ln -s ~/texmf/scripts/bib2gls/bib2gls.sh bib2gls +ln -s ~/texmf/scripts/bib2gls/convertgls2bib.sh convertgls2bib +\end{verbatim} +The \file{texparserlib.jar} file isn't an application but is a +library used by both \file{bib2gls.jar} and +\file{convertgls2bib.jar}, and so needs to be in the same class path. +(The library is in a separate +\href{https://github.com/nlct/texparser}{GitHub repository} as it's +also used by some of my other applications.) + +Windows users can create a \ext{bat} file that works in a +similar way to the bash scripts. To do this, create a file called +\file{bib2gls.bat} that contains the following: +\begin{verbatim} +@ECHO OFF +FOR /F "tokens=*" %%I IN ('kpsewhich --progname=bib2gls --format=texmfscripts +bib2gls.jar') DO SET JARPATH=%%I +java -Djava.locale.providers=CLDR,JRE -jar "%JARPATH%" %* +\end{verbatim} +Save this file to somewhere on your system's path. +(Similarly for \filefmt{convertgls2bib}.) Note that \TeX\ +distributions for Windows usually convert \ext{jar} files to +executables. + +You may need to refresh \TeX's database to ensure that +\app{kpsewhich} can find the \ext{jar} files. + +To test that the application has been successfully installed, open a +command prompt or terminal and run the following command: +\begin{verbatim} +bib2gls --version +convertgls2bib --version +\end{verbatim} +This should display the version information for both applications. + +\chapter{\texorpdfstring{\TeX}{TeX}\ Parser Library} +\label{sec:texparserlib} + +The \bibgls\ application requires the \TeX\ Parser Library +\file{texparserlib.jar}\footnote{\url{https://github.com/nlct/texparser}} which is used to parse the \ext{aux} +and \ext{bib} files. + +With the \argref{interpret} switch on (default), this library is +also used to interpret the sort value when it contains +a backslash \verb|\| or a dollar symbol \verb|$| or braces \verb|{| +\verb|}| (and when the \optref{sort} option is not \optfmt{unsrt} or +\optfmt{none} or \optfmt{use}). The other case is with +\optref{set-widest} when determining the width of the \field{name} +field. The \argref{no-interpret} switch will turn off this function, +but the library will still be used to parse the \ext{aux} and +\ext{bib} files. + +The \file{texparserlib.jar} library is not a +\TeX\ engine and there are plenty of situations where it doesn't +work. In particular, in this case it's being used in a fragmented +context without knowing most of the packages used by the +document\footnote{\bibgls\ can detect from the log file a small +number of packages that the parser can support, such as +\sty{pifonts}, \sty{wasysym}, \sty{amssymb}, \sty{stix}, \sty{mhchem} +and \sty{bpchem}. There's also partial support for \sty{siunitx}'s +\cs{si} command.}\ or any custom +commands or environments provided within the document. + +\TeX\ syntax can be quite complicated and, in some cases, far too +complicated for simple regular expressions. The library performs +better than a simple pattern match, and that's the purpose of +\file{texparserlib.jar} and why it's used by \bibgls\ (and by +\appfmt{convertgls2bib}). When +the \argref{debug} mode is on, any warnings or errors triggered by +the \argref{interpret} mode will be written to the transcript +prefixed with \texttt{texparserlib:} (the results of the conversions +will be included in the transcript as informational messages +prefixed with \texttt{texparserlib:} even with \argref{no-debug}). + +For example, suppose the \ext{bib} file includes: +\begin{verbatim} +@preamble{ +"\providecommand{\mtx}[1]{\boldsymbol{#1}} +\providecommand{\set}[1]{\mathcal{#1}} +\providecommand{\card}[1]{|\set{#1}|} +\providecommand{\imaginary}{i}"} + +@entry{M, + name={{}$\mtx{M}$}, + text={\mtx{M}}, + description={a matrix} +} + +@entry{v, + name={{}$\vec{v}$}, + text={\vec{v}}, + description={a vector} +} + +@entry{S, + name={{}$\set{S}$}, + text={\set{S}}, + description={a set} +} + +@entry{card, + name={{}$\card{S}$}, + text={\card{S}}, + description={the cardinality of the set $\set{S}$} +} + +@entry{i, + name={{}$\imaginary$}, + text={\imaginary}, + description={square root of minus one ($\sqrt{-1}$)} +} +\end{verbatim} +(The empty group at the start of the \field{name} fields +protects against the possibility that the \catattr{glossname} +category attribute might be set to \optfmt{firstuc}, which +automatically converts the first letter of the name to +upper case when displaying the glossary. See also +\argref{mfirstuc-protection} and +\argref{mfirstuc-math-protection}.) + +None of these entries have a \field{sort} field so the \field{name} +is used. If the entry type had been \atentryref{symbol} instead, +the fallback would be the entry's label. +This means that with \entry{symbol} instead of \entry{entry}, and the default +\optref[sort]{sort-field}, and with +\optref[letter-case]{sort}, these entries will be defined in +the order: \texttt{M}, \texttt{S}, \texttt{card}, \texttt{i}, \texttt{v} (since +this is the case-sensitive letter order of the labels) whereas +with \optref[letter-nocase]{sort-field}, the order will be: +\texttt{card}, \texttt{i}, \texttt{M}, \texttt{S}, \texttt{v} (since this +is the case-insensitive letter order of the labels). + +However, with \atentryref{entry}, the fallback field will +be taken from the \field{name} which in the above example contains \TeX\ code, so +\bibgls\ will use \file{texparserlib.jar} to interpret this code. +The library has several different ways of writing the processed +code. For simplicity, \bibgls\ uses the library's HTML output and then +strips the HTML markup and trims any leading or trailing +spaces. The library method that writes non-ASCII +characters using \qtt{\&x\meta{hex};} markup is overridden +by \bibgls\ to just write the Unicode character, which means +that the letter-based sorting options will sort according +to the integer value \meta{hex} rather than the string +\qtt{\&x\meta{hex};}. + +The interpreter is first passed the code provided with +\atentryref{preamble}: +\begin{verbatim} +\providecommand{\mtx}[1]{\boldsymbol{#1}} +\providecommand{\set}[1]{\mathcal{#1}} +\providecommand{\card}[1]{|\set{#1}|} +\providecommand{\imaginary}{i} +\end{verbatim} +(unless \optref[false]{interpret-preamble}). +This means that the provided commands are now recognised by the +interpreter when it has to parse the fields later. + +In the case of the \texttt{M} entry in the example above, the +code that's passed to the interpreter is: +\begin{verbatim} +{}$\mtx{M}$ +\end{verbatim} +The transcript (\ext{glg}) file will show the results of the +conversion:\footnote{The \argref{debug} mode will show additional +information.} +\begin{verbatim} +texparserlib: {}$\mtx{M}$ -> M +\end{verbatim} +So the \field{sort} value for this entry is set to \qtt{M}. The font +change (caused by math-mode and \cs{boldsymbol}) has been +ignored. The sort value therefore consists of a single Unicode +character 0x4D (Latin upper case letter \qtt{M}, decimal value 77). + +For the \texttt{v} entry, the code is: +\begin{verbatim} +{}$\vec{v}$ +\end{verbatim} +The transcript shows: +\begin{alltt} +texparserlib: \marg{}\$\csfmt{vec}\marg{v}\$ -> \usebox\varrow +\end{alltt} +So the \field{sort} value for this entry is set to \qtt{\usebox\varrow}, +which consists of two Unicode characters 0x76 +(Latin lower case letter \qtt{v}, decimal value 118) and +0x20D7 (combining right arrow above, decimal value 8407). + +For the \texttt{set} entry, the code is: +\begin{verbatim} +{}$\set{S}$ +\end{verbatim} +The transcript shows: +\begin{verbatim} +texparserlib: {}$\set{S}$ -> S +\end{verbatim} +So the \field{sort} value for this entry is set to \qtt{S} (again +ignoring the font change). This consists of a single Unicode +character 0x53 (Latin upper case letter \qtt{S}, decimal value~83). + +For the \texttt{card} entry, the code is: +\begin{verbatim} +{}$\card{S}$ +\end{verbatim} +The transcript shows: +\begin{verbatim} +texparserlib: {}$\card{S}$ -> |S| +\end{verbatim} +So the \field{sort} value for this entry is set to \qtt{|S|} +(the \textbar\ characters from the definition of \csfmt{card} provided +in \atentry{preamble} have been included, but the +font change has been discarded). In this case the sort value +consists of three Unicode characters 0x7C (vertical line, decimal +value 124), +0x53 (Latin upper case letter \qtt{S}, decimal value 83) and 0x7C again. +If \optref[false]{interpret-preamble} had been used, \csfmt{card} +wouldn't be recognised and would be discarded leaving just \qtt{S} +as the sort value. + +For the \texttt{i} entry, the code is: +\begin{verbatim} +{}$\imaginary$ +\end{verbatim} +The transcript shows: +\begin{verbatim} +texparserlib: {}$\imaginary$ -> i +\end{verbatim} +So the \field{sort} value for this entry is set to \qtt{i}. + +This means that in the case of the default \optref[sort]{sort-field} with +\optref[letter-case]{sort}, these entries will be defined in +the order: \texttt{M} ($\mtx{M}$), \texttt{S} ($\set{S}$), +\texttt{i} ($\imaginary$), \texttt{v} ($\vec{v}$) and +\texttt{card} ($\card{S}$). +In this case, the entries have been sorted according to +the character codes. If you run \bibgls\ with \argref{verbose} +the decimal character codes will be included in the transcript. +For this example: +\begin{alltt} +i -> 'i' [105] +card -> '|S|' [124 83 124] +M -> 'M' [77] +S -> 'S' [83] +v -> '\usebox\varrow' [118 8407] +\end{alltt} + +The \argref{group} option (in addition to \argref{verbose}) +will place the letter group in +parentheses before the character code list: +\begin{alltt} +i -> 'i' (i) [105] +card -> '|S|' [124 83 124] +M -> 'M' (M) [77] +S -> 'S' (S) [83] +v -> '\usebox\varrow' (v) [118 8407] +\end{alltt} +(Note that the \texttt{card} entry doesn't have a letter +group since the vertical bar character isn't considered a +letter.) + +If \optref[letter-nocase]{sort} is used instead then, after conversion +by the interpreter, the sort values will all be changed to +lower case. The order is now: \texttt{i} ($\imaginary$), +\texttt{M} ($\mtx{M}$), \texttt{S} ($\set{S}$), +\texttt{v} ($\vec{v}$) and \texttt{card} ($\card{S}$). +The transcript (with \argref{verbose}) now shows +\begin{alltt} +i -> 'i' [105] +card -> '|s|' [124 115 124] +M -> 'm' [109] +S -> 's' [115] +v -> '\usebox\varrow' [118 8407] +\end{alltt} +With \argref{group} (in addition to \argref{verbose}) +the letter groups are again included: +\begin{alltt} +i -> 'i' (I) [105] +card -> '|s|' [124 115 124] +M -> 'm' (M) [109] +S -> 's' (S) [115] +v -> '\usebox\varrow' (V) [118 8407] +\end{alltt} +Note that the letter groups are upper case not lower case. +Again the \texttt{card} entry doesn't have an associated +letter group. + +If a locale-based sort is used, the ordering will follow the +locale's alphabet rules. For example, with \optref[en]{sort} +(English, no region or variant), the order becomes: +\texttt{card} ($\card{S}$), \texttt{i} ($\imaginary$), +\texttt{M} ($\mtx{M}$), \texttt{S} ($\set{S}$) and +\texttt{v} ($\vec{v}$). The transcript (with \argref{verbose}) +shows the collation keys instead: +\begin{alltt} +i -> 'i' [0 92 0 0 0 0] +card -> '|S|' [0 66 0 102 0 66 0 0 0 0] +M -> 'M' [0 96 0 0 0 0] +S -> 'S' [0 102 0 0 0 0] +v -> '\usebox\varrow' [0 105 0 0 0 0] +\end{alltt} +Again the addition of the \argref{group} switch will show +the letter groups.\footnote{For more information on collation keys see the +\href{http://docs.oracle.com/javase/8/docs/api/java/text/CollationKey.html}{CollationKey} +class in Java's API.} + +Suppose I add a new symbol to my \ext{bib} file: +\begin{verbatim} +@symbol{angstrom, + name={\AA}, + description={\AA ngstr\"om} +} +\end{verbatim} +and I also use this entry in the document. Then with +\optref[en]{sort}, the order is: \texttt{card} ($\card{S}$), +\texttt{angstrom} (\AA), \texttt{i} ($\imaginary$), \texttt{M} +($\mtx{M}$), \texttt{S} ($\set{S}$), and \texttt{v} ($\vec{v}$). +The \argref{group} switch shows that the \texttt{angstrom} entry +(\AA) has been placed in the \qt{A} letter group. + +However, if I change the locale to \optref[sv]{sort}, the +\texttt{angstrom} entry is moved to the end of the list and the +\argref{group} switch shows that it's been placed in the \qt{\AA} +letter group. + +If you are using Java~8, you can set the +\texttt{java.locale.providers} property to \texttt{CLDR,JRE} to use +the Common Locale Data Repository, which has more extensive +support for locales than the native Java Runtime Environment. +This isn't available for Java~7, and should be enabled by default +for the proposed Java~9. + +\chapter{Command Line Options} +\label{sec:switches} + +\edef\resetsecnumdepth{\noexpand\setcounter{secnumdepth}{\arabic{secnumdepth}}} +\setcounter{secnumdepth}{0} + +The syntax of \bibgls\ is: +\begin{alltt} +bib2gls \oargm{options} \meta{filename} +\end{alltt} +where \meta{filename} is the name of the \ext{aux} file. (The +extension may be omitted.) Only one \meta{filename} is permitted. + +Available options are listed below. + +\section{\longarg{help} (or \shortarg{h})} +\labelarg{help} + +Display the help message and quit. + +\section{\longarg{version} (or \shortarg{v})} +\labelarg{version} + +Display the version information and quit. + +\section{\longarg{debug} \oargm{n}} +\labelarg{debug} + +Switch on debugging mode. If \meta{n} is present, it must be a +non-negative integer indicating the debugging level. If omitted 1 is +assumed. This option also switches on the verbose mode. A value of 0 +is equivalent to \longargfmt{no-debug}. + +\section{\longarg{no-debug} (or \longarg{nodebug})} +\labelarg{no-debug} + +Switches off the debugging mode. + +\section{\longarg{verbose}} +\labelarg{verbose} + +Switches on the verbose mode. This writes extra information to the +terminal and transcript file. + +\section{\longarg{no-verbose} (or \longarg{noverbose})} +\labelarg{no-verbose} + +Switches off the verbose mode. This is the default behaviour. +Some messages are written to the terminal. To completely suppress +all messages (except errors), switch on the silent mode. +For additional information messages, switch on the verbose mode. + +\section{\longarg{silent}} +\labelarg{silent} + +Suppresses all messages except for errors that would normally be +written to the terminal. Warnings and informational messages are +written to the transcript file, which can be inspected afterwards. + +\section{\longarg{locale} \meta{lang} (or \shortarg{l} \meta{lang})} +\labelarg{locale} + +Specify the preferred \langxml, where \meta{lang} is a valid \gls{IETF} language tag. +This option requires an appropriate \metafilefmt{bib2gls-}{lang}{.xml} +resource file otherwise \bibgls\ will fallback on English. + +\section{\longarg{log-file} \meta{filename} (or \shortarg{t} +\meta{filename})} +\labelarg{log-file} + +Sets the name of the transcript file. By default, the name is the +same as the \ext{aux} file but with a \ext{glg} extension. Note that +if you use \bibgls\ in combination with \app{xindy} or +\app{makeindex}, you will need to change the transcript file name to +prevent interference. + +\section{\longarg{dir} \meta{dirname} (or \shortarg{d} +\meta{dirname})} +\labelarg{dir} + +By default \bibgls\ assumes that the output files should be written +in the current working directory. The input \ext{bib} files are assumed to be +either in the current working directory or on \TeX's path (in which +case \app{kpsewhich} will be used to find them). + +If your \ext{aux} file isn't in the current working directory (for +example, you have run \TeX\ with \shortargfmt{output-directory}) +then you need to take care how you invoke \bibgls. + +Suppose I have a file called \filefmt{test-entries.bib} that +contains my entry definitions and a document called +\filefmt{mydoc.tex} that selects the \ext{bib} file using: +\begin{verbatim} +\GlsXtrLoadResources[src={test-entries}] +\end{verbatim} +(\filefmt{test-entries.bib} is in the same directory as +\filefmt{mydoc.tex}). +If I compile this document using +\begin{verbatim} +pdflatex -output-directory tmp mydoc +\end{verbatim} +then the auxiliary file \filefmt{mydoc.aux} will be written to the +\filefmt{tmp} sub-directory. The resource information is listed in +the \ext{aux} file as +\begin{verbatim} +\glsxtr@resource{src={test-entries}}{mydoc} +\end{verbatim} +If I run \bibgls\ from the \filefmt{tmp} directory, then it won't +be able to find the \filefmt{test-entries.bib} file (since it's in +the parent directory). + +If I run \bibgls\ from the same directory as \filefmt{mydoc.tex} +using +\begin{verbatim} +bib2gls tmp/mydoc +\end{verbatim} +then the \ext{aux} file is found and the transcript file is +\filefmt{tmp/mydoc.glg} (since the default is the same as the +\ext{aux} file but with the extension changed to \ext{glg}) but the +output file \filefmt{mydoc.glstex} will be written to the current +directory. + +This works fine from \TeX's point of view as it can find the +\ext{glstex} file, but it may be that you'd rather the \ext{glstex} +file was tidied away into the \filefmt{tmp} directory along with all +the other files. In this case you need to invoke \bibgls\ with the +\longarg{dir} or \shortarg{d} option: +\begin{verbatim} +bib2gls -d tmp mydoc +\end{verbatim} + +\section{\longarg{interpret}} +\labelarg{interpret} + +Switch on the interpreter mode (default). See \sectionref{sec:texparserlib} +for more details. + +\section{\longarg{no-interpret}} +\labelarg{no-interpret} + +Switch off the interpreter mode. See \sectionref{sec:texparserlib} +for more details. + +\section{\longarg{mfirstuc-protection} (or \shortarg{u})} +\labelarg{mfirstuc-protection} + +Commands like \cs{Gls} use \cs{makefirstuc} provided by the +\sty{mfirstuc} package. This command has limitations and one of the +things that can break it is the use of a referencing command +at the start of its argument. The \sty{glossaries-extra} package has +more detail about the problem in the \qt{Nested Links} section of +the user manual. If a glossary field starts with one of these +problematic commands, the recommended method (if the command can't +be replaced) is to insert an empty group in front of it. + +For example, the following definition +\begin{verbatim} +\newabbreviation{shtml}{shtml}{\glsps{ssi} enabled \glsps{short}{html}} +\end{verbatim} +will cause a problem for \verb|\Gls{shtml}| on first use. + +The above example, would be written in a \ext{bib} file as: +\begin{verbatim} +@abbreviation{shtml, + short={shtml}, + long={\glsps{ssi} enabled \glsps{html}} +} +\end{verbatim} + +With the \longarg{mfirstuc-protection} switch on (the default +behaviour), \bibgls\ will automatically insert an empty group at the +start of the \field{long} field to guard against this problem. A +warning will be written to the transcript. + +\section{\longarg{no-mfirstuc-protection}} +\labelarg{no-mfirstuc-protection} + +Switches off the \sty{mfirstuc} protection mechanism described +above. + +\section{\longarg{mfirstuc-math-protection}} +\labelarg{mfirstuc-math-protection} + +This works in the same way as \argref{mfirstuc-protection} but +guards against fields starting with inline maths +(\verb|$|\ldots\verb|$|). For example, if the \field{name} field +starts with \verb|$x$| and the glossary style automatically tries to +convert the first letter of the name to upper case, then this will +cause a problem. + +With \longarg{mfirstuc-math-protection} set, \bibgls\ will +automatically insert an empty group at the start of the field and +write a warning in the transcript. This setting is on by default. + +\section{\longarg{no-mfirstuc-math-protection}} +\labelarg{no-mfirstuc-math-protection} + +Switches off the above. + +\section{\longarg{nested-link-check} \meta{list}\argor\texttt{none}} +\labelarg{nested-link-check} + +By default, \bibgls\ will parse certain fields for potential nested links. +(See the section \qt{Nested Links} in the \sty{glossaries-extra} +user manual.) + +The default set of fields to check are: \field{name}, \field{text}, +\field{plural}, \field{first}, \field{firstplural}, \field{long}, +\field{longplural}, \field{short}, \field{shortplural} and +\field{symbol}. + +You can change this set of fields using +\longarg{nested-link-check} \meta{value} where \meta{value} may be +\optfmt{none} (don't parse any of the fields) or a comma-separated +list of fields to be checked. + +\section{\longarg{no-nested-link-check}} +\labelarg{no-nested-link-check} + +Equivalent to \longarg{nested-link-check} \optfmt{none}. + +\section{\longarg{shortcuts} \meta{value}} +\labelarg{shortcuts} + +Some entries may reference another entry within a field, using +commands like \cs{gls}, so \bibgls\ parses the fields for these +commands to determine dependent entries to allow them to be selected +even if they haven't been used within the document. +The \styopt{shortcuts} package option provided by +\styfmt{glossaries-extra} defines various synonyms, such as \cs{ac} +which is equivalent to \cs{gls}. By default the value of the +\styopt{shortcuts} option will be picked up by \bibgls\ when parsing the +\ext{aux} file. This then allows \bibgls\ to additionally search for +those shortcut commands while parsing the fields. + +You can override the \styopt{shortcuts} setting using +\longarg{shortcuts} \meta{value} (where \meta{value} may take +any of the allowed values for the \styopt{shortcuts} package option), +but in general there is little need to use this switch. + +\section{\longarg{map-format} \meta{format1}:\meta{format2} +or \shortarg{m} \meta{format1}:\meta{format2}} +\labelarg{map-format} + +This sets up the rule of precedence for partial location +matches (see \sectionref{sec:locationopts}). For example, +\begin{verbatim} +bib2gls --map-format "emph:hyperbf" mydoc +\end{verbatim} +This essentially means that if there's a record conflict +involving \texttt{emph}, try replacing \texttt{emph} with +\texttt{hyperbf} and see if that resolves the conflict. + +Note that if the conflict includes a range formation, the +range takes precedence. + +If you have multiple mappings, you can either use a single +\longarg{map-format} with a comma separated list of +\meta{format1}\dcolon\meta{format2} or you can have multiple instances of +\longarg{map-format} \meta{format1}\dcolon\meta{format2}. + +Note that the mapping tests are applied as the records are +read. For example, suppose the records are listed in the \ext{aux} +file as: +\begin{verbatim} +\glsxtr@record{gls.sample}{}{page}{emph}{3} +\glsxtr@record{gls.sample}{}{page}{hypersf}{3} +\glsxtr@record{gls.sample}{}{page}{hyperbf}{3} +\end{verbatim} +and \bibgls\ is invoked with +\begin{verbatim} +bib2gls --map-format "emph:hyperbf,hypersf:hyperit" mydoc +\end{verbatim} +or +\begin{verbatim} +bib2gls --map-format emph:hyperbf --map-format hypersf:hyperit mydoc +\end{verbatim} +then \bibgls\ will process these records as follows: +\begin{enumerate} +\item Accept the first record (\texttt{emph}) since there's +currently no conflict. (This is the first record for page~3 for the +entry given by \texttt{gls.sample}.) +\item The second record (\texttt{hypersf}) conflicts +with the existing record (\texttt{emph}). Neither has +the format \texttt{glsnumberformat} or \texttt{glsignore} so \bibgls\ consults +the mappings provided by \longargfmt{map-format}. +\begin{itemize} +\item The \texttt{hypersf} format (from the new record) is mapped to \texttt{hyperit}, +so \bibgls\ checks if the existing record +has this format. In this case it doesn't (the format is +\texttt{emph}). So \bibgls\ moves onto the next test: + +\item The \texttt{emph} format (from the existing record) is mapped to \texttt{hyperbf}, +so \bibgls\ checks if the new record has this format. +In this case it doesn't (the format is \texttt{hypersf}). + +Since the provided mappings haven't resolved this conflict, +the new record is discarded with a warning. Note that there's +no look ahead to the next record. (There may be other +records for other entries also used on page~3 interspersed between these records.) +\end{itemize} +\item The third record (\texttt{hyperbf}) conflicts +with the existing record (\texttt{emph}). Neither has +the format \texttt{glsnumberformat} or \texttt{glsignore} so \bibgls\ again consults +the mappings provided by \longargfmt{map-format}. +\begin{itemize} +\item The new record's \texttt{hyperbf} format has no mapping provided, +so \bibgls\ moves onto the next test: + +\item The existing record's \texttt{emph} format has a mapping +provided (\texttt{hyperbf}). This matches the new record's format, +so the new record takes precedence. + +This means that the location list ends up with the \texttt{hyperbf} +location for page~3. +\end{itemize} +\end{enumerate} + +If, on the other hand, the mappings are given as +\begin{verbatim} +--map-format "emph:hyperit,hypersf:hyperit,hyperbf:hyperit" +\end{verbatim} +then all the three conflicting records (\texttt{emph}, +\texttt{hypersf} and \texttt{hyperbf}) will end up being replaced +by a single record with \texttt{hyperit} as the format. + +Multiple conflicts will typically be rare as there's usually little +reason for more than two or three different location formats within +the same list. (For example, \texttt{glsnumberformat} as the default +and \texttt{hyperbf} or \texttt{hyperit} for a primary reference.) + +\section{\longarg{group}} +\labelarg{group} + +The \styfmt{glossaries-extra} \styopt{record} package option automatically creates a new field +called \field{group}. If the \longarg{group} switch is used then, when +sorting, \bibgls\ will try to determine the letter group for each +entry and add it to the \field{group} field. (Some \optref{sort} +options ignore this setting.) This value will be picked up by +\cs{printunsrtglossary} if group headings are required (for +example with the \glostyle{indexgroup} style). If you're not using +a glossary style that displays the group headings, there's no need +to use this switch. Note that this switch doesn't automatically +select an appropriate glossary style. + +There are four basic types of groups: +\begin{itemize} +\item \keyword{letter groups} where the group title indicates the +first letter of all the sort values within that group. +The group title is set with \csref{bibglslettergroup}. + +\item \keyword{non-letter groups} (or \keyword{symbol groups}) +where the first characters of all the sort values within that group +are non-alphabetical. The group title is set with \csref{bibglsothergroup}. + +\item \keyword{number groups} for all entries sorted by a numeric +comparison (such as \optref[integer]{sort}). +The group title is set with \csref{bibglsnumbergroup}. + +\item \keyword{custom groups} for all entries that have had the +group title explicitly set using the \optref[\meta{title}]{group} +resource option. +\end{itemize} + +The letter group titles will typically have the first character +converted to upper case for the rule-based comparisons +(\optref[custom]{sort} and \optref[\meta{lang-tag}]{sort}). A +\qt{letter} may not necessarily be a single character (depending on +the sort rule), but may be composed of multiple characters, such as +a \keyword{digraph} (two characters) or \keyword{trigraph} (three +characters). + +For example, if the sort rule recognises the digraph \qt{dz} as a +letter, then it will be converted to \qt{Dz} for the group title. +There are some exceptions to this. For example, the Dutch digraph +\qt{ij} should be \qt{IJ} rather than \qt{Ij}. This is indicated +by the following line in the \langxml: +\begin{verbatim} +<entry key="grouptitle.case.ij">IJ</entry> +\end{verbatim} +If there isn't a \texttt{grouptitle.case.\meta{lc}} key (where +\meta{lc} is the lower case version), then only the first character +will be converted to upper case otherwise the value supplied by the +resource file is used. This resource key is only checked for +the locale and custom rule comparisons. If the initial part of +the sort value isn't recognised as a letter according to the sort rule, +then the entry will be in a non-letter group (even if the character +is alphabetical). + +The locale-independent character code comparisons (such as +\optref[letter-nocase]{sort}) only select the first character of the +sort value for the group. If the character is +alphabetical\footnote{according to Java's +\texttt{Character.isAlphabetic(int)} method} then it will be a +letter group otherwise it's a non-letter group. The +case-insensitive ordering (such as \optref[letter-nocase]{sort}) +will convert the letter group character to upper case. The +case-sensitive ordering (such as \optref[letter-case]{sort}) won't +change the case. + +Glossary styles with navigational links to groups (such as +\glostyle{indexhypergroup}) require an extra run for the ordinary +\csfmt{makeglossaries} and \csfmt{makenoidxglossaries} methods. For +example, for the document \filefmt{myDoc.tex}: +\begin{verbatim} +pdflatex myDoc +makeglossaries myDoc +pdflatex myDoc +pdflatex myDoc +\end{verbatim} +On the first \appfmt{pdflatex} call, there's no glossary. On the second +\appfmt{pdflatex}, there's a glossary but the glossary must be +processed to find the group information, which is written to the +\ext{aux} file as +\begin{alltt} +\cs{@gls@hypergroup}\margm{type}\margm{group id} +\end{alltt} +The third \appfmt{pdflatex} reads this information and is then able +to create the navigation links. + +With \bibgls, if the \optfmt{type} is provided (through the +\field{type} field or via options such as \optref{type} and +\optref{dual-type}) then this information can be determined when +\bibgls\ is ready to write the \ext{glstex} file, which means that +the extra \LaTeX\ run isn't necessary. + +For example: +\begin{verbatim} +\documentclass{article} +\usepackage[colorlinks]{hyperref} +\usepackage[record,abbreviations,style=indexhypergroup]{glossaries-extra} + +\GlsXtrLoadResources[src={entries},% data in entries.bib + type={main}% put these entries in the 'main' glossary +] + +\GlsXtrLoadResources[src={abbrvs},% data in abbrvs.bib + type={abbreviations}% put these entries in the 'abbreviations' glossary +] +\end{verbatim} +Here the \optref{type} is set and \bibgls\ can detect that +\sty{hyperref} has been loaded, so if the \longargfmt{group} switch +is used, then the group hyperlinks can be set (using +\csref{bibglshypergroup}). This means that the build process is +just: +\begin{verbatim} +pdflatex myDoc +bibtex --group myDoc +pdflatex myDoc +\end{verbatim} +Note that this requires \sty{glossaries} v4.32+. If your version of +\sty{glossaries} is too old then \bibgls\ can't override +the default behaviour of \sty{glossary-hypernav}'s +\cs{glsnavhypertarget}. + +If \sty{hyperref} isn't loaded or the \longargfmt{group} switch +isn't used or the \field{type} isn't set or your version of +\sty{glossaries} is too old, then the information isn't saved. + +For example: +\begin{verbatim} +\documentclass{article} +\usepackage[colorlinks]{hyperref} +\usepackage[record,abbreviations,style=indexhypergroup]{glossaries-extra} + +\GlsXtrLoadResources[src={entries}]% data in entries.bib + +\GlsXtrLoadResources[src={abbrvs}]% data in abbrvs.bib +\end{verbatim} +This requires the build process: +\begin{verbatim} +pdflatex myDoc +bibtex --group myDoc +pdflatex myDoc +pdflatex myDoc +\end{verbatim} +because the group hyperlink information can't be determined by +\bibgls, so it's best to always set the \optfmt{type} if you want +hyper-group styles, and make sure you have an up-to-date version of +\sty{glossaries} (and \sty{glossaries-extra}). + +\section{\longarg{no-group}} +\labelarg{no-group} + +Don't use the \field{group} field. (Default.) +The glossary won't have groups even if a group style, such as +\glostyle{indexgroup}, is used. + +\section{\longarg{tex-encoding} \meta{name}} +\labelarg{tex-encoding} + +\bibgls\ tries to determine the character encoding to use for the +output files. If the document has loaded the \sty{inputenc} package then +\bibgls\ can obtain the value of the encoding from the +\ext{aux} file. This then needs to be converted to a name +recognised by Java. For example, \texttt{utf8} will be mapped to +\texttt{UTF-8}. If the \sty{fontspec} package has been loaded, +\sty{glossaries-extra} will assume the encoding is \texttt{utf8} and +write that value to the \ext{aux} file. + +If neither package has been loaded, \bibgls\ will assume the +operating system's default encoding. If this is incorrect or if +\bibgls\ can't work out the appropriate mapping then you can specify +the correct encoding using \longargfmt{tex-encoding} \meta{name} +where \meta{name} is the encoding name. + +\section{\longarg{trim-fields}} +\labelarg{trim-fields} + +Trim leading and trailing spaces from field values. For example, +if the \ext{bib} file contains: +\begin{verbatim} +@entry{sample, + name = { sample }, + description = { + an example + } +} +\end{verbatim} +This will cause spurious spaces. Using \longarg{trim-fields} will +automatically trim the values before writing the \ext{glstex} file. + +\section{\longarg{no-trim-fields}} +\labelarg{no-trim-fields} + +Don't trim any leading or trailing spaces from field values. +This is the default setting. + +\chapter{\ext{bib} Format} +\label{sec:bib} + +\bibgls\ recognises certain entry types. Any unrecognised types will +be ignored and a warning will be written to the transcript file. +Entries are defined in the usual \ext{bib} format: +\begin{alltt} +@\meta{entry-type}\marg{\meta{id}, + \meta{field-name-1} = \margm{text}, + ... + \meta{field-name-n} = \margm{text} +} +\end{alltt} +where \meta{entry-type} is the entry type (listed below), +\meta{field-name-1}, \ldots, \meta{field-name-n} are the field names +(same as the keys available with \cs{newglossaryentry}) and +\meta{id} is a unique label. The label can't contain any spaces or +commas. In general it's best to stick with alpha-numeric labels. +The field values may be delimited by braces \margm{text} or +double-quotes \texttt{"\meta{text}"}. + +\bibgls\ allows you to insert prefixes to the labels when the data +is read through the \optref{label-prefix} option. Remember to use +these prefixes when you reference the entries in the document, but +don't include them when you reference them in the \ext{bib} file. +There are some special prefixes that have a particular meaning to +\bibgls: \qt{\idprefix{dual}} and \qt{\idprefix{ext\meta{n}}} where +\meta{n} is a positive integer. In the first case, +\idprefix{dual} references the dual element of a dual entry (see +\atentryref{dualentry}). This prefix will be replaced by the value of +the \csopt{dual-prefix} option. The \idprefix{ext\meta{n}} prefix +is used to reference an entry from a different set of resources +(loaded by another \cs{GlsXtrLoadResources} command). This prefix is +replaced by the corresponding element of the list supplied by +\optref{ext-prefixes}. + +In the event that the \field{sort} value falls back on the label, +the original label supplied in the \ext{bib} file is used, not the +prefixed label. + +Avoid non-ASCII characters in the \meta{id} if your document uses the +\sty{inputenc} package. +You can set the character encoding in the \ext{bib} file using: +\begin{alltt} +\% Encoding: \meta{encoding-name} +\end{alltt} +where \meta{encoding-name} is the name of the character encoding. +For example: +\begin{verbatim} +% Encoding: UTF-8 +\end{verbatim} +You can also set the encoding using the \optref{charset} option, +but it's simpler to include the above comment on the first line of +the \ext{bib} file. (This comment is also searched for by JabRef +to determine the encoding, so it works for both applications.) +If you don't use either method \bibgls\ will +have to search the entire \ext{bib} file, which is inefficient and +you may end up with a mismatched encoding. + +Each entry type may have required fields and optional fields. For the +optional fields, any key recognised by \cs{newglossaryentry} may be +used as a field. However, note that if you add +any custom keys in your document using \cs{glsaddkey} or \cs{glsaddstoragekey}, those +commands must be placed before the first use of +\cs{GlsXtrLoadResources}. + +Any unrecognised fields will be ignored. +This is more convenient than using \cs{input} or \cs{loadglsentries}, which +requires all the keys used in the file to be defined, regardless of +whether or not you actually need them in the document. + +If an optional field is missing and \bibgls\ needs to access it for +some reason (for example, for sorting), \bibgls\ will try to +fallback on another value. The actual fallback value depends on the +entry type. + +Other entries can be cross-referenced using the \field{see}, +\field{seealso} or \field{alias} fields or +by using commands like \cs{gls} or \cs{glsxtrp} in any of the +recognised fields. These will automatically be selected if the +\csopt{selection} setting includes dependencies, but you may need to +rebuild the document to ensure the location lists are correct. +If an entry has the \field{see} field set, any instance of +\cs{glssee} in the document for that entry will be ignored, +otherwise the reference from \cs{glssee} will be transferred to the +\field{see} field (provided you have at least v1.14 of +\sty{glossaries-extra}). In general, it's best just to use the \field{see} +field and not use \cs{glssee}. + +The \field{seealso} key was only added to \sty{glossaries-extra} +v1.16, but this field may be used with \bibgls\ even if you only +have version 1.14 or 1.15. If the key isn't available, +\texttt{seealso=\margm{xr-list}} will be treated as +\texttt{see=\marg{[\cs{seealsoname}]\meta{xr-list}}} (the resource +option \optref{seealso} won't have an effect). You can't use both +\field{see} and \field{seealso} for the same entry with \bibgls. +Note that the \field{seealso} field doesn't allow for the optional +\oargm{tag} part. If you need a different tag, either use \field{see} +or change the definition of \cs{seealsoname} or +\cs{glsxtruseseealsoformat}. Note that, unless you are using +\app{xindy}, \cs{glsxtrindexseealso} just does +\cs{glssee}[\cs{seealsoname}], and so will be treated as \field{see} +rather than \field{seealso} by \bibgls. Again, it's better to just +use the \field{seealso} field directly. + +\section{\atentry{string}} +\labelatentry{string} + +The standard \atentry{string} is available and can be used to define +variables that may be used in field values. +For example: +\begin{verbatim} +@string{ssi={server-side includes}} +@string{html={hypertext markup language}} + +@abbreviation{shtml, + short="shtml", + long= ssi # " enabled " # html, + see={ssi,html} +} + +@abbreviation{html, + short ="html", + long = html +} + +@abbreviation{ssi, + short="ssi", + long = ssi +} +\end{verbatim} + +\section{\atentry{preamble}} +\labelatentry{preamble} + +The standard \atentry{preamble} is available and can be used to +provide command definitions used within field values. +For example: +\begin{verbatim} +@preamble{"\providecommand{\mtx}[1]{\boldsymbol{#1}}"} + +@entry{matrix, + name={matrix}, + plural={matrices}, + description={rectangular array of values, denoted $\mtx{M}$} +} +\end{verbatim} + +The \TeX\ parser library used by \bibgls\ will parse the contents of +\atentry{preamble} before trying to interpret the field value used +as a fallback when \field{sort} is omitted (unless +\optref[false]{interpret-preamble} is set in the resource options). +For example: +\begin{verbatim} +@preamble{"\providecommand{\set}[1]{\mathcal{#1}} +\providecommand{\card}[1]{|\set{#1}|}"} + +@entry{S, + name={{}$\set{S}$}, + text={\set{S}}, + description={a set} +} +@entry{card, + name={{}$\card{S}$}, + text={\card{S}}, + description={the cardinality of \gls{S}} +} +\end{verbatim} +Neither entry has the \field{sort} field, so \bibgls\ has to fall +back on the \field{name} field and, since this contains the special +characters \verb|\| \verb|$| \verb|{| and \verb|}|, the \TeX\ parser +library is used to interpret it. The definitions provided by +\atentry{preamble} allow \bibgls\ to deduce that the \field{sort} +value of the \texttt{S} entry is just \texttt{S} and the \field{sort} +value of the \texttt{card} entry is \verb"|S|" (see +\sectionref{sec:texparserlib}). + +What happens if you also need to use these commands in the document? +The definitions provided in \atentry{preamble} won't be available +until the \ext{glstex} file has been created, which means the +commands won't be defined on the first \LaTeX\ run. + +There are several approaches: +\begin{enumerate} +\item Just define the commands in the document. This means the +commands are available, but \bibgls\ won't be able to correctly +interpret the \field{name} fields. + +\item Define the commands in both the document and in +\atentry{preamble}. For example: +\begin{verbatim} +\newcommand{\set}[1]{\mathcal{#1}} +\newcommand{\card}[1]{|\set{#1}|} +\GlsXtrLoadResources[src={my-data}] +\end{verbatim} +Alternatively: +\begin{verbatim} +\GlsXtrLoadResources[src={my-data}] +\providecommand{\set}[1]{\mathcal{#1}} +\providecommand{\card}[1]{|\set{#1}|} +\end{verbatim} +If the provided definitions match those given in the \ext{bib} file, +there's no difference. If they don't match then in the first example +the document definitions will take precedence (but the interpreter +will use the \atentry{preamble} definitions) and in the second +example the \atentry{preamble} definitions will take precedence. + +\item Make use of \cs{glsxtrfmt} provided by +\sty{glossaries-extra}\footnote{Introduced in version 1.12.}\ which +allows you to store the name of the formatting command in a field. +The default is the \field{user1} field, but this can be changed to +another field by redefining \cs{GlsXtrFmtField}. + +The \ext{bib} file can now look like this: +\begin{verbatim} +@preamble{"\providecommand{\set}[1]{\mathcal{#1}} +\providecommand{\card}[1]{|\set{#1}|}"} + +@symbol{S, + name={{}$\set{S}$}, + text={\set{S}}, + user1={set}, + description={a set} +} +@symbol{cardS, + name={{}$\card{S}$}, + text={\card{S}}, + user1={card}, + description={the cardinality of \gls{S}} +} +\end{verbatim} +Within the document, you can format \meta{text} using the formatting +command provided in the \field{user1} field with: +\begin{definition} +\cs{glsxtrfmt}\oargm{options}\margm{label}\margm{text} +\end{definition} +(which internally uses \cs{glslink}) or +\begin{definition} +\cs{glsxtrentryfmt}\margm{label}\margm{text} +\end{definition} +which just applies the appropriate formatting command to +\meta{text}. If the entry given by \meta{label} hasn't been defined, +then this just does \meta{text} and a warning is issued. (It +just does \meta{text} without a warning if the field hasn't been set.) +The \meta{options} are as for \cs{glslink} but \cs{glslink} will +actually be using +\begin{alltt} +\cs{glslink}\oarg{\meta{def-options},\meta{options}}\margm{label}\marg{\csfmt{}\meta{csname}\margm{text}} +\end{alltt} +where the default options \meta{def-options} are given by +\cs{GlsXtrFmtDefaultOptions}. The default definition of this is +just \texttt{noindex} which suppresses the automatic indexing or +recording action. (See the \sty{glossaries-extra} manual +for further details.) + +This means that the document doesn't need to actually provide +\verb|\set| or \verb|\card| but can instead use, for example, +\begin{alltt} +\cs{glsxtrfmt}\marg{S}\marg{A} +\cs{glsxtrentryfmt}\marg{cardS}\marg{B} +\end{alltt} +instead of +\begin{verbatim} +\set{A} +\card{B} +\end{verbatim} +The first \LaTeX\ run will simply ignore the formatting and produce +a warning. + +Since this is a bit cumbersome to write, you can provide shortcut +commands. For example: +\begin{verbatim} +\GlsXtrLoadResources[src={my-data}] +\newcommand{\gset}[2][]{\glsxtrfmt[#1]{S}{#2}} +\newcommand{\gcard}[2][]{\glsxtrfmt[#1]{cardS}{#2}} +\end{verbatim} +Whilst this doesn't seem a great deal different from simply +providing the definitions of \csfmt{set} and \csfmt{card} in the +document, this means you don't have to worry about remembering +the names of the actual commands provided in the \ext{bib} file +(just the entry labels) and the use of \cs{glsxtrfmt} will +automatically produce a hyperlink to the glossary entry if the +\sty{hyperref} package has been loaded. +\end{enumerate} + +Here's an alternative \ext{bib} that defines entries with a term, a +description and a symbol: +\begin{verbatim} +@preamble{"\providecommand{\setfmt}[1]{\mathcal{#1}} +\providecommand{\cardfmt}[1]{|\setfmt{#1}|}"} + +@entry{set, + name={set}, + symbol={\setfmt{S}}, + user1={setfmt}, + description={collection of values} +} +@entry{cardinality, + name={cardinality}, + symbol={\cardfmt{S}}, + user1={cardfmt}, + description={the number of elements in the \gls{set} $\glssymbol{set}$} +} +\end{verbatim} +I've changed the entry labels and the names of the formatting commands. +The definitions in the document need to reflect the change in label +but not the change in the formatting commands: +\begin{verbatim} +\newcommand{\gset}[2][]{\glsxtrfmt[#1]{set}{#2}} +\newcommand{\gcard}[2][]{\glsxtrfmt[#1]{cardinality}{#2}} +\end{verbatim} + +Here's another approach that allows for a more complicated argument +for the cardinality. (For example, if the argument is an expression +involving set unions or intersections.) +The \ext{bib} file is now: +\begin{verbatim} +@preamble{"\providecommand{\setfmt}[1]{\mathcal{#1}} +\providecommand{\cardfmt}[1]{|#1|}"} + +@entry{set, + name={set}, + symbol={\setfmt{S}}, + user1={setfmt}, + description={collection of values} +} +@entry{cardinality, + name={cardinality}, + symbol={\cardfmt{\setfmt{S}}}, + user1={cardfmt}, + description={the number of elements in the \gls{set} $\glssymbol{set}$} +} +\end{verbatim} +This has removed the \csfmt{setfmt} command from the definition of +\csfmt{cardfmt}. Now the definitions in the document: +\begin{verbatim} +\newcommand{\gset}[1]{\glsxtrentryfmt{set}{#1}} +\newcommand{\gcard}[2][]{\glsxtrfmt[#1]{cardinality}{#2}} +\end{verbatim} +This allows for code such as: +\begin{verbatim} +\[ \gcard{\gset{A} \cap \gset{B}} \] +\end{verbatim} +which will link back to the \texttt{cardinality} entry in the +glossary and avoids any hyperlinking with \csfmt{gset}. +Alternatively to avoid links with \csfmt{gcard} as well: +\begin{verbatim} +\newcommand{\gset}[1]{\glsxtrentryfmt{set}{#1}} +\newcommand{\gcard}[1]{\glsxtrentryfmt{cardinality}{#1}} +\end{verbatim} +Now \csfmt{gset} and \csfmt{gcard} are simply formatting commands, +but their actual definitions are determined in the \ext{bib} file. + +\section{\atentry{entry}} +\labelatentry{entry} + +Regular terms are defined by the \atentry{entry} field. This requires the +\field{description} field and either \field{name} or \field{parent}. + +For example: +\begin{verbatim} +@preamble{"\providecommand{\mtx}[1]{\boldsymbol{#1}}"} + +@entry{matrix, + name={matrix}, + plural={matrices}, + description={rectangular array of values, denoted \gls{M}}, + seealso={vector} +} + +@entry{M, + name={\ensuremath{M}}, + description={a \gls{matrix}} +} + +@entry{vector, + name = "vector", + description = {column or row of values, denoted \gls{v}}, + seealso={matrix} +} + +@entry{v, + name={\ensuremath{\vec{v}}}, + description={a \gls{vector}} +} +\end{verbatim} +If the \field{name} field is omitted it will be set from the +parent's \field{name}. If the \field{sort} field is missing the +default is obtained from the \field{name} field. +(This can be overridden with \optref{sort-field}.) + +Terms defined using \atentry{entry} will be written to the output +(\ext{glstex}) file using the command \csref{bibglsnewentry}. + +\section{\atentry{symbol}} +\labelatentry{symbol} + +The \atentry{symbol} entry type is much like \atentry{entry}, but it's +designed specifically for symbols, so in the previous example, the +\texttt{M} and \texttt{v} terms would be better defined using the +\atentry{symbol} entry type instead. For example: +\begin{verbatim} +@symbol{M, + name={\ensuremath{M}}, + description={a \gls{matrix}} +} +\end{verbatim} + +The required fields are \field{name} or \field{parent}. The +\field{description} field is required if the \field{name} field is +missing. If the \field{sort} field is omitted, the default sort is +given by the entry label. Note that this is different from +\atentry{entry} where the sort defaults to \field{name} if omitted. + +Terms that are defined using \atentry{symbol} will be written to +the output file using the command \csref{bibglsnewsymbol}. + +\section{\atentry{number}} +\labelatentry{number} + +The \atentry{number} entry type is like \atentry{symbol}, but it's for +numbers. The numbers don't have to be explicit digits and may have a +symbolic representation. There's no real difference between the +behaviour of \atentry{number} and \atentry{symbol} except that terms +defined using \atentry{number} will be written to the output file +using the command \csref{bibglsnewnumber}. + +For example, the file \filefmt{constants.bib} might define +mathematical constants like this: +\begin{verbatim} +@number{pi, + name={\ensuremath{\pi}}, + description={the ratio of the length of the circumference + of a circle to its diameter}, + user1={3.14159} +} + +@number{e, + name={\ensuremath{e}}, + description={base of natural logarithms}, + user1={2.71828} +} +\end{verbatim} +This stores the approximate value in the \field{user1} field. This +can be used to sort the entries in numerical order according to the +values rather than the symbols: +\begin{verbatim} +\GlsXtrLoadResources[ + src={constants},% constants.bib + category={number},% set the category for all selected entries + sort={double},% numerical double-precision sort + sort-field={user1}% sort according to 'user1' field +] +\end{verbatim} +The \optref[number]{category} option makes it easy to adjust the +glossary format to include the \field{user1} field: +\begin{verbatim} +\renewcommand{\glsxtrpostdescnumber}{% + \ifglshasfield{useri}{\glscurrententrylabel} + { (approximate value: \glscurrentfieldvalue)}% + {}% +} +\end{verbatim} + +\section{\atentry{index}} +\labelatentry{index} + +The \atentry{index} entry type is designed for entries that don't +have a description. Only the label is required. If \field{name} is +omitted, it's assumed to be the same as the label, even if +\field{parent} is present. (Note this is different to the fallback +behaviour of \atentry{entry}, which fetches the name from the parent +entry.) However, this means that if the name contains any characters +that can't be used in the label, you will need the \field{name} +field. If the \field{sort} field is missing the +default is obtained from the \field{name} field. + +Example: +\begin{verbatim} +@index{duck} + +@index{goose,plural={geese}} + +@index{sealion,name={sea lion}} + +@index{facade,name={fa\c{c}ade}} +\end{verbatim} + +Terms that are defined using \atentry{index} will be written to the output +file using the command \csref{bibglsnewindex}. + +\section{\atentry{abbreviation}} +\labelatentry{abbreviation} + +The \atentry{abbreviation} entry type is designed for abbreviations. +The required fields are \field{short} and \field{long}. If the +\field{sort} key is missing, \bibgls\ will use the value of the +\field{short} field. +You can also use \optref{short-case-change} to convert the case of +the \field{short} field. + +Note that you must set the abbreviation style before loading the +resource file to ensure that the abbreviations are defined +correctly, however \bibgls\ has no knowledge of the abbreviation +style so it doesn't know if the \field{description} field must be +included or if the default \field{sort} value isn't simply the value +of the \field{short} field. + +You can instruct \bibgls\ to sort by the \field{long} field instead +using \optref[long]{sort-field}. You can also tell \bibgls\ to +ignore certain fields using \optref{ignore-fields}, so you can +include a \field{description} field in the \ext{bib} file if +you sometimes need it, and then instruct \bibgls\ to ignore it when +you don't want it. + +For example: +\begin{verbatim} +@abbreviation{html, + short ="html", + long = {hypertext markup language}, + description={a markup language for creating web pages} +} +\end{verbatim} +If you want the \abbrstyle{long-noshort-desc} style, then you can put +the following in your document (where the \ext{bib} file is called +\filefmt{entries-abbrv.bib}): +\begin{verbatim} +\setabbreviationstyle{long-noshort-desc} +\GlsXtrLoadResources[src={entries-abbrv.bib},sort-field={long}] +\end{verbatim} +Whereas, if you want the \abbrstyle{long-short-sc} style, then you can +instead do: +\begin{verbatim} +\setabbreviationstyle{long-short-sc} +\GlsXtrLoadResources[src={entries-abbrv.bib},ignore-fields={description}] +\end{verbatim} +or to convert the short value to upper case and use the +\abbrstyle{long-short-sm} style instead: +\begin{verbatim} +\setabbreviationstyle{long-short-sm} +\GlsXtrLoadResources[src={entries-abbrv.bib}, + short-case-change={uc},% convert short value to upper case + ignore-fields={description}] +\end{verbatim} +(If you want an equivalent of \csfmt{newdualentry}, use +\atentryref{dualentryabbreviation} instead.) + +Terms defined using \atentry{abbreviation} will be written to the output +file using the command \csref{bibglsnewabbreviation}. + +\section{\atentry{acronym}} +\labelatentry{acronym} + +The \atentry{acronym} entry type is like \atentry{abbreviation} except that +the term is written to the output file using the command +\csref{bibglsnewacronym}. + +\section{\atentry{dualentry}} +\labelatentry{dualentry} + +The \atentry{dualentry} entry type is similar to \atentry{entry} but +actually defines two entries: the primary entry and the dual entry. +The dual entry contains the same information as the primary entry +but some of the fields are swapped around. The dual entry is given +the prefix set by the \optref{dual-prefix} option. + +Note that the \field{alias} field will never be copied to the dual +entry, nor can it be mapped. The alias will only apply to the +primary entry. + +By default, the \field{name} and \field{description} fields and the +\field{plural} and \field{descriptionplural} fields are swapped. + +For example: +\begin{verbatim} +@dualentry{child, + name={child}, + plural={children}, + description={enfant} +} +\end{verbatim} +Is like +\begin{verbatim} +@entry{child, + name={child}, + plural={children}, + description={enfant} + descriptionplural={enfants} +} + +@entry{dual.child, + description={child}, + descriptionplural={children}, + name={enfant} + plural={enfants} +} +\end{verbatim} +where \idprefix{dual} is replaced by the value of the +\csopt{dual-prefix} option. However, instead of defining the entries +with \csfmt{bibglsnewentry} both the primary and dual entries are +defined using \csref{bibglsnewdualentry}. The \field{category} +and \field{type} fields can be set for the dual entry using the +\optref{dual-category} and \optref{dual-type} options. + +If \optref[combine]{dual-sort} then the dual entries will be sorted +along with the primary entries, otherwise the \csopt{dual-sort} +indicates how to sort the dual entries and the dual entries will be +appended to the end of the \ext{glstex} file. The +\optref{dual-sort-field} determines what field to use for the sort +value if the dual entries should be sorted separately. + +For example: +\begin{verbatim} +\newglossary*{english}{English} +\newglossary*{french}{French} + +\GlsXtrLoadResources[ + src = {entries-dual},% data in entries-dual.bib + type = {english},% put primary entries in glossary 'english' + dual-type = {french},% put dual entries in glossary 'french' + category = {dictionary},% set the primary category to 'dictionary' + dual-category = {dictionary},% set the dual category to 'dictionary' + sort = {en},% sort primary entries according to language 'en' + dual-sort = {fr}% sort dual entries according to language 'fr' +] +\end{verbatim} + +Note that there's no dual equivalent to \atentry{index} +since that entry type doesn't have required fields and +there's nothing obvious to swap with that type that would +differentiate it from a normal entry. + +\section{\atentry{dualentryabbreviation}} +\labelatentry{dualentryabbreviation} + +The \atentry{dualentryabbreviation} entry type is similar to +\atentry{dualentry}, but by default the +field mappings are: +\begin{itemize} +\item \field{long} $\mapsto$ \field{name} +\item \field{short} $\mapsto$ \field{text} +\end{itemize} +You may need to add a mapping from \field{shortplural} to +\field{plural} if the default is inappropriate. + +The required fields are: \field{short}, \field{long} and +\field{description}. This entry type is designed to emulate the +example \cs{newdualentry} command given in the \sty{glossaries} +user manual. The primary entry is an abbreviation with the given +\field{short} and \field{long} fields (but not the +\field{description}) and the secondary entry is a regular entry with +the \field{name} copied from the \field{long} field. + +For example: +\begin{verbatim} +@dualentryabbreviation{svm, + long = {support vector machine}, + short = {SVM}, + description = {statistical pattern recognition technique} +} +\end{verbatim} +is rather like doing +\begin{verbatim} +@abbreviation{svm, + long = {support vector machine}, + short = {SVM} +} + +@entry{dual.svm, + name = {support vector machine}, + description = {statistical pattern recognition technique} +} +\end{verbatim} +but \texttt{dual.svm} will automatically be selected if \texttt{svm} +is indexed in the document. If \texttt{dual.svm} isn't explicitly +indexed, it won't have a location list. + +As with \atentry{dualentry}, the \field{alias} field will never +be copied to the dual entry, nor can it be mapped. The alias will +only apply to the primary entry. + +If the \field{sort} field is missing \bibgls\ by default falls back +on the \field{name} field. If this is missing, this sort value will +fallback on the \field{short} field. This means that if \field{name} +isn't explicitly given in \atentry{dualentryabbreviation}, then the +primary entry will be sorted according to \field{short} but the dual +will be sorted according its \field{name} (which has been copied +from the primary \field{long}). + +Entries provided using \atentry{dualentryabbreviation} will be defined +with +\begin{alltt} +\csref{bibglsnewdualentryabbreviation} +\end{alltt} +(which uses \cs{newabbreviation}) for the primary entries and with +\begin{alltt} +\csref{bibglsnewdualentryabbreviationsecondary} +\end{alltt} +(which uses \cs{longnewglossaryentry}) for the secondary entries. +This means that if the \styopt{abbreviations} +package option is used, this will put the primary entry in the +\optfmt{abbreviations} glossary and the secondary entry in the +\optfmt{main} glossary. Use the \optref{type} and +\optref{dual-type} options to override this. + +\section{\atentry{dualsymbol}} +\labelatentry{dualsymbol} + +This is like \atentryref{dualentry} but the default mappings +swap the \field{name} and \field{symbol} fields (and the +\field{plural} and \field{symbolplural} fields). The \field{name} +and \field{symbol} are required. + +As with \atentry{dualentry}, the \field{alias} field will never +be copied to the dual entry, nor can it be mapped. The alias will +only apply to the primary entry. + +For example: +\begin{verbatim} +@dualsymbol{pi, + name={pi}, + symbol={\ensuremath{\pi}}, + description={the ratio of the length of the circumference + of a circle to its diameter} +} +\end{verbatim} + +Entries are defined using \csref{bibglsnewdualsymbol}, which by +default sets the \field{category} to \optfmt{symbol}. + +\section{\atentry{dualnumber}} +\labelatentry{dualnumber} + +This is much the same as \atentryref{dualsymbol} but entries are +defined using \csref{bibglsnewdualnumber}, which by default sets +the \field{category} to \optfmt{number}. + +The above example could be defined as a number since $\pi$ is a +constant: +\begin{verbatim} +@dualnumber{pi, + name={pi}, + symbol={\ensuremath{\pi}}, + description={the ratio of the length of the circumference + of a circle to its diameter}, + user1={3.14159} +} +\end{verbatim} + +This has stored the approximate value in the \field{user1} field. +The post-description hook could then be adapted to show this. +\begin{verbatim} +\renewcommand{\glsxtrpostdescnumber}{% + \ifglshasfield{useri}{\glscurrententrylabel} + { (approximate value: \glscurrentfieldvalue)}% + {}% +} +\end{verbatim} + +This use of the \field{user1} field means that the dual entries +could be sorted numerically according to the approximate value: +\begin{verbatim} +\usepackage[record,postdot,numbers,style=index]{glossaries-extra} + +\GlsXtrLoadResources[ + src={entries},% entries.bib + dual-type={numbers}, + dual-sort={double},% decimal sort + dual-sort-field={user1} +] +\end{verbatim} + +\section{\atentry{dualabbreviation}} +\labelatentry{dualabbreviation} + +The required fields are: \field{short}, \field{long}, +\field{dualshort} and \field{duallong}. +This includes some new fields: \field{dualshort}, +\field{dualshortplural}, \field{duallong} and +\field{duallongplural}. If these aren't already defined, they +will be provided in the \ext{glstex} file with +\begin{alltt} +\cs{glsxtrprovidestoragekey}\margm{key}\marg{}\marg{} +\end{alltt} +This command is defined by the \sty{glossaries-extra} package. +Note that this use with an empty third argument prevents +the creation of a field access command (analogous to +\cs{glsentrytext}). You can fetch the value with +\cs{glsxtrusefield}. (See the \sty{glossaries-extra} manual for +further details.) Remember that the field won't be +available until the \ext{glstex} file has been created. + +As with \atentry{dualentry}, the \field{alias} field will never +be copied to the dual entry, nor can it be mapped. The alias will +only apply to the primary entry. + +Note that \bibgls\ doesn't know what abbreviation styles +are in used, so if the \field{sort} field is missing +it will fallback on the \field{short} field. If the abbreviations +need to be sorted according to the \field{long} field instead, +use \optref[long]{sort-field}. + +The \atentry{dualabbreviation} entry type is similar to +\atentry{dualentry}, but by default the +field mappings are: +\begin{itemize} +\item \field{short} $\mapsto$ \field{dualshort} +\item \field{shortplural} $\mapsto$ \field{dualshortplural} +\item \field{long} $\mapsto$ \field{duallong} +\item \field{longplural} $\mapsto$ \field{duallongplural} +\item \field{dualshort} $\mapsto$ \field{short} +\item \field{dualshortplural} $\mapsto$ \field{shortplural} +\item \field{duallong} $\mapsto$ \field{long} +\item \field{duallongplural} $\mapsto$ \field{longplural} +\end{itemize} +Terms that are defined using \atentry{dualabbreviation} will be +written to the output file using \csref{bibglsnewdualabbreviation}. + +If the \optref{dual-abbrv-backlink} option is on, the default field +used for the backlinks is the \field{dualshort} field, so you'll need +to make sure you adapt the glossary style to show that field. The +simplest way to do this is through the category post description +hook. + +For example, if the entries all have the \field{category} set +to \optfmt{abbreviation}, then this requires redefining +\cs{glsxtrpostdescabbreviation}. + +Here's an example dual abbreviation for a document where English is +the primary language and German is the secondary language: +\begin{alltt} +@dualabbreviation\marg{rna, + short=\marg{RNA}, + dualshort=\marg{RNS}, + long=\marg{ribonucleic acid}, + duallong=\marg{Ribonukleins\"aure} +} +\end{alltt} +If the abbreviation is in the file called +\filefmt{entries-dual-abbrv.bib}, then here's an example document: +\begin{verbatim} +\documentclass{article} + +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} + +\usepackage[ngerman,main=english]{babel} +\usepackage[colorlinks]{hyperref} +\usepackage[record,nomain]{glossaries-extra} + +\newglossary*{english}{English} +\newglossary*{german}{German} + +\setabbreviationstyle{long-short} + +\renewcommand*{\glsxtrpostdescabbreviation}{% + \ifglshasfield{dualshort}{\glscurrententrylabel} + {% + \space(\glscurrentfieldvalue)% + }% + {}% +} + +\GlsXtrLoadResources[ + src={entries-dual-abbrv},% entries-dual-abbrv.bib + type=english,% put primary entries in glossary 'english' + dual-type=german,% put primary entries in glossary 'german' + label-prefix={en.},% primary label prefix + dual-prefix={de.},% dual label prefix + sort=en,% sort primary entries according to language 'en' + dual-sort=de-1996,% sort dual entries according to 'de-1996' + % (German new orthography) + dual-abbrv-backlink% add links in the glossary to the opposite + %entry +] + +\begin{document} + +English: \gls{en.rna}; \gls{en.rna}. + +German: \gls{de.rna}; \gls{de.rna}. + +\printunsrtglossaries +\end{document} +\end{verbatim} +If the \optref{label-prefix} is omitted, then only the dual entries +will have a prefix: +\begin{verbatim} +English: \gls{rna}; \gls{rna}. + +German: \gls{de.rna}; \gls{de.rna}. +\end{verbatim} +Another variation is to use the \abbrstyle{long-short-user} +abbreviation style and modify the associated \cs{glsxtruserfield} so that +the \field{duallong} field is selected for the parenthetical +material: +\begin{verbatim} +\renewcommand*{\glsxtruserfield}{duallong} +\end{verbatim} +This means that the first use of the primary entry is displayed as +\begin{quote} +ribonucleic acid (RNA, Ribonukleins\"aure) +\end{quote} +and the first use of the dual entry is displayed as: +\begin{quote} +Ribonukleins\"aure (RNS, ribonucleic acid) +\end{quote} + +Here's an example to be used with the \abbrstyle{long-short-desc} +style: +\begin{alltt} +@dualabbreviation\marg{rna, + short=\marg{RNA}, + dualshort=\marg{RNS}, + long=\marg{ribonucleic acid}, + duallong=\marg{Ribonukleins\"aure} + description=\marg{a polymeric molecule}, + user1=\marg{Ein polymeres Molek\"ul} +} +\end{alltt} +This stores the dual description in the \field{user1} field, +so this needs a mapping. +The new example document is much the same as the previous one, except +that the \optref{dual-abbrv-map} option is needed to include the +mapping between the \field{description} and \field{user1} fields: +\begin{verbatim} +\documentclass{article} + +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} + +\usepackage[ngerman,main=english]{babel} +\usepackage[colorlinks]{hyperref} +\usepackage[record,nomain]{glossaries-extra} + +\newglossary*{english}{English} +\newglossary*{german}{German} + +\setabbreviationstyle{long-short-desc} + +\renewcommand*{\glsxtrpostdescabbreviation}{% + \ifglshasfield{dualshort}{\glscurrententrylabel} + {% + \space(\glscurrentfieldvalue)% + }% + {}% +} + +\GlsXtrLoadResources[ + src={entries-dual-abbrv-desc},% entries-dual-abbrv-desc.bib + type=english,% put primary entries in glossary 'english' + dual-type=german,% put primary entries in glossary 'german' + label-prefix={en.},% primary label prefix + dual-prefix={de.},% dual label prefix + sort=en,% sort primary entries according to language 'en' + sort-field={long},% sort by the 'long' field + dual-sort=de-1996,% sort dual entries according to 'de-1996' + % (German new orthography) + dual-abbrv-backlink,% add links in the glossary to the opposite + % entry +% dual key mappings: + dual-abbrv-map={% + {short,shortplural,long,longplural,dualshort,dualshortplural, + duallong,duallongplural,description,user1}, + {dualshort,dualshortplural,duallong,duallongplural,short,shortplural, + long,longplural,user1,description} + } +] + +\begin{document} + +English: \gls{en.rna}; \gls{en.rna}. + +German: \gls{de.rna}; \gls{de.rna}. + +\printunsrtglossaries +\end{document} +\end{verbatim} +Note that since this document uses the \abbrstyle{long-short-desc} +abbreviation style, the \optref{sort-field} needs to be changed +to \optfmt{long}, since the fallback if the \field{sort} field is +missing is the \field{short} field. + +If I change the order of the mapping to: +\begin{verbatim} + dual-abbrv-map={% + {long,longplural,short,shortplural,dualshort,dualshortplural, + duallong,duallongplural,description,user1}, + {duallong,duallongplural,dualshort,dualshortplural,short,shortplural, + long,longplural,user1,description} +\end{verbatim} +Then the back-link field will switch to \field{duallong}. The +post-description hook can be modified to allow for this: +\begin{verbatim} +\renewcommand*{\glsxtrpostdescabbreviation}{% + \ifglshasfield{duallong}{\glscurrententrylabel} + {% + \space(\glscurrentfieldvalue)% + }% + {}% +} +\end{verbatim} + +An alternative is to use the \abbrstyle{long-short-user-desc} style +without the post-description hook: +\begin{verbatim} +\setabbreviationstyle{long-short-user-desc} + +\renewcommand*{\glsxtruserfield}{duallong} +\end{verbatim} +However be careful with this approach as it can cause nested +hyperlinks. In this case it's better to use the +\abbrstyle{long-postshort-user-desc} style which defers the +parenthetical material until after the link-text: +\begin{verbatim} +\setabbreviationstyle{long-postshort-user-desc} + +\renewcommand*{\glsxtruserfield}{duallong} +\end{verbatim} +If the back-link field has been switched to \field{duallong} then +the post-description hook is no longer required. + +\section{\atentry{dualacronym}} +\labelatentry{dualacronym} + +As \atentry{dualabbreviation} but defines the entries with +\csref{bibglsnewdualacronym}. + +\chapter{Resource File Options} +\label{sec:resourceopts} +\setcounter{secnumdepth}{1} + +Make sure that you load \sty{glossaries-extra} with the +\styopt{record} package option. This ensures that \bibgls\ can pick +up the required information from the \ext{aux} file. (You may omit +this option if you use \optref[all]{selection} and you don't require +the location lists.) + +The \ext{glstex} resource files created by \bibgls\ are loaded in +the document using +\begin{definition}\plabelcs{glsxtrresourcefile} +\cs{glsxtrresourcefile}\oargm{options}\margm{filename} +\end{definition} +where \meta{filename} is the name of the resource file without the +\ext{glstex} extension. +You can have multiple \cs{glsxtrresourcefile} commands within your +document, but each \meta{filename} must be unique, otherwise \LaTeX\ +would attempt to input the same \ext{glstex} file multiple times. +\bibgls\ checks for non-unique file names. + +There's a shortcut command that uses +\cs{jobname} in the \meta{filename}: +\begin{definition} +\cs{GlsXtrLoadResources}\oargm{options} +\end{definition} +The first instance of this command is equivalent to +\begin{alltt} +\cs{glsxtrresourcefile}\oargm{options}\marg{\cs{jobname}} +\end{alltt} +Any additional use of \cs{GlsXtrLoadResources} is equivalent to +\begin{alltt} +\cs{glsxtrresourcefile}\oargm{options}\marg{\cs{jobname}-\meta{n}} +\end{alltt} +where \meta{n} is number. For example: +\begin{verbatim} +\GlsXtrLoadResources[src=entries-en,sort={en}] +\GlsXtrLoadResources[src=entries-fr,sort={fr}] +\GlsXtrLoadResources[src=entries-de,sort={de-1996}] +\end{verbatim} +This is equivalent to: +\begin{verbatim} +\glsxtrresourcefile[src=entries-en,sort={en}]{\jobname} +\glsxtrresourcefile[src=entries-fr,sort={fr}]{\jobname-1} +\glsxtrresourcefile[src=entries-de,sort={de-1996}]{\jobname-2} +\end{verbatim} +In general, it's simplest just to use \cs{GlsXtrLoadResources}. + +The optional argument \meta{options} is a comma-separated \keyvallist. +Allowed options are listed below. +The option list applies only to that specific +\meta{filename}\ext{glstex} and are not carried over to the next +instance of \cs{glsxtrresourcefile}. The \sty{glossaries-extra} +package doesn't parse the options, but just writes the information to the +\ext{aux} file. This means that any invalid options will be reported +by \bibgls\ not by \sty{glossaries-extra}. + +If you have multiple \ext{bib} files you can either select them all +using \optref[\meta{bib list}]{src} in a single +\cs{glsxtrresourcefile} call, if they all require the same settings, +or you can load them separately with different settings applied. + +For example, if the files \filefmt{entries-terms.bib} and +\filefmt{entries-symbols.bib} have the same settings: +\begin{verbatim} +\GlsXtrLoadResources[src={entries-terms,entries-symbols}] +\end{verbatim} +Alternatively, if they have different settings: +\begin{verbatim} +\GlsXtrLoadResources[src={entries-terms},type=main] +\GlsXtrLoadResources[src={entries-symbols},sort=use,type=symbols] +\end{verbatim} + +Note that the sorting is applied to each resource call independently +of other resources. This means that if you have multiple instances +of \cs{glsxtrresourcefile} but only one glossary type, the glossary +will effectively contain blocks of sorted entries. For example, if +\filefmt{file1.bib} contains: +\begin{verbatim} +@index{duck} +@index{zebra} +@index{aardvark} +\end{verbatim} +and \filefmt{file2.bib} contains: +\begin{verbatim} +@index{caterpillar} +@index{bee} +@index{wombat} +\end{verbatim} +then +\begin{verbatim} +\GlsXtrLoadResources[src={file1,file2}] +\end{verbatim} +will result in the list: aardvark, bee, caterpillar, duck, wombat, +zebra. These six entries are all defined when +\csfmt{jobname}\filefmt{.glstex} is read. +Whereas +\begin{verbatim} +\GlsXtrLoadResources[src={file1}] +\GlsXtrLoadResources[src={file2}] +\end{verbatim} +will result in the list: aardvark, duck, zebra, bee, caterpillar, +wombat. The first three (aardvark, duck, zebra) are defined when +\csfmt{jobname}\filefmt{.glstex} is read. The second three (bee, +caterpillar, wombat) are defined when \csfmt{jobname}\filefmt{-1.glstex} +is read. Since \cs{printunsrtglossary} simply iterates over all +defined entries, this is the ordering used. + +\plabelcs{strong}% +Note \bibgls\ allows \ext{bib} files that don't provide any entries. +This can be used to provide commands in \atentryref{preamble}. +For example, suppose I have \filefmt{defs.bib} that just contains +\begin{verbatim} +@preamble{"\providecommand{\strong}[1]{\textbf{\color{red}#1}} +\providecommand{\test}[2]{#2 (#1)}"} +\end{verbatim} +This provides two commands: \csfmt{strong} (which sets the font +weight and colour) and \csfmt{test} (which just displays its second +argument followed by the first in parentheses). + +Suppose I also have \filefmt{entries.bib} that contains: +\begin{verbatim} +@index{example, + name={\strong{\test{stuff}{example}}} +} +@index{sample} +@index{test} +@index{foo} +@index{bar} +\end{verbatim} +This contains an entry that requires the commands provided in +\filefmt{defs.bib}, so to ensure those commands are defined, I can +do: +\begin{verbatim} +\GlsXtrLoadResources[src={defs,entries}] +\end{verbatim} +Unfortunately this results in the sort value for \texttt{example} being +set to \texttt{redexample (stuff)} because the interpreter has +detected the provided commands and expanded +\begin{verbatim} +\strong{\test{stuff}{example}} +\end{verbatim} +to +\begin{verbatim} +\textbf{\color{red}example (stuff)} +\end{verbatim} +It discards font changes, so \csfmt{textbf} is ignored, but it doesn't +recognise \cs{color} and so doesn't know that the first argument is +just the colour specifier and therefore doesn't discard it. +This means that \qt{\textbf{\color{red}example (stuff)}} is placed +between \qt{foo} and \qt{sample} instead of between \qt{bar} and +\qt{foo}. + +I can prevent the interpreter from parsing \atentryref{preamble}: +\begin{verbatim} +\GlsXtrLoadResources[src={defs,entries},interpret-preamble=false] +\end{verbatim} +Now when the sort value for \texttt{example} is obtained from +\begin{verbatim} +\strong{\test{stuff}{example}} +\end{verbatim} +no expansion occurs (since \csfmt{strong} and \csfmt{test} are +unrecognised) so the sort value ends up as +\texttt{stuffexample} +which places \qt{\textbf{\color{red}example (stuff)}} between +\qt{sample} and \qt{test}, which is again incorrect. + +The best thing to do in this situation is to split the provided +commands into two \ext{bib} files: one that shouldn't be interpreted +and one that should. + +For example, \filefmt{defs-nointerpret.bib}: +\begin{verbatim} +@preamble{"\providecommand{\strong}[1]{\textbf{\color{red}#1}}"} +\end{verbatim} +and \filefmt{defs-interpret.bib}: +\begin{verbatim} +@preamble{"\providecommand{\test}[2]{#2 (#1)}"} +\end{verbatim} +Now the first one can be loaded with \optref[false]{interpret-preamble}: +\begin{verbatim} +\GlsXtrLoadResources[src={defs-nointerpret},interpret-preamble=false] +\end{verbatim} +This creates a \ext{glstex} file that provides \csfmt{strong} but +doesn't define any entries. The other file \filefmt{defs-interpret.bib} can +then be loaded with the default \optref[true]{interpret-preamble}: +\begin{verbatim} +\GlsXtrLoadResources[src={defs-interpret,entries}] +\end{verbatim} +The provided commands are remembered by the interpreter, so you can +also do: +\begin{verbatim} +\GlsXtrLoadResources[src={defs-interpret}] +\GlsXtrLoadResources[src={entries}] +\end{verbatim} +The \emph{contents} of \atentryref{preamble} are only written to the +associated \ext{glstex} file, but the definitions contained within +the \atentry{preamble} are retained by the interpreter for subsequent +resource sets. + +\section{General Options} +\label{sec:generalopts} + +\subsection{\csoptnv{charset}\csopteqval{encoding-name}} +\labelopt{charset} + +If the character encoding hasn't been supplied in the \ext{bib} file +with the encoding comment +\begin{alltt} +\% Encoding: \meta{encoding-name} +\end{alltt} +then you can supply the correct encoding using +\csopt[encoding-name]{charset}. In general, it's better to include +the encoding in the \ext{bib} file where it can also be read by +a \ext{bib} managing systems, such as JabRef. + +See \argref{tex-encoding} for the encoding used to write the \ext{glstex} +file. + +\subsection{\csoptnv{interpret-preamble}\csopteqval{boolean}} +\labelopt{interpret-preamble} + +This is a boolean option that determines whether or not the +interpreter should parse the contents of \atentryref{preamble}. +The default is \optfmt{true}. If \optfmt{false}, the preamble +contents will still be written to the \ext{glstex} file, but any +commands provided in the preamble won't be recognised if the +interpreter is needed to determine an entry's sort value. + +\subsection{\csoptnv{set-widest}\csopteqval{boolean}} +\labelopt{set-widest} + +The \glostyle{alttree} glossary style needs to know the widest +\field{name} (for each level, if hierarchical). This can +be set using \cs{glssetwidest} provided by the \sty{glossaries} +package, but this requires knowing which name is the widest. + +The boolean option \csopt[true]{set-widest} will try to calculate +the widest names for each hierarchical level. Since it doesn't know +the fonts that will be used in the document or if there are any +non-standard commands that aren't provided in the \ext{bib} files +preamble, this option may not work. The transcript file will +include the message +\begin{alltt} +Calculated width of '\meta{text}': \meta{number} +\end{alltt} +where \meta{text} is \bibgls's interpretation of the contents +of the \field{name} field and \meta{number} is a rough guide +to the width of \meta{text} assuming the operating system's +default serif font. The entry that has the largest \meta{number} +is the one that will be selected. This will then be implemented +using: +\begin{alltt} +\cs{glssetwidest}\oargm{level}\marg{\cs{glsentryname}\margm{id}} +\end{alltt} +where \meta{id} is the entry's label. This leaves \TeX\ to +compute the width according to the document fonts. + +If \optref{type} has been set, the \cs{glssetwidest} command +will be appended to the glossary preamble for that type, otherwise +it's simply set in the \ext{glstex} file and may be overridden +later in the document if required. + +\subsection{\csoptnv{secondary}\csopteqval{list}} +\labelopt{secondary} + +It may be that you want to display a glossary multiple times +but with a different order. For example, the first time +alphabetically and the second time by category. + +You can do this with the \csopt{secondary} option. The value +(which must be supplied) is a comma-separated list where each +item in the list is in the format +\begin{definition} +\meta{sort}:\meta{field}:\meta{type} +\end{definition} +or +\begin{definition} +\meta{sort}:\meta{type} +\end{definition} +If the +\meta{field} is omitted, the value of \optref{sort-field} is used. +The value of \meta{sort} is as for \optref{sort}, but note that in this case the sort value \optfmt{unsrt} or +\optfmt{none} means to use the same ordering as the primary +entries. So with \optref[de-CH-1996]{sort}, +\optref[none:copies]{secondary} the \texttt{copies} +list will be ordered according to \texttt{de-CH-1996} and not +according to the order in which they were read when the \ext{bib} +file or files were parsed. +If \meta{sort} is \optfmt{custom}, then the rule should be +provided with \optref{secondary-sort-rule}. + +This will copy all the selected entries into the glossary labelled +\meta{type} sorted according to \meta{sort} using \meta{field} as +the sort value. + +(If the glossary \meta{type} doesn't exist, it will be +defined with \cs{provideignoredglossary*}\margm{type}.) +Note that if the glossary already exists and contains entries, +the existing entries aren't re-ordered. The new entries are +simply appended to the list. + +For example, suppose the \ext{bib} file contains entries like: +\begin{verbatim} +@entry{quartz, + name={quartz}, + description={hard mineral consisting of silica}, + category={mineral} +} + +@entry{cabbage, + name={cabbage}, + description={vegetable with thick green or purple leaves}, + category={vegetable} +} + +@entry{waterfowl, + name={waterfowl}, + description={any bird that lives in or about water}, + category={animal} +} +\end{verbatim} +and the document preamble contains: +\begin{verbatim} +\GlsXtrLoadResources[src={entries},sort={en-GB}, + secondary={en-GB:category:topic} +] +\end{verbatim} +This sorts the primary entries according to the default +\optref{sort-field} and then sorts the entries according +to the \field{category} field and copies this list to +the \texttt{topic} glossary (which will be provided if not defined.) + +The secondary list can be displayed with the hypertargets switched +off to prevent duplicates. The cross-references will link to the +original glossary. + +For example: +\begin{verbatim} +\printunsrtglossary[title={Summary (alphabetical)}] +\printunsrtglossary[title={Summary (by topic)},target=false] +\end{verbatim} + +The alternative (or if more than two lists are required) is to +reload the same \ext{bib} file with different label prefixes. +For example, if the entries are stored in \filefmt{entries.bib}: +\begin{verbatim} +\newglossary*{nosort}{Symbols (Unsorted)} +\newglossary*{byname}{Symbols (Letter Order)} +\newglossary*{bydesc}{Symbols (Ordered by Description)} +\newglossary*{byid}{Symbols (Ordered by Label)} + +\GlsXtrLoadResources[ + src={entries},% entries.bib + sort={unsrt}, + type={nosort} +] + +\GlsXtrLoadResources[ + src={entries},% entries.bib + sort={letter-case}, + type={byname}, + label-prefix={byname.} +] + +\GlsXtrLoadResources[ + src={entries},% entries.bib + sort={locale}, + sort-field={description}, + type={bydesc}, + label-prefix={bydesc.} +] + +\GlsXtrLoadResources[ + src={entries},% entries.bib + sort={letter}, + sort-field={id}, + type={byid}, + label-prefix={byid.} +] +\end{verbatim} + +\subsection{\csoptnv{secondary-sort-rule}\csopteqval{value}} +\labelopt{secondary-sort-rule} + +As \optref{sort-rule} but for secondary custom sorting. + +\section{Selection Options} +\label{sec:selectionopts} + +\subsection{\csoptnv{src}\csopteqval{list}} +\labelopt{src} + +This identifies the \ext{bib} files containing the entry +definitions. The value should be a comma-separated list of the +required \ext{bib} files. These may either be in the current working +directory or in the directory given by the \argref{dir} switch or on +\TeX's path (in which case \app{kpsewhich} will be used to find +them). The \ext{bib} extension may be omitted. Remember that if +\meta{list} contains multiple files it must be grouped to protect +the comma from the \meta{options} list. + +For example +\begin{verbatim} +\GlsXtrLoadResources[src={entries-terms,entries-symbols}] +\end{verbatim} +indicates that \bibgls\ must read the files +\filefmt{entries-terms.bib} and \filefmt{entries-symbols.bib} and +create the file given by \cs{jobname}\ext{glstex} on the first +instance or \cs{jobname}\texttt{-}\meta{n}\ext{glstex} on subsequent +use. + +With \csref{glsxtrresourcefile}\oargm{options}\margm{filename}, if +the \csopt{src} option is omitted, +the \ext{bib} file is assumed to be \meta{filename}\ext{bib}. For example: +\begin{verbatim} +\glsxtrresourcefile{entries-symbols} +\end{verbatim} +indicates that \bibgls\ needs to read the file +\filefmt{entries-symbols.bib}, which contains the entry data, and create the file +\filefmt{entries-symbols.glstex}. If the \ext{bib} file is +different or if you have multiple \ext{bib} files, you need to use +the \csopt{src} option. + +\cs{GlsXtrLoadResources} uses \cs{jobname} as the argument of +\cs{glsxtrresourcefile} on the first instance, so +\begin{verbatim} +\GlsXtrLoadResources[] +\end{verbatim} +will assume \optfmt{src=\cs{jobname}}. Remember that subsequent uses +of \cs{GlsXtrLoadResources} append a suffix, so in general it's +best to always supply \csopt{src}. + +\subsection{\csoptnv{selection}\csopteqval{value}} +\labelopt{selection} + +By default all entries that have records in the \ext{aux} file will +be selected as well as all their dependent entries. The dependent +entries that don't have corresponding records on the first \LaTeX\ +run, may need an additional build to ensure their location lists +are updated. + +Remember that on the first \LaTeX\ run the \ext{glstex} files don't +exist. This means that the entries can't be defined. The +\styopt{record} package option additionally switches on the +\styopt[warn]{undefaction} option, which means that you'll only get +warnings rather than errors when you reference entries in the +document. This means that you can't use \cs{glsaddall} with +\bibgls\ because the glossary lists are empty on the first run, so +there's nothing for \cs{glsaddall} to iterate over. +Instead, if you want to add all defined entries, you need to +instruct \bibgls\ to do this with the \csopt{selection} option. The +following values are allowed: +\begin{itemize} +\item \optfmt{recorded and deps}: add all recorded entries and +their dependencies (default). +\item \optfmt{recorded and deps and see}: as above but will also +add unrecorded entries whose \field{see} or \field{seealso} field refers to a recorded entry. +\item \optfmt{recorded no deps}: add all recorded entries but not +their dependencies. The dependencies include those referenced in the +\field{see} or \field{seealso} field, \field{parent} entries and those found referenced +with commands like \cs{gls} in the field values that are parsed by +\bibgls. With this setting, parents will be omitted unless they've +been referenced in the document through commands like \cs{gls}. +\item \optfmt{recorded and ancestors}: this is like the previous +setting but parents are added even if they haven't been referenced +in the document. The other dependent entries are omitted if they +haven't been referenced in the document. +\item \optfmt{all}: add all entries found in the \ext{bib} files +supplied in the \csopt{src} option. +\end{itemize} +The \meta{value} must be supplied. + +For example, suppose the file \filefmt{entries.bib} contains: +\begin{verbatim} +@index{run} + +@index{sprint,see={run}} + +@index{dash,see={sprint}} +\end{verbatim} +If the document only references the \qt{run} entry (for example, +using \verb|\gls{run}|) then: +\begin{itemize} +\item If \csopt[recorded and deps]{selection}, only the \qt{run} +entry is selected. The \qt{run} entry has a record, so it's +selected, but it has no dependencies. Neither \qt{sprint} nor +\qt{dash} have records, so they're not selected. +\item If \csopt[recorded and deps and see]{selection}, the \qt{run} +and \qt{sprint} entries are selected, but not the \qt{dash} entry. +The \qt{run} entry is selected because it has a record. The +\qt{sprint} entry doesn't have a record but its \field{see} field +includes \qt{run}, which does have a record, so \qt{sprint} is also +selected. The \qt{dash} entry doesn't have a record. Its +\field{see} field references \qt{sprint}. Although \qt{sprint} has +been selected, it doesn't have any records, so \qt{dash} isn't +selected. +\end{itemize} +The above is just an example. The circuitous redirection of +\qt{dash} to \qt{sprint} to \qt{run} is unhelpful to the reader and +is best avoided. A better method would be: +\begin{verbatim} +@index{run} + +@index{sprint,see={run}} + +@index{dash,see={run}} +\end{verbatim} +The \csopt[recorded and deps and see]{selection} in this case will +select all three entries, and the document won't send the reader on a +long-winded detour. +\subsection{\csoptnv{match}\csopteqval{\keyvallist}} +\labelopt{match} + +It's possible to filter the selection by matching field values. +If \meta{\keyvallist} is empty no filtering will be applied, otherwise +\meta{\keyvallist} should be a \meta{key}=\meta{regexp} list, where +\meta{key} is the name of a field or \optfmt{id} for the entry's +label or \optfmt{entrytype} for the entry's \ext{bib} type (as in +the part after \verb|@| in the \ext{bib} file not the \field{type} +field identifying the glossary label). + +The \meta{regex} part should be a regular expression conforming +to +\href{http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html}{Java's +Pattern class}. The pattern is anchored (\texttt{oo.*} matches +\texttt{oops} but not \texttt{loops}) and \meta{regexp} can't be +empty. Remember that \TeX\ will expand the option list as +it writes the information to the \ext{aux} file so take +care with special characters. For example, to match a literal +period use \verb|\string\.| not \verb|\.| (backslash dot). + +If the field is missing its value it is assumed to be empty for +the purposes of the pattern match even if it will be assigned a +non-empty default value when the entry is defined. + +If a field is listed multiple times, the pattern for that +field is concatenated using +\begin{alltt} +(?:\meta{pattern-1})|(?:\meta{pattern-2}) +\end{alltt} +where \meta{pattern-1} is the current pattern for that field +and \meta{pattern-2} is the new pattern. This means it performs a +logical OR\@. For the non-duplicate +fields the logical operator is given by \optref{match-op}. +For example: +\begin{verbatim} +match-op={and}, +match={ + {category=animals}, + {topic=biology}, + {category=vegetables} +} +\end{verbatim} +This will keep all the selected entries that satisfy: +\begin{itemize} +\item \field{category} matches \verb"(?:animals)|(?:vegetables)" + +(the \field{category} is either \optfmt{animals} or +\optfmt{vegetables}) + +\item[AND] + +\item \field{topic} is \texttt{biology}. +\end{itemize} +and will discard any entries that don't satisfy this condition. +A message will be written to the log file for each entry +that's discarded. + +Patterns for unknown fields will be ignored. If the entire +list consists of patterns for unknown fields it will be +treated as \csopt[\empty]{match}. That is, no filtering will be +applied. + +\subsection{\csoptnv{match-op}\csopteqval{value}} +\labelopt{match-op} + +If the value of \optref{match} contains more than one +\meta{key}=\meta{pattern} element, the \csopt{match-op} +determines whether to apply a logical AND or a logical OR. +The \meta{value} may be either \optfmt{and} or \optfmt{or}. +The default is \csopt[and]{match-op}. + +\subsection{\csoptnv{flatten}\csopteqval{boolean}} +\labelopt{flatten} + +This is a boolean option. The default value is +\csopt[false]{flatten}. +If \csopt[true]{flatten}, the sorting will ignore hierarchy and +the \field{parent} field will be omitted when writing +the definitions to the \ext{glstex} file, but the parent entries +will still be considered a dependent ancestor from the +\optref{selection} point of view. + +Note the difference between this option and using +\csopt[parent]{ignore-fields} which will remove the dependency +(unless a dependency is established through another field). + +\subsection{\csoptnv{flatten-lonely}\csopteqval{value}} +\labelopt{flatten-lonely} + +This may take one of three values: \optfmt{false} (default), +\optfmt{presort} and \optfmt{postsort}. The value must be supplied. + +Unlike the \optref{flatten} option, which completely +removes the hierarchy, the \csopt{flatten-lonely} option can be used +to selectively alter the hierarchy. In this case only those entries +that have a parent but have no siblings are checked. This option +is affected by the \optref{flatten-lonely-rule} setting. The conditions for +moving a child up one hierarchical level are as follows: +\begin{itemize} +\item The child must have a parent, and +\item the child can't have any selected siblings, and +\item if \csopt[only unrecorded parents]{flatten-lonely-rule} + then the parent can't have a location list, where the location list + includes records and \field{see} or \field{seealso} + cross-references (for the other rules the parent may have a location + list as long as it only has the one child selected). +\end{itemize} +If the child is selected for hierarchical adjustment, the parent +will be removed if: +\begin{itemize} +\item The parent has no location list, and +\item \csopt{flatten-lonely-rule} isn't set to \optfmt{no discard}. +\end{itemize} + +The value of \csopt{flatten-lonely} determines whether the +adjustment should be made before sorting (\optfmt{presort}) +or after sorting (\optfmt{postsort}). To disable this function +use \csopt[false]{flatten-lonely}. + +For example, suppose the file \filefmt{entries.bib} contains: +\begin{verbatim} +@index{birds} +@index{duck,parent={birds}} +@index{goose,plural={geese},parent={birds}} +@index{swan,parent={birds}} +@index{chicken,parent={birds}} + +@index{vegetable} +@index{cabbage,parent={vegetable}} + +@index{minerals} +@index{quartz,parent={minerals}} +@index{corundum,parent={minerals}} +@index{amber,parent={minerals}} +@index{gypsum,parent={minerals}} + +@index{aardvark} +@index{bard} +@index{buzz} + +@index{item} +@index{subitem,parent={item}} +@index{subsubitem,parent={subitem}} +\end{verbatim} +and suppose the document contains: +\begin{verbatim} +\documentclass{article} + +\usepackage[record,style=indexgroup]{glossaries-extra} + +\GlsXtrLoadResources[src={entries.bib}] + +\begin{document} +\gls{duck}. +\gls{quartz}, \gls{corundum}, \gls{amber}. +\gls{aardvark}, \gls{bard}, \gls{buzz}. +\gls{vegetable}, \gls{cabbage}. +\gls{subsubitem}. + +\printunsrtglossaries +\end{document} +\end{verbatim} +Although the \texttt{duck} entry has siblings in the +\filefmt{entries.bib} file, none of them have been recorded +(indexed) in the document, nor has the parent \texttt{birds} entry. + +This document hasn't used \csopt{flatten-lonely}, so the default +\csopt[false]{flatten-lonely} is assumed. This results in the +hierarchical structure: +\begin{description}\setlength\itemsep{0pt}% +\item[A] \null +\item[aardvark] 1 +\item[B] \null +\item[bard] 1 +\item[birds] \mbox{} + \begin{description}\setlength\itemsep{0pt}% + \item[duck] 1 + \end{description} +\item[buzz] 1 +\item[I] \null +\item[item] \mbox{} + \begin{description}\setlength\itemsep{0pt}% + \item[subitem] \mbox{} + \begin{description}\setlength\itemsep{0pt}% + \item[subsubitem] 1 + \end{description} + \end{description} +\item[M] \null +\item[minerals] \mbox{} + \begin{description}\setlength\itemsep{0pt}% + \item[amber] 1 + \item[corundum] 1 + \item[quartz] 1 + \end{description} +\item[V] \null +\item[vegetable] 1 + \begin{description}\setlength\itemsep{0pt}% + \item[cabbage] 1 + \end{description} +\end{description} +(The \qt{1} in the above indicates the page number.) +There are some entries here that look a little odd: \texttt{duck}, +\texttt{cabbage} and \texttt{subsubitem}. In each case they are a +lone child entry. It would look better if they could be compressed, +but I don't want to use the \optref{flatten} option, as I still want +to keep the mineral hierarchy. + +If I now add \csopt[postsort]{flatten-lonely}: +\begin{verbatim} +\GlsXtrLoadResources[src={entries.bib},flatten-lonely=postsort] +\end{verbatim} +the hierarchy becomes: +\begin{description}\setlength\itemsep{0pt}% +\item[A] \null +\item[aardvark] 1 +\item[B] \null +\item[bard] 1 +\item[birds, duck] 1 +\item[buzz] 1 +\item[I] \null +\item[item, subitem, subsubitem] 1 +\item[M] \null +\item[minerals] \mbox{} + \begin{description}\setlength\itemsep{0pt}% + \item[amber] 1 + \item[corundum] 1 + \item[quartz] 1 + \end{description} +\item[V] \null +\item[vegetable] 1 + \begin{description}\setlength\itemsep{0pt}% + \item[cabbage] 1 + \end{description} +\end{description} +The \field{name} field of the \texttt{duck} entry has been +set to +\begin{verbatim} +name={\bibglsflattenedchildpostsort{birds}{duck}} +\end{verbatim} +the \field{text} field has been set to +\begin{verbatim} +text={duck} +\end{verbatim} +the \field{group} field is copied over from the parent entry (\qt{B}), +and the \field{parent} field has been adjusted, moving \texttt{duck} +up one hierarchical level. +Finally, the former parent \texttt{birds} entry has been removed (the default +\optref[only unrecorded parents]{flatten-lonely-rule} is in effect). + +The default definition of \csref{bibglsflattenedchildpostsort} +formats its arguments so that they are separated by a comma and +space (\qt{birds, duck}). If the \field{text} field had been set +in the original \atentryref{index} definition of \text{duck}, it +wouldn't have been altered. This adjustment ensures that in the +document \verb|\gls{duck}| still produces \qt{duck} rather than +\qt{birds, duck}. +(If the child and parent \field{name} fields are identical, +the terms are considered homographs. See below for further details.) + +The \texttt{subsubitem} entry has also been adjusted. This was done +in a multi-stage process, starting with sub-items and then moving down +the hierarchical levels: +\begin{itemize} +\item The \texttt{subitem} entry was adjusted, moving it from a +sub-entry to a top-level entry. The \field{name} field was then +modified to +\begin{verbatim} +name={\bibglsflattenedchildpostsort{item}{subitem}} +\end{verbatim} +This now means that the \texttt{subsubitem} entry is now a sub-entry +(rather than a sub-sub-entry). The \texttt{subitem} entry now has no +parent, but at this stage the \texttt{subsubitem} entry still has +\texttt{subitem} as its parent. +\item The \texttt{subsubitem} entry is then adjusted moving from a +sub-entry to a top-level entry. The \field{name} field was then +modified to +\begin{verbatim} +name= +{% + \bibglsflattenedchildpostsort + {% + % name from former parent + \bibglsflattenedchildpostsort{item}{subitem}% + }% + {subsubitem}% original name +} +\end{verbatim} +The first argument of \csref{bibglsflattenedchildpostsort} is +obtained from the \field{name} field of the entry's former parent +(which is removed from the child's set of ancestors). This field +value was changed in the previous step, and the change is +reflected here. + +This means that the name for \texttt{subitem} will be displayed as +\qt{item, subitem} and the name for \texttt{subsubitem} will be +displayed as \qt{item, subitem, subsubitem}. + +\item The parent entries \texttt{item} and \texttt{subitem} +are removed from the selection as they have no location lists. +\end{itemize} + +Note that the \texttt{cabbage} sub-entry hasn't been adjusted. It +doesn't have any siblings but its parent entry (\texttt{vegetable}) +has a location list so it can't be discarded. +If I change the rule: +\begin{verbatim} +\GlsXtrLoadResources[src={entries.bib}, + flatten-lonely-rule=discard unrecorded, + flatten-lonely=postsort] +\end{verbatim} +then this will move the \texttt{cabbage} entry up a level but the +original parent entry \texttt{vegetable} will remain: +\begin{description}\setlength\itemsep{0pt}% +\item[A] \null +\item[aardvark] 1 +\item[B] \null +\item[bard] 1 +\item[birds, duck] 1 +\item[buzz] 1 +\item[I] \null +\item[item, subitem, subsubitem] 1 +\item[M] \null +\item[minerals] \mbox{} + \begin{description}\setlength\itemsep{0pt}% + \item[amber] 1 + \item[corundum] 1 + \item[quartz] 1 + \end{description} +\item[V] \null +\item[vegetable] 1 +\item[vegetable, cabbage] 1 +\end{description} + +Remember that \csopt[postsort]{flatten-lonely} performs the +adjustment after sorting. This means that the entries are still in +the same relative location that they were in with the original +\csopt[false]{flatten-lonely} setting. For example, \texttt{duck} +remains in the B letter group before \qt{buzz}. + +With \csopt[presort]{flatten-lonely} the adjustments are made before +the sorting is performed. For example, using: +\begin{verbatim} +\GlsXtrLoadResources[src={entries.bib}, + flatten-lonely-rule=discard unrecorded, + flatten-lonely=presort] +\end{verbatim} +the hierarchical order is now: +\begin{description}\setlength\itemsep{0pt}% +\item[A] \null +\item[aardvark] 1 +\item[B] \null +\item[bard] 1 +\item[buzz] 1 +\item[C] \null +\item[cabbage] 1 +\item[D] \null +\item[duck] 1 +\item[M] \null +\item[minerals] \mbox{} + \begin{description}\setlength\itemsep{0pt}% + \item[amber] 1 + \item[corundum] 1 + \item[quartz] 1 + \end{description} +\item[S] \null +\item[subsubitem] 1 +\item[V] \null +\item[vegetable] 1 +\end{description} +This method uses a different format for the modified \field{name} +field. For example, the \texttt{duck} entry now has: +\begin{verbatim} +name={\bibglsflattenedchildpresort{duck}{birds}} +\end{verbatim} +The default definition of \csref{bibglsflattenedchildpresort} simply +does the first argument and ignores the second. The sorting is then +performed, but the interpreter recognises this command and can +deduce that the sort value for this entry should be \texttt{duck}, +so \qt{duck} now ends up in the D letter group. + +If you provide a definition of \cs{bibglsflattenedchildpresort} in +the \atentryref{preamble}, it will be picked up by the interpreter. +For example: +\begin{verbatim} +@preamble{"\providecommand{\bibglsflattenedchildpresort}[2]{#1 (#2)}"} +\end{verbatim} + +Note that the \field{text} field is only changed if not already set. +This option may have unpredictable results for abbreviations as the +\field{name} field (and sometimes the \field{text} field) is +typically set by the abbreviation style. Remember that +if the parent entry doesn't have a location list and the rule isn't +set to \optfmt{no discard} then the parent entry will be discarded +after all relevant entries and their dependencies have been +selected, so any cross-references within the parent entry (such as +\cs{gls} occurring in the description) may end up being selected +even if they wouldn't be selected if the parent entry didn't exist. + +With both \optfmt{presort} and \optfmt{postsort}, +if the parent \field{name} is the same as the child's \field{name} +then the child is considered a homograph and +the child's name is set to +\begin{alltt} +\csref{bibglsflattenedhomograph}\margm{name}\margm{parent label} +\end{alltt} +instead of the corresponding \csfmt{bibglsflattenedchild...sort}. +This defaults to just \meta{name}. + + +\subsection{\csoptnv{flatten-lonely-rule}\csopteqval{value}} +\labelopt{flatten-lonely-rule} + +This option governs the rule used by \csopt{flatten-lonely} to +determine which sub-entries (that have no siblings) to adjust and +which parents to remove. The value may be one of the following: +\begin{description} +\item[\optfmt{only unrecorded parents}] Only the sub-entries +that have a parent without a location list will be altered. +The parent entry will be removed from the selection. +This value is the default setting. +\item[\optfmt{discard unrecorded}] This setting will adjust all +sub-entries that have no siblings regardless of whether or not the +parent has a location list. +Only the parent entries that don't have a location list will be +removed from the selection. +\item[\optfmt{no discard}] This setting will adjust all +sub-entries that have no siblings regardless of whether or not the +parent has a location list. No entries will be discarded, so parent +entries that don't have a location list will still appear in the +glossary. +\end{description} +In the above, the location list includes records and +cross-references obtained from the \field{see} or \field{seealso} +fields. See \optref{flatten-lonely} for further details. + +\section{Master Documents} +\label{sec:master} + +Suppose you have two documents \filefmt{mybook.tex} and +\filefmt{myarticle.tex} that share a common glossary that's shown +in \filefmt{mybook.pdf} but not in \filefmt{myarticle.pdf}. +Furthermore, you'd like to use \sty{hyperref} and be able to click +on a term in \filefmt{myarticle.pdf} and be taken to the relevant +page in \filefmt{mybook.pdf} where the term is listed in the +glossary. + +This can be achieved with the \catattr{targeturl} and +\catattr{targetname} category attributes. For example, without +\bibgls\ the file \filefmt{mybook.tex} might look like: +\begin{verbatim} +\documentclass{book} +\usepackage[colorlinks]{hyperref} +\usepackage{glossaries-extra} + +\makeglossaries + +\newglossaryentry{sample}{name={sample},description={an example}} + +\begin{document} +\chapter{Example} +\gls{sample}. + +\printglossaries +\end{document} +\end{verbatim} +The other document \filefmt{myarticle.tex} might look like: +\begin{verbatim} +\documentclass{article} +\usepackage[colorlinks]{hyperref} +\usepackage{glossaries-extra} + +\newignoredglossary*{external} +\glssetcategoryattribute{external}{targeturl}{mybook.pdf} +\glssetcategoryattribute{external}{targetname}{\glolinkprefix\glslabel} + +\newglossaryentry{sample}{type=external,category=external, + name={sample},description={an example}} + +\begin{document} +\gls{sample}. +\end{document} +\end{verbatim} +In this case the \optfmt{main} glossary isn't used, but the category +attributes allow a mixture of internal and external references, so +the \optfmt{main} glossary could be used for the internal +references. (In which case, \csfmt{makeglossaries} and +\csfmt{printglossaries} would need to be added back to +\filefmt{myarticle.tex}.) + +Note that both documents had to define the common terms. The above +documents can be rewritten to work with \bibgls. First a \ext{bib} +file needs to be created: +\begin{verbatim} +@entry{sample, + name={sample}, + description={an example} +} +\end{verbatim} +Assuming this file is called \filefmt{myentries.bib}, then +\filefmt{mybook.tex} can be changed to: +\begin{verbatim} +\documentclass{book} +\usepackage[colorlinks]{hyperref} +\usepackage[record]{glossaries-extra} + +\GlsXtrLoadResources[src={myentries}] + +\begin{document} +\chapter{Example} +\gls{sample}. + +\printunsrtglossaries +\end{document} +\end{verbatim} +and \filefmt{myarticle.tex} can be changed to: +\begin{verbatim} +\documentclass{article} +\usepackage[colorlinks]{hyperref} +\usepackage[record]{glossaries-extra} + +\newignoredglossary*{external} +\glssetcategoryattribute{external}{targeturl}{mybook.pdf} +\glssetcategoryattribute{external}{targetname}{\glolinkprefix\glslabel} + +\GlsXtrLoadResources[ + src={myentries}, + sort=none, + type=external, + category=external] + +\begin{document} +\gls{sample}. +\end{document} +\end{verbatim} +Most of the options related to sorting and the glossary format are +unneeded here since the glossary isn't being displayed. This may be +sufficient for your needs, but it may be that the book has changed +various settings that have been written to \filefmt{mybook.glstex} +but aren't present in the \ext{bib} file (such as +\optref[uc]{short-case-change}). In this case, you could just remember to copy +over the settings from \filefmt{mybook.tex} to +\filefmt{myarticle.tex}, but +another possibility is to simply make \filefmt{myarticle.tex} input +\filefmt{mybook.glstex} instead of using \cs{GlsXtrLoadResources}. This +can work but it's not so convenient to set the label prefix, the +type and the category. The \optfmt{master} option allows this, but +it has limitations (see below), so in complex cases (in particular +different label prefixes combined with hierarchical entries or cross-references) you'll have to use +the method shown in the example code above. + +\subsection{\csoptnv{master}\csopteqval{name}} +\labelopt{master} + +This option will disable most of the options that relate to +parsing and processing data contained in \ext{bib} files +(since this option doesn't actually read any \ext{bib} files). + +The use of \optfmt{master} isn't always suitable. In particular +if any of the terms cross-reference each other, such as through +the \field{see} or \field{seealso} field or the \field{parent} field or +using commands like \cs{gls} in any of the other fields when +the labels have been assigned prefixes. In this +case you will need to use the method described in the example above. + +The \meta{name} is the name of the \ext{aux} file for the master +document without the extension (in this case, \filefmt{mybook}). It +needs to be relative to the document referencing it or an absolute +path using forward slashes as the directory divider. Remember that +if it's a relative path, the PDF files (\filefmt{mybook.pdf} and +\filefmt{myarticle.pdf}) will also need to be located in the same +relative position. + +When \bibgls\ detects the \csopt{master} option, it won't search for +entries in any \ext{bib} files (for that particular resource set) +but will create a \ext{glstex} file that inputs the master +document's +\ext{glstex} files, but it will additionally temporarily +adjust the internal commands used to define entries so that +the prefix given by \optref{label-prefix}, the glossary type and the +category type are all automatically inserted. If the \optref{type} +or \optref{category} options haven't been used, the corresponding +value will default to \optfmt{master}. The \catattr{targeturl} +and \catattr{targetname} category attributes will automatically be +set, and the glossary type will be provided using +\cs{provideignoredglossary*}\margm{type}. + +The above \filefmt{myarticle.tex} can be changed to: +\begin{verbatim} +\documentclass{article} +\usepackage[colorlinks]{hyperref} +\usepackage[record]{glossaries-extra} + +\GlsXtrLoadResources[ + label-prefix={book.}, + master={mybook}] + +\begin{document} +\gls{book.sample}. +\end{document} +\end{verbatim} + +There are some settings from the master document that you +still need to repeat in the other document. These include +the label prefixes set when the master document loaded +the resource files, and any settings in the master document +that relate to the master document's entries. + +For example, if the master document loaded a resource file +with \optref[term.]{label-prefix} then you also need this +prefix when you reference the entries in the dependent document +in addition to the \optfmt{label-prefix} for the dependent document. +Suppose \filefmt{mybook.tex} loads the resources using +\begin{verbatim} +\GlsXtrLoadResources[src={myentries},label-prefix={term.}] +\end{verbatim} +and \filefmt{myarticle.tex} loads the resources using: +\begin{verbatim} +\GlsXtrLoadResources[ + label-prefix={book.}, + master={mybook}] +\end{verbatim} +Then the entries referenced in \filefmt{myarticle.tex} need +to use the prefix \optfmt{book.term.}\ as in: +\begin{verbatim} +This is a \gls{book.term.sample} term. +\end{verbatim} + +Remember that the category labels will need adjusting to reflect the +change in category label in the dependent document. + +For example, if \filefmt{mybook.tex} included: +\begin{verbatim} +\setabbreviationstyle{long-short-sc} +\end{verbatim} +then \filefmt{myarticle.tex} will need: +\begin{verbatim} +\setabbreviationstyle[master]{long-short-sc} +\end{verbatim} +(change \optfmt{master} to \meta{value} if you have used +\optref[\meta{value}]{category}). You can, of course, choose +a different abbreviation style for the dependent document, +but the category in the optional argument needs to be correct. + +\subsection{\csoptnv{master-resources}\csopteqval{list}} +\labelopt{master-resources} + +If the master document has multiple resource files +then by default all that document's +\ext{glstex} files will be input. If you don't want them all +you can use \optfmt{master-resources} to specify +only those files that should be included. The value \meta{list} is +a comma-separated list of names, where each name corresponds +to the final argument of \csref{glsxtrresourcefile}. +Remember that \cs{GlsXtrLoadResources} is just a shortcut +for \cs{glsxtrresourcefile} that bases the name on \cs{jobname}. +(Note that, as with the argument of \cs{glsxtrresourcefile}, +the \ext{glstex} extension should not be included.) The file +\primaryresourcefmt\ is considered the primary +resource file and the files \suppresourcefmt{\meta{n}} +(starting with \meta{n} equal to 1) are considered the supplementary resource files. + +For example, to just select the first and third of the +supplementary resource files (omitting the primary +\filefmt{mybook.glstex}): +\begin{verbatim} +\GlsXtrLoadResources[ + master={mybook}, + master-resources={mybook-1,mybook-3} +] +\end{verbatim} + +\section{Field and Label Options} +\label{sec:labelopts} + +\subsection{\csoptnv{ignore-fields}\csopteqval{list}} +\labelopt{ignore-fields} + +The \csopt{ignore-fields} key indicates that you want \bibgls\ to +skip the fields listed in the supplied comma-separated \meta{list} of field +labels. Remember that unrecognised fields will always be skipped. + +For example, suppose my \ext{bib} file contains +\begin{verbatim} +@abbreviation{html, + short ="html", + long = {hypertext markup language}, + description={a markup language for creating web pages}, + seealso={xml} +} +\end{verbatim} +but I want to use the \abbrstyle{short-long} style and I don't want +the cross-referenced term, then I can use +\csopt[seealso,description]{ignore-fields}. + +Note that \csopt[parent]{ignore-fields} removes the \field{parent} +before determining the dependency lists. This means that +\optref[recorded and deps]{selection} and +\optref[recorded and ancestors]{selection} won't pick up the +label in the \field{parent} field. + +If you want to maintain the dependency and ancestor relationship but +omit the \field{parent} field when writing the entries to the +\ext{glstex} file, you need to use \optref{flatten} instead. + +\subsection{\csoptnv{category}\csopteqval{value}} +\labelopt{category} + +The selected entries may all have their \field{category} field +changed before writing their definitions to the \ext{glstex} file. +The \meta{value} may be: +\begin{itemize} +\item \optfmt{same as entry}: set the +\field{category} to the \ext{bib} entry type used to define it +(without the leading \texttt{@}); +\item \optfmt{same as type}: set the \field{category} to the same +value as the \field{type} field (if that field has been provided +either in the \ext{bib} file or through the \optref{type} option); +\item \meta{label}: the \field{category} is set to +\meta{label} (which mustn't contain any special characters). +\end{itemize} +This will override any +\field{category} fields supplied in the \ext{bib} file. + +For example, if the \ext{bib} file contains: +\begin{verbatim} +@entry{bird, + name={bird}, + description = {feathered animal} +} + +@index{duck} + +@index{goose,plural="geese"} + +@dualentry{dog, + name={dog}, + description={chien} +} +\end{verbatim} +then if the document contains +\begin{verbatim} +\GlsXtrLoadResources[category={same as entry},src={entries}] +\end{verbatim} +this will set the \field{category} of the \texttt{bird} field to +\optfmt{entry} (since it was defined with \cs{entry}), the \field{category} of the \texttt{duck} and +\texttt{goose} entries to \optfmt{index} (since they were defined +with \atentry{index}), and the \field{category} of the \texttt{dog} +entry to \optfmt{dualentry} (since it was +defined with \atentry{dualentry}). Note that the dual entry +\texttt{dual.dog} doesn't have the category set, since that's +governed by \optref{dual-category} instead. + +If, instead, the document contains +\begin{verbatim} +\GlsXtrLoadResources[category={animals},src={entries}] +\end{verbatim} +then the \field{category} of all the primary selected entries will +be set to \optfmt{animals}. Again the dual entry \texttt{dual.dog} +doesn't have the \field{category} set. + +Note that the categories may be overridden by the commands, +such as \csref{bibglsnewindex}, that are used to actually define the +entries. + +For example, if the document contains +\begin{verbatim} +\newcommand{\bibglsnewdualentry}[4]{% + \longnewglossaryentry*{#1}{name={#3},#2,category={dual}}{#4}% +} + +\GlsXtrLoadResources[category={animals},src={entries}] +\end{verbatim} +then both the \texttt{dog} and \texttt{dual.dog} entries will +have their \field{category} field set to \optfmt{dual} since the +new definition of \cs{bibglsnewdualentry} has overridden +the \csopt[animals]{category} option. + +\subsection{\csoptnv{type}\csopteqval{value}} +\labelopt{type} + +The \meta{value} may be \optfmt{same as entry} or a glossary label. +This is similar to the \optref{category} option except that +it sets the \field{type} field. As with the \csopt{category} option, +\csopt[same as entry]{type} indicates that the entry +type should be used. There is no \meta{value} analogous to +\csopt[same as type]{category}. + +Make sure that the glossary type has already been defined. + +Note that this setting only changes the \field{type} field for +primary entries. Use \optref{dual-type} for dual entries. + +For example: +\begin{verbatim} +\usepackage[record,symbols]{glossaries-extra} + +\GlsXtrLoadResources[src={entries-symbols},type=symbols] +\end{verbatim} + +Remember that you can use the starred version of \cs{newglossary} +if you don't want to worry about the extensions needed by +\app{makeindex} or \app{xindy}. For example: +\begin{verbatim} +\usepackage[record,nomain]{glossaries-extra} + +\newglossary*{dictionary}{Dictionary} + +\GlsXtrLoadResources[src={entries-symbols},type=dictionary] +\end{verbatim} +(The \styopt{nomain} option was added to suppress the +creation of the default \texttt{main} glossary.) + +Alternatively you can use \cs{newignoredglossary} if you don't +want the glossary picked up by \cs{printunsrtglossaries}. + + +\subsection{\csoptnv{label-prefix}\csopteqval{tag}} +\labelopt{label\dhyphen prefix} + +The \csopt{label-prefix} option prepends \meta{tag} to each +entry's label. This \meta{tag} will also be inserted in front of any +cross-references, unless they start with \idprefix{dual} or +\idprefix{ext\meta{n}} (where \meta{n} is an integer). + +For example, if the \ext{bib} file contains +\begin{verbatim} +@entry{bird, + name={bird}, + description = {feathered animal, such as a \gls{duck} or \gls {goose}} +} + +@entry{waterfowl, + name={waterfowl}, + description={Any \gls{bird} that lives in or about water}, + see={[see also]{duck,goose}} +} + +@index{duck} + +@index{goose,plural="geese"} +\end{verbatim} +Then if this \ext{bib} file is loaded with \csopt[gls.]{label-prefix} +it's as though the entries had been defined as: +\begin{verbatim} +@entry{gls.bird, + name={bird}, + description = {feathered animal, such as a \gls{gls.duck} or +\gls{gls.goose}} +} + +@entry{gls.waterfowl, + name={waterfowl}, + description={Any \gls{gls.bird} that lives in or about water}, + see={[see also]{gls.duck,gls.goose}} +} + +@index{gls.duck,name={duck}} + +@index{gls.goose,name={goose},plural="geese"} +\end{verbatim} + +Remember to use this prefix when you reference the terms in the +document with commands like \cs{gls}. + +\subsection{\csoptnv{ext-prefixes}\csopteqval{list}} +\labelopt{ext-prefixes} + +Any cross-references in the \ext{bib} file that start with +\idprefix{ext\meta{n}} (where \meta{n} is a positive integer) will be +substituted with the \meta{n}th tag listed in the comma-separated +\meta{list}. If there aren't that many items in the list, the +\idprefix{ext\meta{n}} will simply be removed. The default setting is +an empty list, which will strip all \idprefix{ext\meta{n}} prefixes. + +For example, suppose the file \filefmt{entries-terms.bib} contains: +\begin{verbatim} +@entry{set, + name={set}, + description={collection of values, denoted \gls{ext1.set}} +} +\end{verbatim} +and the file \filefmt{entries-symbols.bib} contains: +\begin{verbatim} +@symbol{set, + name={\ensuremath{\mathcal{S}}}, + description={a \gls{ext1.set}} +} +\end{verbatim} + +These files both contain an entry with the label \texttt{set} +but the description includes \verb|\gls{ext1.set}| which is +referencing the entry from the other file. These +two files can be loaded without conflict using: +\begin{verbatim} +\usepackage[record,symbols]{glossaries-extra} + +\GlsXtrLoadResources[src={entries-terms}, + label-prefix={gls.}, + ext-prefixes={sym.} +] + +\GlsXtrLoadResources[src={entries-symbols}, + type=symbols, + label-prefix={sym.}, + ext-prefixes={gls.} +] +\end{verbatim} + +Now the \texttt{set} entry from \filefmt{entries-terms.bib} +will be defined with the label \texttt{gls.set} and the +description will be +\begin{verbatim} +collection of values, denoted \gls{sym.set} +\end{verbatim} +The \texttt{set} entry +from \filefmt{entries-symbols.bib} will be defined with the label +\texttt{sym.set} and the description will be +\begin{verbatim} +a \gls{gls.set} +\end{verbatim} + +Note that in this case the \ext{bib} files have to be loaded +as two separate resources. They can't be combined into a +single \optref{src} list as the labels aren't unique. + +If you want to allow the flexibility to choose between +loading them together or separately, you'll have to give them +unique labels. For example, \filefmt{entries-terms.bib} could +contain: +\begin{verbatim} +@entry{set, + name={set}, + description={collection of values, denoted \gls{ext1.S}} +} +\end{verbatim} +and \filefmt{entries-symbols.bib} could contain: +\begin{verbatim} +@symbol{S, + name={\ensuremath{\mathcal{S}}}, + description={a \gls{ext1.set}} +} +\end{verbatim} +Now they can be combined with: +\begin{verbatim} +\GlsXtrLoadResources[src={entries-terms,entries-symbols}] +\end{verbatim} +which will simply strip the \idprefixfmt{ext1} prefix from the +cross-references. Alternatively: +\begin{verbatim} +\GlsXtrLoadResources[src={entries-terms,entries-symbols}, + label-prefix={gls.}, + ext-prefixes={gls.} +] +\end{verbatim} +which will insert the supplied \optref{label-prefix} at the +start of the labels in the entry definitions and will replace +the \idprefix{ext1} prefix with \idprefixfmt{gls} in the +cross-references. + +\subsection{\csoptnv{short-case-change}\csopteqval{value}} +\labelopt{short-case-change} + +The value of the \field{short} field may be automatically converted +to upper or lower case. This option may take one of the following +values: +\begin{itemize} +\item \optfmt{none}: don't apply any case-changing (default); +\item \optfmt{lc}: convert to lower case; +\item \optfmt{uc}: convert to upper case; +\item \optfmt{lc-cs}: convert to lower case using +\cs{MakeTextLowercase}; +\item \optfmt{uc-cs}: convert to upper case using +\cs{MakeTextUppercase}. +\end{itemize} + +For example, if the \ext{bib} file contains +\begin{verbatim} +@abbreviation{html, + short = "html", + long = "hypertext markup language" +} +\end{verbatim} +then \csopt[uc]{short-case-change} would convert the value of the +\field{short} field into +\begin{verbatim} +HTML +\end{verbatim} +whereas \csopt[uc-cs]{short-case-change} would convert it to +\begin{verbatim} +\MakeTextUppercase{html} +\end{verbatim} +In the case of \csopt[uc]{short-case-change} and \csopt[lc]{short-case-change} +only tokens that are recognised as characters will be converted. +For example, suppose I have a slightly more eccentric definition: +\begin{verbatim} +@abbreviation{html, + short = "ht\emph{ml}", + long = "hypertext markup language" +} +\end{verbatim} +then \csopt[uc]{short-case-change} would convert the value of the +\field{short} field into: +\begin{verbatim} +HT\emph{ML} +\end{verbatim} +Note that \cs{emph} isn't modified as it's recognised as a command. +There's no attempt at interpreting the contents at this point (but +the value may later be interpreted during sorting). + +For example, suppose an abbreviation is defined using: +\begin{verbatim} +short = "z\ae\oe", +\end{verbatim} +then with \csopt[uc]{short-case-change}, this would be converted to +\begin{verbatim} +Z\ae\oe +\end{verbatim} +since the interpreter isn't being used at this stage. If the +interpreter is later used during sorting, the sort value will be set to +\texttt{Z\ae\oe}. + +However, with \csopt[uc-cs]{short-case-change}, the \field{short} +value would be converted to +\begin{verbatim} +\MakeTextUppercase{z\ae\oe} +\end{verbatim} +If the interpreter is used during sorting, the sort value will be set to +\texttt{Z\AE\OE}. + +You can use \cs{NoCaseChange}\margm{text} to prevent the given \meta{text} +from having the case changed. For example, if the \field{short} +field is defined as +\begin{verbatim} +short = {a\NoCaseChange{bc}d} +\end{verbatim} +then with \csopt[uc]{short-case-change}, this would be converted to +\begin{verbatim} +A\NoCaseChange{bc}D +\end{verbatim} +(This command is provided by \sty{textcase}, which is automatically +loaded by \sty{glossaries}.) + +If you have a command that takes a label or identifier as an argument then it's +best to hide the label in a custom command. For example, if the +\field{short} field in the \ext{bib} definition is defined as: +\begin{verbatim} + short = "ht\textcolor{red}{ml}", +\end{verbatim} +then with \csopt[uc]{short-case-change} this would end up as: +\begin{verbatim} +HT\textcolor{RED}{ML} +\end{verbatim} +which is incorrect. Instead, provide a command that hides the label +(such as the \csfmt{strong} example described on page~\pageref{cs.strong}). + +See \optref{dual-short-case-change} to adjust the \field{dualplural} +field. + +\subsection{\csoptnv{group}\csopteqval{value}} +\labelopt{group} + +This option may only be used with the \argref{group} switch. +This will set the \field{group} field to \meta{value} unless +\meta{value} is \optfmt{auto}, in which case the value is +set automatically during the sorting. +For example: +\begin{verbatim} +\GlsXtrLoadResources[sort=integer,group={Constants}, + src={entries-constants}% data in entries-constants.bib +] +\GlsXtrLoadResources[sort=letter-case,group={Variables}, + src={entries-variables}% data in entries-variables.bib +] +\end{verbatim} +If the \field{type} field hasn't been set in the \ext{bib} files, +these entries will be added to the same glossary, but will +be grouped according to each instance of \cs{GlsXtrLoadResources}, +with the provided group label. +The default behaviour is \csopt[auto]{group}. + +\subsection{\csoptnv{save-child-count}\csopteqval{boolean}} +\labelopt{save-child-count} + +This is a boolean option. The default setting is +\csopt[false]{save-child-count}. +If \csopt[true]{save\dhyphen child\dhyphen count}, +each entry will be assigned a field called \texttt{childcount} with +the value equal to the number of child entries that have been +selected. + +The assignment is done using \cs{GlsXtrSetField} so there's +no associated key. +For example, suppose \filefmt{entries.bib} contains: +\begin{verbatim} +@index{birds} +@index{duck,parent={birds}} +@index{goose,plural={geese},parent={birds}} +@index{swan,parent={birds}} + +@index{minerals} +@index{quartz,parent={minerals}} +@index{corundum,parent={minerals}} +@index{amber,parent={minerals}} +@index{gypsum,parent={minerals}} +@index{gold,parent={minerals}} +\end{verbatim} +and the document contains: +\begin{verbatim} +\documentclass{article} + +\usepackage[record,style=indexgroup]{glossaries-extra} + +\GlsXtrLoadResources[src={entries},save-child-count] + +\begin{document} +\gls{duck} and \gls{goose}. +\gls{quartz}, \gls{corundum}, \gls{amber}. + +\printunsrtglossaries +\end{document} +\end{verbatim} +Then the \ext{glstex} file will contain: +\begin{verbatim} +\GlsXtrSetField{birds}{childcount}{2} +\GlsXtrSetField{duck}{childcount}{0} +\GlsXtrSetField{goose}{childcount}{0} +\GlsXtrSetField{minerals}{childcount}{3} +\GlsXtrSetField{amber}{childcount}{0} +\GlsXtrSetField{corundum}{childcount}{0} +\GlsXtrSetField{quartz}{childcount}{0} +\end{verbatim} +Note that although \texttt{birds} has three children defined in the +\ext{bib} file, only two have been selected, so the child count is +set to 2. Similarly the \texttt{minerals} entry has five children +defined in the \ext{bib} file, but only three have been selected, so +the child count is 3. + +The following uses the post-description hook to show the child count +in parentheses: +\begin{verbatim} +\GlsXtrLoadResources[src={entries},category=general,save-child-count] + +\renewcommand{\glsxtrpostdescgeneral}{% + \glsxtrifhasfield{childcount}{\glscurrententrylabel} + { (child count: \glscurrentfieldvalue.)}% + {}% +} +\end{verbatim} +(\cs{glsxtrifhasfield} requires at least \sty{glossaries-extra} v1.19. +It's slightly more efficient that \cs{ifglshasfield} provided by +the base \sty{glossaries} package, and it doesn't complain if the +entry or field don't exist, but note that \cs{glsxtrifhasfield} +implicitly scopes its content. Use the starred version to omit the +grouping.) + +\section{Plurals} +\label{sec:plurals} + +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, mice), so a +simplistic approach of just doing \texttt{\cs{gls}\margm{label}[s]} +will sometimes produce inappropriate results, so the \sty{glossaries} +package provides a \field{plural} key with the corresponding command +\cs{glspl}. + +In some cases a plural may not make any sense (for example, if the +term is a verb or symbol), so the \field{plural} key is optional, but to +make life easier for languages where the majority of plurals can +simply be formed by appending a suffix to the singular, the +\sty{glossaries} package lets the \field{plural} field default +to the value of the \field{text} field with \cs{glspluralsuffix} +appended. This command is defined to be just the letter \qt{s}. +This means that the majority of terms in such languages don't need to have the +\field{plural} supplied as well, and you only need to use it for the +exceptions. + +For languages that don't have this general rule, the \field{plural} +field will always need to be supplied for nouns. + +There are other plural fields, such as \field{firstplural}, +\field{longplural} and \field{shortplural}. 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 \sty{glossaries} package follows +these rules: +\begin{itemize} +\item If \field{firstplural} is missing, then \cs{glspluralsuffix} +is appended to the \field{first} field, if that field has been +supplied. If the \field{first} field hasn't been supplied but the +\field{plural} field has been supplied, then the \field{firstplural} +field defaults to the \field{plural} field. If the \field{plural} +field hasn't been supplied, then both the \field{plural} and +\field{firstplural} fields default to the \field{text} field (or +\field{name}, if no \field{text} field) with \cs{glspluralsuffix} +appended. + +\item If the \field{longplural} field is missing, then +\cs{glspluralsuffix} is appended to the \field{long} field, if the +\field{long} field has been supplied. + +\item If the \field{shortplural} field is missing then, \emph{with +the base \sty{glossaries} acronym mechanism}, \cs{acrpluralsuffix} +is appended to the \field{short} field. + +\end{itemize} + +The last case is different with the \sty{glossaries-extra} extension +package. The \field{shortplural} field defaults to the \field{short} +field with \cs{abbrvpluralsuffix} appended \emph{unless overridden +by category attributes}. This suffix command is set by the +abbreviation styles. This means that every time an abbreviation +style is implemented, \cs{abbrvpluralsuffix} is redefined. Most +styles simply define this command as: +\begin{verbatim} +\renewcommand*{\abbrvpluralsuffix}{\glsxtrabbrvpluralsuffix} +\end{verbatim} +where \cs{glsxtrabbrvpluralsuffix} expands to \cs{glspluralsuffix}. +The \qt{sc} styles (such as \abbrstyle{long-short-sc}) use a different +definition: +\begin{verbatim} +\renewcommand*{\abbrvpluralsuffix}{\protect\glsxtrscsuffix} +\end{verbatim} +This allows the suffix to be reverted back to the upright font, +counter-acting the affect of the small-caps font. + +This means that if you want to change or strip the suffix used for +the plural short form, it's usually not sufficient to redefine +\cs{abbrvpluralsuffix}, as the change will be undone the next time +the style is applied. Instead, for a document-wide solution, you +need to redefine \cs{glsxtrabbrvpluralsuffix}. Alternatively you can +use the category attributes. + +There are two attributes that affect the short plural suffix +formation. The first is \catattr{aposplural} which uses the suffix +\begin{verbatim} +'\abbrvpluralsuffix +\end{verbatim} +That is, an apostrophe followed by \cs{abbrvpluralsuffix} is +appended. The second attribute is \catattr{noshortplural} which +suppresses the suffix and simply sets \field{shortplural} to the +same as \field{short}. + +With \bibgls, if you have some abbreviations where the plural should +have a suffix and some where the plural shouldn't have a suffix +(for example, the document has both English and French abbreviations) +then there are two approaches. + +The first approach is to use the category attributes. For example: +\begin{verbatim} +\glssetcategoryattribute{french}{noshortplural} +\end{verbatim} +Now just make sure all the French abbreviations are have their +\field{category} field set to \optfmt{french}: +\begin{verbatim} +\GlsXtrLoadResources[src={fr-abbrvs},category={french}] +\end{verbatim} + +The other approach is to use the options listed below. + +\subsection{\csoptnv{short-plural-suffix}\csopteqval{value}} +\labelopt{short-plural-suffix} + +Sets the plural suffix for the default \field{shortplural} to \meta{value}. If +this option is omitted or if +\csopt[use-default]{short\dhyphen plural-suffix}, then \bibgls\ will leave +it to \sty{glossaries-extra} to determine the appropriate default. +If the \meta{value} is omitted or empty, the suffix is set to empty. + +\subsection{\csoptnv{dual-short-plural-suffix}\csopteqval{value}} +\labelopt{dual-short-plural-suffix} + +Sets the plural suffix for the default \field{dualshortplural} field to +\meta{value}. If this option is omitted or if +\csopt[use-default]{dual-short-plural-suffix}, then \bibgls\ will leave it to +\sty{glossaries-extra} to determine the appropriate default. +If the \meta{value} is omitted or empty, the suffix is set to empty. + +\section{Location List Options} +\label{sec:locationopts} + +The \styopt{record} package option automatically adds two new keys: +\field{loclist} and \field{location}. These two fields are set by +\bibgls\ from the information supplied in the \ext{aux} file (unless +the option \optref[false]{save-locations} is used). The +\field{loclist} field has the syntax of an \sty{etoolbox} internal list +and includes every location (except for the discarded duplicates and +ignored formats). +Each item in the list is provided in the form +\begin{alltt} +\cs{glsseeformat}\oargm{tag}\margm{label list}\marg{} +\end{alltt} +for the cross-reference supplied by the \field{see} field, +\begin{alltt} +\cs{glsxtruseseealsoformat}\margm{label list} +\end{alltt} +for the cross-reference supplied by the \field{seealso} field, +and +\begin{alltt} +\cs{glsnoidxdisplayloc}\margm{prefix}\margm{counter}\margm{format}\margm{location} +\end{alltt} +for the locations. You can iterate through the \field{loclist} value +using one of \sty{etoolbox}'s internal list loops (either +by first fetching the list using \cs{glsfieldfetch} +or through \sty{glossaries-extra}'s \cs{glsxtrfielddolistloop} +or \cs{glsxtrfieldforlistloop} shortcuts). + +The \meta{format} is that supplied by the \gencsopt{gls}{format} key +when using commands like \cs{gls} or \cs{glsadd} (the encapsulator or encap in +\appfmt{makeindex} parlance). If omitted, +\gencsopt[glsnumberformat]{gls}{format} is assumed (unless this +default value is changed with \cs{GlsXtrSetDefaultNumberFormat}, +provided by \sty{glossaries-extra} v1.19+). + +Ranges can be explicitly formed using the parenthetical encap +syntax \glsopt[(]{format} and +\glsopt[)]{format} or \glsopt[(\meta{csname}]{format} and +\glsopt[)\meta{csname}]{format} (where \meta{csname} is the name of +a text-block command without the initial backslash) in the optional +argument of commands like \cs{gls} or \cs{glsadd}. These will always +form a range, regardless of \optref{min-loc-range}, and will be +encapsulated by \csref{bibglsrange}. (This command is not used with +ranges that are formed by collating consecutive locations.) + +Explicit ranges don't merge with neighbouring locations, but will +absorb any single locations within the range that don't conflict. +(Conflicts will be moved to the start of the explicit range.) +For example, if \verb|\gls{sample}| is used on page~1, +\verb|\gls[format=(]{sample}| is used on page~2, +\verb|\gls{sample}| is used on page~3, and +\verb|\gls[format=)]{sample}| is used on page~4, then the location +list will be 1, 2--4. The entry on page~3 is absorbed into the +explicit range, but the range can't be expanded to include page~1. +If the entry on page~3 had a different format to the explicit range, +for example \verb|\gls[format=textbf]{sample}| then it would cause a +warning and be moved before the start of the range so that the +location list would then be 1, \textbf{3}, 2--4. + +The special format \gencsopt[glsignore]{glsadd}{format} is provided +by the \styfmt{glossaries} package for cases where the location +should be ignored. (The command \cs{glsignore} simply ignores its +argument.) This works reasonably well if an entry only has the one +location, but if the entry happens to be indexed again, it can lead +to an odd empty gap in the location list with a spurious comma. If +\bibgls\ encounters a record with this special format, the entry +will be selected but the record will be discarded. + +This means that the location list will be empty if the entry was +only indexed with \optfmt{glsignore}, but if the entry was also +indexed with another format then the location list won't include the +ignored record. (This format is used by \cs{glsaddallunused} but +remember that iterative commands like this don't work with \bibgls. +Instead, just use \optref[all]{selection} to select all entries.) + +For example, suppose you only want main matter locations in the +number list, but you want entries that only appear in the back matter +to still appear in the glossary (without a location list), then you could do: +\begin{verbatim} +\backmatter +\GlsXtrSetDefaultNumberFormat{glsignore} +\end{verbatim} +(This command requires v1.19 of \sty{glossaries-extra}.) If you also +want to drop front matter locations as well: +\begin{verbatim} +\frontmatter +\GlsXtrSetDefaultNumberFormat{glsignore} +... +\mainmatter +\GlsXtrSetDefaultNumberFormat{glsnumberformat} +... +\backmatter +\GlsXtrSetDefaultNumberFormat{glsignore} +\end{verbatim} + +Note that explicit range formations aren't discarded, so if +\optfmt{glsignore} is used in a range, such as +\begin{verbatim} +\glsadd[format=(glsignore]{sample} +... +\glsadd[format=)glsignore]{sample} +\end{verbatim} +then the range will be included in the location list (encapsulated +with \cs{glsignore}), but this case would be a rather odd use of +this special format and is not recommended. + +The locations are always listed in the order in which they were indexed, +(except for the cross-reference which may be placed at the start or +end of the list or omitted). +This is different to \app{xindy} and \app{makeindex} where you can +specify the ordering (such as lower case Roman first, then digits, +etc), but unlike those applications, \bibgls\ allows any location, +although it may not be able to work out an integer representation. +(With \app{xindy}, you can define new location formats, but you need +to remember to add the appropriate code to the custom module.) + +It's possible to define a custom glossary style where +\cs{glossentry} (and the child form \cs{subglossentry}) ignore the +final argument (which will be the \field{location} field) +and instead parse the \field{loclist} field and re-order the +locations or process them in some other way. Remember that you can also use \cs{glsnoidxloclist} +provided by \sty{glossaries}. For example: +\begin{verbatim} +\glsfieldfetch{gls.sample}{loclist}{\loclist}% fetch location list +\glsnoidxloclist{\loclist}% iterate over locations +\end{verbatim} +This uses \cs{glsnoidxloclisthandler} as the list's handler +macro, which simply displays each location separated by \cs{delimN}. +(See also +\href{http://www.dickimaw-books.com/latex/admin/html/foreachtips.shtml}{Iteration +Tips and Tricks}.) + +Each location is listed in the \ext{aux} file in the form: +\begin{alltt} +\cs{glsxtr@record}\margm{label}\margm{prefix}\margm{counter}\margm{format}\margm{location} +\end{alltt} +Exact duplicates are discarded. For example, if \texttt{cat} +is indexed twice on page 1: +\begin{verbatim} +\glsxtr@record{cat}{}{page}{glsnumberformat}{1} +\glsxtr@record{cat}{}{page}{glsnumberformat}{1} +\end{verbatim} +then the second record is discarded. Only the first record is added +to the location list. + +Partial duplicates, where all arguments match except for +\meta{format}, may be discarded depending on the value +of \meta{format}. For example, if page~1 of the document +uses \verb|\gls{cat}| and \verb|\gls[format=hyperbf]{cat}| +then the \ext{aux} file will contain: +\begin{verbatim} +\glsxtr@record{cat}{}{page}{glsnumberformat}{1} +\glsxtr@record{cat}{}{page}{hyperbf}{1} +\end{verbatim} +This is a partial record match. In this case, \bibgls\ +makes the following tests: +\begin{itemize} +\item If one of the formats includes a range formation, the +range takes precedence. + +\item If one of the formats is \texttt{glsnumberformat} (as in the +above example) or \texttt{glsignore}, that format will be skipped. +So in the above example, the second record will be added to the +location list, but not the first. (A message will only be written to +the transcript if the \longarg{debug} switch is used.) The default +\texttt{glsnumberformat} will take precedence over the ignored +format \texttt{glsignore}. + +\item If a mapping has been set with the \argref{map-format} +switch that mapping will be checked. +\item Otherwise the duplicate record will be discarded with a +warning. +\end{itemize} + +The \field{location} field is used to store the formatted location +list. The code for this list is generated by \bibgls\ based on the +information provided in the \ext{aux} file, the presence of the +\field{see} or \field{seealso} field and the various settings described in this +chapter. When you display the glossary using \cs{printunsrtglossary}, +if the \field{location} field is present it will be displayed +according to the glossary style (and other factors, such as whether the +\styopt{nonumberlist} option has been used, either as a package +option or supplied in the optional argument of \cs{printunsrtglossary}). +For more information on adjusting the formatting see the +\sty{glossaries} and \sty{glossaries-extra} user manuals. + +\subsection{\csoptnv{save-locations}\csopteqval{boolean}} +\labelopt{save-locations} + +By default, the locations will be processed and stored in the +\field{location} and \field{loclist} fields. However, if you don't +want the location lists (for example, you are using the +\styopt{nonumberlist} option or you are using \app{xindy} with a +custom location rule), then there's no need for \bibgls\ to process +the locations. To switch this function off, just use +\csopt[false]{save-locations}. Note that with this setting, if +you're not additionally using \app{makeindex} or \app{xindy}, then +the locations won't be available even if you don't have the +\styopt{nonumberlist} option set. + +\subsection{\csoptnv{min-loc-range}\csopteqval{value}} +\labelopt{min-loc-range} + +By default, three or more consecutive locations \meta{loc-1}, +\meta{loc-2}, \ldots, \meta{loc-n} are compressed into +the range \texttt{\meta{loc-1}\cs{delimR} \meta{loc-n}} (where +\cs{delimR} is provided by the \sty{glossaries} package). Otherwise +the locations are separated by \cs{delimN} (again provided by +\sty{glossaries}). As mentioned above, these aren't merged with +explicit range formations. + +You can change this with the \csopt{min-loc-range} setting where +\meta{value} is either \optfmt{none} (don't form ranges) or an +integer greater than one indicating how many consecutive locations should be +converted into a range. + +\bibgls\ determines if one location +\margm{prefix-2}\margm{counter-2}\margm{format-2}\margm{location-2} +is one unit more than another location +\margm{prefix-1}\margm{counter-1}\margm{format-1}\margm{location-1} +according to the following: +\begin{enumerate} +\item\label{itm:pre} If \meta{prefix-1} is not equal to \meta{prefix-2} or +\meta{counter-1} is not equal to \meta{counter-2} or \meta{format-1} +is not equal to \meta{format-2}, then the locations aren't +considered consecutive. +\item\label{itm:emptyloc} If either \meta{location-1} or \meta{location-2} are empty, +then the locations aren't considered consecutive. +\item\label{itm.csmatch} If both \meta{location-1} and \meta{location-2} match the +pattern (line break for clarity only)\footnote{The Java class \texttt{\csfmt{p}\marg{javaDigit}} +used in the regular expression will not only match the Western +Arabic digits 0,\ldots, 9 but also digits in other scripts. +Similarly the alphabetic classes will match alphabetic characters +outside the Basic Latin set.} +\begin{verbatim} +(.*?)(?:\\protect\s*)?(\\[\p{javaAlphabetic}@]+)\s*\{([\p{javaDigit} +\p{javaAlphabetic}]+)\} +\end{verbatim} +then: + \begin{itemize} + \item if the control sequence matched by group 2 isn't the same for + both locations, the locations aren't considered consecutive; + \item if the argument of the control sequence (group 3) is the same for + both locations, then the test is retried with \meta{location-1} +set to group 1 of the first pattern match and \meta{location-2} +set to group 1 of the second pattern match; + \item otherwise the test is retried with \meta{location-1} set to +group 3 of the first pattern match and \meta{location-2} set to +group 3 of the second pattern match. + \end{itemize} +\item\label{itm:decmatch} If both \meta{location-1} and \meta{location-2} match the +pattern +\begin{verbatim} +(.*?)([^\p{javaDigit}]?)(\p{javaDigit}+) +\end{verbatim} +then: + \begin{enumerate} + \item\label{itm:decgrp3eq} if group 3 of both pattern matches are +equal then: + \begin{enumerate} + \item\label{itm:decgrp3nz} if group 3 isn't zero, the locations +aren't considered consecutive; + \item if the separators (group 2) are different the test is +retried with \meta{location-1} set to the concatenation of the first +two groups \meta{group-1}\meta{group-2} of the first pattern match +and \meta{location-2} set to the concatenation of the first two groups +\meta{group-1}\meta{group-2} of the second pattern +match; + \item\label{itm:decgrp3eqsepeq} if the separators (group 2) are the same the test is +retried with \meta{location-1} set to the first +group \meta{group-1} of the first pattern match +and \meta{location-2} set to the first group +\meta{group-1} of the second pattern match. + \end{enumerate} + \item If \meta{group-1} of the first pattern match (of +\meta{location-1}) doesn't equal +\meta{group-1} of the second pattern match (of \meta{location-2}) +or \meta{group-2} of the first pattern match (of +\meta{location-1}) doesn't equal +\meta{group-2} of the second pattern match (of \meta{location-2}) +then the locations aren't considered consecutive; + \item\label{itm:decgrp3} If $0 < l_2 - l_1 \leq d $ +where $l_2$ is \meta{group 3} of the second pattern match, +$l_1$ is \meta{group 3} of the first pattern match and +$d$ is the value of \optfmt{max-loc-diff} then the locations +are consecutive otherwise they're not consecutive. + \end{enumerate} +\item\label{itm:rommatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{n} +where \meta{n} is a lower case Roman numeral, which is converted to +a decimal value and the test is performed in the same way as the +above \hyperref[itm:decmatch]{decimal test}. +\item\label{itm:Rommatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{n} +where \meta{n} is an upper case Roman numeral, which is converted to +a decimal value and the test is performed +in the same way as the above \hyperref[itm:decmatch]{decimal test}. +\item\label{itm:alphmatch} The next pattern matches for \meta{prefix}\meta{sep}\meta{c} +where \meta{c} is either a lower case letter from \texttt{a} to +\texttt{z} or an upper case letter from \texttt{A} to \texttt{Z}. +The character is converted to its code point and the test is +performed in the same way as the \hyperref[itm:decmatch]{decimal pattern} above. +\item\label{itm:nomatch} If none of the above, the locations aren't considered +consecutive. +\end{enumerate} + +Examples: +\begin{enumerate} +\item +\begin{verbatim} +\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{1} +\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{2} +\end{verbatim} +These records are consecutive. The prefix, counter and format are +identical (so the test passes step~\ref{itm:pre}), the locations match +the \hyperref[itm:decmatch]{decimal pattern} and the test in +step~\ref{itm:decgrp3} passes. + +\item +\begin{verbatim} +\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{1} +\glsxtr@record{gls.sample}{}{page}{textbf}{2} +\end{verbatim} +These records aren't consecutive since the formats are different. + +\item +\begin{verbatim} +\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{A.i} +\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{A.ii} +\end{verbatim} +These records are consecutive. The prefix, counter and format are +identical (so it passes step~\ref{itm:pre}). The locations match +the \hyperref[itm:rommatch]{lower case Roman numeral pattern}, where +\texttt{A} is considered a prefix and the dot is consider a +separator. The Roman numerals i and ii are converted to decimal and +the test is retried with the locations set to 1 and 2, respectively. +This now passes the decimal pattern test (step~\ref{itm:decgrp3}). + +\item +\begin{verbatim} +\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{i.A} +\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{ii.A} +\end{verbatim} +These records aren't consecutive. They match the +\hyperref[itm:alphmatch]{alpha pattern}. The first location is +considered to consist of the prefix \texttt{i}, the separator +\texttt{.} (dot) and the number given by the character code of A. +The second location is considered to consist of the prefix +\texttt{ii}, the separator \texttt{.} (dot) and the number +given by the character code of A. + +The test fails because the numbers are equal and the prefixes are +different. + +\item +\begin{verbatim} +\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{1.0} +\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{2.0} +\end{verbatim} +These records are consecutive. They match the \hyperref[itm:decmatch]{decimal +pattern}, and then step~\ref{itm:decgrp3eq} followed by +step~\ref{itm:decgrp3eqsepeq}. The \texttt{.0} part is discarded and +the test is retried with the first location set to 1 and the second +location set to 2. + +\item +\begin{verbatim} +\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{1.1} +\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{2.1} +\end{verbatim} +These records aren't consecutive as the test branches off into +step~\ref{itm:decgrp3nz}. + +\item +\begin{verbatim} +\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{\@alph{1}} +\glsxtr@record{gls.sample}{}{page}{glsnumberformat}{\@alph{2}} +\end{verbatim} +These records are consecutive. The locations match the +\hyperref[itm.csmatch]{control sequence pattern}. The control +sequences are the same, so the test is retried with the first +location set to 1 and the second location set to 2. +(Note that \csref{glsxtrresourcefile} changes the category code of +\texttt{@} to allow for internal commands in locations.) +\end{enumerate} + +\subsection{\csoptnv{max-loc-diff}\csopteqval{value}} +\labelopt{max-loc-diff} + +This setting is used to determine whether two locations are +considered consecutive. +The value must be an integer greater than or equal to 1. +(The default is \optfmt{1}.) + +For two locations, \meta{location-1} and \meta{location-2}, +that have numeric values $n_1$ and $n_2$ (and identical prefix, +counter and format), then the sequence \meta{location-1}, +\meta{location-2} is considered consecutive if +\[ +0 < n_2 - n_1 \leq \text{\meta{max-loc-diff}} +\] +The default value of 1 means that \meta{location-2} immediately +follows \meta{location-1} if $n_2 = n_1+1$. + +For example, if \meta{location-1} is \qt{B} and \meta{location-2} +is \qt{C}, then $n_1 = 66$ and $n_2 = 67$. Since $n_2 = 67 = 66+1= +n_1+1$ then \meta{location-2} immediately follows \meta{location-1}. + +This is used in the range formations within the location lists. +So, for example, the list \qt{1, 2, 3, 5, 7, 8, 10, 11, 12, 58, 59, +61} becomes +\qt{1--3, 5, 7, 8, 10--12, 58, 59, 61}. + +The automatically indexing of commands like \cs{gls} means that +the location lists can become long and ragged. You could +deal with this by switching off the automatic indexing and +only explicitly index pertinent use or you can adjust +the value of \optfmt{max-loc-diff} so that a range can be formed even +there are one or two gaps in it. +By default, any location ranges that have skipped gaps in this +manner will be followed by \csref{bibglspassim}. The default +definition of this command is obtained from the resource file. +For English, this is \verb*| passim| (space followed by \qt{passim}). + +So with the above set of locations, if \csopt[2]{max-loc-diff} then +the list becomes \qt{1--12 passim, 58--61 passim} which now highlights that +there are two blocks within the document related to that +term. + +\subsection{\csoptnv{suffixF}\csopteqval{value}} +\labelopt{suffixF} + +If set, a range consisting of two consecutive locations +\meta{loc-1} and \meta{loc-2} will be +displayed in the location list as \meta{loc-1}\meta{value}. + +Note that \csopt[\empty]{suffixF} sets the suffix to the +empty string. To remove the suffix formation use +\csopt[none]{suffixF}. + +The default is \csopt[none]{suffixF}. + +\subsection{\csoptnv{suffixFF}\csopteqval{value}} +\labelopt{suffixFF} + +If set, a range consisting of three or more consecutive locations +\meta{loc-1} and \meta{loc-2} will be +displayed in the location list as \meta{loc-1}\meta{value}. + +Note that \csopt[\empty]{suffixFF} sets the suffix to the +empty string. To remove the suffix formation use +\csopt[none]{suffixFF}. + +The default is \csopt[none]{suffixFF}. + +\subsection{\csoptnv{see}\csopteqval{value}} +\labelopt{see} + +If an entry has a \field{see} field, this can be placed before or +after the location list, or completely omitted (but the value will +still be available in the \field{see} field for use with +\cs{glsxtrusesee}). This option may take the following values: +\begin{itemize} +\item \optfmt{omit}: omit the see reference from the location +list. +\item \optfmt{before}: place the see reference before the location +list. +\item \optfmt{after}: place the see reference after the location +list (default). +\end{itemize} +The \meta{value} part is required. + +The separator between the location list and the cross-reference is +provided by \csref{bibglsseesep}. This separator is omitted if the +location list is empty. The cross-reference is written to the +\field{location} field using \cs{glsxtrusesee}\margm{label}. + +\subsection{\csoptnv{seealso}\csopteqval{value}} +\labelopt{seealso} + +This is like \optref{see} but governs the location of the cross-references +provided by the \field{seealso} field. You need at least v1.16 +of \sty{glossaries-extra} for this option. The values are the +same as for \optref{see} but the separator is given by +\csref{bibglsseealsosep}. The cross-reference is written to the +\field{location} field using \cs{glsxtruseseealso}\margm{label}. + +\subsection{\csoptnv{alias-loc}\csopteqval{value}} +\labelopt{alias-loc} + +If an entry has an \field{alias} field, the location list +may be retained or omitted or transferred to the target entry. +The \meta{value} may be one of: +\begin{itemize} +\item\optfmt{keep}: keep the location list; +\item\optfmt{transfer}: transfer the location list; +\item\optfmt{omit}: omit the location list. +\end{itemize} +The default setting is \csopt[transfer]{alias-loc}. +In all cases, the target entry will be added to the \field{see} +field of the entry with the \field{alias} field, unless it +already has a \field{see} field (in which case the \field{see} value +is left unchanged). + +Note that with \csopt[transfer]{alias-loc}, both the aliased +entry and the target entry must be in the same resource set. +(That is, both entries have been selected by the same instance of +\csref{glsxtrresourcefile}.) If you have \sty{glossaries-extra} version +1.12, you may need to redefine \cs{glsxtrsetaliasnoindex} to do +nothing if the location lists aren't showing correctly +with aliased entries. (This was corrected in version 1.13.) + +\subsection{\csoptnv{loc-prefix}\csopteqval{value}} +\labelopt{loc-prefix} + +The \csopt{loc-prefix} setting indicates that the location lists +should begin with \csref{bibglslocprefix}\margm{n}. The \meta{value} may +be one of the following: +\begin{itemize} +\item \optfmt{false}: don't insert \cs{bibglslocprefix}\margm{n} at the start +of the location lists (default). +\item \optfmt{\margm{prefix-1},\margm{prefix-2},\ldots,\margm{prefix-n}}: +insert \cs{bibglslocprefix}\margm{n} (where \meta{n} is the number of +locations in the list) at the start of each location list and the +definition of \cs{bibglslocprefix} will be appended to the glossary +preamble providing an \cs{ifcase} condition: +\begin{alltt} +\cs{providecommand}\marg{\cs{bibglslocprefix}}[1]\marg{\% + \cs{ifcase}\string#1 + \csfmt{or} \meta{prefix-1}\csref{bibglspostlocprefix} + \csfmt{or} \meta{prefix-2}\csfmt{bibglspostlocprefix} + \ldots + \csfmt{else} \meta{prefix-n}\csfmt{bibglspostlocprefix} + \csfmt{fi} +} +\end{alltt} + +\item \optfmt{list}: equivalent to \csopt[\cs{pagelistname} ]{loc-prefix}. +\item \optfmt{true}: equivalent to +\csopt[\csref{bibglspagename},\csref{bibglspagesname}]{loc-prefix}, +where the definitions of \cs{bibglspagename} and +\cs{bibglspagesname} are obtained from the \texttt{tag.page} and +\texttt{tag.pages} entries in \bibgls's \langxml. +This setting works best if the document's language matches the +language file. However, you can redefine these commands within +the document's language hooks or in the glossary preamble. +\end{itemize} + +If \meta{value} is omitted, \optfmt{true} is assumed. Take care not +to mix different values of \csopt{loc-prefix} for entries for the +same \csopt{type} setting. It's okay to mix \csopt[false]{loc-prefix} with +another value, but don't mix non-\optfmt{false} values. +See the description of \csref{bibglslocprefix} for +further details. + +For example: +\begin{verbatim} +\GlsXtrLoadResources[type=main,src={entries1},loc-prefix=false] +\GlsXtrLoadResources[type=main,src={entries2},loc-prefix] +\GlsXtrLoadResources[type=symbols,src={entries3},loc-prefix={p.,pp.}] +\end{verbatim} +This works since the conflicting \csopt[p.,pp.]{loc-prefix} and +\csopt[true]{loc-prefix} are in different glossaries (assigned through the +\optref{type} key). The entries fetched from \texttt{entries1.bib} +won't have a location prefix. The entries fetched from +\texttt{entries2.bib} will have the location prefix obtained from +the language resource file. The entries fetched from +\texttt{entries3.bib} will have the location prefix \qt{p.}\ or +\qt{pp.} (Note that using the \csopt{type} option isn't the same as +setting the \field{type} field for each entry in the \ext{bib} +file.) + +If the \csopt{type} option isn't used: +\begin{verbatim} +\GlsXtrLoadResources[src={entries1},loc-prefix=false] +\GlsXtrLoadResources[src={entries2},loc-prefix] +\GlsXtrLoadResources[src={entries3},loc-prefix={p.,pp.}] +\end{verbatim} +then \csopt[true]{loc-prefix} takes precedence over +\csopt[p.,pp.]{loc-prefix} (since it was used first). The entries fetched from +\texttt{entries1.bib} still won't have a location prefix, but the entries +fetched from both \texttt{entries2.bib} and \texttt{entries3.bib} +have the location prefixes obtained from the language resource file. + +\subsection{\csoptnv{loc-suffix}\csopteqval{value}} +\labelopt{loc-suffix} + +This is similar to \optref{loc-prefix} but there are some subtle +differences. In this case \meta{value} may either be the keyword +\optfmt{false} (in which case the location suffix is omitted) +or a comma-separated list +\optfmt{\meta{suffix-0}\dcomma\meta{suffix-1}\dcomma\ldots\dcomma\meta{suffix-n}} +where \meta{suffix-0} is the suffix to use when the location list +only has a cross-reference with no locations, \meta{suffix-1} is the suffix to use +when the location list has one location (optionally with a +cross-reference), and so on. The final \meta{suffix-n} in the list +is the suffix when the location list has \meta{n} or more locations +(optionally with a cross-reference). + +This option will append \csref{bibglslocsuffix}\margm{n} to location +lists that either have a cross-reference or have at least one location. +Unlike \cs{bibglslocprefix}, this command isn't used when the +location list is completely empty. Also, unlike +\cs{bibglslocprefix}, this suffix command doesn't have an equivalent +to \cs{bibglspostlocprefix}. + +If \meta{value} omitted, \csopt[\cs{@}.]{loc-suffix} is assumed. +The default is \csopt[false]{loc-suffix}. + +As with \optref{loc-prefix}, take care not to mix different values +of \csopt{loc-suffix} for entries in the same glossary type. + +\subsection{\csoptnv{loc-counters}\csopteqval{list}} +\labelopt{loc-counters} + +Commands like \cs{gls} allow you to select a different +counter to use for the location for that specific instance +(overriding the default counter for the entry's glossary type). +This is done with the \glsopt{counter} option. For example, +consider the following document: +\begin{verbatim} +\documentclass{article} + +\usepackage[colorlinks]{hyperref} +\usepackage[record,style=tree]{glossaries-extra} + +\GlsXtrLoadResources[ + src={entries}% data in entries.bib +] + +\begin{document} + +\gls{pi}. + +\begin{equation} +\gls[counter=equation]{pi} +\end{equation} + +\begin{equation} +\gls[counter=equation]{pi} +\end{equation} + +\newpage + +\begin{equation} +\gls[counter=equation]{pi} +\end{equation} + + +\newpage + +\gls{pi}. + +\newpage + +\gls{pi}. + +\newpage + +\gls{pi}. + +\newpage + +\printunsrtglossaries +\end{document} +\end{verbatim} +This results in the location list \qt{1, 1--3, 3--5}. This +looks a little odd and it may seem as though the range formation +hasn't worked, but the locations are actually: page~1, equation~1, +equation~2, equation~3, page~3, page~4 and page~5. Ranges can't +be formed across different counters. + +The \csopt[\meta{list}]{loc-counters} option instructs \bibgls\ +to group the locations according to the counters given in +the comma-separated \meta{list}. If a location has a counter +that's not listed in \meta{list}, then the location is discarded. + +For example: +\begin{verbatim} +\GlsXtrLoadResources[ + loc-counters={equation,page},% group locations by counter + src={entries}% data in entries.bib +] +\end{verbatim} +This will first list the locations for the \counter{equation} +counter and then the locations for the \counter{page} counter. +Each group of locations is encapsulated within the command +\csref{bibglslocationgroup}\margm{n}\margm{counter}\margm{locations}. +The groups are separated by \csref{bibglslocationgroupsep} +(which defaults to \cs{delimN}). + +The \meta{list} value must be non-empty. Use +\csopt[as-use]{loc-counters} to restore the default behaviour, where +the locations are listed in the document order of use, or +\csopt[false]{save-locations} to omit the location lists. Note that +you can't form counter groups from +\hyperref[sec:supplementalopts]{supplemental location lists}. + +\section{Supplemental Locations} +\label{sec:supplementalopts} + +\emph{These options require at least version 1.14 of \sty{glossaries-extra}.} + +\subsection{\csoptnv{supplemental-locations}\csopteqval{basename}} +\labelopt{supplemental-locations} + +The \sty{glossaries-extra} package (from v1.14) provides a way of +manually adding locations in supplemental documents through the use +of the \glsaddopt{thevalue} option in the optional argument of +\cs{glsadd}. Setting values manually is inconvenient and can result +in errors, so \bibgls\ provides a way of doing this automatically. +Both the main document and the supplementary document need to use +the \styopt{record} option. The entries provided in the \csopt{src} +set must have the same labels as those used in the supplementary +document. (The simplest way to achieve this is to ensure that both +documents use the same \ext{bib} files and the same prefixes.) + +For example, suppose the file \filefmt{entries.bib} contains: +\begin{verbatim} +@entry{sample, + name={sample}, + description="an example entry" +} + +@abbreviation{html, + short="html", + long={hypertext markup language} +} +@abbreviation{ssi, + short="ssi", + long="server-side includes" +} + +@index{goose,plural="geese"} +\end{verbatim} +Now suppose the supplementary document is contained in the file +\filefmt{suppl.tex}: +\begin{verbatim} +\documentclass{article} + +\usepackage[colorlinks]{hyperref} +\usepackage[record,counter=section]{glossaries-extra} + +\GlsXtrLoadResources[src=entries] + +\renewcommand{\thesection}{S\arabic{section}} +\renewcommand{\theHsection}{\thepart.\thesection} + +\begin{document} +\part{Sample Part} +\section{Sample Section} +\gls{goose}. \gls{sample}. + +\part{Another Part} +\section{Another Section} +\gls{html}. +\gls{ssi}. + +\printunsrtglossaries +\end{document} +\end{verbatim} +This uses the \counter{section} counter for the locations and has a +prefix (\verb|\thepart.|) for the section hyperlinks. + +Now let's suppose I have another document called \filefmt{main.tex} +that uses the \texttt{sample} entry, but also needs to include the +location (S1) from the supplementary document. The manual approached +offered by \sty{glossaries-extra} is quite cumbersome and requires +setting the \catattr{externallocation} attribute and using +\cs{glsadd} with \glsaddopt[S1]{thevalue}, \glsaddopt[I.S1]{theHvalue} +and \glsaddopt[glsxtrsupphypernumber]{format}. + +This can be simplified with \bibgls\ by using the +\optfmt{supplemental-locations} option. The value should be the base +name (without the extension) of the supplementary document +(\optfmt{suppl} in the above example). For example: +\begin{verbatim} +\documentclass{article} + +\usepackage[colorlinks]{hyperref} +\usepackage[record]{glossaries-extra} + +\GlsXtrLoadResources[ + supplemental-locations=suppl,% fetch records from suppl.aux + src=entries] + +\begin{document} +\Gls{sample} document. + +\printunsrtglossaries + +\end{document} +\end{verbatim} +The location list for \texttt{sample} will now be \qt{1, S1} (page~1 +from the main document and S1 from the supplementary document). Note +that the original location format from the supplementary document +will be replaced by \optfmt{glsxtrsupphypernumber}, which will +produce an external hyperlink if the main document loads the +\sty{hyperref} package. (Note that not all PDF viewers can handle +external hyperlinks, and some that can open the external PDF file may not +recognise the destination within that file.) + +The supplementary locations lists are encapsulated within +\cs{bibglssupplemental}. + +\subsection{\csoptnv{supplemental-selection}\csopteqval{value}} +\labelopt{supplemental-selection} + +In the above example, only the \texttt{sample} entry is listed in +the main document, even though the supplementary document also +references the \texttt{goose}, \texttt{html} and \texttt{ssi} +entries. By default, only those entries that are referenced in the +main document will have supplementary locations added (if found in +the supplementary document's \ext{aux} file). You can additionally +include other entries that are referenced in the supplementary +document but not in the main document using +\optfmt{supplemental-selection}. The \meta{value} may be one of the +following: +\begin{itemize} +\item \optfmt{all}: add all the entries in the supplementary +document that have been defined in the \ext{bib} files listed in +\optref{src} for this resource set in the main document. +\item \optfmt{selected}: only add supplemental locations for entries +that have already been selected by this resource set. +\item \meta{label-1},\ldots,\meta{label-2}: in addition to all those +entries that have already been selected by this resource set, also +add the entries identified in the comma-separated list. If a label +in this list doesn't have a record in the supplementary document's +\ext{aux} file, it will be ignored. +\end{itemize} +Any records in the supplementary \ext{aux} file that aren't defined +by the current resource set (through the \ext{bib} files listed in +\optref{src}) will be ignored. Entry aliases aren't taken into +account when including supplementary locations. + +For example: +\begin{verbatim} +\documentclass{article} + +\usepackage[colorlinks]{hyperref} +\usepackage[record]{glossaries-extra} + +\GlsXtrLoadResources[ + supplemental-locations=suppl, + supplemental-selection={html,ssi}, + src=entries] + +\begin{document} +\Gls{sample} document. + +\printunsrtglossaries + +\end{document} +\end{verbatim} +This will additionally add the \texttt{html} and \texttt{ssi} entries +even though they haven't been used in this document. The +\texttt{goose} entry used in the supplementary document won't be +included. + +If an entry has both a main location list and a supplementary +location list (such as the \texttt{sample} entry above), the lists +will be separated by \csref{bibglssupplementalsep}. + +\subsection{\csoptnv{supplemental-category}\csopteqval{value}} +\labelopt{supplemental-category} + +The \optfmt{category} for entries containing supplemental location +lists may be set using \optfmt{supplemental\dhyphen category}. If unset, +\meta{value} defaults to the same as that given by the +\optref{category} option. The \meta{value} may either be a known +identifier (as per \optref{category}) or the category label. For example: +\begin{verbatim} +\documentclass{article} + +\usepackage[colorlinks]{hyperref} +\usepackage[record]{glossaries-extra} + +\GlsXtrLoadResources[ + supplemental-locations=suppl, + supplemental-selection={html,ssi}, + supplemental-category={supplemental}, + src=entries] + +\begin{document} +\Gls{sample} document. + +\printunsrtglossaries + +\end{document} +\end{verbatim} + +\section{Sorting} +\label{sec:sortingopts} + +Entries are typically sorted (for example, alphabetically +or in order of use), but the \sty{glossaries-extra} package +is versatile enough to be used in wider contexts than simple +terms, symbols or abbreviations. For example, entries could +contain theorems or problems where the \field{name} supplies +the title and the \field{description} provides a description +of the theorem or problem. Another field might then contain +the proof or solution. Therefore, somewhat unusually for +an indexing application, \bibgls\ also provides the option +to shuffle the entries instead of sorting them. + +\subsection{\csoptnv{sort}\csopteqval{value}} +\labelopt{sort} + +The \csopt{sort} key indicates how entries should be sorted. The +\meta{value} may be one of: +\begin{itemize} + +\item \optfmt{none} (or \optfmt{unsrt}): don't sort the entries. +(The entries will be in the order they were processed when parsing +the data.) + +\item \optfmt{random}: shuffles rather than sorts the entries. +This won't work if there are hierarchical entries, so it's best +to use this option with \optref{flatten}. The seed for the +random generator can be set using \optref{shuffle} (which +also automatically sets \csopt[random]{sort} and \csopt{flatten}). + +\item \meta{lang tag}: sort according to the rules of the locale +given by the \gls{IETF} language tag \meta{lang tag}. (Use with +\optref{break-at} to determine whether or not to split at word +boundaries.) + +\item \optfmt{locale}: equivalent to +\csopt[\meta{lang tag}]{sort} where \meta{lang tag} is obtained +from the operating system (or Java Runtime Environment). + +\item \optfmt{doc}: sort the entries according to the document +language. This is equivalent to \optref[\meta{lang tag}]{sort} +where \meta{lang tag} is the locale associated with the document +language. In the case of a multi-lingual document, \meta{lang tag} +is the locale of the last language resource file to be loaded through +\sty{tracklang}'s interface. It's best to explicitly set the locale +for multi-lingual documents to avoid confusion. If no languages have been tracked, this +option is equivalent to \csopt[locale]{sort}. + +\item \optfmt{custom}: sort the entries according to the +rule provided by \optref{sort-rule}. + +\item \optfmt{use}: sort in order of use. (This order is determined +by the records written to the \ext{aux} file by the \styopt{record} +package option.) + +\item \optfmt{letter-case}: case-sensitive letter (character code) sort. + +\item \optfmt{letter-case-reverse}: reverse case-sensitive letter (character code) sort. + +\item \optfmt{letter-nocase}: case-insensitive letter (character code) sort. +Use \csopt[\meta{lang tag}]{sort} with \csopt[none]{break-at} to +emulate \app{xindy}'s locale letter ordering. + +\item \optfmt{letter-nocase-reverse}: reverse case-insensitive letter (character code) sort. + +\item \optfmt{integer}: integer sort. This is for integer sort +values. Any value that isn't an integer is treated as 0. + +\item \optfmt{integer-reverse}: as above but reverses the order. + +\item \optfmt{hex}: hexadecimal integer sort. This is for +hexadecimal sort values. Any value that isn't a hexadecimal number +is treated as 0. + +\item \optfmt{hex-reverse}: as above but reverses the order. + +\item \optfmt{octal}: octal integer sort. This is for +octal sort values. Any value that isn't a octal number +is treated as 0. + +\item \optfmt{octal-reverse}: as above but reverses the order. + +\item \optfmt{binary}: binary integer sort. This is for binary sort +values. Any value that isn't a binary number is treated as 0. + +\item \optfmt{binary-reverse}: as above but reverses the order. + +\item \optfmt{float}: single-precision sort. This is for +decimal sort values. Any value that isn't a decimal is treated as 0.0. + +\item \optfmt{float-reverse}: as above but reverses the order. + +\item \optfmt{double}: double-precision sort. This is for +decimal sort values. Any value that isn't a decimal is treated as 0.0. + +\item \optfmt{float-reverse}: as above but reverses the order. + +\end{itemize} +If the \meta{value} is omitted, \csopt[doc]{sort} is assumed. If the +\csopt{sort} option isn't used then \csopt[locale]{sort} is assumed. + +Note that \csopt[locale]{sort} can provide more detail about the +locale than \csopt[doc]{sort}, depending on how the document +language has been specified. + +For example, with: +\begin{verbatim} +\documentclass{article} +\usepackage[ngerman]{babel} +\usepackage[record]{glossaries} +\GlsXtrLoadResources[src={german-terms}] +\end{verbatim} +the language tag will be \texttt{de-1996}, which doesn't have an +associated region. Whereas with +\begin{verbatim} +\documentclass[de-DE-1996]{article} +\usepackage[ngerman]{babel} +\usepackage[record]{glossaries} +\GlsXtrLoadResources[src={german-terms}] +\end{verbatim} +the language tag will be \texttt{de-DE-1996} because \sty{tracklang} +has picked up the locale from the document class options. This is +only likely to cause a difference if a language has different +sorting rules according to the region or if the language may be +written in multiple scripts. + +A multilingual document will need to have the \csopt{sort} specified +when loading the resource to ensure the correct language is chosen. +For example: +\begin{verbatim} +\GlsXtrLoadResources[src={english-terms},sort={en-GB}] +\GlsXtrLoadResources[src={german-terms},sort={de-DE-1996}] +\end{verbatim} + +\subsection{\csoptnv{sort-rule}\csopteqval{value}} +\labelopt{sort-rule} + +If the \optref[custom]{sort} option is used, the sort rule +must be provided with \optfmt{sort-rule}. In this case +the collation is performed using Java's +\href{http://docs.oracle.com/javase/8/docs/api/java/text/RuleBasedCollator.html}{RuleBasedCollator} +class. Remember that the options will be expanded as they +are written to the \ext{aux} file, so be careful of +any special characters that occur in the rule. You can +use \cs{string}\cs{u}\meta{hex} (where \meta{hex} is a hexadecimal +code) to represent a Unicode character. For example: +\begin{verbatim} +\GlsXtrLoadResources[ + sort={custom}, + sort-rule={< a,A < b,B < c,C < ch,Ch,CH < d,D + < dd,Dd,DD < e,E < f,F < ff,Ff,FF + < g,G < ng,Ng,NG < h,H < ij,Ij,IJ + < i,I < j,J < k,K < l,L < ll,Ll,LL < m,M + < n,N < o,O < p,P < ph,Ph,PH < q,Q < r,R < rh,Rh,RH + < s,S < t,T < th,Th,TH < u,U < v,V < w,W < x,X < y,Y < z,Z + < \string\u00E6,\string\u00C6} +] +\end{verbatim} +You can also use \cs{protect} instead of \cs{string}. This will +cause a space to appear between \cs{u} and the hexadecimal +value in the \ext{aux} file (if \meta{hex} starts with a decimal +digit), but \bibgls\ will accept a single space between \cs{u} and +\meta{hex} to allow for this. However it's safer to just use +\cs{string} (in case \meta{hex} start with a letter). + +If \optref{sort} is not set to \optfmt{custom}, the +\optfmt{sort-rule} setting will be ignored. + +\subsection{\csoptnv{break-at}\csopteqval{option}} +\labelopt{break-at} + +The rule-based sort options (\csopt[\meta{lang tag}]{sort} +and \csopt[custom]{sort}) typically list punctuation characters +(such as space) before alphabetical characters. This means that +the rule-based sort options are naturally in a letter order, similar +to \app{xindy}'s \texttt{ord/letorder} module. This isn't the same +as \csopt[letter-nocase]{sort} as the locale letter ordering is rule-based +rather than according to the Unicode value. + +In order to replicate \app{makeindex} and \app{xindy}'s default word +order, \bibgls\ splits up the sort value at word boundaries and +inserts a marker (identified by \optref{break-marker}). + +For example, if the sort value is \qt{sea lion} then it's actually +converted to \verb"sea|lion|" whereas \qt{sea} becomes \verb"sea|" +and \qt{seal} becomes \verb"seal|". The default marker is \verb"|" +which is commonly placed in collation rules before digits but +after the ignored characters, such as spaces and hyphens. + +You can change where the break points are inserted with +\csopt[\meta{option}]{break-at} where \meta{option} may be one of: +\begin{itemize} +\item \optfmt{word}: break at word boundaries (default). +For example, the sort value \qt{Tom, Dick, and Harry} becomes +\verb"Tom|Dick|and|Harry". +\item \optfmt{character}: break after each character. +\item \optfmt{sentence}: break after each sentence. +\item \optfmt{none}: don't create break points. Use this option to +emulate \app{makeindex} or \app{xindy}'s letter ordering. +\end{itemize} + +This option is ignored when used with the non-locale \csopt{sort} options. +Use the \argref{debug} switch to show the break points. +(This will also show the collation rule.) + +\subsection{\csoptnv{break-marker}\csopteqval{marker}} +\labelopt{break-marker} + +The break marker can be changed using +\csopt[\meta{marker}]{break-marker}, where \meta{marker} is +the character to use. For example, \csopt[-]{break-marker} will use a +hyphen. The marker may be empty, which effectively strips the +inter-word punctuation. For example, with +\csopt[\empty]{break-marker}, \qt{Tom, Dick, and Harry} becomes +\texttt{TomDickandHarry} and \qt{sea lion} simply becomes +\texttt{sealion}. If \meta{marker} is omitted, +\csopt[\empty]{break-marker} is assumed. + +\subsection{\csoptnv{sort-field}\csopteqval{field}} +\labelopt{sort-field} + +The \csopt{sort-field} key indicates which field provides the sort +value. The default is the \field{sort} field. For example +\begin{verbatim} +\GlsXtrLoadResources[ + src={entries-terms},% data in entries-terms.bib + sort-label=category,% sort by 'category' field + sort=letter-case% case-sensitive letter sort +] +\end{verbatim} +This sorts the entries according to the \field{category} field using +a case-sensitive letter comparison. +You may also use \csopt[id]{sort-field} to sort according to +the label. + +If an entry is missing a value for \meta{field}, then the value of +the fallback field will be used instead. For example, with the +default \csopt[sort]{sort-field}, then for an entry defined with +\atentry{entry}, if the \field{sort} field is missing the fallback +field will be the \field{name} or the \field{parent} field if the +\field{name} field is missing. If the entry is instead defined with +\atentry{abbreviation} (or \atentry{acronym}) then if the +\field{sort} field is missing, \bibgls\ will start with the same +fallback as for \atentry{entry} but if neither the \field{name} or +\field{parent} field is set, it will fallback on the \field{short} +field. + +If no fallback field can be found, the entry's label will be used. + +\subsection{\csoptnv{shuffle}\csopteqval{seed}} +\labelopt{shuffle} + +Automatically sets \csopt[random]{sort} and \csopt{flatten}. +The value \meta{seed} may be omitted. If present, it should +be an integer used as a seed for the random number generator. + +\subsection{\csoptnv{strength}\csopteqval{value}} +\labelopt{strength} + +The collation strength used by \csopt[\meta{locale}]{sort} can be set +to the following values: \optfmt{primary} (default), +\optfmt{secondary}, \optfmt{tertiary} or \optfmt{identical}. These +indicate the difference between two characters, but the exact +assignment is locale dependent. See the documentation for Java's +\href{http://docs.oracle.com/javase/8/docs/api/java/text/Collator.html}{\texttt{Collator} +class} for further details. + +For example, suppose the file \filefmt{entries.bib} contained: +\begin{verbatim} +@index{resume} + +@index{RESUME} + +@index{resumee, + name={r\'esum\'e}} + +@index{rat} + +@index{rot} + +@index{aardvark} + +@index{zoo} +\end{verbatim} +and the document contained: +\begin{verbatim} +\documentclass{article} + +\usepackage[record]{glossaries-extra} + +\GlsXtrLoadResources[sort={en},src={entries}] + +\begin{document} +\gls{resumee}, \gls{resume}, \gls{RESUME}, +\gls{aardvark}, \gls{rat}, \gls{rot}, \gls{zoo}. + +\printunsrtglossaries +\end{document} +\end{verbatim} +then this uses the default \csopt[primary]{strength}, so the entries +are listed as aardvark, rat, r\'esum\'e, resume, RESUME, rot, zoo. + +If the strength is changed to \optfmt{secondary}: +\begin{verbatim} +\GlsXtrLoadResources[sort={en},src={entries},strength=secondary] +\end{verbatim} +then the entries are listed as aardvark, rat, resume, RESUME, +r\'esum\'e, rot, zoo. + +If the strength is changed to \optfmt{tertiary} or +\optfmt{identical}, there's no difference from +\csopt[secondary]{strength} for this particular example. + +This option is ignored by non-locale sorts (such as letter or numeric). + +\subsection{\csoptnv{decomposition}\csopteqval{value}} +\labelopt{decomposition} + +The collation decomposition used by \csopt[\meta{locale}]{sort} can be set +to the following values: \optfmt{canonical} (default), +\optfmt{full} or \optfmt{none}. This determines how Unicode composed +characters are handled. The fastest mode is \optfmt{none} but is +only appropriate for languages without accents. The slowest mode is +\optfmt{full} but is the most complete for languages with non-ASCII +characters. See the documentation for Java's +\href{http://docs.oracle.com/javase/8/docs/api/java/text/Collator.html}{\texttt{Collator} +class} for further details. +This option is ignored by non-locale sorts (such as letter or numeric). + +\section{Dual Entries} + +\subsection{\csoptnv{dual-sort}\csopteqval{value}} +\labelopt{dual-sort} + +This option indicates how to sort the dual entries. The primary +entries are sorted with the normal entries according to +\optref{sort}, and the dual entries are sorted according to +\csopt{dual-sort} unless \csopt[combine]{dual-sort} in which case the dual +entries will be combined with the primary entries and all the +entries will sorted together according to the \optref{sort} option. + +If \meta{value} isn't set to \optfmt{combine} then the dual +entries are sorted separately according to \meta{value} (as per +\optref{sort}) and the dual entries will be appended at the end of +the \ext{glstex} file. The field used by the comparator is given by +\optref{dual-sort-field}. +If \csopt[custom]{dual-sort}, then the dual entries according to the +rule provided by \optref{dual-sort-rule}. + + +For example: +\begin{verbatim} +\GlsXtrLoadResources[ + src={entries-dual}, + sort={en}, + dual-sort={de-CH-1996} +] +\end{verbatim} +This will sort the primary entries according to \optfmt{en} +(English) and the secondary entries according to \optfmt{de-CH-1996} +(Swiss German new orthography) whereas: +\begin{verbatim} +\GlsXtrLoadResources[ + src={entries-dual}, + sort={en-GB}, + dual-sort={combine} +] +\end{verbatim} +will combine the dual entries with the primary entries and sort them +all according to the \optfmt{en-GB} locale (British English). + +If not set, \csopt{dual-sort} defaults to \optfmt{combine}. If +\meta{value} is omitted, \optfmt{locale} is assumed. + +\subsection{\csoptnv{dual-sort-field}\csopteqval{value}} +\labelopt{dual-sort-field} + +This option indicates the field to use when sorting dual entries +(when they haven't been combined with the primary entries). The +default value is the same as the \optref{sort-field} value. + +\subsection{\csoptnv{dual-sort-rule}\csopteqval{value}} +\labelopt{dual-sort-rule} + +As \optref{sort-rule} but for \csopt[custom]{dual-sort}. + +\subsection{\csoptnv{dual-prefix}\csopteqval{value}} +\labelopt{dual-prefix} + +This option indicates the prefix to use for the dual entries. The +default value is \idprefix{dual} (including the terminating period). +Any references to dual entries within the \ext{bib} file should use +the prefix \idprefix{dual} which will be replaced by \meta{value} +when the \ext{bib} file is parsed. + +\subsection{\csoptnv{dual-type}\csopteqval{value}} +\labelopt{dual-type} + +This option sets the \field{type} field for all dual +entries. (The primary entries obey the \optref{type} option.) This +will override any value of \field{type} provided in the \ext{bib} +file (or created through a mapping). The \meta{value} is required. + +The \meta{value} may be: +\begin{itemize} +\item \optfmt{same as entry}: sets the +\field{type} to the entry type. For example, if the entry +was defined with \atentryref{dualentry}, the \field{type} will be +set to \optfmt{dualentry}. +\item \optfmt{same as primary}: sets the \field{type} to the same +as the corresponding primary entry's \field{type} (which may +have been set with \optref{type}). If the primary entry doesn't +have the \field{type} field set, the dual's \field{type} will +remain unchanged. +\item \meta{label}: sets the \field{type} field to \meta{label}. +\end{itemize} + +Remember that the glossary with that label must have already +been defined. + +For example: +\begin{verbatim} +\newglossary*{english}{English} +\newglossary*{french}{French} + +\GlsXtrLoadResources[src={entries},sort={en},dual-sort={fr}, + type=english, + dual-type=french] +\end{verbatim} + +Alternatively: +\begin{verbatim} +\newglossary*{dictionary}{Dictionary} + +\GlsXtrLoadResources[src={entries},sort={en},dual-sort={fr}, + type=dictionary, + dual-type={same as primary}] +\end{verbatim} + +\subsection{\csoptnv{dual-category}\csopteqval{value}} +\labelopt{dual-category} + +This option sets the \field{category} field for all dual +entries. (The primary entries obey the \optref{category} option.) This +will override any value of \field{category} provided in the \ext{bib} +file (or created through a mapping). The \meta{value} may be empty. + +The \meta{value} may be: +\begin{itemize} +\item \optfmt{same as entry}: sets the +\field{category} to the entry type. For example, if the entry +was defined with \atentryref{dualentry}, the \field{category} will be +set to \optfmt{dualentry}. +\item \optfmt{same as primary}: sets the \field{category} to the same +as the corresponding primary entry's \field{category} (which may +have been set with \optref{category}). If the primary entry doesn't +have the \field{category} field set, the dual's \field{category} will +remain unchanged. +\item \optfmt{same as type}: sets the \field{category} to the same +as the value of the entry's \field{type} field (which may have been +set with \optref{dual-type}). If the entry doesn't +have the \field{type} field set, the \field{category} will +remain unchanged. +\item \meta{label}: sets the \field{category} field to \meta{label}. +\end{itemize} + +\subsection{\csoptnv{dual-short-case-change}\csopteqval{value}} +\labelopt{dual-short-case-change} + +As \optref{short-case-change} but applies to the \field{dualshort} +field instead. + +\subsection{\csoptnv{dual-entry-map}=\marg{\margm{list1},\margm{list2}}} +\labelopt{dual-entry-map} + +This setting governs the behaviour of \atentry{dualentry} +definitions. The value consists of two comma-separated lists of +equal length identifying the field mapping used to create the dual +entry from the primary one. Note that the \field{alias} field +can't be mapped. + +The default setting is: +\begin{verbatim} +dual-entry-map= +{ + {name,plural,description,descriptionplural}, + {description,descriptionplural,name,plural} +} +\end{verbatim} +The dual entry is created by copying the value of the field in the +first list \meta{list1} to the field in the corresponding place in the second +list \meta{list2}. Any additional fields are copied over to the same +field. + +For example: +\begin{verbatim} +@dualentry{cat, + name={cat}, + description={chat}, + see={dog} +} +\end{verbatim} +defines two entries. The primary entry is essentially like +\begin{verbatim} +@entry{cat, + name={cat}, + plural={cat\glspluralsuffix }, + description={chat}, + descriptionplural={chat\glspluralsuffix }, + see={dog} +} +\end{verbatim} +and the dual entry is essentially like +\begin{verbatim} +@entry{dual.cat, + description={cat}, + descriptionplural={cat\glspluralsuffix }, + name={chat}, + plural={chat\glspluralsuffix }, + see={dog} +} +\end{verbatim} +(except they're defined using \cs{bibglsnewdualentry} instead of +\cs{bibglsnewentry}, and each is considered dependent on the other.) + +The \field{see} field isn't listed in \csopt{dual-entry-map} so its +value is simply copied directly over to the \field{see} field in the +dual entry. Note that the missing plural fields (\field{plural} and +\field{descriptionplural}) have been filled in. + +In general \bibgls\ doesn't try to supply missing fields, but in the +dual entry cases it needs to do this for the mapped fields. This is +because the shuffled fields might have different default values from +the \sty{glossaries-extra} package's point of view. For example, +\cs{longnewglossaryentry} doesn't provide a default for +\field{descriptionplural} if if hasn't been set. + +\subsection{\csoptnv{dual-abbrv-map}=\marg{\margm{list1},\margm{list2}}} +\labelopt{dual-abbrv-map} + +This is like \csopt{dual-entry-map} but applies to +\atentry{dualabbreviation} rather than \atentry{dualentry}. +Note that the \field{alias} field can't be mapped. The +default setting is: +\begin{verbatim} +dual-abbrv-map= +{ + {short,shortplural,long,longplural,dualshort,dualshortplural, + duallong,duallongplural}, + {dualshort,dualshortplural,duallong,duallongplural,short,shortplural, + long,longplural} +} +\end{verbatim} + +This essentially flips the \field{short} field with the +\field{dualshort} field and the \field{long} field with the +\field{duallong} field. See \atentryref{dualabbreviation} +for further details. + +\subsection{\csoptnv{dual-entryabbrv-map}=\marg{\margm{list1},\margm{list2}}} +\labelopt{dual-entryabbrv-map} + +This is like \csopt{dual-entry-map} but applies to +\atentry{dualentryabbreviation} rather than \atentry{dualentry}. +Note that the \field{alias} field can't be mapped. The +default setting is: +\begin{verbatim} +dual-entryabbrv-map= +{ + {long,short,shortplural}, + {name,text,plural} +} +\end{verbatim} +See \atentryref{dualentryabbreviation} for further details. + + +\subsection{\csoptnv{dual-symbol-map}=\marg{\margm{list1},\margm{list2}}} +\labelopt{dual-symbol-map} + +This is like \csopt{dual-entry-map} but applies to +\atentry{dualsymbol} rather than \atentry{dualentry}. +Note that the \field{alias} field can't be mapped. The +default setting is: +\begin{verbatim} +dual-symbol-map= +{ + {name,plural,symbol,symbolplural}, + {symbol,symbolplural,name,plural} +} +\end{verbatim} + +This essentially flips the \field{name} field with the +\field{symbol} field. + +\subsection{\csoptnv{dual-entry-backlink}\csopteqval{boolean}} +\labelopt{dual-entry-backlink} + +This is a boolean setting. +When used with \atentry{dualentry}, if \meta{boolean} is +\optfmt{true}, this will wrap the contents of first mapped field +with \cs{glshyperlink}. If \meta{boolean} is missing \optfmt{true} +is assumed. + +The field is obtained from the first mapping +listed in \csopt{dual-entry-map}. + +For example, if the document contains: +\begin{verbatim} +\GlsXtrLoadResource[dual-entry-backlink, +dual-entry-map={ + {name,plural,description,descriptionplural}, + {description,descriptionplural,name,plural} +}, +src={entries-dual}] +\end{verbatim} +and if the \ext{bib} file contains +\begin{verbatim} +@dualentry{child, + name={child}, + plural={children}, + description={enfant} +} +\end{verbatim} +Then the definition of the primary entry (\texttt{child}) in the +\ext{glstex} file will have the \field{description} field set to +\begin{verbatim} +{\glshyperlink[enfant]{dual.child}} +\end{verbatim} +and the dual entry (\texttt{dual.child}) will have the +\field{description} field set to +\begin{verbatim} +{\glshyperlink[child]{child}} +\end{verbatim} + +The reason the \field{description} field is chosen for the modification is +because the first field listed in the first list in \csopt{dual-entry-map} +is the \field{name} field which maps to \field{description} (the +first field in the second list). This means that the hyperlink for +the dual entry should be put in the \field{description} field. + +For the primary entry, the \field{name} field is looked up in the +second list from the \csopt{dual-entry-map} setting. This is the +third item in this second list, so the third item in the first list +is selected, which also happens to be the \field{description} field, +so the hyperlink for the primary entry is put in the +\field{description} field. + +\subsection{\csoptnv{dual-abbrv-backlink}\csopteqval{boolean}} +\labelopt{dual-abbrv-backlink} + +This is analogous to \csopt{dual-entry-backlink} but for entries +defined with \atentry{dualabbreviation} instead of +\atentry{dualentry}. + +\subsection{\csoptnv{dual-symbol-backlink}\csopteqval{boolean}} +\labelopt{dual-symbol-backlink} + +This is analogous to \csopt{dual-entry-backlink} but for entries +defined with \atentry{dualsymbol} instead of \atentry{dualentry}. + +\subsection{\csoptnv{dual-entryabbrv-backlink}\csopteqval{boolean}} +\labelopt{dual-entryabbrv-backlink} + +This is analogous to \csopt{dual-entry-backlink} but for entries +defined with \atentry{dualentryabbreviation} instead of +\atentry{dualentry}. + +\subsection{\csoptnv{dual-backlink}\csopteqval{boolean}} +\labelopt{dual-backlink} + +Shortcut for \csopt[\meta{boolean}]{dual-entry-backlink}, +\csopt[\meta{boolean}]{dual-entryabbrv-backlink}, +\csopt[\meta{boolean}]{dual-abbrv-backlink}, and +\csopt[\meta{boolean}]{dual-symbol-backlink}. + +\subsection{\csoptnv{dual-field}\csopteqval{value}} +\labelopt{dual-field} + +If this option is used, this will add \cs{glsxtrprovidestoragekey} +to the start of the \ext{glstex} file providing the key given by +\meta{value}. Any entries defined using \atentry{dualentry} +will be written to the \ext{glstex} file with an extra field called +\meta{value} that is set to the mirror entry. If \meta{value} is +omitted \texttt{dual} is assumed. + +For example, if the \ext{bib} file contains +\begin{verbatim} +@dualentry{child, + name={child}, + plural={children}, + description={enfant} +} +\end{verbatim} +Then with \csopt[dualid]{dual-field} this will first add the line +\begin{verbatim} +\glsxtrprovidestoragekey{dualid}{}{} +\end{verbatim} +at the start of the file and will include the line +\begin{verbatim} +dualid={dual.child}, +\end{verbatim} +for the primary entry (\texttt{child}) and the line +\begin{verbatim} +dualid={child}, +\end{verbatim} +for the dual entry (\texttt{dual.child}). It's then possible to +reference one entry from the other. For example, the post-description +hook could contain: +\begin{verbatim} + \ifglshasfield{dualid}{\glscurrententrylabel} + {% + \space + (\glshyperlink{\glsxtrusefield{\glscurrententrylabel}{dualid}})% + }% + {}% +\end{verbatim} +Note that this new field won't be available for use within the +\ext{bib} file (unless it was previously defined in the document +before \csref{glsxtrresourcefile}). + +\chapter{Provided Commands} +\label{sec:bibglscs} + +When \bibgls\ creates the \ext{glstex} file, it writes some +definitions for custom commands in the form \csfmt{bibgls...} which +may be changed as required. The command definitions all use +\cs{providecommand} which means that you can define the command with +\cs{newcommand} before the resource file is loaded. + +\section{Entry Definitions} +\label{sec:newentrydefs} + +This section lists the commands (\csfmt{bibglsnew...}) used to +define entries. Note that the entry definition commands are +actually used when \TeX\ inputs the resource file, so redefining +them after the resource file is loaded won't have an effect on the +entries defined in that resource file (but will affect entries defined +in subsequent resource files). Each provided command is defined in +the \ext{glstex} file immediately before the first entry that +requires it, so only the commands that are actually needed are +provided. + +After each entry is defined, if it has any associated locations, the +locations are added using +\begin{alltt} +\cs{glsxtrfieldlistadd}\margm{label}\marg{loclist}\margm{record} +\end{alltt} +This command is provided by \sty{glossaries-extra} (v1.12). + + +\subsection{\csfmt{bibglsnewentry}} +\labelcs{bibglsnewentry} + +\begin{definition} +\cs{bibglsnewentry}\margm{label}\margm{options}\margm{name}\margm{description} +\end{definition} +This command is used to define terms identified with the +\atentryref{entry} type. The definition provided in the \ext{glstex} +file is: +\begin{verbatim} +\providecommand{\bibglsnewentry}[4]{% + \longnewglossaryentry*{#1}{name={#3},#2}{#4}% +} +\end{verbatim} +This uses the starred form of \cs{longnewglossaryentry} that +doesn't automatically append \cs{nopostdesc} (which interferes with +the post-description hooks provided by category attributes). + +\subsection{\csfmt{bibglsnewsymbol}} +\labelcs{bibglsnewsymbol} + +\begin{definition} +\cs{bibglsnewsymbol}\margm{label}\margm{options}\margm{name}\margm{description} +\end{definition} +This command is used to define terms identified with the +\atentryref{symbol} type. The definition provided in the \ext{glstex} +file is: +\begin{verbatim} +\providecommand{\bibglsnewsymbol}[4]{% + \longnewglossaryentry*{#1}{name={#3},sort={#1},category={symbol},#2}{#4}% +} +\end{verbatim} +Note that this sets the \field{sort} field to the label, but this +may be overridden by the \meta{options} if the \field{sort} field +was supplied or if \bibgls\ has determined the value whilst sorting +the entries. + +This also sets the \field{category} to \optfmt{symbol}, but again this may +be overridden by \meta{options} if the entry had the \field{category} +field set in the \ext{bib} file or if the \field{category} was +overridden with \optref[\meta{value}]{category}. + +\subsection{\csfmt{bibglsnewnumber}} +\labelcs{bibglsnewnumber} + +\begin{definition} +\cs{bibglsnewnumber}\margm{label}\margm{options}\margm{name}\margm{description} +\end{definition} +This command is used to define terms identified with the +\atentryref{number} type. The definition provided in the \ext{glstex} +file is: +\begin{verbatim} +\providecommand{\bibglsnewnumber}[4]{% + \longnewglossaryentry*{#1}{name={#3},sort={#1},category={number},#2}{#4}% +} +\end{verbatim} +This is much the same as \cs{bibglsnewsymbol} above but sets the +\field{category} to \optfmt{number}. Again the \field{sort} and +\field{category} keys may be overridden by \meta{options}. + +\subsection{\csfmt{bibglsnewindex}} +\labelcs{bibglsnewindex} + +\begin{definition} +\cs{bibglsnewindex}\margm{label}\margm{options} +\end{definition} +This command is used to define terms identified with the +\atentryref{index} type. The definition provided in the \ext{glstex} +file is: +\begin{verbatim} +\providecommand*{\bibglsnewindex}[2]{% + \newglossaryentry{#1}{name={#1},description={},#2}% +} +\end{verbatim} +This makes the \field{name} default to the \meta{label} and sets +an empty \field{description}. These settings may be overridden by +\meta{options}. Note that the \field{description} doesn't include +\cs{nopostdesc} to allow for the post-description hook used by +category attributes. + +\subsection{\csfmt{bibglsnewabbreviation}} +\labelcs{bibglsnewabbreviation} + +\begin{definition} +\cs{bibglsnewabbreviation}\margm{label}\margm{options}\margm{short}\margm{long} +\end{definition} +This command is used to define terms identified with the +\atentryref{abbreviation} type. The definition provided in the \ext{glstex} +file is: +\begin{verbatim} +\providecommand{\bibglsnewabbreviation}[4]{% + \newabbreviation[#2]{#1}{#3}{#4}% +} +\end{verbatim} +Since this uses \cs{newabbreviation}, it obeys the current +abbreviation style for its given \field{category} (which may have +been set in \meta{options}, either from the \field{category} field +in the \ext{bib} file or through the \optref{category} option). +Similarly the \field{type} will obey \cs{glsxtrabbrvtype} unless +the value is supplied in the \ext{bib} file or through the +\optref{type} option. + +\subsection{\csfmt{bibglsnewacronym}} +\labelcs{bibglsnewacronym} + +\begin{definition} +\cs{bibglsnewacronym}\margm{label}\margm{options}\margm{short}\margm{long} +\end{definition} +This command is used to define terms identified with the +\atentryref{acronym} type. The definition provided in the \ext{glstex} +file is: +\begin{verbatim} +\providecommand{\bibglsnewacronym}[4]{% + \newacronym[#2]{#1}{#3}{#4}% +} +\end{verbatim} +This works in much the same way as \cs{bibglsnewabbreviation}. +Remember that with the \sty{glossaries-extra} package \cs{newacronym} +is redefined to just use \cs{newabbreviation} with the default \field{type} +set to \cs{acronymtype} and the default \field{category} set to +\cs{acronym}. + +\subsection{\csfmt{bibglsnewdualentry}} +\labelcs{bibglsnewdualentry} + +\begin{definition} +\cs{bibglsnewdualentry}\margm{label}\margm{options}\margm{name}\margm{description} +\end{definition} +This command is used to define terms identified with the +\atentryref{dualentry} type. The definition provided in the \ext{glstex} +file is: +\begin{verbatim} +\providecommand{\bibglsnewdualentry}[4]{% + \longnewglossaryentry*{#1}{name={#3},#2}{#4}% +} +\end{verbatim} + +\subsection{\csfmt{bibglsnewdualentryabbreviation}} +\labelcs{bibglsnewdualentryabbreviation} + +\begin{definition} +\cs{bibglsnewdualentryabbreviation}\margm{label}\margm{options}\margm{short}\margm{long}\margm{description} +\end{definition} +This command is used to define primary terms identified with the +\atentryref{dualentryabbreviation} type. The definition provided in the \ext{glstex} +file is: +\begin{verbatim} +\providecommand{\bibglsnewdualentryabbreviation}[5]{% + \newabbreviation[#2]{#1}{#3}{#4}% +} +\end{verbatim} +Note that this definition ignores the \meta{description} argument. + +\subsection{\csfmt{bibglsnewdualentryabbreviationsecondary}} +\labelcs{bibglsnewdualentryabbreviationsecondary} + +\begin{definition} +\cs{bibglsnewdualentryabbreviationsecondary}\margm{label}\margm{options}\margm{short}\margm{long}\margm{description} +\end{definition} +This command is used to define secondary terms identified with the +\atentryref{dualentryabbreviation} type. The definition provided in the \ext{glstex} +file is: +\begin{verbatim} +\providecommand{\bibglsnewdualentryabbreviationsecondary}[5]{% + \longnewglossaryentry*{#1}{#2}{#5}% +} +\end{verbatim} +Note that this definition ignores the \meta{short} and \meta{long} +arguments (which will typically be empty unless the default mappings +are changed). + +\subsection{\csfmt{bibglsnewdualsymbol}} +\labelcs{bibglsnewdualsymbol} + +\begin{definition} +\cs{bibglsnewdualsymbol}\margm{label}\margm{options}\margm{name}\margm{description} +\end{definition} +This command is used to define terms identified with the +\atentryref{dualsymbol} type. The definition provided in the \ext{glstex} +file is: +\begin{verbatim} +\providecommand{\bibglsnewdualsymbol}[4]{% + \longnewglossaryentry*{#1}{name={#3},sort={#1},category={symbol},#2}{#4}} +\end{verbatim} + +\subsection{\csfmt{bibglsnewdualnumber}} +\labelcs{bibglsnewdualnumber} + +\begin{definition} +\cs{bibglsnewdualnumber}\margm{label}\margm{options}\margm{name}\margm{description} +\end{definition} +This command is used to define terms identified with the +\atentryref{dualnumber} type. The definition provided in the \ext{glstex} +file is: +\begin{verbatim} +\providecommand{\bibglsnewdualnumber}[4]{% + \longnewglossaryentry*{#1}{name={#3},sort={#1},category={symbol},#2}{#4}} +\end{verbatim} + +\subsection{\csfmt{bibglsnewdualabbreviation}} +\labelcs{bibglsnewdualabbreviation} + +\begin{definition} +\cs{bibglsnewdualabbreviation}\margm{label}\margm{options}\margm{short}\margm{long} +\end{definition} +This command is used to define terms identified with the +\atentryref{dualabbreviation} type where the \field{duallong} field +is swapped with the \field{long} field and the \field{dualshort} +field is swapped with the \field{short} field. The definition provided in the +\ext{glstex} file is: +\begin{verbatim} +\providecommand{\bibglsnewdualabbreviation}[4]{% + \newabbreviation[#2]{#1}{#3}{#4}% +} +\end{verbatim} + +\subsection{\csfmt{bibglsnewdualacronym}} +\labelcs{bibglsnewdualacronym} + +\begin{definition} +\cs{bibglsnewdualacronym}\margm{label}\margm{options}\margm{short}\margm{long} +\end{definition} +This command is used to define terms identified with the +\atentryref{dualacronym} type. The definition provided in the \ext{glstex} +file is: +\begin{verbatim} +\providecommand{\bibglsnewdualacronym}[4]{% + \newacronym[#2]{#1}{#3}{#4}% +} +\end{verbatim} +This works in much the same way as \cs{bibglsnewdualabbreviation}. +Remember that with the \sty{glossaries-extra} package \cs{newacronym} +is redefined to just use \cs{newabbreviation} with the default \field{type} +set to \cs{acronymtype} and the default \field{category} set to +\cs{acronym}. + +\section{Location Lists and Cross-References} +\label{sec:loclistdefs} + +These commands deal with the way the location lists and cross +references are formatted. The commands typically aren't used until +the entry information is displayed in the glossary, so you may +redefine these commands after the resource file has been loaded. + +\subsection{\csfmt{bibglsseesep}} +\labelcs{bibglsseesep} + +\begin{definition} +\cs{bibglsseesep} +\end{definition} + +Any entries that provide a \field{see} field (and that field hasn't +be omitted from the location list with \csopt[omit]{see}) will +have \cs{bibglsseesep} inserted between the \field{see} part and the +location list (unless there are no locations, in which case just +the \field{see} part is displayed without \cs{bibglsseesep}). + +This command is provided with: +\begin{verbatim} +\providecommand{\bibglsseesep}{, } +\end{verbatim} +You can define this before you load the \ext{bib} file: +\begin{verbatim} +\newcommand{\bibglsseesep}{; } +\GlsXtrLoadResources[src={entries}] +\end{verbatim} +Or you can redefine it afterwards: +\begin{verbatim} +\GlsXtrLoadResources[src={entries}] +\renewcommand{\bibglsseesep}{; } +\end{verbatim} + +\subsection{\csfmt{bibglsseealsosep}} +\labelcs{bibglsseealsosep} + +\begin{definition} +\cs{bibglsseealsosep} +\end{definition} + +This is like \cs{bibglsseesep} but is used with cross-reference +lists provided with the \field{seealso} field, if supported. + +\subsection{\csfmt{bibglspassim}} +\labelcs{bibglspassim} + +\begin{definition} +\cs{bibglspassim} +\end{definition} + +If \optref{max-loc-diff} is greater than 1, then any ranges that have +skipped over gaps will be followed by \cs{bibglspassim}, which is +defined as: +\begin{verbatim} +\providecommand{\bibglspassim}{ \bibglspassimname} +\end{verbatim} +You can define this before you load the \ext{bib} file: +\begin{verbatim} +\newcommand{\bibglspassim}{} +\GlsXtrLoadResources[src={entries}] +\end{verbatim} +Or you can redefine it afterwards: +\begin{verbatim} +\GlsXtrLoadResources[src={entries}] +\renewcommand{\bibglspassim}{} +\end{verbatim} + +\subsection{\csfmt{bibglspassimname}} +\labelcs{bibglspassimname} + +\begin{definition} +\cs{bibglspassimname} +\end{definition} + +The default definition is obtained from the \langxml. For example, with \file{bib2gls-en.xml} the provided +definition is +\begin{verbatim} +\providecommand{\bibglspassimname}{passim} +\end{verbatim} + +\subsection{\csfmt{bibglsrange}} +\labelcs{bibglsrange} + +\begin{definition} +\cs{bibglsrange}\marg{\meta{start}\cs{delimR} \meta{end}} +\end{definition} + +Explicit ranges formed using \glsopt[(]{format} and +\glsopt[)]{format} or \glsopt[(\meta{csname}]{format} and +\glsopt[)\meta{csname}]{format} (where \meta{csname} matches and is a +text-block command without the initial backslash) in the optional +argument of commands like \cs{gls} or \cs{glsadd} are encapsulated within +the argument of \cs{bibglsrange}. By default this simply does its +argument. This command is not used with ranges that are formed by collating +consecutive locations. + +\subsection{\csfmt{bibglsinterloper}} +\labelcs{bibglsinterloper} + +\begin{definition} +\cs{bibglsinterloper}\margm{location} +\end{definition} + +If an explicit range conflicts with a record, a warning will be +issued and the conflicting record will be shifted to the front +of the range inside the argument of \cs{bibglsinterloper}. +The default definition just does \meta{location}\cs{delimN} +so that it fits neatly into the list. + +For example, suppose on page~4 of my document I start a range with +\begin{verbatim} +\glsadd[format={(}]{sample} +\end{verbatim} +and end it on page~9 with +\begin{verbatim} +\glsadd[format={)}]{sample} +\end{verbatim} +This forms an explicit range, but let's suppose on page~6 I +have +\begin{verbatim} +\gls[format={hyperbf}]{sample} +\end{verbatim} +This record conflicts with the explicit range (which doesn't include +\texttt{hyperbf} in the format). This causes a warning and +the conflicting entry will be moved before the start of the +explicit range resulting in \textbf{6}, 4--9. + +Note that implicit ranges can't be formed from interlopers (nor can +implicit ranges be merged with explicit ones), +so if \verb|\gls[format={hyperbf}]{sample}| also occurs +on pages~7 and~8 then the result will be \textbf{6}, \textbf{7}, +\textbf{8}, 4--9. Either remove the explicit range or +remove the conflicting entries. (Alternatively, redefine +\cs{bibglsinterloper} to ignore its argument, which will +discard the conflicting entries.) + +\subsection{\csfmt{bibglspostlocprefix}} +\labelcs{bibglspostlocprefix} + +\begin{definition} +\cs{bibglspostlocprefix} +\end{definition} + +If the \optref{loc-prefix} option is on, \csref{bibglslocprefix} will +be inserted at the start of location lists. The command \cs{bibglspostlocprefix} +is placed after the prefix text. This command is provided with: +\begin{verbatim} +\providecommand{\bibglspostlocprefix}{\ } +\end{verbatim} +which puts a space between the prefix text and the location list. +You can define this before you load the \ext{bib} file: +\begin{verbatim} +\newcommand{\bibglspostlocprefix}{: } +\GlsXtrLoadResources[src={entries},loc-prefix] +\end{verbatim} +Or you can redefine it afterwards: +\begin{verbatim} +\GlsXtrLoadResources[src={entries},loc-prefix] +\renewcommand{\bibglspostlocprefix}{: } +\end{verbatim} + +\subsection{\csfmt{bibglslocprefix}} +\labelcs{bibglslocprefix} + +\begin{definition} +\cs{bibglslocprefix}\margm{n} +\end{definition} + +If the \optref{loc-prefix} option is on, this command will be +provided. If the glossary type has been provided by \optref{type} +(and \optref{dual-type} if there are any dual entries) then the +definition of \cs{bibglslocprefix} will be appended to the glossary +preamble for the given type (or types if there are dual entries). +For example, if the document has +\begin{verbatim} +\GlsXtrLoadResources[type=main,loc-prefix={p.,pp.},src={entries}] +\end{verbatim} +and there are no dual entries, then the following will be added to +the \ext{glstex} file: +\begin{verbatim} +\apptoglossarypreamble[main]{% + \providecommand{\bibglslocprefix}[1]{% + \ifcase##1 + \or p.\bibglspostlocprefix + \else pp.\bibglspostlocprefix + \fi + }% +} +\end{verbatim} +However, if the \csopt{type} key is missing, then the following will +be added instead: +\begin{verbatim} +\appto\glossarypreamble{% + \providecommand{\bibglslocprefix}[1]{% + \ifcase#1 + \or p.\bibglspostlocprefix + \else pp.\bibglspostlocprefix + \fi + }% +} +\end{verbatim} + +\subsection{\csfmt{bibglspagename}} +\labelcs{bibglspagename} + +\begin{definition} +\cs{bibglspagename} +\end{definition} + +If \csopt[true]{loc-prefix} is used, then this command is provided +using the value of \texttt{tag.page} from the \langxml. For example with \file{bib2gls-en.xml} the definition is: +\begin{verbatim} +\providecommand{\bibglspagename}{Page} +\end{verbatim} + +\subsection{\csfmt{bibglspagesname}} +\labelcs{bibglspagesname} + +\begin{definition} +\cs{bibglspagesname} +\end{definition} + +If \csopt[true]{loc-prefix} is used, then this command is provided +using the value of \texttt{tag.pages} from the \langxml. For example with \file{bib2gls-en.xml} the definition is: +\begin{verbatim} +\providecommand{\bibglspagesname}{Pages} +\end{verbatim} + +\subsection{\csfmt{bibglslocsuffix}} +\labelcs{bibglslocsuffix} + +\begin{definition} +\cs{bibglslocsuffix}\margm{n} +\end{definition} + +If the \optref{loc-suffix} option is on, this command will be +provided. If the glossary type has been provided by \optref{type} +(and \optref{dual-type} if there are any dual entries) then the +definition of \cs{bibglslocsuffix} will be appended to the glossary +preamble for the given type (or types if there are dual entries). + +This commands definition depends on the value provided by +\optref{loc-suffix}. For example, with \csopt[\cs{@}.]{loc-suffix} +the command is defined as: +\begin{verbatim} +\providecommand{\bibglslocsuffix}[1]{\@.} +\end{verbatim} +(which ignores the argument). + +Whereas with \csopt[\meta{A}\dcomma\meta{B}\dcomma\meta{C}]{loc-suffix} +the command is defined as: +\begin{verbatim} +\providecommand{\bibglslocsuffix}[1]{\ifcase#1 A\or B\else C\fi} +\end{verbatim} + +Note that this is slightly different from \cs{bibglslocprefix} as +it includes the 0 case, which in this instance means that there were +no locations but there was a cross-reference. This command isn't +added when the location list is empty. + +\subsection{\csfmt{bibglslocationgroup}} +\labelcs{bibglslocationgroup} + +\begin{definition} +\cs{bibglslocationgroup}\margm{n}\margm{counter}\margm{list} +\end{definition} + +When the \optref{loc-counters} option is used, the locations +for each entry are grouped together according to the counter +(in the order specified in the value of \optref{loc-counters}). +Each group of locations is encapsulated within +\cs{bibglslocationgroup}, where \meta{n} is the number +of locations within the group, \meta{counter} is the +counter name and \meta{list} is the formatted location sub-list. +By default, this simply does \meta{list}, but may be +defined (before the resources are loaded) or redefined +(after the resources are loaded) as required. + +For example: +\begin{verbatim} +\newcommand*{\bibglslocationgroup}[3]{% + \ifnum#1=1 + #2: + \else + #2s: + \fi + #3% +} + +\GlsXtrLoadResources[ + loc-counters={equation,page},% group locations by counter + src={entries}% data in entries.bib +] +\end{verbatim} +This will prefix each group with the counter name, if there's +only one location, or the counter name followed by \qt{s}, +if there are multiple locations within the group. + +There are various ways to adapt this to translate the counter +name to a different textual label, such as: +\begin{verbatim} +\providecommand{\pagename}{Page} +\providecommand{\pagesname}{Pages} +\providecommand{\equationname}{Equation} +\providecommand{\equationsname}{Equations} + +\newcommand*{\bibglslocationgroup}[3]{% + \ifnum#1=1 + \ifcsdef{#2name}{\csuse{#2name}}{#2}: + \else + \ifcsdef{#2sname}{\csuse{#2sname}}{#2s}: + \fi + #3% +} +\end{verbatim} + +\subsection{\csfmt{bibglslocationgroupsep}} +\labelcs{bibglslocationgroupsep} + +\begin{definition} +\cs{bibglslocationgroupsep} +\end{definition} + +When the \optref{loc-counters} option is set, this command +is used to separate each location sub-group. It may be defined +before the resources are loaded: +\begin{verbatim} +\newcommand*{\bibglslocationgroupsep}{; } + +\GlsXtrLoadResources[ + loc-counters={equation,page},% group locations by counter + src={entries}% data in entries.bib +] +\end{verbatim} +or redefined after the resources are loaded: +\begin{verbatim} +\GlsXtrLoadResources[ + loc-counters={equation,page},% group locations by counter + src={entries}% data in entries.bib +] + +\renewcommand*{\bibglslocationgroupsep}{; } +\end{verbatim} + +\subsection{\csfmt{bibglssupplemental}} +\labelcs{bibglssupplemental} + +\begin{definition} +\cs{bibglssupplemental}\margm{n}\margm{list} +\end{definition} + +When the \optref{supplemental-locations} option is used, the locations +from a supplementary document are encapsulated within the \meta{list} +part of \cs{bibglssupplemental}. The first argument \meta{n} +(ignored by default) is the number of supplementary locations. + +\subsection{\csfmt{bibglssupplementalsep}} +\labelcs{bibglssupplementalsep} + +\begin{definition} +\cs{bibglssupplementalsep} +\end{definition} + +The separator between the main location list and the supplementary +location list. By default this is just \cs{delimN}. This may be +defined before the resources are loaded: +\begin{verbatim} +\newcommand{\bibglssupplementalsep}{; } + +\GlsXtrLoadResources[ + supplemental-locations=supplDoc, + src={entries}] +\end{verbatim} +or redefined after the resources are loaded: +\begin{verbatim} +\GlsXtrLoadResources[ + supplemental-locations=supplDoc, + src={entries}] + +\renewcommand{\bibglssupplementalsep}{; } +\end{verbatim} + +\section{Letter Groups} +\label{sec:lettergroupdefs} + +The commands listed in this section are provided for use with the +\argref{group} switch and glossary styles that display the letter +group title. If these need their definitions altered, they should +be defined before the resource file is loaded (rather than redefined +afterwards). + +The base \sty{glossaries} package determines group titles through a fairly +simplistic rule. Both \app{makeindex} and \app{xindy} write the +line +\begin{alltt} +\cs{glsgroupheading}\margm{heading} +\end{alltt} +to the associated glossary file at the start of each new letter group. +For example, the \qt{A} letter group will be written as: +\begin{verbatim} +\glsgroupheading{A} +\end{verbatim} +This is quite straightforward and the heading title can just be +\qt{A}. The \qt{Symbols} group is written as +\begin{verbatim} +\glsgroupheading{glssymbols} +\end{verbatim} +To allow for easy translation, the base \sty{glossaries} package has +the simple rule: +\begin{itemize} +\item if \csfmt{\meta{heading}groupname} exists use that; +\item otherwise just use \meta{heading}. +\end{itemize} +There's no \csfmt{Agroupname} provided, but \cs{glssymbolsgroupname} +is provided and is supported by the associated language modules, +such as \styfmt{glossaries-french}. (Similarly for the \qt{Numbers} +group.) + +The glossary styles that provide hyperlinks to the groups (such as +\glostyle{indexhypergroup}) use \meta{heading} to form the target +name. A problem arises when active characters occur in +\meta{heading}, which happens with extended characters and +\sty{inputenc}. + +The \sty{glossaries-extra} package (as from version 1.14) provides +\begin{definition} +\cs{glsxtrsetgrouptitle}\margm{label}\margm{title} +\end{definition} +to set the title for a group with the given label. The internal +workings of \cs{glsgroupheading} are modified to use a slightly +altered rule: +\begin{itemize} +\item if a title has been set using +\cs{glsxtrsetgrouptitle}\margm{heading}\margm{title} for the given +\meta{heading}, use that; +\item if \csfmt{\meta{heading}groupname} exists, use that; +\item just use \meta{heading} for the title. +\end{itemize} +So if \cs{glsxtrsetgrouptitle} hasn't been used, it falls back on +the original rule. + +The problem is now how to make the indexing application use the +desired label in the argument of \cs{glsgroupheading} instead of selecting +the heading based on the first character of each sort value for each +top-level entry in that group. This can't be done with +\app{makeindex}, and with \app{xindy} it requires a custom language +module, which isn't a trivial task. + +With \bibgls, a different approach is used. The \ext{glstex} file +created isn't comparable to the \ext{gls} file created by +\app{makeindex} or \app{xindy}. There's nowhere for \bibgls\ to +write the \cs{glsgroupheading} line as it isn't creating the code +that typesets the glossary list. Instead it's creating the code that +defines the entries. The actual group heading is inserted by +\cs{printunsrtglossary} and it's only able to do this by checking if +the entry has a \field{group} field and comparing it to the previous +entry's \field{group} field. + +The collators used by the locale and letter-based rules save the +following information for each entry based on the first significant letter of +the \field{sort} field (if the letter is recognised as alphabetical, +according to the rule): +\begin{itemize} +\item \meta{title} The group's title. This is typically title-cased. +For example, if the rule recognises the digraph \qt{dz}, then the +title is \qt{Dz}. Exceptions to this are included in the \langxml. +If the key \texttt{grouptitle.case.\meta{lc}} exists, where +\meta{lc} is the lower case version of \meta{title}, then the value +of that key is used instead. For example, the Dutch digraph \qt{ij} +should be converted to \qt{IJ}, so \file{bib2gls-en.xml} includes: +\begin{verbatim} +<entry key="grouptitle.case.ij">IJ</entry> +\end{verbatim} +(See the \argref{group} switch for more details.) +\item \meta{letter} This is the actual letter at the start of the +given entry's \field{sort} field, which may be lower case or may +contain diacritics that don't appear in \meta{title}. +\item \meta{id} A numeric identifier. This may be the collation key +or the code point for the given letter, depending on the sort +method. +\item \meta{type} The entry's glossary type. If not known, this will +be empty. (\bibgls\ won't know if you've modified the associated +\csfmt{bibglsnew...} command to set the \field{type}. It can only +know the type if it's in the original \ext{bib} definition or is set +using resource options such as \optref{type}.) +\end{itemize} + +The \field{group} field is then set using: +\begin{alltt} +group=\marg{\cs{bibglslettergroup}\margm{title}\margm{letter}\margm{id}\margm{type}} +\end{alltt} +This field needs to expand to a simple label, which \csref{bibglslettergroup} +is designed to do. Note that non-letter groups are dealt with +separately (see below). + +\subsection{\csfmt{bibglssetlettergrouptitle}} +\labelcs{bibglssetlettergrouptitle} + +For each group that's detected, \bibgls\ will write the line: +\begin{definition} +\cs{bibglssetlettergrouptitle}\marg{\margm{title}\margm{letter}\margm{id}\margm{type}} +\end{definition} +in the \ext{glstex} file, which sets the group's title using +\begin{alltt} +\cs{glsxtrsetgrouptitle}\margm{group label}\margm{group title} +\end{alltt} +where the \meta{group label} part matches the corresponding \field{group} +value. + +Note that \cs{bibglssetlettergrouptitle} only has a single +argument, but that argument contains the four arguments needed by +\csref{bibglslettergroup} and \csref{bibglslettergrouptitle}. +These arguments are as described above. + +If \cs{glsxtrsetgrouptitle} has been defined (\sty{glossaries-extra} +version 1.14 onwards), then \cs{bibglssetlettergrouptitle} will be +defined as +\begin{verbatim} +\providecommand{\bibglssetlettergrouptitle}[1]{% + \glsxtrsetgrouptitle{\bibglslettergroup#1}{\bibglslettergrouptitle#1}} +\end{verbatim} +If an earlier version of \sty{glossaries-extra} is used, then this +function can't be supported and the command will be defined to +simply ignore its argument. This will fall back on the original +method of just using \meta{title} as the label. + +Since \cs{bibglssetlettergrouptitle} is used in the \ext{glstex} file to +set the group titles, the associated commands need to be defined +before the resource file is loaded if their definitions require +modification. After the resource file has been loaded, you can +adjust the title of a specific group, but you'll need to check the +\ext{glstex} file for the appropriate arguments. For example, if the +\ext{glstex} file contains: +\begin{alltt} +\cs{bibglssetlettergrouptitle}\marg{\marg{\AE}\marg{\ae}\marg{7274496}\marg{}} +\end{alltt} +but you actually want the group title to appear as \qt{\AE\ (AE)} +instead of just \qt{\AE}, then after the resource file has been +loaded you can do: +\begin{alltt} +\cs{glsxtrsetgrouptitle} + \marg{\cs{bibglslettergroup}\marg{\AE}\marg{\ae}\marg{7274496}\marg{}}\% label + \marg{\AE\ (AE)}\% title +\end{alltt} + +\subsection{\csfmt{bibglslettergroup}} +\labelcs{bibglslettergroup} + +\begin{definition} +\cs{bibglslettergroup}\margm{title}\margm{letter}\margm{id}\margm{type} +\end{definition} +This command is used to determine the letter group label. The +default definition is \meta{type}\meta{id}, which ensures that no +problematic characters occur in the label since \meta{type} can't +contains special characters and \meta{id} is numeric. The +\meta{type} is included in case there are multiple glossaries, since +the hyperlink name must be unique. + +\subsection{\csfmt{bibglslettergrouptitle}} +\labelcs{bibglslettergrouptitle} + +\begin{definition} +\cs{bibglslettergrouptitle}\margm{title}\margm{letter}\margm{id}\margm{type} +\end{definition} +This command is used to determine the letter group title. +The default definition is \cs{unexpanded}\margm{title}, which guards +against any expansion issues that may arise with characters outside +the basic Latin set. + +For example: +\begin{verbatim} +@entry{angstrom, + name={\AA ngstr\"om} + description={a unit of length equal to one hundred-millionth +of a centimetre} +} +\end{verbatim} +The \field{sort} value is \qtt{\AA ngstr\"om}. With \optref[en]{sort} +the \meta{title} part will be \texttt{A} but with \optref[sv]{sort} +the \meta{title} part will be \texttt{\AA}. In both cases the +\meta{letter} argument will be \texttt{\AA}. + +Take care if you are using a script that needs encapsulating. For +example, with the \sty{CJKutf8} package the CJK characters need to +be placed within the \env{CJK} environment, so any letter group +titles that contain CJK characters will need special attention. + +For example, suppose the \ext{bib} file contains entries in the +form: +\begin{alltt} +\atentryref{dualentry}\marg{\meta{label}, + name = \marg{\cs{cjkname}\margm{CJK characters}}, + description = \margm{English description} +} +\end{alltt} +and the document contains: +\begin{verbatim} +\usepackage{CJKutf8} +\usepackage[record,style=indexgroup,nomain]{glossaries-extra} + +\newglossary*{japanese}{Japanese to English} +\newglossary*{english}{English to Japanese} + +\newrobustcmd{\cjkname}[1]{\begin{CJK}{UTF8}{min}#1\end{CJK}} +\glsnoexpandfields + +\GlsXtrLoadResources[ + src=testcjk,% bib file + sort={ja-JP},% locale used to sort primary entries + dual-sort={en-GB},% locale used to sort secondary entries + type=japanese,% put the primary entries in the 'japanese' glossary + dual-type=english,% put the primary entries in the 'english' glossary + dual-prefix={en.} +] +\end{verbatim} +then CJK characters will appear in the \meta{title} argument of +\cs{bibglslettergrouptitle} which causes a problem because they need +to be encapsulated within the \env{CJK} environment. This can be more +conveniently done with the user supplied \csfmt{cjkname}, but the CJK +characters need to be protected from expansion so \cs{unexpanded} is +also needed. The new definition of \cs{bibglslettergrouptitle} needs +to be defined before \cs{GlsXtrLoadResources}. For example: +\begin{verbatim} +\newcommand{\bibglslettergrouptitle}[4]{\unexpanded{\cjkname{#1}}} +\end{verbatim} +There's a slight problem here in that the English letter group titles +also end up encapsulated. An alternative approach is to use the +\meta{type} part to provide different forms. For example: +\begin{verbatim} +\newcommand*{\englishlettergroup}[1]{#1} +\newcommand*{\japaneselettergroup}[1]{\cjkname{#1}} +\newcommand{\bibglslettergrouptitle}[4]{% + \unexpanded{\csuse{#4lettergroup}{#1}}} +\end{verbatim} +(\csfmt{csuse} is provided by \sty{etoolbox}, which is automatically +loaded by the \styfmt{glossaries} package.) + +\subsection{\csfmt{bibglssetothergrouptitle}} +\labelcs{bibglssetothergrouptitle} + +The group label and title for non-alphabetic characters (symbols) +are dealt with in a similar way to the letter groups, but in this +case the title is set using +\begin{definition} +\cs{bibglssetothergrouptitle}\marg{\margm{character}\margm{id}\margm{type}} +\end{definition} +This is defined in an analogous manner: +\begin{verbatim} +\providecommand{\bibglssetothergrouptitle}[1]{% + \glsxtrsetgrouptitle{\bibglsothergroup#1}{\bibglsothergrouptitle#1}} +\end{verbatim} +where the group label is obtained using \csref{bibglsothergroup} and +the group title is obtained from \csref{bibglsothergrouptitle}. +Note that since non-alphabetic characters don't have upper or lower +case versions, there are only three arguments. The other difference +between this and the letter group version is that the \meta{id} is +given in hexadecimal format (corresponding to the character code). + +For example, suppose my \ext{bib} file contains: +\begin{verbatim} +@entry{sauthor, + name={/Author}, + description = {author string} +} +\end{verbatim} +If a locale sort is used, the leading slash \texttt{/} will be +ignored and this entry will belong to the \qt{A} letter group using +the letter commands described above. If, instead, one of the +character code sort methods are used, such as +\optref[letter-case]{sort}, then this entry will be identified as +belonging to a symbol (or \qt{other}) group and the title will be +set using: +\begin{verbatim} +\bibglssetothergrouptitle{{/}{2F}{}} +\end{verbatim} + +\subsection{\csfmt{bibglsothergroup}} +\labelcs{bibglsothergroup} + +\begin{definition} +\cs{bibglsothergroup}\margm{character}\margm{id}\margm{type} +\end{definition} +This expands to the group label for symbol groups. This just +defaults to \texttt{glssymbols} (ignoring all arguments), which +replicates the label used when \app{makeindex} or \app{xindy} +generate the glossary files. + +\subsection{\csfmt{bibglsothergrouptitle}} +\labelcs{bibglsothergrouptitle} + +\begin{definition} +\cs{bibglsothergrouptitle}\margm{character}\margm{id}\margm{type} +\end{definition} +This expands to the group title for symbol groups. This just +expands to \cs{glssymbolsgroupname} by default. + +\subsection{\csfmt{bibglssetnumbergrouptitle}} +\labelcs{bibglssetnumbergrouptitle} + +The numeric sort methods all create number groups instead of letter +or symbol groups. These behave in an analogous way to the above. +\begin{definition} +\cs{bibglssetnumbergrouptitle}\marg{\margm{value}\margm{id}\margm{type}} +\end{definition} +In this case \meta{value} is the actual numeric sort value, and +\meta{id} is a decimal number obtained from converting \meta{value} +to an integer. This command is defined as +\begin{verbatim} +\providecommand{\bibglssetnumbergrouptitle}[1]{% + \glsxtrsetgrouptitle{\bibglsnumbergroup#1}{\bibglsnumbergrouptitle#1}} +\end{verbatim} + +\subsection{\csfmt{bibglsnumbergroup}} +\labelcs{bibglsnumbergroup} + +The number group label is obtained from: +\begin{definition} +\cs{bibglsnumbergroup}\margm{value}\margm{id}\margm{type} +\end{definition} +This just defaults to \texttt{glsnumbers}. + +\subsection{\csfmt{bibglsnumbergrouptitle}} +\labelcs{bibglsnumbergrouptitle} + +The number group title is obtained from: +\begin{definition} +\cs{bibglsnumbergrouptitle}\margm{value}\margm{id}\margm{type} +\end{definition} +This just defaults to \cs{glsnumbersgroupname}. + +\subsection{\csfmt{bibglshypergroup}} +\labelcs{bibglshypergroup} + +\begin{definition} +\cs{bibglshypergroup}\margm{type}\margm{group id} +\end{definition} + +If the \ext{log} file indicates that \sty{hyperref} has been loaded +and the \longarg{group} switch is used, then this command will be +used to create the navigation information for glossary styles such +as \glostyle{indexhypergroup}. + +\section{Flattened Entries} +\label{sec:flattendefs} + +These commands relate to the way the \field{name} field is altered +when flattening lonely child entries with the \optref{flatten-lonely} +option. + +\subsection{\csfmt{bibglsflattenedhomograph}} +\labelcs{bibglsflattenedhomograph} + +\begin{definition} +\cs{bibglsflattenedhomograph}\margm{name}\margm{parent label} +\end{definition} +The default definition simply does \meta{name}. + +This command is used if the child and parent name's are identical. +For example, suppose the \ext{bib} file contains: +\begin{verbatim} +@index{super.glossary, name={glossary}} + +@entry{glossarycol, + parent={super.glossary}, + description={collection of glosses} +} + +@entry{glossarylist, + parent={super.glossary}, + description={list of technical words} +} +\end{verbatim} +The child entries don't have a \field{name} field, so the value is assumed +to be the same as the parent's \field{name} field. Here's an example +document where both child entries are used: +\begin{verbatim} +\documentclass{article} + +\usepackage[record,subentrycounter,style=treenoname]{glossaries-extra} + +\GlsXtrLoadResources[src={entries}] + +\begin{document} +\gls{glossarycol} (collection) vs \gls{glossarylist} (list). + +\printunsrtglossary +\end{document} +\end{verbatim} +This uses one of the glossary styles designed for homographs and the +glossary has the structure: +\begin{flushleft} +\textbf{glossary}\par +\quad 1) collection of glosses 1\par +\quad 2) list of technical words 1 +\end{flushleft} +If only one child entry is selected, then the result looks a little +odd. For example: +\begin{flushleft} +\textbf{glossary}\par +\quad 1) collection of glosses 1 +\end{flushleft} +With the \optref{flatten-lonely} option, the parent is removed and +the child is moved up a hierarchical level. With +\optref[postsort]{flatten-lonely} this would normally adjust the +name so that it appears as \meta{parent name}, \meta{child name} +but in this case it would look a little odd for the name to +appear as \qt{glossary, glossary} so instead the name is +set to +\begin{verbatim} +\bibglsflattenedhomograph{glossary}{super.glossary} +\end{verbatim} +(where the first argument is the original name and the second argument is the +label of the parent entry). + +This means that the name simply appears as \qt{glossary}, even if +the \optref[postsort]{flatten-lonely} option is used. Note that if +the parent entry is removed, the parent label won't be of much use. +You can test for existence using \cs{ifglsentryexists} (provided by +the \sty{glossaries} package) in case you want to vary the way the +name is displayed according to whether or not the parent is still +present. + +\subsection{\csfmt{bibglsflattenedchildpresort}} +\labelcs{bibglsflattenedchildpresort} + +\begin{definition} +\cs{bibglsflattenedchildpresort}\margm{child name}\margm{parent name} +\end{definition} + +Used by the \optref[presort]{flatten-lonely} option. This defaults +to just \meta{child name}. If you want to change this, remember that +you can let the interpreter know by adding the definition to +\atentry{preamble}. For example: +\begin{verbatim} +@preamble{"\providecommand{\bibglsflattenedchildpresort}[2]{#1 (#2)}"} +\end{verbatim} + +\subsection{\csfmt{bibglsflattenedchildpostsort}} +\labelcs{bibglsflattenedchildpostsort} + +\begin{definition} +\cs{bibglsflattenedchildpostsort}\margm{parent name}\margm{child name} +\end{definition} + +Used by the \optref[postsort]{flatten-lonely} option. This defaults +to \texttt{\meta{parent name}, \meta{child name}}. + +Note that the arguments are in the reverse order to those of the +previous command. This is done to assist the automated first letter +upper-casing. If either command is redefined to alter the ordering, +then this can confuse the case-changing mechanism, in which case you +may want to consider switching on the expansion of the \field{name} +field using: +\begin{verbatim} +\glssetexpandfield{name} +\end{verbatim} +(before \cs{GlsXtrLoadResources}). + +\chapter{Converting Existing \filefmt{.tex} to \filefmt{.bib}} +\label{sec:gls2bib} + +If you have already been using the \sty{glossaries} or +\sty{glossaries-extra} package with a large file containing all your +definitions using commands like \cs{newglossaryentry}, then you can +use the supplementary tool \app{convertgls2bib} to convert the definitions +to the \ext{bib} format required by \bibgls. The syntax is: +\begin{alltt} +convertgls2bib \oargm{options} \meta{tex file} \meta{bib file} +\end{alltt} +where \meta{tex file} is the \ext{tex} file and \meta{bib file} is +the \ext{bib} file. This application is less secure than \bibgls\ as +it doesn't use \app{kpsewhich} to check \texttt{openin\_any} and +\texttt{openout\_any}. Take care not to accidentally overwrite +existing \ext{bib} files as there's no check to determine if +\meta{bib file} already exists. + +The \meta{options} are: +\begin{description} +\item[\longargfmt{texenc} \meta{encoding}] The character encoding of the +\ext{tex} file. If omitted, the operating system's default encoding +is assumed (or the Java Virtual Machine's). + +\item[\longargfmt{bibenc} \meta{encoding}] The character encoding of the +\ext{bib} file. If omitted, the same encoding as the +\ext{tex} file is assumed. + +\item[\longargfmt{space-sub} \meta{replacement}] The \ext{bib} +format doesn't allow spaces in labels. If your original +definitions in your \ext{tex} file have spaces, use this option to +replace spaces in labels. Each space will be substituted with +\meta{replacement}. The cross-referencing fields, \field{see}, +\field{seealso} and \field{alias}, will also be adjusted, but any +references using \cs{gls} etc will have to be substituted manually +(or use a global search and replace in your text editor). +If you want to strip the spaces, use an empty string for +\meta{replacement}. You'll need to delimit this according to your +operating system. For example: +\begin{verbatim} +gls2bib --space-sub '' entries.tex entries.bib +\end{verbatim} + +\item[\longargfmt{help} or \shortargfmt{h}] Display help message and +quit. +\item[\longargfmt{version} or \shortargfmt{v}] Display version +information and quit. +\end{description} + +This application recognises the commands listed below. Avoid any +overly complicated code within the \ext{tex} file. The \TeX\ parser +library isn't a \TeX\ engine! +In all cases below, if \meta{\keyvallist} contains +\begin{alltt} +see=[\cs{seealsoname}]\margm{label(s)} +\end{alltt} +this will be substituted with +\begin{alltt} +seealso=\margm{label(s)} +\end{alltt} +For example: +\begin{verbatim} +\newterm[see={[\seealsoname]goose}]{duck} +\end{verbatim} +will be written as +\begin{verbatim} +@index{duck, + seealso = {goose} +} +\end{verbatim} +(The \field{seealso} key is provided by \sty{glossaries-extra} +v1.16+.) + +Additionally, if \meta{\keyvallist} contains +\begin{alltt} +type=\marg{\cs{glsdefaulttype}} +\end{alltt} +then this field will be ignored. (This \field{type} value is +recommended in \meta{\keyvallist} when loading files with +\cs{loadglsentries}\oargm{type}\margm{file} to allow the optional +argument to set the \field{type}. With \bibgls\ you can use the +\optref{type} option instead.) + +\section{\cs{newglossaryentry}} +The base \sty{glossaries} package provides: +\begin{definition} +\cs{newglossaryentry}\margm{label}\margm{\keyvallist} +\end{definition} + +This is converted to: +\begin{alltt} +\atentryref{entry}\marg{\meta{label}, + \meta{\keyvallist} +} +\end{alltt} + +\cs{newentry} (provided by the \sty{glossaries-extra} +\styopt{shortcuts} option) is recognised as a synonym of \cs{newglossaryentry}. + +\section{\cs{provideglossaryentry}} +The base \sty{glossaries} package provides: +\begin{definition} +\cs{provideglossaryentry}\margm{label}\margm{\keyvallist} +\end{definition} + +This is converted to: +\begin{alltt} +\atentryref{entry}\marg{\meta{label}, + \meta{\keyvallist} +} +\end{alltt} +but only if \meta{label} hasn't already been defined. + +\section{\cs{longnewglossaryentry}} +The base \sty{glossaries} package provides: +\begin{definition} +\cs{longnewglossaryentry}\margm{label}\margm{\keyvallist}\margm{description} +\end{definition} + +This is converted to: +\begin{alltt} +\atentryref{entry}\marg{\meta{label}, + \meta{\keyvallist}, + description = \margm{description} +} +\end{alltt} + +The starred version provided by the \sty{glossaries-extra} package +is also recognised. The unstarred version strips trailing spaces +from \meta{description}. (This doesn't add \cs{nopostdesc}, but +\sty{glossaries-extra} defaults to \styopt{nopostdot}.) + +\section{\cs{longprovideglossaryentry}} + +The base \sty{glossaries} package provides: +\begin{definition} +\cs{longprovideglossaryentry}\margm{label}\margm{\keyvallist}\margm{description} +\end{definition} + +As above, but only if \meta{label} hasn't already been defined. + +\section{\cs{newterm}} +The base \sty{glossaries} package provides: +\begin{definition} +\cs{newterm}\oargm{\keyvallist}\margm{label} +\end{definition} +(when the \styopt{index} option is used). + +This is converted to: +\begin{alltt} +\atentryref{index}\marg{\meta{label}, + \meta{\keyvallist} +} +\end{alltt} +if the optional argument is present, otherwise it's just converted +to: +\begin{alltt} +\atentryref{index}\marg{\meta{label}} +\end{alltt} + +If \longargfmt{space-sub} is used and \meta{label} contains one or +more spaces, then \field{name} will be set if not included in +\meta{\keyvallist}. For example, if \texttt{entries.bib} +contains +\begin{verbatim} +\newterm{sea lion} +\newterm[seealso={sea lion}]{seal} +\end{verbatim} +then +\begin{verbatim} +gls2bib --space-sub '-' entries.bib entries.tex +\end{verbatim} +will write the terms to \texttt{entries.tex} as +\begin{verbatim} +@index{sea-lion, + name = {sea lion} +} + +@index{seal, + seealso = {sea-lion} +} +\end{verbatim} +whereas just +\begin{verbatim} +gls2bib entries.bib entries.tex +\end{verbatim} +will write the terms to \texttt{entries.tex} as +\begin{verbatim} +@index{sea lion} + +@index{seal, + seealso = {sea lion} +} +\end{verbatim} +which will cause a problem when the \ext{bib} file is parsed +by \bibgls\ (and will probably also cause a problem for +bibliographic management systems). + +\section{\cs{newabbreviation}} +The \sty{glossaries-extra} package provides: +\begin{definition} +\cs{newabbreviation}\oargm{\keyvallist}\margm{label}\margm{short}\margm{long} +\end{definition} + +This is converted to: +\begin{alltt} +\atentryref{abbreviation}\marg{\meta{label}, + short = \margm{short}, + long = \margm{long}, + \meta{\keyvallist} +} +\end{alltt} +if the optional argument is present, otherwise it's converted to: +\begin{alltt} +\atentryref{abbreviation}\marg{\meta{label}, + short = \margm{short}, + long = \margm{long} +} +\end{alltt} + +\section{\cs{newacronym}} +The base \sty{glossaries} package provides: +\begin{definition} +\cs{newacronym}\oargm{\keyvallist}\margm{label}\margm{short}\margm{long} +\end{definition} +(which is redefined by \sty{glossaries-extra} to use +\cs{newabbreviation}). + +As above but uses \atentryref{acronym} instead. + +\section{\cs{glsxtrnewsymbol}} +The \sty{glossaries-extra} package provides: +\begin{definition} +\cs{glsxtrnewsymbol}\oargm{\keyvallist}\margm{label}\margm{symbol} +\end{definition} +(when the \styopt{symbols} option is used). + +This is converted to: +\begin{alltt} +\atentryref{symbol}\marg{\meta{label}, + name = \margm{symbol} +} +\end{alltt} +if the optional argument is missing, otherwise it's converted to: +\begin{alltt} +\atentryref{symbol}\marg{\meta{label}, + name = \margm{symbol}, + \meta{\keyvallist} +} +\end{alltt} +unless \meta{\keyvallist} contains the \field{name} field, +in which case it's converted to: +\begin{alltt} +\atentryref{symbol}\marg{\meta{label}, + \meta{\keyvallist} +} +\end{alltt} + +\cs{newsym} (provided by the \styopt{shortcuts} option) is recognised +as a synonym for \cs{glsxtrnewsymbol}. + +\section{\cs{glsxtrnewnumber}} +The \sty{glossaries-extra} package provides: +\begin{definition} +\cs{glsxtrnewnumber}\oargm{\keyvallist}\margm{label} +\end{definition} +(when the \styopt{numbers} option is used). + +This is converted to: +\begin{alltt} +\atentryref{number}\marg{\meta{label}, + name = \margm{label} +} +\end{alltt} +if the optional argument is missing, otherwise it's converted to: +\begin{alltt} +\atentryref{number}\marg{\meta{label}, + name = \margm{label}, + \meta{\keyvallist} +} +\end{alltt} +if \field{name} isn't listed in \meta{\keyvallist}, +otherwise it's converted to: +\begin{alltt} +\atentryref{number}\marg{\meta{label}, + \meta{\keyvallist} +} +\end{alltt} + +\cs{newnum} (provided by the \styopt{shortcuts} option) is +recognised as a synonym for \cs{glsxtrnewnumber}. + +\section{\cs{newdualentry}} + +\begin{definition} +\cs{newdualentry}\oargm{\keyvallist}\margm{label}\margm{short}\margm{long}\margm{description} +\end{definition} + +This command isn't provided by either \sty{glossaries} or +\sty{glossaries-extra} but is used as an example in the +\sty{glossaries} user manual and in the sample file +\file{sample-dual.tex} that accompanies the \sty{glossaries} +package. Since this command seems to be used quite a bit (given the +number of times it crops up on sites like +\href{https://tex.stackexchange.com/}{\TeX\ on StackExchange}), +\appfmt{convertgls2bib} also supports it unless this command is +defined using \csfmt{newcommand} or \csfmt{renewcommand} in the +input file. In which case the default definition will be overridden. + +If the command definition isn't overridden, then it's converted to +\begin{alltt} +\atentryref{dualentryabbreviation}\marg{\meta{label}, + short = \margm{short}, + long = \margm{long}, + description = \margm{description}, + \meta{\keyvallist} +} +\end{alltt} +if \meta{\keyvallist} is supplied, otherwise it's converted to: +\begin{alltt} +\atentryref{dualentryabbreviation}\marg{\meta{label}, + short = \margm{short}, + long = \margm{long}, + description = \margm{description} +} +\end{alltt} + +For example, if the original \filefmt{.tex} file contains +\begin{verbatim} +\newcommand*{\newdualentry}[5][]{% + \newglossaryentry{main-#2}{name={#4},% + text={#3\glsadd{#2}},% + description={#5},% + #1 + }% + \newacronym{#2}{#3\glsadd{main-#2}}{#4} +} + +\newdualentry{svm}% label + {SVM}% abbreviation + {support vector machine}% long form + {Statistical pattern recognition technique}% description +\end{verbatim} +then the \filefmt{.bib} file will contain +\begin{verbatim} +@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} +} +\end{verbatim} +since \cs{newdualentry} was defined with \cs{newcommand}. However, +if the original file uses \cs{providecommand} or omits the +definition of \cs{newdualentry}, then the \filefmt{.bib} file will +contain: +\begin{verbatim} +@dualentryabbreviation{svm, + short = {SVM}, + description = {Statistical pattern recognition technique}, + long = {support vector machine} +} +\end{verbatim} + +\resetsecnumdepth +\printindex +\end{document} diff --git a/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip b/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip Binary files differnew file mode 100644 index 00000000000..a99d9e215aa --- /dev/null +++ b/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip diff --git a/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip b/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip Binary files differnew file mode 100644 index 00000000000..2d68d27209f --- /dev/null +++ b/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip diff --git a/Master/tlpkg/bin/tlpkg-ctan-check b/Master/tlpkg/bin/tlpkg-ctan-check index 08da819aa52..b55d1f1c6c4 100755 --- a/Master/tlpkg/bin/tlpkg-ctan-check +++ b/Master/tlpkg/bin/tlpkg-ctan-check @@ -87,7 +87,7 @@ my @TLP_working = qw( beebe begingreek begriff beilstein belleek bengali bera berenisadf besjournals bestpapers betababel beton beuron bewerbung bez123 bezos bgreek bgteubner bguq bhcexam - bib-fr bibarts biber bibhtml + bib-fr bib2gls bibarts biber bibhtml biblatex biblatex-abnt biblatex-anonymous biblatex-apa biblatex-archaeology biblatex-arthistory-bonn biblatex-bookinarticle biblatex-bookinother biblatex-bwl diff --git a/Master/tlpkg/libexec/ctan2tds b/Master/tlpkg/libexec/ctan2tds index 8c604f3a178..2d20b21ff6f 100755 --- a/Master/tlpkg/libexec/ctan2tds +++ b/Master/tlpkg/libexec/ctan2tds @@ -1293,6 +1293,7 @@ chomp ($Build = `cd $Master/../Build/source && pwd`); 'apalike' => '&POSTapalike', 'asapsym' => '&POSTasapsym', 'autosp' => '&POSTautosp', + 'bib2gls' => '&POSTbib2gls', 'biber' => '&POSTbiber', 'biblatex' => '&POSTbiblatex', 'bibtex' => '&POSTbibtex', @@ -2263,6 +2264,7 @@ $standardsource = '(\.(bat|c|drv|dtx|fea|fdd|ins|sfd)' 'arabxetex', 'NULL', # dtx with others, why not 'babelbib', 'NULL', # dtx with others, why not 'bbold', $standardsource . '|fonttabl.sty', + 'bib2gls', 'src/', 'biber', '.', # everything, lots to do in post 'bibtexperllibs', '.', # everything 'bigints', 'NULL', @@ -2760,6 +2762,7 @@ $standardttf = '\.ttf|\.TTC'; # scripts to install under texmf*/.../scripts, but not bindir. %specialscripts_nobin = ( + 'bib2gls' => '\.jar$', 'changes' => '\.bash$', 'cloze' => '\.lua$', 'epspdf' => '(epspdf(|\.help|boot|tk)|\.rb|makegray\.pro)$', @@ -2793,6 +2796,7 @@ $standardttf = '\.ttf|\.TTC'; 'adhocfilelist' => 'adhocfilelist\.sh$', 'arara' => 'arara\.sh$', 'authorindex' => 'authorindex$', + 'bib2gls' => '\.sh$', 'bibexport' => 'bibexport\.sh$', 'bundledoc' => '(arlatex|bundledoc)$', 'checkcites' => '\.lua$', @@ -3661,8 +3665,9 @@ sub doscripts { if $linkname eq "texdef"; # latexdef->texdef } else { - # Windows. If a shell script, usually skip. Else copy the wrapper. - if ($s !~ /arara|texosquery/) { # java programs, want wrapper. + # Windows. If a shell script, usually skip, except for Java + # programs. Else copy the wrapper. + if ($s !~ /arara|bib2gls|convertgls2bib|texosquery/) { next if $s =~ /\.sh$/ && $s !~ /-sys\.sh$/; } # @@ -5418,6 +5423,15 @@ sub POSTautosp { &preserve_man_pages ($package); } +sub POSTbib2gls { + print "POST$package - resources xml, src dir\n"; + my $resources_dir = "$DEST/scripts/$package/resources"; + &mv_with_mkdir ("$package-en.xml", $resources_dir); + # + my $source_dir = "$DEST/source/support/$package"; + &SYSTEM ("$MV src $source_dir"); +} + sub POSTbiber { print "POST$package - unpack and install binaries\n"; # we've started with everything under source/. diff --git a/Master/tlpkg/tlpsrc/bib2gls.tlpsrc b/Master/tlpkg/tlpsrc/bib2gls.tlpsrc new file mode 100644 index 00000000000..1b71f7bdd0d --- /dev/null +++ b/Master/tlpkg/tlpsrc/bib2gls.tlpsrc @@ -0,0 +1,2 @@ +binpattern f bin/${ARCH}/${PKGNAME} +binpattern f bin/${ARCH}/convertgls2bib diff --git a/Master/tlpkg/tlpsrc/collection-bibtexextra.tlpsrc b/Master/tlpkg/tlpsrc/collection-bibtexextra.tlpsrc index 59b7f3bf87b..90ea8e53f7c 100644 --- a/Master/tlpkg/tlpsrc/collection-bibtexextra.tlpsrc +++ b/Master/tlpkg/tlpsrc/collection-bibtexextra.tlpsrc @@ -14,6 +14,7 @@ depend archaeologie depend beebe depend besjournals depend bestpapers +depend bib2gls depend bibarts depend biber depend bibexport |