diff options
author | Karl Berry <karl@freefriends.org> | 2021-01-09 21:36:18 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2021-01-09 21:36:18 +0000 |
commit | b33d382702e71037548dba5374e276b861ea8031 (patch) | |
tree | 1670ea7d19f460766341de9e97fe76c8bd09931f /Master/texmf-dist/source/latex-dev/base/ltshipout.dtx | |
parent | 23616a07e621fb344c8329dfa20c60408b644d95 (diff) |
latex-dev (9jan21)
git-svn-id: svn://tug.org/texlive/trunk@57365 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex-dev/base/ltshipout.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex-dev/base/ltshipout.dtx | 160 |
1 files changed, 117 insertions, 43 deletions
diff --git a/Master/texmf-dist/source/latex-dev/base/ltshipout.dtx b/Master/texmf-dist/source/latex-dev/base/ltshipout.dtx index 8f0422c887b..2ea0a1b6651 100644 --- a/Master/texmf-dist/source/latex-dev/base/ltshipout.dtx +++ b/Master/texmf-dist/source/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> |