diff options
Diffstat (limited to 'support')
33 files changed, 521 insertions, 252 deletions
diff --git a/support/TeX4ht/source/ChangeLog b/support/TeX4ht/source/ChangeLog index f65184fe92..ed15608655 100644 --- a/support/TeX4ht/source/ChangeLog +++ b/support/TeX4ht/source/ChangeLog @@ -1,3 +1,8 @@ +2022-11-04 Michal Hoftich <michal.h21@gmail.com> + + * tex4ht-4ht.tex (xskak.4ht), + * tex4ht-html4.tex (html4.4ht): added support for the Xskak package. + 2022-11-02 Michal Hoftich <michal.h21@gmail.com> * tex4ht-mathml.tex (mathml.4ht): added extra group for \mathcal, to diff --git a/support/TeX4ht/source/mktex4ht-cnf.tex b/support/TeX4ht/source/mktex4ht-cnf.tex index 3d85a09637..bb78f1e571 100644 --- a/support/TeX4ht/source/mktex4ht-cnf.tex +++ b/support/TeX4ht/source/mktex4ht-cnf.tex @@ -1,4 +1,4 @@ -% $Id: mktex4ht-cnf.tex 1219 2022-10-20 14:40:14Z michal_h21 $ +% $Id: mktex4ht-cnf.tex 1235 2022-11-04 15:46:19Z michal_h21 $ % Manually-maintained file, listing *.4ht files created by tex4ht-4ht.tex. % Read by tex4ht-cond4ht. % @@ -373,6 +373,7 @@ \AddFile{9}{parallel} \AddFile{9}{skak} \AddFile{9}{chessboard} +\AddFile{9}{xskak} \AddFile{9}{texmate} \AddFile{9}{menukeys} \AddFile{9}{animate} diff --git a/support/TeX4ht/source/tex4ht-4ht.tex b/support/TeX4ht/source/tex4ht-4ht.tex index 88324fc0db..29bfdaf2db 100644 --- a/support/TeX4ht/source/tex4ht-4ht.tex +++ b/support/TeX4ht/source/tex4ht-4ht.tex @@ -1,4 +1,4 @@ -% $Id: tex4ht-4ht.tex 1229 2022-10-31 11:23:43Z michal_h21 $ +% $Id: tex4ht-4ht.tex 1235 2022-11-04 15:46:19Z michal_h21 $ % tex tex4ht-4ht or ht tex tex4ht-4ht % % Copyright 2009-2022 TeX Users Group @@ -33442,6 +33442,74 @@ of \''\:temp' below. %%%%%%%%%%%%%%%%%%%%%%%% +\Section{xskak.sty} +%%%%%%%%%%%%%%%%%%%%%%%% + +\<xskak.4ht\><<< +% xskak.4ht (|version), generated from |jobname.tex +% Copyright 2022 TeX Users Group +|<TeX4ht license text|> +|<xskak depth|> +|<xskak inline elements|> +|<xskak.sty|> +\Hinput{xskak} +\endinput +>>>\AddFile{9}{xskak} + +This command calculates vertical align for Xskak commands that can be used inline, +so the image is aligned correctly to the baseline of the surrounding text. + +\<xskak depth\><<< +\ExplSyntaxOn +\def\:xskakdepth{vertical-align:-\fp_eval:n{ + \dim_to_fp:n{\dp0}/(\dim_to_fp:n{\ht0}+\dim_to_fp:n{\dp0}) * 100 +}\@percentchar;} +\ExplSyntaxOff +>>> + +The following commands are used in text, so we save the result in a box, which can +be used for calculation of vertical alignment. + +\<xskak inline elements\><<< +\NewConfigure{mainline}{2} +\def\:tempa#1{% + \setbox0=\hbox{\o:mainline:{#1}}% + \edef\:xskakalt{\detokenize{#1}}% + %\a:mainline\Picture*[\detokenize{#1}]{ style="\:xskakdepth"}\box0\EndPicture\b:mainline% + \a:mainline\box0\b:mainline% +} +\HLet\mainline\:tempa + +\NewConfigure{xskakget}{2} +\def\:tempa#1{% + \edef\:xskakalt{\detokenize{#1}}% + \setbox0=\hbox{\o:xskakget:{#1}}% + \a:xskakget\box0\b:xskakget% +} +\HLet\xskakget\:tempa +>>> + +The chessboard configuration is defined by chessboard.4ht too. We declare it here +because + +\<xskak.sty\><<< +\NewConfigure{chessboard}{2} +>>> + +\<xskak.sty\><<< +\def\:tempa{% + % reset to the original version of \chessboard + \let\:currchesboard\chessboard + \let\chessboard\o:chessboard:% + \o:newchessgame:% + % set the TeX4ht version of \chessboard back + \let\chessboard\:currchesboard +} +\HLet\newchessgame\:tempa +>>> + + +%%%%%%%%%%%%%%%%%%%%%%%% \Section{texmate.sty} %%%%%%%%%%%%%%%%%%%%%%%% diff --git a/support/TeX4ht/source/tex4ht-html4.tex b/support/TeX4ht/source/tex4ht-html4.tex index b9119693d3..00502d272b 100644 --- a/support/TeX4ht/source/tex4ht-html4.tex +++ b/support/TeX4ht/source/tex4ht-html4.tex @@ -1,4 +1,4 @@ -% $Id: tex4ht-html4.tex 1226 2022-10-27 14:19:24Z michal_h21 $ +% $Id: tex4ht-html4.tex 1235 2022-11-04 15:46:19Z michal_h21 $ % Compile 4 times: latex tex4ht-html4 % Copy html4.4ht into the work directory before all but the last compilation. % @@ -19426,6 +19426,27 @@ latex.ltx, fontmath.ltx, plain.tex >>> %%%%%%%%%%%%%%%%% +\section{xskak} +%%%%%%%%%%%%%%%%% + +\<configure html4 xskak\><<< +\Configure{mainline}{\Picture*[\:xskakalt]{ style="\:xskakdepth"}}{\EndPicture} +\Configure{xskakget}{\Picture*[\:xskakalt]{ style="\:xskakdepth"}}{\EndPicture} +>>> + +%%%%%%%%%%%%%%%%% +\section{chessboard} +%%%%%%%%%%%%%%%%% + +If called from Xskak, we can use the xskakget command to get +chess notation as an alt text. + +\<configure html4 chessboard\><<< +\def\chessboard:alt{\ifdefined\o:xskakget:\o:xskakget:{nextfen}\fi} +\Configure{chessboard}{\Picture*[\chessboard:alt]{}}{\EndPicture} +>>> + +%%%%%%%%%%%%%%%%% \section{texmate} \<configure html4 texmate\><<< diff --git a/support/bib2gls/CHANGES b/support/bib2gls/CHANGES index a00bda1966..a3e2fbcaac 100644 --- a/support/bib2gls/CHANGES +++ b/support/bib2gls/CHANGES @@ -1,3 +1,22 @@ +v3.1 (2022-11-05): + + * If new versions of glossaries.sty, mfirstuc.sty and glossaries-extra.sty + are detected, \bibglsuppercase and \bibglslowercase will now + have \glsuppercase and \glslowercase in their definition, + instead of \MakeTextUppercase and \MakeTextLowercase + + * skip empty elements in src + + * added resource option merge-ranges + + * added support for \ifglsfieldvoid + + * bug fix: secondary sort type not included in group label + + * TeX parser library (texparserlib.jar) now has limited support + for \NewDocumentCommand, \RenewDocumentCommand, + \ProvideDocumentCommand and \DeclareDocumentCommand. + v3.0 (2022-10-14): * support for \glsxtr@select@entry and \glsxtr@select@entry@nameref diff --git a/support/bib2gls/bib2gls-begin.pdf b/support/bib2gls/bib2gls-begin.pdf Binary files differindex 4e3e53dcdc..c825f2b8c0 100644 --- a/support/bib2gls/bib2gls-begin.pdf +++ b/support/bib2gls/bib2gls-begin.pdf diff --git a/support/bib2gls/bib2gls-en.xml b/support/bib2gls/bib2gls-en.xml index 29947b6bb6..1deb254d84 100644 --- a/support/bib2gls/bib2gls-en.xml +++ b/support/bib2gls/bib2gls-en.xml @@ -364,6 +364,7 @@ Aliased entries must be in the same resource set as their target entries with op <entry key="warning.exclusions.unknown.token">Unknown token in exclusion list: {0}</entry> <entry key="warning.blockers.unknown.token">Unknown token in blocker list: {0}</entry> <entry key="warning.mappings.cant.parse">Can''t parse mapping list: {0}</entry> +<entry key="warning.mismatched.sty">Mismatching versions of packages {0} ({1}) and {2} ({3}). Please upgrade {2}</entry> <entry key="error.title">Error: {0}</entry> <entry key="error.alias.map.forbidden">The 'alias' field can't be mapped.</entry> @@ -597,6 +598,7 @@ converted to @dualabbreviationentry.)</entry> <entry key="latex.package.not.loaded">Package ''{0}'' has not been loaded</entry> <entry key="latex.error.counter.too.large">Counter too large</entry> <entry key="latex.error.counter.out.of.range">Counter value {0} out of valid range ({1})</entry> +<entry key="latex.unsupported.xparse_type">Unsupported xparse type {0} in command {1}</entry> <entry key="bibtex.error.missing_value">Missing value</entry> <entry key="bibtex.error.expecting">Expecting ''{0}''</entry> diff --git a/support/bib2gls/bib2gls.pdf b/support/bib2gls/bib2gls.pdf Binary files differindex 77ed097987..e23282b73c 100644 --- a/support/bib2gls/bib2gls.pdf +++ b/support/bib2gls/bib2gls.pdf diff --git a/support/bib2gls/examples/sample-authors.pdf b/support/bib2gls/examples/sample-authors.pdf Binary files differindex 9a4103cbf4..5094e02ec7 100644 --- a/support/bib2gls/examples/sample-authors.pdf +++ b/support/bib2gls/examples/sample-authors.pdf diff --git a/support/bib2gls/examples/sample-bacteria.pdf b/support/bib2gls/examples/sample-bacteria.pdf Binary files differindex 291ebb781e..f8bc312fef 100644 --- a/support/bib2gls/examples/sample-bacteria.pdf +++ b/support/bib2gls/examples/sample-bacteria.pdf diff --git a/support/bib2gls/examples/sample-chemical.pdf b/support/bib2gls/examples/sample-chemical.pdf Binary files differindex a2f40c87e0..0d303e4783 100644 --- a/support/bib2gls/examples/sample-chemical.pdf +++ b/support/bib2gls/examples/sample-chemical.pdf diff --git a/support/bib2gls/examples/sample-citations.pdf b/support/bib2gls/examples/sample-citations.pdf Binary files differindex 5bc3bf66ee..46c9b2e8a9 100644 --- a/support/bib2gls/examples/sample-citations.pdf +++ b/support/bib2gls/examples/sample-citations.pdf diff --git a/support/bib2gls/examples/sample-constants.pdf b/support/bib2gls/examples/sample-constants.pdf Binary files differindex 52152df16b..07c5a9b596 100644 --- a/support/bib2gls/examples/sample-constants.pdf +++ b/support/bib2gls/examples/sample-constants.pdf diff --git a/support/bib2gls/examples/sample-hierarchical.pdf b/support/bib2gls/examples/sample-hierarchical.pdf Binary files differindex eec25021db..9f83fe64da 100644 --- a/support/bib2gls/examples/sample-hierarchical.pdf +++ b/support/bib2gls/examples/sample-hierarchical.pdf diff --git a/support/bib2gls/examples/sample-markuplanguages.pdf b/support/bib2gls/examples/sample-markuplanguages.pdf Binary files differindex 49b5ea397f..959a97cfbf 100644 --- a/support/bib2gls/examples/sample-markuplanguages.pdf +++ b/support/bib2gls/examples/sample-markuplanguages.pdf diff --git a/support/bib2gls/examples/sample-markuplanguages.tex b/support/bib2gls/examples/sample-markuplanguages.tex index aba4cbf219..925f8e8c11 100644 --- a/support/bib2gls/examples/sample-markuplanguages.tex +++ b/support/bib2gls/examples/sample-markuplanguages.tex @@ -38,7 +38,7 @@ \glssetcategoryattribute{markuplanguage}{glossname}{firstuc} -\renewcommand*{\glsxtrtagfont}[1]{\underline{\MakeTextUppercase{#1}}} +\renewcommand*{\glsxtrtagfont}[1]{\underline{\glsuppercase{#1}}} \begin{document} diff --git a/support/bib2gls/examples/sample-maths.pdf b/support/bib2gls/examples/sample-maths.pdf Binary files differindex 7489b36c4c..327dea9a3e 100644 --- a/support/bib2gls/examples/sample-maths.pdf +++ b/support/bib2gls/examples/sample-maths.pdf diff --git a/support/bib2gls/examples/sample-media.pdf b/support/bib2gls/examples/sample-media.pdf Binary files differindex 7838716497..085fba316a 100644 --- a/support/bib2gls/examples/sample-media.pdf +++ b/support/bib2gls/examples/sample-media.pdf diff --git a/support/bib2gls/examples/sample-msymbols.pdf b/support/bib2gls/examples/sample-msymbols.pdf Binary files differindex 5b83de642e..1a9fef2971 100644 --- a/support/bib2gls/examples/sample-msymbols.pdf +++ b/support/bib2gls/examples/sample-msymbols.pdf diff --git a/support/bib2gls/examples/sample-multi1.pdf b/support/bib2gls/examples/sample-multi1.pdf Binary files differindex feb6e36e18..0376963383 100644 --- a/support/bib2gls/examples/sample-multi1.pdf +++ b/support/bib2gls/examples/sample-multi1.pdf diff --git a/support/bib2gls/examples/sample-multi2.pdf b/support/bib2gls/examples/sample-multi2.pdf Binary files differindex 65a6867d42..c356c6c2f9 100644 --- a/support/bib2gls/examples/sample-multi2.pdf +++ b/support/bib2gls/examples/sample-multi2.pdf diff --git a/support/bib2gls/examples/sample-nested.pdf b/support/bib2gls/examples/sample-nested.pdf Binary files differindex da75246646..9b59f762b1 100644 --- a/support/bib2gls/examples/sample-nested.pdf +++ b/support/bib2gls/examples/sample-nested.pdf diff --git a/support/bib2gls/examples/sample-people.pdf b/support/bib2gls/examples/sample-people.pdf Binary files differindex bc03fd1e1c..8824610553 100644 --- a/support/bib2gls/examples/sample-people.pdf +++ b/support/bib2gls/examples/sample-people.pdf diff --git a/support/bib2gls/examples/sample-textsymbols.pdf b/support/bib2gls/examples/sample-textsymbols.pdf Binary files differindex ce6b25d425..64aab9e3ac 100644 --- a/support/bib2gls/examples/sample-textsymbols.pdf +++ b/support/bib2gls/examples/sample-textsymbols.pdf diff --git a/support/bib2gls/examples/sample-textsymbols2.pdf b/support/bib2gls/examples/sample-textsymbols2.pdf Binary files differindex 4f6fd3116b..f50f6f721d 100644 --- a/support/bib2gls/examples/sample-textsymbols2.pdf +++ b/support/bib2gls/examples/sample-textsymbols2.pdf diff --git a/support/bib2gls/examples/sample-units1.pdf b/support/bib2gls/examples/sample-units1.pdf Binary files differindex fdf5d60878..f5c7275af8 100644 --- a/support/bib2gls/examples/sample-units1.pdf +++ b/support/bib2gls/examples/sample-units1.pdf diff --git a/support/bib2gls/examples/sample-units2.pdf b/support/bib2gls/examples/sample-units2.pdf Binary files differindex e9641f4918..7445d761e6 100644 --- a/support/bib2gls/examples/sample-units2.pdf +++ b/support/bib2gls/examples/sample-units2.pdf diff --git a/support/bib2gls/examples/sample-units3.pdf b/support/bib2gls/examples/sample-units3.pdf Binary files differindex 897e09a989..2d1e53be63 100644 --- a/support/bib2gls/examples/sample-units3.pdf +++ b/support/bib2gls/examples/sample-units3.pdf diff --git a/support/bib2gls/examples/sample-usergroups.pdf b/support/bib2gls/examples/sample-usergroups.pdf Binary files differindex 74cbc7cbe5..27bcbecd59 100644 --- a/support/bib2gls/examples/sample-usergroups.pdf +++ b/support/bib2gls/examples/sample-usergroups.pdf diff --git a/support/bib2gls/src/bib2gls-begin.tex b/support/bib2gls/src/bib2gls-begin.tex index 95993aae36..b0c002641e 100644 --- a/support/bib2gls/src/bib2gls-begin.tex +++ b/support/bib2gls/src/bib2gls-begin.tex @@ -655,7 +655,29 @@ as \gls{commentchar} (percent), \gls{ampchar} (ampersand), \gls{param} (hash), \gls{mshiftchar} (dollar), or \gls{nbspchar} (tilde). Be careful of packages that make other characters active (such as \isty{babel} with its shortcuts). If you are using \isty{inputenc}, this also includes extended Latin characters and -characters from other scripts. If you want to include UTF-8 characters in the +characters from other scripts. + +Recent updates to the \LaTeX\ kernel mean that there's much better +support for UTF-8 characters. Ensure that you have at least +\sty{glossaries} v4.50, \sty{glossaries-extra} v1.49 and +\sty{mfirstuc} 2.08. It's now possible to have: +\begin{codeenv} +\gls{newglossaryentry}\marg{élite}\comment{label} +\marg{ + \field{name} = \marg{élite}, + \field{description} = \marg{group of people regarded as + the best of a particular society or organisation} +} +\end{codeenv} +Regardless of whether or not you use a native UTF-8 engine, provided +you have a new \TeX\ distribution. + +\begin{important} +The UTF-8 information below refers to older +versions and older kernels. +\end{important} + +If you want to include UTF-8 characters in the label then you must use a \TeX\ engine with native Unicode support (that is, \XeLaTeX\ or \LuaLaTeX). @@ -4665,36 +4687,14 @@ Additionally, depending on the page style, the section argument may also be reproduced in the page header. This repeated use of the same material can cause complications, in particular it can prematurely triggering the \idx{firstuseflag} switch and cause unwanted -indexing. If the content appears in the page header and the page -styles converts headers to upper case, this can also cause a -problem. +indexing. -For example: -\begin{codeenv} -\cmd{documentclass}\marg{book} -\strut -\cmd{usepackage}\marg{lipsum}\comment{provides \cmd{lipsum}} -\cmd{usepackage}\marg{glossaries} -\strut -\gls{newglossaryentry}\marg{sample}\marg{\field{name}=\marg{sample},\field{description}=\marg{an example}} -\strut -\cmd{begin}{document} -\gls{chapter}\marg{A \gls{gls}\marg{sample} chapter} -\cmd{lipsum} \comment{dummy text} -\cmd{end}\marg{document} -\end{codeenv} -I've used \csfmt{lipsum} here to create some dummy text that ensures -a multi-paged document because the problem doesn't occur until the second -page. The error message is: -\begin{verbatim} -Glossary entry `SAMPLE' has not been defined. -\end{verbatim} -The problem here is that the chapter title is copied to the header -(which doesn't appear on the chapter's first page) but the header -uses \gls{MakeUppercase}, which can't expand \gls{gls} but it does -change the label, so \code{\gls{gls}\marg{sample}} is converted to -\code{\gls{gls}\marg{SAMPLE}}, but there's no entry with that label. -(Labels are case-sensitive.) +If the content appears in the page header and the page +styles converts headers to upper case, this can also cause a +problem. However, if you make sure you have \sty{glossaries} v4.50+, +\sty{glossaries-extra} v1.49+ and \sty{mfirstuc} v2.08+ with a +recent \TeX\ distribution, most of the case-changing problems should +now no longer occur. Here's an example that doesn't cause an error (because there's not enough text to trigger a page break) but does cause unexpected output: @@ -4769,8 +4769,8 @@ case-change hasn't been applied, so the page heading appears as: \begin{result} 4\hfill \emph{CHAPTER 1. A CHAPTER ABOUT hypertext markup language} \end{result} -This can be corrected by setting the \catattr{headuc} attribute to -\code{true}: +This shouldn't occur any more, but if it does, it can be corrected by +setting the \catattr{headuc} attribute to \code{true}: \begin{codeenv} \gls{glssetcategoryattribute}\marg{abbreviation}\marg{headuc}\marg{true} \end{codeenv} @@ -4802,14 +4802,14 @@ the \sty{slantsc} package. Another possibility is to redefine: which is used by the \qt{sc} abbreviation styles: \begin{codeenv} \cmd{renewcommand}\marg{\gls{glsabbrvscfont}}[1]\marg{\comment{} - \gls{glsxtrifinmark}\marg{\gls{MakeTextUppercase}\marg{\gls{param}1}}\marg{\gls{textsc}\marg{\gls{param}1}}\comment{} + \gls{glsxtrifinmark}\marg{\gls{glsuppercase}\marg{\gls{param}1}}\marg{\gls{textsc}\marg{\gls{param}1}}\comment{} } \end{codeenv} This uses: \nosecformatdef{glsxtrifinmark} which expands to \meta{true} in headings and the \gls{toc}, otherwise it expands to \meta{false}. This use of -\gls{MakeTextUppercase} replaces the need for the \catattr{headuc} +\gls{glsuppercase} replaces the need for the \catattr{headuc} attribute. Both \catattr{headuc} and the above redefinition of \gls{glsabbrvscfont} will cause the abbreviation to appear in \idx{uppercase} in the \gls{toc}. If you don't want this, @@ -4826,7 +4826,7 @@ which makes \gls{glsxtrifinmark} expand to \meta{false} in the \cmd{usepackage}\marg{glossaries-extra} \strut \cmd{renewcommand}\marg{\gls{glsabbrvscfont}}[1]\marg{\comment{} - \gls{glsxtrifinmark}\marg{\gls{MakeTextUppercase}\marg{\gls{param}1}}\marg{\gls{textsc}{\gls{param}1}}\comment{} + \gls{glsxtrifinmark}\marg{\gls{glsuppercase}\marg{\gls{param}1}}\marg{\gls{textsc}{\gls{param}1}}\comment{} } \strut \gls{setabbreviationstyle}\marg{\abbrstyle{long-short-sc}} @@ -4867,125 +4867,6 @@ Instead, use \gls{glsentrysymbol}: Better still, use commands like \gls{glsxtrpostlinkAddSymbolOnFirstUse} (see \sectionref{sec:postlinkhooks}). -The next most problematic nesting is the use of \gls{gls} in -abbreviations. It's far more of a problem if you only use the base -\sty{glossaries} package. For example: -\begin{codeenv} -\cmd{documentclass}\marg{book} -\strut -\gls{usepackage}\marg{glossaries} -\strut -\gls{newacronym}\marg{ssi}\marg{SSI}\marg{server-side includes} -\gls{newacronym}\marg{html}\marg{HTML}\marg{hypertext markup language} -\gls{newacronym}\marg{shtml}\marg{SHTML}\marg{\gls{gls}\marg{ssi} enabled \gls{gls}\marg{html}}\incorrect -\strut -\cmd{begin}\marg{document} -\gls{gls}\marg{shtml}. -\cmd{end}\marg{document} -\end{codeenv} -This results in: -\begin{result} -server-side includes (SSI) enabled hypertext markup language (HTML) (SHTML). -\end{result} -The \sty{glossaries-extra} package temporarily changes \gls{gls} -within the \idx{link-text} to avoid this type of problem. -\begin{codeenv} -\cmd{documentclass}\marg{book} -\strut -\cmd{usepackage}\marg{glossaries-extra} -\strut -\gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes} -\gls{newabbreviation}\marg{html}\marg{HTML}\marg{hypertext markup language} -\gls{newabbreviation}\marg{shtml}\marg{SHTML}\marg{\gls{gls}\marg{ssi} enabled \gls{gls}\marg{html}} -\strut -\cmd{begin}\marg{document} -\gls{gls}\marg{shtml}. -\cmd{end}\marg{document} -\end{codeenv} -This now produces: -\begin{result} -SSI enabled HTML (SHTML). -\end{result} -This doesn't seem so bad, but now let's see what happens if the -\catattr{glossdesc} is set to \code{firstuc}: -\begin{codeenv} -\cmd{documentclass}\marg{book} -\strut -\cmd{usepackage}\marg{glossaries-extra} -\strut -\gls{glssetcategoryattribute}\marg{abbreviation}\marg{\catattr{glossdesc}}\marg{firstuc} -\gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes} -\gls{newabbreviation}\marg{html}\marg{HTML}\marg{hypertext markup language} -\gls{newabbreviation}\marg{shtml}\marg{SHTML}\marg{\gls{gls}\marg{ssi} enabled \gls{gls}\marg{html}}\incorrect -\strut -\cmd{begin}\marg{document} -\gls{gls}\marg{shtml}. -\gls{printunsrtglossary} -\cmd{end}\marg{document} -\end{codeenv} -This now causes an error: -\begin{verbatim} -! Missing \endcsname inserted. -<to be read again> - \protect -\end{verbatim} -The problem here is that the first-letter upper-casing command is -being applied to \code{\gls{gls}\marg{ssi}}. This results in -\code{\gls{gls}\marg{\gls{MakeTextUppercase} ssi}} which has an -invalid label. A workaround is to insert an empty group before -the initial \gls{gls}: -\begin{codeenv} -\gls{newabbreviation}\marg{shtml}\marg{SHTML}\marg{\marg{}\gls{gls}\marg{ssi} enabled \gls{gls}\marg{html}} -\end{codeenv} -However, \gls{gls} functions normally within the glossary, so the -result is: -\begin{result} -\textbf{SSI} Server-side includes - -\textbf{HTML} Hypertext markup language - -\textbf{SHTML} server-side includes (SSI) enabled hypertext markup language (HTML) -\end{result} -Since neither \code{ssi} nor \code{html} have been referenced in the -document, the reference in the \code{shtml} description in the -glossary is the \idx{firstuse} for both of them, so they show the -full form, but the upper-casing can't be applied. This means that -the description for the \code{shtml} entry doesn't start with an -\idx{uppercase} letter. The best solution is to avoid using -\gls{gls} in the \field{long} field: -\begin{codeenv} -\cmd{documentclass}\marg{book} -\strut -\cmd{usepackage}[\styopt{record}]\marg{glossaries-extra} -\strut -\gls{glssetcategoryattribute}\marg{abbreviation}\marg{glossdesc}\marg{firstuc} -\strut -\gls[noindex]{glsdefpostdesc}\marg{abbreviation}\marg{\comment{} - \gls{glsxtrifhasfield}\marg{\field{seealso}}\marg{\gls{glscurrententrylabel}}\comment{} - \marg{ (\gls{emph}\marg{see also} \gls[noindex=false]{glsxtrseelist}\marg{\gls{glscurrentfieldvalue}})}\comment{} - \marg{}\comment{} -} -\strut -\gls{newabbreviation}\marg{ssi}\marg{SSI}\marg{server-side includes} -\gls{newabbreviation}\marg{html}\marg{HTML}\marg{hypertext markup language} -\gls{newabbreviation}\oarg{\field{seealso}=\marg{ssi,html}}\marg{shtml}\marg{SHTML} -\marg{server-side includes enabled hypertext markup language} -\strut -\cmd{begin}\marg{document} -\gls{Gls}\marg{shtml}. -\gls{printunsrtglossary} -\cmd{end}\marg{document} -\end{codeenv} -I've used the \field{seealso} key here. (The value should be a -comma-separated list of labels.) It doesn't show -in the glossary by default as it needs an indexing application to add it -automatically to the \idx{locationlist}, so I've used the -\idx{postdescriptionhook} to append the cross-reference. The -\styopt{record} option is needed, otherwise the default -\gls{makeindex} setting will be assumed and an error will occur as -the associated \gls{makeindex} file hasn't been opened. If \bibgls\ -support is added then the hook won't be needed. - \section{Shortcut Commands or Active Characters} \label{sec:activeshortcuts} diff --git a/support/bib2gls/src/bib2gls-terms.bib b/support/bib2gls/src/bib2gls-terms.bib index 10cb3b3eec..8ca871f605 100644 --- a/support/bib2gls/src/bib2gls-terms.bib +++ b/support/bib2gls/src/bib2gls-terms.bib @@ -409,7 +409,7 @@ user1={idx.ignoredglossary}, description={A glossary defined with commands like \cs{newignoredglossary}. An ignored glossary doesn't have an -associated title (so it one is required it needs to be explicitly +associated title (so if one is required it needs to be explicitly set), and isn't picked up by iterative commands such as \cs{printunsrtglossaries}. See \sectionref{sec:newglossary}.} } diff --git a/support/bib2gls/src/bib2gls.bib b/support/bib2gls/src/bib2gls.bib index b55acf3f20..9f2d002928 100644 --- a/support/bib2gls/src/bib2gls.bib +++ b/support/bib2gls/src/bib2gls.bib @@ -1078,6 +1078,16 @@ given label}, category={command} } +@mainglscommand{glssubgroupheading, + name={\csfmt{gls\-sub\-group\-heading}}, + user1={\margm{previous level}\margm{level}\margm{parent-label}\margm{group-label}}, + description={formats the heading for the \idx{sub-group} identified by the +given label}, + topics={glossarystylecommands,formattingcommands}, + note={\styfmt{glossaries-extra} v1.49+}, + category={command} +} + @bibglscommand{bibglssetlastgrouptitle, name={\csfmt{bib\-gls\-set\-last\-group\-title}}, user1={\margm{cs}\margm{specs}}, @@ -1108,7 +1118,7 @@ given label}, @bibglscommand{bibglsgrouplevel, name={\csfmt{bib\-gls\-group\-level}}, user1={\margm{label}{n}}, - description={expands to the group label for hierarchical level \meta{n} + description={expands to the \idx{sub-group} label for hierarchical level \meta{n} where \meta{label} is the label that would normally be applied to level~0}, topics={glossarystylecommands,groupcommands}, @@ -1119,7 +1129,7 @@ given label}, @bibglscommand{bibglshiersubgrouptitle, name={\csfmt{bib\-gls\-hier\-sub\-group\-title}}, user1={\marg{level}\marg{parent}\marg{title}}, - description={formats the title for a hierarchical group where the + description={formats the title for a \idx{hiergroup} where the normal non-hierarchical title would be \meta{title}}, topics={glossarystylecommands,groupcommands}, note={\bibgls}, @@ -3168,6 +3178,13 @@ field\dhyphen locale}}, parent={resourceoptions} } +@resourceoption{opt.merge-ranges, + name={\csoptfmt{merge\dhyphen ranges}}, + user1={\meta{boolean}}, + category={resourceoption}, + parent={resourceoptions} +} + @resourceoption{opt.min-loc-range, name={\csoptfmt{min\dhyphen loc\dhyphen range}}, user1={\meta{value}}, @@ -10570,6 +10587,73 @@ primary formats, if enabled.}, name={custom group} } +@index{sub-group} +@index{hiergroup, + name={hierarchical group}, + alias={sub-group} +} +@index{smallgroup, + name={small group} +} + +@indexplural{group} +@index{groups.letter, + parent={group}, + name={letter}, + text={letter group}, + alias={lettergroup}} +@index{groups.nonletter, + parent={group}, + name={non-letter}, + text={non-letter group}, + alias={nonlettergroup} +} +@index{groups.symbol, + parent={group}, + name={symbol}, + text={symbol group}, + alias={symbolgroup}} +@index{groups.empty, + parent={group}, + name={empty}, + text={empty group}, + alias={emptygroup}} +@index{groups.number, + parent={group}, + name={number}, + text={number group}, + alias={numbergroup}} +@index{groups.datetime, + parent={group}, + name={datetime}, + text={datetime group}, + alias={datetimegroup}} +@index{groups.date, + parent={group}, + name={date}, + text={date group}, + alias={dategroup}} +@index{groups.time, + parent={group}, + name={time}, + text={time group}, + alias={timegroup}} +@index{groups.custom, + parent={group}, + name={custom}, + text={custom group}, + alias={customgroup}} +@index{groups.sub, + parent={group}, + name={hierarchical}, + text={hierarchical group}, + alias={sub-group}} +@index{groups.small, + parent={group}, + name={small}, + text={small group}, + alias={smallgroup}} + @index{localeprovider, name={locale provider} } @@ -10591,6 +10675,24 @@ primary formats, if enabled.}, name = {location list} } +@index{range} +@index{explicit-range, + parent={range}, + name={explicit}, + text={explicit range} +} +@index{implicit-range, + parent={range}, + name={implicit}, + text={implicit range} +} +@index{interloper,parent={range}} +@index{locationrange, + parent={locationlist}, + name={ranges}, + alias={range} +} + @index{postlinkhook, name={post-link hook} } @@ -12703,14 +12805,31 @@ field value}, category={command} } +@glscommand{ifglsfieldvoid, + name={\csfmt{if\-gls\-field\-void}}, + user1={\margm{field label}\margm{entry label}\margm{true}\margm{false}}, + description={expands to \meta{true} if the given entry doesn't +exist, or exists but doesn't have the field (identified by its +internal field label) defined or does have the field defined but the +field is empty. Otherwise expands to \meta{false}. This is +essentially like \gls{GlsXtrIfFieldUndef} but also +tests for an empty value}, + topics={conditional,fieldrefcommands}, + note={\styfmt{glossaries} v4.50+\texparserdefnote}, + seealso={GlsXtrIfFieldUndef}, + category={command} +} + @glscommand{GlsXtrIfFieldUndef, name={\csfmt{Gls\-Xtr\-If\-Field\-Undef}}, user1={\margm{field label}\margm{entry label}\margm{true}\margm{false}}, - description={tests if the given field isn't defined for the given + description={tests if the given field (identified by its +internal field label) isn't defined for the given entry, which may also not exist}, topics={conditional,fieldrefcommands}, note={\styfmt{glossaries-extra} v1.23+}, - category={command} + category={command}, + seealso={ifglsfieldvoid}, } @glscommand{GlsXtrIfFieldEqStr, @@ -13566,6 +13685,30 @@ letter to \idx{uppercase}}, category={command} } +@glscommand{glsstartrange, + name={\csfmt{gls\-start\-range}}, + user1={\oargm{options}\margm{label list}}, + description={essentially like + \code{\cs{glsaddeach}\oarg{\glsopt[\idx{openrange}]{format},\meta{options}}\margm{label-list}}. + If \glsopt{format} is used in \meta{options}, the open marker + \idx{openrange} will be inserted in front of the value}, + topics={indexing}, + note={\styfmt{glossaries-extra} v1.50+}, + category={command} +} + +@glscommand{glsendrange, + name={\csfmt{gls\-end\-range}}, + user1={\oargm{options}\margm{label list}}, + description={essentially like + \code{\cs{glsaddeach}\oarg{\glsopt[\idx{closerange}]{format},\meta{options}}\margm{label-list}}. + If \glsopt{format} is used in \meta{options}, the close marker + \idx{closerange} will be inserted in front of the value}, + topics={indexing}, + note={\styfmt{glossaries-extra} v1.50+}, + category={command} +} + @glsaddoption{glsadd.thevalue, name={\csoptfmt{thevalue}}, user1={\margm{value}}, @@ -14093,6 +14236,43 @@ usual delay}, category={command} } +@command{NewDocumentCommand, + name={\csfmt{New\-Document\-Com\-mand}}, + user1={\margm{cs}\margm{arg specs}\margm{code}}, + description={defines a new robust command (only partially +implemented by \TeX\ Parser Library)}, + note={\LaTeX3 command\texparserdefnote}, + category={command} +} + +@command{RenewDocumentCommand, + name={\csfmt{Renew\-Document\-Com\-mand}}, + user1={\margm{cs}\margm{arg specs}\margm{code}}, + description={redefines a new robust command (only partially +implemented by \TeX\ Parser Library)}, + note={\LaTeX3 command\texparserdefnote}, + category={command} +} + +@command{ProvideDocumentCommand, + name={\csfmt{Provide\-Document\-Com\-mand}}, + user1={\margm{cs}\margm{arg specs}\margm{code}}, + description={provides a robust command, if not already defined (only partially +implemented by \TeX\ Parser Library)}, + note={\LaTeX3 command\texparserdefnote}, + category={command} +} + +@command{DeclareDocumentCommand, + name={\csfmt{Declare\-Document\-Com\-mand}}, + user1={\margm{cs}\margm{arg specs}\margm{code}}, + description={defines a robust command, regardless of whether or not + it has already been defined (only partially +implemented by \TeX\ Parser Library)}, + note={\LaTeX3 command\texparserdefnote}, + category={command} +} + @command{section, name={\csfmt{section}}, user1={\oargm{\idx{toc} title}\margm{title}}, @@ -16646,6 +16826,22 @@ has three or more items}, category={command} } +@command{glslowercase, + name={\csfmt{gls\-lower\-case}}, + user1={\margm{text}}, + description={converts \meta{text} to lower case}, + note={\styfmt{glossaries} v4.50+\texparserdefnote}, + category={command} +} + +@command{glsuppercase, + name={\csfmt{gls\-upper\-case}}, + user1={\margm{text}}, + description={converts \meta{text} to \idx{uppercase}}, + note={\styfmt{glossaries} v4.50+\texparserdefnote}, + category={command} +} + @command{MakeTextLowercase, name={\csfmt{Make\-Text\-Lower\-case}}, user1={\margm{text}}, diff --git a/support/bib2gls/src/bib2gls.tex b/support/bib2gls/src/bib2gls.tex index 0bee0fd314..dd56fedc31 100644 --- a/support/bib2gls/src/bib2gls.tex +++ b/support/bib2gls/src/bib2gls.tex @@ -1663,14 +1663,14 @@ the order in which the glossaries were defined. You may use preferred order. \end{important} -\item[\field{group}] The entries within a glossary can form groups +\item[\field{group}] The entries within a glossary can form \idxpl{group} as a by-product of the sorting method. This must be enabled with the \longarg{group} switch and isn't available for the sort methods listed in \tableref{tab:sortoptionsnosort}. The group label is stored in the \field{group} field. This is an internal field that typically shouldn't be set in the \ext{bib} file. -You can specify your own custom groups but if you do so you must +You can specify your own \idxpl{customgroup} but if you do so you must ensure that the terms are ordered in such a way that they are gathered according to group. This is typically done by splitting the glossary into blocks using a separate \gls{GlsXtrLoadResources} with @@ -1719,7 +1719,7 @@ commands within the document. For example: Suppose that your list of terms spans many pages and you feel it would be helpful to the reader to split it up into letter groups then you would need to run \bibgls\ with the \longarg{group} switch -and use a glossary style that supports letter groups for that +and use a glossary style that supports \idxpl{lettergroup} for that glossary. For example: \begin{codeenv} \cs{printunsrtglossary}\oarg{\printglossopt[indexgroup]{style}} @@ -3042,7 +3042,7 @@ 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 letter group for each entry and assign it to the +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 @@ -3052,6 +3052,11 @@ if group headings are required (for example with the 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 @@ -3514,13 +3519,18 @@ Don't check for instances of \ics{citation} in the \ext{aux} file \argsection{collapse-same-location-range} -Collapse any explicit \gls{location} range into a normal \gls{record} if -the \glspl{location} are the same (default). +Collapse any \idx{explicit-range} into a normal \gls{record} if +the start and end \glspl{location} are the same (default). +This record will be treated as a normal \gls{location} that can be +merged with neighbouring \glspl{location}, regardless of +\csopt{merge-ranges}. \argsection{no-collapse-same-location-range} -Don't collapse any explicit \gls{location} range into a normal -\gls{record} if the \glspl{location} are the same. +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}. \argsection{map-format} @@ -3539,8 +3549,8 @@ This essentially means that if there's a \gls{record} conflict involving \encap{emph}, try replacing \encap{emph} with \encap{hyperbf} and see if that resolves the conflict. -Note that if the conflict includes a range formation, the -range takes precedence. +Note that if the conflict includes a \idx{range} formation, the +\idx{range} takes precedence. The mapping tests are applied as the records are read. For example, suppose the records are listed in the \ext{aux} file as: @@ -3824,11 +3834,12 @@ switch with a comma-separated list of formats that should be retained. Note that exact duplicates will still be merged. This switch has a cumulative effect. -Take care if you use this switch and you have an explicit range with +Take care if you use this switch and you have an \idx{explicit-range} with coincident start and end locations. If the \glsdisp{principallocation}{principal record} is between -the start and end format markers then the range can't collapse -to an ordinary \gls{record}. +the start and end format markers then the \idx{range} can't collapse +to an ordinary \gls{record}. (You may need to use +\csopt[true]{merge-ranges}.) \argsection{no-retain-formats} @@ -8648,10 +8659,11 @@ The default setting is \csopt[no value]{missing-parent-category}. \optsection{group-level} -If letter group formation is enabled (see \csopt{group}, +If letter \idx{group} formation is enabled (see \csopt{group}, \csopt{group-formation} and \longarg{group}) then the default behaviour is to only assign the group label for \glspl{top-levelentry}. -This option allows the group label to be assigned to \glspl{sub-entry}. +This option allows the group label to be assigned to \glspl{sub-entry} +if \idxpl{sub-group} are required. The value may be one of the following: \begin{itemize} \item \meta{n}: only assign the group for level~\meta{n} entries; @@ -8671,10 +8683,10 @@ hierarchical levels start at 0 (\gls{top-levelentry}). For any value other than \csopt[0]{group-level}, the parent entry label will be included in the group label. -The hierarchical group titles are formatted according to +The \idx{hiergroup} titles are formatted according to \gls{bibglshiersubgrouptitle}. If the group title would usually be set with the command \csfmt{bibglsset\ldots group} -for \glspl{top-levelentry} then the hierarchical group title would +for \glspl{top-levelentry} then the \idx{hiergroup} title would be set with the analogous \csfmt{bibglsset\ldots group} command. For example, letter groups are normally set with \gls{bibglssetlettergrouptitle} but hierarchical letter groups are set @@ -8684,21 +8696,30 @@ If the \longarg{no-group} setting is on then this option has no effect. \begin{important} Any value other than the default \csopt[0]{group-level} requires -\sty{glossaries-extra} v1.49+. +\sty{glossaries-extra} v1.49+, which provides \cs{glssubgroupheading}. \end{important} +\Idxpl{sub-group} are implemented by the glossary style command: +\nosecformatdef{glssubgroupheading} +The \sty{glossaries-extra} package automatically implements: +\begin{codeenv} +\cmd{renewcommand}*\marg{\cs{glssubgroupheading}}[4]\marg{\cs{glsgroupheading}\marg{\idx{param}4}} +\end{codeenv} +whenever a style is set, so that if the style doesn't provide a +definition for this command, it will behave like \cs{glsgroupheading}. + \optsection{merge-small-groups} -Merges consecutive groups that have less than \meta{n} entries. The +Merges consecutive \idxpl{smallgroup} that have less than \meta{n} entries. The default is \csopt[0]{merge-small-groups}, which switches off this action. If \meta{n} is omitted, \csopt[1]{merge-small-groups} is assumed. This setting only has an effect if group formation is enabled. -If hierarchical sub-groups are enabled (\csopt{group-level}) then +If hierarchical \idxpl{sub-group} are enabled (\csopt{group-level}) then merging is only performed on consecutive small groups within the same hierarchical level. Any \glspl{childentry} that aren't in their -own sub-group are included in the higher level group count. +own \idx{sub-group} are included in the higher level group count. For example, suppose you have a large number of entries in most of the letter groups: @@ -12338,7 +12359,7 @@ the locations, use \csopt[see]{save-locations} (or similar). The \field{loclist} field has the syntax of an \isty{etoolbox} internal list and includes every \gls{location} (except for the \glsdisp{discardedrecord}{discarded duplicates} and -\iglspl{ignoredrecord}) with no range formations. Any explicit range +\iglspl{ignoredrecord}) with no \idx{range} formations. Any \idx{explicit-range} markup is stripped from the \glsopt{format} information to leave just the \idx{encap} name, so you just get the start and end \glspl{location} added as individual elements but they are still @@ -12396,34 +12417,54 @@ The \csfmt{hyper}\meta{xx} set of commands all internally use \gls{location}. See Table~6.1 in the \styfmt{glossaries}~\cite{glossaries} user manual for a list of all the \csfmt{hyper}\meta{xx} commands. -Ranges can be explicitly formed using the parenthetical +\Idxpl{range} can be explicitly formed using the parenthetical syntax \glsopt[\idx{openrange}]{format} and \glsopt[\idx{openrange}]{format} or \glsopt[\idx{openrange}\meta{csname}]{format} and \glsopt[\idx{closerange}\meta{csname}]{format} (where \meta{csname} is again the name of a text-block command without the initial backslash) in the optional -argument of commands like \ics{gls} or \ics{glsadd}. These will always -form a range, regardless of \csopt{min-loc-range}, and will be -encapsulated by \gls!{bibglsrange}. (This command is not used with -ranges that are formed by collating consecutive \glspl{location}.) The -initial marker is stripped from the \meta{format} argument of the -\gls{location} formatting commands, such as \gls{glsnoidxdisplayloc}, to -allow for easy conversion to the corresponding text-block command. - -Explicit ranges don't merge with neighbouring \glspl{location}, but -will absorb any single \glspl{location} within the range that don't -conflict. (Conflicts will be moved to the start of the explicit -range.) For example, if \code{\cs{gls}\marg{sample}} is used on -page~1, +argument of commands like \ics{gls} or \ics{glsadd}. With +\sty{glossaries-extra} v1.50+, you can also use \ics{glsstartrange} +and \ics{glsendrange} (which is useful if the unbalanced parentheses +upset syntax highlighting). + +These \idxpl{explicit-range} will always form a \idx{range}, +regardless of \csopt{min-loc-range}, unless the start and end +coincide and \longarg{collapse-same-location-range} is in effect. +The \idx{explicit-range} will be encapsulated with \gls!{bibglsrange} +(unless \csopt[true]{merge-ranges}). (This command is not used with +\idxpl{implicit-range} that are formed by collating consecutive \glspl{location}.) +The initial marker is stripped from the \meta{format} argument of +the \gls{location} formatting commands, such as +\gls{glsnoidxdisplayloc}, to allow for easy conversion to the +corresponding text-block command. + +\Idxpl{explicit-range} don't merge with neighbouring +\glspl{location} (unless \csopt[true]{merge-ranges}), but will +absorb any individual \glspl{location} within the \idx{range} that doesn't +conflict. (Conflicts, denoted \idxpl{interloper}, will be moved to the start of the +\idx{explicit-range}, regardless of \csopt{merge-ranges}.) +For example, if \code{\cs{gls}\marg{sample}} is used on page~1, \code{\cs{gls}\oarg{\glsopt[\idx{openrange}]{format}}\marg{sample}} is used on page~2, \code{\cs{gls}\marg{sample}} is used on page~3, and \code{\cs{gls}\oarg{\glsopt[\idx{closerange}]{format}}\marg{sample}} is used on page~4, then the \gls{locationlist} will be 1, 2--4. The -entry on page~3 is absorbed into the explicit range, but the range -can't be expanded to include page~1. If the entry on page~3 had a -different format to the explicit range, for example +entry on page~3 is absorbed into the \idx{explicit-range}, but, with +the default \csopt[false]{merge-ranges}, the +\idx{range} can't be expanded to include page~1. If the entry on page~3 had a +different format to the \idx{explicit-range}, for example \code{\cs{gls}\oarg{\glsopt[\encap{textbf}]{format}}\marg{sample}} -then it would cause a warning and be moved before the start of the -range so that the \gls{locationlist} would then be 1, \textbf{3}, 2--4. +then this will cause a warning and the \idx{interloper} will be +moved before the start of the \idx{range} so that the +\gls{locationlist} would then be 1, \textbf{3}, 2--4. + +The \csopt[true]{merge-ranges} option will make \idxpl{explicit-range} +behave like \idxpl{implicit-range}, which allows them to merge with +neighbouring \idxpl{range}. The \gls{bibglsrange} command won't be used in +this case (regardless of whether or not the \idx{range} was merged with +neighbouring \glspl{location}). Options such as +\csopt{min-loc-range} won't have an effect on the merged \idx{range}, but +will still effect \idxpl{implicit-range} that haven't been merged with an +\idx{explicit-range}. An \igls{ignoredrecord} identifies a term that needs to be treated as though it has a \gls{record} for selection purposes, but the @@ -12464,14 +12505,14 @@ If you also want to drop front matter \glspl{location} as well: \cs{GlsXtrSetDefaultNumberFormat}\marg{\encap{glsignore}} \end{codeenv} -Note that explicit range formations aren't discarded, so if -\encap{glsignore} is used in a range, such as: +Note that \idx{explicit-range} formations aren't discarded, so if +\encap{glsignore} is used in a \idx{range}, such as: \begin{codeenv} \ics{glsadd}\oarg{\glsopt[\idx{openrange}\encap{glsignore}]{format}}\marg{sample} \ldots \cs{glsadd}\oarg{\glsopt[\idx{closerange}\encap{glsignore}]{format}}\marg{sample} \end{codeenv} -then the range will be included in the \gls{locationlist} (encapsulated +then the \idx{range} will be included in the \gls{locationlist} (encapsulated with \ics{glsignore}), but this case would be a rather odd use of this special format and is not recommended. @@ -12531,8 +12572,8 @@ then the \ext{aux} file will contain: This is a partial \gls{record} match. In this case, \bibgls\ makes the following tests: \begin{itemize} -\item If one of the formats includes a range formation, the -range takes precedence. +\item If one of the formats includes an \idx{explicit-range} formation marker, the +\idx{range} takes precedence. \item If one of the formats is \encap{glsnumberformat} (as in the above example) or an \igls{ignoredrecord} format such as @@ -12661,7 +12702,8 @@ usual \igls{locationlist}; \igls{locationlist}. You may want to consider using the \longswitch{retain-formats} switch with this setting if you don't want to lose a partial \gls{location} match (for example, if the -\gls{principallocation} coincides with the start of an explicit range). +\gls{principallocation} coincides with the start of an +\idx{explicit-range}). \end{itemize} @@ -12812,7 +12854,7 @@ the \field{location} field due to the \csopt[remove]{save-principal-locations} setting. This can lead to a ragged \gls{locationlist}. The option \csopt[default format]{save-principal-locations} can allow the -\gls{principallocation} to be absorbed into a range. +\gls{principallocation} to be absorbed into a \idx{range}. The \gls{mainglossary} records are added through the category-independent post-name hook with \cs{glsadd}. This won't be implemented until the entries are actually @@ -12935,7 +12977,7 @@ define the custom commands as follows: This is more useful if you want to simply omit the \code{\glsopt[primaryfmt]{format}} option (just remove it from the above four definitions), which makes it easier to merge the \glspl{location} into -ranges in the index. +\idxpl{range} in the index. \optsection{primary-loc-counters} @@ -13073,18 +13115,39 @@ first, followed by the \counter{chapter} group. Whereas with: then the \field{primarylocations} field will have the \counter{chapter} group first, followed by the \counter{page} group. +\optsection{merge-ranges} + +This boolean option determines whether or not \idxpl{explicit-range} should +merge with neighbouring \glspl{location} on either side of the +\idx{range}. The default setting is \csopt[false]{merge-ranges}. + +Note that \gls{bibglsrange} won't be used with +\csopt[true]{merge-ranges}, regardless of whether or not the \idx{range} +was merged with neighbouring \glspl{location}. Options such as +\csopt{min-loc-range}, \csopt{suffixF} and \csopt{suffixFF} +won't have an effect on the merged range, but +will still effect \idxpl{implicit-range} that haven't been merged with an +\idx{explicit-range}. + +Regardless of the value of this option, \idxpl{interloper} will still be +moved to the start of the \idx{range} and encapsulated with +\gls{bibglsinterloper}. + \optsection{min-loc-range} By default, three or more consecutive \glspl{location} \meta{loc-1}, \meta{loc-2}, \ldots, \meta{loc-n} are compressed into -the range \code{\meta{loc-1}\ics{delimR} \meta{loc-n}}. Otherwise +the \idx{range} \code{\meta{loc-1}\ics{delimR} \meta{loc-n}} +(an \idx{implicit-range}). Otherwise the \glspl{location} are separated by \gls!{bibglsdelimN} or \gls!{bibglslastDelimN}. -As mentioned above, these aren't merged with explicit range formations. +As mentioned above, these aren't merged with \idx{explicit-range} +formations unless \csopt[true]{merge-ranges}. -You can change this with the \csopt{min-loc-range} setting where +You can change how many consecutive \glspl{location} are need to +form an \idx{implicit-range} with the \csopt{min-loc-range} setting where \meta{value} is either \optfmt{none} (don't form ranges) or an integer greater than one indicating how many consecutive -\glspl{location} should be converted into a range. +\glspl{location} should be converted into a \idx{range}. \bibgls\ determines if one \gls{location} \code{\margm{prefix-2}\margm{counter-2}\margm{format-2}\margm{location-2}} @@ -13278,7 +13341,8 @@ For example, if \meta{location-1} is \qt{B} and \meta{location-2} is \qt{C}, then $n_1 = 66$ and $n_2 = 67$. Since $n_2 = 67 = 66+1= n_1+1$ then \meta{location-2} immediately follows \meta{location-1}. -This is used in the range formations within the \glspl{locationlist} (as described +This is used in the \idx{implicit-range} formations within +the \glspl{locationlist} (as described in the above section). So, for example, the list \qt{1, 2, 3, 5, 7, 8, 10, 11, 12, 58, 59, 61} becomes @@ -13288,9 +13352,9 @@ The automatically indexing of commands like \ics{gls} means that the \glspl{locationlist} can become long and ragged. You could deal with this by switching off the automatic indexing and only explicitly index pertinent use or you can adjust -the value of \optfmt{max-loc-diff} so that a range can be formed even +the value of \optfmt{max-loc-diff} so that a \idx{range} can be formed even if there are one or two gaps in it. -By default, any \gls{location} ranges that have skipped gaps in this +By default, any \idxpl{range} that have skipped gaps in this manner will be followed by \gls!{bibglspassim}. The default definition of this command is obtained from the resource file. For English, this is \verb*| passim| (space followed by \qt{passim}). @@ -13302,9 +13366,11 @@ term. \optsection{suffixF} -If set, a range consisting of two consecutive \glspl{location} -\meta{loc-1} and \meta{loc-2} will be -displayed in the \gls{locationlist} as \meta{loc-1}\meta{value}. +If set, an \idx{implicit-range} consisting of two consecutive +\glspl{location} \meta{loc-1} and \meta{loc-2} will be displayed in +the \gls{locationlist} as \meta{loc-1}\meta{value}. This option +doesn't affect \idxpl{explicit-range}, even with +\csopt[true]{merge-ranges}. Note that \csopt[\empty]{suffixF} sets the suffix to the empty string. To remove the suffix formation use @@ -13314,9 +13380,11 @@ The default is \csopt[none]{suffixF}. \optsection{suffixFF} -If set, a range consisting of three or more consecutive \glspl{location} -\meta{loc-1} and \meta{loc-2} will be +If set, an \idx{implicit-range} consisting of three or more +consecutive \glspl{location} \meta{loc-1} and \meta{loc-2} will be displayed in the \gls{locationlist} as \meta{loc-1}\meta{value}. +This option doesn't affect \idxpl{explicit-range}, even with +\csopt[true]{merge-ranges}. Note that \csopt[\empty]{suffixFF} sets the suffix to the empty string. To remove the suffix formation use @@ -13331,9 +13399,9 @@ The \meta{value} may be an integer \meta{n} or \optfmt{false} (equivalent to \csopt[3]{compact-ranges}). If no \meta{value} is specified, \optfmt{true} is assumed. -This setting allows \gls{location} ranges such as 184--189 to appear +This setting allows location \idxpl{range} such as 184--189 to appear more compactly as 184--9. The end \gls{location} is encapsulated -in the command \gls{bibglscompact}, so the range would actually +in the command \gls{bibglscompact}, so the \idx{range} would actually become: \begin{codeenv} 184\ics{delimR}\gls{bibglscompact}\marg{digit}\marg{18}\marg{9} @@ -13341,7 +13409,7 @@ become: If the \gls{location} is in the form \code{\meta{cs}\margm{loc}} (where \meta{cs} is a command) then \gls{bibglscompact} will be inside the argument. -For example, if the range would normally be: +For example, if the \idx{range} would normally be: \begin{codeenv} \cmd{custom}\marg{184}\ics{delimR}\cmd{custom}\marg{189} \end{codeenv} @@ -13630,9 +13698,9 @@ consider the following document: \cmd{end}\marg{document} \end{codeenv} This results in the \gls{locationlist} \qt{1, 1--3, 3--5}. This -looks a little odd and it may seem as though the range formation +looks a little odd and it may seem as though the \idx{implicit-range} formation hasn't worked, but the \glspl{location} are actually: page~1, equation~1, -equation~2, equation~3, page~3, page~4 and page~5. Ranges can't +equation~2, equation~3, page~3, page~4 and page~5. \Idxpl{range} can't be formed across different counters. The \csopt[\meta{list}]{loc-counters} option instructs \bibgls\ @@ -13727,7 +13795,7 @@ the place where the corresponding \cs{label} occurred. This method works partially with \idx!{makeindex} and \idx!{xindy} but from their point of view the \gls{location} is the value of the \counter{wrglossary} counter, which interferes with their ability to -merge duplicate page numbers and form ranges. Since \bibgls\ is +merge duplicate page numbers and form \idxpl{range}. Since \bibgls\ is designed specifically to work with \sty{glossaries-extra}, it's aware of this special counter and will merge and collate the \glspl{location} according to the corresponding page number instead. @@ -16962,9 +17030,9 @@ will be adjusted to locally change the field to in the \gls{secondaryglossary} will be the same as for the \gls{primaryglossary}. -(If the glossary \meta{type} doesn't exist, it will be +If the glossary \meta{type} doesn't exist, it will be defined with \ics{provideignoredglossary*}\margm{type} -even if \longarg{no-provide-glossaries} is set.) +even if \longarg{no-provide-glossaries} is set. Note that if the glossary already exists and contains entries, the existing entries aren't re-ordered. The new entries are simply appended to the list. @@ -19006,6 +19074,8 @@ This defaults to \code{,\idx{nbspchar}} to discourage lonely \glspl{location}. \cssection{bibglscompact} \formatdef{bibglscompact} +This command is used with \csopt{compact-ranges} when the end +\gls{location} in a \idx{range} is compacted. The first argument \meta{pattern} indicates the \gls{location} pattern: \code{digit} for digits, \code{roman} for \idx!{lowercase} Roman numerals, \code{ROMAN} for \idx!{uppercase} Roman @@ -19019,9 +19089,9 @@ This just does \meta{part2} by default. \cssection{bibglspassim} \formatdef{bibglspassim} -If \csopt{max-loc-diff} is greater than~1, then any ranges that have -skipped over gaps will be followed by \gls{bibglspassim}, which is -defined as: +If \csopt{max-loc-diff} is greater than~1, then any +\idxpl{implicit-range} that have skipped over gaps will be followed +by \gls{bibglspassim}, which is defined as: \begin{codeenv} \cs{providecommand}\marg{\gls{bibglspassim}}\marg{ \gls{bibglspassimname}} \end{codeenv} @@ -19048,25 +19118,26 @@ The default definition is obtained from the \langxml. For example, with \cssection{bibglsrange} \formatdef{bibglsrange} -Explicit ranges formed using \glsopt[\idx{openrange}]{format} and +\Idxpl{explicit-range} formed using \glsopt[\idx{openrange}]{format} and \glsopt[\idx{closerange}]{format} or \glsopt[\idx{openrange}\meta{csname}]{format} and \glsopt[\idx{closerange}\meta{csname}]{format} (where \meta{csname} matches and is a text-block command without the initial backslash) in the optional argument of commands like \ics{gls} or \ics{glsadd} are encapsulated within -the argument of \gls{bibglsrange}. By default this simply does its -argument. This command is not used with ranges that are formed by collating -consecutive \glspl{location}. +the argument of \gls{bibglsrange}. By default, this simply does its +argument. This command is not used with \idxpl{implicit-range} that +are formed by collating consecutive \glspl{location} or when +\csopt[true]{merge-ranges} is used. \cssection{bibglsinterloper} \formatdef{bibglsinterloper} -If an explicit range conflicts with a record, a warning will be -issued and the conflicting record will be shifted to the front -of the range inside the argument of \gls{bibglsinterloper}. +If an \idxpl{explicit-range} conflicts with a record, a warning will be +issued and the conflicting record (the \idx{interloper}) will be shifted to the front +of the \idx{range} inside the argument of \gls{bibglsinterloper}. The default definition just does \meta{location}\gls!{bibglsdelimN} so that it fits neatly into the list. -For example, suppose on page~4 of my document I start a range with: +For example, suppose on page~4 of my document I start a \idx{range} with: \begin{codeenv*} \cs{glsadd}\oarg{\glsaddopt[\idx{openrange}]{format}}\marg{sample} \end{codeenv*} @@ -19074,21 +19145,22 @@ and end it on page~9 with: \begin{codeenv*} \cs{glsadd}\oarg{\glsaddopt[\idx{closerange}]{format}}\marg{sample} \end{codeenv*} -This forms an explicit range, but let's suppose on page~6 I +This forms an \idx{explicit-range}, but let's suppose on page~6 I have: \begin{codeenv} \cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{sample} \end{codeenv} -This record conflicts with the explicit range (which doesn't include +This record conflicts with the \idx{explicit-range} (which doesn't include \encap{hyperbf} in the format). This causes a warning and the conflicting entry will be moved before the start of the -explicit range resulting in \textbf{6}, 4--9. +\idx{explicit-range} resulting in \textbf{6}, 4--9. -Note that implicit ranges can't be formed from interlopers (nor can -implicit ranges be merged with explicit ones), +Note that \idxpl{implicit-range} can't be formed from \idxpl{interloper} (nor can +\idxpl{implicit-range} be merged with explicit ones with the default +\csopt[false]{merge-ranges}), so if \code{\cs{gls}\oarg{\glsopt[\encap{hyperbf}]{format}}\marg{sample}} also occurs on pages~7 and~8 then the result will be \textbf{6}, \textbf{7}, -\textbf{8}, 4--9. Either remove the explicit range or +\textbf{8}, 4--9. Either remove the \idx{explicit-range} or remove the conflicting entries. (Alternatively, redefine \gls{bibglsinterloper} to ignore its argument, which will discard the conflicting entries.) @@ -20708,12 +20780,16 @@ This command is only provided if \longarg{replace-quotes} is used. \formatdef{bibglsuppercase} Converts \meta{text} to \idx{uppercase}. This just uses -\ics{MakeTextUppercase} by default. +\ics{glsuppercase} (if \sty{glossaries} v4.50+, +\sty{glossaries-extra} v1.49+ and \sty{mfirstuc} v2.08+) +or \ics{MakeTextUppercase} by default. \cssection{bibglslowercase} \formatdef{bibglslowercase} Converts \meta{text} to \idx{lowercase}. This just uses +\ics{glslowercase} (if \sty{glossaries} v4.50+, +\sty{glossaries-extra} v1.49+ and \sty{mfirstuc} v2.08+) \ics{MakeTextLowercase} by default. \cssection{bibglstitlecase} @@ -24532,14 +24608,14 @@ The tagging format is governed by \ics{glsxtrtagfont} which underlines its argument by default. I've redefined it to also convert the letter to \idx{uppercase}: \begin{codeenv} -\cs{renewcommand}*\marg{\cs{glsxtrtagfont}}[1]\marg{\ics{underline}\marg{\cs{MakeTextUppercase}\marg{\idx{param}1}}} +\cs{renewcommand}*\marg{\cs{glsxtrtagfont}}[1]\marg{\ics{underline}\marg{\cs{glsuppercase}\marg{\idx{param}1}}} \end{codeenv} Note that in the \code{mathml} case, the first tag consists of more than one letter: \begin{codeenv} \field{long}=\marg{\cmd{abbrvtag}\marg{m\cs{NoCaseChange}\marg{ath}}ematical }\idx{stringconcat}markuplang \end{codeenv} -Here \ics{NoCaseChange} prevents \ics{MakeTextUppercase} +Here \ics{NoCaseChange} prevents \ics{glsuppercase} from applying the case change. The default \csopt{selection} criteria includes entries that have |