[latex3-commits] [git/LaTeX3-latex3-latex2e] gh920: start at adding hook for #920 (c8d75c57)

[Frank Mittelbach]

Repository : https://github.com/latex3/latex2e
On branch  : gh920
Link       : https://github.com/latex3/latex2e/commit/c8d75c57744db5164d6804df72da19fbca559e7a

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

commit c8d75c57744db5164d6804df72da19fbca559e7a
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Tue Nov 8 15:39:59 2022 +0100

    start at adding hook for #920


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

c8d75c57744db5164d6804df72da19fbca559e7a
 base/changes.txt                             |  6 +++
 base/ltshipout.dtx                           | 49 ++++++++++++++++-----
 base/testfiles-lthooks/ltcmdhooks-001.tlg    |  1 +
 base/testfiles-lthooks/lthooks-000.tlg       |  1 +
 base/testfiles-lthooks/lthooks-001.tlg       |  3 ++
 base/testfiles-lthooks/lthooks-002.tlg       |  3 ++
 base/testfiles-lthooks/lthooks-003.tlg       |  2 +
 base/testfiles-lthooks/lthooks-004.tlg       |  2 +
 base/testfiles-lthooks/lthooks-005.tlg       |  2 +
 base/testfiles-lthooks/lthooks-006.tlg       |  2 +
 base/testfiles-lthooks/lthooks-007.tlg       |  3 ++
 base/testfiles-lthooks/lthooks-008.tlg       |  2 +
 base/testfiles-lthooks/lthooks-009.tlg       |  1 +
 base/testfiles-lthooks/lthooks-011.tlg       |  4 ++
 base/testfiles-lthooks/lthooks-013.tlg       |  1 +
 base/testfiles-lthooks/lthooks-021.tlg       |  1 +
 base/testfiles-lthooks/lthooks-legacy.tlg    |  1 +
 base/testfiles-lthooks2/github-0920.lvt      | 39 ++++++++++++++++
 base/testfiles-lthooks2/lthooks2-002.tlg     |  1 +
 base/testfiles-lthooks2/lthooks2-005.tlg     |  2 +
 base/testfiles-search/github-0920.luatex.tlg | 66 ++++++++++++++++++++++++++++
 base/testfiles-search/github-0920.lvt        | 40 +++++++++++++++++
 base/testfiles-search/github-0920.tlg        | 61 +++++++++++++++++++++++++
 base/testfiles-search/github-0920.xetex.tlg  | 60 +++++++++++++++++++++++++
 24 files changed, 342 insertions(+), 11 deletions(-)

diff --git a/base/changes.txt b/base/changes.txt
index 0ae9b55c..5087dff1 100644
--- a/base/changes.txt
+++ b/base/changes.txt
@@ -10,6 +10,12 @@ are not part of the distribution.
 All changes above are only part of the development branch for the next release.
 ================================================================================
 
+2022-11-08  Frank Mittelbach  <Frank.Mittelbach at latex-project.org>
+
+	* ltshipout.dtx:
+	Add shipout/final hook to be executed just before we
+	actually do the shipout (gh/920)
+
 #########################
 # 2022-11-01 Release
 #########################
diff --git a/base/ltshipout.dtx b/base/ltshipout.dtx
index ae29c1ac..f2c4978b 100644
--- a/base/ltshipout.dtx
+++ b/base/ltshipout.dtx
@@ -32,8 +32,8 @@
 %%% From File: ltshipout.dtx
 %
 %    \begin{macrocode}
-\providecommand\ltshipoutversion{v1.0m}
-\providecommand\ltshipoutdate{2022/08/26}
+\providecommand\ltshipoutversion{v1.0n}
+\providecommand\ltshipoutdate{2022/11/08}
 %    \end{macrocode}
 %
 %<*driver>
@@ -241,6 +241,18 @@
 %       But being placed after the main box content it will be typeset
 %       later and thus overprints it (i.e., is in the foreground).
 %
