Merge pull request #556 from latex3/ProvideHook

Provide hook

base/changes.txt

@@ -6,6 +6,17 @@ completeness or accuracy and it contains some references to files that
 are not part of the distribution.
 ================================================================================
 
+2021-04-29  Frank Mittelbach  <[email protected]>
+
+	* lthooks.dtx (subsection{\LaTeXe{} package interface commands}):
+	Add \ProvideHook and related commands.
+
+2021-04-29  Frank Mittelbach  <[email protected]>
+
+	* lthooks.dtx, ltfilehook.dtx:
+	Switch to kernel (not package) errors.
+
+
 2021-04-29  Marcel Krüger  <[email protected]>
 
 	* ltoutenc.dtx (subsection{Definitions for the TU encoding}):

base/latexrelease.dtx

@@ -40,7 +40,7 @@
 %<*latexrelease>
 % \fi
 %         \ProvidesFile{latexrelease.dtx}
-          [2021/04/16 v1.0m LaTeX release emulation and tests
+          [2021/04/29 v1.0n LaTeX release emulation and tests
               (including releases up to \latexreleaseversion)]
 % \iffalse
 %</latexrelease>
@@ -738,6 +738,10 @@ of this package available from CTAN}
   \msg_new:nnnn \msg_gset:nnnn
   \NewDocumentCommand \DeclareDocumentCommand
   \newcommand \@@_declare_command:w
+%    \end{macrocode}
+%    Temp addition \ldots
+%    \begin{macrocode}
+  \__kernel_msg_error:nnn  \use_none:nnn  % needed while redirect for kernel msgs doesn't work
   \q_recursion_tail \q_recursion_tail
   \q_recursion_stop
 %    \end{macrocode}

base/ltcmdhooks.dtx

@@ -14,7 +14,7 @@
 %%% From File: ltcmdhooks.dtx
 %
 \def\ltcmdhooksversion{v1.0a}
-\def\ltcmdhooksdate{2021/04/19}
+\def\ltcmdhooksdate{2021/04/30}
 %
 %
 %
@@ -165,13 +165,22 @@
 % hooks added will be patched in one go.  That means that no command in
 % the preamble will have hooks patched into them.
 %
-% At |\begin{document}| all the delayed patches will be executed, and if
-% the command doesn't exist the code is still added to the hook, but it
-% will not be executed.  After |\begin{document}|, when \cs{AddToHook}
-% is called with a generic |cmd| hook, the command will be immediately
-% patched to include the hook, and if it doesn't exist or if it can't be
-% patched for any reason, an error is thrown.
+% At |\begin{document}| all the delayed patches will be executed, and
+% if the command doesn't exist the code is still added to the hook,
+% but it will not be executed.  After |\begin{document}|, when
+% \cs{AddToHook} is called with a generic |cmd| hook the first time,
+% the command will be immediately patched to include the hook, and if
+% it doesn't exist or if it can't be patched for any reason, an error
+% is thrown; if \cs{AddToHook} was already used in the preamble no new
+% patching is attempted.
 %
+% This has the consequence that a command defined or redefined after
+% |\begin{document}| only uses generic |cmd| hook code if
+% \cs{AddToHook} is called for the first time after the definition is
+% made, or if the command explicitly uses the generic hook in its
+% definition by declaring it with \cs{NewHookPair} adding \cs{UseHook} as
+% part of the code.\footnote{We might change this behavior in the main
+% document slightly after gaining some usage experience.}
 %
 %
 % \subsection{Commands that look ahead}
@@ -196,11 +205,11 @@
 %
 % \section{Package Author Interface}
 %
-% \hook{cmd} hooks are, by default, available for all commands that can
-% be patched to add the hooks.  For some commands, however, the very
-% beginning or the very end of the code is not the best place to put the
-% hooks, for example, if the command looks ahead for arguments
-% (see section~\ref{sec:look-ahead}).
+% The \hook{cmd} hooks are, by default, available for all commands
+% that can be patched to add the hooks.  For some commands, however,
+% the very beginning or the very end of the code is not the best place
+% to put the hooks, for example, if the command looks ahead for
+% arguments (see section~\ref{sec:look-ahead}).
 %
 % If you are a package author and you want to add the hooks to your
 % own commands in the proper position you can define the command and
@@ -220,7 +229,7 @@
 %    \AddToHook{cmd/fancybox/after}{<code>}
 % \end{verbatim}
 % and then use the \cs[no-index]{fancybox} command you will see that it
-% will be completely broken bcause the hook will get executed in the
+% will be completely broken, because the hook will get executed in the
 % middle of parsing for optional \texttt{(...)} argument.
 %
 % If, on the other hand, you want to add hooks to your command you can
@@ -245,9 +254,14 @@
 %
 % Alternatively, if for whatever reason your command does not support
 % the generic hooks provided here, you can disable a hook with
-% \cs{DisableHook}, so that when someone tries to add code to it they
-% will get an error.  Or if you don't want the error, you can simply
-% declare the hook with \cs{NewHook} and never use it.
+% \cs{DisableHook}\footnote{Please use \cs{DisableHook} if at all, only
+% on hooks that you \enquote{own}, i.e., for commands that your
+% package or class defines and not second guess
+% whether or not hooks of other packages should get disabled!}, so
+% that when someone tries to add code to it they will get an error.
+% Or if you don't want the error, you can simply declare the hook with
+% \cs{NewHook} and never use it.
+%
 %
 % The above approach is useful for really complex commands where for
 % one or the other reason the hooks can't be placed at the very

base/ltfilehook.dtx

@@ -31,8 +31,8 @@
 %%% From File: ltfilehook.dtx
 %
 %    \begin{macrocode}
-\providecommand\ltfilehookversion{v1.0i}
-\providecommand\ltfilehookdate{2021/04/20}
+\providecommand\ltfilehookversion{v1.0j}
+\providecommand\ltfilehookdate{2021/04/29}
 %    \end{macrocode}
 %
 %<*driver>
@@ -605,7 +605,7 @@
     \seq_gpop:NNTF \g_@@_input_file_seq \l_@@_internal_tl
       { \exp_after:wN \@@_file_pop_assign:nnnn \l_@@_internal_tl }
       {
-        \msg_error:nnn { hooks } { should-not-happen }
+        \__kernel_msg_error:nnn { hooks } { should-not-happen }
           { Tried~to~pop~from~an~empty~file~name~stack. }
       }
   }