[latex3-commits] [git/LaTeX3-latex3-latex2e] lthooks2: docu (4af63feb)

[Frank Mittelbach]

Repository : https://github.com/latex3/latex2e
On branch  : lthooks2
Link       : https://github.com/latex3/latex2e/commit/4af63feb54b5c5f2f4e15870f475142b6734a1fe

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

commit 4af63feb54b5c5f2f4e15870f475142b6734a1fe
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Sat Aug 22 22:58:53 2020 +0200

    docu


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

4af63feb54b5c5f2f4e15870f475142b6734a1fe
 base/lthooks.dtx                       | 44 +++++++++++++++++++++++++++++-----
 base/testfiles-lthooks/lthooks-010.lvt |  9 +++++--
 base/testfiles-lthooks/lthooks-010.tlg | 19 +++++++++++++--
 3 files changed, 62 insertions(+), 10 deletions(-)

diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index eca2c763..c31f3e19 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -316,8 +316,19 @@
 %    used several times before the hook is executed then all code is
 %    executed in the order in which it was declared.\footnotemark
 %
-%    The hook doesn't have to exist for code to be added to it.  This
-%    allows for hooks to work regardless of package loading order.
+%    It is possible to nest declarations using the same hook (or
+%    different hooks), e.g.,
+%   \begin{quote}
+%     \cs{AddToHookNext}\Arg{hook}\verb={=\meta{code-1}^^A
+%     \cs{AddToHookNext}\Arg{hook}\Arg{code-2}\verb=}=
+%   \end{quote}
+%    will execute \meta{code-1} next time the \meta{hook} is used and at
+%    that point puts \meta{code-2} into  the \meta{hook} so that it gets
+%    executed on following time the hook is run.
+%
+%    A hook doesn't have to exist for code to be added to it.  This
+%    allows for hooks to work regardless of package loading
+%    order.
 %    See section~\ref{sec:querying}.
 %
 %    The \meta{hook} can be specified using the dot-syntax to denote
