summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/ltshipout.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2022-12-04 03:01:36 +0000
committerNorbert Preining <norbert@preining.info>2022-12-04 03:01:36 +0000
commitb153d9b098596910fb2be9311f13c4415233c2a2 (patch)
treef0f44c9b4caa5756e6957885e8691c0268920a56 /macros/latex-dev/base/ltshipout.dtx
parent34896a353fe22e8ac88ef0b4e39f4fa878e2b0b6 (diff)
CTAN sync 202212040301
Diffstat (limited to 'macros/latex-dev/base/ltshipout.dtx')
-rw-r--r--macros/latex-dev/base/ltshipout.dtx51
1 files changed, 39 insertions, 12 deletions
diff --git a/macros/latex-dev/base/ltshipout.dtx b/macros/latex-dev/base/ltshipout.dtx
index ae29c1acad..7aa07f754b 100644
--- a/macros/latex-dev/base/ltshipout.dtx
+++ b/macros/latex-dev/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>
@@ -75,7 +75,7 @@
% \providecommand\pkg[1]{\texttt{#1}}
%
%
-% \title{The \texttt{ltshipout} package\thanks{This package has version
+% \title{The \texttt{ltshipout} documentation\thanks{This file has version
% \ltshipoutversion\ dated \ltshipoutdate, \copyright\ \LaTeX\
% Project.}}
%
@@ -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}]
+% 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} 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 has got the above extra content it can
+% again be manipulated using the \hook{shipout} 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},
% \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} 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@after@shipout@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 hook (gh/920)}
+% \begin{macrocode}
+ \hook_use:n {shipout}
\@@_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,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 hook (gh/920)}
% \begin{macrocode}
\hook_new:n{shipout/before}
+\hook_new:n{shipout}
\hook_new:n{shipout/after}
\hook_new:n{shipout/foreground}
\hook_new:n{shipout/background}