[latex3-commits] [git/LaTeX3-latex3-latex2e] shipout-hook-adjust: Change package warnings to kernel warnings; allow \DiscardShipoutBox on document-level to have an effect (as documented); some more documentation (bc8b3701)
Frank Mittelbach
frank.mittelbach at latex-project.org
Mon Jan 11 21:47:21 CET 2021
Repository : https://github.com/latex3/latex2e
On branch : shipout-hook-adjust
Link : https://github.com/latex3/latex2e/commit/bc8b37010aba7318d6d8583cf5267a99f1b6dd9e
>---------------------------------------------------------------
commit bc8b37010aba7318d6d8583cf5267a99f1b6dd9e
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Mon Jan 11 21:47:21 2021 +0100
Change package warnings to kernel warnings;
allow \DiscardShipoutBox on document-level to have an effect (as documented);
some more documentation
>---------------------------------------------------------------
bc8b37010aba7318d6d8583cf5267a99f1b6dd9e
base/ltshipout.dtx | 37 ++++++++++++++-----------
base/testfiles-lthooks/shipout-002.tlg | 2 +-
base/testfiles-lthooks2/shipout2-011.lvt | 1 +
base/testfiles-lthooks2/shipout2-012.lvt | 47 ++++++++++++++++++++++++++++++++
base/testfiles-lthooks2/shipout2-012.tlg | 19 +++++++++++++
base/update-lthooks-tests.sh | 3 ++
6 files changed, 92 insertions(+), 17 deletions(-)
diff --git a/base/ltshipout.dtx b/base/ltshipout.dtx
index f3ba62b4..fc7c5113 100644
--- a/base/ltshipout.dtx
+++ b/base/ltshipout.dtx
@@ -254,9 +254,11 @@
% As mentioned above the hook \hook{shipout/before} is executed
% first and can manipulate the prepared shipout box stored in
% \cs{ShipoutBox} or set things up for use in \cs{write} during the
-% actual shipout. The other hooks are added inside hboxes to the
-% box being shipped out in the following
-% order:
+% 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
+% hboxes to the box being shipped out in the following order:
% \begin{center}
% \begin{tabular}{ll}
% \hook{shipout/firstpage} & only on the first page \\
@@ -269,21 +271,21 @@
% If any of the hooks has no code then that particular no box is
% added at that point.
%
-% Once the (page) box has been shipped out the
-% \hook{shipout/after} hook is called (while you are still inide
-% the output routine.
+% Once the (page) box has been shipped out the \hook{shipout/after}
+% hook is called (while you are still inide the output routine). It
+% is not called if the shipout box was discarded.
%
% In a document that doesn't produce pages, e.g., only makes
-% \cs{typeout}s, none of the hooks are executed (as there is no
+% \cs{typeout}s, none of the hooks are ever executed (as there is no
% \cs{shipout}) not even the \hook{shipout/lastpage} hook.
%
% If \cs{RawShipout} is used instead of \cs{shipout} then only the
% hooks \hook{shipout/firstpage} and \hook{shipout/lastpage} are
-% executed, all others are bypassed.
+% executed (on the first or last page), all others are bypassed.
%
%
-% \subsection{Legacy \LaTeX{} commands}
%
+% \subsection{Legacy \LaTeX{} commands}
%
% \begin{function}{\AtBeginDvi,\AtEndDvi}
% \cs{AtBeginDvi} is the existing \LaTeXe{} interface to fill the
@@ -307,12 +309,12 @@
%
% \subsection{Special commands for use inside the hooks}
%
-% \begin{function}{\DiscardShipoutBox,\shipout_discard_box:}
+% \begin{function}{\DiscardShipoutBox,\shipout_discard:}
% \begin{syntax}
% \cs{AddToHookNext} \texttt{\{shipout/before\} \{...\cs{DiscardShipoutBox}...\}}
% \end{syntax}
% The \cs{DiscardShipoutBox} declaration (L3 name
-% \cs{shipout_discard_box:})
+% \cs{shipout_discard:})
% requests that on the next
% shipout the page box is thrown away instead of being shipped to
% the \texttt{.dvi} or \texttt{.pdf} file.
@@ -321,8 +323,10 @@
% some processing logic that decides to use or not to use the page.
%
% Note that if this declaration is used directly in the document it
-% may depend on the placement to which page it applies, given that
+% may depends on the placement to which page it applies, given that
% \LaTeX{} output routine is called in an asynchronous manner!
+% Thus normally one would use this only as part of the
+% \hook{shipout/before} code.
%
% \fmi{Once we have a new mark mechanism available we can improve
% on that and make sure that the declaration applies to the page
@@ -779,7 +783,7 @@
% \begin{macrocode}
\cs_new:Npn \@@_execute_main_cont:Nnnn #1#2#3#4 {
\box_if_empty:NTF #1
- { \PackageWarning{ltshipout}{Ignoring~ void~ shipout~ box} }
+ { \@latex at warning{Ignoring~ void~ shipout~ box} }
{
% \end{macrocode}
% Otherwise we assume that we will ship something and prepare for
@@ -787,7 +791,8 @@
% \cs{protect} while we are running the hook code).
% We also save the current \cs{protect} state to restore it later.
% \begin{macrocode}
- \bool_gset_false:N \g_@@_discard_bool
+% \bool_gset_false:N \g_@@_discard_bool % setting this would disable
+ % \DiscardShipoutBox on doc-level
\cs_set_eq:NN \@@_saved_protect: \protect
\set at typeset@protect
% \end{macrocode}
@@ -820,7 +825,7 @@
% we now test for it.
% \begin{macrocode}
\bool_if:NTF \g_@@_discard_bool
- { \PackageInfo{ltshipout}{Completed~ page~ discarded}
+ { \@latex at info@no at line{Completed~ page~ discarded}
\bool_gset_false:N \g_@@_discard_bool
% \end{macrocode}
% As we are discarding the page box and not shipping anything out,
@@ -846,7 +851,7 @@
% practice way is to use the request mechanism.
% \begin{macrocode}
{ \box_if_empty:NTF #1
- { \PackageWarning{ltshipout}{
+ { \@latex at warning{
Shipout~ box~ was~ voided~ by~ hook,\MessageBreak
ignoring~ shipout~ box }
}
diff --git a/base/testfiles-lthooks/shipout-002.tlg b/base/testfiles-lthooks/shipout-002.tlg
index 2c635352..5039c6ce 100644
--- a/base/testfiles-lthooks/shipout-002.tlg
+++ b/base/testfiles-lthooks/shipout-002.tlg
@@ -30,7 +30,7 @@ Completed box being shipped out [1]
...\glue 0.0 plus 1.0fil
.\kern 0.0
Dropping page 2
-Package ltshipout Info: Completed page discarded on input line ....
+LaTeX Info: Completed page discarded.
Absolute page = 2 (target: 1073741823)
Completed box being shipped out [3]
\vbox(633.0+0.0)x407.0
diff --git a/base/testfiles-lthooks2/shipout2-011.lvt b/base/testfiles-lthooks2/shipout2-011.lvt
index 8502342b..4786927c 100644
--- a/base/testfiles-lthooks2/shipout2-011.lvt
+++ b/base/testfiles-lthooks2/shipout2-011.lvt
@@ -29,6 +29,7 @@
\endgroup
}
+% push floats onto specific pages
\AddToHook{shipout/after}{%
\ifcase \ReadonlyShipoutCounter
diff --git a/base/testfiles-lthooks2/shipout2-012.lvt b/base/testfiles-lthooks2/shipout2-012.lvt
new file mode 100644
index 00000000..8332dc8f
--- /dev/null
+++ b/base/testfiles-lthooks2/shipout2-012.lvt
@@ -0,0 +1,47 @@
+\RequirePackage[enable-debug]{expl3}
+\ExplSyntaxOn
+\debug_on:n { check-declarations , deprecation }
+\ExplSyntaxOff
+
+\documentclass{article}
+
+\input{regression-test}
+
+\usepackage{lipsum}
+
+
+\DebugShipoutsOn
+
+
+\newbox\testbox
+
+\begin{document}
+
+\START
+
+
+X1 \newpage
+
+X2 \RawShipout\box\testbox X2\newpage % testbox is void, no effect
+
+\savebox\testbox{Z}
+
+X3 \RawShipout\box\testbox X3\newpage % insert extra page
+
+\AddToHookNext{shipout/before}{\setbox\ShipoutBox\box\testbox} % ShipoutBox voided
+
+X4 \newpage
+
+X5 \newpage
+
+\DiscardShipoutBox
+
+X6 \newpage
+
+X7
+
+
+\end{document}
+
+
+
diff --git a/base/testfiles-lthooks2/shipout2-012.tlg b/base/testfiles-lthooks2/shipout2-012.tlg
new file mode 100644
index 00000000..23bd037f
--- /dev/null
+++ b/base/testfiles-lthooks2/shipout2-012.tlg
@@ -0,0 +1,19 @@
+This is a generated file for the l3build validation system.
+Don't change this file in any respect.
+Absolute page = 1 (target: 6)
+[1
+]
+LaTeX Warning: Ignoring void shipout box on input line ....
+Absolute page = 2 (target: 6)
+[2]
+Absolute page = 3 (target: 6)
+[3]
+Absolute page = 4 (target: 6)
+[3]
+LaTeX Warning: Shipout box was voided by hook,
+ ignoring shipout box on input line ....
+Absolute page = 5 (target: 6)
+[5]
+LaTeX Info: Completed page discarded.
+Absolute page = 6 (target: 6)
+[7] (shipout2-012.aux)
diff --git a/base/update-lthooks-tests.sh b/base/update-lthooks-tests.sh
index f6c805f1..c7b63789 100644
--- a/base/update-lthooks-tests.sh
+++ b/base/update-lthooks-tests.sh
@@ -9,6 +9,9 @@ l3build save -cconfig-lthooks2 \
shipout2-007 \
shipout2-008 \
shipout2-009 \
+ shipout2-010 \
+ shipout2-011 \
+ shipout2-012 \
github-0360 \
github-0431
More information about the latex3-commits
mailing list.