summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/ltnews34.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex-dev/base/ltnews34.tex')
-rw-r--r--macros/latex-dev/base/ltnews34.tex843
1 files changed, 493 insertions, 350 deletions
diff --git a/macros/latex-dev/base/ltnews34.tex b/macros/latex-dev/base/ltnews34.tex
index 7497b71879..4bd847a19f 100644
--- a/macros/latex-dev/base/ltnews34.tex
+++ b/macros/latex-dev/base/ltnews34.tex
@@ -5,7 +5,7 @@
% in this file.
%
% This file is part of the LaTeX base system.
-% -------------------------------------------
+% -——————————————
%
% It may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
@@ -34,14 +34,12 @@
\documentclass{ltnews}
-%%CCC Temporary definitions:
-\providecommand\Dash {\unskip ---}
-
-
+%% Temporary definition for Chris' inadequate system: CCC
+\providecommand\Dash {\unskip \textemdash}
%% NOTE: Chris' preferred hyphens!
%%\showhyphens{parameters}
-\hyphenation{because parameters parameter}
+%% \hyphenation{because parameters parameter}
\usepackage[T1]{fontenc}
@@ -72,6 +70,8 @@
{github issue#1 #2}%
)}%
\par\smallskip}
+%% But Chris has to mostly disable \href for his TEXPAD app: CCC
+\def\href #1{}
% simple solution right now (just link to the first issue if there are more)
\def\getfirstgithubissue#1 #2\relax{#1}
@@ -117,7 +117,8 @@
\tubcommand{\input{tubltmac}}
\publicationmonth{November}
-\publicationyear{2021 --- Draft Version (with many unfinished blocks)}
+\publicationyear{2021 \Dash Third Draft Version,
+ not quite complete, eg needs Intro?)} %% CCC
\publicationissue{34}
@@ -136,140 +137,107 @@
\section{Introduction}
-\emph{write}
-
-\section{???}
-
-\emph{write}
+\emph{TO BE COMPOSED, PROBABLY}
+%%
+% \subsection{???}
+%
+% \emph{write} ??
+%%
\section{Hook business}
-After the introduction of the hook management system in the 2020
-release of \LaTeX{}~\cite{34:ltnews32} package developers have started
-to make more and more use of the new functionality. This resulted in a
-number of queries showing that some of the documentation was not
-precise enough and that one or the other clarification was
-needed. This has now been addressed in the documentation. The extended
-usage also showed a small number of deficiencies that we thought
-should be corrected now while the adoption rate is still relatively
-small. These are addressed in this release and documented below.
+Since the introduction of the hook management system in the 2020
+release of \LaTeX{}~\cite{34:ltnews32} package
+developers have started
+to make more and more use of this new functionality. One result
+of this increased activity has been a
+number of queries which show that some of the documentation was not
+precise enough and that some clarifications were needed; these
+deficiencies have now been addressed in the documentation.
+%
+The increased usage has also shown up a small number of
+errors that we thought
+should be corrected now, while the adoption rate is still relatively
+small; the following problems have therefore been addressed in this release.
-\subsection{Providing \cs{ActivateGenericHook}}
+\subsection{Provide \cs{ActivateGenericHook}}
The hook management system offers a number of generic hooks, i.e.,
-hooks whose names contain a variable component, for example the name
-of an environment. Predeclaring such hooks as not really feasible
-which is why these hooks use a different mechanism: they are
-implicitly available end spring into life the moment a package or the
-user in the preamble adds code to them using \cs{AddToHook}. The
-kernel offers such hooks for environments \texttt{env/...}, commands
-\texttt{cmd/...}, and files, package or classes, \texttt{file/...},
-\texttt{include/...}, \texttt{package/...}, and \texttt{class/...}.
-
-It is possible to offer generic hooks in packages, e.g., if you have
-hooks that depend on the current language and therefore need the
-language name as part of the hook name and you don't know all possible
-names beforehand.
-
-If you want to offer your generic hooks you do this by using
+hooks whose names contain a variable component such as the name
+of an environment. Predeclaring such hooks is not really feasible,
+so these hooks use a different mechanism: they are
+implicitly available, springing into life the moment a package, or
+the document preamble, adds any code to one by using \cs{AddToHook}.
+%
+The kernel offers such hooks for environments
+ (\texttt{env/...}) and commands (\texttt{cmd/...}), and for files,
+ packages or classes (\texttt{file/...},
+\texttt{include/...}, \texttt{package/...}, \texttt{class/...}).
+
+It is also possible to offer such generic hooks in
+packages if, for example, hooks are needed that depend on the
+current language and therefore need the
+language name as part of the hook name (but you probably
+don't know beforehand all the necessary names).
+
+If you want to offer such generic hooks, you can now
+do this by using
\cs{UseHook} or \cs{UseOneTimeHook} in your (package) code, but
-\emph{without declaring the hook} with \cs{NewHook}. Without any
-further work a call to \cs{UseHook} with an undeclared hook name does
-nothing. So as an additional setup step, it is necessary to explicitly
-activate the generic hook with \cs{ActivateGenericHook}.\footnote{Note
+\emph{without declaring the hook} with \cs{NewHook}. But without
+further work, a call to \cs{UseHook} with an undeclared hook name
+will do
+nothing; so, as an additional setup step, it is necessary to explicitly
+activate the generic hook by using \cs{ActivateGenericHook}.\footnote{Note
that in the previous release we offered \cs{ProvideHook} as a means
to achieve this effect, but the name was badly chosen so we decided
- to deprecate it and now offer \cs{ActivateGenericHook} instead
- because that is what it is meant for.}
+ to deprecate it and now offer \cs{ActivateGenericHook} instead.}
Assuming
-that you don't know all the different hook names up front it will
+that you don't know all the different hook names up front, it will
remain the task of the users of your package to activate the hook
themselves before adding code to it. For example, Babel offers hooks
-such as \texttt{babel/afterextras/\meta{language}} enabling the user
-to add language specific declarations there. They can then write
+such as \hook{babel/\meta{language}/afterextras}
+that enable a user
+to add language specific declarations to these \enquote{extras}. One can then write
\begin{verbatim}
-\ActivateGenericHook
- {babel/afterextras/ngerman}
-\AddToHook{babel/afterextras/ngerman}
+ \ActivateGenericHook
+ {babel/ngerman/afterextras}
+ \AddToHook{babel/ngerman/afterextras}
{\color{blue}}
\end{verbatim}
after which all German words would be colored blue in the text.
Note that a generic hook produced in this way is always a normal hook.
-
-
-
-\subsection{Clear extra hook code for next invocation}
-
-There are a few use cases where it would be helpful if one can cancel
-an earlier use of \cs{AddToHookNext}, for example, when a page is
-discarded with \cs{DiscardShipoutBox} because only some pages of the
-document are printed. For such situations the new command
-\cs{ClearHookNext} is provided.
-%
-\githubissue{565}
-
-
-
-\subsection{Clean up after \cs{UseOneTimeHook}}
-
-Some hooks are meant to be used only once in a document, and any
-further attempt to add code to them causes the code to be executed
-immediately instead of being added to the hook. The initial implementation of
-this concept was very simple and didn't anticipate that packages may try to
-execute a one-time hook several times resulting in the hook code
-being executed repeatedly. Thus, the implementation was fine for
-simple usages (e.g., the \hook{begindocument} hook), but caused
-trouble if the one-time hook was intended, for example, as an
-initialization hook that is used once when a command is first
-called, but then ignored in further calls.
-
-This deficiency has been addressed, and now a one-time hook will only be executed once
-and the hook code is removed after usage to free up the memory.
-%
-\githubissue{565}
-
-
-
-\subsection{Class, package, and include hook improvements}
-
-Classes, packages and include files can only be loaded once in a
-\LaTeX{} document. For that reasons hooks that are specific to such
-files have been made one-time hooks. Beside being more efficient this
-supports the following important use case
-\begin{verbatim}
-\AddToHook{package/varioref/after}
- { ... apply my customizations if the package
- gets loaded (or was loaded already) ... }
-\end{verbatim}
-without the need to first test if the package was already loaded
-before.
-%
-\githubissue{623}
-
-
-\subsection{Standardizing generic hook names}
-
-The initial set of generic hooks provided by the \LaTeXe{} kernel had
-two patterns of hook names: ones like
-\verb|env/|\meta{name}\verb|/after|, with the variable (\meta{name})
-part in the middle position, and ones like
-\verb|file/after/|\meta{name}, with the variable part in the third
-position. The coexistence of these two types caused confusion, because
-the user had to remember in which position was the variable part
-supposed to go, and made the code more complicated and slower.
-
-The file-related hooks have been renamed so that the variable part of
-their is in the middle, as with other hooks. The changes were:
+\subsection{Standardized names for the generic hooks}
+
+The initial set of generic hooks provided by the kernel had
+two patterns of names:\\
+ones like
+\verb|env/|\meta{name}\verb|/after|,
+with the variable (\meta{name})
+part in the middle position;\\
+and ones like
+\verb|file/after/|\meta{name}, with the
+variable part in the third
+position.
+%
+The coexistence of these two types caused confusion because
+the user had to remember in which position the variable part was
+supposed to go; and it also made the code more complicated and slower.
+
+The file-related hooks have therefore been renamed
+so that the variable part of
+the name is in the middle, as with all other hooks.
+The changes are listed here:
+\smallskip
\begin{center}
\small\ttfamily
- \begin{tabular}{l@{\;$\rightarrow$\;}l}
+ \begin{tabular}{l@{$\;\rightarrow\;$}l}
\hline
\multicolumn{1}{l}{Old name} & \rmfamily New name \\
\hline
@@ -285,265 +253,430 @@ their is in the middle, as with other hooks. The changes were:
\hline
\end{tabular}
\end{center}
-
+\smallskip
Since this is a breaking change, the old names will still work for a
-while, so that users and package authors have enough time to adjust, and
-a warning will be issued when the old names are used. Eventually the
-deprecated names will be turned into errors and then removed completely.
+while so that users and package authors have enough time to adjust;
+but a warning will be issued when the old names are used.
+Eventually the deprecated names will be turned into errors and
+then removed completely.
%
\githubissue{648}
+\subsection{Some file hooks made one-time}
+
+Classes, packages and included files can only be loaded once in a
+\LaTeX{} document. For this reason, the hooks that are specific to loading such
+files have been made one-time hooks. Beside being more efficient, this
+supports the following important use case
+\begin{verbatim}
+ \AddToHook{package/varioref/after}
+ {... apply when the package gets loaded,
+ or apply now (if it is already loaded) ...}
+\end{verbatim}
+without the need to first test whether the package is already loaded.
+%
+\githubissue{623}
-\subsection{Changed how \cs{RemoveFromHook} treats code that isn't in the hook}
-In the first version of \cs{RemoveFromHook}, in case the code label
-being removed didn't exist in the hook, a ``removal order'' would be
-queued, and the next time something tried to add that label to the hook,
-the \cs{AddToHook} would be cancelled by the removal order, and no code
-would be added that once. This was so that in principle package loading
-order wouldn't matter. However this implementation didn't work quite as
-intended, because while two \cs{AddToHook} to a given label would be
-removed by a single \cs{RemoveFromHook}, one \cs{RemoveFromHook} could
-not cancel two \cs{AddToHook} to that label, and this asymmetry caused
-confusion and was a recipe for further problems.
+\subsection{Clearing extra hook code for the next invocation}
-The implementation was changed and now \cs{RemoveFromHook} only removes
-labels that already exist in a hook, and will display a warning if they
-don't. For usage across packages, for removing code in a hook, the
-\texttt{voids} relation should be used instead: this relation is
-non-destructive (meaning it can be later reverted with another one), and
-it is truly independent of package loading order, so it should be
-preferred.
+There are a few use cases where it is helpful if one can cancel
+an earlier use of \cs{AddToHookNext}: for example, when a page is
+discarded with \cs{DiscardShipoutBox} because only some pages of the
+document are printed. For such situations the new command
+\cs{ClearHookNext} is now provided.
%
-\githubissue{625}
+\githubissue{565}
+\subsection{Cleaning up after \cs{UseOneTimeHook}}
-\subsection{???}
+Some hooks are meant to be used only once in a document, and any
+further attempt to add code to one of these will
+cause the code to be executed
+immediately instead of being added to the hook.
+%
+The initial implementation of
+this concept was very simple and didn't anticipate that packages may try to
+execute a one-time hook several times, resulting in the hook code
+being executed repeatedly. Thus the implementation was fine for
+simple cases (such as the \hook{begindocument} hook) but it causes
+trouble if the one-time hook was intended, for example, as an
+initialization hook that is used just once (when a command is first
+called) but is then ignored in further calls.
+This deficiency has been addressed, and now a one-time
+hook will only be executed once, with
+its code being removed after use to free up some memory.
%
-\githubissue{000}
+\githubissue{565}
+\subsection{\cs{RemoveFromHook} with a missing code label}
+In the first version of \cs{RemoveFromHook}, when the code label
+to be removed didn't exist in the hook a ``removal order'' would be
+queued; and then, the next time something tried to add that label to the hook,
+this \cs{AddToHook} action would be cancelled by the removal order, so that no code
+would be added that one time. This was so that, in principle, package loading
+order wouldn't matter.
+%
+However, this implementation didn't work as
+intended because, while two \cs{AddToHook} actions with a given label would be
+removed by a single \cs{RemoveFromHook}, one \cs{RemoveFromHook} could
+not cancel two \cs{AddToHook} actions for that label; this caused
+confusion and also led to further problems.
-\section{New or improved commands}
+The implementation has now been changed, so that
+\cs{RemoveFromHook} removes only code
+labels that already exist in a hook: it will display a
+warning if there is no such code label.
+Note that, whereas when working with a single package
+you should use \cs{RemoveFromHook} to remove a code label,
+when working with more than one package, the
+\texttt{voids} relation should preferably be used.
+%
+This is best because this relation is non-destructive
+(meaning that it can be later reverted by using another relation),
+and it is also truly independent of package loading order.
+%
+\githubissue{625}
-\subsection{Added \cs{PackageNote} and \cs{ClassNote}}
+\subsection{Patching commands that contain parameter tokens}
-\LaTeX{} offers \cs{PackageError} to signal errors that stop
-processing, \cs{PackageWarning} that generates a warning message on the
-terminal, but continues with the processing and also \cs{PackageInfo}
-to provide some information that is only written to the \texttt{.log}
-file. What hasn't existed up to now is a way to provide some
-information on the terminal that is identifying itself as coming from
-a specific package but which isn't claiming to be a warning. Thus,
-packages that wanted to write to the terminal used \cs{PackageWarning}
-even though the information wasn't really warning the user. For this
-we now have \cs{PackageNote} and \cs{PackageNoteNoLine}, that identify
-themselves as \enquote{informational}, but still go to the terminal and
-not only to the transcript.
-
-Similar commands exist for classes and there we have added the missing
-\cs{ClassNote} and \cs{ClassNoteNoLine} as well.
+In the last release, \LaTeX's hook mechanism was extended to add
+support for hooking into commands using generic \hook{cmd} hooks
+(see~\cite{34:ltnews33}). That version of the extension had a bug: the
+patching of some commands that contained a parameter token
+(normally \verb|#|) in
+their definition would fail with a low-level \TeX{} error. This has now
+been fixed so that patching now works for those commands as well.
%
-\githubissue{613}
+\githubissue{697}
+
-\subsection{New implementation for \cs{counterwithin}}
+\section{New or improved commands}
+
-New implementation for \cs{counterwithout} and \cs{counterwithin} with
-an additional optional arg so it becomes a drop-in replacement for
-amsmath \cs{numberwithin}.
+\subsection{\cs{PackageNote} and \cs{ClassNote} added}
-\emph{write appropriate description}
+\LaTeX{} offers these three commands:\cs{PackageError} to signal errors that
+stop the processing; \cs{PackageWarning} to generate a warning message on the
+terminal but continue with the processing; and \cs{PackageInfo}
+to provide some information that is only written to the \texttt{.log}
+file but not sent to the terminal.
+%
+What has not existed up to now is a way to provide
+information on the terminal that identifies itself as coming from
+a specific package but which does not claim to be a warning.
+(Packages that wanted to write to the terminal used \cs{PackageWarning}
+even though the information wasn't really a warning.)
+We have therefore now added \cs{PackageNote} (and the closely
+related \cs{PackageNoteNoLine}): these identify
+themselves as \enquote{informational}, but they still go to the terminal and
+not only to the \texttt{.log} file.
+%
+Similar commands exist for classes and so there too we have
+new commands: \cs{ClassNote} and \cs{ClassNoteNoLine}.
+%
+\githubissue{613}
-\subsection{New default for \cs{tracinglostchars}}
+\subsection{New \cs{ShowFloat} command}
-In 2021 the \TeX{} engines got enhanced so that \cs{tracinglostchars}
-is now also supporting the value \texttt{3}, turning missing
-characters into errors and not just warnings. This change made us
-realize that \LaTeX{} should use a better default for this parameter
-(so far the warning was only written to the transcript file).
-Using the now available \texttt{3} would really be the best, but for
-compatibility reasons we only set it to \texttt{2} in the kernel.
-However, we recommend adding \cs{tracinglostchars}\texttt{=3} to the
-preamble of documents, because missing glyphs in the output are an
-error and should therefore be properly looked at.
+The package \pkg{fltrace} offers a (fairly low-level but very
+detailed) way to trace \LaTeX's float mechanism. This can help in
+understanding why a certain float is placed into a certain
+region, or why it shows up unexpectedly on a later page.
+\LaTeX{} stores floats in registers named \cs{bx@A}, \cs{bx@B}, etc.,
+and these names show up in the tracing information.
+To display the contents of a float register, you can now say
+\verb=\ShowFloat{=\textit{identifier}\verb=}= where
+\textit{identifier} is the uppercase letter (or letters) after
+\texttt{bx@} in the register name shown in the tracing.
+If additional
+registers have been allocated (with \cs{extrafloats}), the
+\textit{identifier} can also be a number. The command is generally
+available, whether or not you have loaded \pkg{fltrace}, because
+it is also useful when interpreting the tracing output of the
+\pkg{fewerfloatpages} package.
+\subsection{New argument for \cs{counterwithin/without}}
+The commands \cs{counterwithout} and \cs{counterwithin} each now has
+an additional optional argument, similar to that for the command
+ \cs{numberwithin} from \pkg{amsmath},
+for which these are now the preferred replacements.
+This optional argument
+specifies the format of the counter, such as \cs{roman},
+the default value being \cs{arabic}.
-\subsection{Provide tests for package and class loading}
+\subsection{Tests for package and class loading}
-To test if a package was loaded you can now use \cs{IfPackageLoadedTF}
-\Arg{package} \Arg{true} \Arg{false} and based on the result execute
-different code. It is also possible to check if the package was loaded
+To test whether a package has been loaded you can now use \cs{IfPackageLoadedTF}
+\Arg{package} \Arg{true} \Arg{false} and, based on the result, execute
+different code. It is also possible to check whether the package was loaded
with certain options. This is done with
\cs{IfPackageLoadedWithOptionsTF}. It takes four arguments:
-\Arg{package}\Arg{option-list}\Arg{true}\Arg{false}. It uses the
-\meta{false} code if at least one option in the \meta{option-list} has
-not been used during loading or if the package hasn't been loaded at
-all.
+\Arg{package}\Arg{option-list}\Arg{true}\Arg{false}.
+%
+It uses the \meta{false} code if at least one option in
+the \meta{option-list} was
+not specified when loading the package, or if the package
+has never been.
%
-Both commands can be used anywhere in the document, i.e., they are not
-restricted to the preamble.\footnote{This is now also true for the
+Both commands can be used anywhere in the document, i.e.,
+they are not restricted to the preamble.%
+\footnote{This is now also true for the
corresponding internal commands, e.g., \cs{@ifpackageloaded}, that
had this restriction in the past.}
-For classes similar commands (\texttt{Package} replaced by
+For classes, similar commands (with \texttt{Package} replaced by
\texttt{Class} in the name) are provided.
%
\githubissue{621}
+\subsection{\cs{NewCommandCopy}, \cs{ShowCommand} now in \pkg{ltcmd}}
-
-
-
-
-
-
-\subsection{New \cs{ShowFloat} command}
-
-The package \pkg{fltrace} offers a (fairly low-level but very
-detailed) way to trace \LaTeX's float mechanism. This can help to
-understand why a certain float is placed into a certain region or why
-it shows up unexpectedly on a later page. \LaTeX{} stores floats in
-registers named \cs{bx@A}, \cs{bx@B}, etc., and these names show up in
-the tracing information.
+Since the 2020-10-01 release (see~\cite{34:ltnews32}), \LaTeX{}
+has provided \cs{NewCommandCopy} to copy robust commands,
+and \cs{ShowCommand} to show their definitions on the terminal.
%
-To display their contents you can now say
-\verb=\ShowFloat{=\textit{identifier}\verb=}= where
-\textit{identifier} is the uppercase letter (or letters) after
-\texttt{bx@} in the register name shown in the tracing. If additional
-registers have been allocated with \cs{extrafloats}, the
-\textit{identifier} can also be a number. The command is generally
-available, whether or not you have loaded \pkg{fltrace}, because it is
-also useful when interpreting the tracing output of the
-\pkg{fewerfloatpages} package.
-
-
-\subsection{Add \pkg{ltcmd} support for \cs{NewCommandCopy} and \cs{ShowCommand}}
-
-Since the 2020-10-01 release (see~\cite{34:ltnews32}), \LaTeX{} provides
-\cs{NewCommandCopy} to copy robust commands, and \cs{ShowCommand} to
-show their definition in the terminal. In the same release, the
-\pkg{xparse} package was integrated in the kernel (now called
-\pkg{ltcmd}). However, the extended support for \cs{NewCommandCopy} and
+In that same release, the \pkg{xparse} package was integrated
+into the kernel (as \pkg{ltcmd}).
+%
+However, the extended support for \cs{NewCommandCopy} and
\cs{ShowCommand} was not implemented in \pkg{ltcmd}. The present
-\LaTeX{} release ships with that support implemented, so now commands
-defined with \pkg{xparse}/\pkg{ltcmd} can be copied and their definition
-can be easily shown in the terminal without \cs{csname} gymnastics.
+\LaTeX{} release implements this support, so now commands
+defined with \pkg{xparse}/\pkg{ltcmd} can be copied, and their definitions
+can be easily shown on the terminal without the need for ``\cs{csname} gymnastics''.
%
\githubissue{569}
+\subsection{Undo math alphabet allocations if necessary}
+
+\TeX{}, or more exactly the 8-bit versions of \TeX, such as \pdfTeX{}
+have a hard limit of 16 on the number of different math font groups
+(\cs{fam} or \cs{mathgroup}) that can be used in a single formula. For each symbol font
+declared (by a package or in the preamble) an extra math group is allocated,
+and the same happens for each math alphabet, (such as \cs{mathbf}) that
+gets used anywhere in the document. Up to now, these math
+alphabet allocations were permanent, even if they were
+used only once;
+the result was that in complex documents you
+could easily run out of available math font groups.
+The only remedy for this was to
+define your own math version, which is a complicated and cumbersome process.
+
+This situation has now been improved by the introduction of a new counter
+\texttt{localmathalphabets}: this counter governs how many of
+the math group slots are assigned only locally when a new math
+alphabet (and a new math group) is needed.
+%
+Once the current formula is finished, every such further (local)
+allocation is undone, giving you a fighting chance of being
+able to use different new math alphabets in the next formula.
+
+The default value of \texttt{localmathalphabets} is 2,
+but if you need more local alphabets because of the complexity of your
+document, you can set this to a higher value such as 4 or 5.
+Setting it even higher is possible, but this would seldom
+be useful because many group slots will be taken up by
+symbol fonts and such slots are always permanently allocated,
+whether used or not.
+%
+\githubissue{676}
+
+
+\subsection{Better handling for a misuse of \cs{include}}
+
+The command \cs{include} is by now getting used quite often, but
+erroneously, to input a variety files in the preamble of the document
+(before \verb|\begin{document}|).
+%
+Therefore \LaTeX\ now warns about such bad use of \cs{include}.
+As a recovery action it will nevertheless input the specified file
+if it exists (this is as before). Note, however, that this is now done
+without any adjustments to the \texttt{.aux} file settings and
+without running the \cs{include} file hooks (only the generic
+file hooks from \cs{InputIfFileExists} are run).
+%
+\githubissue{645}
+
+
+\subsection{New default value for \cs{tracinglostchars}}
+
+In 2021 all \TeX{} engines were enhanced so that \cs{tracinglostchars}
+supported the extra value \texttt{3}, that turns missing
+characters into errors and not just warnings.
+%
+This engine change made us
+realize that \LaTeX{} should set a better default value for this parameter
+(previously, the warning was written only to the transcript file).
+Using the now available value of \texttt{3} as the default
+would really be best, but for
+compatibility reasons we have only increased it to \texttt{2} in the kernel.
+%
+However, we recommend setting \cs{tracinglostchars}\texttt{=3},
+in either a package or the
+preamble of your documents: this is because having missing glyphs
+in the output is definitely an error and should therefore be
+flagged as such (to ensure that it gets proper attention).
+Further reasons, related especially to Unicode engines, for making
+this recommended change can be found later in this newsletter
+(in connection with the misuse of text accents in mathmode).
+\section{Code improvements}
-\subsection{???}
-%
-\githubissue{000}
+\subsection{Use OpenType version of Latin Modern Upright Italic font}
+When a Latin Modern font is used with the TU encoding under \XeTeX\ or \LuaTeX\
+and fontshape \texttt{ui} is requested, \LaTeX\ now uses the OpenType
+version of the font instead of substituting the (T1-encoded) Type 1 version.
+\subsection{Additional Extended Latin characters predefined}
+More characters, such as \'k (U+1E131), are now pre-defined and
+do not need a \verb|\DeclareUnicodeCharacter| declaration.
+%
+\githubissue{593}
-\section{Code improvements}
+\subsection{Check \cs{endfoo} in \cs{NewDocumentEnvironment}}
-\subsection{Detect ``\cs{endfoo}'' when using \cs{NewDocumentEnvironment}}
+The \cs{newenvironment} command has always checked that neither \cs{foo} nor
+\cs{endfoo} exists before creating a \texttt{foo} environment.
+In contrast (for historical reasons) the more recently introduced
+command \cs{NewDocumentEnvironment}
+checked only for \cs{foo}.
+%
+The behavior of \cs{NewDocumentEnvironment} now aligns with that
+of \cs{newenvironment}, except that it gives distinct errors
+concerning the existence of \cs{foo} and \cs{endfoo}.
-The \cs{newenvironment} command has always checked that both \cs{foo} and
-\cs{endfoo} do not exist before creating a \texttt{foo} environment. In
-contrast, \cs{NewDocumentEnvironment} has only to date checked for \cs{foo};
-this reflects the fact that historically the code was designed around the
-target of an entirely new format. The behavior of \cs{NewDocumentEnvironment}
-now aligns with \cs{newenvironment}, except that it gives separate errors
-for the existence of \cs{foo} and \cs{endfoo}.
-\subsection{Improve ``\cs{begin} ended by'' error message}
+\subsection{Improve the error
+ message \texttt{\textup{\cs{begin} ended by \textellipsis}}}
-In the past it was possible to get an error message stating something
+In the past it was possible to get an error message something
like \verb=\begin{foo} ended by \end{foo}=. This could happen when the
-environment name was partly hidden inside a macro, because the test was
-comparing the literal strings while the error message expanded the
-strings fully. This has now been changed to show a more sensible error
+environment name was partly hidden inside a macro. It happened because
+the test was comparing the literal strings, whereas in the error message
+these got fully expanded.
+%
+This has now been changed to show a more sensible error
message in this instance.
%
\githubissue{587}
-
-\subsection{Additional Extended Latin characters predefined}
-Some additional characters such as \'k (U+1E131) are now pre-defined and
-will work without needing \verb|\DeclareUnicodeCharacter| declarations.
-%
-\githubissue{593}
-
-
-\subsection{Use OpenType version of Latin Modern Upright Italic}
-When Latin Modern is used with the TU encoding under \XeTeX\ or \LuaTeX\
-and fontshape \texttt{ui} is requested, \LaTeX\ now uses the OpenType
-version instead of substituting the (T1 encoded) Type 1 version.
-
-
\subsection{Pick up all arguments to \cs{contentsline}}
-The \cs{contentsline} commands in the TOC file are always followed by
-four arguments, the last one being empty by default and only used by
-\pkg{hyperref}. The \cs{contentsline} command itself only used the
-first three arguments and relied on the fourth being empty (and thus
-doing no harm). But this assumption is not always correct, e.g., if
-you use \pkg{hyperref} and then remove it from the preamble.
-
-So now we pick up all four arguments and save the last one away, so
-that it can be used by \pkg{hyperref}.
+A \cs{contentsline} command in the TOC file is always followed by
+four arguments, the last one being empty except when using the
+\pkg{hyperref} package. The \cs{contentsline} command itself only used the
+first three arguments and it relied on the fourth being empty (and thus
+doing no harm).
+%
+But this assumption is not always correct: e.g., if
+you at first decide to load \pkg{hyperref} but then later you remove
+this loading from the preamble.
+%
+So now all four arguments ate picked up, with the
+fourth being saved away so that it can be used by \pkg{hyperref}.
%
\githubissue{633}
-\subsection{Fix dropping math lists in \LuaTeX\ callbacks}
+\subsection{Allow dropping a math list in \LuaTeX\ callback}
The \LuaTeX\ callbacks \texttt{pre\_mlist\_to\_hlist\_filter}
-and \texttt{post\_mlist\_to\_hlist\_filter} no longer create an error if
-the callback handler indicates to remove the entire math block.
+and \texttt{post\_mlist\_to\_hlist\_filter} no longer create an error when
+the callback handler indicates removal of the entire math list.
%
\githubissue{644}
+\subsection{Extended label handling in package code}
+Since 2020, as noted in \LaTeX News 32~\cite{34:ltnews32}, \LaTeX\ has
+recorded the name of the counter associated with the current label in
+the internal command \cs{@currentcounter}. This facility (originally
+from the \pkg{zref} package of Heiko Oberdiek) can be used to generate
+prefixes such as \enquote{Figure} before the reference text.
+%
+In the most
+common cases the current label is set by \cs{refstepcounter}, which
+automatically stores the counter name; but some constructs (alignments
+and footnotes) may need to store the current label directly and so for
+these it is useful to update additionally \cs{@currentcounter} so as to
+store this counter name.
+In this release both the footnote command in the kernel and
+also some of the environments in the \pkg{amsmath} package
+have been updated in this way.
+%
+We encourage the maintainers of any class or
+package files that defines \cs{@currentlabel} to also set
+\cs{@currentcounter} at the same point.
+%
+\githubissue{300, 687}
-\subsection{???}
-%
-\githubissue{000}
+\subsection{Better message if text accent used in mathmode}
+Using text accents like \verb|\^| in math does not work
+(and \TeX{} explicitly provides math accents such as \cs{hat}
+for accessing such symbols in mathmode). Therefore LaTeX issued a
+warning when such a wrongly placed accent was encountered
+and this was often followed by a strange, and apparently
+unrelated, low-level error.
+%
+This has now been changed so that the message from this
+error is at least about accents, which we hope is less puzzling.
+Discussion of such warnings or errors reminds us to reinforce
+here a recommendation from earlier in this newsletter, as part
+of the item on the value of \cs{tracinglostchars}.
+%
+Using \TeX\ implementations from 2020 onwards, any warning that
+concerns missing characters can be
+converted to an error by setting \cs{tracinglostchars} to 3; we therefore
+now recommend changing this setting to 3, especially for
+Unicode engines where such missing characters are common (because
+no font supports the full Unicode range).
+%
+\githubissue{643}
\section{Bug fixes}
-\subsection{Replicate argument processors for all embellishments}
+\subsection[Replicate argument processors for all
+ embellishments in command declarations]
+ {Replicate argument processors for all \\
+ \mbox{}\qquad embellishments in command declarations}
-There was a bug in \pkg{ltcmd} (former \pkg{xparse}) that caused
+There was a bug in \pkg{ltcmd} (formerly \pkg{xparse}) that caused
commands to misbehave if they were defined with embellishments and
argument processors. In that case, only one (possibly void) argument
processor would be added to the full set of embellishment arguments,
-resulting in too few processors in some cases, leading to unpredictable
+resulting in too few processors in some cases and thus leading to unpredictable
behavior. This bug has been fixed by applying the same argument
-processors to all the embellishments in a set, so a declaration like:
+processors to all the embellishments in a set, so that a declaration like:
\begin{verbatim}
-\NewDocumentCommand\foo{>{\TrimSpaces}e{_^}}
- {(#1)[#2]}
-\foo^{ a }_{ b }
+ \NewDocumentCommand\foo{>{\TrimSpaces}e{_^}}
+ {(#1)[#2]}
+ \foo^{ a }_{ b }
\end{verbatim}
will now correctly apply \cs{TrimSpaces} to both arguments.
%
@@ -551,143 +684,147 @@ will now correctly apply \cs{TrimSpaces} to both arguments.
-\subsection{Correct case changes for \cs{ij} and \cs{IJ}}
+\subsection{Correct case changing of \cs{ij} and \cs{IJ}}
The ligatures \enquote{\ij} and \enquote{\IJ}, as used in Dutch,
-are only available in most \TeX{} fonts, if the commands \cs{ij} or
-\cs{IJ} are used or when you enter them as UTF-8 characters U+0133 or
+are available (for most \TeX{} fonts) only
+when the commands \cs{ij} or
+\cs{IJ} are used, or when you enter them as the Unicode characters U+0133 or
U+0132.
%
However, when using \texttt{OT1} or \texttt{T1} encoded fonts in
\pdfTeX, the upper or lower casing with \cs{MakeUppercase} and
\cs{MakeLowercase} would always fail regardless of the input method.
This has now been corrected. At the same time we improved the
-hyphenation results for words containing this ligature (when
-typesetting is done in \texttt{OT1} encoding).
+hyphenation results for words containing this ligature (when using the \texttt{OT1} encoding).
%
\githubissue{658}
-\subsection{Improve handling of legacy \cs{bfdefault} changes}
+\subsection{Legacy font series default changes}
In the past, changes to the font series defaults were made by directly
altering \cs{bfdefault} or \cs{mddefault}. Since 2020 there is now
-\cs{DeclareFontSeriesDefault} that allows more granular control,
-i.e., with that declaration you can alter the default for individual meta
-font families, for example, by only altering the bold settings for the
-sans serif family without changing it for \cs{rmfamily} or \cs{ttfamily}.
+\cs{DeclareFontSeriesDefault} that allows more granular control:
+with this declaration you can alter the default for individual meta
+font families by, for example, changing the bold setting only for the
+sans serif family, without changing it for \cs{rmfamily} or \cs{ttfamily}.
See~\cite{34:ltnews31} for more details.
For backwards compatibility, changing \cs{bfdefault} with
-\cs{renewcommand} remained possible. If used, it alters the setting
-for all meta families in one go. This cannot be done when the
-\cs{renewcommand} happens and was therefore delayed until the next
+\cs{renewcommand} remained possible: if used, this alters the setting
+for all meta families in one go. This alteration cannot be done when the
+\cs{renewcommand} happens and it was therefore delayed until the next
time \cs{bfseries} or \cs{mdseries} was executed.
-
+%
However, the problem with that
-approach was that any call to \cs{DeclareFontSeriesDefault} that
-happened in the mean time was overwritten---the two approaches didn't
-work well side by side. This is a problem because older font packages
+approach was that any call to \cs{DeclareFontSeriesDefault} in
+the meantime was overwritten, thus these two approaches didn't
+work well side by side.
+There was a problem because older font packages
use the legacy method while newer ones use
-\cs{DeclareFontSeriesDefault}. This has now been corrected by changing
+\cs{DeclareFontSeriesDefault}.
+
+This has now been resolved by changing
\cs{DeclareFontSeriesDefault} to do any necessary resetting prior to
-setting new defaults.
+setting the new defaults.
%
\githubissue{663}
-\subsection{Use of \# in \cs{textbf} and similar commands}
-Previously you could not use the macro parameter character \# in inline functions
-in the argument of \cs{texbf} and similar text font commands.
+\subsection{Use of \texttt{\textup{\#}} in \cs{textbf} and similar commands}
+Previously you could not use the macro parameter character \texttt{\#}
+in inline functions
+within the argument of \cs{texbf} or similar text font commands.
An internal definition is now guarded with \cs{unexpanded}
-so that \# does not generate an error.
+so that the use of \texttt{\#} here no longer generates an error.
%
\githubissue{665}
-\subsection{???}
-
-%
-\githubissue{000}
-
-
-
-
-
\section{Changes to packages in the \pkg{graphics} category}
-\subsection{Key for alt text}
-A new key \texttt{alt} has been added to \verb|\includegraphics| allowing specification
-of an alternative text for accessibility.
-This is unused by default but may be used by extension packages and possible future use.
+\subsection{\pkg{graphicx}: New key, for alt text}
+A new key, \texttt{alt}, has been added to \cs{includegraphics} to support the addition of descriptive text that is important for accessibility.
+This key is unused by default; it can be deployed by extension packages and it will provide useful support for other future possibilities.
%
\githubissue{651}
-
\section{Changes to packages in the \pkg{tools} category}
-\subsection{\pkg{varioref}: Improve missing label handling}
+\subsection{\pkg{array}: No \cs{mathsurround} around a \env{tabular}}
-If an undefined label is referenced, \pkg{varioref} makes a default
-definition so that later processing finds the right structure (two
-brace groups inside \cs{r@}\meta{label}) However, if \pkg{nameref} or
-\pkg{hyperref} is loaded, the data structure changes to five
-arguments, resulting in low-evel errors in some cases. The code has
-been changed to avoid these errors.
+A \env{tabular} environment is typeset (internally) as an \env{array}
+environment with special settings, and it therefore uses (hidden) math mode.
+Since it is not in fact a math formula,
+no extra space from \cs{mathsuround} should be added
+(the spacing around the \env{tabular} should not get changed).
%
-\sxissue{603948}
-
-
-\subsection{\pkg{array}: Cancel \cs{mathsurround} for \env{tabular}}
-
-A \env{tabular} environment is internally typeset as an \env{array}
-environment with special settings and therefore in math mode. This
-math group should not get any \cs{mathsuround} added as it isn't a
-real formula because otherwise the spacing around the \env{tabular}
-changes. This bug has been there forever (which means not many people
-use \cs{mathsurround} or noticed the difference). Anyhow, this now got
-fixed.
+Note that this bug has been present ``forever'', which shows that \cs{mathsurround}
+is never used, or at least its use is never noticed.
+Anyhow, this bug has now finally gotten fixed.
%
\githubissue{614}
-\subsection{\pkg{longtable}: Improve behavior after a section heading}
-The \env{longtable} environment now sets the \cs{@nobreakfalse} flag so that
-spacing and indentation changes after a section heading are not triggered by
-a paragraph which follows a table which starts a section. Similarly a test for
-\cs{if@noskipsec} added so that a table follows a run-in heading
-rather than appearing before it.
-%
-\githubissue[s]{131 and 173}
-
-\subsection{???}
+\subsection{\pkg{longtable}: Improvements after a section heading}
+The \env{longtable} environment now sets the \cs{@nobreakfalse} flag
+to correct the typesetting when a table immediately follows a heading.
+Previously the spacing and indentation changes that are required
+immediately after a section heading were incorrectly triggered
+within the next paragraph (if any)
+following the table.
%
-\githubissue{000}
+A similar test for
+\cs{if@noskipsec} has been added, so that a table is correctly placed after
+a run-in heading rather than appearing before that heading.
+%
+\githubissue[s]{131 and 173}
-\section{Changes to packages in the \pkg{amsmath} category}
-\subsection{Improve compability with hyperref}
+\subsection{\pkg{multicol}: Better column break control}
-When \pkg{hyperref} is used, incrementing a counter creates anchors and this can affect spacing.
-For a long time \pkg{hyperref} patched the \env{equation} environment to
-avoid some of the side effects. This patch has now been moved directly into \pkg{amsmath}.
-Additionally,
-a \cs{mathopen} has been added to avoid that the anchor affects a following unary symbol.
+From version 1.9 onwards \cs{columnbreak} accepts an optional
+argument (like \cs{pagebreak}) in which you can specify the
+desirability of breaking the column after the current line: supported values are
+\texttt{1} to \texttt{4}, with higher numbers indicating increased desirability.
+This version also adds \cs{newcolumn},
+which forces a break but runs the column short (comparable to
+\cs{newpage} for pages).
%
-\githubissue{652}
+\githubissue{682}
+
-\subsection{???}
+\subsection{\pkg{varioref}: Improved handling of missing labels}
+If an undefined label is referenced, \pkg{varioref} makes a default
+definition so that later processing finds the right structure (two
+brace groups inside \cs{r@}\meta{label}) However, if \pkg{nameref} or
+\pkg{hyperref} is loaded this data structure changes to having five
+arguments; this could cause low-evel errors in some cases.
+The code has therefore now been changed to avoid these errors.
%
-\githubissue{000}
+\sxissue{603948}
+\section{Changes to packages in the \pkg{amsmath} category}
+\subsection{Improved compatibility with \pkg{hyperref}}
+This change in amsmath fixes a spacing problem caused by the
+method used in \pkg{hyperref} to change the \env{equation} environment.
+%
+For simplicity, an explicit, low-level (hence possibly temporary)
+patch has been added to \pkg{amsmath}: this consists
+of an extra, empty (hence invisible)
+\cs{mathopen} atom (with no mathematical meaning) at the start of the
+environment's mathematical content.
+%
+\githubissue{652}
\medskip
@@ -711,8 +848,14 @@ a \cs{mathopen} has been added to avoid that the anchor affects a following unar
\emph{\LaTeXe{} news 32}.\\
\url{https://latex-project.org/news/latex2e-news/ltnews32.pdf}
+\bibitem{34:ltnews33} \LaTeX{} Project Team:
+ \emph{\LaTeXe{} news 33}.\\
+ \url{https://latex-project.org/news/latex2e-news/ltnews33.pdf}
+
\end{thebibliography}
\end{document}
+
+