diff options
Diffstat (limited to 'macros/latex-dev/base/lthooks.dtx')
-rw-r--r-- | macros/latex-dev/base/lthooks.dtx | 55 |
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 |