summaryrefslogtreecommitdiff
path: root/support/bib2gls/src/bib2gls-begin.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/bib2gls/src/bib2gls-begin.tex')
-rw-r--r--support/bib2gls/src/bib2gls-begin.tex189
1 files changed, 35 insertions, 154 deletions
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}