summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/lthooks.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex-dev/base/lthooks.dtx')
-rw-r--r--macros/latex-dev/base/lthooks.dtx55
1 files changed, 44 insertions, 11 deletions
diff --git a/macros/latex-dev/base/lthooks.dtx b/macros/latex-dev/base/lthooks.dtx
index 7e02aa4fd5..aed23ab16d 100644
--- a/macros/latex-dev/base/lthooks.dtx
+++ b/macros/latex-dev/base/lthooks.dtx
@@ -32,7 +32,7 @@
%<*driver>
% \fi
\ProvidesFile{lthooks.dtx}
- [2024/03/09 v1.1h LaTeX Kernel (hooks)]
+ [2024/07/08 v1.1h LaTeX Kernel (hooks)]
% \iffalse
%
\documentclass{l3doc}
@@ -130,6 +130,9 @@
%
% The \meta{hook} can be specified using the dot-syntax to denote
% the current package name. See section~\ref{sec:default-label}.
+% The string \texttt{??} can't be used as a hook name because it
+% has a special significance as a placeholder in hook rules.
+%
% \end{function}
%
% \begin{function}{\NewReversedHook}
@@ -751,8 +754,6 @@
% given \meta{hook}. If \meta{hook} is \texttt{??} this defines a default
% relation for all hooks that use the two labels, i.e., that have
% chunks of code labeled with \meta{label1} and \meta{label2}.
-% Rules specific to a given hook take precedence over default
-% rules that use \texttt{??} as the \meta{hook}.
%
% Currently, the supported relations are the following:
% \begin{itemize}
@@ -793,9 +794,17 @@
%
% \end{itemize}
% There can only be a single relation between two labels for a
-% given hook,
-% i.e., a later \cs{DeclareHookRule} overwrites any previous
-% declaration.
+% given hook, i.e., a later \cs{DeclareHookRule} overwrites any
+% previous declaration. In all cases rules specific to a given
+% hook take precedence over default rules that use \texttt{??} as
+% the \meta{hook}.
+%
+% If a default rule is applied, it is done before reversing the
+% label order in a reversed hook, e.g., \texttt{before} in a
+% default rule effectively becomes \texttt{after} in such a hook.
+% In contrast, a rule for a specific hook is always applied to the
+% state after any reversal (i.e., the state you see when using
+% \cs{ShowHook} on that hook).
%
% The \meta{hook} and \meta{label} can be specified using the
% dot-syntax to denote the current package name.
@@ -826,6 +835,16 @@
% (Technically it is just a shorthand for using \cs{DeclareHookRule}
% with \texttt{??} as the hook name.)
%
+% If such a rule is applied to a reversed
+% hook it behaves as if the rule is reversed (e.g.,
+% \texttt{after} becomes \texttt{before})
+% because those rules are applied first and then the order is reversed.
+% The rationale is that in hook pairs (in which the ordering in one
+% is reversed) default rules have to be reversed too in nearly all
+% scenarios. If this is not the case, a default rule can't be used
+% or has to be overwritten with an explicit \cs{DeclareHookRule}
+% for that specific hook.
+%
% Declaring default rules is only supported in the document
% preamble.\footnotemark{}
%
@@ -1411,7 +1430,7 @@
% This is helpful if you have a pair of hooks where you expect to see
% code added that involves grouping, e.g., starting an environment
% in the first and closing that environment in the second hook.
-% To give a somewhat contrived example\footnote{there are simpler
+% To give a somewhat contrived example\footnote{There are simpler
% ways to achieve the same effect.}, suppose there is a package
% adding the following:
%\begin{verbatim}
@@ -1457,9 +1476,14 @@
% > package-too, package-1.
%\end{verbatim}
%
-% The reversal of the execution order happens before applying any
-% rules, so if you alter the order you will probably have to alter
-% it in both hooks, not just in one, but that depends on the use case.
+% If there is a matching default rule (done with
+% \cs{DeclareDefaultHookRule} or with \texttt{??} for the hook
+% name) then this default rule is applied before the reversal so that the order
+% in the reversed hook mirrors the one in the normal hook. However,
+% all rules specific to a hook happen always after the reversal of the
+% execution order, so if you alter the order you will probably have
+% to alter it in both hooks, not just in one, but that depends on
+% the use case.
%
%
%
@@ -1549,7 +1573,7 @@
% \hook{cmd},
% \hook{env},
% \hook{file},
-% \hook{include}
+% \hook{include},
% \hook{package}, and
% \hook{class},
% and all these are available out of the box: you only have to
@@ -1910,6 +1934,14 @@
% right sequence.
%
% \end{description}
+%
+% Given that these generic hook names involve \texttt{/} as part of
+% their name they would not work if one tries to define an
+% environment using a name that involves a
+% \texttt{/}.\footnote{Officially, \LaTeX{} names for environments
+% should only consist of a sequence of letters, numbers, and the
+% character \texttt{*}, i.e., this is not a new restriction.}
+%
% Generic environment hooks are never one-time hooks even with
% environments that are supposed to appear only once in a
% document.\footnote{Thus if one adds code to such hooks after the
@@ -7601,6 +7633,7 @@
% \begin{macrocode}
\NewDocumentCommand \SetDefaultHookLabel { m }
{ \@@_set_default_hook_label:n {#1} }
+% \end{macrocode}
%
% The label is only automatically updated with \cs{@onefilewithoptions}
% (\cs{usepackage} and \cs{documentclass}), but some packages, like