+%    \item[\hook{shipout/final}]
+%       This hook is executed after foreground and/or background
+%       material has been added, i.e., just in front of the actual
+%       shipout operation. Its purpose is to allow manipulation of the
+%       finalized box (stored in \cs{ShipoutBox}) with the extra
+%       material also in place (which is not yet the case in
+%       \hook{shipout/before}).
+%
+%       It cannot be used to cancel the shipout operation via
+%       \cs{DiscardShipoutBox} (that has
+%       to happen in \hook{shipout/before}, if desired!
+%
 %
 %    \item[\hook{shipout/firstpage}]
 %
@@ -296,7 +308,7 @@
 %    actual shipout. It is even run if there was a
 %    \cs{DiscardShipoutBox} request in the document.
 %
-%    The other hooks (except \hook{shipout/after}) are added inside
+%    The other hooks (except \hook{shipout/final} and \hook{shipout/after}) are added inside
 %    hboxes to the box being shipped out in the following order:
 %    \begin{center}
 %    \begin{tabular}{ll}
@@ -307,9 +319,13 @@
 %       \hook{shipout/lastpage}    & only on the last page \\
 %    \end{tabular}
 %    \end{center}
-%    If any of the hooks has no code then that particular no box is
+%    If any of the hooks has no code then the corresponding box is
 %    added at that point.
 %
+%    Once the (page) box as gotting the above extra content it can
+%    again be manipulated using the \hook{shipout/final} hook and then
+%    is shipped out for real.
+%
 %    Once the (page) box has been shipped out the \hook{shipout/after}
 %    hook is called (while you are still inside the output routine). It
 %    is not called if the shipout box was discarded.
@@ -381,13 +397,16 @@
 %
 %    \fmi{Once we have a new mark mechanism available we can improve
 %    on that and make sure that the declaration applies to the page
-%    that contains it.}
+%    that contains it --- not done (yet)}
+%
+%    \cs{DiscardShipoutBox} cannot be used in any of the \hook{shipout/...}
+%    hooks other than \hook{shipout/before}.
 %  \end{function}
 %
 %    In the \pkg{atbegshi} package there are a number of additional
 %    commands for use inside the \hook{shipout/before} hook. They
 %    should normally not be needed any more as one can instead simply
-%    add code to the hooks \hook{shipout/before},
+%    add code to the hooks \hook{shipout/before}, \hook{shipout/final},
 %    \hook{shipout/background} or
 %    \hook{shipout/foreground}.\footnote{If that assumption turns out to
 %    be wrong it would be trivial to change them to public functions
@@ -401,7 +420,9 @@
 % 
 %  \begin{variable}{pre_shipout_filter}
 %    Under Lua\TeX{} the \texttt{pre\_shipout\_filter} Lua callback is
-%    provided which gets called immediately before the shipout primitive gets invoked.
+%    provided which gets called directly after the
+%    \hook{shipout/final} hook, immediately before the shipout
+%    primitive gets invoked.
 %    The signature is
 %    \begin{verbatim}
 %     function(<node> head)
@@ -1014,15 +1035,20 @@
                       \_@@_add_foreground_box:n
                           { \UseHook{shipout/lastpage}
                             \@kernel at after@shipout at lastpage }
-                      \bool_gset_true:N \g_@@_lastpage_handled_bool
 %    \end{macrocode}
 %    We record that we have handled the \hook{shipout/lastpage} hook
 %    but only if we really did.
 % \changes{v1.0m}{2022/05/08}{Handle case where shipout/lastpage is
 %    run too early (gh/813)}
 %    \begin{macrocode}
+                      \bool_gset_true:N \g_@@_lastpage_handled_bool
                     }
                 }
+%    \end{macrocode}
+%    
+%  \changes{v1.0n}{2022/11/08}{Add shipout/final hook (gh/920)}
+%    \begin{macrocode}
+              \hook_use:n {shipout/final}
               \@@_finalize_box:
 %    \end{macrocode}
 %    Finally we run the actual \TeX{} primitive for shipout. As that will
@@ -1116,13 +1142,14 @@
 %    \end{macrocode}
 %  \end{macro}
 %
-%  \begin{macro}{shipout/before,shipout/after,
+%  \begin{macro}{shipout/before,shipout/final,shipout/after,
 %                   shipout/foreground,shipout/background,
-%                   shipout/firstpage,
-%                   shipout/lastpage}
+%                   shipout/firstpage,shipout/lastpage}
 %    Declaring all hooks for the shipout code.
+%  \changes{v1.0n}{2022/11/08}{Add shipout/final hook (gh/920)}
 %    \begin{macrocode}
 \hook_new:n{shipout/before}
+\hook_new:n{shipout/final}
 \hook_new:n{shipout/after}
 \hook_new:n{shipout/foreground}
 \hook_new:n{shipout/background}
diff --git a/base/testfiles-lthooks/ltcmdhooks-001.tlg b/base/testfiles-lthooks/ltcmdhooks-001.tlg
index 5d863b6a..1382e7fb 100644
--- a/base/testfiles-lthooks/ltcmdhooks-001.tlg
+++ b/base/testfiles-lthooks/ltcmdhooks-001.tlg
@@ -102,6 +102,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
diff --git a/base/testfiles-lthooks/lthooks-000.tlg b/base/testfiles-lthooks/lthooks-000.tlg
index 28c05df5..5f5a900f 100644
--- a/base/testfiles-lthooks/lthooks-000.tlg
+++ b/base/testfiles-lthooks/lthooks-000.tlg
@@ -42,6 +42,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
diff --git a/base/testfiles-lthooks/lthooks-001.tlg b/base/testfiles-lthooks/lthooks-001.tlg
index c35d9486..d0b2d375 100644
--- a/base/testfiles-lthooks/lthooks-001.tlg
+++ b/base/testfiles-lthooks/lthooks-001.tlg
@@ -48,6 +48,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
@@ -190,6 +191,7 @@ The sequence \g__hook_all_seq contains the items (without outer braces):
 >  {file/before}
 >  {file/after}
 >  {shipout/before}
+>  {shipout/final}
 >  {shipout/after}
 >  {shipout/foreground}
 >  {shipout/background}
@@ -250,6 +252,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
diff --git a/base/testfiles-lthooks/lthooks-002.tlg b/base/testfiles-lthooks/lthooks-002.tlg
index 26f1ab51..cbfd4f29 100644
--- a/base/testfiles-lthooks/lthooks-002.tlg
+++ b/base/testfiles-lthooks/lthooks-002.tlg
@@ -48,6 +48,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
@@ -192,6 +193,7 @@ The sequence \g__hook_all_seq contains the items (without outer braces):
 >  {file/before}
 >  {file/after}
 >  {shipout/before}
+>  {shipout/final}
 >  {shipout/after}
 >  {shipout/foreground}
 >  {shipout/background}
@@ -252,6 +254,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
diff --git a/base/testfiles-lthooks/lthooks-003.tlg b/base/testfiles-lthooks/lthooks-003.tlg
index 73759f8c..cc724541 100644
--- a/base/testfiles-lthooks/lthooks-003.tlg
+++ b/base/testfiles-lthooks/lthooks-003.tlg
@@ -55,6 +55,7 @@ The sequence \g__hook_all_seq contains the items (without outer braces):
 >  {file/before}
 >  {file/after}
 >  {shipout/before}
+>  {shipout/final}
 >  {shipout/after}
 >  {shipout/foreground}
 >  {shipout/background}
@@ -126,6 +127,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
diff --git a/base/testfiles-lthooks/lthooks-004.tlg b/base/testfiles-lthooks/lthooks-004.tlg
index 3f0577e3..94ce1afe 100644
--- a/base/testfiles-lthooks/lthooks-004.tlg
+++ b/base/testfiles-lthooks/lthooks-004.tlg
@@ -45,6 +45,7 @@ The sequence \g__hook_all_seq contains the items (without outer braces):
 >  {file/before}
 >  {file/after}
 >  {shipout/before}
+>  {shipout/final}
 >  {shipout/after}
 >  {shipout/foreground}
 >  {shipout/background}
@@ -110,6 +111,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
diff --git a/base/testfiles-lthooks/lthooks-005.tlg b/base/testfiles-lthooks/lthooks-005.tlg
index e8afa1c5..33e83af0 100644
--- a/base/testfiles-lthooks/lthooks-005.tlg
+++ b/base/testfiles-lthooks/lthooks-005.tlg
@@ -62,6 +62,7 @@ The sequence \g__hook_all_seq contains the items (without outer braces):
 >  {file/before}
 >  {file/after}
 >  {shipout/before}
+>  {shipout/final}
 >  {shipout/after}
 >  {shipout/foreground}
 >  {shipout/background}
@@ -133,6 +134,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
diff --git a/base/testfiles-lthooks/lthooks-006.tlg b/base/testfiles-lthooks/lthooks-006.tlg
index 0a960381..d33fabe5 100644
--- a/base/testfiles-lthooks/lthooks-006.tlg
+++ b/base/testfiles-lthooks/lthooks-006.tlg
@@ -43,6 +43,7 @@ The sequence \g__hook_all_seq contains the items (without outer braces):
 >  {file/before}
 >  {file/after}
 >  {shipout/before}
+>  {shipout/final}
 >  {shipout/after}
 >  {shipout/foreground}
 >  {shipout/background}
@@ -106,6 +107,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
diff --git a/base/testfiles-lthooks/lthooks-007.tlg b/base/testfiles-lthooks/lthooks-007.tlg
index 323d5e3f..7bc5361b 100644
--- a/base/testfiles-lthooks/lthooks-007.tlg
+++ b/base/testfiles-lthooks/lthooks-007.tlg
@@ -43,6 +43,7 @@ The sequence \g__hook_all_seq contains the items (without outer braces):
 >  {file/before}
 >  {file/after}
 >  {shipout/before}
+>  {shipout/final}
 >  {shipout/after}
 >  {shipout/foreground}
 >  {shipout/background}
@@ -107,6 +108,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
@@ -255,6 +257,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
diff --git a/base/testfiles-lthooks/lthooks-008.tlg b/base/testfiles-lthooks/lthooks-008.tlg
index 82681d81..d984b8b0 100644
--- a/base/testfiles-lthooks/lthooks-008.tlg
+++ b/base/testfiles-lthooks/lthooks-008.tlg
@@ -45,6 +45,7 @@ The sequence \g__hook_all_seq contains the items (without outer braces):
 >  {file/before}
 >  {file/after}
 >  {shipout/before}
+>  {shipout/final}
 >  {shipout/after}
 >  {shipout/foreground}
 >  {shipout/background}
