[latex3-commits] [git/LaTeX3-latex3-latex2e] copyedits-chris: ltnews34: the work goes on (18fdcca4)
Chris Rowley
car222222 at github.github.io
Mon Oct 4 10:44:31 CEST 2021
Repository : https://github.com/latex3/latex2e
On branch : copyedits-chris
Link : https://github.com/latex3/latex2e/commit/18fdcca4bc048751762f50cc0fabea4e4ab1cc87
>---------------------------------------------------------------
commit 18fdcca4bc048751762f50cc0fabea4e4ab1cc87
Author: Chris Rowley <car222222 at users.noreply.github.com>
Date: Mon Oct 4 15:44:31 2021 +0700
ltnews34: the work goes on
>---------------------------------------------------------------
18fdcca4bc048751762f50cc0fabea4e4ab1cc87
base/doc/ltnews34.tex | 160 ++++++++++++++++++++++++--------------------------
1 file changed, 77 insertions(+), 83 deletions(-)
diff --git a/base/doc/ltnews34.tex b/base/doc/ltnews34.tex
index fac21130..d3a26fff 100644
--- a/base/doc/ltnews34.tex
+++ b/base/doc/ltnews34.tex
@@ -161,15 +161,14 @@ usage also showed a small number of deficiencies that we thought
should be corrected now, while the adoption rate is still relatively
small; these have been addressed in this release and are documented here.
-%% NOT YET CHECKED
-\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
+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
+user in the preamble, adds any code to one 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/...}.
@@ -179,22 +178,24 @@ 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
+If you want to offer such generic hooks you 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
+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 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.}
+%% CCC because that is what it is meant for.}
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
+such as \texttt{babel/afterextras/\meta{language}}
+%% CCC OR ???
+that enable the user
to add language specific declarations there. They can then write
\begin{verbatim}
\ActivateGenericHook
@@ -209,33 +210,32 @@ Note that a generic hook produced in this way is always a normal hook.
-\subsection{Clear extra hook code for next invocation}
+\subsection{Clearing extra hook code for the 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
+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.
+\cs{ClearHookNext} is provided..
%
\githubissue{565}
-%% NOT YET CHECKED
-\subsection{Clean up after \cs{UseOneTimeHook}}
+\subsection{Cleaning 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
+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 once when a command is first
+initialization hook that is used just 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.
+This deficiency has been addressed, and now a one-time hook will only be executed once,
+and its code is removed after use to free up the memory.
%
\githubissue{565}
@@ -244,7 +244,7 @@ and the hook code is removed after usage to free up the memory.
\subsection{Class, package, and include hook improvements}
Classes, packages and included files can only be loaded once in a
-\LaTeX{} document. For that reasons hooks that are specific to such
+\LaTeX{} document. For this reason, hooks that are specific to such
file loading have been made one-time hooks. Beside being more efficient, this
supports the following important use case
\begin{verbatim}
@@ -257,7 +257,6 @@ without the need to first test whether the package is already loaded.
\githubissue{623}
-%% NOT YET CHECKED
\subsection{Standardizing generic hook names}
The initial set of generic hooks provided by the \LaTeXe{} kernel had
@@ -266,11 +265,11 @@ two patterns of hook names: ones like
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 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 been renamed so that the variable part of
-their is in the middle, as with other hooks. The changes were:
+The file-related hooks have therefore been renamed so that the variable part of
+the name is in the middle, as with other hooks. The changes are listed here:
\begin{center}
\small\ttfamily
\begin{tabular}{l@{$\;\rightarrow\;$}l}
@@ -291,34 +290,33 @@ their is in the middle, as with other hooks. The changes were:
\end{center}
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
+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}
-%% NOT YET CHECKED
-\subsection{Changed how \cs{RemoveFromHook} treats code that isn't in the hook}
+\subsection{Changed how \cs{RemoveFromHook} treats code that is not 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
+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 quite 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} to that label, and this asymmetry caused
+not cancel two \cs{AddToHook} actions for that label; this asymmetry caused
confusion and was a recipe for further problems.
-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
+The implementation has been changed so that \cs{RemoveFromHook} now removes only code
+labels that already exist in a hook, and will display a warning if there s no such code label.
+When this is used 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.
+non-destructive (meaning it can be later reverted by using another relation), and so
+it is truly independent of package loading order.
+%% CCC so it should be preferred.
%
\githubissue{625}
@@ -388,27 +386,23 @@ error and should therefore be flagged as such (to ensure that it gets proper att
-
-
-%% NOT YET CHECKED
\subsection{Provide 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
+\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.
+not been used during loading, or if the package hasn't been loaded at all.
%
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}
@@ -457,30 +451,32 @@ can be easily shown on the terminal without the need for ``\cs{csname} gymnastic
-
-%% NOT YET CHECKED
\subsection{Undo some math alphabet allocations if necessary}
-\TeX{} or more exactly the 8-bit versions of \TeX, such as \pdfTeX{}
-have a hard limit of 16 in the number of different math font groups
-(\cs{fam}) that can be used in a single formula. For each symbol font
-declared (by a package or in the preamble) one math group is allocated
-and the same happens for each math alphabet, such as \cs{mathbf}, that
-has be used at least once somewhere in the document. Up to now math
+\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
-and then never again with the result that in complex documents you
-could run out of available math font groups. The only remedy then was to
-define your own math version which is complicated and cumbersome.
-
-This has now been changed and a new counter
-\texttt{localmathalphabets} was introduced. It defines how many of the
-remaining slots are assigned only locally if new math alphabets need a
-math group. Once the formula is finished the allocation or
-allocations are then undone, giving you a fighting chance to use
-different math alphabets in the next formula. The default value is 2
+and then never; the result was that in complex documents you
+could easily run out of available math font groups. The only remedy then was to
+define your own math version, which is a complicated and cumbersome process.
+
+This situation has has now been improved by the introduction of a new counter
+\texttt{localmathalphabets}, which governs how many of the math group
+%%CCC remaining
+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 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 it to a higher value, e.g., 4 or 5. Setting it
-even higher is possible, but seldom useful, because many slots will be
+document, you can set this to a higher value, e.g., 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 those are always permanently allocated,
whether used or not.
%
@@ -536,15 +532,17 @@ 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.
-%% NOT YET CHECKED
+
\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
+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 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.
+you use \pkg{hyperref} and then remove
+%%CCC What is "it" here:
+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}.
@@ -555,7 +553,7 @@ that it can be used by \pkg{hyperref}.
\subsection{Fix dropping math lists in \LuaTeX\ callbacks}
The \LuaTeX\ callbacks \texttt{pre\_mlist\_to\_hlist\_filter}
-and \texttt{post\_mlist\_to\_hlist\_filter} no longer create an error if
+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}
@@ -612,7 +610,7 @@ hyphenation results for words containing this ligature (when using the \texttt{O
-\subsection{Improve handling of legacy \cs{bfdefault} changes}
+\subsection{Improve the handling of legacy \cs{bfdefault} 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
@@ -656,10 +654,6 @@ so that \texttt{\#} no longer generates an error.
\githubissue{000}
-
-
-
-
\section{Changes to packages in the \pkg{graphics} category}
More information about the latex3-commits
mailing list.