@@ -3120,7 +3131,12 @@
         \iow_term:x{~Extra~ code~ next~ invocation:}
         \iow_term:x{\@spaces
           \tl_if_empty:cTF { g_@@_#1_next_code_tl }
-            {---} {->~ \exp_args:NNc \exp_args:No \@@_log_next_code:n {g_@@_#1_next_code_tl} } }
+             {---}
+%    \end{macrocode}
+%    If the token list is not empty we want to display it but without
+%    the first two tokens (the code to clear itself)
+%    \begin{macrocode}
+             {->~  \@@_log_next_code:v {g_@@_#1_next_code_tl} } }
 %    \end{macrocode}
 %
 %   Loop through the rules in a hook and for every rule found, print it.
@@ -3166,10 +3182,14 @@
   }
 %    \end{macrocode}
 %
+%    To display the code for next invocation only (i.e., from
+%    \cs{AddToHookNext} we have to remove the first two tokens at the
+%    front which are \cs{tl_gclear:N} and the token list to clear.
 %    \begin{macrocode}
 \cs_new:Npn \@@_log_next_code:n #1 {
   \exp_args:No \tl_to_str:n{\use_none:nn #1}    
 }
+\cs_generate_variant:Nn \@@_log_next_code:n { v }
 %    \end{macrocode}
 %  \end{macro}
 %
@@ -3259,10 +3279,22 @@
       { \@@_gput_next_do:nn {#1} {#2} }
       { \@@_try_declaring_generic_next_hook:nn {#1} {#2} }
   }
-\cs_new_protected:Npn \@@_gput_next_do:nn #1 #2
+%    \end{macrocode}
+%    
+%    \begin{macrocode}
+\cs_new_protected:Npn \@@_gput_next_do:nn #1
+  { \exp_args:Nc \@@_gput_next_do_aux:Nn { g_@@_#1_next_code_tl } }
+%    \end{macrocode}
+%
+%    If no \enquote{next} action is requested then the token list holding
+%    the code will be empty, but if some code has been specified we first
+%    add a \cs{tl_gclear:N} so that the token list is emptied after
+%    use.
+%    \begin{macrocode}
+\cs_new_protected:Npn \@@_gput_next_do_aux:Nn #1
   {
-    \tl_gput_right:cn { g_@@_#1_next_code_tl }
-      { #2 \tl_gclear:c { g_@@_#1_next_code_tl } }
+    \tl_if_empty:NT #1 { \tl_gset:Nn #1 { \tl_gclear:N #1 } }
+    \tl_gput_right:Nn #1
   }
 %    \end{macrocode}
 %  \end{macro}
diff --git a/base/testfiles-lthooks/lthooks-010.lvt b/base/testfiles-lthooks/lthooks-010.lvt
index f04e8668..7efac2b3 100644
--- a/base/testfiles-lthooks/lthooks-010.lvt
+++ b/base/testfiles-lthooks/lthooks-010.lvt
@@ -17,7 +17,8 @@
 \AddToHook     {sffamily}[legacy] {Std sffamily code}
 \AddToHook     {sffamily}[foo] {foo code}
 \AddToHook     {sffamily}[bar] {bar code}
-\AddToHookNext {sffamily} {first occasion only $\frac12$}  % should not expand!
+\AddToHookNext {sffamily} {\typeout{first occasion only $\frac12$} % should not expand!
+   \AddToHookNext{sffamily}{\typeout{on second only}}}
 
 \DeclareHookRule {sffamily} {foo} {after} {bar}
 \DeclareHookRule {sffamily} {baz} {voids} {foo}
@@ -32,16 +33,20 @@
 
 \begin{document}
 
-\sffamily
+\sffamily              % first next code
 \ShowHook{sffamily}
 
 \AddToHook     {sffamily}[baz] {baz code}
 \ShowHook{sffamily}
 
+\sffamily
+\ShowHook{sffamily}     % second next code
+
 \ExplSyntaxOn
 \prop_show:c{g__hook_sffamily_code_prop}
 \ExplSyntaxOff
 
+\sffamily
 \ShowHook{sffamily}
 
 \ShowHook{enddocument}
diff --git a/base/testfiles-lthooks/lthooks-010.tlg b/base/testfiles-lthooks/lthooks-010.tlg
index 5ab2af2a..1ccec95c 100644
--- a/base/testfiles-lthooks/lthooks-010.tlg
+++ b/base/testfiles-lthooks/lthooks-010.tlg
@@ -13,7 +13,7 @@ The hook 'sffamily':
     foo -> foo code
     bar -> bar code
  Extra code next invocation:
-    -> first occasion only\tl_gclear:c {g__hook_sffamily_next_code_tl}
+    -> \typeout {first occasion only $\frac 12$} \AddToHookNext {sffamily}{\typeout {on second only}}
  Rules:
     foo|bar with relation >
  Execution order (after applying rules):
@@ -33,13 +33,14 @@ LaTeX Font Info:    Checking defaults for OMX/cmex/m/n on input line ....
 LaTeX Font Info:    ... okay on input line ....
 LaTeX Font Info:    Checking defaults for U/cmr/m/n on input line ....
 LaTeX Font Info:    ... okay on input line ....
+first occasion only $\frac 12$
 The hook 'sffamily':
  Code chunks:
     legacy -> Std sffamily code
     foo -> foo code
     bar -> bar code
  Extra code next invocation:
-    ---
+    -> \typeout {on second only}
  Rules:
     foo|bar with relation >
  Execution order (after applying rules):
@@ -51,6 +52,20 @@ The hook 'sffamily':
     bar -> bar code
     baz -> baz code
  Extra code next invocation:
+    -> \typeout {on second only}
+ Rules:
+    foo|bar with relation >
+    foo|baz with relation <-
+ Execution order (after applying rules):
+    legacy, bar, baz, foo
+on second only
+The hook 'sffamily':
+ Code chunks:
+    legacy -> Std sffamily code
+    foo -> foo code
+    bar -> bar code
+    baz -> baz code
+ Extra code next invocation:
     ---
  Rules:
     foo|bar with relation >