Skip to content

Commit

Permalink
ltnews34: the work goes on
Browse files Browse the repository at this point in the history
  • Loading branch information
@car222222
car222222 committed Oct 4, 2021
1 parent 62da9fb commit 18fdcca
Showing 1 changed file with 77 additions and 83 deletions.
160 changes: 77 additions & 83 deletions base/doc/ltnews34.tex
View file
Expand Up @@ -161,15 +161,14 @@ \section{Hook business}
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/...}.
Expand All @@ -179,22 +178,24 @@ \subsection{Providing \cs{ActivateGenericHook}}
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
Expand All @@ -209,33 +210,32 @@ \subsection{Providing \cs{ActivateGenericHook}}



\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}

Expand All @@ -244,7 +244,7 @@ \subsection{Clean up after \cs{UseOneTimeHook}}
\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}
Expand All @@ -257,7 +257,6 @@ \subsection{Class, package, and include hook improvements}
\githubissue{623}


%% NOT YET CHECKED
\subsection{Standardizing generic hook names}

The initial set of generic hooks provided by the \LaTeXe{} kernel had
Expand All @@ -266,11 +265,11 @@ \subsection{Standardizing generic hook names}
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}
Expand All @@ -291,34 +290,33 @@ \subsection{Standardizing generic hook names}
\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}

Expand Down Expand Up @@ -388,27 +386,23 @@ \subsection{New default for \cs{tracinglostchars}}





%% 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}
Expand Down Expand Up @@ -457,30 +451,32 @@ \subsection{Add \pkg{ltcmd} support for \cs{NewCommandCopy} and \cs{ShowCommand}




%% 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.
%
Expand Down Expand Up @@ -536,15 +532,17 @@ \subsection{Use OpenType version of Latin Modern Upright Italic}
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}.
Expand All @@ -555,7 +553,7 @@ \subsection{Pick up all arguments to \cs{contentsline}}
\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}
Expand Down Expand Up @@ -612,7 +610,7 @@ \subsection{Correct case changes for \cs{ij} and \cs{IJ}}



\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
Expand Down Expand Up @@ -656,10 +654,6 @@ \subsection{???}
\githubissue{000}






\section{Changes to packages in the \pkg{graphics} category}


Expand Down

0 comments on commit 18fdcca

Please sign in to comment.