@@ -114,6 +115,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
diff --git a/base/testfiles-lthooks/lthooks-009.tlg b/base/testfiles-lthooks/lthooks-009.tlg
index 5718da17..08558e75 100644
--- a/base/testfiles-lthooks/lthooks-009.tlg
+++ b/base/testfiles-lthooks/lthooks-009.tlg
@@ -48,6 +48,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
diff --git a/base/testfiles-lthooks/lthooks-011.tlg b/base/testfiles-lthooks/lthooks-011.tlg
index fc153587..bedb4863 100644
--- a/base/testfiles-lthooks/lthooks-011.tlg
+++ b/base/testfiles-lthooks/lthooks-011.tlg
@@ -43,6 +43,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
@@ -189,6 +190,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
@@ -337,6 +339,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
@@ -487,6 +490,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
diff --git a/base/testfiles-lthooks/lthooks-013.tlg b/base/testfiles-lthooks/lthooks-013.tlg
index 243b0f6a..b8a11dca 100644
--- a/base/testfiles-lthooks/lthooks-013.tlg
+++ b/base/testfiles-lthooks/lthooks-013.tlg
@@ -98,6 +98,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
diff --git a/base/testfiles-lthooks/lthooks-021.tlg b/base/testfiles-lthooks/lthooks-021.tlg
index ec093363..42928318 100644
--- a/base/testfiles-lthooks/lthooks-021.tlg
+++ b/base/testfiles-lthooks/lthooks-021.tlg
@@ -42,6 +42,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
diff --git a/base/testfiles-lthooks/lthooks-legacy.tlg b/base/testfiles-lthooks/lthooks-legacy.tlg
index fc741830..2e3c9b4d 100644
--- a/base/testfiles-lthooks/lthooks-legacy.tlg
+++ b/base/testfiles-lthooks/lthooks-legacy.tlg
@@ -67,6 +67,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
diff --git a/base/testfiles-lthooks2/github-0920.lvt b/base/testfiles-lthooks2/github-0920.lvt
new file mode 100644
index 00000000..4e3191d2
--- /dev/null
+++ b/base/testfiles-lthooks2/github-0920.lvt
@@ -0,0 +1,39 @@
+\RequirePackage[enable-debug]{expl3}
+\ExplSyntaxOn
+\debug_on:n { check-declarations , deprecation }
+\ExplSyntaxOff
+
+\documentclass[a4paper,oneside]{article}
+
+\usepackage{graphicx}
+
+\input{regression-test}
+
+\showoutput
+
+
+\setlength\parindent{0pt}
+
+\AddToHook{shipout/background}{%
+  \put(100,-100){\Huge X}%
+}
+
+
+\AddToHook{shipout/final}{%
+  \setbox\ShipoutBox=\vbox{\moveright1in\box\ShipoutBox}%
+  \setbox\ShipoutBox=\hbox to\paperwidth{\box\ShipoutBox\hss}%  
+  \setbox\ShipoutBox=\hbox{\reflectbox{\box\ShipoutBox}}%
+  \setbox\ShipoutBox=\vbox{\moveleft1in\box\ShipoutBox}%
+}
+
+\begin{document}
+
+\START
+
+ABC
+
+\end{document}
+
+
+
+
diff --git a/base/testfiles-lthooks2/lthooks2-002.tlg b/base/testfiles-lthooks2/lthooks2-002.tlg
index 93ef3afd..8fe8c221 100644
--- a/base/testfiles-lthooks2/lthooks2-002.tlg
+++ b/base/testfiles-lthooks2/lthooks2-002.tlg
@@ -56,6 +56,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
diff --git a/base/testfiles-lthooks2/lthooks2-005.tlg b/base/testfiles-lthooks2/lthooks2-005.tlg
index fdf4433b..025ae96b 100644
--- a/base/testfiles-lthooks2/lthooks2-005.tlg
+++ b/base/testfiles-lthooks2/lthooks2-005.tlg
@@ -43,6 +43,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
@@ -177,6 +178,7 @@ Update code for hook 'class/after' on input line ...:
 Update code for hook 'file/before' on input line ...:
 Update code for hook 'file/after' on input line ...:
 Update code for hook 'shipout/before' on input line ...:
+Update code for hook 'shipout/final' on input line ...:
 Update code for hook 'shipout/after' on input line ...:
 Update code for hook 'shipout/foreground' on input line ...:
 Update code for hook 'shipout/background' on input line ...:
diff --git a/base/testfiles-search/github-0920.luatex.tlg b/base/testfiles-search/github-0920.luatex.tlg
new file mode 100644
index 00000000..68f4ce86
--- /dev/null
+++ b/base/testfiles-search/github-0920.luatex.tlg
@@ -0,0 +1,66 @@
+This is a generated file for the l3build validation system.
+Don't change this file in any respect.
+Completed box being shipped out [1]
+\vbox(682.0+0.0)x525.23788, direction TLT
+.\hbox(682.0+0.0)x597.50787, shifted -72.26999, direction TLT
+..\hbox(682.0+0.0)x597.50787, direction TLT
+...\kern597.50787
+...\hbox(682.0+0.0)x0.0, direction TLT
+....\special{ps: currentpoint currentpoint translate -1 1 scale neg exch neg exch translate}
+....\hbox(682.0+0.0)x0.0, glue set - 597.50787fil, direction TLT
+.....\hbox(682.0+0.0)x597.50787, direction TLT
+......\hbox(682.0+0.0)x597.50787, glue set 127.23788fil, direction TLT
+.......\vbox(682.0+0.0)x470.26999, direction TLT
+........\vbox(682.0+0.0)x398.0, shifted 72.26999, direction TLT
+.........\hbox(0.0+0.0)x0.0, direction TLT
+.........\hbox(0.0+0.0)x0.0, direction TLT
+..........\kern0.0
+..........\vbox(0.0+0.0)x0.0, direction TLT
+...........\kern0.0
+...........\hbox(0.0+0.0)x0.0, direction TLT
+............\hbox(16.99782+0.0)x0.0, glue set - 117.24966fil, shifted 100.0, direction TLT
+.............\kern100.0
+.............\OT1/cmr/m/n/24.88 X
+.............\glue 0.0 plus 1.0fil minus 1.0fil
+............\glue 0.0 plus 1.0fil minus 1.0fil
+...........\glue 0.0 plus 1.0fil minus 1.0fil
+.........\glue 17.0
+.........\vbox(665.0+0.0)x345.0, shifted 53.0, direction TLT
+..........\vbox(12.0+0.0)x345.0, glue set 12.0fil, direction TLT
+...........\glue 0.0 plus 1.0fil
+...........\hbox(0.0+0.0)x345.0, direction TLT
+............\hbox(0.0+0.0)x345.0, direction TLT
+..........\glue 25.0
+..........\glue(\lineskip) 0.0
+..........\vbox(598.0+0.0)x345.0, glue set 587.9372fil, direction TLT
+...........\write-{}
+...........\glue(\topskip) 3.16669
+...........\hbox(6.83331+0.0)x345.0, glue set 323.1944fil, direction TLT
+............\localpar
+.............\localinterlinepenalty=0
+.............\localbrokenpenalty=0
+.............\localleftbox=null
+.............\localrightbox=null
+............\hbox(0.0+0.0)x0.0, direction TLT
+............\OT1/cmr/m/n/10 A
+............\OT1/cmr/m/n/10 B
+............\OT1/cmr/m/n/10 C
+............\penalty 10000
+............\glue(\parfillskip) 0.0 plus 1.0fil
+............\glue(\rightskip) 0.0
+...........\glue 0.0 plus 1.0fil
+...........\glue 0.0
+...........\glue 0.0 plus 0.0001fil
+..........\glue(\baselineskip) 23.55556
+..........\hbox(6.44444+0.0)x345.0, direction TLT
+...........\hbox(6.44444+0.0)x345.0, glue set 170.0fil, direction TLT
+............\glue 0.0 plus 1.0fil
+............\OT1/cmr/m/n/10 1
+............\glue 0.0 plus 1.0fil
+.........\kern0.0
+.........\kern0.0
+.......\glue 0.0 plus 1.0fil minus 1.0fil
+.....\glue 0.0 plus 1.0fil minus 1.0fil
+....\special{ps: currentpoint currentpoint translate 1 -1 div 1 1 div scale neg exch neg exch translate}
+...\glue 0.0 plus 1.0fil minus 1.0fil
+(github-0920.aux)
diff --git a/base/testfiles-search/github-0920.lvt b/base/testfiles-search/github-0920.lvt
new file mode 100644
index 00000000..c4eeda95
--- /dev/null
+++ b/base/testfiles-search/github-0920.lvt
@@ -0,0 +1,40 @@
+\RequirePackage[enable-debug]{expl3}
+\ExplSyntaxOn
+\debug_on:n { check-declarations , deprecation }
+\ExplSyntaxOff
+
+\documentclass[a4paper,oneside]{article}
+\usepackage{pict2e,graphicx}
+
+
+
+\input{regression-test}
+
+\showoutput
+
+
+\setlength\parindent{0pt}
+
+\AddToHook{shipout/background}{%
+  \put(100,-100){\Huge X}%
+}
+
+
+\AddToHook{shipout/final}{%
+  \setbox\ShipoutBox=\vbox{\moveright1in\box\ShipoutBox}%
+  \setbox\ShipoutBox=\hbox to\paperwidth{\box\ShipoutBox\hss}%  
+  \setbox\ShipoutBox=\hbox{\reflectbox{\box\ShipoutBox}}%
+  \setbox\ShipoutBox=\vbox{\moveleft1in\box\ShipoutBox}%
+}
+
+\begin{document}
+
+\START
+
+ABC
+
+\end{document}
+
+
+
+
diff --git a/base/testfiles-search/github-0920.tlg b/base/testfiles-search/github-0920.tlg
new file mode 100644
index 00000000..1e01cd12
--- /dev/null
+++ b/base/testfiles-search/github-0920.tlg
@@ -0,0 +1,61 @@
+This is a generated file for the l3build validation system.
+Don't change this file in any respect.
+Completed box being shipped out [1]
+\vbox(682.0+0.0)x525.23788
+.\hbox(682.0+0.0)x597.50787, shifted -72.26999
+..\hbox(682.0+0.0)x597.50787
+...\kern 597.50787
+...\hbox(682.0+0.0)x0.0
+....\special{ps: currentpoint currentpoint translate -1 1 scale neg exch neg exch translate}
+....\hbox(682.0+0.0)x0.0, glue set - 597.50787fil
+.....\hbox(682.0+0.0)x597.50787
+......\hbox(682.0+0.0)x597.50787, glue set 127.23788fil
+.......\vbox(682.0+0.0)x470.26999
+........\vbox(682.0+0.0)x398.0, shifted 72.26999
+.........\hbox(0.0+0.0)x0.0
+.........\hbox(0.0+0.0)x0.0
+..........\kern -72.27
+..........\vbox(0.0+0.0)x0.0, glue set 72.27fil
+...........\kern -72.27
+...........\hbox(0.0+0.0)x0.0
+............\hbox(16.99782+0.0)x0.0, glue set - 117.24966fil, shifted 100.0
+.............\kern 100.0
+.............\OT1/cmr/m/n/24.88 X
+.............\glue 0.0 plus 1.0fil minus 1.0fil
+............\glue 0.0 plus 1.0fil minus 1.0fil
+...........\glue 0.0 plus 1.0fil minus 1.0fil
+.........\glue 17.0
+.........\vbox(665.0+0.0)x345.0, shifted 53.0
+..........\vbox(12.0+0.0)x345.0, glue set 12.0fil
+...........\glue 0.0 plus 1.0fil
+...........\hbox(0.0+0.0)x345.0
+............\hbox(0.0+0.0)x345.0
+..........\glue 25.0
+..........\glue(\lineskip) 0.0
+..........\vbox(598.0+0.0)x345.0, glue set 587.9372fil
+...........\write-{}
+...........\glue(\topskip) 3.16669
+...........\hbox(6.83331+0.0)x345.0, glue set 323.1944fil
+............\hbox(0.0+0.0)x0.0
+............\OT1/cmr/m/n/10 A
+............\OT1/cmr/m/n/10 B
+............\OT1/cmr/m/n/10 C
+............\penalty 10000
+............\glue(\parfillskip) 0.0 plus 1.0fil
+............\glue(\rightskip) 0.0
+...........\glue 0.0 plus 1.0fil
+...........\glue 0.0
+...........\glue 0.0 plus 0.0001fil
+..........\glue(\baselineskip) 23.55556
+..........\hbox(6.44444+0.0)x345.0
+...........\hbox(6.44444+0.0)x345.0, glue set 170.0fil
+............\glue 0.0 plus 1.0fil
+............\OT1/cmr/m/n/10 1
+............\glue 0.0 plus 1.0fil
+.........\kern 0.0
+.........\kern 0.0
+.......\glue 0.0 plus 1.0fil minus 1.0fil
+.....\glue 0.0 plus 1.0fil minus 1.0fil
+....\special{ps: currentpoint currentpoint translate 1 -1 div 1 1 div scale neg exch neg exch translate}
+...\glue 0.0 plus 1.0fil minus 1.0fil
+(github-0920.aux)
diff --git a/base/testfiles-search/github-0920.xetex.tlg b/base/testfiles-search/github-0920.xetex.tlg
new file mode 100644
index 00000000..faa481e7
--- /dev/null
+++ b/base/testfiles-search/github-0920.xetex.tlg
@@ -0,0 +1,60 @@
+This is a generated file for the l3build validation system.
+Don't change this file in any respect.
+Completed box being shipped out [1]
+\vbox(682.0+0.0)x525.23788
+.\hbox(682.0+0.0)x597.50787, shifted -72.26999
+..\hbox(682.0+0.0)x597.50787
+...\kern 597.50787
+...\hbox(682.0+0.0)x0.0
+....\special{pdf:btrans}
+....\special{x:scale -1 1}
+....\hbox(682.0+0.0)x0.0, glue set - 597.50787fil
+.....\hbox(682.0+0.0)x597.50787
+......\hbox(682.0+0.0)x597.50787, glue set 127.23788fil
+.......\vbox(682.0+0.0)x470.26999
+........\vbox(682.0+0.0)x398.0, shifted 72.26999
+.........\hbox(0.0+0.0)x0.0
+..........\kern -72.26999
+..........\vbox(0.0+0.0)x0.0, glue set 72.26999fil
+...........\kern -72.26999
+...........\hbox(0.0+0.0)x0.0
+............\hbox(16.99782+0.0)x0.0, glue set - 117.24966fil, shifted 100.0
+.............\kern 100.0
+.............\OT1/cmr/m/n/24.88 X
+.............\glue 0.0 plus 1.0fil minus 1.0fil
+............\glue 0.0 plus 1.0fil minus 1.0fil
+...........\glue 0.0 plus 1.0fil minus 1.0fil
+.........\glue 17.0
+.........\vbox(665.0+0.0)x345.0, shifted 53.0
+..........\vbox(12.0+0.0)x345.0, glue set 12.0fil
+...........\glue 0.0 plus 1.0fil
+...........\hbox(0.0+0.0)x345.0
+............\hbox(0.0+0.0)x345.0
+..........\glue 25.0
+..........\glue(\lineskip) 0.0
+..........\vbox(598.0+0.0)x345.0, glue set 587.9372fil
+...........\write-{}
+...........\glue(\topskip) 3.16669
+...........\hbox(6.83331+0.0)x345.0, glue set 323.1944fil
+............\hbox(0.0+0.0)x0.0
+............\OT1/cmr/m/n/10 A
+............\OT1/cmr/m/n/10 B
+............\OT1/cmr/m/n/10 C
+............\penalty 10000
+............\glue(\parfillskip) 0.0 plus 1.0fil
+............\glue(\rightskip) 0.0
+...........\glue 0.0 plus 1.0fil
+...........\glue 0.0
+...........\glue 0.0 plus 0.0001fil
+..........\glue(\baselineskip) 23.55556
+..........\hbox(6.44444+0.0)x345.0
+...........\hbox(6.44444+0.0)x345.0, glue set 170.0fil
+............\glue 0.0 plus 1.0fil
+............\OT1/cmr/m/n/10 1
+............\glue 0.0 plus 1.0fil
+.........\kern 0.0
+.......\glue 0.0 plus 1.0fil minus 1.0fil
+.....\glue 0.0 plus 1.0fil minus 1.0fil
+....\special{pdf:etrans}
+...\glue 0.0 plus 1.0fil minus 1.0fil
+(github-0920.aux)