[latex3-commits] [git/LaTeX3-latex3-latex2e] shipout-hook-adjust: show raw shipout when debugging; make sure firstpage material does not end up in \ShipoutBox in case that gets reused (1d204f5e)

Frank Mittelbach frank.mittelbach at latex-project.org
Wed Jan 13 00:15:15 CET 2021


Repository : https://github.com/latex3/latex2e
On branch  : shipout-hook-adjust
Link       : https://github.com/latex3/latex2e/commit/1d204f5e1ad2a5ef80c3e67fb5af31a1e9960af0

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

commit 1d204f5e1ad2a5ef80c3e67fb5af31a1e9960af0
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Wed Jan 13 00:15:15 2021 +0100

    show raw shipout when debugging;
    make sure firstpage material does not end up in \ShipoutBox in case that gets reused


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

1d204f5e1ad2a5ef80c3e67fb5af31a1e9960af0
 base/changes.txt                                   |  6 ++
 base/ltshipout.dtx                                 | 75 ++++++++++++++++------
 base/testfiles-lthooks/shipout-005.tlg             |  2 +-
 base/testfiles-lthooks2/shipout2-008.tlg           |  6 +-
 base/testfiles-lthooks2/shipout2-009.tlg           |  9 +--
 base/testfiles-lthooks2/shipout2-010.lvt           |  3 +-
 base/testfiles-lthooks2/shipout2-010.tlg           |  4 +-
 base/testfiles-lthooks2/shipout2-013.lvt           | 39 +++++++++++
 .../{shipout2-010.tlg => shipout2-013.tlg}         | 66 +++++++++++++++++--
 base/update-lthooks-tests.sh                       |  1 +
 10 files changed, 171 insertions(+), 40 deletions(-)

diff --git a/base/changes.txt b/base/changes.txt
index 546385f8..0a3065d9 100644
--- a/base/changes.txt
+++ b/base/changes.txt
@@ -6,6 +6,12 @@ completeness or accuracy and it contains some references to files that
 are not part of the distribution.
 ================================================================================
 
+2021-01-12  Frank Mittelbach  <Frank.Mittelbach at latex-project.org>
+
+	* ltshipout.dtx: Make sure that the shipout/firstpage hook material
+	is not stored inside \ShipoutBox, in case that gets reused, e.g. via
+	\RawShipout but is only ever added to the very first page shipped out.
+
 2021-01-10  Frank Mittelbach  <Frank.Mittelbach at latex-project.org>
 
 	* ltshipout.dtx:
diff --git a/base/ltshipout.dtx b/base/ltshipout.dtx
index 2f12bce0..980bff3e 100644
--- a/base/ltshipout.dtx
+++ b/base/ltshipout.dtx
@@ -32,8 +32,8 @@
 %%% From File: ltshipout.dtx
 %
 %    \begin{macrocode}
-\providecommand\ltshipoutversion{v1.0f}
-\providecommand\ltshipoutdate{2021/01/11}
+\providecommand\ltshipoutversion{v1.0g}
+\providecommand\ltshipoutdate{2021/01/12}
 %    \end{macrocode}
 %
 %<*driver>
@@ -883,18 +883,13 @@
 %    \begin{macrocode}
               \@@_get_box_size:N #1
 %    \end{macrocode}
