[latex3-commits] [git/LaTeX3-latex3-latex2e] gh565-clearhooknext: fix for #565 (8075122d)

Frank Mittelbach frank.mittelbach at latex-project.org
Tue Jul 27 18:44:16 CEST 2021


Repository : https://github.com/latex3/latex2e
On branch  : gh565-clearhooknext
Link       : https://github.com/latex3/latex2e/commit/8075122dd48bd0ffa165fac7abe9c41948861257

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

commit 8075122dd48bd0ffa165fac7abe9c41948861257
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Tue Jul 27 18:44:16 2021 +0200

    fix for #565


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

8075122dd48bd0ffa165fac7abe9c41948861257
 base/changes.txt                                   |  5 ++
 base/doc/ltnews34.tex                              | 15 ++++++
 base/lthooks.dtx                                   | 58 +++++++++++++++++++---
 base/testfiles-lthooks/github-0565.lvt             | 15 ++++++
 .../github-0565.tlg}                               |  4 ++
 base/update-lthooks-tests.sh                       | 27 +++++-----
 6 files changed, 103 insertions(+), 21 deletions(-)

diff --git a/base/changes.txt b/base/changes.txt
index 25b4d541..a24e3e2c 100644
--- a/base/changes.txt
+++ b/base/changes.txt
@@ -6,6 +6,11 @@ completeness or accuracy and it contains some references to files that
 are not part of the distribution.
 ================================================================================
 
+2021-07-27  Frank Mittelbach  <Frank.Mittelbach at latex-project.org>
+
+	* lthooks.dtx (subsubsection{Updating code for hooks}):
+	Commands \ClearHookNext and \hook_gclear_next_code:n added (gh/565)
+
 2021-07-23  Frank Mittelbach  <Frank.Mittelbach at latex-project.org>
 
 	* ltclass.dtx (section{Implementation}):
diff --git a/base/doc/ltnews34.tex b/base/doc/ltnews34.tex
index 2dd95a76..e2b190a4 100644
--- a/base/doc/ltnews34.tex
+++ b/base/doc/ltnews34.tex
@@ -143,6 +143,20 @@
 
 \section{Hook business}
 
+
+
+\subsection{Clear extra hook code for next invocation}
+
+There are a few use cases where it would be helpful if one can cancel
+an earlier use of \cs{AddToHookNext}, for example, when a page is
+discarded with \cs{DiscardShipoutBox} because only some pages of the
+document are printed. For such situations the new command
+\cs{ClearHookNext} is provided.
+%
+\githubissue{565}
+
+
+
 \subsection{Class, package, and include hook improvements}
 
 Classes, packages and include files can only be loaded once in a
@@ -162,6 +176,7 @@ before.
 
 
 
+
 \subsection{???}
 
 %
diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index 2a6a114e..614fe0cd 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -31,8 +31,8 @@
 %%% From File: lthooks.dtx
 %
 %    \begin{macrocode}
-\def\lthooksversion{v1.0n}
-\def\lthooksdate{2021/07/18}
+\def\lthooksversion{v1.0o}
+\def\lthooksdate{2021/07/27}
 %    \end{macrocode}
 %
 %<*driver>
@@ -404,6 +404,25 @@
 % \end{function}\footnotetext{There is
 %    no mechanism to reorder such code chunks (or delete them).}
 %
+%
+%
+% \begin{function}{\ClearHookNext}
+%   \begin{syntax}
+%     \cs{ClearHookNext}\Arg{hook}
+%   \end{syntax}
+%    Normally \cs{AddToHookNext} is only used when you know precisely
+%    where it will apply and why you want some extra code at that
+%    point. However, there are a few use cases in which such a
+%    declaration needs to be canceled again, for example, when
+%    discarding a page with \cs{DiscardShipoutBox} (but even then not
+%    always), and in such situations \cs{ClearHookNext} can be
+%    used.
+% \end{function}
+%
+%
+%
+%
+%
 % \subsubsection{Hook names and default labels}
 % \label{sec:default-label}
 %
@@ -1013,6 +1032,15 @@
 % \end{function}
 %
 %
+% \begin{function}
+%   {\hook_gclear_next_code:n}
+%   \begin{syntax}
+%     \cs{hook_gclear_next_code:n} \Arg{hook}
+%   \end{syntax}
+%   Undo any earlier \cs{hook_gput_next_code:nn}.
+% \end{function}
+%
+%
 %
 %  \begin{function}{\hook_gremove_code:nn}
 %   \begin{syntax}
@@ -2130,7 +2158,7 @@
 %    One problem we have to solve is, that we need to be able to add
 %    code to hooks (e.g., with \cs{AddToHook}) even if that code has
 %    not been declared yet. For example, one package needs to write
-%    into a hook of another package, but that package ay not get
+%    into a hook of another package, but that package may not get
 %    loaded or only loaded later. Another problem most hooks require
 %    declaration but this is not the case for the generic hooks.
 %
