summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/ltshipout.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex-dev/base/ltshipout.dtx')
-rw-r--r--macros/latex-dev/base/ltshipout.dtx825
1 files changed, 567 insertions, 258 deletions
diff --git a/macros/latex-dev/base/ltshipout.dtx b/macros/latex-dev/base/ltshipout.dtx
index 8d6150b593..650c46866e 100644
--- a/macros/latex-dev/base/ltshipout.dtx
+++ b/macros/latex-dev/base/ltshipout.dtx
@@ -1,24 +1,38 @@
% \iffalse meta-comment
-%
+%%
%% File: ltshipout.dtx (C) Copyright 2020 Frank Mittelbach, LaTeX Team
+%%
%
-% It may be distributed and/or modified under the conditions of the
-% LaTeX Project Public License (LPPL), either version 1.3c of this
-% license or (at your option) any later version. The latest version
-% of this license is in the file
+% This file is part of the LaTeX base system.
+% -------------------------------------------
%
+% It may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3c
+% of this license or (at your option) any later version.
+% The latest version of this license is in
% https://www.latex-project.org/lppl.txt
+% and version 1.3c or later is part of all distributions of LaTeX
+% version 2008 or later.
+%
+% This file has the LPPL maintenance status "maintained".
%
+% The list of all files belonging to the LaTeX base distribution is
+% given in the file `manifest.txt'. See also `legal.txt' for additional
+% information.
%
-% The development version of the bundle can be found below
+% The list of derived (unpacked) files belonging to the distribution
+% and covered by LPPL is defined by the unpacking scripts (with
+% extension .ins) which are part of the distribution.
+%
+% \fi
%
-% https://github.com/FrankMittelbach/...
+% \iffalse
%
-% for those people who are interested or want to report an issue.
+%%% From File: ltshipout.dtx
%
% \begin{macrocode}
-\providecommand\ltshipoutversion{v0.9a}
-\providecommand\ltshipoutdate{2020/07/15}
+\providecommand\ltshipoutversion{v1.0a}
+\providecommand\ltshipoutdate{2020/08/31}
% \end{macrocode}
%
%<*driver>
@@ -53,7 +67,8 @@
%
% \long\def\fmi#1{\begin{quote}\itshape Todo: #1\end{quote}}
%
-% \newcommand\hook[1]{\texttt{#1}}
+% \providecommand\hook[1]{\texttt{#1}}
+% \providecommand\pkg[1]{\texttt{#1}}
%
%
% \title{The \texttt{ltshipout} package\thanks{This package has version
@@ -94,13 +109,13 @@
% manipulated through a set of hooks after which it is shipped out
% for real.
% \end{function}
-
+%
% \begin{variable}{\ShipoutBox,\l_shipout_box}
% This box register is called \cs{ShipoutBox} (alternatively available via the
% L3 name \cs{l_shipout_box}).
% \end{variable}
%
-
+%
% \begin{variable}{\l_shipout_box_ht_dim,
% \l_shipout_box_dp_dim,\l_shipout_box_wd_dim,
% \l_shipout_box_ht_plus_dp_dim}
@@ -136,7 +151,7 @@
% \item[\hook{shipout/background}]
%
% This hook adds a picture environment into the background of
-% the page (with the \texttt{(0,0)} coordinate in the top-left
+% the page with the \texttt{(0,0)} coordinate in the top-left
% corner using a \cs{unitlength} of \texttt{1pt}.
%
% It should therefore only receive \cs{put} commands or other
@@ -144,10 +159,6 @@
% vertical coordinate values would normally be
% negative.
%
-% \fmi{Again, mainly \pkg{atbegshi} compatibility. Not
-% sure it is best to have to always use negative
-% coordinates.}
-%
% Technically this is implemented by adding a zero-sized
% \cs{hbox} as the very first item into the \cs{ShipoutBox}
% containing that \texttt{picture} environment. Thus the rest of
@@ -157,7 +168,7 @@
% \item[\hook{shipout/foreground}]
%
% This hook adds a picture environment into the foreground of
-% the page (with the \texttt{(0,0)} coordinate in the top-left
+% the page with the \texttt{(0,0)} coordinate in the top-left
% corner using a \cs{unitlength} of \texttt{1pt}.
%
% Technically this is implemented by adding a zero-sized
@@ -171,29 +182,30 @@
% \item[\hook{shipout/firstpage}]
%
% The material from this hook is executed only once at the very
-% beginning of the first output page. It should only contain
-% \cs{special} commands needed to direct post processors
-% handling the \texttt{.dvi} or \texttt{.pdf} output.\fmi{not
-% sure it has to be that restrictive.}
+% beginning of the first output page that is shipped out (i.e.,
+% not discarded at the last minute). It should only contain
+% \cs{special} or similar commands needed to direct post processors
+% handling the \texttt{.dvi} or \texttt{.pdf} output.\footnotemark
%
-% In \LaTeXe{} that was already existing but implemented as a box
-% register \cs{@begindvibox}.
-% \fmi{drop or at least mark the obsolete code in latex.ltx}
+% ^^A \fmi{not sure it has to be that restrictive.}
%
%
% \item[\hook{shipout/lastpage}]
%
% The corresponding hook to add \cs{special}s at the very end of
-% the output file. It is only entered on the very last page.
+% the output file. It is only executed on the very last page ---
+% or rather on the page that \LaTeX{} believes is the last one.
%
-% It may not be possible for \LaTeX{} to correctly determine which page is
-% the last one without several reruns. If this happens and the
-% hook is non-empty then \LaTeX{} will add an extra page to
-% place the material and also request a rerun to get the correct
-% placement sorted out.
+% It may not be possible for \LaTeX{} to correctly determine
+% which page is the last one without several reruns. If this
+% happens and the hook is non-empty then \LaTeX{} will add an
+% extra page to place the material and also request a rerun to
+% get the correct placement sorted out.
%
% \end{description}
-% \end{variable}
+% \end{variable}\footnotetext{In
+% \LaTeXe{} that was already existing, but implemented using a box
+% register with the name \cs{@begindvibox}.}
%
% As mentioned above the hook \hook{shipout/before} is executed
% first and can manipulate the prepared shipout box stored in
@@ -280,7 +292,7 @@
% routine). More precisely, it is incremented only after it is
% clear that a page will be shipped out, i.e., after the
% \hook{shipout/before} hook (because that might discard the page)!
-
+%
% Just like with the \texttt{page} counter its value is
% only accurate within the output routine. In the body of the
% document it may be off by one as the output routine is called
@@ -314,22 +326,33 @@
% reliable inside the output routine!
% \end{variable}
%
-
+% \begin{variable}{\PreviousTotalPages}
+% \begin{syntax}
+% \cs{thetotalpages}/\cs{PreviousTotalPages}
+% \end{syntax}
+% Command that expands to the number of total pages from the
+% previous run. If there was no previous run or if usedin the
+% preamble it expands to
+% \texttt{0}. Note that this is a command to a counter, so in order
+% to display the number in, say, Roman numerals you have to assign
+% its value to a counter and then use \cs{Roman} on that counter.
+% \end{variable}
+%
%
% \subsection{Debugging shipout code}
%
-% \begin{function}{\DebugShipoutOn,\DebugShipoutOff,
+% \begin{function}{\DebugShipoutsOn,\DebugShipoutsOff,
% \shipout_debug_on:,\shipout_debug_off:}
% \begin{syntax}
-% \cs{DebugShipoutOn}
+% \cs{DebugShipoutsOn}
% \end{syntax}
% Turn the debugging of shipout code on or off. This displays
% changes made to the shipout data structures. \fmi{This needs
-% some rationalizing and will probably not stay this way.}
+% some rationalizing and may not stay this way.}
% \end{function}
%
%
-
+%
%
% \section{Emulating commands from other packages}
%
@@ -381,8 +404,8 @@
% just adding it to the hook should be sufficient.
% \end{function}
%
-
-
+%
+%
% \begin{function}{\AtBeginShipoutBox}
% This is the name of the shipout box as \pkg{atbegshi} knows it.
% \end{function}
@@ -406,13 +429,12 @@
% The \pkg{atbegshi} names for \cs{AtBeginDvi} and \cs{DiscardShipoutBox}.
% \end{function}
%
-
-
-
+%
+%
+%
% \subsection{Emulating \pkg{everyshi}}
%
-
-
+%
% \begin{function}{\EveryShipout}
% \begin{syntax}
% \cs{EveryShipout}\Arg{code} $\equiv$ \cs{AddToHook}\texttt{\{shipout/before\}}\Arg{code}
@@ -425,15 +447,15 @@
% \end{syntax}
% \end{function}
%
-
-
+%
+%
% \subsection{Emulating \pkg{atenddvi}}
%
% The \pkg{atenddvi} package implemented only a single command:
% \cs{AtEndDvi} and that is now available out of the box.
-
-
-
+%
+%
+%
% \subsection{Emulating \pkg{everypage}}
%
% This page takes over the original \cs{@begindvi} hook and replaces
@@ -448,8 +470,20 @@
%
% \section{The Implementation}
% \begin{macrocode}
-%<*2ekernel>
%<@@=shipout>
+% \end{macrocode}
+%
+% At the moment the whole module rolls back in one go, but if we
+% make any modifications in later releases this will then need
+% splitting.
+% \begin{macrocode}
+%<*2ekernel|latexrelease>
+%<latexrelease>\IncludeInRelease{2020/10/01}%
+%<latexrelease> {\shipout}{Hook mangement (shipout)}%
+% \end{macrocode}
+%
+%
+% \begin{macrocode}
\ExplSyntaxOn
% \end{macrocode}
%
@@ -489,24 +523,10 @@
% \end{macro}
% \end{macro}
%
-
-% \begin{macro}{shipout/before,
-% shipout/foreground,shipout/background,
-% shipout/firstpage,
-% shipout/lastpage}
-% Declaring all hooks for the shipout code.
-% \begin{macrocode}
-\hook_new:n{shipout/before}
-\hook_new:n{shipout/foreground}
-\hook_new:n{shipout/background}
-\hook_new:n{shipout/firstpage}
-\hook_new:n{shipout/lastpage}
-% \end{macrocode}
-% \end{macro}
-
-
-
-
+%
+%
+%
+%
% \begin{macro}{\ShipoutBox,\l_shipout_box}
% The box filled with the page to be shipped out (both L3 and
% \LaTeXe{} name).
@@ -518,10 +538,10 @@
\cs_set_eq:NN \ShipoutBox \l_shipout_box
% \end{macrocode}
% \end{macro}
-
-
-
-
+%
+%
+%
+%
% \begin{macro}{\@@_execute:}
% This is going to the be the code run by \cs{shipout}. The code
% follows closely the ideas from \pkg{atbegshi}, so not
@@ -535,25 +555,25 @@
}
% \end{macrocode}
% \end{macro}
-
-
+%
+%
% \begin{macro}{\shipout}
% Overloading the \cs{shipout} primitive:
% \begin{macrocode}
\cs_gset_eq:NN \shipout \@@_execute:
% \end{macrocode}
% \end{macro}
-
-
+%
+%
% \begin{macro}{\l_@@_group_level_tl}
% Helper token list to record the group level at which
% \cs{@@_execute:} is encountered. \begin{macrocode}
\tl_new:N \l_@@_group_level_tl
% \end{macrocode}
% \end{macro}
-
+%
-
+%
% \begin{macro}{\@@_execute_test_level:}
% If the group level has changed then we are still constructing
% \cs{l_shipout_box} and to continue we need to wait until the
@@ -567,8 +587,8 @@
}
% \end{macrocode}
% \end{macro}
-
-
+%
+%
% \begin{macro}{\@@_execute_cont:}
% When we have reached this point the shipout box has been
% processed and is available in \cs{l_shipout_box} and ready for
@@ -589,8 +609,10 @@
% Otherwise we assume that we will ship something and prepare for
% final adjustments (in particular setting the state of
% \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
+ \cs_set_eq:NN \@@_saved_protect: \protect
\set@typeset@protect
% \end{macrocode}
% We also store the current shipout box dimension in registers, so that
@@ -675,13 +697,13 @@
%
% \begin{macrocode}
\@@_get_box_size:N \l_shipout_box
- \@kernel@before@shipout@foreground
\hook_if_empty:nF {shipout/foreground}
{ \@@_add_foreground_picture:n
{ \hook_use:n {shipout/foreground} } }
\hook_if_empty:nF {shipout/background}
{ \@@_add_background_picture:n
- { \hook_use:n {shipout/background} } }
+ { \@kernel@before@shipout@background
+ \hook_use:n {shipout/background} } }
% \end{macrocode}
% We then run \cs{@@_execute_firstpage_hook:} that adds
% the content of the hook \hook{shipout/firstpage} to the
@@ -713,22 +735,52 @@
\tex_shipout:D \box_use:N \l_shipout_box
}
}
+% \end{macrocode}
+% Restore the value of \cs{protect} in case \cs{shipout} is called
+% outside of the output routine (where it is automatically restored
+% because of the implicit group).
+% \begin{macrocode}
+ \cs_set_eq:NN \protect \@@_saved_protect:
}
}
% \end{macrocode}
% \end{macro}
-
-
-
-% \begin{macro}{\@kernel@after@shipout@lastpage,\@kernel@before@shipout@foreground}
-%
+%
+%
+% \begin{macro}{\@@_saved_protect:}
+% Remeber the current \cs{protect} state.
+% \begin{macrocode}
+\cs_new_eq:NN \@@_saved_protect: \protect
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{shipout/before,
+% shipout/foreground,shipout/background,
+% shipout/firstpage,
+% shipout/lastpage}
+% Declaring all hooks for the shipout code.
+% \begin{macrocode}
+\hook_new:n{shipout/before}
+\hook_new:n{shipout/foreground}
+\hook_new:n{shipout/background}
+\hook_new:n{shipout/firstpage}
+\hook_new:n{shipout/lastpage}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\@kernel@after@shipout@lastpage,
+% \@kernel@before@shipout@background}
+% And here are the internal kernel hooks going before or after the
+% public ones where needed.
% \begin{macrocode}
\let\@kernel@after@shipout@lastpage\@empty
-\let\@kernel@before@shipout@foreground\@empty
+\let\@kernel@before@shipout@background\@empty
% \end{macrocode}
% \end{macro}
-
-
+%
+%
% \begin{macro}{\@@_execute_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
@@ -750,15 +802,15 @@
% \begin{macrocode}
\cs_gset_eq:NN \@@_execute_firstpage_hook: \prg_do_nothing:
\cs_gset:Npn \@@_add_firstpage_material:Nn ##1 ##2 {
- \PackageWarning{ltshipout}{
+ \@latex@warning{
First~ page~ is~ already~ shipped~ out,~ ignoring\MessageBreak
\string##1 }
}
}
% \end{macrocode}
% \end{macro}
-
-
+%
+%
% \begin{macro}{\g_@@_lastpage_handled_bool}
% A boolean to signal if we have already handled the
% \hook{shipout/lastpage} hook.
@@ -766,9 +818,9 @@
\bool_new:N \g_@@_lastpage_handled_bool
% \end{macrocode}
% \end{macro}
-
-
-
+%
+%
+%
% \begin{macro}{\@@_add_firstpage_material:Nn}
% This command adds material to the
% \hook{shipout/firstpage} hook. It is used in
@@ -782,13 +834,13 @@
}
% \end{macrocode}
% \end{macro}
-
-
-
-
-
-
-
+%
+%
+%
+%
+%
+%
+%
% \begin{macro}{\@@_get_box_size:N}
% Store the box dimensions in dimen registers.
% \fmi{This could/should perhaps be generalized to set height depth and
@@ -803,7 +855,7 @@
}
% \end{macrocode}
% \end{macro}
-
+%
% \begin{macro}{\l_shipout_box_ht_dim,
% \l_shipout_box_dp_dim,\l_shipout_box_wd_dim,
% \l_shipout_box_ht_plus_dp_dim}
@@ -815,20 +867,20 @@
\dim_new:N \l_shipout_box_ht_plus_dp_dim
% \end{macrocode}
% \end{macro}
-
-
-
-
-
+%
+%
+%
+%
+%
% \begin{macro}{\g_@@_discard_bool}
% Indicate whether or not the current page box should be discarded
% \begin{macrocode}
\bool_new:N \g_@@_discard_bool
% \end{macrocode}
% \end{macro}
-
-
-
+%
+%
+%
% \begin{macro}{\l_@@_tmp_box,\l_@@_saved_badness_tl}
% We need a box for the background and foreground material and a
% token register to remember badness settings as we disable them
@@ -838,8 +890,8 @@
\tl_new:N \l_@@_saved_badness_tl
% \end{macrocode}
% \end{macro}
-
-
+%
+%
% \begin{macro}{\@@_add_background_box:n}
% In standard \LaTeX{} the shipout box is always a \cs{vbox} but
% here we are allow for other usage as well, in case some package
@@ -930,10 +982,10 @@
}
% \end{macrocode}
% \end{macro}
-
-
-
-
+%
+%
+%
+%
% \begin{macro}{\@@_add_foreground_box:n}
% Foreground boxes are done in the same way, only the order and
% placement of boxes has to be done differently.
@@ -993,17 +1045,21 @@
}
% \end{macrocode}
% \end{macro}
-
-
-
-
-% \begin{macro}{\c_@@_horigin_tl,\c_@@_vorigin_tl}
+%
+%
+%
+%
+% \begin{macro}{\@@_init_page_origins:,\c_@@_horigin_tl,\c_@@_vorigin_tl}
% Two constants holding the offset of the top-left with respect to
% the media box.
%
% Setting the constants this way is courtesy of Bruno.
+%
+% We delay setting the constants to the last possible place as
+% there might be updates in the preamble or even in the
+% \hook{begindocument} hook that affects their setup.
% \begin{macrocode}
-\tl_gput_right:Nn \@kernel@after@begindocument {
+\cs_new:Npn \@@_init_page_origins: {
\tl_const:Nx \c_@@_horigin_tl
{
\cs_if_exist_use:NTF \pdfvariable { horigin }
@@ -1014,11 +1070,17 @@
\cs_if_exist_use:NTF \pdfvariable { vorigin }
{ \cs_if_exist_use:NF \pdfvorigin { 1in } }
}
+% \end{macrocode}
+% After the constants have been set there is no need to execute
+% this command again, in fact it would raise an error, so we
+% redefine it to do nothing.
+% \begin{macrocode}
+ \cs_gset_eq:NN \@@_init_page_origins: \prg_do_nothing:
}
% \end{macrocode}
% \end{macro}
-
-
+%
+%
% \begin{macro}{\@@_picture_overlay:n}
% Put the argument into a \texttt{picture} environment that doesn't take up
% any size and uses \texttt{1pt} for \cs{unitlength}.
@@ -1026,6 +1088,14 @@
% not it is not.}
% \begin{macrocode}
\cs_new:Npn \@@_picture_overlay:n #1 {
+% \end{macrocode}
+% The very first time this is executed we have ot initializes (and
+% freeze) the origins.
+% \begin{macrocode}
+ \@@_init_page_origins:
+% \end{macrocode}
+%
+% \begin{macrocode}
\kern -\c_@@_horigin_tl \scan_stop:
\vbox_to_zero:n {
\kern -\c_@@_vorigin_tl \scan_stop:
@@ -1040,20 +1110,21 @@
}
% \end{macrocode}
% \end{macro}
-
-
+%
+%
% \begin{macro}{\@@_add_background_picture:n}
% Put a \texttt{picture} env in the background of the shipout box
% with its reference point in the top-left corner.
+%
% \begin{macrocode}
\cs_new:Npn \@@_add_background_picture:n #1 {
\@@_add_background_box:n { \@@_picture_overlay:n {#1} }
}
% \end{macrocode}
% \end{macro}
-
-
-
+%
+%
+%
% \begin{macro}{\@@_add_foreground_picture:n}
%
% Put a \texttt{picture} env in the foreground of the shipout box
@@ -1064,8 +1135,8 @@
}
% \end{macrocode}
% \end{macro}
-
-
+%
+%
% \begin{macro}{\shipout_discard:}
% Request that the next shipout box should be discarded. At the
% moment this is just setting a boolean, but we may want to augment
@@ -1078,18 +1149,18 @@
}
% \end{macrocode}
% \end{macro}
-
-
-
-
+%
+%
+%
+%
% \subsection{Handling the end of job hook}
-
+%
% At the moment this is partly solved by using the existing hooks.
% But rather than putting the code into these hooks it should be
% moved to the right place directly as we shouldn't prefill hooks
% with material unless it needs to interact with other code.
%
-
+%
%
% \begin{macro}{\g_shipout_readonly_int,\ReadonlyShipoutCounter}
% We count every shipout activity that makes a page (but not those
@@ -1103,7 +1174,7 @@
\cs_new_eq:NN \ReadonlyShipoutCounter \g_shipout_readonly_int
% \end{macrocode}
% \end{macro}
-
+%
% \begin{macro}{\g_shipout_totalpages_int,\c@totalpages}
% We count every shipout attempt (even those that are discarded) in
% tis counter. It is not used in the code but may get used in user
@@ -1120,15 +1191,15 @@
% \end{macrocode}
% \end{macro}
%
-
-
-
+%
+%
+%
% \begin{macro}{\@abspage@last}
% In \cs{@abspage@last} record the number of pages from the last
% run. This is written to the \texttt{.aux} and this way made
% available to the next run. In case there is no \texttt{.aux} file
% or the statement is missing from it we initialize it with the
-% largest possible number in \TeX{}. We use this a s the default
+% largest possible number in \TeX{}. We use this as the default
% because then we are inserting the \hook{shipout/lastpage} on
% the last page (or after the last page but not on page 1 for a
% multipage document.
@@ -1136,8 +1207,8 @@
\xdef\@abspage@last{\number\maxdimen}
% \end{macrocode}
% \end{macro}
-
-
+%
+%
% \begin{macro}{\enddocument}
%
% Instead of using the hooks \hook{enddocument} and
@@ -1188,7 +1259,7 @@
{
% \end{macrocode}
% This ends up in the \texttt{.aux} so we use \LaTeXe{} names here.
-% \fmi{this needs an interface for \cs{nofiles} in expl3, doesn't at the moment!}
+% \fmi{This needs an interface for \cs{nofiles} in expl3, doesn't at the moment!}
% \begin{macrocode}
\if@filesw
\iow_now:Nx \@auxout {
@@ -1202,32 +1273,47 @@
% run but helps to keep pdf viewers happy.
% \begin{macrocode}
\bool_if:NF \g_@@_lastpage_handled_bool
- { \tex_shipout:D\vbox to\textheight{
- \hbox{\UseHook{shipout/lastpage} \@kernel@after@shipout@lastpage }
+ {
+% \end{macrocode}
+% However, making this extra page in case the hook is actually
+% empty would be forcing a rerun without any reason, so we check
+% that condition and also check if
+% \cs{@kernel@after@shipout@lastpage} contains any code. If both
+% are empty we omit the page generation.
+% \begin{macrocode}
+ \bool_lazy_and:nnF
+ { \hook_if_empty_p:n {shipout/lastpage} }
+ { \tl_if_empty_p:N \@kernel@after@shipout@lastpage }
+ {
+ \tex_shipout:D\vbox to\textheight
+ {
+ \hbox:n { \UseHook{shipout/lastpage}
+ \@kernel@after@shipout@lastpage }
% \end{macrocode}
% This extra page could be totally empty except for the hook
% content, but to help the user understanding why it is there we
% put some text into it.
% \begin{macrocode}
- \@@_excuse_extra_page:
- \null
- }
+ \@@_excuse_extra_page:
+ \null
+ }
% \end{macrocode}
-% At this point we should also signal to \LaTeX{} that a rerun is
+% At this point we also signal to \LaTeX{}'s endgame that a rerun is
% necessary so that an appropriate message can be shown on the
-% terminal.
-%
-% \fmi{integrate warning ``Rerun \ldots'' }
+% terminal. We do this by simply defining a command used as a flag and
+% tested \cs{enddocument}.
% \begin{macrocode}
- }
- }
+ \cs_gset_eq:NN \@extra@page@added \relax
+ }
+ }
+ }
}
% \end{macrocode}
% \end{macro}
% \end{macro}
-
-
-
+%
+%
+%
% \begin{macro}{\@@_excuse_extra_page:}
% Say mea culpa \ldots
% \begin{macrocode}
@@ -1248,178 +1334,401 @@
}
% \end{macrocode}
% \end{macro}
-
-
-
-
+%
+%
+% \begin{macro}{\PreviousTotalPages,\@kernel@before@begindocument}
+% In the preamble before the \texttt{aux} file was read
+% \cs{PreviousTotalPages} is always zero.
+% \begin{macrocode}
+\def\PreviousTotalPages{0}
+% \end{macrocode}
+% In the \texttt{aux} file there should be an update for
+% \cs{@abspage@last} recording the number of pages from the
+% previous run. If not that macro holds the value of
+% \cs{maxdimen}. So we test for it and update
+% \cs{PreviousTotalPages} if there was a real value. This should
+% happen just before the \hook{begindocument} hook is executed so
+% that the value can be used inside that hook.
+% \begin{macrocode}
+\g@addto@macro\@kernel@before@begindocument
+ {\ifnum\@abspage@last<\maxdimen
+ \xdef\PreviousTotalPages{\@abspage@last}\fi}
+% \end{macrocode}
+% \end{macro}
+%
+%
% \section{Legacy \LaTeXe{} interfaces}
-
-
-
+%
+%
+%
% \begin{macro}{\DiscardShipoutBox}
% Request that the next shipout box is to be discarded.
% \begin{macrocode}
\cs_new_eq:NN \DiscardShipoutBox \shipout_discard:
% \end{macrocode}
% \end{macro}
-
-
+%
+%
% \begin{macro}{\AtBeginDvi}
%
% \begin{macrocode}
-\renewcommand \AtBeginDvi {\@@_add_firstpage_material:Nn \AtBeginDvi}
+\DeclareRobustCommand \AtBeginDvi {\@@_add_firstpage_material:Nn \AtBeginDvi}
% \end{macrocode}
% \end{macro}
-
-
-% \begin{macro}{\DebugShipoutOn,\DebugShipoutOff}
+%
+%
+% \begin{macro}{\DebugShipoutsOn,\DebugShipoutsOff}
%
% \begin{macrocode}
-\cs_new_eq:NN \DebugShipoutOn \shipout_debug_on:
-\cs_new_eq:NN \DebugShipoutOff \shipout_debug_off:
+\cs_new_eq:NN \DebugShipoutsOn \shipout_debug_on:
+\cs_new_eq:NN \DebugShipoutsOff \shipout_debug_off:
% \end{macrocode}
% \end{macro}
-
-
-
-
-
+%
+%
+% \section{Internal commands needed elsewhere}
+%
+% These internal commands use double and triple \texttt{@} signs so
+% we need to stop getting them translated to the module name.
+% \begin{macrocode}
+%<@@=>
+% \end{macrocode}
+%
+% \begin{macro}{\@expl@@@shipout@add@firstpage@material@@Nn,
+% \@expl@@@shipout@add@background@box@@n,
+% \@expl@@@shipout@add@foreground@box@@n,
+% \@expl@@@shipout@add@background@picture@@n,
+% \@expl@@@shipout@add@foreground@picture@@n}
+% Some internals needed elsewhere.
+%
+% \begin{macrocode}
+\cs_set_eq:NN \@expl@@@shipout@add@firstpage@material@@Nn
+ \__shipout_add_firstpage_material:Nn
+% \end{macrocode}
+%
+% \begin{macrocode}
+\cs_set_eq:NN \@expl@@@shipout@add@background@box@@n
+ \__shipout_add_background_box:n
+% \end{macrocode}
+%
+% \begin{macrocode}
+\cs_set_eq:NN \@expl@@@shipout@add@foreground@box@@n
+ \__shipout_add_foreground_box:n
+% \end{macrocode}
+%
+% \begin{macrocode}
+\cs_set_eq:NN \@expl@@@shipout@add@background@picture@@n
+ \__shipout_add_background_picture:n
+% \end{macrocode}
+%
+% \begin{macrocode}
+\cs_set_eq:NN \@expl@@@shipout@add@foreground@picture@@n
+ \__shipout_add_foreground_picture:n
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+\ExplSyntaxOff
+%</2ekernel|latexrelease>
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+%
+% Rolling back here doesn't undefine the interface commands as they
+% may be used in packages without rollback functionality. So we
+% just make them do nothing which may or may not work depending on
+% the code usage.
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{0000/00/00}%
+%<latexrelease> {\shipout}{The hook management (shipout)}%
+%<latexrelease>\expandafter\let\expandafter\shipout\csname tex_shipout:D\endcsname
+%<latexrelease>
+%<latexrelease>\let \ShipoutBox\@undefined
+%<latexrelease>\let \ReadonlyShipoutCounter \@undefined
+%<latexrelease>\let \c@totalpages \@undefined
+%<latexrelease>\let \thetotalpages \@undefined
+%<latexrelease>
+%<latexrelease>\let \DiscardShipoutBox \@undefined
+%<latexrelease>\let \DebugShipoutsOn \@undefined
+%<latexrelease>\let \DebugShipoutsOff \@undefined
+%<latexrelease>
+%<latexrelease>\DeclareRobustCommand \AtBeginDvi [1]{%
+%<latexrelease> \global \setbox \@begindvibox
+%<latexrelease> \vbox{\unvbox \@begindvibox #1}%
+%<latexrelease>}
+%<latexrelease>
+%<latexrelease>\let \AtBeginShipout \@undefined
+%<latexrelease>\let \AtBeginShipoutNext \@undefined
+%<latexrelease>
+%<latexrelease>\let \AtBeginShipoutFirst \@undefined
+%<latexrelease>
+%<latexrelease>\let \ShipoutBoxHeight \@undefined
+%<latexrelease>\let \ShipoutBoxDepth \@undefined
+%<latexrelease>\let \ShipoutBoxWidth \@undefined
+%<latexrelease>
+%<latexrelease>\let \AtBeginShipoutDiscard \@undefined
+%<latexrelease>
+%<latexrelease>\let \AtBeginShipoutAddToBox \@undefined
+%<latexrelease>\let \AtBeginShipoutAddToBoxForeground \@undefined
+%<latexrelease>\let \AtBeginShipoutUpperLeft \@undefined
+%<latexrelease>\let \AtBeginShipoutUpperLeftForeground \@undefined
+%<latexrelease>
+%<latexrelease>
+% \end{macrocode}
+% We do not undo a substitution when rolling back. As the file
+% support gets undone the underlying data is no longer used (and
+% sufficiently obscure that should not interfer with existing
+% commands) and properly removing it would mean we need to make the
+% \cs{unclare@...} and its support macros available in all earlier
+% kernel releases which is pointless (and actually worse).
+% \begin{macrocode}
+%\undeclare@file@substitution{everyshi.sty}{everyshi-ltx.sty}
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>
+%<latexrelease>\let \AtEndDvi \@undefined
+% \end{macrocode}
+% We do not reenable a disabled package load when rolling back. As the file
+% support gets undone the underlying data is no longer checked (and
+% sufficiently obscure that it should not interfer with existing
+% commands) and properly removing it would mean we need to make the
+% \cs{reenable@package@load} command available in all earlier
+% kernel releases which is pointless (and actually worse).
+% \begin{macrocode}
+%\reenable@package@load{atenddvi}
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>
+%<latexrelease>\EndIncludeInRelease
+%<*2ekernel>
+% \end{macrocode}
+%
+%
+%
+%
% \section{Package emulation for compatibility}
-
-
+%
+%
+% \subsection{Package \pkg{atenddvi} emulation}
+%
+%
+% \begin{macro}{\AtEndDvi}
+% This package has only one public command to simulating it is easy
+% and actually sensible to provide as part of the kernel.
+% \begin{macrocode}
+%</2ekernel>
+%<*2ekernel|latexrelease>
+%<latexrelease>\IncludeInRelease{2020/10/01}%
+%<latexrelease> {\AtEndDvi}{atenddvi emulation}%
+\ExplSyntaxOn
+\cs_new:Npn \AtEndDvi {\AddToHook{shipout/lastpage}}
+\ExplSyntaxOff
+% \end{macrocode}
+% As the package is integrate we prevent loading (no need to roll that back):
+% \begin{macrocode}
+\disable@package@load{atenddvi}
+ {\PackageWarning{atenddvi}
+ {Functionality of this package is already\MessageBreak
+ provided by LaTeX.\MessageBreak\MessageBreak
+ It is there no longer necessary to load it\MessageBreak
+ and you can safely remove it.\MessageBreak
+ Found on}}
+% \end{macrocode}
+%
+% \begin{macrocode}
+%</2ekernel|latexrelease>
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{0000/00/00}%
+%<latexrelease> {\AtEndDvi}{atenddvi emulation}%
+%<latexrelease>\let \AtEndDvi \@undefined
+%<latexrelease>\EndIncludeInRelease
+%<*2ekernel>
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macrocode}
+%</2ekernel>
+% \end{macrocode}
+%
+%
% \subsection{Package \pkg{atbegshi} emulation}
-
+%
+%
+%
+%
+%
+% \begin{macrocode}
+%<*atbegshi-ltx>
+\ProvidesPackage{atbegshi}
+ [2020/08/17 v1.0a
+ Emulation of the original atbegshi package^^Jwith kernel methods]
+% \end{macrocode}
+%
+%
% \begin{macro}{\AtBeginShipoutBox}
% \begin{macrocode}
-\cs_new_eq:NN \AtBeginShipoutBox \ShipoutBox
+\let \AtBeginShipoutBox \ShipoutBox
% \end{macrocode}
% \end{macro}
-
-
-
+%
+%
% \begin{macro}{\AtBeginShipoutInit}
% Compatibility only, we aren't delaying \ldots
% \begin{macrocode}
-\cs_set_eq:NN\AtBeginShipoutInit\@empty
+\let \AtBeginShipoutInit \@empty
% \end{macrocode}
% \end{macro}
-
-
-
+%
+%
% \begin{macro}{\AtBeginShipout,\AtBeginShipoutNext}
% Filling hooks
% \begin{macrocode}
-\newcommand\AtBeginShipout {\AddToHook{shipout/before}}
-\newcommand\AtBeginShipoutNext {\AddToHookNext{shipout/before}}
+\def \AtBeginShipout {\AddToHook{shipout/before}}
+\def \AtBeginShipoutNext {\AddToHookNext{shipout/before}}
% \end{macrocode}
% \end{macro}
-
-
-
+%
+%
% \begin{macro}{\AtBeginShipoutFirst}
% Slightly more complex as we need to know the name of the command under which the
% \hook{shipout/firstpage} hook is filled.
% \begin{macrocode}
-\newcommand\AtBeginShipoutFirst{\@@_add_firstpage_material:Nn \AtBeginShipoutFirst}
+\def \AtBeginShipoutFirst
+ {\@expl@@@shipout@add@firstpage@material@@Nn \AtBeginShipoutFirst}
% \end{macrocode}
% \end{macro}
-
-
-
-% This is somewhat different from the original where
-% \cs{ShipoutBoxHeight} etc.\ only holds the \verb=\the\ht<box>= value. This
-% may has some implications in some use cases and if that is a problem
-% then it might need changing.
-%
-% \begin{macrocode}
-\cs_new:Npn \ShipoutBoxHeight { \dim_use:N \l_shipout_box_ht_dim }
-\cs_new:Npn \ShipoutBoxDepth { \dim_use:N \l_shipout_box_dp_dim }
-\cs_new:Npn \ShipoutBoxWidth { \dim_use:N \l_shipout_box_wd_dim }
-% \end{macrocode}
-
-
+%
+%
% \begin{macro}{\AtBeginShipoutDiscard}
% Just a different name.
% \begin{macrocode}
-\cs_new_eq:NN \AtBeginShipoutDiscard \DiscardShipoutBox
+\let \AtBeginShipoutDiscard \DiscardShipoutBox
% \end{macrocode}
% \end{macro}
-
-
+%
+%
% \begin{macro}{\AtBeginShipoutAddToBox,\AtBeginShipoutAddToBoxForeground,
% \AtBeginShipoutUpperLeft,\AtBeginShipoutUpperLeftForeground}
% We don't expose them.
% \begin{macrocode}
-\cs_new_eq:NN \AtBeginShipoutAddToBox \@@_add_background_box:n
-\cs_new_eq:NN \AtBeginShipoutAddToBoxForeground \@@_add_foreground_box:n
+\let \AtBeginShipoutAddToBox
+ \@expl@@@shipout@add@background@box@@n
+\let \AtBeginShipoutAddToBoxForeground
+ \@expl@@@shipout@add@foreground@box@@n
% \end{macrocode}
%
% \begin{macrocode}
-\cs_new_eq:NN\AtBeginShipoutUpperLeft \@@_add_background_picture:n
-\cs_new_eq:NN\AtBeginShipoutUpperLeftForeground \@@_add_foreground_picture:n
+\let \AtBeginShipoutUpperLeft
+ \@expl@@@shipout@add@background@picture@@n
+\let \AtBeginShipoutUpperLeftForeground
+ \@expl@@@shipout@add@foreground@picture@@n
% \end{macrocode}
% \end{macro}
-
%
%
-% We prevent the package \pkg{atbegshi} from loading:
+%
+% \begin{macro}{\ShipoutBoxHeight,\ShipoutBoxWidth,\ShipoutoBoxDepth}
+% This is somewhat different from the original in \pkg{atbegshi}
+% where \cs{ShipoutBoxHeight} etc.\ only holds the
+% \verb=\the\ht<box>= value. This may has some implications in some
+% use cases and if that is a problem then it might need changing.
% \begin{macrocode}
-\expandafter\cs_set_eq:NN\csname ver@atbegshi.sty\endcsname\fmtversion
+\ExplSyntaxOn
+\cs_new:Npn \ShipoutBoxHeight { \dim_use:N \l_shipout_box_ht_dim }
+\cs_new:Npn \ShipoutBoxDepth { \dim_use:N \l_shipout_box_dp_dim }
+\cs_new:Npn \ShipoutBoxWidth { \dim_use:N \l_shipout_box_wd_dim }
+\ExplSyntaxOff
% \end{macrocode}
-% \pkg{hyperref} code (and \pkg{ltxcmds}) doesn't understand 2020-10-01
-% and thinks it is before 1994, so for now \ldots
+% \end{macro}
+%
+%
% \begin{macrocode}
-\@namedef {ver@atbegshi.sty}{2020/10/01}
+%</atbegshi-ltx>
% \end{macrocode}
-
-
-
-% \subsection{Package \pkg{everyshi} emulation}
%
-% \begin{macro}{\EveryShipout,\AtNextShipout}
-% This package has only two public commands to simulating it is easy:
+% If the package is requested we substitute the one above:
% \begin{macrocode}
-\cs_new_eq:NN\EveryShipout\AtBeginShipout
-\cs_new_eq:NN\AtNextShipout\AtBeginShipoutNext
+%<*2ekernel>
+\declare@file@substitution{atbegshi.sty}{atbegshi-ltx.sty}
+%</2ekernel>
% \end{macrocode}
-% \end{macro}
+%
+%
+%
+%
+%
+%
+% \subsection{Package \pkg{everyshi} emulation}
%
% \begin{macrocode}
-\expandafter\cs_set_eq:NN\csname ver@everyshi.sty\endcsname\fmtversion
-\@namedef {ver@everyshi.sty}{2020/10/01}
+%<*everyshi-ltx>
% \end{macrocode}
-
-
-
-% \subsection{Package \pkg{atenddvi} emulation}
%
-% \begin{macro}{\AtEndDvi}
-% This package has only one public command to simulating it is easy:
% \begin{macrocode}
-\cs_new:Npn \AtEndDvi {\AddToHook{shipout/lastpage}}
+\ProvidesPackage{everyshi}
+ [2020/08/17 v1.0a
+ Emulation of the original everyshi package^^Jwith kernel methods]
+% \end{macrocode}
+%
+% \begin{macro}{\EveryShipout,\AtNextShipout}
+% This package has only two public commands so simulating it is easy:
+% \begin{macrocode}
+\def \EveryShipout {\AddToHook{shipout/before}}
+\def \AtNextShipout {\AddToHookNext{shipout/before}}
% \end{macrocode}
% \end{macro}
%
+% \begin{macrocode}
+% This is one difference between \pkg{everyshi} and the kernel
+% implementation, the latter does not directly use box 255.
+%
+% For usage by ordinary users this makes no difference but of a
+% package use complicated code together with \pkg{everyshi} and
+% directly manipulates box 255 then this package needs updating.
+% In most cases the updates are simple because the kernel offers
+% hooks that makes such complicated code unnecessary.
%
+% We therefore add a little file into the adjusted package
% \begin{macrocode}
-\expandafter\cs_set_eq:NN\csname ver@atenddvi.sty\endcsname\fmtversion
-\@namedef {ver@atenddvi.sty}{2020/10/01}
+%%
+%% In normal circumstances the above emulation is sufficient and in
+%% all known packages (we know of) that use everyshi it either works or
+%% the packages have been adjusted.
+%%
+%% Code that directly manipulates box 255, however, might fail.
+%% If that is the case look at the shipout hooks offered now as
+%% they are normally sufficienct to avoid such minpulations (or
+%% replace box 255 with \ShipoutBox in the code.
+%%
+%</everyshi-ltx>
% \end{macrocode}
-
-
-
-
+%
+%
+% If the package is requested we substitute the one above:
% \begin{macrocode}
-\ExplSyntaxOff
+%<*2ekernel>
+\declare@file@substitution{everyshi.sty}{everyshi-ltx.sty}
%</2ekernel>
% \end{macrocode}
-
+%
+%
+% Rather important :-)
+% \begin{macrocode}
+%<@@=>
+% \end{macrocode}
+%
% \Finale
%
-
-
+%
+%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\endinput
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-