[latex3-commits] [git/LaTeX3-latex3-latex2e] ProvideHook: slight rewording and some more docu (afbc9da8)

[Frank Mittelbach]

Repository : https://github.com/latex3/latex2e
On branch  : ProvideHook
Link       : https://github.com/latex3/latex2e/commit/afbc9da869bcf81f7a2ed094222c2be5144d6dd0

>---------------------------------------------------------------

commit afbc9da869bcf81f7a2ed094222c2be5144d6dd0
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Fri Apr 30 16:05:52 2021 +0200

    slight rewording and some more docu


>---------------------------------------------------------------

afbc9da869bcf81f7a2ed094222c2be5144d6dd0
 base/ltcmdhooks.dtx                       | 29 ++++++++++++++++-------------
 base/testfiles-lthooks/ltcmdhooks-009.lvt |  9 +++++++++
 base/testfiles-lthooks/ltcmdhooks-009.tlg |  2 ++
 3 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/base/ltcmdhooks.dtx b/base/ltcmdhooks.dtx
index aee180d2..cc67f5ea 100644
--- a/base/ltcmdhooks.dtx
+++ b/base/ltcmdhooks.dtx
@@ -165,19 +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 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 commands defined or redefined after   
-% |\begin{document}| only use generic |cmd| hook code if
-% \cs{AddToHook} is called the first time after their definition, or if
-% they explicitly use the generic hook code in their definition
-% by calling \cs{UseHook} as part of their code.
+% 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}
diff --git a/base/testfiles-lthooks/ltcmdhooks-009.lvt b/base/testfiles-lthooks/ltcmdhooks-009.lvt
index 118e9ed6..1c595c62 100644
--- a/base/testfiles-lthooks/ltcmdhooks-009.lvt
+++ b/base/testfiles-lthooks/ltcmdhooks-009.lvt
@@ -11,9 +11,18 @@
 
 \AddToHook{cmd/notdefined/after}{Error}
 
+\AddToHook{cmd/notyetdefined/after}[X]{\typeout{how about this?}}
+
 \OMIT \AtBeginDocument{\TIMO}
 \begin{document}
 
 \AddToHook{cmd/alsoundefined/after}{Error}
 
+\newcommand\notyetdefined{\typeout{now defined (but no after cmd hook)}}
+
+\AddToHook{cmd/notyetdefined/before}[Y]{\typeout{This one is ... }}
+\AddToHook{cmd/notyetdefined/after}[Y]{\typeout{and what about that?}}
+
+\notyetdefined  % hook is not patched in!
+
 \END
diff --git a/base/testfiles-lthooks/ltcmdhooks-009.tlg b/base/testfiles-lthooks/ltcmdhooks-009.tlg
index f7bcd8c9..51a3ecf2 100644
--- a/base/testfiles-lthooks/ltcmdhooks-009.tlg
+++ b/base/testfiles-lthooks/ltcmdhooks-009.tlg
@@ -7,3 +7,5 @@ For immediate help type H <return>.
 l. ...\AddToHook{cmd/alsoundefined/after}{Error}
 You tried to add a hook to `\alsoundefined', but LaTeX was not able to add the
 hook to that command because `\alsoundefined' doesn't exist.
+This one is ... 
+now defined (but no after cmd hook)