-%    Run the hooks for background and foreground (or nothing if this
-%    is called by \cs{RawShipout}.
+%    Run the hooks for background and foreground or, if this
+%    is called by \cs{RawShipout}, copy the box \cs{l_@@_raw_box} to
+%    \cs{l_shipout_box} so that firstpage and lastpage material gets
+%    added if necessary (that is always done to \cs{l_shipout_box}.
 %    \begin{macrocode}
               #3
 %    \end{macrocode}
-%    We then run \cs{@@_execute_firstpage_hook:} that adds
-%    the content of the hook \hook{shipout/firstpage} to the
-%    start of the first page (if non-empty). It is then redefined to
-%    do nothing on later pages.
-%    \begin{macrocode}
-              \@@_execute_firstpage_hook:
-%    \end{macrocode}
 %    Then we check if we have to add the \hook{shipout/lastpage} hook
 %    or the corresponding kernel hook
 %    because we have reached the last page. This test will be false for
@@ -913,16 +908,31 @@
                     \bool_gset_true:N \g_@@_lastpage_handled_bool
                 }
 %    \end{macrocode}
+%    We then run \cs{@@_add_firstpage_hook:} that adds
+%    the content of the hook \hook{shipout/firstpage} to the
+%    start of the first page (if non-empty). It is then redefined to
+%    do nothing on later pages.
+%    \begin{macrocode}
+              \@@_add_firstpage_hook:
+%    \end{macrocode}
 %    Finally we run the actual \TeX{} primitive for shipout. As that will
 %    expand delayed \cs{write} statements inside the page in which
 %    protected commands should not expand we first change \cs{protect}
 %    to the appropriate definition for that case.
 %    \begin{macrocode}
               \cs_set_eq:NN \protect \exp_not:N
-              \tex_shipout:D \box_use:N #1
+              \tex_shipout:D \box_use:N \l_shipout_box
 %    \end{macrocode}
-%    The \hook{shipout/after} hook (if exected in \verb=#4=) needs to
-%    run with \cs{protect}ed commands again being executedas that hook
+%    The \cs{l_shipout_box} may contain the firstpage material if this
+%    was the very first shipout. That makes it unsuitable for reuse in
+%    another shipout, so as a safety measure the next command resets
+%    \cs{l_shipout_box} to its earlier state if that is necessary. On
+%    later pages this is then a no-op.
+%    \begin{macrocode}
+              \@@_drop_firstpage_hook:
+%    \end{macrocode}
+%    The \hook{shipout/after} hook (if in \verb=#4=) needs to run with
+%    \cs{protect}ed commands again being executed, because that hook
 %    will ``typeset'' material added at the top of the next page.
 %    \begin{macrocode}
               \set at typeset@protect
@@ -972,7 +982,8 @@
 %    \begin{macrocode}
 \cs_new:Npn \@@_execute_nohooks_cont: {
   \@@_execute_main_cont:Nnnn \l_@@_raw_box
-     {} { \@@_debug:n{\typeout{Doing~ raw~ shipout~ ...}} } {} 
+     {} { \@@_debug:n{ \typeout{Doing~ raw~ shipout~ ...} }
+          \box_set_eq:NN \l_shipout_box \l_@@_raw_box } {} 
 } 
 %    \end{macrocode}
 %  \end{macro}
@@ -1024,26 +1035,44 @@
 %  \end{macro}
 %
 %
-%  \begin{macro}{\@@_execute_firstpage_hook: }
+%  \begin{macro}{\@@_add_firstpage_hook:,\@@_drop_firstpage_hook}
+%
 %    This command adds any specials into a box and adds that to the
 %    very beginning of the first box shipped out. After that we
 %    redefine it to do nothing on later pages.
 %    \begin{macrocode}
-\cs_new:Npn \@@_execute_firstpage_hook: {
+\cs_new:Npn \@@_add_firstpage_hook: {
 %    \end{macrocode}
 %    Adding something to the beginning means adding it to the
-%    background as that  layer is done first in the output. Of course
+%    background as that layer is done first in the output. Of course
 %    that is only needed if the hook actually contains anything.
 %    \begin{macrocode}
   \hook_if_empty:nF {shipout/firstpage}
-       { \@@_add_background_box:n { \UseHook{shipout/firstpage} } }
+       {
+%    \end{macrocode}
+%    First we make a copy of the \cs{l_shipout_box} that we can
+%    restore it later on.
+%    \begin{macrocode}
+         \box_set_eq:NN \l_@@_raw_box \l_shipout_box
+         \@@_add_background_box:n { \UseHook{shipout/firstpage} }
+%    \end{macrocode}
+%    After the actual shipout \cs{@@_drop_firstpage_hook:} is
+%    run. Normally that does nothing but now it is used (once) to
+%    restore the earlier content of \cs{l_shipout_box} and then
+%    redefines itself again to do nothing.
+%    \begin{macrocode}
+         \cs_gset:Npn \@@_drop_firstpage_hook: {
+           \box_set_eq:NN \l_shipout_box \l_@@_raw_box
+           \cs_gset_eq:NN \@@_drop_firstpage_hook:  \prg_do_nothing:
+         }
+       }
 %    \end{macrocode}
 %    Once we are here we change the definition to do nothing next time
 %    and we also change the command used to implement \cs{AtBeginDvi}
-%    to become a warning and not  add further material to a hook that
+%    to become a warning and not add further material to a hook that
 %    is never used again.
 %    \begin{macrocode}
-  \cs_gset_eq:NN \@@_execute_firstpage_hook: \prg_do_nothing:
+  \cs_gset_eq:NN \@@_add_firstpage_hook: \prg_do_nothing:
   \cs_gset:Npn \@@_add_firstpage_material:Nn ##1 ##2 {
     \@latex at warning{
         First~ page~ is~ already~ shipped~ out,~ ignoring\MessageBreak
@@ -1051,6 +1080,10 @@
   }
 }
 %    \end{macrocode}
+%
+%    \begin{macrocode}
+\cs_new_eq:NN \@@_drop_firstpage_hook: \prg_do_nothing:
+%    \end{macrocode}
 %  \end{macro}
 %
 %
diff --git a/base/testfiles-lthooks/shipout-005.tlg b/base/testfiles-lthooks/shipout-005.tlg
index 87dd0f50..496d65d1 100644
--- a/base/testfiles-lthooks/shipout-005.tlg
+++ b/base/testfiles-lthooks/shipout-005.tlg
@@ -99,7 +99,6 @@ Completed box being shipped out [1]
 ...\glue 0.0 plus 1.0fil minus 1.0fil
 .\kern 633.0
 .\kern 0.0
-.\kern 0.0
 .\kern -633.0
 .\hbox(0.0+0.0)x0.0
 ..\OT1/cmr/m/n/10 l
@@ -112,4 +111,5 @@ Completed box being shipped out [1]
 ..\OT1/cmr/m/n/10 e
 ..\glue 0.0 plus 1.0fil minus 1.0fil
 .\kern 633.0
+.\kern 0.0
 (shipout-005.aux)
diff --git a/base/testfiles-lthooks2/shipout2-008.tlg b/base/testfiles-lthooks2/shipout2-008.tlg
index 2d6dfbd8..75b5286b 100644
--- a/base/testfiles-lthooks2/shipout2-008.tlg
+++ b/base/testfiles-lthooks2/shipout2-008.tlg
@@ -19,15 +19,13 @@ Absolute page = 6 (target: 11)
 Doing raw shipout ...
 [4]
 Absolute page = 7 (target: 11)
-[4
-]
+[4]
 Chapter 3.
 Absolute page = 8 (target: 11)
 Doing raw shipout ...
 [5]
 Absolute page = 9 (target: 11)
-[5
-]
+[5]
 Absolute page = 10 (target: 11)
 Doing raw shipout ...
 [6]
diff --git a/base/testfiles-lthooks2/shipout2-009.tlg b/base/testfiles-lthooks2/shipout2-009.tlg
index 415ee86e..d0581d02 100644
--- a/base/testfiles-lthooks2/shipout2-009.tlg
+++ b/base/testfiles-lthooks2/shipout2-009.tlg
@@ -5,8 +5,7 @@ Absolute page = 1 (target: 12)
 Doing raw shipout ...
 [1]
 Absolute page = 2 (target: 12)
-[1
-]
+[1]
 Absolute page = 3 (target: 12)
 Doing raw shipout ...
 [2]
@@ -22,15 +21,13 @@ Absolute page = 7 (target: 12)
 Doing raw shipout ...
 [4]
 Absolute page = 8 (target: 12)
-[4
-]
+[4]
 Chapter 3.
 Absolute page = 9 (target: 12)
 Doing raw shipout ...
 [5]
 Absolute page = 10 (target: 12)
-[5
-]
+[5]
 Absolute page = 11 (target: 12)
 Doing raw shipout ...
 [6]
diff --git a/base/testfiles-lthooks2/shipout2-010.lvt b/base/testfiles-lthooks2/shipout2-010.lvt
index 33896fff..0723a734 100644
--- a/base/testfiles-lthooks2/shipout2-010.lvt
+++ b/base/testfiles-lthooks2/shipout2-010.lvt
@@ -10,7 +10,8 @@
 
 \AddToHook{shipout/background}{\put(.5\paperwidth, -.5\paperheight){\clap{\huge Background}}}
 
-% make two pages: the first without foreground/background (with shipout/after both would be identical)
+% make two pages: the first without foreground/background
+% (with shipout/after both would be identical)
 
 \AddToHook{shipout/before}{\RawShipout\copy\ShipoutBox}
 
diff --git a/base/testfiles-lthooks2/shipout2-010.tlg b/base/testfiles-lthooks2/shipout2-010.tlg
index 0f81a720..764de3a0 100644
--- a/base/testfiles-lthooks2/shipout2-010.tlg
+++ b/base/testfiles-lthooks2/shipout2-010.tlg
@@ -4,6 +4,7 @@ Absolute page = 1 (target: 4)
 Doing raw shipout ...
 Completed box being shipped out [1]
 \vbox(633.0+0.0)x407.0
+.\hbox(0.0+0.0)x0.0
 .\glue 16.0
 .\vbox(617.0+0.0)x345.0, shifted 62.0
 ..\vbox(12.0+0.0)x345.0, glue set 12.0fil
@@ -28,6 +29,7 @@ Completed box being shipped out [1]
 ...\glue 0.0 plus 1.0fil
 ...\OT1/cmr/m/n/10 1
 ...\glue 0.0 plus 1.0fil
+.\kern 0.0
 Absolute page = 2 (target: 4)
 Completed box being shipped out [1]
 \vbox(633.0+0.0)x407.0
@@ -55,7 +57,6 @@ Completed box being shipped out [1]
 .....\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
-.\hbox(0.0+0.0)x0.0
 .\glue 16.0
 .\vbox(617.0+0.0)x345.0, shifted 62.0
 ..\vbox(12.0+0.0)x345.0, glue set 12.0fil
@@ -81,7 +82,6 @@ Completed box being shipped out [1]
 ...\OT1/cmr/m/n/10 1
 ...\glue 0.0 plus 1.0fil
 .\kern 0.0
-.\kern 0.0
 Absolute page = 3 (target: 4)
 Doing raw shipout ...
 Completed box being shipped out [2]
diff --git a/base/testfiles-lthooks2/shipout2-013.lvt b/base/testfiles-lthooks2/shipout2-013.lvt
new file mode 100644
index 00000000..8dbdfb60
--- /dev/null
+++ b/base/testfiles-lthooks2/shipout2-013.lvt
@@ -0,0 +1,39 @@
+\RequirePackage[enable-debug]{expl3}
+\ExplSyntaxOn
+\debug_on:n { check-declarations , deprecation }
+\ExplSyntaxOff
+
+\documentclass{article}
+
+\input{regression-test}
+
+
+\AddToHook{shipout/background}{\put(.5\paperwidth, -.5\paperheight){\clap{\huge Background}}}
+
+% make two pages: the first without foreground/background
+% (with shipout/after both would be identical except for stuff from "firstpage")
+
+\AddToHook{shipout/after}{\RawShipout\copy\ShipoutBox}
+
+% test if this really only shows up on the very first and verylast page even though
+% we do a copy of the shipoutbox
+
+\AddToHook{shipout/firstpage}{\special{FIRST-ONLY}}
+\AddToHook{shipout/lastpage}{\special{LAST-ONLY}}
+
+
+\DebugShipoutsOn
+
+\showoutput
+
+\begin{document}
+
+\START
+
+X \newpage
+Y
+
+\end{document}
+
+
+
diff --git a/base/testfiles-lthooks2/shipout2-010.tlg b/base/testfiles-lthooks2/shipout2-013.tlg
similarity index 73%
copy from base/testfiles-lthooks2/shipout2-010.tlg
copy to base/testfiles-lthooks2/shipout2-013.tlg
index 0f81a720..5bb9e05d 100644
--- a/base/testfiles-lthooks2/shipout2-010.tlg
+++ b/base/testfiles-lthooks2/shipout2-013.tlg
@@ -1,9 +1,34 @@
 This is a generated file for the l3build validation system.
 Don't change this file in any respect.
 Absolute page = 1 (target: 4)
-Doing raw shipout ...
 Completed box being shipped out [1]
 \vbox(633.0+0.0)x407.0
+.\hbox(0.0+0.0)x0.0
+..\special{FIRST-ONLY}
+.\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(14.40277+4.0341)x0.0, glue set - 307.14749fil, shifted 397.48499
+.....\kern 307.14749
+.....\hbox(14.40277+4.0341)x0.0, glue set - 49.58824fil
+......\glue 0.0 plus 1.0fil minus 1.0fil
+......\OT1/cmr/m/n/20.74 B
+......\OT1/cmr/m/n/20.74 a
+......\OT1/cmr/m/n/20.74 c
+......\kern-0.54178
+......\OT1/cmr/m/n/20.74 k
+......\OT1/cmr/m/n/20.74 g
+......\OT1/cmr/m/n/20.74 r
+......\OT1/cmr/m/n/20.74 o
+......\OT1/cmr/m/n/20.74 u
+......\OT1/cmr/m/n/20.74 n
+......\OT1/cmr/m/n/20.74 d
+......\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 0.0 plus 1.0fil minus 1.0fil
 .\glue 16.0
 .\vbox(617.0+0.0)x345.0, shifted 62.0
 ..\vbox(12.0+0.0)x345.0, glue set 12.0fil
@@ -28,7 +53,10 @@ Completed box being shipped out [1]
 ...\glue 0.0 plus 1.0fil
 ...\OT1/cmr/m/n/10 1
 ...\glue 0.0 plus 1.0fil
+.\kern 0.0
+.\kern 0.0
 Absolute page = 2 (target: 4)
+Doing raw shipout ...
 Completed box being shipped out [1]
 \vbox(633.0+0.0)x407.0
 .\hbox(0.0+0.0)x0.0
@@ -55,7 +83,6 @@ Completed box being shipped out [1]
 .....\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
-.\hbox(0.0+0.0)x0.0
 .\glue 16.0
 .\vbox(617.0+0.0)x345.0, shifted 62.0
 ..\vbox(12.0+0.0)x345.0, glue set 12.0fil
@@ -81,11 +108,33 @@ Completed box being shipped out [1]
 ...\OT1/cmr/m/n/10 1
 ...\glue 0.0 plus 1.0fil
 .\kern 0.0
-.\kern 0.0
 Absolute page = 3 (target: 4)
-Doing raw shipout ...
 Completed box being shipped out [2]
 \vbox(633.0+0.0)x407.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(14.40277+4.0341)x0.0, glue set - 307.14749fil, shifted 397.48499
+.....\kern 307.14749
+.....\hbox(14.40277+4.0341)x0.0, glue set - 49.58824fil
+......\glue 0.0 plus 1.0fil minus 1.0fil
+......\OT1/cmr/m/n/20.74 B
+......\OT1/cmr/m/n/20.74 a
+......\OT1/cmr/m/n/20.74 c
+......\kern-0.54178
+......\OT1/cmr/m/n/20.74 k
+......\OT1/cmr/m/n/20.74 g
+......\OT1/cmr/m/n/20.74 r
+......\OT1/cmr/m/n/20.74 o
+......\OT1/cmr/m/n/20.74 u
+......\OT1/cmr/m/n/20.74 n
+......\OT1/cmr/m/n/20.74 d
+......\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 0.0 plus 1.0fil minus 1.0fil
 .\glue 16.0
 .\vbox(617.0+0.0)x345.0, shifted 62.0
 ..\vbox(12.0+0.0)x345.0, glue set 12.0fil
@@ -109,7 +158,10 @@ Completed box being shipped out [2]
 ...\glue 0.0 plus 1.0fil
 ...\OT1/cmr/m/n/10 2
 ...\glue 0.0 plus 1.0fil
+.\kern 0.0
 Absolute page = 4 (target: 4)
+Doing raw shipout ...
+Executing lastpage hook on page 4
 Completed box being shipped out [2]
 \vbox(633.0+0.0)x407.0
 .\hbox(0.0+0.0)x0.0
@@ -160,4 +212,8 @@ Completed box being shipped out [2]
 ...\OT1/cmr/m/n/10 2
 ...\glue 0.0 plus 1.0fil
 .\kern 0.0
-(shipout2-010.aux)
+.\kern -633.0
+.\hbox(0.0+0.0)x0.0
+..\special{LAST-ONLY}
+.\kern 633.0
+(shipout2-013.aux)
diff --git a/base/update-lthooks-tests.sh b/base/update-lthooks-tests.sh
index c7b63789..41338d1e 100644
--- a/base/update-lthooks-tests.sh
+++ b/base/update-lthooks-tests.sh
@@ -12,6 +12,7 @@ l3build save -cconfig-lthooks2 \
    shipout2-010 \
    shipout2-011 \
    shipout2-012 \
+   shipout2-013 \
    github-0360  \
    github-0431
 





More information about the latex3-commits mailing list.