[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.