@@ -4249,8 +4277,7 @@
 %
 % \begin{macro}{\@@_gput_next_code:nn,
 %               \@@_gput_next_do:nn,
-%               \@@_gput_next_do:Nnn,
-%               \@@_clear_next:n}
+%               \@@_gput_next_do:Nnn}
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_gput_next_code:nn #1 #2
   {
@@ -4287,16 +4314,22 @@
     \tl_if_empty:cT { @@~#2 }
       { \@@_update_hook_code:n {#2} }
     \tl_if_empty:NT #1
-      { \@@_tl_gset:Nn #1 { \@@_clear_next:n {#2} } }
+      { \@@_tl_gset:Nn #1 { \hook_gclear_next_code:n {#2} } }
     \@@_tl_gput_right:Nn #1
   }
-\cs_new_protected:Npn \@@_clear_next:n #1
-  { \cs_gset_eq:cN { @@_next~#1 } \c_empty_tl }
 %    \end{macrocode}
 %  \end{macro}
 %
 %
 %
+%  \begin{macro}{\hook_gclear_next_code:n}
+%    Discard anything set up for next invocation of the hook.
+% \changes{v1.0o}{2021/07/27}{Macro made public}
+%    \begin{macrocode}
+\cs_new_protected:Npn \hook_gclear_next_code:n #1
+  { \cs_gset_eq:cN { @@_next~#1 } \c_empty_tl }
+%    \end{macrocode}
+%  \end{macro}
 %
 %
 %
@@ -4769,6 +4802,15 @@
 %    \end{macrocode}
 %  \end{macro}
 %
+%  \begin{macro}{\ClearHookNext}
+%    
+% \changes{v1.0o}{2021/07/27}{Macro added}
+%    \begin{macrocode}
+\NewDocumentCommand \ClearHookNext { m }
+  { \hook_gclear_next_code:n {#1} }
+%    \end{macrocode}
+%  \end{macro}
+%
 %
 %  \begin{macro}{\RemoveFromHook}
 %    
diff --git a/base/testfiles-lthooks/github-0565.lvt b/base/testfiles-lthooks/github-0565.lvt
new file mode 100644
index 00000000..c14e5e04
--- /dev/null
+++ b/base/testfiles-lthooks/github-0565.lvt
@@ -0,0 +1,15 @@
+\documentclass{article}
+
+\input{test2e}
+
+\START
+
+\NewHook{foo}
+\AddToHookNext{foo}{\typeout{--> next}}
+\ClearHookNext{foo}
+
+\ShowHook{foo}
+
+
+
+\END
diff --git a/base/testfiles/github-0060.luatex.tlg b/base/testfiles-lthooks/github-0565.tlg
similarity index 55%
copy from base/testfiles/github-0060.luatex.tlg
copy to base/testfiles-lthooks/github-0565.tlg
index 1d0c6975..a4851590 100644
--- a/base/testfiles/github-0060.luatex.tlg
+++ b/base/testfiles-lthooks/github-0565.tlg
@@ -1,2 +1,6 @@
 This is a generated file for the LaTeX2e validation system.
 Don't change this file in any respect.
+-> The hook 'foo':
+> The hook is empty.
+<recently read> }
+l. ...\ShowHook{foo}
diff --git a/base/update-lthooks-tests.sh b/base/update-lthooks-tests.sh
index 31127810..1fe64f15 100644
--- a/base/update-lthooks-tests.sh
+++ b/base/update-lthooks-tests.sh
@@ -29,18 +29,18 @@ l3build save -cconfig-lthooks2 \
 
 
 l3build save -cconfig-lthooks \
- ltcmdhooks-001 \
- ltcmdhooks-002 \
- ltcmdhooks-003 \
- ltcmdhooks-004 \
- ltcmdhooks-005 \
- ltcmdhooks-005a \
- ltcmdhooks-006 \
- ltcmdhooks-007 \
- ltcmdhooks-008 \
- ltcmdhooks-009 \
- ltcmdhooks-010 \
- ltcmdhooks-011 \
+   ltcmdhooks-001 \
+   ltcmdhooks-002 \
+   ltcmdhooks-003 \
+   ltcmdhooks-004 \
+   ltcmdhooks-005 \
+   ltcmdhooks-005a \
+   ltcmdhooks-006 \
+   ltcmdhooks-007 \
+   ltcmdhooks-008 \
+   ltcmdhooks-009 \
+   ltcmdhooks-010 \
+   ltcmdhooks-011 \
    filehook-001 \
    filehook-002 \
    filehook-003 \
@@ -86,7 +86,8 @@ l3build save -cconfig-lthooks \
    shipout-000 \
    shipout-002 \
    shipout-004 \
-   shipout-005
+   shipout-005 \
+   github-0565
 
 exit
 





More information about the latex3-commits mailing list.