[latex3-commits] [git/LaTeX3-latex3-latex2e] develop: Gh565 \ClearHookNext (#632) (388a86f6)
GitHub
noreply at github.com
Wed Jul 28 10:49:05 CEST 2021
Repository : https://github.com/latex3/latex2e
On branch : develop
Link : https://github.com/latex3/latex2e/commit/388a86f69a5a728d066f893614b6e4666c6afb19
>---------------------------------------------------------------
commit 388a86f69a5a728d066f893614b6e4666c6afb19
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Wed Jul 28 10:49:05 2021 +0200
Gh565 \ClearHookNext (#632)
* fix for #565
* the change shows up in one more test
* Add argument normalisation for \hook_gclear_next_code:n
Co-authored-by: PhelypeOleinik <phelype.oleinik at latex-project.org>
>---------------------------------------------------------------
388a86f69a5a728d066f893614b6e4666c6afb19
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, 104 insertions(+), 20 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..bae3a126 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
{
@@ -4290,13 +4317,21 @@
{ \@@_tl_gset:Nn #1 { \@@_clear_next: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,\@@_clear_next: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
+ { \@@_normalize_hook_args:Nn \@@_clear_next:n {#1} }
+\cs_new_protected:Npn \@@_clear_next:n #1
+ { \cs_gset_eq:cN { @@_next~#1 } \c_empty_tl }
+% \end{macrocode}
+% \end{macro}
%
%
%
@@ -4769,6 +4804,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.