diff options
author | Karl Berry <karl@freefriends.org> | 2024-12-15 21:15:55 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2024-12-15 21:15:55 +0000 |
commit | 779b703a845f90e162434b946fd007362d4559a7 (patch) | |
tree | dd889abb713f980fc159bb87d99d54a8f5b249eb /Master/texmf-dist/source/support/bib2gls/src | |
parent | 0d9db987ade0af3bf5efca7295916e58141f643d (diff) |
bib2gls, with new script datatool2bib (15dec24)
git-svn-id: svn://tug.org/texlive/trunk@73132 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/support/bib2gls/src')
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip | bin | 322888 -> 328951 bytes | |||
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/bib2gls-terms.bib | 4 | ||||
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib | 877 | ||||
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex | 2120 | ||||
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/convertgls2bib.pod | 168 | ||||
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/datatool2bib.pod | 387 | ||||
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip | bin | 33240 -> 24631 bytes | |||
-rw-r--r-- | Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip | bin | 1496140 -> 1643148 bytes |
8 files changed, 2989 insertions, 567 deletions
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 differindex 2e8e1796971..16b1db53ef1 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-src.zip diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-terms.bib b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-terms.bib index 89fcd9682df..602e07d4d57 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls-terms.bib +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls-terms.bib @@ -408,14 +408,14 @@ This can be set with the \csopt{locale} resource option. If not explicitly set, then the default will be the document language, if it has been detected by \sty{tracklang} or identified with - \longarg{locale}, or the \idx{JRE} locale otherwise.} + \commonlongarg{locale}, or the \idx{JRE} locale otherwise.} } @entry{document-locale, name = {document locale}, user1={idx.locale-doc}, description={the locale associated with the document - language (or by \longarg{locale}, if no document language has been + language (or by \commonlongarg{locale}, if no document language has been detected). In the case of a multi-lingual document, this is the locale of the last language resource file to be loaded through \isty{tracklang}'s interface. It's best to explicitly set the locale diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib index 8f33ed27756..b8f98bf7f06 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.bib @@ -107,6 +107,11 @@ name={defining terms} } +@topic{convertercommands, + name={converter commands}, + text={converter command} +} + @topic{formattingcommands, name={formatting commands}, text={formatting command} @@ -2061,7 +2066,8 @@ name}, @mainglscommand{glssetexpandfield, name={\csfmt{gls\-set\-expand\-field}}, user1={\margm{field}}, - description={switches on field expansion for the given field}, + description={switches on field expansion for the given field, +identified by its internal label}, topics={assigncommands,definingterms}, note={\styfmt{glossaries}}, category={command} @@ -2302,6 +2308,16 @@ starred version \csref{glsxtrfmt*}}, category={command} } +@mainglscommand{BibGlsOptions, + name={\csfmt{Bib\-Gls\-Options}}, + user1={\margm{options}}, + description={simply writes global \bibgls\ \meta{options} to the +\ext{aux} file}, + topics={indexing}, + note={\styfmt{glossaries-extra} v1.54+}, + category={command} +} + @mainglscommand{glsxtrresourcefile, name={\csfmt{gls\-xtr\-resource\-file}}, user1={\oargm{options}\margm{filename}}, @@ -2571,6 +2587,20 @@ starred version \csref{glsxtrfmt*}}, parent={resourceoptions} } +@resourceoption{opt.wordify-math-greek, + name={\csoptfmt{wordify\dhyphen math\dhyphen greek}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + +@resourceoption{opt.wordify-math-symbol, + name={\csoptfmt{wordify\dhyphen math\dhyphen symbol}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + @resourceoption{opt.sort-replace, name={\csoptfmt{sort\dhyphen replace}}, user1={\meta{list}}, @@ -3749,6 +3779,13 @@ field\dhyphen locale}}, parent={resourceoptions} } +@resourceoption{opt.ignored-type, + name={\csoptfmt{ignored\dhyphen type}}, + user1={\meta{type}}, + category={resourceoption}, + parent={resourceoptions} +} + @resourceoption{opt.progenitor-type, name={\csoptfmt{progenitor\dhyphen type}}, user1={\meta{type}}, @@ -4438,6 +4475,26 @@ placed at the start of a rule in the \qt{ignored characters} section category={command} } +@glscommand{glsxtrcontrolIrules, + name={\csfmt{gls\-xtr\-control\-I\-rules}}, + user1={}, + description={as \cs{glsxtrcontrolrules} but omits control codes + \hex{0}, \hex{1C}, \hex{1D}, \hex{1E}, \hex{1F} and \hex{7F}}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.54+}, + category={command} +} + +@glscommand{glsxtrcontrolIIrules, + name={\csfmt{gls\-xtr\-control\-II\-rules}}, + user1={}, + description={expands to the ordered set of \qt{information separator} control codes + \hex{1C}, \hex{1D}, \hex{1E}, and \hex{1F}}, + topics={collationsubrules}, + note={\styfmt{glossaries-extra-bib2gls} v1.54+}, + category={command} +} + @glscommand{glsxtrspacerules, name={\csfmt{gls\-xtr\-space\-rules}}, user1={}, @@ -4978,6 +5035,30 @@ and \L/\l\ treated as L/l}, parent={fileformats} } +@fileformat{ext.dbtex, + name={\extfmt{dbtex}}, + category={fileformat}, + parent={fileformats} +} + +@fileformat{ext.dtltex, + name={\extfmt{dtltex}}, + category={fileformat}, + parent={fileformats} +} + +@fileformat{ext.csv, + name={\extfmt{csv}}, + category={fileformat}, + parent={fileformats} +} + +@fileformat{ext.tsv, + name={\extfmt{tsv}}, + category={fileformat}, + parent={fileformats} +} + @index{applications, name={applications}, text={applications} @@ -5037,6 +5118,12 @@ and \L/\l\ treated as L/l}, parent={applications} } +@application{datatool2bib, + name={\appfmt{data\-tool2bib}}, + category={application}, + parent={applications} +} + @index{packages, name={packages}, text={package} @@ -5349,31 +5436,37 @@ and \L/\l\ treated as L/l}, } @package{textcase, - name={\styfmt{textcase}}, + name={\styfmt{text\-case}}, category={package}, parent={packages} } @package{datetime2, - name={\styfmt{datetime2}}, + name={\styfmt{date\-time2}}, category={package}, parent={packages} } @package{datatool-base, - name={\styfmt{datatool\dhyphen base}}, + name={\styfmt{data\-tool\dhyphen base}}, category={package}, parent={packages} } @package{datatool, - name={\styfmt{datatool}}, + name={\styfmt{data\-tool}}, + category={package}, + parent={packages} +} + +@package{datagidx, + name={\styfmt{data\-gidx}}, category={package}, parent={packages} } @package{etoolbox, - name={\styfmt{etoolbox}}, + name={\styfmt{etool\-box}}, category={package}, parent={packages} } @@ -5391,13 +5484,13 @@ and \L/\l\ treated as L/l}, } @package{tracklang, - name={\styfmt{tracklang}}, + name={\styfmt{track\-lang}}, category={package}, parent={packages} } @package{accsupp, - name={\styfmt{accsupp}}, + name={\styfmt{acc\-supp}}, category={package}, parent={packages} } @@ -10178,12 +10271,12 @@ primary formats, if enabled.}, name={switches}, text={switch}, plural={switches}, - see={commandlineoptions,commandlineoptionsgls2bib} + see={commandlineoptions,commandlineoptionsconverter,commandlineoptionsgls2bib,commandlineoptionsdatatool2bib} } @index{--switch, name={\longargfmt{\meta{switch}}}, - see={commandlineoptions,commandlineoptionsgls2bib} + see={commandlineoptions,commandlineoptionsconverter,commandlineoptionsgls2bib,commandlineoptionsdatatool2bib} } @index{commandlineoptions, @@ -10191,85 +10284,100 @@ primary formats, if enabled.}, text={command line option} } +@index{commandlineoptionscommon, + name={command line options (common)}, + text={command line option} +} + +@index{commandlineoptionsconverter, + name={command line options (conversion tools)}, + text={command line option} +} + @index{commandlineoptionsgls2bib, name={command line options (\appfmt{convertgls2bib})}, text={command line option} } -@switch{switch.help, +@index{commandlineoptionsdatatool2bib, + name={command line options (\appfmt{datatool2bib})}, + text={command line option} +} + +@switch{switch.common.help, name={\longargfmt{help}}, symbol={\shortargfmt{h}}, user1={}, category={switch}, - parent={commandlineoptions} + parent={commandlineoptionscommon} } -@switch{switch.version, +@switch{switch.common.version, name={\longargfmt{version}}, symbol={\shortargfmt{v}}, user1={}, category={switch}, - parent={commandlineoptions} + parent={commandlineoptionscommon} } -@switch{switch.debug, +@switch{switch.common.debug, name={\longargfmt{debug}}, user1={\oargm{n}}, category={switch}, - parent={commandlineoptions} + parent={commandlineoptionscommon} } -@switch{switch.debug-mode, +@switch{switch.common.debug-mode, name={\longargfmt{debug\dhyphen mode}}, user1={\meta{setting}}, category={switch}, - parent={commandlineoptions} + parent={commandlineoptionscommon} } -@switch{switch.no-debug, +@switch{switch.common.no-debug, name={\longargfmt{no\dhyphen debug}}, symbol={\longargfmt{nodebug}}, user1={}, category={switch}, - parent={commandlineoptions} + parent={commandlineoptionscommon} } -@switch{switch.verbose, +@switch{switch.common.verbose, name={\longargfmt{verbose}}, user1={}, category={switch}, - parent={commandlineoptions} + parent={commandlineoptionscommon} } -@switch{switch.no-verbose, +@switch{switch.common.no-verbose, name={\longargfmt{no\dhyphen verbose}}, symbol={\longargfmt{noverbose}}, user1={}, category={switch}, - parent={commandlineoptions} + parent={commandlineoptionscommon} } -@switch{switch.silent, +@switch{switch.common.silent, name={\longargfmt{silent}}, user1={}, category={switch}, - parent={commandlineoptions} + parent={commandlineoptionscommon} } -@switch{switch.quiet, +@switch{switch.common.quiet, name={\longargfmt{quiet}}, symbol={\shortargfmt{q}}, user1={}, category={switch}, - parent={commandlineoptions} + parent={commandlineoptionscommon} } -@switch{switch.locale, +@switch{switch.common.locale, name={\longargfmt{locale}}, symbol={\shortargfmt{l}}, user1={\meta{lang}}, category={switch}, - parent={commandlineoptions} + parent={commandlineoptionscommon} } @switch{switch.log-file, @@ -10280,6 +10388,14 @@ primary formats, if enabled.}, parent={commandlineoptions} } +@switch{switch.converter.log-file, + name={\longargfmt{log\dhyphen file}}, + symbol={\shortargfmt{t}}, + user1={\meta{filename}}, + category={switch}, + parent={commandlineoptionsconverter} +} + @switch{switch.dir, name={\longargfmt{dir}}, symbol={\shortargfmt{d}}, @@ -10407,6 +10523,18 @@ primary formats, if enabled.}, parent={commandlineoptions} } +@switch{switch.datatool-sort-markers, + name={\longargfmt{datatool\dhyphen sort\dhyphen markers}}, + category={switch}, + parent={commandlineoptions} +} + +@switch{switch.no-datatool-sort-markers, + name={\longargfmt{no\dhyphen datatool\dhyphen sort\dhyphen markers}}, + category={switch}, + parent={commandlineoptions} +} + @switch{switch.force-cross-resource-refs, name={\longargfmt{force\dhyphen cross\dhyphen resource\dhyphen refs}}, symbol={\shortargfmt{x}}, @@ -10695,55 +10823,55 @@ primary formats, if enabled.}, parent={commandlineoptions} } -@switch{switch.gls2bib.help, - name={\longargfmt{help}}, - symbol={\shortargfmt{h}}, - user1={}, +@switch{switch.converter.texenc, + name={\longargfmt{texenc}}, + user1={\meta{encoding}}, category={switch}, - parent={commandlineoptionsgls2bib} + parent={commandlineoptionsconverter} } -@switch{switch.gls2bib.version, - name={\longargfmt{version}}, - symbol={\shortargfmt{v}}, - user1={}, +@switch{switch.converter.bibenc, + name={\longargfmt{bibenc}}, + user1={\meta{encoding}}, category={switch}, - parent={commandlineoptionsgls2bib} + parent={commandlineoptionsconverter} } -@switch{switch.gls2bib.debug, - name={\longargfmt{debug}}, +@switch{switch.converter.overwrite, + name={\longargfmt{overwrite}}, user1={}, category={switch}, - parent={commandlineoptionsgls2bib} + parent={commandlineoptionsconverter} } -@switch{switch.gls2bib.silent, - name={\longargfmt{silent}}, +@switch{switch.converter.no-overwrite, + name={\longargfmt{no\dhyphen overwrite}}, user1={}, category={switch}, - parent={commandlineoptionsgls2bib} + parent={commandlineoptionsconverter} } -@switch{switch.gls2bib.verbose, - name={\longargfmt{verbose}}, +@switch{switch.converter.preamble-only, + name={\longargfmt{preamble\dhyphen only}}, + symbol={\shortargfmt{p}}, user1={}, category={switch}, - parent={commandlineoptionsgls2bib} + parent={commandlineoptionsconverter} } -@switch{switch.gls2bib.texenc, - name={\longargfmt{texenc}}, - user1={\meta{encoding}}, +@switch{switch.converter.no-preamble-only, + name={\longargfmt{no\dhyphen preamble\dhyphen only}}, + user1={}, category={switch}, - parent={commandlineoptionsgls2bib} + parent={commandlineoptionsconverter} } -@switch{switch.gls2bib.bibenc, - name={\longargfmt{bibenc}}, - user1={\meta{encoding}}, +@switch{switch.converter.space-sub, + name={\longargfmt{space\dhyphen sub}}, + symbol={\shortargfmt{s}}, + user1={\meta{replacement}}, category={switch}, - parent={commandlineoptionsgls2bib} + parent={commandlineoptionsconverter} } @switch{switch.gls2bib.ignore-sort, @@ -10803,11 +10931,45 @@ primary formats, if enabled.}, parent={commandlineoptionsgls2bib} } -@switch{switch.gls2bib.ignore-fields, +@switch{switch.converter.ignore-fields, name={\longargfmt{ignore\dhyphen fields}}, symbol={\shortargfmt{f}}, user1={\meta{list}}, category={switch}, + parent={commandlineoptionsconverter} +} + +@switch{switch.converter.no-ignore-fields, + name={\longargfmt{no\dhyphen ignore\dhyphen fields}}, + category={switch}, + parent={commandlineoptionsconverter} +} + +@switch{switch.converter.field-map, + name={\longargfmt{field\dhyphen map}}, + symbol={\shortargfmt{m}}, + user1={\meta{src=dest list}}, + category={switch}, + parent={commandlineoptionsconverter} +} + +@switch{switch.converter.no-field-map, + name={\longargfmt{no\dhyphen field\dhyphen map}}, + category={switch}, + parent={commandlineoptionsconverter} +} + +@switch{switch.converter.field-case, + name={\longargfmt{field\dhyphen case}}, + user1={\meta{setting}}, + category={switch}, + parent={commandlineoptionsconverter} +} + +@switch{switch.gls2bib.internal-field-map, + name={\longargfmt{internal\dhyphen field\dhyphen map}}, + user1={\meta{src=dest list}}, + category={switch}, parent={commandlineoptionsgls2bib} } @@ -10826,73 +10988,224 @@ primary formats, if enabled.}, parent={commandlineoptionsgls2bib} } -@switch{switch.gls2bib.overwrite, - name={\longargfmt{overwrite}}, - user1={}, +@switch{switch.converter.index-conversion, + name={\longargfmt{index\dhyphen conversion}}, + symbol={\shortargfmt{i}}, category={switch}, - parent={commandlineoptionsgls2bib} + user1={}, + parent={commandlineoptionsconverter} } -@switch{switch.gls2bib.no-overwrite, - name={\longargfmt{no\dhyphen overwrite}}, +@switch{switch.converter.no-index-conversion, + name={\longargfmt{no\dhyphen index\dhyphen conversion}}, + category={switch}, user1={}, + parent={commandlineoptionsconverter} +} + +@switch{switch.gls2bib.absorb-see, + name={\longargfmt{absorb\dhyphen see}}, category={switch}, + user1={}, parent={commandlineoptionsgls2bib} } -@switch{switch.gls2bib.preamble-only, - name={\longargfmt{preamble\dhyphen only}}, - symbol={\shortargfmt{p}}, - user1={}, +@switch{switch.gls2bib.no-absorb-see, + name={\longargfmt{no\dhyphen absorb\dhyphen see}}, category={switch}, + user1={}, parent={commandlineoptionsgls2bib} } -@switch{switch.gls2bib.no-preamble-only, - name={\longargfmt{no\dhyphen preamble\dhyphen only}}, - user1={}, +@switch{switch.datatool2bib.detect-symbols, + name={\longargfmt{detect\dhyphen symbols}}, category={switch}, - parent={commandlineoptionsgls2bib} + parent={commandlineoptionsdatatool2bib} } -@switch{switch.gls2bib.space-sub, - name={\longargfmt{space\dhyphen sub}}, - symbol={\shortargfmt{s}}, - user1={\meta{replacement}}, +@switch{switch.datatool2bib.no-detect-symbols, + name={\longargfmt{no\dhyphen detect\dhyphen symbols}}, category={switch}, - parent={commandlineoptionsgls2bib} + parent={commandlineoptionsdatatool2bib} } -@switch{switch.gls2bib.locale, - name={\longargfmt{locale}}, - user1={\meta{language tag}}, +@switch{switch.datatool2bib.numeric-locale, + name={\longargfmt{numeric\dhyphen locale}}, category={switch}, - parent={commandlineoptionsgls2bib} + user1={\meta{lang-tag}}, + parent={commandlineoptionsdatatool2bib} } -@switch{switch.gls2bib.index-conversion, - name={\longargfmt{index\dhyphen conversion}}, - symbol={\shortargfmt{i}}, +@switch{switch.datatool2bib.label, + name={\longargfmt{label}}, + symbol={\shortargfmt{L}}, category={switch}, - parent={commandlineoptionsgls2bib} + user1={\meta{column-key}}, + parent={commandlineoptionsdatatool2bib} } -@switch{switch.gls2bib.no-index-conversion, - name={\longargfmt{no\dhyphen index\dhyphen conversion}}, +@switch{switch.datatool2bib.auto-label, + name={\longargfmt{auto\dhyphen label}}, + symbol={\shortargfmt{a}}, category={switch}, - parent={commandlineoptionsgls2bib} + parent={commandlineoptionsdatatool2bib} } -@switch{switch.gls2bib.absorb-see, - name={\longargfmt{absorb\dhyphen see}}, +@switch{switch.datatool2bib.no-auto-label, + name={\longargfmt{no\dhyphen auto\dhyphen label}}, category={switch}, - parent={commandlineoptionsgls2bib} + parent={commandlineoptionsdatatool2bib} } -@switch{switch.gls2bib.no-absorb-see, - name={\longargfmt{no\dhyphen absorb\dhyphen see}}, +@switch{switch.datatool2bib.auto-label-prefix, + name={\longargfmt{auto\dhyphen label\dhyphen prefix}}, category={switch}, - parent={commandlineoptionsgls2bib} + user1={\meta{prefix}}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.read, + name={\longargfmt{read}}, + symbol={\shortargfmt{r}}, + category={switch}, + user1={\meta{options}}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.no-read, + name={\longargfmt{no\dhyphen read}}, + category={switch}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.setup, + name={\longargfmt{setup}}, + category={switch}, + user1={\meta{options}}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.save-datum, + name={\longargfmt{save\dhyphen datum}}, + category={switch}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.no-save-datum, + name={\longargfmt{no\dhyphen save\dhyphen datum}}, + category={switch}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.save-value, + name={\longargfmt{save\dhyphen value}}, + category={switch}, + user1={\meta{suffix}}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.no-save-value, + name={\longargfmt{no\dhyphen save\dhyphen value}}, + category={switch}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.save-currency, + name={\longargfmt{save\dhyphen currency}}, + category={switch}, + user1={\meta{suffix}}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.no-save-currency, + name={\longargfmt{no\dhyphen save\dhyphen currency}}, + category={switch}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.split, + name={\longargfmt{split}}, + category={switch}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.no-split, + name={\longargfmt{no\dhyphen split}}, + category={switch}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.adjust-gls, + name={\longargfmt{adjust\dhyphen gls}}, + category={switch}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.no-adjust-gls, + name={\longargfmt{no\dhyphen adjust\dhyphen gls}}, + category={switch}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.strip, + name={\longargfmt{strip}}, + category={switch}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.no-strip, + name={\longargfmt{no\dhyphen strip}}, + category={switch}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.dependency-field, + name={\longargfmt{dependency\dhyphen field}}, + user1 = {\meta{field}}, + category={switch}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.no-dependency-field, + name={\longargfmt{no\dhyphen dependency\dhyphen field}}, + category={switch}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.strip-glsadd, + name={\longargfmt{strip\dhyphen glsadd}}, + category={switch}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.no-strip-glsadd, + name={\longargfmt{no\dhyphen strip\dhyphen glsadd}}, + category={switch}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.strip-acronym-font, + name={\longargfmt{strip\dhyphen acronym\dhyphen font}}, + category={switch}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.no-strip-acronym-font, + name={\longargfmt{no\dhyphen strip\dhyphen acronym\dhyphen font}}, + category={switch}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.strip-case-change, + name={\longargfmt{strip\dhyphen case\dhyphen change}}, + category={switch}, + parent={commandlineoptionsdatatool2bib} +} + +@switch{switch.datatool2bib.no-strip-case-change, + name={\longargfmt{no\dhyphen strip\dhyphen case\dhyphen change}}, + category={switch}, + parent={commandlineoptionsdatatool2bib} } @index{lettergroup, @@ -11292,6 +11605,10 @@ primary formats, if enabled.}, name={\filefmt{convert\-gls2bib.sh}} } +@file{file.datatool2bib.sh, + name={\filefmt{datatool2bib.sh}} +} + @file{file.texparserlib.jar, name={\filefmt{texparserlib.jar}} } @@ -11304,6 +11621,10 @@ primary formats, if enabled.}, name={\filefmt{convert\-gls2bib.jar}} } +@file{file.datatool2bib.jar, + name={\filefmt{datatool2bib.jar}} +} + @file{file.bib2gls.bat, name={\filefmt{bib2gls.bat}} } @@ -13078,6 +13399,25 @@ field value}, category={command} } +@command{MFUblocker, + name={\csfmt{MFU\-block\-er}}, + user1={\margm{cs}}, + description={identifies \meta{cs} as a command that, if it occurs + at the start of the argument of \idx{makefirstuc}, it should prevent + any case-change}, + note={\styfmt{mfirstuc} v2.08+\texparserdefnote}, + category={command} +} + +@command{MFUexcl, + name={\csfmt{MFU\-excl}}, + user1={\margm{cs}}, + description={identifies \meta{cs} as a command whose argument should + not have its case changed}, + note={\styfmt{mfirstuc} v2.08+\texparserdefnote}, + category={command} +} + @glscommand{glsxtrusefield, name={\csfmt{gls\-xtr\-use\-field}}, user1={\margm{entry label}\margm{field label}}, @@ -13550,6 +13890,7 @@ can be referenced in \meta{true} or \meta{false} with description={adds a new key for internal use that can be set in \csref{newglossaryentry}}, topics={definingterms,providingcommands,fieldrefcommands}, + seealso={glsxtrprovidestoragekey}, note={\styfmt{glossaries}}, category={command} } @@ -13693,7 +14034,7 @@ can be referenced in \meta{true} or \meta{false} with category={command} } -@glscommand{loadglsentries, +@mainglscommand{loadglsentries, name={\csfmt{load\-gls\-entries}}, user1={\oargm{type}\margm{file}}, description={locally redefines \cs{glsdefaulttype} @@ -14533,6 +14874,15 @@ usual delay}, category={command} } +@command{include, + name={\csfmt{include}}, + user1={\margm{file}}, + description={clears the page, creates a supplementary \ext{aux} + file, and selectively inputs the given file}, + note={kernel command\texparserdefnote}, + category={command} +} + @command{IfFileExists, name={\csfmt{IfFileExists}}, user1={\margm{file}\margm{true}\margm{false}}, @@ -15557,6 +15907,27 @@ conditional in \csopt{assign-fields} conditionals. This token needs annote={quark} } +@mainglscommand{INTERPRETNOREPL, + name={\csfmt{INTER\-PRET\-NO\-REPL}}, + user1={\margm{element-list}}, + description={as \gls{INTERPRET} but doesn't replace \TeX\ special characters}, + note={\bibgls\ \idx{quark}}, + topics={quark}, + category={command}, + annote={quark} +} + +@mainglscommand{REPLACESPCHARS, + name={\csfmt{RE\-PLACE\-SP\-CHARS}}, + user1={\margm{element-list}}, + description={a \idx{quark} that replaces \TeX\ special characters with commands like + \gls{glsbackslash} which expand to the literal character}, + note={\bibgls\ \idx{quark}}, + topics={quark}, + category={command}, + annote={quark} +} + @mainglscommand{LABELIFY, name={\csfmt{LABEL\-IFY}}, user1={\margm{element-list}}, @@ -17684,6 +18055,27 @@ has three or more items}, category={command} } +@command{DTLgidxParen, + name={\csfmt{DTL\-gidx\-Paren}}, + user1={\margm{text}}, + description={normally expands to \code{ (\meta{text})} but is +locally redefined under certain situations. +Note that \idx{datatool2bib} discards the argument for sorting, +which is different to the behaviour with \sty{datagidx} when +constructing the sort value}, + note={\styfmt{datagidx}}, + category={command} +} + +@command{DTLgidxIgnore, + name={\csfmt{DTL\-gidx\-Ignore}}, + user1={\margm{text}}, + description={normally expands to its argument but is +locally redefined to ignore its argument under certain situations}, + note={\styfmt{datagidx}}, + category={command} +} + @command{si, name={\csfmt{si}}, user1={\margm{unit}}, @@ -18849,6 +19241,192 @@ displays the given entry's \field{text} field}, category={command} } +@glscommand{acronymfont, + name={\csfmt{acronym\-font}}, + user1={\margm{text}}, + description={used by the base \sty{glossaries} package's acronyms to + encapsulate the short form. This command should not be used with + \sty{glossaries-extra}}, + topics={formattingcommands}, + note={\styfmt{glossaries} \& \styfmt{datagidx}}, + category={command} +} + +@mainglscommand{datagidx.newterm, + name={\csfmt{new\-term}\nameparen{\styfmt{datagidx}}}, + text={\csfmt{new\-term}}, + user1={\oargm{\keyvallist}\margm{name}}, + description={defines a new term}, + topics={convertercommands}, + note={\styfmt{datagidx}}, + category={command} +} + +@mainglscommand{datagidx.newacro, + name={\csfmt{new\-acro}\nameparen{\styfmt{datagidx}}}, + text={\csfmt{new\-acro}}, + user1={\oargm{\keyvallist}\margm{short}\margm{long}}, + description={defines a new abbreviation}, + topics={convertercommands}, + note={\styfmt{datagidx}}, + category={command} +} + +@mainglscommand{datagidx.newgidx, + name={\csfmt{new\-gidx}\nameparen{\styfmt{datagidx}}}, + text={\csfmt{new\-gidx}}, + user1={\oargm{\keyvallist}\margm{db-name}\margm{title}}, + description={defines a new database customised for \sty{datagidx}}, + topics={convertercommands}, + note={\styfmt{datagidx}}, + category={command} +} + +@glscommand{datagidx.glsadd, + name={\csfmt{gls\-add}\nameparen{\styfmt{datagidx}}}, + text={\csfmt{gls\-add}}, + user1={\marg{\oargm{format}\meta{label}}}, + description={indexes the term identified by the given label}, + topics={convertercommands}, + note={\styfmt{datagidx}}, + category={command} +} + +@glscommand{datagidx.gls, + name={\csfmt{gls}\nameparen{\styfmt{datagidx}}}, + text={\csfmt{gls}}, + user1={\marg{\oargm{format}\meta{label}}}, + description={indexes and displays the term identified by the given +label with a hyperlink, if supported}, + topics={convertercommands}, + note={\styfmt{datagidx}}, + category={command} +} + +@glscommand{datagidx.glsnl, + name={\csfmt{glsnl}\nameparen{\styfmt{datagidx}}}, + text={\csfmt{glsnl}}, + user1={\marg{\oargm{format}\meta{label}}}, + description={indexes and displays the term identified by the given label +without a hyperlink}, + topics={convertercommands}, + note={\styfmt{datagidx}}, + category={command} +} + +@mainglscommand{DTLsetup, + name={\csfmt{DTLsetup}}, + user1={\margm{options}}, + description={sets default \sty{datatool} options}, + note={\styfmt{datatool-base}\texparserdefnote}, + topics={convertercommands}, + category={command} +} + +@mainglscommand{DTLread, + name={\csfmt{DTLread}}, + user1={\oargm{options}\margm{filename}}, + description={loads a database from the given file, where the +format should be identified in \meta{options}}, + note={\styfmt{datatool}\texparserdefnote\ v3.0+}, + topics={convertercommands}, + category={command} +} + +@glscommand{DTLloaddb, + name={\csfmt{DTLloaddb}}, + user1={\oargm{options}\margm{db-name}\margm{filename}}, + description={loads CSV data from the given file}, + note={\styfmt{datatool}\texparserdefnote}, + topics={convertercommands}, + category={command} +} + +@glscommand{DTLloaddbtex, + name={\csfmt{DTLloaddbtex}}, + user1={\margm{cs}\margm{filename}}, + description={loads \ext{dbtex} data from the given file}, + note={\styfmt{datatool}\texparserdefnote\ v2.20+}, + topics={convertercommands}, + category={command} +} + +@command{DTLwrite, + name={\csfmt{DTLwrite}}, + note={\styfmt{datatool}\texparserdefnote\ v3.0+}, + category={command} +} + +@glscommand{DTLnewcurrencysymbol, + name={\csfmt{DTL\-new\-currency\-symbol}}, + user1={\margm{symbol}}, + description={identifies \meta{symbol} as a currency symbol}, + note={\styfmt{datatool}\texparserdefnote}, + topics={convertercommands}, + category={command} +} + +@glscommand{DTLsetnumberchars, + name={\csfmt{DTLsetnumberchars}}, + user1={\margm{number group char}\margm{decimal char}}, + description={sets the number group and decimal characters}, + note={\styfmt{datatool}\texparserdefnote}, + topics={convertercommands}, + category={command} +} + +@mainglscommand{DTLnewdb, + name={\csfmt{DTLnewdb}}, + user1={\margm{db-name}}, + description={defines a new database}, + note={\styfmt{datatool}\texparserdefnote}, + topics={convertercommands}, + category={command} +} + +@mainglscommand{DTLnewrow, + name={\csfmt{DTL\-new\-row}}, + user1={\margm{db-name}}, + description={creates a new row in the given database}, + note={\styfmt{datatool}\texparserdefnote}, + topics={convertercommands}, + category={command} +} + +@mainglscommand{DTLnewdbentry, + name={\csfmt{DTL\-new\-db\-entry}}, + user1={\margm{db-name}\margm{col-key}\margm{value}}, + description={adds a new entry to the final row of the given database}, + note={\styfmt{datatool}\texparserdefnote}, + topics={convertercommands}, + category={command} +} + +@mainglscommand{DTLaction, + name={\csfmt{DTL\-action}}, + user1={\oargm{options}\margm{action}}, + description={general purpose action command}, + note={\styfmt{datatool}\texparserdefnote\ v3.0+}, + topics={convertercommands}, + category={command} +} + +@mainglscommand{dtlexpandnewvalue, + name={\csfmt{dtl\-expand\-new\-value}}, + description={new values will be expanded before being added to the database}, + note={\styfmt{datatool}\texparserdefnote}, + topics={convertercommands}, + category={command} +} + +@mainglscommand{dtlnoexpandnewvalue, + name={\csfmt{dtl\-no\-expand\-new\-value}}, + description={new values will not be expanded before being added to the database}, + note={\styfmt{datatool}\texparserdefnote}, + topics={convertercommands}, + category={command} +} + @command{tableofcontents, name={\csfmt{table\-of\-contents}}, description={displays the \glsxtrlong{toc} (by reading in the @@ -18863,17 +19441,119 @@ sectioning commands to write to it}, user1={\margm{number}}, description={expands to \meta{number} zero-padded to ensure at least two digits}, + seealso={dtlpadleadingzeros,bibglspaddigits}, note={kernel command\texparserdefnote}, category={command} } @command{IfTeXParserLib, name={\csfmt{If\-TeX\-Parser\-Lib}}, - user1={\margm{interpreter}\margm{\TeX}}, + user1={\margm{parser code}\margm{\TeX\ code}}, description={defined by the \TeX\ parser library to expand to - \meta{interpreter} and by \sty{glossaries-extra-bib2gls} to expand - to \meta{\TeX}}, + \meta{parser code} and by \sty{glossaries-extra-bib2gls} to expand + to \meta{\TeX\ code}}, note={\styfmt{glossaries-extra-bib2gls}\texparserdefnote}, + seealso={IfNotBibGls}, + category={command} +} + +@command{IfNotBibGls, + name={\csfmt{If\-Not\-Bib\-Gls}}, + user1={\margm{not bib2gls}\margm{bib2gls}}, + description={defined by the \bibgls\ interpreter to expand to + \meta{bib2gls} and by \sty{glossaries-extra-bib2gls} to expand + to \meta{not bib2gls}. The command either won't be recognised by other +applications that use the \texparserlib\ or it will expand to its +first argument}, + note={\styfmt{glossaries-extra-bib2gls}\texparserdefnote}, + seealso={IfTeXParserLib}, + category={command} +} + +@command{dtlpadleadingzeros, + name={\csfmt{dtl\-pad\-lead\-ing\-zeros}}, + user1={\margm{num digits}\margm{number}}, + description={expands to \meta{number} zero-padded to ensure at + least \meta{num digits} digits}, + note={\styfmt{datatool-base}\texparserdefnote\ v3.0+}, + category={command} +} + +@command{DTLsortwordlist, + name={\csfmt{DTL\-sort\-word\-list}}, + user1={\margm{clist-var}\margm{handler-cs}}, + description={sorts the given comma-separated list variable, where the values + are preprocessed by the given sort handler function}, + note={\styfmt{datatool-base} v3.0+}, + category={command} +} + +@command{datatoolasciistart, + name={\csfmt{data\-tool\-ascii\-start}}, + description={marker used with \cs{DTLsortwordlist}}, + note={\styfmt{datatool-base}\texparserdefnote\ v3.0+}, + category={command} +} + +@command{datatoolpersoncomma, + name={\csfmt{data\-tool\-person\-comma}}, + description={marker used with \cs{DTLsortwordlist}}, + note={\styfmt{datatool-base}\texparserdefnote}, + category={command} +} + +@command{datatoolplacecomma, + name={\csfmt{data\-tool\-place\-comma}}, + description={marker used with \cs{DTLsortwordlist}}, + note={\styfmt{datatool-base}\texparserdefnote}, + category={command} +} + +@command{datatoolsubjectcomma, + name={\csfmt{data\-tool\-subject\-comma}}, + description={marker used with \cs{DTLsortwordlist}}, + note={\styfmt{datatool-base}\texparserdefnote}, + category={command} +} + +@command{datatoolparenstart, + name={\csfmt{data\-tool\-paren\-start}}, + description={marker used with \cs{DTLsortwordlist}}, + note={\styfmt{datatool-base}\texparserdefnote\ v3.0+}, + category={command} +} + +@command{datatoolctrlboundary, + name={\csfmt{data\-tool\-ctrl\-boundary}}, + description={marker used with \cs{DTLsortwordlist}}, + note={\styfmt{datatool-base}\texparserdefnote\ v3.0+}, + category={command} +} + +@command{datatoolasciiend, + name={\csfmt{data\-tool\-ascii\-end}}, + description={marker used with \cs{DTLsortwordlist}}, + note={\styfmt{datatool-base}\texparserdefnote\ v3.0+}, + category={command} +} + +@command{datatoolparen, + name={\csfmt{data\-tool\-paren}}, + user1={\margm{text}}, + description={marker used with \cs{DTLsortwordlist} for parenthetical +content}, + note={\styfmt{datatool-base}\texparserdefnote\ v3.0+}, + category={command} +} + +@command{dtltexorsort, + name={\csfmt{dtl\-tex\-or\-sort}}, + user1={\margm{normal}\margm{sorting}}, + description={provided for use with \cs{DTLsortwordlist}, this +normally expands to its first argument. Within \cs{DTLsortwordlist} +or when used by the interpreter with \longswitch{datatool-sort-markers} +this command will expand to its second argument instead}, + note={\styfmt{datatool-base}\texparserdefnote\ v3.0+}, category={command} } @@ -18882,6 +19562,7 @@ sectioning commands to write to it}, user1={\margm{num digits}\margm{number}}, description={expands to \meta{number} zero-padded to ensure at least \meta{num digits} digits}, + seealso={dtlpadleadingzeros}, note={\bibgls\ interpreter only}, category={command} } diff --git a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex index a0f931b3b8d..8d78c9d1986 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex +++ b/Master/texmf-dist/source/support/bib2gls/src/bib2gls.tex @@ -232,9 +232,9 @@ documents}} \DTMsavetimestamp{creation}{2017-01-20T15:39:00Z} -\IfFileExists{../java/Bib2Gls.java} +\IfFileExists{../java/common/BibGlsTeXApp} { - \DTMsavefilemoddate{moddate}{../java/Bib2Gls.java} + \DTMsavefilemoddate{moddate}{../java/common/BibGlsTeXApp.java} } { \DTMsavenow{moddate} @@ -512,6 +512,14 @@ Library}} #1{\texorpdfstring{\glsxtrglossentry{#2}}{\string\\#2}}% } +\newcommand{\nameparen}[1]{ (#1)} +\newcommand{\prefixedcssection}[3][\cssectioncmd]{% + {% + \renewcommand{\nameparen}[1]{}% + #1{\texorpdfstring{\glsxtrglossentry{#2.#3}}{\string\\#3}}% + }% +} + \newcommand{\format}[1]{% \gls{#1}\glsentryuseri{#1}% } @@ -1135,7 +1143,13 @@ Library}} \newcommand*{\entryref}[1]{\glslink[format=glsignore]{entry.#1}{\entryfmt{#1}}} -\newcommand{\convertglsbibarg}[2][\subsection]{\argsection[#1]{gls2bib.#2}} +\newcommand{\commonarg}[2][\subsection]{\argsection[#1]{common.#2}} + +\newcommand{\converterarg}[2][\subsection]{\argsection[#1]{converter.#2}} + +\newcommand{\convertglsbibarg}[2][\subsubsection]{\argsection[#1]{gls2bib.#2}} + +\newcommand{\datatoolbibarg}[2][\subsubsection]{\argsection[#1]{datatool2bib.#2}} \newcommand{\argsection}[2][\subsection]{% \def\switcharg{}% @@ -1173,12 +1187,30 @@ Library}} {\string-\string-#1}% } +\newcommand*{\commonlongarg}[1]{% + \texorpdfstring + {\gls{switch.common.#1}}% + {\string-\string-#1}% +} + +\newcommand*{\converterlongarg}[1]{% + \texorpdfstring + {\gls{switch.converter.#1}}% + {\string-\string-#1}% +} + \newcommand*{\convertglsbiblongarg}[1]{% \texorpdfstring {\gls{switch.gls2bib.#1}}% {\string-\string-#1}% } +\newcommand*{\datatoolbiblongarg}[1]{% + \texorpdfstring + {\gls{switch.datatool2bib.#1}}% + {\string-\string-#1}% +} + \newcommand*{\longargpageref}[1]{% \longarg{#1} (page~\glsxtrpageref{switch.#1})}% @@ -1444,7 +1476,7 @@ If you have extensively used the \styfmt{glossaries}~\cite{glossaries} or you may have found yourself creating a large \iext{tex} file containing many definitions that you frequently use in documents. This file can then simply be loaded using \ics{input} or -\ics{loadglsentries}, but a large file like this can be difficult to +\gls{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. @@ -1698,7 +1730,8 @@ Symbol: \idx!{mshiftchar}\cs{gls}\marg{v}\idx!{mshiftchar}. Abbreviation: \cs{gl \cs{printunsrtglossaries} \cmd{end}\marg{document} \end{codeenv} -There are more examples provided in \sectionref{sec:examples}. +There are more examples provided in \sectionref{sec:examples} and +also in the \href{https://www.dickimaw-books.com/gallery/#bib2gls}{\bibgls\ gallery}. Note that there's no need to called \idx!{xindy} or \idx!{makeindex} since \bibgls\ automatically sorts the entries and collates the \glspl{location} @@ -2028,8 +2061,8 @@ Greek characters, Latin characters and Pictographs. Some of the examples in this manual use \ics{newglossary*} to define a new glossary type and some use \ics{newignoredglossary} or -\ics{newignoredglossary*}. Why the starred forms and why define an -\igls{ignoredglossary}? +\ics{newignoredglossary*}. You may be wondering why the starred +forms and why define an \igls{ignoredglossary}? The base \styfmt{glossaries} package was originally designed to work with \idx!{makeindex}. Support for \idx!{xindy} was later added, but @@ -2089,12 +2122,15 @@ have an \igls{ignoredglossary} that doesn't suppress the hyperlinks, which can be obtained with the starred form \ics{newignoredglossary*} provided by \styfmt{glossaries-extra} (or \cs{provideignoredglossary*}). -Some resource options, such as \csopt{master}, \csopt{secondary} and -\csopt{trigger-type}, need to ensure that a +Some resource options, such as \csopt{master}, \csopt{secondary}, +and \csopt{trigger-type}, need to ensure that a required glossary is defined. In this case, \bibgls\ uses \ics{provideignoredglossary*} in the \iext{glstex} file -even if \longarg{no-provide-glossaries} is set. If you -haven't already defined that glossary in the document with \cs{newglossary*}, +even if \longarg{no-provide-glossaries} is set. +Note that only \csopt{ignored-type} uses the unstarred +\ics{provideignoredglossary}. + +If you haven't already defined that glossary in the document with \cs{newglossary*}, you'll need to set the title in the optional argument of \cs{printunsrtglossary} if you don't want the default. The glossary won't be defined on the first run (if the definition is only @@ -2104,7 +2140,8 @@ the document build. If you want \bibgls\ to automatically provide unknown glossaries for all entries that have the \field{type} field set (unrelated to the -\csopt{master}, \csopt{secondary} and \csopt{trigger-type} options) +\csopt{master}, \csopt{secondary}, \csopt{trigger-type} +and \csopt{ignored-type} options) then use the \longarg{provide-glossaries} switch. The base \sty{glossaries} package provides a command that can be @@ -2408,6 +2445,18 @@ so you can change the above to the following: \cs{GlsXtrResourceInitEscSequences} } \end{codeenv} +Note that if new quarks, such as \gls{INTERPRETNOREPL} and \gls{REPLACESPCHARS}, +are added to \bibgls, they may not be included in \cs{GlsXtrResourceInitEscSequences} if they +were introduced to \bibgls\ after the version date of the \sty{glossaries-extra} +package installed on your system. In this case, you will need to add them. For example: +\begin{codeenv} +\cs{renewcommand}*\marg{\cs{glsxtrresourceinit}}\marg{\comment{} + \cs{GlsXtrResourceInitEscSequences} + \cmd{def}\gls{INTERPRETNOREPL}\marg{\idx{cs.string}\gls{INTERPRETNOREPL}}\comment{} + \cmd{def}\gls{REPLACESPCHARS}\marg{\idx{cs.string}\gls{REPLACESPCHARS}}\comment{} +} +\end{codeenv} + This will locally define the quarks listed below. Since \cs{glsxtrresourceinit} is used in a scoped context, the @@ -2452,6 +2501,7 @@ or \idx{regex.dollar} to denote the start and end. \item[Field assignments] The following commands may be used in the \meta{element-list} syntax of \csopt{assign-fields}: \gls{CS}, \gls{MGP}, \gls{LEN}, \gls{TRIM}, \gls{INTERPRET}, +\gls{INTERPRETNOREPL}, \gls{REPLACESPCHARS}, \gls{LC}, \gls{UC}, \gls{FIRSTLC}, \gls{FIRSTUC}, and \gls{TITLE}. \item[Conditionals] The \meta{condition} part of the \csopt{assign-fields} @@ -2544,7 +2594,7 @@ The only external processes that are run by \bibgls\ are calls to \idx{kpsewhich} to check the security settings and locate files on \TeX's path. These are started with Java's \code{ProcessBuilder} class so there should be no issues with spaces or shell special characters -in the argument. The \longarg{debug} switch will write the process +in the argument. The \commonlongarg{debug} switch will write the process call in the transcript file and will delimit the argument in the log with single quote characters for convenience, but the process isn't actually called in that way. @@ -2569,7 +2619,7 @@ valid \idx{IETF} language tag. The appropriate file is searched for in the following order, where \meta{locale} is the \gls{Java-locale} or the value supplied -by the \longarg{locale} switch: +by the \commonlongarg{locale} switch: \begin{enumerate} \item \meta{lang} exactly matches \meta{locale}. For example, my locale is \code{en-GB}, so \bibgls\ will first search @@ -2682,8 +2732,9 @@ the document build}}~\cite{buildglossaries}. \section{Manual Installation} -If you are unable to install \bibgls\ through your \TeX\ package -manager, you can install manually using the instructions below. +In general it's best to install \bibgls\ via your \TeX\ package manager. +However, if you are unable to do this or if you are testing a development version, +you can install manually using the instructions below. Replace \meta{TEXMF} with the path to your local or home TEXMF tree (for example, \filefmt{\glstildechar/texmf}). @@ -2693,10 +2744,18 @@ Copy the files provided to the following locations: (Java application.) \item \meta{TEXMF}\filefmt{/scripts/bib2gls/convertgls2bib.jar} (Java application.) +\item \meta{TEXMF}\filefmt{/scripts/bib2gls/datatool2bib.jar} +(Java application.) +\item \meta{TEXMF}\filefmt{/scripts/bib2gls/bibglscommon.jar} +(Java library.) \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{/scripts/bib2gls/resources/bib2gls-extra-en.xml} +(Extra English resource file.) +\item \meta{TEXMF}\filefmt{/scripts/bib2gls/resources/bib2gls-extra-nl.xml} +(Extra Dutch resource file.) \item \meta{TEXMF}\filefmt{/doc/support/bib2gls/bib2gls.pdf} (This document.) \item \meta{TEXMF}\filefmt{/doc/support/bib2gls/bib2gls-begin.pdf} @@ -2707,24 +2766,27 @@ If you use the Unix \appfmt{man} command, copy the appropriate location. 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 \iext{sh} +provided called \file{bib2gls.sh}, \file{convertgls2bib.sh} and \file{datatool2bib.sh}. +Either copy them directly to somewhere on your path without the \iext{sh} extension, for example: \begin{verbatim} cp bib2gls.sh ~/bin/bib2gls cp convertgls2bib.sh ~/bin/convertgls2bib +cp datatool2bib.sh ~/bin/datatool2bib \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 +symbolic link to them called just \filefmt{bib2gls}, +\filefmt{convertgls2bib} and \filefmt{datatool2bib} from somewhere on your path, for example: \begin{verbatim} cp bib2gls.sh ~/texmf/scripts/bib2gls/ cp convertgls2bib.sh ~/texmf/scripts/bib2gls/ +cp datatool2bib.sh ~/texmf/scripts/bib2gls/ cd ~/bin ln -s ~/texmf/scripts/bib2gls/bib2gls.sh bib2gls ln -s ~/texmf/scripts/bib2gls/convertgls2bib.sh convertgls2bib +ln -s ~/texmf/scripts/bib2gls/datatool2bib.sh datatool2bib \end{verbatim} The \file{texparserlib.jar} file isn't an application but is a library used by both \file{bib2gls.jar} and @@ -2741,10 +2803,10 @@ similar way to the bash scripts. To do this, create a file called @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%" %* +java -jar "%JARPATH%" %* \end{verbatim} Save this file to somewhere on your system's path. -(Similarly for \filefmt{convertgls2bib}.) Note that \TeX\ +(Similarly for \filefmt{convertgls2bib} and \filefmt{datatool2bib}.) Note that \TeX\ distributions for Windows usually convert \iext{jar} files to executables. @@ -2755,6 +2817,7 @@ command prompt or terminal and run the following command: \begin{verbatim} bib2gls --version convertgls2bib --version +datatool2bib --version \end{verbatim} This should display the version information for both applications. @@ -2937,18 +3000,25 @@ The sort values for these entries will be: \qt{John 04}, \qt{John will be typeset as \qt{John~IV}, \qt{John~VI}, \qt{John~IX} and \qt{John~XII}. Note that \ics{bibglspaddigits} is only recognised by the \bibgls\ interpreter. Alternatively, you can use the -\csopt{sort-number-pad} option to pad the numbers. +\csopt{sort-number-pad} option to pad the numbers (or use +\ics{dtlpadleadingzeros} which is also recognised by the +\texparserlib\ and \sty{datatool-base} v3.0+). + +There is a similar command with reversed syntax \ics{IfNotBibGls}, +which is defined by \sty{glossaries-extra-bib2gls} to expand to its +first argument. The \bibgls\ interpreter defines this command to +expand to its second argument. \TeX\ syntax can be quite complicated and, in some cases, far too complicated for simple \idxpl!{regex}. The \texparserlib\ 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 -\idx!{convertgls2bib}). When the \longarg{debug} mode is on, any +\idx!{convertgls2bib}). When the \commonlongarg{debug} mode is on, any warnings or errors triggered by the interpreter will be written to the transcript prefixed with \code{texparserlib:} (the results of the conversions will be included in the transcript as informational messages prefixed with \code{texparserlib:} even with -\longarg{no-debug}). +\commonlongarg{no-debug}). For example, suppose the \ext{bib} file includes: \begin{codeenv} @@ -3115,7 +3185,7 @@ the order: \code{M} ($\mtx{M}$), \code{S} ($\set{S}$), \code{i} ($\imaginary$), \code{v} ($\vec{v}$) and \code{card} ($\card{S}$). In this case, the entries have been sorted according to -the character codes. If you run \bibgls\ with \longarg{verbose} +the character codes. If you run \bibgls\ with \commonlongarg{verbose} the decimal character codes will be included in the transcript. For this example: \begin{alltt} @@ -3126,7 +3196,7 @@ S -> 'S' [83] v -> '\usebox\varrow' [118 8407] \end{alltt} -The \longarg{group} option (in addition to \longarg{verbose}) +The \longarg{group} option (in addition to \commonlongarg{verbose}) will place the letter group in parentheses before the character code list: \begin{alltt} @@ -3145,7 +3215,7 @@ by the interpreter, the sort values will all be changed to \idx{lowercase}. The order is now: \code{i} ($\imaginary$), \code{M} ($\mtx{M}$), \code{S} ($\set{S}$), \code{v} ($\vec{v}$) and \code{card} ($\card{S}$). -The transcript (with \longarg{verbose}) now shows +The transcript (with \commonlongarg{verbose}) now shows \begin{alltt} i -> 'i' [105] card -> '|s|' [124 115 124] @@ -3153,7 +3223,7 @@ M -> 'm' [109] S -> 's' [115] v -> '\usebox\varrow' [118 8407] \end{alltt} -With \longarg{group} (in addition to \longarg{verbose}) +With \longarg{group} (in addition to \commonlongarg{verbose}) the letter groups are again included: \begin{alltt} i -> 'i' (I) [105] @@ -3171,7 +3241,7 @@ locale's alphabet rules. For example, with \csopt[en]{sort} (English, no region or variant), the order becomes: \code{card} ($\card{S}$), \code{i} ($\imaginary$), \code{M} ($\mtx{M}$), \code{S} ($\set{S}$) and -\code{v} ($\vec{v}$). The transcript (with \longarg{verbose}) +\code{v} ($\vec{v}$). The transcript (with \commonlongarg{verbose}) shows the collation keys instead: \begin{alltt} i -> 'i' [0 92 0 0 0 0] @@ -3230,6 +3300,9 @@ or in Windows: \begin{verbatim} set JAVA_TOOL_OPTIONS=-Djava.locale.providers=CLDR,JRE,SPI \end{verbatim} +Note that newer versions of Java support \idx{CLDR} by +default, and the \idx{JRE} synonym for the \code{COMPAT} provider is now +deprecated.\footnote{https://www.oracle.com/java/technologies/javase/jdk21-suported-locales.html} \chapter{Command Line Options} \label{sec:switches} @@ -3243,40 +3316,97 @@ 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. +If you are using an automated build system that makes it difficult +to change the command line options and you have at least version +1.54 of \sty{glossaries-extra} and at least version 4.0 of \bibgls, +then most (but not all) switches can be specified within the +argument of +\nosecformatdef{BibGlsOptions} +This command may be placed anywhere within the preamble, but the +options will always be processed before the resource commands. This +command may be used multiple times. +Unlike the resource options, which are local to the resource set, the options +described here are global and are applied to all resource sets, +where applicable. +For example: +\begin{codeenv} +\gls{BibGlsOptions}\marg{replace-quotes=true} +\gls{GlsXtrLoadResources} +\gls{BibGlsOptions}\marg{collapse-same-location-range=true} +\end{codeenv} +This is equivalent to: +\begin{codeenv} +\gls{BibGlsOptions}\marg{replace-quotes=true,collapse-same-location-range=true} +\gls{GlsXtrLoadResources} +\end{codeenv} +The \meta{options} list should be a \keyvallist\ where the \meta{key} +is the same as the long switch without the preceding +\code{\longswitch}. Any \code{\longswitch no-\meta{option}} should +be specified as \code{\meta{option}=false} within +\gls{BibGlsOptions}. +For example, to set global options via the command line: +\begin{verbatim} +bib2gls --group --no-replace-quotes myDoc +\end{verbatim} +Alternatively, the document may contain: +\begin{codeenv} +\gls{BibGlsOptions}\marg{group=true,replace-quotes=false} +\end{codeenv} +You can omit the value if it is \code{true}, so the above can also +be written: +\begin{codeenv} +\gls{BibGlsOptions}\marg{group,replace-quotes=false} +\end{codeenv} + +\begin{important} +Options that must be set before the \ext{log} and \ext{aux} file are read can +only be set via the command line switch. +\end{important} + \section{Common Options} +\label{sec:commonswitches} + +These command line switches are common to \bibgls\ and the +supplementary command line conversion tools -\argsection{help} +\commonarg{help} Display the help message and quit. +This option cannot be set in \gls{BibGlsOptions}. -\argsection{version} +\commonarg{version} Display the version information and quit. As from v2.5, this now includes the version number of the \file{texparserlib.jar} library. +This option cannot be set in \gls{BibGlsOptions}. -\argsection{verbose} +\commonarg{verbose} Switches on the verbose mode. This writes extra information to the terminal and transcript file. +This option cannot be set in \gls{BibGlsOptions}. -\argsection{no-verbose} +\commonarg{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. +This option cannot be set in \gls{BibGlsOptions}. -\argsection{quiet} +\commonarg{quiet} 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. +This option cannot be set in \gls{BibGlsOptions}. -\argsection{silent} +\commonarg{silent} -Synonym of \longarg{quiet}. +Synonym of \commonlongarg{quiet}. +This option cannot be set in \gls{BibGlsOptions}. -\argsection{locale} +\commonarg{locale} Specify the preferred \langxml, where \meta{lang} is a valid \idx{IETF} language tag. This option requires an appropriate \metafilefmt{bib2gls-}{lang}{.xml} @@ -3286,6 +3416,7 @@ keyword (in options such as \csopt[doc]{sort}) is used and the document doesn't have any language support. Note that the \optfmt{locale} keyword (in options such as \csopt[locale]{sort}) uses the \gls{Java-locale} and is not governed by this switch. +This option cannot be set in \gls{BibGlsOptions}. If a document doesn't have any locale support or has support for more than one language then it's best to explicitly set @@ -3294,224 +3425,7 @@ the \csopt{locale} resource option, to specify the default \gls{resource-locale}, or set the locale for individual options, such as \csopt{sort}. -\argsection{group} - -The \styfmt{glossaries-extra} \styopt{record} package option -automatically creates a new internal field called \field{group}. If the -\longarg{group} switch is used with the default \csopt[auto]{group} -option then, when sorting, \bibgls\ will try -to determine the \idx{group} for each entry and assign it to the -\field{group} field. (Some \csopt{sort} options ignore this -setting.) This value will be picked up by \ics{printunsrtglossary} -if group headings are required (for example with the -\glostyle{indexgroup} style) or if group separators are required -(for example, the \glostyle{index} style with the default -\styopt[false]{nogroupskip}). If you don't require grouping within -the glossary, there's no need to use this switch. Note that this -switch doesn't automatically select an appropriate glossary style. - -If you want \idxpl{sub-group}, you will need to use the \csopt{group-level} -resource option and ensure you have \sty{glossaries-extra} v1.49+. -\Idxpl{smallgroup} can be merged with the \csopt{merge-small-groups} -resource option. - -\begin{important} -The \field{group} field should typically not be set in the \ext{bib} -file and will trigger a warning if found. The explicit use of the -\field{group} key will override \bibgls's normal group formation -behaviour, which can cause unexpected results. The custom use of the -\field{group} field requires some care. As a general rule, if you -find yourself wanting to use the \field{group} field in the -\ext{bib} file, then the chances are that what you actually have is -a \gls{hierarchicalglossary} (list of topics) and what you really -need is the \field{parent} field. Compare the example files -\exfile{sample-textsymbols.tex} and -\exfile{sample-textsymbols2.tex}. See also -\sectionref{sec:logicaldivisions}. -\end{important} -There are eight types of groups: -\begin{description} -\item[\idx{lettergroup}] The first non-ignored character of the -sort value is alphabetic. This type of group occurs when using the -alphabetic sort methods listed in \tableref{tab:sortoptionsrule} or -with the letter sort methods listed in -\tableref{tab:sortoptionsletter} or with the letter-number sort -methods listed in \tableref{tab:sortoptionsletternumber}. The group -label is obtained from \gls!{bibglslettergroup}. - -\item[\idx{nonlettergroup} (or \idx{symbolgroup})] -The first non-ignored character of all the sort values within this group -are non-alphabetical. This type of group occurs when using the -alphabetic sort methods listed in \tableref{tab:sortoptionsrule} or -with the letter sort methods listed in -\tableref{tab:sortoptionsletter} or with the letter-number sort -methods listed in \tableref{tab:sortoptionsletternumber}. -The alphabetic sort methods ignore many punctuation -characters, so an entry that has a non-alphabetic initial -character in the sort value may actually be placed in a -\idx{lettergroup}. -The group label is obtained from \gls!{bibglsothergroup}. - -\item[\idx{emptygroup}] The sort value is empty when sorting with an -alphabetical, letter or letter-number method, typically a -result of the original value consisting solely of commands that \bibgls\ -can't interpret. The group label is obtained from \gls!{bibglsemptygroup}. - -\item[\idx{numbergroup}] The entries were sorted by one of the -numeric comparisons listed in \tableref{tab:sortoptionsnumerical}. -The group label is obtained from \gls!{bibglsnumbergroup}. - -\item[\idx{datetimegroup}] The entries were sorted by one of the date-time -comparisons listed in \tableref{tab:sortoptionsdatetime} (where both -date and time are present). -The group label is obtained from \gls!{bibglsdatetimegroup}. - -\item[\idx{dategroup}] The entries were sorted by one of the date -comparisons (where the time is omitted). -The group label is obtained from \gls!{bibglsdategroup}. - -\item[\idx{timegroup}] The entries were sorted by one of the time -comparisons (where the date is omitted). -The group label is obtained from \gls!{bibglstimegroup}. - -\item[\idx{customgroup}] The group label is explicitly set either by -aliasing a field (with \csopt{field-aliases}) or by using the -\csopt[\meta{label}]{group} resource option. You will need to use -\gls{glsxtrsetgrouptitle} in the document to provide an associated title if the -\meta{label} isn't the same as the title. Remember that with older -\LaTeX\ kernels, the label can't contain any active characters, so -you can't use non-ASCII characters in \meta{label} with -\sty{inputenc} (but you can use non-ASCII alphanumerics with -\sty{fontspec}). To ensure better support for UTF-8 with \pdfLaTeX, make sure you -have a recent \TeX\ distribution and up-to-date versions of -\sty{glossaries} and \sty{glossaries-extra}. - -\end{description} - -The \idx{lettergroup} titles will typically have the first character -converted to \idx{uppercase} for the alphabet sort methods -(\tableref{tab:sortoptionsrule}). 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 \idx{digraph} (two -characters) or \idx{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 \idx{grouptitle.case.lc} key (where -\meta{lc} is the \idx!{lowercase} version), then only the first character -will be converted to \idx{uppercase} otherwise the value supplied by the -resource file is used. This resource key is only checked for -the alphabetical comparisons listed in -\tableref{tab:sortoptionsrule}. 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 \idx{nonlettergroup} (even if the character is -alphabetical). - -The letter (\tableref{tab:sortoptionsletter}) and letter-number -(\tableref{tab:sortoptionsletternumber}) methods only select the -first character of the sort value for the group. If the character is -alphabetical\footnote{according to Java's -\code{Character.isAlphabetic(int)} method} then it will be a -\idx{lettergroup} otherwise it's a \idx{nonlettergroup}. The case-insensitive -ordering (such as \csopt[letter-nocase]{sort}) will convert the -letter group character to \idx{uppercase}. The case-sensitive ordering -(such as \csopt[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 -\cs{cs.makeglossaries} and \cs{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 -\iext{aux} file as -\nosecdef{@gls@hypergroup} -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 \csopt{type} and -\csopt{dual-type}) then this information can be determined when -\bibgls\ is ready to write the \iext{glstex} file, which means that -the extra \LaTeX\ run isn't necessary. If \bibgls\ doesn't know -the glossary type then it will fallback on the original method -which requires an extra \LaTeX\ run. - -For example: -\begin{codeenv} -\cmd{documentclass}\marg{article} -\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} -\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt[indexhypergroup]{style}}\marg{glossaries-extra} -\strut -\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\comment{data in entries.bib} - \csopt[main]{type}\comment{put these entries in the 'main' glossary} -} -\strut -\gls{GlsXtrLoadResources}\oarg{\csopt[abbrvs]{src},\comment{data in abbrvs.bib} - \csopt[abbreviations]{type}\comment{put entries in the 'abbreviations' glossary} -} -\end{codeenv} -Here the \csopt{type} is set and \bibgls\ can detect that -\isty{hyperref} has been loaded, so if the \longargfmt{group} switch -is used, then the group hyperlinks can be set (using -\gls!{bibglshypergroup}). This means that the build process is -just: -\begin{verbatim} -pdflatex myDoc -bibtex --group myDoc -pdflatex myDoc -\end{verbatim} -Note that this requires \isty{glossaries} v4.53+ and -\isty{glossaries-extra} v1.53. If your version of \sty{glossaries} -or \sty{glossaries-extra} is too old, an extra \LaTeX\ run is -required. - -If \isty{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 can't be saved in -the \ext{glstex} file. - -For example: -\begin{codeenv} -\cmd{documentclass}\marg{article} -\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} -\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt[indexhypergroup]{style}}\marg{glossaries-extra} -\strut -\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}\comment{data in entries.bib} -\gls{GlsXtrLoadResources}\oarg{\csopt[abbrvs]{src}}\comment{data in abbrvs.bib} -\end{codeenv} -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 -\styfmt{glossaries} (and \styfmt{glossaries-extra}). - -\argsection{no-group} - -Don't automatically set the \field{group} field with -\csopt[auto]{group} (default). The glossary won't have groups even if a -group style, such as \glostyle{indexgroup}, is used (unless the -\field{group} field is set to a custom value). - -\argsection{debug} +\commonarg{debug} Sometimes when things go wrong it can be hard to diagnose the problem from the normal messages. If you report an issue, you may be asked @@ -3522,7 +3436,8 @@ The \longargfmt{debug} option can be used to switch on debugging mode. If \meta{n} is present, it must be a non-negative integer indicating the debugging mode. If omitted, 1 is assumed. This option also switches on the verbose mode. A value of 0 is equivalent to -\longargfmt{no-debug}. +\commonlongarg{no-debug}. +This option cannot be set in \gls{BibGlsOptions}. The value of \meta{n} determines how much extra information is provided. If \meta{n} is greater than 0 then all \bibgls\ debugging @@ -3541,12 +3456,16 @@ setting. An error message will start with \qt{Error:~} and a warning message will start with \qt{Warning:~}. Unknown commands will throw an exception with a stack trace in debug mode. -\argsection{debug-mode} +\commonarg{debug-mode} This option is an alternative to \longargfmt{debug} where the value -of \meta{n} needs to be calculated. The \meta{setting} is -required and should be a comma-separated list of any of the -following keywords. +of \meta{n} needs to be calculated. +This option cannot be set in \gls{BibGlsOptions}. +Debugging mode requires a +transcript file, which is automatically created with \bibgls, but is +optional for the converter tools (see \sectionref{sec:tex2bib}). The +\meta{setting} is required and should be a comma-separated list of +any of the following keywords. \begin{itemize} \item\optfmt{all}: enable all debugging information @@ -3589,6 +3508,8 @@ list detail (may result in a large transcript file). \item\optfmt{read}: \texparserlib\ file codepoint read (likely to result in a very large transcript file). +\item\optfmt{settings}: \texparserlib\ settings information. + \item\optfmt{sty-data}: data associated with packages used to store information that may not exactly correspond to the way the information is stored in \LaTeX. In the case of \bibgls, this will @@ -3601,14 +3522,17 @@ For example: bib2gls \longargfmt{debug-mode} catcode,sty-data \meta{filename} \end{alltt} -\argsection{no-debug} +\commonarg{no-debug} -Switches off the debugging mode. Equivalent to \longarg{debug}~0. +Switches off the debugging mode. +This option cannot be set in \gls{BibGlsOptions}. \section{File Options} \argsection{dir} +This option cannot be set in \gls{BibGlsOptions}. + By default \bibgls\ assumes that the output files should be written in the current working directory. The input \iext{bib} files are assumed to be either in the current working directory or on \TeX's path (in which @@ -3667,12 +3591,15 @@ same as the \iext{aux} file but with a \iext{glg} extension. Note that if you use \bibgls\ in combination with \idx{xindy} or \idx{makeindex}, you will need to change the transcript file name to prevent conflict. +This option cannot be set in \gls{BibGlsOptions}. The transcript file encoding is governed by \longarg{log-encoding}. \argsection{tex-encoding} +This option cannot be set in \gls{BibGlsOptions}. + In general, it's best to have all your files (\ext{aux}, \ext{bib} and \iext{glstex}) in the same \igls{encoding} that matches your default encoding (see \sectionref{sec:defencoding}). However, if @@ -3697,6 +3624,7 @@ The \igls{encoding} of the \iext{log} file. If omitted, the default encoding will be used. See \sectionref{sec:defencoding}. (Note that the \ext{log} file may not have the same encoding as the \ext{tex} file~\cite{tex.sx.2013}.) +This option cannot be set in \gls{BibGlsOptions}. \argsection{default-encoding} @@ -3707,6 +3635,7 @@ globally change the encoding for the \idx{JVM}, which will affect all Java applications installed on your device, or you can use \longarg{default-encoding} just to set the default for \bibgls. See \sectionref{sec:defencoding}. +This option cannot be set in \gls{BibGlsOptions}. \argsection{date-in-header} @@ -3721,6 +3650,10 @@ timestamp changes. The comment header block at the start of the \iext{glstex} files won't include the file modification date (default). +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{date-in-header=false} +\end{codeenv} \section{Interpreter Options} @@ -3734,6 +3667,10 @@ space. Similarly \ics{nobreakspace} just produces a space. The interpreter treats a tilde character \idx{nbspchar} as a non-breakable space (default). Similarly the interpreter will define \ics{nobreakspace} to produce a non-breakable space character (\hex{00A0}). +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{break-space=false} +\end{codeenv} \argsection{custom-packages} @@ -3746,6 +3683,72 @@ but it can't deal with complicated code. In the case of \ics{RequirePackage}, support will also be governed by \longargfmt{custom-packages}. This option has a cumulative action. +Multiple instances of this switch can occur on the command line. +If used in \gls{BibGlsOptions}, the nature of the \keyvallist\ +parser means that multiple instances within the same option list +will override each other. Instead, you will need a comma-separated +list as the argument. +For example, from the command line: +\begin{verbatim} +bib2gls --custom-packages 'pkg1,pkg2,pkg3' myDoc +\end{verbatim} +This is equivalent to: +\begin{verbatim} +bib2gls --custom-packages pkg1 --custom-packages pkg2 --custom-packages pkg3 myDoc +\end{verbatim} +Alternatively, within the document: +\begin{codeenv} +\gls{BibGlsOptions}\marg{custom-packages=\marg{pkg1,pkg2,pkg3}} +\end{codeenv} + +\argsection{datatool-sort-markers} + +The \sty{datatool-base} package provides some marker commands +designed for use with \ics{DTLsortwordlist}. These commands by +default will be defined to match their normal \sty{datatool-base} +behaviour. + +The \longswitch{datatool-sort-markers} switch will instead define those +marker commands to match their localised definitions within +\cs{DTLsortwordlist}. Additionally, \ics{dtltexorsort} will be +redefined to expand to its second argument. + +Note that you don't need to request the \sty{datatool-base} package, +unless you require support for other commands provided by that +package. + +The marker commands are: \ics{datatoolasciistart}, +\ics{datatoolpersoncomma}, \ics{datatoolplacecomma}, +\ics{datatoolsubjectcomma}, \ics{datatoolparenstart}, +\ics{datatoolctrlboundary}, \ics{datatoolasciiend}, and +\ics{datatoolparen} (see the \sty{datatool} documentation for +further details). With \longswitch{datatool-sort-markers}, these +commands will expand to content that includes special control codes. +Note that language-sensitive sort methods typically ignore control +codes, so these would either need to be used with a character-code +comparator or a custom sort method would need to be used. +For example: +\begin{codeenv} +\csopt[\ics{glsxtrcontrolIrules} + ;\cs{glshex} 0 + ;\cs{glsxtrspacerules} + ;\cs{glsxtrnonprintablerules} + ;\cs{glsxtrcombiningdiacriticrules} + ,\cs{glsxtrhyphenrules} + <\ics{glsxtrcontrolIIrules} + <\cs{glsxtrgeneralpuncrules} + <\cs{glsxtrdigitrules} + <\cs{glsxtrfractionrules} + <\ics{glsxtrGeneralLatinIrules} + <\cs{glshex} 7F +]{sort-rule} +\end{codeenv} + +\argsection{no-datatool-sort-markers} + +Define the \sty{datatool-base} marker commands +(including \cs{dtltexorsort}) to match their normal definition. + \argsection{ignore-packages} This option is cumulative. When the document \iext{log} file is @@ -3756,6 +3759,7 @@ that are identified with \longarg{packages} will be passed to the interpreter if support is available, even if the package is also listed in \longargfmt{ignore-packages}. Note that unknown packages can't be included in the ignored \meta{list}. +This option cannot be set in \gls{BibGlsOptions}. \argsection{interpret} @@ -3766,11 +3770,18 @@ for more details. Switch off the interpreter mode. See \sectionref{sec:texparserlib} for more details about the interpreter. +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{interpret=false} +\end{codeenv} \argsection{list-known-packages} This option will list all the packages supported by the \texparserlib\ -and will then exit \bibgls. The results are divided into two +and will then exit \bibgls. +This option cannot be set in \gls{BibGlsOptions}. + +The results are divided into two sections: those packages that are searched for in the \iext{log} file and those packages that aren't searched for in the \iext{log} file but have some support available. Some of the support is very @@ -3818,7 +3829,11 @@ Instruct the interpreter to assume the packages listed in \meta{list} have been used by the document. This option has a cumulative action so \code{\longarg{packages} "wasysym,pifont"} is the same as \code{\longarg{packages} wasysym -\longarg{packages} pifont}. +\longarg{packages} pifont}. + +This option may also be used in \gls{BibGlsOptions} but, as with +\longarg{custom-packages}, multiple instances of the \code{packages} +key in the same option list will override each other. Note that there's only a limited number of packages supported by the \texparserlib. This option is provided for cases where you're @@ -3874,17 +3889,24 @@ this setting. For example, if \csfmt{superiortwo} is defined as then it will be interpreted as \hex{00B2} (superscript two) even if this setting is on. +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{support-unicode-script=false} +\end{codeenv} + \argsection{obey-aux-catcode} By default, the \ext{aux} parser ignores category code changing commands. This option will instruct the parser to implement the category code, but note that it can only do this for known commands that the parser is able to implement. +This option cannot be set in \gls{BibGlsOptions}. \argsection{no-obey-aux-catcode} Instructs the \ext{aux} parser to ignore category code changing commands. (Default.) +This option cannot be set in \gls{BibGlsOptions}. \section{Record Options} @@ -3904,6 +3926,10 @@ This switch is most useful in conjunction with Don't check for instances of \ics{citation} in the \ext{aux} file (default). +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{cite-as-record=false} +\end{codeenv} \argsection{collapse-same-location-range} @@ -3919,6 +3945,10 @@ Don't collapse any \idx{explicit-range} into a normal \gls{record} if the start and end \glspl{location} are the same. The \idx{explicit-range} will only be able to merge with neighbouring \glspl{location} if \csopt[true]{merge-ranges}. +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{collapse-same-location-range=false} +\end{codeenv} \argsection{map-format} @@ -3927,7 +3957,10 @@ matches (see \sectionref{sec:locationopts}). The argument may be a comma-separated list of \meta{map}\code{:}\meta{value} pairs. Alternatively, you can have multiple instances of \longarg{map-format} \meta{map}\dcolon\meta{value} which have a -cumulative effect. +cumulative effect on the command line. You can also use +\code{map-format} as an option within \gls{BibGlsOptions}, but +multiple instances of this key in the same option list will override +each other. For example, \begin{verbatim} @@ -4088,6 +4121,10 @@ default setting. (See also \csopt{save-index-counter}.) Don't merge an entry's \counter{wrglossary} records. This means that you may end up with duplicate page numbers in the entry's \gls{locationlist}, but they will link to different parts of the page. +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{merge-wrglossary-records=false} +\end{codeenv} \argsection{record-count} @@ -4159,6 +4196,10 @@ obtained by \bibgls\ from the \ext{aux} file. \argsection{no-record-count} Switch off record counting. (Default.) +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{record-count=false} +\end{codeenv} \argsection{record-count-unit} @@ -4173,6 +4214,10 @@ to determine which records should be counted. Switches off unit record counting. (Default.) Note that you need \longarg{no-record-count} to completely switch off record counting. +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{record-count-unit=false} +\end{codeenv} \argsection{record-count-rule} @@ -4232,6 +4277,10 @@ to an ordinary \gls{record}. (You may need to use \argsection{no-retain-formats} Normal \gls{location} merging rules apply (default). +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{retain-formats=false} +\end{codeenv} \section{Bib File Options} @@ -4261,6 +4310,10 @@ have taken appropriate precautions to avoid unexpected results. Switches off the check for non-bib fields. If you use this option you need to make sure you have taken appropriate precautions to avoid unexpected results. +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{warn-non-bib-fields=false} +\end{codeenv} \argsection{warn-unknown-entry-types} @@ -4271,9 +4324,234 @@ will issue a warning with this option set (default). This option will suppress the warning if an unknown \glspl{entrytype} are found in the \ext{bib} file. +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{warn-unknown-entry-types=false} +\end{codeenv} \section{Field Options} +\argsection{group} + +The \styfmt{glossaries-extra} \styopt{record} package option +automatically creates a new internal field called \field{group}. If the +\longarg{group} switch is used with the default \csopt[auto]{group} +option then, when sorting, \bibgls\ will try +to determine the \idx{group} for each entry and assign it to the +\field{group} field. (Some \csopt{sort} options ignore this +setting.) This value will be picked up by \ics{printunsrtglossary} +if group headings are required (for example with the +\glostyle{indexgroup} style) or if group separators are required +(for example, the \glostyle{index} style with the default +\styopt[false]{nogroupskip}). If you don't require grouping within +the glossary, there's no need to use this switch. Note that this +switch doesn't automatically select an appropriate glossary style. + +If you want \idxpl{sub-group}, you will need to use the \csopt{group-level} +resource option and ensure you have \sty{glossaries-extra} v1.49+. +\Idxpl{smallgroup} can be merged with the \csopt{merge-small-groups} +resource option. + +\begin{important} +The \field{group} field should typically not be set in the \ext{bib} +file and will trigger a warning if found. The explicit use of the +\field{group} key will override \bibgls's normal group formation +behaviour, which can cause unexpected results. The custom use of the +\field{group} field requires some care. As a general rule, if you +find yourself wanting to use the \field{group} field in the +\ext{bib} file, then the chances are that what you actually have is +a \gls{hierarchicalglossary} (list of topics) and what you really +need is the \field{parent} field. Compare the example files +\exfile{sample-textsymbols.tex} and +\exfile{sample-textsymbols2.tex}. See also +\sectionref{sec:logicaldivisions}. +\end{important} +There are eight types of groups: +\begin{description} +\item[\idx{lettergroup}] The first non-ignored character of the +sort value is alphabetic. This type of group occurs when using the +alphabetic sort methods listed in \tableref{tab:sortoptionsrule} or +with the letter sort methods listed in +\tableref{tab:sortoptionsletter} or with the letter-number sort +methods listed in \tableref{tab:sortoptionsletternumber}. The group +label is obtained from \gls!{bibglslettergroup}. + +\item[\idx{nonlettergroup} (or \idx{symbolgroup})] +The first non-ignored character of all the sort values within this group +are non-alphabetical. This type of group occurs when using the +alphabetic sort methods listed in \tableref{tab:sortoptionsrule} or +with the letter sort methods listed in +\tableref{tab:sortoptionsletter} or with the letter-number sort +methods listed in \tableref{tab:sortoptionsletternumber}. +The alphabetic sort methods ignore many punctuation +characters, so an entry that has a non-alphabetic initial +character in the sort value may actually be placed in a +\idx{lettergroup}. +The group label is obtained from \gls!{bibglsothergroup}. + +\item[\idx{emptygroup}] The sort value is empty when sorting with an +alphabetical, letter or letter-number method, typically a +result of the original value consisting solely of commands that \bibgls\ +can't interpret. The group label is obtained from \gls!{bibglsemptygroup}. + +\item[\idx{numbergroup}] The entries were sorted by one of the +numeric comparisons listed in \tableref{tab:sortoptionsnumerical}. +The group label is obtained from \gls!{bibglsnumbergroup}. + +\item[\idx{datetimegroup}] The entries were sorted by one of the date-time +comparisons listed in \tableref{tab:sortoptionsdatetime} (where both +date and time are present). +The group label is obtained from \gls!{bibglsdatetimegroup}. + +\item[\idx{dategroup}] The entries were sorted by one of the date +comparisons (where the time is omitted). +The group label is obtained from \gls!{bibglsdategroup}. + +\item[\idx{timegroup}] The entries were sorted by one of the time +comparisons (where the date is omitted). +The group label is obtained from \gls!{bibglstimegroup}. + +\item[\idx{customgroup}] The group label is explicitly set either by +aliasing a field (with \csopt{field-aliases}) or by using the +\csopt[\meta{label}]{group} resource option. You will need to use +\gls{glsxtrsetgrouptitle} in the document to provide an associated title if the +\meta{label} isn't the same as the title. Remember that with older +\LaTeX\ kernels, the label can't contain any active characters, so +you can't use non-ASCII characters in \meta{label} with +\sty{inputenc} (but you can use non-ASCII alphanumerics with +\sty{fontspec}). To ensure better support for UTF-8 with \pdfLaTeX, make sure you +have a recent \TeX\ distribution and up-to-date versions of +\sty{glossaries} and \sty{glossaries-extra}. + +\end{description} + +The \idx{lettergroup} titles will typically have the first character +converted to \idx{uppercase} for the alphabet sort methods +(\tableref{tab:sortoptionsrule}). 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 \idx{digraph} (two +characters) or \idx{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 \idx{grouptitle.case.lc} key (where +\meta{lc} is the \idx!{lowercase} version), then only the first character +will be converted to \idx{uppercase} otherwise the value supplied by the +resource file is used. This resource key is only checked for +the alphabetical comparisons listed in +\tableref{tab:sortoptionsrule}. 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 \idx{nonlettergroup} (even if the character is +alphabetical). + +The letter (\tableref{tab:sortoptionsletter}) and letter-number +(\tableref{tab:sortoptionsletternumber}) methods only select the +first character of the sort value for the group. If the character is +alphabetical\footnote{according to Java's +\code{Character.isAlphabetic(int)} method} then it will be a +\idx{lettergroup} otherwise it's a \idx{nonlettergroup}. The case-insensitive +ordering (such as \csopt[letter-nocase]{sort}) will convert the +letter group character to \idx{uppercase}. The case-sensitive ordering +(such as \csopt[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 +\cs{cs.makeglossaries} and \cs{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 +\iext{aux} file as +\nosecdef{@gls@hypergroup} +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 \csopt{type} and +\csopt{dual-type}) then this information can be determined when +\bibgls\ is ready to write the \iext{glstex} file, which means that +the extra \LaTeX\ run isn't necessary. If \bibgls\ doesn't know +the glossary type then it will fallback on the original method +which requires an extra \LaTeX\ run. + +For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt[indexhypergroup]{style}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src},\comment{data in entries.bib} + \csopt[main]{type}\comment{put these entries in the 'main' glossary} +} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[abbrvs]{src},\comment{data in abbrvs.bib} + \csopt[abbreviations]{type}\comment{put entries in the 'abbreviations' glossary} +} +\end{codeenv} +Here the \csopt{type} is set and \bibgls\ can detect that +\isty{hyperref} has been loaded, so if the \longargfmt{group} switch +is used, then the group hyperlinks can be set (using +\gls!{bibglshypergroup}). This means that the build process is +just: +\begin{verbatim} +pdflatex myDoc +bibtex --group myDoc +pdflatex myDoc +\end{verbatim} +Note that this requires \isty{glossaries} v4.53+ and +\isty{glossaries-extra} v1.53. If your version of \sty{glossaries} +or \sty{glossaries-extra} is too old, an extra \LaTeX\ run is +required. + +If \isty{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 can't be saved in +the \ext{glstex} file. + +For example: +\begin{codeenv} +\cmd{documentclass}\marg{article} +\cmd{usepackage}\oarg{colorlinks}\marg{hyperref} +\cmd{usepackage}\oarg{\styopt{record},\styopt{abbreviations},\styopt[indexhypergroup]{style}}\marg{glossaries-extra} +\strut +\gls{GlsXtrLoadResources}\oarg{\csopt[entries]{src}}\comment{data in entries.bib} +\gls{GlsXtrLoadResources}\oarg{\csopt[abbrvs]{src}}\comment{data in abbrvs.bib} +\end{codeenv} +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 +\styfmt{glossaries} (and \styfmt{glossaries-extra}). + +\argsection{no-group} + +Don't automatically set the \field{group} field with +\csopt[auto]{group} (default). The glossary won't have groups even if a +group style, such as \glostyle{indexgroup}, is used (unless the +\field{group} field is set to a custom value). +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{group=false} +\end{codeenv} + \argsection{no-expand-fields} By default, \gls{newglossaryentry} and similar commands expand field values @@ -4290,6 +4568,11 @@ that this automatic expansion is required and since it can also be problematic this option is on by default. You can switch it off with \longarg{expand-fields}. +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{expand-fields=false} +\end{codeenv} + \argsection{expand-fields} Don't write \gls{glsnoexpandfields} to the \iext{glstex} file, @@ -4304,7 +4587,7 @@ before the entries are defined (that is, before using If you have \isty{mfirstuc} v2.08+, \isty{glossaries} v4.50+ and \isty{glossaries-extra} v1.49+ then this setting shouldn't be -required any more as there's now better sentence-case handling. +required any more as there's now better \idx{sentencecase} handling. If these versions are detected in the \ext{log} file then the default will switch to \longarg{no-mfirstuc-protection} otherwise the default is \longarg{mfirstuc-protection}. If this causes any @@ -4350,12 +4633,16 @@ equivalent to \longarg{no-mfirstuc-protection}. The default value is Switches off the \isty{mfirstuc} protection mechanism described above. +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{mfirstuc-protection=false} +\end{codeenv} \argsection{mfirstuc-math-protection} If you have \isty{mfirstuc} v2.08+, \isty{glossaries} v4.50+ and \isty{glossaries-extra} v1.49+ then this setting shouldn't be -required any more as there's now better sentence-case handling. If +required any more as there's now better \idx{sentencecase} handling. If these versions are detected in the \ext{log} file then the default will switch to \longarg{no-mfirstuc-math-protection}. If this causes any problems, use \longarg{mfirstuc-math-protection} to re-enable @@ -4376,6 +4663,10 @@ write a warning in the transcript. This setting is on by default. \argsection{no-mfirstuc-math-protection} Switches off the above. +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{mfirstuc-math-protection=false} +\end{codeenv} \argsection{nested-link-check} @@ -4396,6 +4687,14 @@ list of fields to be checked. \argsection{no-nested-link-check} Equivalent to \longarg{nested-link-check} \optfmt{none}. +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{nested-link-check=none} +\end{codeenv} +or +\begin{codeenv} +\gls{BibGlsOptions}\marg{nested-link-check=false} +\end{codeenv} \argsection{shortcuts} @@ -4478,6 +4777,10 @@ bib2gls --trim-except-fields short --trim-except-fields long myDoc Don't trim any leading or trailing spaces from field values (but see the above note about \sty{xkeyval}). This is the default setting. +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{trim-fields=false} +\end{codeenv} \section{Other Options} @@ -4491,6 +4794,10 @@ Force \igls{crossresourceref} mode on (see Don't force \igls{crossresourceref} mode on (default). The mode will be enabled if applicable (see \sectionref{sec:resourcesets}). +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{force-cross-resource-refs=false} +\end{codeenv} \argsection{provide-glossaries} @@ -4511,10 +4818,14 @@ will prevent an error if the glossary has already been defined. This setting prevents \bibgls\ from providing unknown glossaries, except in a few documented situations (the \csopt{master}, -\csopt{trigger-type} and \csopt{secondary} options). This is the +\csopt{trigger-type}, \csopt{ignored-type} and \csopt{secondary} options). This is the default since it's a useful way of detecting misspelt glossary labels. It's harder to detect the problem if a misspelt label has caused an entry to be added to a hidden glossary. +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{provide-glossaries=false} +\end{codeenv} \argsection{replace-quotes} @@ -4528,6 +4839,10 @@ written to the \ext{glstex} file. Single and double-quote characters (\idx{aposchar} and \idx{doublequotechar}) will be written as those actual characters (default). +If used in \gls{BibGlsOptions}, this option should be specified as +\begin{codeenv} +\gls{BibGlsOptions}\marg{replace-quotes=false} +\end{codeenv} \chapter{\iext{bib} Format} \label{sec:bib} @@ -4693,7 +5008,7 @@ Any special characters found in the sort value are always substituted before writing the \ext{bib} file to avoid syntax errors. Any unrecognised fields will be ignored by \bibgls. This is more -convenient than using \ics{input} or \ics{loadglsentries}, which +convenient than using \ics{input} or \gls{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. @@ -7933,7 +8248,154 @@ Returns its argument with any leading and trailing spaces removed. \nosecdef{INTERPRET} Interprets the contents of \meta{element-list} using \bibgls's interpreter and returns the result, which may be an empty string if -the content only contains unknown commands. +the content only contains unknown commands. Note that the result is +a string with any special characters replaced by detokenized commands, such as +\ics{glsbackslash}. This ensures that the value is suitable to be written +in the entry definition in the \ext{glstex} file. + +It's important to remember that the result of \gls{INTERPRET} is a detokenized string. +In general, it's therefore best to have \gls{INTERPRET} as the outermost quark. + +Suppose I have a \ext{bib} file that contains: +\begin{codeenv} +\atentry{preamble}\marg{\qtdelim{\cs{providecommand}\marg{\cmd{csfmt}}[1]\marg{\cs{glsbackslash} \idx{param}1}}} +\atentry{index}\marg{relax,\field{name}=\marg{\cmd{csfmt}\marg{relax}}} +\atentry{index}\marg{comment,\field{name}=\marg{\cs{cs.percent} comment}} +\end{codeenv} +If the resource options include: +\begin{codeenv} +\csopt[ + \field{user1} = \gls{INTERPRET} \marg{ \field{name} } , +]{assign-fields} +\end{codeenv} +Then the definitions in the \ext{glstex} file will be: +\begin{codeenv} +\gls{bibglsnewindex}\marg{comment}\comment{} +\marg{\field{user1}=\marg{\cs{glspercentchar} \cs{space} comment}, +\field{name}=\marg{\cs{cs.percent} comment}, +\field{sort}=\marg{comment|}} +\strut +\gls{bibglsnewindex}\marg{relax}\comment{} +\marg{\field{user1}=\marg{\cs{glsbackslash} relax}, +\field{name}=\marg{\cmd{csfmt}\marg{relax}}, +\field{sort}=\marg{relax|}} +\end{codeenv} +This ensures that the \LaTeX\ syntax in the \ext{glstex} definitions is valid and +the \field{user1} field can expand to a literal string. (Remember that the document +definition of the custom \csfmt{csfmt} command may be different from the one provided +in the \atentry{preamble} content.) + +The \gls{INTERPRET} quark converts \code{\cs{cs.percent} comment} to +\qtt{\% comment} since the interpreter recognises \ics{cs.percent}. However, +if this value is written to the \ext{glstex} file: +\begin{codeenv} +\field{user1}=\marg{\% comment}, +\end{codeenv} +then this is invalid. When the \ext{glstex} file is input by \gls{GlsXtrLoadResources}, +\LaTeX\ will interpret the percent symbol \code{\%} as a comment and the rest of the +line, including the closing brace, will be ignored. This leads to a missing closing brace error. + +In the case of the \qt{relax} entry, since a definition of the custom \csfmt{csfmt} +is provided in \atentry{preamble}, the interpreter will convert \code{\csfmt{csfmt}\marg{relax}} +to the string \qtt{\csfmt{relax}}. If this value is written to the \ext{glstex} file: +\begin{codeenv} +\field{user1}=\marg{\csfmt{relax}}, +\end{codeenv} +then this would be parsed as the command \csfmt{relax} when the file is input +by \gls{GlsXtrLoadResources}. + +Therefore, \gls{INTERPRET} automatically replaces all the \TeX\ special characters +in the resulting string to ensure that they expand to their literal meanings +in the \LaTeX\ document. + +Now suppose instead that the resource options include: +\begin{codeenv} +\csopt[ + \field{user1} = \gls{FIRSTUC} \marg{ \gls{INTERPRET} \marg{ \field{name} } }, +]{assign-fields} +\end{codeenv} +This first interprets the value of the \field{name} field and substitutes the special +characters (so \code{\csfmt{relax}} becomes the string \qtt{\csfmt{glsbackslash} relax}). +The resulting string is then converted to \idx{sentencecase}, which results in +\qtt{\csfmt{Glsbackslash} relax} because the initial backslash is now a literal character, +and since it's a non-letter character it's skipped by the case-conversion. +So now the code written to the \ext{glstex} file is: +\begin{codeenv} +\gls{bibglsnewindex}\marg{comment}\comment{} +\marg{\field{user1}=\marg{\csfmt{Glspercentchar} \cs{space} comment}, +\field{name}=\marg{\cs{cs.percent} comment}, +\field{sort}=\marg{comment|}} +\strut +\gls{bibglsnewindex}\marg{relax}\comment{} +\marg{\field{user1}=\marg{\csfmt{Glsbackslash} relax}, +\field{name}=\marg{\cmd{csfmt}\marg{relax}}, +\field{sort}=\marg{relax|}} +\end{codeenv} +This is invalid because \csfmt{Glspercentchar} and \csfmt{Glsbackslash} are not defined. + +Suppose the order of the quarks is swapped: +\begin{codeenv} +\csopt[ + \field{user1} = \gls{INTERPRET} \marg{ \gls{FIRSTUC} \marg{ \field{name} } }, +]{assign-fields} +\end{codeenv} +This results in valid \LaTeX\ code: +\begin{codeenv} +\gls{bibglsnewindex}\marg{comment}\comment{} +\marg{\field{user1}=\marg{\cs{glspercentchar} \cs{space} comment}, +\field{name}=\marg{\cs{cs.percent} comment}, +\field{sort}=\marg{comment|}} +\strut +\gls{bibglsnewindex}\marg{relax}\comment{} +\marg{\field{user1}=\marg{\cs{glsbackslash} Relax}, +\field{name}=\marg{\cmd{csfmt}\marg{relax}}, +\field{sort}=\marg{relax|}} +\end{codeenv} +If you don't want the argument of a command to be affected by case-changing +commands, you can use \ics{MFUblocker} or \ics{MFUexcl}. The +\sty{glossaries-extra} package writes this information in the \ext{aux} +file for the benefit of \bibgls. See the \sty{mfirstuc} +manual for further details of those commands. + +\nosecdef{INTERPRETNOREPL} +As \gls{INTERPRET} but doesn't replace special characters. +Consider an adjustment to the previous example: +\begin{codeenv} +\csopt[ + \field{user1} = \gls{FIRSTUC} \marg{ \gls{INTERPRETNOREPL} \marg{ \field{name} } }, +]{assign-fields} +\end{codeenv} +Now \code{\csfmt{csfmt}\marg{relax}} is converted into the literal string +\qtt{\csfmt{relax}} and then the case-conversion is performed, +which results in the literal string \qtt{\csfmt{Relax}} but this will become +an undefined command in the \ext{glstex} file: +\begin{codeenv} +\field{user1}=\marg{\csfmt{Relax}}, +\end{codeenv} +In the case of the \qt{comment} entry, \code{\cs{cs.percent} comment} will +be converted to the literal string \qtt{\% comment}, which will then have the case-conversion +applied, but the \ext{glstex} file will be invalid: +\begin{codeenv} +\field{user1}=\marg{\% Comment}, +\end{codeenv} + +\nosecdef{REPLACESPCHARS} +Detokenises and replaces special characters with commands like \ics{glsbackslash}. +For example: +\begin{codeenv} +\csopt[ + \field{user1} = \gls{REPLACESPCHARS} \marg{ + \gls{FIRSTUC} \marg{ \gls{INTERPRETNOREPL} \marg{ \field{name} } } }, +]{assign-fields} +\end{codeenv} +This rather long-winded assignment produces the same result as: +\begin{codeenv} +\csopt[ + \field{user1} = \gls{INTERPRET} \marg{ \gls{FIRSTUC} \marg{ \field{name} } }, +]{assign-fields} +\end{codeenv} +A difference can be observed if the custom command is made a blocker or exclusion +using \ics{MFUblocker} or \ics{MFUexcl}. \nosecdef{LABELIFY} Converts the contents of \meta{element-list} into a label string, @@ -8051,7 +8513,12 @@ grandparent entry can be referenced with \code{parent \idx{follow} parent \idx{follow}}. Since \qt{parent} is also a field name, if the keyword \code{parent} is followed by \idx{follow} then the keyword refers to the \gls{parententry} otherwise it refers to the -\field{parent} field. +\field{parent} field. For example, +\code{self \idx{follow} parent} refers to the value of the entry's +\field{parent} field, which is the \gls{parententry}['s] label, whereas +\code{parent \idx{follow} name} refers to the value of the entry's parent's +\field{name} field. + The special keywords identify values that aren't normally stored in a field. The keyword must be followed by the \meta{delineator}, @@ -8419,6 +8886,38 @@ the resource option list, if required. If not set, the default will be the \gls{document-locale}, if supplied, otherwise the \gls{Java-locale} will be used. +\optsection{wordify-math-greek} + +Instructs the interpreter to replace known math Greek commands with +words instead of the applicable symbol. For example, if an entry has +been defined as: +\begin{codeenv} +\atentry{index}\marg{a-Fe, + \field{name}=\marg{\cs{ensuremath}\marg{\ics{alpha}}-iron} +} +\end{codeenv} +Then with \csopt[true]{wordify-math-greek} the interpreter will obtain +the sort value \qt{alpha-iron}. This only works for commands +recognised by the \texparserlib\ as Math Greek commands. + +With the default \csopt[false]{wordify-math-greek}, the interpreter +will convert \cs{alpha} into the nearest appropriate Unicode +character. + +The textual replacement depends on whether or not a corresponding +entry is available in the language file \metafilefmt{bib2gls-extra-}{lang}{.xml} +for the current resource locale. If no entry is found, the control +sequence name (or substring) will typically be used. + +\optsection{wordify-math-symbol} + +Similar to \csopt{wordify-math-greek}, this option will apply to +other known math symbol commands. Again, this only works for a +limited set of commands recognised by the \texparserlib. An +alternative is to provide alternative definitions for \bibgls\ that +aren't picked up by \LaTeX, or use \ics{IfNotBibGls}, or use a more +appropriate field for sorting. + \optsection{interpret-preamble} This is a boolean option that determines whether or not the @@ -8636,6 +9135,7 @@ This governs how the entries are written in the \iext{glstex} file. The \meta{value} may be one of: \begin{itemize} \item\code{define}: define the entries; +\item\code{provide}: provide the entries; \item\code{copy}: copy the entries; \item\code{define or copy}: copy existing entries and define non-existing entries. @@ -8650,6 +9150,14 @@ definition will be ignored. (The warnings can be found in the \ext{log} file since they are warnings produce by \sty{glossaries-extra} not by \bibgls.) +If you have multiple \iglspl{resourceset} to help group different types of +entry for the same glossary, the \csopt[provide]{action} setting can +be used to suppress any warnings if the selection criteria is too +complex to filter out entries that were selected by a previous +\gls{resourceset}. If, however, you want duplicate entries so that +you can have the same entry listed in multiple glossary, you need a +different approach. + For example, if you try: \begin{codeenv} \cs{newglossary*}\marg{copies}\marg{Copies} @@ -8787,6 +9295,18 @@ conditional (see \sectionref{sec:conditionals}). For each \meta{element-list} \oargm{condition} specification, if the condition evaluates to false or if the \meta{element-list} evaluates to null then the copy instruction won't be added. + +For example, the following first sets the \field{type} to +\qt{ignored} for any entries that only have \glspl{ignoredrecord} +and then copies all entries that don't have the \field{type} field +set to \qt{ignored} to the glossary labelled \qt{index}: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[ignored]{ignored-type}, + \csopt[\qtdelim{index} \oarg{ \field{type} \idx{notequalscmp} \qtdelim{ignored}} ]{copy-to-glossary} +} +\end{codeenv} + The fallback action for a missing field value is governed by the \csopt{copy-to-glossary-missing-field-action} setting. The result of the string concatenation (if not null) is the label of the target @@ -10845,6 +11365,8 @@ have values in the form \code{\oargm{tag}\meta{id-list}} where \meta{id-list} is a comma-separated list of entry labels. The value is required for this key but may be empty, which indicates an empty set of fields (that is, the setting is switched off). +Note that the listed fields must be recognised as known fields, for +example, custom fields defined with \cs{glsaddstoragekey}. This setting makes those fields act like the \field{see} field by identifying the listed entries as dependencies, but the information @@ -11170,6 +11692,53 @@ example: (The \styopt{nomain} option was added to suppress the creation of the default \mainglossary.) +\optsection[\subsubsection]{ignored-type} + +Any entry that only has \iglspl{ignoredrecord} will still be +identified as having a record for selection purposes, which is +necessary for the entry to be defined in the document, but it may be +preferable to move such entries to a special \igls{ignoredglossary}. +This can be done with \csopt[\meta{type}]{ignored-type}, where +\meta{type} is the label of the \igls{ignoredglossary}. + +The glossary will be provided with +\ics{provideignoredglossary} to ensure that it's +defined even if \longarg{no-provide-glossaries} is set +(see \sectionref{sec:newglossary}). +Note that it uses the unstarred \ics{provideignoredglossary} +since it's assumed that it won't be needed in a list and +therefore won't have a target. This is different to all the other +settings that provide an \gls{ignoredglossary}, which use the +starred version instead. + +This option is not implemented for entries that have \emph{no} records +(those entries may have been selected because they are dependent on +another entry, such as a parent of a recorded child entry). The entry +must have at least one \gls{ignoredrecord} and +no other type of record and not be dependent on other entries or be +cross-referenced by other entries. + +Note that the \csopt{trigger-type} option, if set, overrides the +\csopt{ignored-type} option for entries that have records with the +special format \ics{glstriggerrecordformat} (which is also +considered an \gls{ignoredrecord}). However, \csopt{ignored-type} +will override the \csopt{type}, \csopt{dual-type}, +\csopt{tertiary-type} and the type specification in +\csopt{secondary}. + +Ignored entries may be copied to another glossary +with \csopt{copy-to-glossary}. If this is undesirable, a condition +may be applied to prevent it. For example, to copy all selected +entries to the glossary labelled \qt{index} except for ignored +entries: +\begin{codeenv} +\gls{GlsXtrLoadResources}\oarg{ + \csopt[\marg{terms,abbreviations}]{src} + \csopt[ignored]{ignored-type}, + \csopt[\qtdelim{index} \oarg{ \field{type} \idx{notequalscmp} \qtdelim{ignored} }]{copy-to-glossary} +} +\end{codeenv} + \optsection[\subsubsection]{trigger-type} The record counting commands, such as \gls{rgls}, use the special @@ -12431,8 +13000,8 @@ texparserlib: {\glsentryname{gato}} -> gato texparserlib: {\glsentryname{gatinho}} -> gatinho \end{verbatim} The \code{kitten} entry has the same list, and the same process is -repeated for that entry. The \longarg{verbose} mode will provide additional -information. The \longarg{debug} mode will indicate whether the +repeated for that entry. The \commonlongarg{verbose} mode will provide additional +information. The \commonlongarg{debug} mode will indicate whether the referenced label was found in the current \igls{resourceset} or if it had to be fetched from another \igls{resourceset}. So if the resulting order isn't what you expect, check the transcript file for messages. @@ -14141,7 +14710,7 @@ obtained from the label. Therefore both \code{glossarylist} and \code{glosscol} end up with the same sort value: \code{glossary}. This triggers a -message in verbose mode (\longarg{verbose}) which can be found +message in verbose mode (\commonlongarg{verbose}) which can be found in the transcript file: \begin{verbatim} Identical sort values for 'glossarylist' and 'glosscol' @@ -14783,7 +15352,7 @@ above example) or an \igls{ignoredrecord} format such as \encap{glsignore}, that format will be skipped. So in the above example, the second \gls{record} will be added to the \gls{locationlist}, but not the first. (A message will only be written to the transcript if -the \longarg{debug} switch is used.) The default +the \commonlongarg{debug} switch is used.) The default \encap{glsnumberformat} will take precedence over the \igls{ignoredrecord} formats (\encap{glsignore} and \encap{glstriggerrecordformat}). @@ -16543,7 +17112,7 @@ had \csopt[doc]{sort} as the default. \item[\optfmt{doc}] The \gls{document-locale} if it has been detected by \sty{tracklang}. If no document language has been detected (or -identified with \longarg{locale}), then +identified with \commonlongarg{locale}), then \optfmt{doc} will be equivalent to \optfmt{locale}. \item[\optfmt{locale}] The default \gls{Java-locale}. @@ -17040,7 +17609,8 @@ and \textsuperscript{2} (\hex{00B2}). As with the letter sort methods, letters are compared using a character code comparison not by a locale alphabet. The closest locale-sensitive equivalent is to use \csopt{sort-number-pad} with a -locale sort method. Alternatively, use \ics{IfTeXParserLib} and +locale sort method. Alternatively, use \ics{IfTeXParserLib} or +\ics{IfNotBibGls} and \ics{bibglspaddigits} to pad the number for the interpreter but not in the \TeX\ document. @@ -17528,7 +18098,7 @@ then I can sort them chronologically: and the locale matches my system locale, so I could omit both \csopt{date-sort-locale} and \csopt{date-sort-format}.) -If \longarg{verbose} mode is on, the transcript will show +If \commonlongarg{verbose} mode is on, the transcript will show the label, sort value and numeric value for each entry. In this case, the information is: \begin{verbatim} @@ -17954,7 +18524,7 @@ This option is ignored when used with the non-alphabetic \csopt{sort} options. You can find the break points in the \field{sort} field for the entry's definition in the \ext{glstex} file (which is provided for information rather than for use in the -document). Alternatively, use the \longarg{debug} switch to show +document). Alternatively, use the \commonlongarg{debug} switch to show the break points in the transcript. (This will also show the collation rule.) @@ -18140,7 +18710,7 @@ The \csopt[\meta{field}]{sort-suffix} setting will only append a suffix if that field is set, but (if set) it will apply the suffix to all \field{sort} values, even those that are unique. -If you use \longarg{verbose}, then \bibgls\ will write information +If you use \commonlongarg{verbose}, then \bibgls\ will write information in the transcript when it appends a suffix to the sort value. The message: \begin{alltt} @@ -22750,63 +23320,238 @@ but will expand to empty if the associated resource option hasn't been set. \chapter{Converting Existing \iext{tex} to \iext{bib}} -\label{sec:gls2bib} +\label{sec:tex2bib} \setsecdepth{1} +\renewcommand{\cssectioncmd}{\subsubsection} -If you have already been using the \styfmt{glossaries} or -\styfmt{glossaries-extra} package with a large file containing all your -definitions using commands like \gls{newglossaryentry}, then you can -use the supplementary tool \idx{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 \idx{kpsewhich} to check \texmfcnf{openinany} and -\texmfcnf{openoutany}. Take care not to accidentally overwrite -existing \ext{bib} files as there's no check to determine if -\meta{bib file} already exists with the default \convertglsbiblongarg{overwrite}. +There are some supplementary command line tools provided with +\bibgls\ that can convert certain types of data from existing +documents to \iext{bib} files: +\begin{itemize} + \item \idx{convertgls2bib} converts +data from commands like \gls{newglossaryentry} to \ext{bib} entry +data (see \sectionref{sec:gls2bib}). -If the \ext{bib} extension is missing from \meta{bib file}, it will -be added. The extension is required for \meta{tex file}. + \item \idx{datatool2bib} converts \sty{datatool} databases to +\ext{bib} entry data (see \sectionref{sec:gls2bib}). +\end{itemize} + +These command line tools share the same common switches listed in +\sectionref{sec:commonswitches}. Additionally, they share the switches +listed in \sectionref{sec:shared2bibswitches}, but they may also +have their specific switches, which are described in the relevant +section. -\section{Command Line Arguments} +\begin{important} +It's likely that you will need to post-process the \ext{bib} files +or at least double-check that the conversion has been performed +adequately. +\end{important} -The \meta{options} recognised by \idx{convertgls2bib} are described below. +The \ext{bib} format has case-insensitive field names. However, the +source files input by the converter tool typically have +case-sensitive labels that correspond to the destination \ext{bib} +field. The converter tools will convert the fields to +\idx{lowercase} after any mappings have been applied. +Use \converterlongarg{field-case} to change this. +Additionally, the \ext{bib} format prohibits certain characters in +field names and entry labels (such as spaces), so these will be +stripped. The resulting field names must be non-empty. + +The \texparserlib\ is used to parse the input files. The conversion +tool may automatically implement the relevant packages (such as +\sty{datatool} and \sty{datagidx} for \idx{datatool2bib}). +However, the behaviour of some commands may be +modified to better suit the conversion process. + +Note that \ics{IfTeXParserLib} will expand to its first argument, +but \ics{IfNotBibGls} will also expand to its first argument, since +it's only defined to expand to its second argument by the \bibgls\ +interpreter not by the \texparserlib\ core code. + +Avoid any overly complicated code within the \ext{tex} file. The +\texparserlib\ isn't a \TeX\ engine! The input \ext{tex} file +doesn't need to be a complete document, but if you want certain +commands recognised from packages that the \texparserlib\ supports, +you'll need to include \ics{usepackage} in the \ext{tex} file. If +you want to quit parsing the \ext{tex} file at the start of the +document, use the \converterlongarg{preamble-only} switch. -\convertglsbibarg{texenc} +\begin{important} +The \texparserlib\ recognises +\ics{input} and \ics{include} and so will also parse the referenced +file if either command is encountered. +If you have multiple files, it's better to pass just the relevant +file to the conversion tool rather than the main document file. +\end{important} -The character \igls{encoding} of the \ext{tex} file. If omitted, the -operating system's default \gls{encoding} is assumed (or the -\idx{JVM}['s]). +\section{Shared Conversion Tool Switches} +\label{sec:shared2bibswitches} -\convertglsbibarg{bibenc} +\converterarg{texenc} + +The character \igls{encoding} of the source \ext{tex} file. If omitted, the +\idx{JVM}['s] default \gls{encoding} is assumed (which may or +may not be the same as the operating system's default). + +\converterarg{bibenc} The character \igls{encoding} of the \ext{bib} file. If omitted, the same \gls{encoding} as the \ext{tex} file is assumed. -\convertglsbibarg{space-sub} +\converterarg{space-sub} 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}, +\meta{replacement}. Where applicable, the cross-referencing fields, \field{see}, \field{seealso} and \field{alias}, will also be adjusted, but any references using \ics{gls} etc will have to be substituted manually -(or use a global search and replace in your text editor). +(or use a global search and replace action 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} convertgls2bib --space-sub '' entries.tex entries.bib \end{verbatim} +Alternatively, use \converterlongarg{field-map} to supply an +alternative field name. + +\begin{important} +Note that all forbidden punctuation characters +(such as commas, equal signs and braces) will be automatically stripped. +\end{important} + +\converterarg{preamble-only} + +Stop parsing if the start of the \env{document} environment is found. + +\converterarg{no-preamble-only} + +Parse the entire file (default). Be prepared for a lot of +\qt{unknown command} warnings if you make the conversion tool parse an +entire document. + +\converterarg{overwrite} + +Allow existing \ext{bib} files to be overwritten. (Default unless +otherwise specified.) + +\converterarg{no-overwrite} + +Don't allow existing \ext{bib} files to be overwritten. + +\converterarg{ignore-fields} + +Omit all the fields listed in \meta{list} from the \ext{bib} file. +This option is cumulative. +Note that in earlier versions of \idx{convertgls2bib} an empty list +cancelled the list of ignored fields. As from version 4.0, you will +need to use \converterlongarg{no-ignore-fields} to clear the list. + +Each item in the list should identify +the field by its original case-sensitive key. + +\converterarg{no-ignore-fields} + +Cancels the effect of \converterlongarg{ignore-fields}. + +\converterarg{field-map} + +Provides a mapping from source labels to the field names used in +the destination \ext{bib} file. The argument should be a +comma-separated list of \code{\meta{src-label}=\meta{dest-field}} +pairs. +This option is cumulative. + +For \idx{convertgls2bib}, the source labels are the keys used in +commands such as \gls{newglossaryentry}. These should ordinarily not +need any mappings. However, you may, for example, want to convert +the user keys to something more appropriate. +For \idx{datatool2bib}, the source labels are the column keys. + +\converterarg{no-field-map} + +Cancels all field mappings. + +\converterarg{field-case} + +Specifies whether or not to change the case of the field name when +writing to the \ext{bib} file. Valid \meta{setting}: +\optfmt{none} (no case-change), \optfmt{lc} (to \idx{lowercase}, default), +\optfmt{uc} (to \idx{uppercase}), \optfmt{title} (to \idx{titlecase}), +or \optfmt{sentence} (to \idx{sentencecase}). Note that since spaces +aren't permitted in field names, the last two are equivalent. +The case-change is applied after mapping. + +\converterarg{index-conversion} + +Use \atentry{index} instead of \atentry{entry} if the +\field{description} is empty or, for \idx{convertgls2bib}, if the +\field{description} is simply \ics{nopostdesc} or +\ics{glsxtrnopostpunc}. (Only applies to terms that would otherwise +be converted to \atentry{entry}, such as those defined with +\gls{newglossaryentry} in the case of \idx{convertgls2bib}.) + +\converterarg{no-index-conversion} + +Don't convert \atentry{entry} to \atentry{index} (default). + +\converterarg{log-file} + +The log file is optional for the converter applications. It's +provided for use with the \texparserlib\ debugging modes +(\commonlongarg{debug-mode}) which writes +logging information to this file (which can be sizeable). +A log file will automatically be created if debugging is enabled, +otherwise it will need to be explicitly created with +\converterlongarg{log-file} if required. The default name, if +automatically created, is the name of the converter application with +the \ext{log} file extension. + +\begin{important} +Unlike \bibgls's \longarg{log-file} switch, the conversion +tools don't have a corresponding short switch. +\end{important} + +\section{\glsfmttext{idx.convertgls2bib}: Conversion from \styfmt{glossaries} or +\styfmt{glossaries-extra}} +\label{sec:gls2bib} +\setsecdepth{2} + +If you have already been using the \styfmt{glossaries} or +\styfmt{glossaries-extra} package with a large file containing all your +definitions using commands like \gls{newglossaryentry}, then you can +use the supplementary tool \idx{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 \idx{kpsewhich} to check \texmfcnf{openinany} and +\texmfcnf{openoutany}. Take care not to accidentally overwrite +existing \ext{bib} files as there's no check to determine if +\meta{bib file} already exists with the default \converterlongarg{overwrite}. + +If the \ext{bib} extension is missing from \meta{bib file}, it will +be added. The extension is required for \meta{tex file}. + +\subsection{Command Line Arguments} + +The \meta{options} specific to \idx{convertgls2bib} are described below. +This is in addition to those described in \sectionref{sec:commonswitches} +and \sectionref{sec:shared2bibswitches}. Note that +\convertglsbiblongarg{split-on-type} overrides the default +\converterlongarg{overwrite} setting. \convertglsbibarg{ignore-sort} Omit the \field{sort} field. This is the default since \bibgls\ can work out a more intuitive sort value than either \idx!{makeindex} or \idx!{xindy}. +This option is automatically set if the \field{sort} field is +included in \converterlongarg{ignore-fields}. \convertglsbibarg{no-ignore-sort} @@ -22817,12 +23562,25 @@ Don't ignore the \field{sort} field. Omit the \field{type} field in the \ext{bib} file. You may find it more flexible not to be locked into a specific glossary type if you have a large database of entries. +This option is automatically set if the \field{type} field is +included in \converterlongarg{ignore-fields}. \convertglsbibarg{no-ignore-type} - Don't omit the \field{type} field (default unless +Don't omit the \field{type} field (default unless \convertglsbiblongarg{split-on-type}). +\convertglsbibarg{ignore-category} + +Omit the \field{category} field in the \ext{bib} file. +This option is automatically set if the \field{category} field is +included in \converterlongarg{ignore-fields}. + +\convertglsbibarg{no-ignore-category} + +Don't omit the \field{category} field (default unless +\convertglsbiblongarg{split-on-category}). + \convertglsbibarg{split-on-type} Split the entries into separate files according to the \field{type} @@ -22851,22 +23609,13 @@ of the definition of \ics{acronymtype} or \ics{glsxtrabbrvtype}); \end{itemize} This option automatically implements \convertglsbiblongarg{ignore-type} and -\convertglsbiblongarg{no-overwrite}. +\converterlongarg{no-overwrite}. \convertglsbibarg{no-split-on-type} Don't split the entries into separate files according to their type (default). -\convertglsbibarg{ignore-category} - -Omit the \field{category} field in the \ext{bib} file. - -\convertglsbibarg{no-ignore-category} - -Don't omit the \field{category} field (default unless -\convertglsbiblongarg{split-on-category}). - \convertglsbibarg{split-on-category} Split the entries into separate files according to the \field{category}. @@ -22902,54 +23651,13 @@ have \convertglsbiblongarg{split-on-category} and not \gls{newabbreviation} will be \filefmt{abbreviation.bib}. This option automatically implements \convertglsbiblongarg{ignore-category} and -\convertglsbiblongarg{no-overwrite}. +\converterlongarg{no-overwrite}. \convertglsbibarg{no-split-on-category} Don't split the entries into separate files according to their category (default). -\convertglsbibarg{ignore-fields} - -Omit all the fields listed in \meta{list} from the \ext{bib} file. -If \field{sort}, \field{type} or \field{category} are included -in the list, this will automatically implement the corresponding -\convertglsbiblongarg{ignore-sort}, -\convertglsbiblongarg{ignore-type} or -\convertglsbiblongarg{ignore-category} option. - -This option is not cumulative. If the list is empty it will unset -any previous list but won't unset any -\convertglsbiblongarg{ignore-sort}, -\convertglsbiblongarg{ignore-type} or -\convertglsbiblongarg{ignore-category} option. - -For example: -\begin{alltt} -convertgls2bib \longargfmt{ignore-fields} 'user1,sort' entries.bib -\end{alltt} -is equivalent to: -\begin{alltt} -convertgls2bib \longargfmt{ignore-fields} user1 \longargfmt{ignore-sort entries.bib} -\end{alltt} -and -\begin{alltt} -convertgls2bib \longargfmt{ignore-fields} 'user1,sort' \longargfmt{ignore-fields} '' entries.bib -\end{alltt} -is equivalent to: -\begin{alltt} -convertgls2bib \longargfmt{ignore-sort} entries.bib -\end{alltt} - -\convertglsbibarg{preamble-only} - -Stop parsing if the start of the \env{document} environment is found. - -\convertglsbibarg{no-preamble-only} - -Parse the entire file (default). Be prepared for a lot of -unknown command warnings if you make \idx{convertgls2bib} parse an -entire document. \convertglsbibarg{absorb-see} @@ -22962,65 +23670,23 @@ the corresponding entry (default). Don't absorb any cross-referencing information identified with \ics{glssee} or \ics{glsxtrindexseealso} commands. -\convertglsbibarg{index-conversion} - -Use \atentry{index} instead of \atentry{entry} if the -\field{description} is empty or simply \ics{nopostdesc} or -\ics{glsxtrnopostpunc}. (Only applies to terms that would otherwise -be converted to \atentry{entry}, such as those defined with -\gls{newglossaryentry}.) - -\convertglsbibarg{no-index-conversion} - -Don't convert \atentry{entry} to \atentry{index} (default). - -\convertglsbibarg{locale} +\convertglsbibarg{internal-field-map} -Identifies the \langxml\ to use for \idx{convertgls2bib}['s] -messages. +Appends the given internal field to key mappings to the predefined +list. This action is cumulative. The mappings are needed for +\gls{glssetexpandfield} and \gls{glssetnoexpandfield}, which use +\idx{internalfields} for their arguments. +Note that this is different from \converterlongarg{field-map} which +maps the key used in commands like \gls{newglossaryentry} to +the corresponding field label written the \ext{bib} file. -\convertglsbibarg{overwrite} +\subsection{Recognised Commands} -Allow existing \ext{bib} files to be overwritten. (Default unless -\convertglsbiblongarg{split-on-type}.) - -\convertglsbibarg{no-overwrite} - -Don't allow existing \ext{bib} files to be overwritten. (Default if -\convertglsbiblongarg{split-on-type}.) - -\convertglsbibarg{silent} - -Suppress all messages except for errors. - -\convertglsbibarg{verbose} - -Display messages and warnings (default). - -\convertglsbibarg{debug} - -Display debugging messages (stack traces and other information in -addition to \convertglsbiblongarg{verbose}). - -\convertglsbibarg{help} - -Display help message and quit. - -\convertglsbibarg{version} - -Display version information and quit. - -\section{Recognised Commands} - -This application recognises the commands listed below as well as -some standard commands such as \ics{newcommand}. Avoid any overly -complicated code within the \ext{tex} file. The \texparserlib\ -isn't a \TeX\ engine! The -\ext{tex} file doesn't need to be a complete document, but if you want certain -commands recognised from packages that the \texparserlib\ supports, -you'll need to include \ics{usepackage} in the \ext{tex} file. If -you want to quit parsing the \ext{tex} file at the start of the -document, use the \convertglsbiblongarg{preamble-only} switch. +The \idx{convertgls2bib} application recognises the commands listed below as well as +some standard commands such as \ics{newcommand}. The \texparserlib\ +is instructed to skip its usual implementation of the +\sty{glossaries} and \sty{glossaries-extra} packages as only a +limited set of commands need to be defined. In all cases below, if \meta{\keyvallist} contains: \begin{codeenv*} @@ -23055,7 +23721,7 @@ Additionally, if \meta{\keyvallist} contains: \end{codeenv} then this field will be ignored. (This \field{type} value is recommended in \meta{\keyvallist} when loading files with -\ics{loadglsentries}\oargm{type}\margm{file} to allow the optional +\gls{loadglsentries}\oargm{type}\margm{file} to allow the optional argument to set the \field{type}. With \bibgls\ you can use the \csopt{type} option instead.) @@ -23081,6 +23747,10 @@ The base \styfmt{glossaries} package provides: \formatdef{glssetexpandfield} If present, this instructs \idx{convertgls2bib} to expand the given field, even if \gls{glsnoexpandfields} has been used. +Note that the argument should be the internal field label. +The default set of mappings are recognised. Any additional mappings +will need to be added with +\convertglsbiblongarg{internal-field-map}. \cssection{glssetnoexpandfield} The base \styfmt{glossaries} package provides: @@ -23088,8 +23758,18 @@ The base \styfmt{glossaries} package provides: If present, this instructs \idx{convertgls2bib} to not expand the given field, even if \gls{glsexpandfields} has been used. Unlike the default behaviour with the \sty{glossaries} package, there are no -fields switched explicitly switched off by default with -\idx{convertgls2bib}. +fields explicitly switched off by default with \idx{convertgls2bib}. + +\cssection{loadglsentries} +The base \styfmt{glossaries} package provides: +\formatdef{loadglsentries} +This locally redefines \ics{glsdefaulttype} to \meta{type} (if the optional argument is supplied) +and inputs \meta{file}. If the \meta{file} doesn't have an extension, \ext{tex} is assumed. +(The \texparserlib\ also recognises \ics{input}.) + +In general, it's better to simply use \meta{file} as the source file +when running \idx{convertgls2bib} instead of using the main document +file as the source. \cssection{newglossaryentry} The base \styfmt{glossaries} package provides: @@ -23346,9 +24026,609 @@ contain: } \end{codeenv} +\section{\glsfmttext{idx.datatool2bib}: Conversion from +\styfmt{datatool}} +\label{sec:datatool2bib} + +A \isty{datatool} database can be converted to a \ext{bib} file +with the supplementary tool \idx{datatool2bib}. The syntax is: +\begin{alltt} +datatool2bib \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 \idx{kpsewhich} to check \texmfcnf{openinany} and +\texmfcnf{openoutany}. Take care not to accidentally overwrite +existing \ext{bib} files as there's no check to determine if +\meta{bib file} already exists with the default \converterlongarg{overwrite}. + +This tool is primarily intended to convert \sty{datagidx} databases, +so it will automatically assume that \sty{datagidx} is loaded. +It can, however, be used for general databases, but you will need to +choose an appropriate column with unique values for the entry label (with +\datatoolbiblongarg{label} or use \datatoolbiblongarg{auto-label}). + +The \meta{tex file} may be a complete document (in which case, you +may want to use \converterlongarg{preamble-only} if the database +commands are all in the preamble) or may be a file that just +contains the database construction commands. The conversion tool +uses the \texparserlib\ which has some limited support for +\sty{datatool}, including database construction commands and file +input commands \ics{DTLloaddb}, \ics{DTLloaddbtex} and the newer +\gls{DTLread}. + +For example, suppose I have a document file called +\filefmt{myDoc.tex} that contains: +\begin{codeenv} +\csfmt{documentclass}\marg{article} +\csfmt{usepackage}\marg{datatool} +\gls{DTLnewdb}\marg{mydata} +\gls{DTLnewrow}\marg{mydata} +\gls{DTLnewdbentry}\marg{mydata}\marg{Forename}\marg{John} +\gls{DTLnewdbentry}\marg{mydata}\marg{Surname}\marg{Smith} +\comment{...} +\cmd{begin}\marg{document} +\comment{...} +\cmd{end}\marg{document} +\end{codeenv} +Then I can extract this data with: +\begin{codeenv} +datatool2bib \converterlongarg{preamble-only} myDoc.tex mydata.bib +\end{codeenv} +If the database commands are instead in a separate file called, say, +\filefmt{mydata.tex} which is simply input in \filefmt{myDoc.tex} +then \filefmt{mydata.tex} can then be used for the \meta{tex file} +input file: +\begin{verbatim} +datatool2bib mydata.tex mydata.bib +\end{verbatim} +Note that the \texparserlib\ also recognises commands such as +\gls{dtlexpandnewvalue}. If this is in \filefmt{myDoc.tex} rather +than in \filefmt{mydata.tex} and only \filefmt{mydata.tex} is parsed +then the \texparserlib\ won't encounter \gls{dtlexpandnewvalue} and +so won't enable new value expansion. You can, however, use +\code{\datatoolbiblongarg{setup} expand-new-value} to switch on new +value expansion. + +If the data source is in a CSV file, then the \texparserlib\ can +parse it but only if the file is referenced in \ics{DTLloaddb} (pre +\sty{datatool} v3.0) or \gls{DTLread} (\sty{datatool} v3.0+). +For the newer \gls{DTLread} command, the \code{format=\iext{csv}} setting is +required to parse CSV files or \code{format=\iext{tsv}} for TSV files. +If the file contains \LaTeX\ commands, \code{content=tex} is +required otherwise \code{content=literal} is required. + +So in order to convert a CSV file called \filefmt{mydata.csv} to +a \ext{bib} file, the \texparserlib\ needs to parse: +\begin{codeenv} +\gls{DTLread}\oarg{format=csv,content=literal}\marg{mydata.csv} +\end{codeenv} +Rather than having to parse the entire document source file or +create a stub file that simply contains this command, you can use +the \datatoolbiblongarg{read} switch instead: +\begin{codeenv} +datatool2bib \datatoolbiblongarg{read} format=csv,content=literal mydata.csv mydata.bib +\end{codeenv} +This is equivalent to creating a stub file with just the +\gls{DTLread} line. + +In general, better results are obtained if \idx{datatool2bib} parses +\gls{datagidx.newterm} and \gls{datagidx.newacro} instead of the +actual \sty{datagidx} databases. The custom \sty{datagidx} databases +have a number of columns for internal use that are not applicable to +\bibgls. + +When you run \idx{datatool2bib} from the command line, there will be +two lines reporting the number of databases found by parsing the +input. For example: +\begin{verbatim} +1 database (datatool) found +0 databases (datagidx) found +\end{verbatim} +The first line indicates the number of regular \sty{datatool} +databases that were found by the \texparserlib. The second line +indicates the number of \sty{datagidx} databases that were detected +by scanning for \gls{datagidx.newterm} and \gls{datagidx.newacro}. + +In the first case, the source field labels will correspond to the +column keys (such as \optfmt{Label}, \optfmt{Name}, +\optfmt{Description} and \optfmt{Symbol}), whereas in the second +case the source field labels will correspond to the option keys for +\gls{datagidx.newterm} and \gls{datagidx.newacro} (such as \optfmt{description} and +\optfmt{symbol}, but not the \optfmt{label} key, which will be +dropped from the list after its value is saved elsewhere). + +\subsection{Command Line Arguments} + +The \meta{options} specific to \idx{datatool2bib} are described below. +This is in addition to those described in \sectionref{sec:commonswitches} +and \sectionref{sec:shared2bibswitches}. + +\datatoolbibarg{label} + +Obtain the \ext{bib} entry label from the column identified by the +\meta{column-key}. Note that the column key is the original +case-sensitive column label not the mapped field. +The label will be obtained by copying the value from the given +column and processing according to \converterlongarg{space-sub} +(and stripping forbidden characters). This option is not applicable +to \gls{datagidx.newterm} and \gls{datagidx.newacro}. + +\begin{important} +The chosen column should have unique values (and should still be +unique after processing). +\end{important} + +The default setting is \code{\datatoolbiblongarg{label} Label} +since this is the column used for labels with \styfmt{datagidx} (but +is only applicable if you save the database with \cs{DTLwrite} +rather than having \idx{datatool2bib} parse \gls{datagidx.newterm} +and \gls{datagidx.newacro}). + +If you are converting a general \sty{datatool} database, either +choose a different column or switch on the auto label. + +\datatoolbibarg{auto-label} + +If there is no appropriate column for a label, this option may be +used to automatically generate the label in the form +\meta{prefix}\meta{n}. If +\datatoolbiblongarg{auto-label-prefix} is set, that will provide the +\meta{prefix}, otherwise the prefix will match the database label. + +\datatoolbibarg{no-auto-label} + +Switches off automatic labelling. The labels will be created from +the column identified by \datatoolbiblongarg{label}. + +\datatoolbibarg{auto-label-prefix} + +Sets the prefix for use with \datatoolbiblongarg{auto-label}. +This option automatically implements +\datatoolbiblongarg{auto-label}. + +\datatoolbibarg{read} + +Instead of parsing the provided \ext{tex} file in the usual manner, +the \datatoolbiblongarg{read} option will act as though the input +is: +\begin{codeenv} +\gls+{DTLread}\oargm{options}\marg{filename} +\end{codeenv} +where \meta{filename} is the input filename supplied to +\idx{datatool2bib}. This can be use where the source file is a +CSV file rather than a \LaTeX\ file. + +\datatoolbibarg{setup} +Implements \code{\gls{DTLsetup}\margm{options}} before parsing. +Note that this can be counteracted by any changes to the settings +within the file being parsed. + +\datatoolbibarg{save-datum} +Equivalent to: +\begin{codeenv} +\datatoolbiblongarg{save-value} "-value" \datatoolbiblongarg{save-currency} "-currency" +\end{codeenv} +For example, if the CSV file +\filefmt{products.csv} contains: +\begin{alltt} +ID,Product,Quantity,Price +1,Sample,3,"\$1,234.50" +\end{alltt} +then with: +\begin{codeenv} +datatool2bib \datatoolbiblongarg{label} Product \datatoolbiblongarg{read} "format=csv,content=literal" products.csv products.bib +\end{codeenv} +The \filefmt{products.bib} file will contain: +\begin{codeenv} +\atentry{entry}\marg{Sample, + \fieldfmt{id} = \marg{1}, + \fieldfmt{product} = \marg{Sample}, + \fieldfmt{quantity} = \marg{3}, + \fieldfmt{price} = \marg{\cs{cs.dollar}1,234.5} +} +\end{codeenv} +Whereas with: +\begin{codeenv} +datatool2bib \datatoolbiblongarg{save-datum} \datatoolbiblongarg{label} Product \datatoolbiblongarg{read} "format=csv,content=literal" products.csv products.bib +\end{codeenv} +\begin{codeenv} +\atentry{entry}\marg{Sample, + \fieldfmt{id} = \marg{1}, + \fieldfmt{product} = \marg{Sample}, + \fieldfmt{quantity} = \marg{3}, + \fieldfmt{price} = \marg{\cs{cs.dollar}1,234.5}, + \fieldfmt{price-value} = \marg{1234.5}, + \fieldfmt{price-currency} = \marg{\cs{cs.dollar}} +} +\end{codeenv} +Note that the original number formatting is retained in the +\fieldfmt{price} field but the plain numeric value is saved in the +\fieldfmt{price-value} field and the currency symbol is saved in the +\fieldfmt{price-currency} field. These custom fields will all need +to be defined or aliased when the \ext{bib} file is read by \bibgls. + +For further information on the \sty{datatool} datum format see the +\sty{datatool} v3.0+ user manual. You need to set the +decimal and number group characters with \ics{DTLsetnumberchars} and +the currency symbol with \ics{DTLnewcurrencysymbol} for the values +to be parsed correctly. + +\datatoolbibarg{no-save-datum} +Equivalent to: +\begin{codeenv} +\datatoolbiblongarg{no-save-value} \datatoolbiblongarg{no-save-currency} +\end{codeenv} + +\datatoolbibarg{save-value} + +If a field contains a formatted numeric value or currency (according +to the current \sty{datatool} settings), the numeric value will be +saved in the field \meta{field}\meta{prefix} if it's different from +the value in \meta{field}. + +\datatoolbibarg{no-save-value} + +Don't save numeric values in a separate field (default). + +\datatoolbibarg{save-currency} + +If a field contains a formatted currency (according +to the current \sty{datatool} settings), the currency symbol will be +saved in the field \meta{field}\meta{prefix}. + +\datatoolbibarg{no-save-currency} + +Don't save the currency symbol in a separate field (default). + +\datatoolbibarg{split} + +If multiple databases are found in the input file, create a separate +output file for each database. If the output \meta{bib file} provided to +\idx{datatool2bib} is given as \filefmt{\meta{base}.bib} then each +database \meta{dbname} will be saved in the file +\filefmt{\meta{base}-\meta{dbname}.bib}. + +\datatoolbibarg{no-split} + +All data found from parsing the input file will be saved in the +single output \meta{bib file} (default). + +\datatoolbibarg{detect-symbols} + +Attempt to detect entries that should be \atentry{symbol} or +\atentry{number} based on the value of the \field{name} field. +This tries to expand the value of the name field with +\ics{DTLgidxParen} and \ics{DTLgidxIgnore} locally defined to +discard their argument. If the result is empty or if the first +character of the result is not alphabetic then, +if the result parses as an integer, \atentry{number} +will be chosen otherwise \atentry{symbol} will be chosen. +(An empty result can occur if the \field{name} field solely consists +of commands that are unknown to the \texparserlib, which suggests +symbols rather than words.) + +This setting is only applicable for entries defined with +\sty{datagidx}['s] \cs{newterm} command, not with general +\sty{datatool} databases. Note that if this +results in a change to the entry type from its default +\atentry{entry} then \converterlongarg{index-conversion} won't +convert the type to \atentry{index}, regardless of whether or +not the \field{description} field is set. + +\datatoolbibarg{no-detect-symbols} + +Don't attempt to detect symbols (default). + +\datatoolbibarg{numeric-locale} + +For use with \datatoolbiblongarg{detect-symbols}, this switch +identifies the locale used for numeric parsing to determine whether +or not the \atentry{number} entry type should be used. +If omitted, the \idx{JVM}['s] default locale is assumed. + +\datatoolbibarg{adjust-gls} + +This setting is the default. +Any instance of commands like \ics{datagidx.gls} found in field +values will have their labels adjusted, if they have been modified +due to stripping spaces etc. Also, the syntax of \sty{datagidx}['s] +\ics{datagidx.gls} is slightly different from \sty{glossaries}['s] +\ics{gls} as the format is incorporated at the start of the label. +If this is detected, the format will be added as an optional +argument, matching the \sty{glossaries} syntax. + +Additionally, commands that have different names from those provided +by \sty{glossaries} will be replaced with the closest match. For +example, \ics{datagidx.glsnl} will be replaced with \code{\ics{gls}*} +(no hyperlink). + +\datatoolbibarg{no-adjust-gls} + +Don't adjust commands like \ics{datagidx.gls} in field values. + +\datatoolbibarg{dependency-field} + +Sets the name of the dependency field. Has no effect with +\datatoolbiblongarg{no-strip-glsadd}. With +\datatoolbiblongarg{strip-glsadd}, the label from the +stripped \ics{datagidx.glsadd} argument will be added to the field identified +by \meta{field}. The default is \fieldfmt{dependency} which will be ignored +by \bibgls\ unless instructed otherwise (via resource options such +as \csopt{field-aliases} or by defining the field with commands such +as \cs{glsaddstoragekey}). + +For example, \meta{field} could be set to \field{see} (but be aware +that this won't be merged with any existing \field{see} value for +the same entry) or the new document to use the created \ext{bib} +file could define \meta{field} and reference it in +\csopt{dependency-fields}. + +The \meta{field} will have any invalid content stripped and will be +adjusted to match the \converterlongarg{field-case} setting. +If the \meta{field} ends up as an empty string, it will behave as +\datatoolbibarg{no-dependency-field}. + +\datatoolbibarg{no-dependency-field} + +Don't save any labels stripped with +\datatoolbiblongarg{strip-glsadd}. + +\datatoolbibarg{strip} + +Switch on all strip options. + +\datatoolbibarg{no-strip} + +Switch off all strip options. + +\datatoolbibarg{strip-glsadd} + +Any instance of \ics{datagidx.glsadd} found in field values will be +stripped, along with the argument. Note that this command is +provided by \sty{datagidx} and, unlike the analogous +\sty{glossaries} command, it doesn't have an optional argument but +instead allows the format option to be included in the mandatory +argument. + +This setting is the default as \cs{glsadd} is rarely needed in field +values with \bibgls, as dependencies and the \csopt{selection} +criteria are usually sufficient. + +\datatoolbibarg{no-strip-glsadd} + +No search is made for \ics{datagidx.glsadd} in field values. Note +that this means that no adjustments for the different syntax will be +made. + +\datatoolbibarg{strip-acronym-font} + +Any instance of \ics{acronymfont} found in field values will be +strip and the braces around the argument will be removed. + +This setting is the default since \cs{acronymfont} should not be +used with \sty{glossaries-extra}. + +\datatoolbibarg{no-strip-acronym-font} + +No search is made for \cs{acronymfont} in the field values. Note +that the use of \cs{acronymfont} is deprecated with +\sty{glossaries-extra} as it has a different abbreviation mechanism +to the base \sty{glossaries} package. + +\datatoolbibarg{strip-case-change} + +The following \idxpl{casecommands} will be stripped from field +values and the braces around the argument will be removed: +\csfmt{uppercase}, \csfmt{lowercase}, +\ics{MakeTextUppercase}, \ics{MakeTextLowercase}, +\ics{MakeUppercase}, \ics{MakeLowercase}, and the \sty{mfirstuc} +commands. + +\datatoolbibarg{no-strip-case-change} + +Don't strip the \idxpl{casecommands} from field values (default). + +\subsection{Recognised Commands} + +This section lists \isty{datatool} and \isty{datagidx} commands that +are recognised by \idx{datatool2bib}. (There may be other commands +that are also recognised but aren't relevant to the conversion +process.) See the \sty{datatool} user manual for further +information. + +\cssection{DTLsetup} +Some but not all \sty{datatool} settings are +recognised by the \texparserlib. Of those that are recognised, the +settings pertinent to \idx{datatool2bib} are: \optfmt{default-name}, +\optfmt{store-datum}, \optfmt{new-value-trim}, +\optfmt{new-value-expand}, and \optfmt{io}. + +The \optfmt{io} setting +takes a comma-separated list of default I/O options applicable to +\gls{DTLread} (and \cs{DTLwrite}). Recognised I/O options: +\optfmt{name}, \optfmt{keys}, \optfmt{headers}, \optfmt{expand}, +\optfmt{format}, \optfmt{add-delimiter}, \optfmt{csv-escape-chars}, +\optfmt{csv-content}, \optfmt{csv-blank}, \optfmt{csv-skip-lines} +(and synonym \optfmt{omitlines}), \optfmt{no-header} (and synonym +\optfmt{noheader}), \optfmt{auto-keys} (and synonym +\optfmt{autokeys}), \optfmt{overwrite}, \optfmt{load-action}, +\optfmt{delimiter}, and \optfmt{separator}. + +\cssection{DTLread} +Loads a database from the given file, where the format should be +identified in \meta{options} with the \optfmt{format} key. The +default is \code{format=csv}, which indicates that the file is a CSV +file. For tab-separated files, use \code{format=tsv}. If the CSV/TSV +file contains \TeX\ markup within the cells, use +\code{csv-content=tex} otherwise use \code{csv-content=literal}. + +Note that: +\begin{codeenv} +datatool2bib \datatoolbiblongarg{read} \meta{io-options} \meta{filename} \meta{bib file} +\end{codeenv} +is equivalent to creating a file \filefmt{otherfile.tex} with a single line: +\begin{codeenv} +\gls{DTLread}\oargm{io-options}\margm{filename} +\end{codeenv} +and then running: +\begin{alltt} +datatool2bib otherfile.tex \meta{bib file} +\end{alltt} + +\begin{important} +The \texparserlib\ also recognises \ics{DTLwrite} but +\idx{datatool2bib} redefines the command to do nothing. +\end{important} + +\cssection{dtlexpandnewvalue} +New values will be expanded before being added to the database. +Note that the \texparserlib\ may not expand commands in the same way +as \TeX, and it won't be able to expand unknown commands. + +\cssection{dtlnoexpandnewvalue} +New values will not be expanded before being added to the database +(default). + +\cssection{DTLnewdb} +Defines a new database with the given label. + +\cssection{DTLnewrow} +Creates a new row in the database identified the given label. + +\cssection{DTLnewdbentry} +Adds a new entry to the final row of the given database. + +For example: +\begin{codeenv} +\gls+{DTLnewdb}\marg{mydata} +\gls+{DTLnewrow}\marg{mydata} +\gls+{DTLnewdbentry}\marg{mydata}\marg{Forename}\marg{John} +\gls{DTLnewdbentry}\marg{mydata}\marg{Surname}\marg{Smith} +\gls{DTLnewdbentry}\marg{mydata}\marg{Email}\marg{j.smith@example.com} +\gls{DTLnewrow}\marg{mydata} +\gls{DTLnewdbentry}\marg{mydata}\marg{Forename}\marg{Jane} +\gls{DTLnewdbentry}\marg{mydata}\marg{Surname}\marg{Doe} +\gls{DTLnewdbentry}\marg{mydata}\marg{Email}\marg{j.doe@example.com} +\end{codeenv} +This can be converted using, for example (assuming the above is in +the file \filefmt{mydata.tex}): +\begin{codeenv} +datatool2bib \datatoolbiblongarg{auto-label} mydata.tex mydata.bib +\end{codeenv} +This will create the file \filefmt{mydata.bib}, which will contain: +\begin{codeenv} +\atentry{entry}\marg{mydata1, + \fieldfmt{forename} = \marg{John}, + \fieldfmt{surname} = \marg{Smith}, + \fieldfmt{email} = \marg{j.smith@example.com} +} +\strut +\atentry{entry}\marg{mydata2, + \fieldfmt{forename} = \marg{Jane}, + \fieldfmt{surname} = \marg{Doe}, + \fieldfmt{email} = \marg{j.doe@example.com} +} +\end{codeenv} +(Use \converterlongarg{index-conversion} to use \atentry{index} instead +of \atentry{entry} where there's no \field{description}.) +The \csopt{assign-fields} resource option can be used to set +the \field{name} field to a concatenation of the forename and +surname fields (which would need to be aliased or defined if +required). + +\cssection{DTLaction} +This general purpose action command can be used to create and append +to databases. The applicable actions that are recognised by the +\texparserlib\ (and therefore by \idx{datatool2bib}) are: +\optfmt{new}, \optfmt{new row}, \optfmt{new entry}, and +\optfmt{add column}. + +For example: +\begin{codeenv} +\gls+{DTLsetup}\marg{default-name=mydata} +\gls+{DTLaction}\marg{new} +\gls{DTLaction}\oarg{ + assign = + \marg{ + Name = \marg{José Arara}, + Score = 68, + Award = \marg{\cs{cs.dollar}2,453.99} + } +}\marg{new row} +\gls{DTLaction}\oarg{ + assign = + \marg{ + Name = \marg{Zoë Zebra}, + Score = 73, + Award = \marg{\cs{cs.dollar}2,542} + } +}\marg{new row} +\end{codeenv} +This can be converted using, for example (assuming the above is in +the file \filefmt{mydata.tex}): +\begin{codeenv} +datatool2bib \datatoolbiblongarg{label} Name mydata.tex mydata.bib +\end{codeenv} +This will create the file \filefmt{mydata.bib}, which will contain: +\begin{codeenv} +\atentry{entry}\marg{JoséArara, + \field{name} = \marg{José Arara}, + \fieldfmt{score} = \marg{68}, + \fieldfmt{award} = \marg{\cs{cs.dollar}2,453.99} +} +\strut +\atentry{entry}{ZoëZebra, + \field{name} = \marg{Zoë Zebra}, + \fieldfmt{score} = \marg{73}, + \fieldfmt{award} = \marg{\cs{cs.dollar}2,542} +} +\end{codeenv} +Again, use \converterlongarg{index-conversion} to use +\atentry{index} instead of \atentry{entry} if the +\field{description} field is missing. + +The \iext{dtltex} and \ext{dbtex} file formats are also recognised +by the \texparserlib. The commands used in those files are not +intended for document use, but the files may be passed to +\idx{datatool2bib} as the input file. See the \sty{datatool} v3.0+ +user manual for further details of those formats. + +\prefixedcssection{datagidx}{newgidx} +Defines a new \sty{datagidx} database, which may be referenced in +\gls{datagidx.newterm} and \gls{datagidx.newacro} by the +\optfmt{database} key in their optional argument (which be parsed +and then dropped from the field list). + +\prefixedcssection{datagidx}{newterm} +This is similar to the \gls{newterm} command provided by +\sty{glossaries} (via the \styopt{index} package option), but has +slightly different behaviour. With \sty{datagidx}, the mandatory +argument is the name. The label may be supplied in the optional +argument. If omitted, the label is obtained from the name. The +\idx{datatool2bib} application will try to mimic the process used by +\sty{datagidx} to create the label from the name, but may not +produce an exact match. It's therefore important to double-check the +resulting \ext{bib} file afterwards. + +Each \gls{datagidx.newterm} will be converted to \atentry{entry} +unless it has both the \field{long} and \field{short} fields set, in +which case it will be converted to \atentry{abbreviation}. If there +is no \field{description} and \converterlongarg{index-conversion} is +used, then \atentry{index} will be used instead of \atentry{entry} +(but not if the term has been identified as an abbreviation). + +\prefixedcssection{datagidx}{newacro} +This is simply a wrapper command that internally uses +\gls{datagidx.newterm}. However, \idx{datatool2bib} has a slightly +different behaviour that doesn't add the formatting or case-changing +commands (since these can be dealt with by the abbreviation style or +\bibgls\ resource options). + \chapter{Examples} \label{sec:examples} \setsecdepth*{0} +\renewcommand{\cssectioncmd}{\subsection} The example files described here can be found in the \filefmt{examples} sub-directory. The \ext{bib} files are listed diff --git a/Master/texmf-dist/source/support/bib2gls/src/convertgls2bib.pod b/Master/texmf-dist/source/support/bib2gls/src/convertgls2bib.pod index 967b59aca4c..f011e252661 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/convertgls2bib.pod +++ b/Master/texmf-dist/source/support/bib2gls/src/convertgls2bib.pod @@ -1,15 +1,18 @@ =head1 SYNOPSIS -B<convertgls2bib> [I<option>]+ I<auxfile> +B<convertgls2bib> [I<option>]+ I<texfile> I<bibfile> =head1 DESCRIPTION Converts a B<.tex> file containing glossary definitions using commands like C<\newglossaryentry> and C<\newacronym> to a B<.bib> file in the format required for B<bib2gls>. +Distributed with F<bib2gls>. =head1 OPTIONS +=head2 GENERAL OPTIONS + =over 4 =item B<--help> or B<-h> @@ -20,18 +23,44 @@ Display help message and exit. Display version information and exit. -=item B<--silent> +=item B<--silent> or B<--quiet> or B<-q> Suppress all messages except for errors. =item B<--verbose> -Display messages. +Switch on verbose mode. + +=item B<--no-verbose> -=item B<--debug> +Switch off verbose mode. + +=item B<--debug> [I<n>] Display debugging messages. +=item B<--debug-mode> I<setting> + +May be used instead of B<--debug> where the level number is +difficult to remember. Value same as for B<bib2gls>'s +B<--debug-mode> option. + +=item B<--no-debug> + +Switch off debugging mode. Equivalent to B<--debug> B<0>. + +=item B<--log-file> I<filename> + +Log messages to given file. Intended primarily for debugging messages so +enabling debug mode will automatically create a transcript file, but otherwise +a file won't be created unless this option is used. + +=back + +=head2 ENCOSING AND LOCALISATION OPTIONS + +=over 4 + =item B<--texenc> I<name> Set the character encoding to I<name> for the input B<.tex> files. @@ -40,13 +69,48 @@ Set the character encoding to I<name> for the input B<.tex> files. Set the character encoding to I<name> for the output B<.bib> files. -=item B<--ignore-sort> +=item B<--locale> I<lang tag> -Ignore the B<sort> field (default). +Use the language resource files associated with the given language +tag I<lang tag>. If there isn't an appropriate file, the B<en> +(English) file will be used. -=item B<--no-ignore-sort> +=back -Don't ignore the B<sort> field. +=head2 FILTERING OPTIONS + +=over 4 + +=item B<--preamble-only> or B<-p> + +Only parse the document preamble. That is, stop parsing if +C<\begin{document}> encountered. + +=item B<--no-preamble-only> + +Parse the entire document (default). + +=item B<--ignore-fields> I<list> or B<-f> I<list> + +Ignore all the fields in the comma-separated I<list>. If the +list includes B<sort>, B<type> or B<category> it will automatically +implement the corresponding B<--ignore-sort>, B<--ignore-type> or +B<--ignore-category> option. Each item in the list should identify +the field by its original case-sensitive key. + +This option is cumulative. + +=item B<--no-ignore-fields> + +Cancels the effect of B<--ignore-fields>. + +=item B<--ignore-category> + +Omit the B<category> field. Default if B<--split-on-category>. + +=item B<--no-ignore-category> + +Don't omit the B<category> field. Default unless B<--split-on-category>. =item B<--ignore-type> @@ -56,6 +120,30 @@ Omit the B<type> field. Default if B<--split-on-type>. Don't omit the B<type> field. Default unless B<--split-on-type>. +=item B<--ignore-sort> + +Ignore the B<sort> field (default). + +=item B<--no-ignore-sort> + +Don't ignore the B<sort> field. + +=back + +=head2 OUTPUT FILE OPTIONS + +=over 4 + +=item B<--overwrite> + +Overwrite existing .bib files. Default unless B<--split-on-type> +used. + +=item B<--no-overwrite> + +Don't overwrite existing .bib files. Default if B<--split-on-type> +used. + =item B<--split-on-type> or B<-t> Split the entries into separate files according to the B<type> field. @@ -67,15 +155,7 @@ B<--no-overwrite>. Don't split the entries into separate files according to the B<type> field (default). -=item B<--ignore-category> - -Omit the B<category> field. Default if B<--split-on-category>. - -=item B<--no-ignore-category> - -Don't omit the B<category> field. Default unless B<--split-on-category>. - -=item B<--split-on-category> or B<-t> +=item B<--split-on-category> or B<-c> Split the entries into separate files according to the B<category> field. This option automatically implements B<--ignore-category> and @@ -86,25 +166,19 @@ B<--no-overwrite>. Don't split the entries into separate files according to the B<category> field (default). -=item B<--ignore-fields> I<list> or B<-f> I<list> +=back -Ignore all the fields in the comma-separated I<list>. If the -list includes B<sort>, B<type> or B<category> it will automatically -implement the corresponding B<--ignore-sort>, B<--ignore-type> or -B<--ignore--category> option. +=head2 ADJUSTMENT OPTIONS -This option isn't cumulative. An empty list will clear a previously -set list but won't undo the sort, type or category ignore options. +=over 4 -=item B<--overwrite> +=item B<--absorb-see> -Overwrite existing .bib files. Default unless B<--split-on-type> -used. +Absorb C<\glssee> and C<\glsxtrindexseealso> into the data (default). -=item B<--no-overwrite> +=item B<--no-absorb-see> -Don't overwrite existing .bib files. Default if B<--split-on-type> -used. +Don't absorb C<\glssee> and C<\glsxtrindexseealso> into the data. =item B<--index-conversion> or B<-i> @@ -118,31 +192,31 @@ and the B<description> field will be omitted. Don't use C<@index> instead of C<@entry> if the description is empty or just C<\nopostdesc> or C<\glsxtrnopostpunc> (default). -=item B<--absorb-see> - -Absorb C<\glssee> and C<\glsxtrindexseealso> into the data (default). - -=item B<--no-absorb-see> +=item B<--space-sub> I<value> or B<-s> I<value> -Don't absorb C<\glssee> and C<\glsxtrindexseealso> into the data. +Substitute spaces in labels with I<value>. -=item B<--preamble-only> or B<-p> +=item B<--field-map> I<mappings> or B<-m> I<mappings> -Only parse the document preamble. +Add source key to destination field label mapping. The argument +should be a comma-separated list of I<src-field>=I<dest-field> +pairs. This option is cumulative. -=item B<--no-preamble-only> +The deprecated B<--key-map> is a synonym of B<--field-map>. -Parse the entire document (default). +=item B<--no-field-map> -=item B<--space-sub> I<value> or B<-s> I<value> +Cancels all mappings applied with B<--field-map>. +The deprecated B<--no-key-map> is a synonym of B<--field-map>. -Substitute spaces in labels with I<value>. +=item B<--internal-field-map> I<mappings> -=item B<--locale> I<lang tag> +Adds the given mappings to the default set of internal field to key mappings. +(For example, B<desc> is the internal field label of the +B<description> key.) This option is cumulative. -Use the language resource files associated with the given language -tag I<lang tag>. If there isn't an appropriate file, the B<en> -(English) file will be used. +This option is only needed if the internal field label is supplied +in the argument of command such as C<\glssetnoexpandfield>. =back @@ -174,7 +248,7 @@ The glossaries manual: =head1 AUTHOR Nicola L. C. Talbot, -L<http://www.dickimaw-books.com/> +L<https://www.dickimaw-books.com/> =cut diff --git a/Master/texmf-dist/source/support/bib2gls/src/datatool2bib.pod b/Master/texmf-dist/source/support/bib2gls/src/datatool2bib.pod new file mode 100644 index 00000000000..230afc13053 --- /dev/null +++ b/Master/texmf-dist/source/support/bib2gls/src/datatool2bib.pod @@ -0,0 +1,387 @@ +=head1 SYNOPSIS + +B<datatool2bib> [I<option>]+ I<in-file> I<bibfile> + +=head1 DESCRIPTION + +Converts a F<.tex> file containing F<datatool.sty> databases to +a F<.bib> file in the format required for B<bib2gls>. +Distributed with F<bib2gls>. + +The TeX Parser Library is used to parse the input, which may be +a DTLTEX or DBTEX file or a file that contains +database construction commands, such as +C<\DTLnewdb> or C<\DTLaction>. The input file may also be a CSV file +if used with B<--read>. + +The B<datatool> and B<datagidx> are automatically implemented so the +input file does not need to include either them with C<\usepackage>. +In general, it's best not to include the entire document but instead +input a file that just contains the database construction commands, +as the TeX Parser Library only has a limited set of commands that it +recognises. + +=head1 OPTIONS + +=head2 GENERAL OPTIONS + +=over 4 + +=item B<--help> or B<-h> + +Display help message and exit. + +=item B<--version> or B<-v> + +Display version information and exit. + +=item B<--silent> or B<--quiet> or B<-q> + +Suppress all messages except for errors. + +=item B<--verbose> + +Switch on verbose mode. + +=item B<--no-verbose> + +Switch off verbose mode. + +=item B<--debug> [I<n>] + +Display debugging messages. + +=item B<--debug-mode> I<setting> + +May be used instead of B<--debug> where the level number is +difficult to remember. Value same as for B<bib2gls>'s +B<--debug-mode> option. + +=item B<--no-debug> + +Switch off debugging mode. Equivalent to B<--debug> B<0>. + +=item B<--log-file> I<filename> + +Log messages to given file. Intended primarily for debugging messages so +enabling debug mode will automatically create a transcript file, but otherwise +a file won't be created unless this option is used. + +=back + +=head2 ENCOSING AND LOCALISATION OPTIONS + +=over 4 + +=item B<--texenc> I<name> + +Set the character encoding to I<name> for the input B<.tex> files. + +=item B<--bibenc> I<name> + +Set the character encoding to I<name> for the output B<.bib> files. + +=item B<--locale> I<lang tag> + +Use the language resource files associated with the given language +tag I<lang tag>. If there isn't an appropriate file, the B<en> +(English) file will be used. + +=back + +=head2 FILTERING OPTIONS + +=over 4 + +=item B<--preamble-only> or B<-p> + +Only parse the document preamble. That is, stop parsing if +C<\begin{document}> encountered. + +=item B<--no-preamble-only> + +Parse the entire document (default). + +=item B<--ignore-fields> I<list> or B<-f> I<list> + +Ignore all the fields in the comma-separated I<list>. +Each item in the list should identify +the field by its original case-sensitive column key. + +This option is cumulative. + +=item B<--no-ignore-fields> + +Cancels the effect of B<--ignore-fields>. + +=item B<--skip-datagidx> + +Skip the special B<datagidx> internal database. +(Default.) + +=item B<--no-skip-datagidx> + +Don't skip the special B<datagidx> internal database. + +=back + +=head2 OUTPUT FILE OPTIONS + +=over 4 + +=item B<--overwrite> + +Overwrite existing .bib files. + +=item B<--no-overwrite> + +Don't overwrite existing .bib files. + +=item B<--split> + +Split the entries into separate files according to the database. + +=item B<--no-split> + +Don't split the entries into separate files (default). + +=back + +=head2 ADJUSTMENT OPTIONS + +=over 4 + +=item B<--space-sub> I<value> or B<-s> I<value> + +Substitute spaces in labels with I<value>. + +=item B<--field-map> I<mappings> or B<-m> I<mappings> + +Add source column key to destination field label mappings. The argument +should be a comma-separated list of I<col-key>=I<bib-field> +pairs. This option is cumulative. + +=item B<--no-field-map> + +Cancels all mappings applied with B<--field-map>. + +=item B<--index-conversion> or B<-i> + +Any entries that would normally be converted to C<@entry> that don't +have a B<description> field will be converted to C<@index>. + +=item B<--no-index-conversion> + +Don't replace C<@entry> with C<@index> if the description is missing (default). + +=item B<--detect-symbols> + +Attempt to detect entries that should be C<@symbol> or C<@number> +based on the value of the B<name> field. + +=item B<--no-detect-symbols> + +Don't attempt symbol detection (default). + + +=item B<--label> I<col-key> or B<-L> + +Use column identified by I<col-key> for the entry label. The default +column key is B<Label> so if the database doesn't have a column with +this key, you will either need to specify a column with B<--label> +or use B<--auto-label>. This option is ignored with B<--auto-label>. + +=item B<--auto-label> or B<-a> + +Auto-generate entry labels instead of using a column value. + +=item B<--no-auto-label> + +Don't auto-generate entry labels. Use the column identified by +B<--label> for the entry label. (Default.) + +=item B<--auto-label-prefix> I<prefix> + +Use I<prefix> when auto-generating entry labels. Ignored with +B<--no-auto-label>. + +=item B<--adjust-gls> + +Adjust labels in commands like C<\gls> in field values. (Default.) +This will also replace the F<datagidx.sty> commands like C<\glsnl> +with the closest F<glossaries.sty> equivalent. + +=item B<--no-adjust-gls> + +Don't adjust labels in commands like C<\gls> in field values. + +=item B<--dependency-field> I<field-name> + +Sets the name of the dependency field. Has no effect with +B<--no-strip-glsadd>. With B<--strip-glsadd>, the label from the +stripped C<\glsadd> argument will be added to the field identified +by I<field-name>. The default is B<dependency> which will be ignored +by B<bib2gls> unless instructed otherwise (via field aliasing etc). + +=item B<--no-dependency-field> + +Don't save labels from any stripped C<\glsadd> instances. + +=item B<--strip> + +Switch on all strip options. + +=item B<--no-strip> + +Switch off all strip options. + +=item B<--strip-glsadd> + +Strip C<\glsadd> and its argument from field values. (Default.) + +=item B<--no-strip-glsadd> + +Don't strip C<\glsadd> from field values. + +=item B<--strip-acronym-font> + +Strip C<\acronymfont> from field values. (Default.) + +=item B<--no-strip-acronym-font> + +Don't strip C<\acronymfont> from field values. + +=item B<--strip-acronym-text> + +Strip B<text> field for acronyms identified by C<\newacro>. +(Default.) + +=item B<--no-strip-acronym-text> + +Don't strip B<text> field for acronyms. + +=item B<--strip-acronym-name> + +Strip B<name> field for acronyms identified by C<\newacro>. +(Default.) + +=item B<--no-strip-acronym-name> + +Don't strip B<name> field for acronyms. + +=item B<--strip-case-change> + +Strip known case-changing commands (such as C<\makefirstuc> or C<\capitalisewords>) +from field values. + +=item B<--nostrip-case-change> + +Don't strip case-changing commands. (Default.) + +=back + +=head2 OTHER OPTIONS + +These options correspond to features introduced to F<datatool.sty> +version 3.0, which has a setting that stores the numeric value and +currency symbol (where applicable) when parsing data. The original +string (formatted number), numeric value and currency symbol are +stored in a special datum format, which ordinarily expands to its +original formatted text but also allows the previously parsed +information to be easily extracted without having to reparse the +data. + +=over 4 + +=item B<--setup> I<options> + +Implement C<\DTLsetup{>I<options>C<}> at the start. This can include +options such as C<store-datum>, C<new-value-expand>, +C<new-value-trim> and C<default-name>. + +=item B<--read> I<options> + +Instead of simply parsing the input file as a normal F<.tex> file, +the source is presented to the TeX parser as +C<\DTLread[>I<options>C<]{>I<in-file>C<}> where the options can be +used to specify the file format (for example, C<format=tsv>). + +If the I<options> list is empty (after trimming white space) then +this becomes equivalent to B<--no-read>. + +=item B<--no-read> + +The input file is parsed as a normal F<.tex> file, which may be the +complete document or a file that can be C<\input> into a document. +(Default.) + +=item B<--save-value> I<suffix> + +If a field value is parsed and identified as numeric, the +unformatted numeric value will be saved in a field whose name is +constructed from the original field name followed by the given +I<suffix>. + +=item B<--no-save-value> + +Don't save numeric value in a separate field. (Default.) + +=item B<--save-currency> I<suffix> + +If a field value is parsed and identified as currency data, the +currency symbol will be saved in a field whose name is +constructed from the original field name followed by the given +I<suffix>. + +=item B<--no-save-currency> + +Don't save currency symbol in a separate field. (Default.) + +=item B<--save-datum> + +Equivalent to: + + --save-value '-value' --save-currency '-currency' + +=item B<--no-save-datum> + +Equivalent to B<--no-save-value> B<--no-save-currency>. + +=back + +=head1 REQUIRES + +Java 8 and a TeX distribution. + +=head1 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. + +=head1 RECOMMENDED READING + +The bib2gls manual: + + texdoc bib2gls + +The glossaries-extra manual: + + texdoc glossaries-extra + +The glossaries manual: + + texdoc glossaries + +The datatool manual: + + texdoc datatool + +=head1 AUTHOR + +Nicola L. C. Talbot, +L<https://www.dickimaw-books.com/> + +=cut + 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 differindex d8f948d3a69..55cc0ed95f8 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/gls2bib-src.zip +++ 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 differindex 69406856be6..1880c516067 100644 --- a/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip +++ b/Master/texmf-dist/source/support/bib2gls/src/texparser-src.zip |