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.dtx160
1 files changed, 117 insertions, 43 deletions
diff --git a/macros/latex-dev/base/ltshipout.dtx b/macros/latex-dev/base/ltshipout.dtx
index 8f0422c887..2ea0a1b665 100644
--- a/macros/latex-dev/base/ltshipout.dtx
+++ b/macros/latex-dev/base/ltshipout.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%%
-%% File: ltshipout.dtx (C) Copyright 2020 Frank Mittelbach, LaTeX Team
+%% File: ltshipout.dtx (C) Copyright 2020,2021 Frank Mittelbach, LaTeX Team
%%
%
% This file is part of the LaTeX base system.
@@ -31,8 +31,8 @@
%%% From File: ltshipout.dtx
%
% \begin{macrocode}
-\providecommand\ltshipoutversion{v1.0c}
-\providecommand\ltshipoutdate{2020/09/27}
+\providecommand\ltshipoutversion{v1.0d}
+\providecommand\ltshipoutdate{2020/12/06}
% \end{macrocode}
%
%<*driver>
@@ -75,7 +75,7 @@
% \ltshipoutversion\ dated \ltshipoutdate, \copyright\ \LaTeX\
% Project.}}
%
-% \author{Frank Mittelbach}
+% \author{Frank Mittelbach, \LaTeX{} Project Team}
%
% \maketitle
%
@@ -193,7 +193,8 @@
% \item[\hook{shipout/lastpage}]
%
% The corresponding hook to add \cs{special}s at the very end of
-% the output file. It is only executed on the very last page ---
+% the output file. It is only executed on the very last page of
+% the output file ---
% or rather on the page that \LaTeX{} believes is the last one.
%
% It may not be possible for \LaTeX{} to correctly determine
@@ -229,19 +230,29 @@
% \cs{typeout}s, none of the hooks are executed (as there is no
% \cs{shipout}) not even the \hook{shipout/lastpage} hook.
%
+%
+% \subsection{Legacy \LaTeX{} commands}
+%
+%
% \begin{function}{\AtBeginDvi,\AtEndDvi}
% \cs{AtBeginDvi} is the existing \LaTeXe{} interface to fill the
% \hook{shipout/firstpage} hook. This is not really a good name
% as it is not just supporting \texttt{.dvi} but also \texttt{.pdf}
-% output or \texttt{.dvx}.
+% output or \texttt{.xdv}.
%
% \cs{AtEndDvi} is the counterpart that was not available in the
% kernel but only through the package \pkg{atenddvi}. It fills the
% \hook{shipout/lastpage} hook.
+% \end{function}
%
-% \fmi{better names? Any suggestions?}
+% As these two wrappers have been available for a long time we
+% continue offering them. However, for new code we suggest using
+% the high-level hook management commands directly instead of
+% ``randomly-named'' wrappers. This will lead to code that is
+% easier to understand and to maintain. For this reason we do not
+% provide any other wrapper commands for the above hooks in the
+% kernel.
%
-% \end{function}
%
% \subsection{Special commands for use inside the hooks}
%
@@ -331,9 +342,9 @@
% \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
+% previous run. If there was no previous run or if used in the
% preamble it expands to
-% \texttt{0}. Note that this is a command to a counter, so in order
+% \texttt{0}. Note that this is a command and not 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}
@@ -356,9 +367,15 @@
%
% \section{Emulating commands from other packages}
%
-% The packages in this section are no longer necessary but as they
-% are used in other packages they are emulated when they are loaded
-% via \cs{usepackage} or \cs{RequirePackage}.
+% The packages in this section are no longer necessary, but as they
+% are used by other packages, they are emulated when they are
+% explicitly loaded with \cs{usepackage} or \cs{RequirePackage}.
+%
+% Please note that the emulation only happens if the package is
+% explicitly requested, i.e., the commands documented below are not
+% automatically available in the \LaTeX{} kernel! If you write a
+% new package we suggest to use the appropriate kernel hooks
+% directly instead of loading the emulation.
%
%
% \subsection{Emulating \pkg{atbegshi}}
@@ -434,6 +451,13 @@
%
% \subsection{Emulating \pkg{everyshi}}
%
+% The \pkg{everyshi} package is providing commands to run arbitrary
+% code just before the shipout starts.
+% One point of difference: in the new shipout hooks the page is
+% available as \cs{ShipoutBox} for inspection of change, one should
+% not manipulate box 255 directly inside \hook{shipout/before}, so
+% old code doing this would change to use \cs{ShipoutBox} instead
+% of \texttt{255} or \cs{@cclv}.
%
% \begin{function}{\EveryShipout}
% \begin{syntax}
@@ -447,22 +471,49 @@
% \end{syntax}
% \end{function}
%
+% However, most use cases for \pkg{everyshi} are attempts to put
+% some picture or text into the background or foreground of the page
+% and that can be done today simply by using the
+% \hook{shipout/background} and
+% \hook{shipout/foreground} hooks without any need to coding.
%
%
% \subsection{Emulating \pkg{atenddvi}}
%
-% The \pkg{atenddvi} package implemented only a single command:
-% \cs{AtEndDvi} and that is now available out of the box.
+% The \pkg{atenddvi} package implemented only a single command:
+% \cs{AtEndDvi} and that is now available out of the box so the
+% emulation makes the package a no-op.
%
%
%
% \subsection{Emulating \pkg{everypage}}
%
-% This page takes over the original \cs{@begindvi} hook and replaces
-% it. It should be all covered by the hooks offered here (details
-% need checking) and thus could simply use the provided hooks
-% rather than defining its own.
+% This package patched the original \cs{@begindvi} hook and replaced
+% it with its own version.
+% Its functionality is now covered by the hooks offered by the
+% kernel so that there is no need for such patching any longer.
%
+% \begin{function}{\AddEverypageHook}
+% \begin{syntax}
+% \cs{AddEverypageHook}\Arg{code} $\equiv$
+% \qquad\cs{AddToHook}\texttt{\{shipout/background\}\{\cs{put}(1in,-1in)\Arg{code}\}}
+% \end{syntax}
+% \cs{AddEverypageHook} is adding something into the
+% background of every page at a position of 1in to the right and
+% 1in down from the top left corner of the page.
+% By using the kernel hook directly you can put your material
+% directly to the right place, i.e., use other coordinates in the
+% \cs{put} statement above.
+% \end{function}
+%
+% \begin{function}{\AddThispageHook}
+% \begin{syntax}
+% \cs{AddThispageHook}\Arg{code} $\equiv$
+% \qquad\cs{AddToHookNext}\texttt{\{shipout/background\}\{\cs{put}(1in,-1in)\Arg{code}\}}
+% \end{syntax}
+% The \cs{AddThispageHook} wrapper is similar but uses
+% \cs{AddToHookNext}.
+% \end{function}
%
%
% \StopEventually{\setlength\IndexMin{200pt} \PrintIndex }
@@ -479,7 +530,7 @@
% \begin{macrocode}
%<*2ekernel|latexrelease>
%<latexrelease>\IncludeInRelease{2020/10/01}%
-%<latexrelease> {\shipout}{Hook mangement (shipout)}%
+%<latexrelease> {\shipout}{Hook management (shipout)}%
% \end{macrocode}
%
%
@@ -631,7 +682,8 @@
% \cs{shipout}.
%
% We increment it after running the above hook so that the values
-% for \cs{g_shipout_totalpages_int} and \cs{} are in sync while the
+% for \cs{g_shipout_totalpages_int} and \cs{g_shipout_readonly_int}
+% are in sync while the
% hook is executed (in the case that totalpages isn't manually
% altered or through discarding pages that is).
% \begin{macrocode}
@@ -699,7 +751,13 @@
\hook_if_empty:nF {shipout/foreground}
{ \@@_add_foreground_picture:n
{ \hook_use:n {shipout/foreground} } }
- \hook_if_empty:nF {shipout/background}
+% \end{macrocode}
+% If there is no user hook, there might still code in the kernel hook.
+% \changes{v1.0d}{2020/11/23}{Check for both kernel and user hook (gh/431)}
+% \begin{macrocode}
+ \bool_lazy_and:nnF
+ { \hook_if_empty_p:n {shipout/background} }
+ { \tl_if_empty_p:N \@kernel@before@shipout@background }
{ \@@_add_background_picture:n
{ \@kernel@before@shipout@background
\hook_use:n {shipout/background} } }
@@ -712,11 +770,15 @@
\@@_execute_firstpage_hook:
% \end{macrocode}
% The 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
% all but one (and hopefully the correct) page.
+% \changes{v1.0d}{2020/11/23}{Check for both kernel and user hook (gh/431)}
% \begin{macrocode}
\int_compare:nNnT \@abspage@last = \g_shipout_readonly_int
- { \hook_if_empty:nF {shipout/lastpage}
+ { \bool_lazy_and:nnF
+ { \hook_if_empty_p:n {shipout/lastpage} }
+ { \tl_if_empty_p:N \@kernel@after@shipout@lastpage }
{ \@@_debug:n { \typeout{Executing~ lastpage~ hook~
on~ page~ \int_use:N \g_shipout_readonly_int } }
\_@@_add_foreground_box:n { \UseHook{shipout/lastpage}
@@ -747,7 +809,7 @@
%
%
% \begin{macro}{\@@_saved_protect:}
-% Remeber the current \cs{protect} state.
+% Remember the current \cs{protect} state.
% \begin{macrocode}
\cs_new_eq:NN \@@_saved_protect: \protect
% \end{macrocode}
@@ -883,7 +945,7 @@
% \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
-% during te buildup below.
+% during the buildup below.
% \begin{macrocode}
\box_new:N \l_@@_tmp_box
\tl_new:N \l_@@_saved_badness_tl
@@ -1088,7 +1150,7 @@
% \begin{macrocode}
\cs_new:Npn \@@_picture_overlay:n #1 {
% \end{macrocode}
-% The very first time this is executed we have to initializes (and
+% The very first time this is executed we have to initialize (and
% freeze) the origins.
% \begin{macrocode}
\@@_init_page_origins:
@@ -1183,7 +1245,7 @@
%
% \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
+% this counter. It is not used in the code but may get used in user
% code.
% \begin{macrocode}
\int_new:N \g_shipout_totalpages_int
@@ -1207,7 +1269,7 @@
% or the statement is missing from it we initialize it with the
% 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
+% the last page (or after the last page) but not on page 1 for a
% multipage document.
% \begin{macrocode}
\xdef\@abspage@last{\number\maxdimen}
@@ -1219,11 +1281,11 @@
%
% Instead of using the hooks \hook{enddocument} and
% \hook{enddocument/afterlastpage} we add this code to private
-% kernel hooks to be 100\% when it is executed and to avoid
+% kernel hooks to be 100\% sure when it is executed and to avoid
% cluttering the hooks with data that is always there.
%
% Inside \cs{enddocument} there is a \cs{clearpage}. Just before
-% that we execute this code here. There is a good change that we
+% that we execute this code here. There is a good chance that we
% are on the last page. Therefore, if we don't know the value from
% the last run, we assume that the current page is the right
% one. So we set \cs{@abspage@last} and as a result the next
@@ -1307,7 +1369,7 @@
% 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. We do this by simply defining a command used as a flag and
-% tested \cs{enddocument}.
+% tested in \cs{enddocument}.
% \begin{macrocode}
\cs_gset_eq:NN \@extra@page@added \relax
}
@@ -1376,9 +1438,11 @@
%
%
% \begin{macro}{\AtBeginDvi}
-%
+% If we roll forward from an earlier kernel \cs{AtBeginDvi} is
+% defined so we better not use \cs{cs_new_protected:Npn} here.
+% \changes{v1.0d}{2020/11/24}{Support for roll forward (gh/434)}
% \begin{macrocode}
-\cs_new_protected:Npn \AtBeginDvi {\@@_add_firstpage_material:Nn \AtBeginDvi}
+\cs_set_protected:Npn \AtBeginDvi {\@@_add_firstpage_material:Nn \AtBeginDvi}
% \end{macrocode}
% \end{macro}
%
@@ -1447,8 +1511,18 @@
%
% \begin{macrocode}
%<latexrelease>\IncludeInRelease{0000/00/00}%
-%<latexrelease> {\shipout}{The hook management (shipout)}%
-%<latexrelease>\expandafter\let\expandafter\shipout\csname tex_shipout:D\endcsname
+%<latexrelease> {\shipout}{Hook management (shipout)}%
+%<latexrelease>
+% \end{macrocode}
+% If we roll forward then \cs{tex\_shipout:D} may not be defined in
+% which case \cs{shipout} does have it original definition and so
+% we must not \cs{let} it to something else which is \cs{relax}!
+% \changes{v1.0d}{2020/11/24}{Support for roll forward (gh/434)}
+% \begin{macrocode}
+%<latexrelease>\ifcsname tex_shipout:D\endcsname
+%<latexrelease>\expandafter\let\expandafter\shipout
+%<latexrelease> \csname tex_shipout:D\endcsname
+%<latexrelease>\fi
%<latexrelease>
%<latexrelease>\let \ShipoutBox\@undefined
%<latexrelease>\let \ReadonlyShipoutCounter \@undefined
@@ -1483,7 +1557,7 @@
% \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
+% sufficiently obscure that it should not interfere 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).
@@ -1497,7 +1571,7 @@
% \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
+% sufficiently obscure that it should not interfere 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).
@@ -1573,8 +1647,8 @@
% \begin{macrocode}
%<*atbegshi-ltx>
\ProvidesPackage{atbegshi-ltx}
- [2020/08/17 v1.0a
- Emulation of the original atbegshi package^^Jwith kernel methods]
+ [2020/10/15 v1.0b
+ Emulation of the original atbegshi^^Jpackage with kernel methods]
% \end{macrocode}
%
%
@@ -1640,7 +1714,7 @@
%
%
%
-% \begin{macro}{\ShipoutBoxHeight,\ShipoutBoxWidth,\ShipoutoBoxDepth}
+% \begin{macro}{\ShipoutBoxHeight,\ShipoutBoxWidth,\ShipoutBoxDepth}
% 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
@@ -1679,8 +1753,8 @@
%
% \begin{macrocode}
\ProvidesPackage{everyshi-ltx}
- [2020/08/17 v1.0a
- Emulation of the original everyshi package^^Jwith kernel methods]
+ [2020/10/15 v1.0b
+ Emulation of the original everyshi^^Jpackage with kernel methods]
% \end{macrocode}
%
% \begin{macro}{\EveryShipout,\AtNextShipout}
@@ -1710,7 +1784,7 @@
%%
%% 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
+%% they are normally sufficient to avoid such manipulations (or
%% replace box 255 with \ShipoutBox in the code.
%%
%</everyshi-ltx>