diff options
Diffstat (limited to 'Master/texmf-dist/source/latex-dev/base/ltshipout.dtx')
| -rw-r--r-- | Master/texmf-dist/source/latex-dev/base/ltshipout.dtx | 825 |
1 files changed, 567 insertions, 258 deletions
diff --git a/Master/texmf-dist/source/latex-dev/base/ltshipout.dtx b/Master/texmf-dist/source/latex-dev/base/ltshipout.dtx index 8d6150b5930..650c46866e4 100644 --- a/Master/texmf-dist/source/latex-dev/base/ltshipout.dtx +++ b/Master/texmf-dist/source/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 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - |