[latex3-commits] [git/LaTeX3-latex3-latex2e] lthooks2: More documentation further rolloback and integration Added \PreviousTotalPages for use in documents Drop \@kernel at before@shipout at foreground and added \@kernel at before@shipout at background in the right place (fdfb0d7e)
Frank Mittelbach
frank.mittelbach at latex-project.org
Fri Aug 21 11:10:46 CEST 2020
Repository : https://github.com/latex3/latex2e
On branch : lthooks2
Link : https://github.com/latex3/latex2e/commit/fdfb0d7e90f91fe0096daaeee379b96f8823e93d
>---------------------------------------------------------------
commit fdfb0d7e90f91fe0096daaeee379b96f8823e93d
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Fri Aug 21 11:10:46 2020 +0200
More documentation
further rolloback and integration
Added \PreviousTotalPages for use in documents
Drop \@kernel at before@shipout at foreground and added \@kernel at before@shipout at background in the right place
>---------------------------------------------------------------
fdfb0d7e90f91fe0096daaeee379b96f8823e93d
base/ltfilehook.dtx | 199 ++++++++++++++++++---
base/ltfiles.dtx | 22 ++-
base/lthooks.dtx | 158 ++++++++--------
base/ltshipout.dtx | 77 +++++---
base/testfiles-lthooks2/shipout2-004.lvt | 9 +-
base/testfiles-lthooks2/shipout2-004.tlg | 3 +
.../tlb-latexrelease-rollback-003-often.luatex.tlg | 14 ++
.../tlb-latexrelease-rollback-003-often.tlg | 14 ++
.../tlb-latexrelease-rollback-003-often.xetex.tlg | 14 ++
base/testfiles/tlb-rollback-004-often.luatex.tlg | 7 +
base/testfiles/tlb-rollback-004-often.tlg | 7 +
base/testfiles/tlb-rollback-004-often.xetex.tlg | 7 +
12 files changed, 398 insertions(+), 133 deletions(-)
diff --git a/base/ltfilehook.dtx b/base/ltfilehook.dtx
index 4abdd861..77d05fc4 100644
--- a/base/ltfilehook.dtx
+++ b/base/ltfilehook.dtx
@@ -346,6 +346,58 @@
% \pkg{filehook} or \pkg{scrlfile} do) but think that for package
% writers the commands from for hook management are sufficient.
%
+%
+%
+% \subsection{Internal interfaces for \LaTeX{}}
+%
+% \begin{function}{\declare at file@substitution,\undeclare at file@substitution}
+% \begin{syntax}
+% \cs{declare at file@substitution} \Arg{file} \Arg{replacement-file}
+% \cs{undeclare at file@substitution} \Arg{file}
+% \end{syntax}
+% If \meta{file} is requested for loading replace it with
+% \meta{replacement-file}. \cs{CurrentFile} remains pointing to
+% \meta{file} but \cs{CurrentFileUsed} will show the file actually
+% loaded.
+%
+% The main use case for this declaration is to provide a corrected
+% version of a package that can't be changed (due to its license)
+% but no longer functions because of \LaTeX{} kernel changes, for
+% example, or to provide a version that makes use of new kernel
+% functionality while the original package remains available for
+% use with older releases.
+%
+% The \cs{undeclare at file@substitution} declaration undoes a
+% substitution made earlier.
+%
+% \begin{quote}
+% \em
+% Please do not misuse this functionality and replace a file with
+% another unless if really needed and only if the new version is
+% implementating the same functionality as the original one!
+% \end{quote}
+% \end{function}
+%
+% \begin{function}{\disable at package@load,\reenable at package@load}
+% \begin{syntax}
+% \cs{disable at package@load} \Arg{package} \Arg{alternate-code}
+% \cs{reenable at package@load} \Arg{package}
+% \end{syntax}
+% If \meta{package} is requested do not load it but instead run
+% \meta{alternate-code} which could issue a warning, error or any
+% other code.
+%
+% The main use case is for classesthat want to restrict the set of
+% supported packages or contain code that make the use of some
+% packages impossible. So rather than waiting until the document
+% breaks they can set up informative messages why certain packages
+% are not available.
+%
+% The function is only implemented for packages not for arbitrary
+% files.
+% \end{function}
+%
+%
% \subsection{A sample package for structuring the log output}
%
% As an application we provide the package \pkg{structuredlog} that
@@ -402,13 +454,15 @@
%<*2ekernel>
% \end{macrocode}
%
-% \subsection{\pkg{expl3} helpers}
-%
% \begin{macrocode}
%<@@=filehook>
\ExplSyntaxOn
% \end{macrocode}
%
+%
+% \subsection{Document and package-level commands}
+%
+%
% \begin{macro}{\CurrentFile,\CurrentFilePath}
% \begin{macro}{\CurrentFileUsed,\CurrentFilePathUsed}
% User-level macros that hold the current file name and file path.
@@ -447,6 +501,10 @@
% \end{macro}
% \end{macro}
%
+%
+%
+% \subsection{\pkg{expl3} helpers}
+%
% \begin{macro}{
% \@@_file_parse_full_name:nN,
% \@@_full_name:nn,
@@ -700,10 +758,11 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\declare at file@substitution}
-% \begin{macro}{\undeclare at file@substitution}
-% \begin{macro}{\@@_subst_file_normalise:n,\@@_subst_empty_name_chk:NN}
-% \cs{declare at file@substitution} declares a file substitution by
+%
+%
+% \begin{macro}{\@@_subst_add:nn,\@@_subst_remove:n,
+% \@@_subst_file_normalise:n,\@@_subst_empty_name_chk:NN}
+% \cs{@@_substitution_add:nn} declares a file substitution by
% doing a (global) definition of the form
% |\def|\cs{@file-subst@\meta{file}}|{|\meta{replacement}|}|.
% The file names are properly sanitised, and normalised with the same
@@ -712,7 +771,7 @@
% the file path should not be given. If a file name is empty it is
% replaced by |.tex| (the empty csname is used to check that).
% \begin{macrocode}
-\cs_new_protected:Npn \declare at file@substitution #1 #2
+\cs_new_protected:Npn \@@_subst_add:nn #1 #2
{
\group_begin:
\cs_set:cpx { } { \exp_not:o { \cs:w\cs_end: } }
@@ -721,7 +780,7 @@
{ \@@_subst_file_normalise:n {#2} }
\group_end:
}
-\cs_new_protected:Npn \undeclare at file@substitution #1
+\cs_new_protected:Npn \@@_subst_remove:n #1
{
\group_begin:
\cs_set:cpx { } { \exp_not:o { \cs:w\cs_end: } }
@@ -739,9 +798,41 @@
{ \if_meaning:w #1 #2 .tex \else: \token_to_str:N #2 \fi: }
% \end{macrocode}
% \end{macro}
+%
+%
+%
+% \begin{macro}{\declare at file@substitution}
+% \begin{macro}{\undeclare at file@substitution}
+% For two internals we provide \LaTeXe{} names so that we can use
+% them elsewhere in the kernel (and so that they can be used in
+% packages if really needed, e.g., \pkg{scrlfile}).
+% \begin{macrocode}
+%</2ekernel>
+%<*2ekernel|latexrelease>
+%<latexrelease>\IncludeInRelease{2020/10/01}%
+%<latexrelease> {\declare at file@substitution}{File substitution}%
+\cs_new_eq:NN \declare at file@substitution \@@_subst_add:nn
+\cs_new_eq:NN \undeclare at file@substitution \@@_subst_remove:n
+%</2ekernel|latexrelease>
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{0000/00/00}%
+%<latexrelease> {\declare at file@substitution}{File substitution}%
+%<latexrelease>
+%<latexrelease>\let \declare at file@substitution \@undefined
+%<latexrelease>\let \undeclare at file@substitution \@undefined
+%<latexrelease>
+%<latexrelease>\EndIncludeInRelease
+%<*2ekernel>
+% \end{macrocode}
% \end{macro}
% \end{macro}
%
+%
+%
+%
% \begin{macrocode}
%<@@=>
\ExplSyntaxOff
@@ -749,8 +840,7 @@
%
% \subsection{Selecting a file (\cs{set at curr@file})}
%
-% \begin{macro}{\set at curr@file,\@filehook at set@CurrentFile}
-% \begin{macro}{\@kernel at make@file at csname,\@set at curr@file at aux}
+% \begin{macro}{\set at curr@file,\@curr at file,\@curr at file@reqd}
% Now we hook into \cs{set at curr@file} to resolve a possible file
% substitution, and add \cs{@filehook at set@curr at file} at the end, after
% \cs{@curr at file} is set.
@@ -772,6 +862,10 @@
% expand to itself to avoid it matching the definition of some other
% control sequence.
% \begin{macrocode}
+%</2ekernel>
+%<*2ekernel|latexrelease>
+%<latexrelease>\IncludeInRelease{2020/10/01}%
+%<latexrelease> {\set at curr@file}{Setting current file name}%
\def\set at curr@file#1{%
\begingroup
\escapechar\m at ne
@@ -806,9 +900,41 @@
{\if at tempswa \@filehook at drop@extension\@curr at file \fi
\global\let\@curr at file@reqd\@curr at file}%
\endgroup}
+%</2ekernel|latexrelease>
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2019/10/01}%
+%<latexrelease> {\set at curr@file}{Setting current file name}%
+%<latexrelease>\def\set at curr@file#1{%
+%<latexrelease> \begingroup
+%<latexrelease> \escapechar\m at ne
+%<latexrelease> \xdef\@curr at file{%
+%<latexrelease> \expandafter\expandafter\expandafter\unquote at name
+%<latexrelease> \expandafter\expandafter\expandafter{%
+%<latexrelease> \expandafter\string
+%<latexrelease> \csname\@firstofone#1\@empty\endcsname}}%
+%<latexrelease> \endgroup
+%<latexrelease>}
+%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
%
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{0000/00/00}%
+%<latexrelease> {\set at curr@file}{Setting current file name}%
+%<latexrelease>\let\set at curr@file\@undefined
+%<latexrelease>\EndIncludeInRelease
+%<*2ekernel>
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+%
+% \begin{macro}{\@filehook at set@CurrentFile}
+% \begin{macro}{\@kernel at make@file at csname,\@set at curr@file at aux}
+% \begin{macrocode}
\def\@kernel at make@file at csname#1#2#3{%
\xdef#1{\expandafter\@set at curr@file at aux
\csname\expandafter#2\@firstofone#3\@nil\endcsname}}
@@ -822,6 +948,10 @@
.tex\else\string#1\fi}
% \end{macrocode}
%
+% \begin{macrocode}
+% \end{macrocode}
+%
+%
% Then we call \cs{@filehook at set@curr at file} once for \cs{@curr at file}
% to set \cs[no-index]{CurrentFile(Path)Used} and once for
% \cs{@curr at file@reqd} to set \cs[no-index]{CurrentFile(Path)}.
@@ -1034,24 +1164,32 @@
%
%
%
-% \subsection{Preventing a package/class from loading}
+% \subsection{Preventing a package from loading}
+%
+% We support the use case of preventing a package from loading but not
+% any other type of files (e.g., classes).
%
% \begin{macro}{\disable at package@load}
+% \begin{macro}{\reenable at package@load}
% \begin{macro}{\@disable at packageload@do}
% \cs{disable at package@load} defines
% \cs[no-index]{@pkg-disable@\meta{package}} to expand to some code |#2|
% instead of loading the package.
% \begin{macrocode}
+%</2ekernel>
+%<*2ekernel|latexrelease>
+%<latexrelease>\IncludeInRelease{2020/10/01}%
+%<latexrelease> {\disable at package@load}{Disable packages}%
\def\disable at package@load#1#2{%
\global\@namedef{@pkg-disable@#1.\@pkgextension}{#2}}
+% \end{macrocode}
+%
+% \begin{macrocode}
\def\@disable at packageload@do#1#2{%
\@ifundefined{@pkg-disable@#1}{#2}%
{\@nameuse{@pkg-disable@#1}}}
% \end{macrocode}
-% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\reenable at package@load}
% \cs{reenable at package@load} undefines
% \cs[no-index]{@pkg-disable@\meta{package}} to reallow loading a package.
% \begin{macrocode}
@@ -1059,7 +1197,24 @@
\global\expandafter\let
\csname @pkg-disable@#1.\@pkgextension \endcsname \@undefined}
% \end{macrocode}
+%
+%
+% \begin{macrocode}
+%</2ekernel|latexrelease>
+%<latexrelease>\EndIncludeInRelease
+%<latexrelease>\IncludeInRelease{0000/00/00}%
+%<latexrelease> {\disable at package@load}{Disable packages}%
+%<latexrelease>
+%<latexrelease>\let\disable at package@load \@undefined
+%<latexrelease>\let\@disable at packageload@do\@undefined
+%<latexrelease>\let\reenable at package@load \@undefined
+%<latexrelease>\EndIncludeInRelease
+%<*2ekernel>
+% \end{macrocode}
+% \end{macro}
% \end{macro}
+% \end{macro}
+%
%
%
%
@@ -1075,15 +1230,12 @@
%
%
%
-% \section{Internal commands needed elsewhere}
+% \subsection{Internal commands needed elsewhere}
%
-% \begin{macro}{}
-% Some internals needed elsewhere.
+% None so far.
% \begin{macrocode}
%<@@=>
% \end{macrocode}
-% \end{macro}
-%
%
% \begin{macrocode}
%</2ekernel>
@@ -1209,7 +1361,7 @@
% \begin{macrocode}
\newcommand\AtVeryVeryEnd {\AddToHook{enddocument/end}}
% \end{macrocode}
-
+%
% \begin{macro}{\BeforeClearDocument}
% This one is the only one we don't implement or rather don't have
% a dedicated hook in the code.
@@ -1412,13 +1564,12 @@
% \end{macrocode}
%
%
-
+%
% \Finale
%
-
-
+%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\endinput
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
+%
diff --git a/base/ltfiles.dtx b/base/ltfiles.dtx
index dd20fc2a..132f2cd2 100644
--- a/base/ltfiles.dtx
+++ b/base/ltfiles.dtx
@@ -352,6 +352,7 @@
% \changes{v1.1e}{1996/04/24}
% {(DPC) Reset \cs{AtBeginDocument} eg for latex/1297}
% \begin{macrocode}
+ \@kernel at before@begindocument
\UseOneTimeHook{begindocument}%
\@kernel at after@begindocument
% \end{macrocode}
@@ -427,7 +428,9 @@
-% \begin{macro}{\@kernel at after@begindocument at before,\@kernel at after@begindocument}
+% \begin{macro}{\@kernel at after@begindocument at before,
+% \@kernel at before@begindocument,
+% \@kernel at after@begindocument}
%
% Above we used two kernel only hooks to be run after the public
% \hook{begindocument/before} and after \hook{begindocument}
@@ -452,6 +455,7 @@
% \end{macrocode}
%
% \begin{macrocode}
+\let \@kernel at before@begindocument \@empty
\let \@kernel at after@begindocument \@empty
% \end{macrocode}
%
@@ -964,7 +968,6 @@
%
%
%
-
% \begin{macro}{\@curr at file}
% \begin{macro}{\set at curr@file}
%
@@ -992,11 +995,11 @@
% \changes{v1.2c}{2019/10/11}{Remove one brace group}
% \changes{v1.2d}{2019/10/26}{remove quotes}
% \changes{v1.2e}{2019/11/09}{expand and \cs{string} before removing quotes}
+%
+% The definition below is from 2019 and only used during kernel
+% bootstrapping, later on in \texttt{ltfilehook.dtx} it will get
+% overwritten.
% \begin{macrocode}
-%</2ekernel>
-%<*2ekernel|latexrelease>
-%<latexrelease>\IncludeInRelease{2019/10/01}%
-%<latexrelease> {\set at curr@file}{Quote file names}%
\def\set at curr@file#1{%
\begingroup
\escapechar\m at ne
@@ -1023,6 +1026,10 @@
% -> ""
%\end{verbatim}
% \begin{macrocode}
+%</2ekernel>
+%<*2ekernel|latexrelease>
+%<latexrelease>\IncludeInRelease{2019/10/01}%
+%<latexrelease> {\quote at name}{Quote file names}%
\def\quote at name#1{"\quote@@name#1\@gobble""}
\def\quote@@name#1"{#1\quote@@name}
% \end{macrocode}
@@ -1104,12 +1111,11 @@
%</2ekernel|latexrelease>
%<latexrelease>\EndIncludeInRelease
%<latexrelease>\IncludeInRelease{0000/00/00}%
-%<latexrelease> {\set at curr@file}{Quote file names}%
+%<latexrelease> {\quote at name}{Quote file names}%
%<latexrelease>
%<latexrelease>\let\quote at name\@undefined
%<latexrelease>\let\quote@@name\@undefined
%<latexrelease>\let\unquote at name\@undefined
-%<latexrelease>\let\set at curr@file\@undefined
%<latexrelease>
%<latexrelease>\let\IfFileExists@\@undefined
%<latexrelease>
diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index 06c2d409..a35b3bf4 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -172,9 +172,9 @@
% the current package name. See section~\ref{sec:default-label}.
% \end{function}
%
-
-
-
+%
+%
+%
% \begin{function}{\UseHook}
% \begin{syntax}
% \cs{UseHook} \Arg{hook}
@@ -727,8 +727,8 @@
% the current package name. See section~\ref{sec:default-label}.
% \end{function}
%
-
-
+%
+%
% \begin{function}{\hook_gremove_code:nn}
% \begin{syntax}
% \cs{hook_gremove_code:nn} \Arg{hook} \Arg{label}
@@ -749,8 +749,8 @@
% dot-syntax to denote the current package name.
% See section~\ref{sec:default-label}.
% \end{function}
-
-
+%
+%
% \begin{function}{\hook_gset_rule:nnnn}
% \begin{syntax}
% \cs{hook_gset_rule:nnnn} \Arg{hook} \Arg{label1} \Arg{relation} \Arg{label2}
@@ -1274,8 +1274,8 @@
% \hook{env/document/before} and \hook{env/document/begin}, but
% with this special environment it is better use the dedicated
% one-time hooks above.
-
-
+%
+%
%
%
% \subsubsection{Hooks provided by \cs{end}\texttt{\{document\}}}
@@ -1364,7 +1364,7 @@
% several times, so initially it might get executed on the wrong
% page. See section~\ref{sec:shipout} for where to find the details.
%
-
+%
% It is in also possible to use the generic \hook{env/document/end}
% hook which is execuded by \cs{end}, i.e., just in front of the
% first hook above. Note however that the other generic \cs{end}
@@ -1372,8 +1372,8 @@
% executed, because by that time \LaTeX{} has finished the document
% processing.
%
-
-
+%
+%
%
% \subsubsection{Hooks provided \cs{shipout} operations}
% \label{sec:shipout}
@@ -1393,13 +1393,13 @@
% \texttt{ltfilehook-code.pdf}.
%
%
-
+%
% \StopEventually{\setlength\IndexMin{200pt} \PrintIndex }
%
%
% \section{The Implementation}
-
-
+%
+%
% \subsection{Loading further extensions}
%
% \begin{macrocode}
@@ -1455,7 +1455,7 @@
% \end{macro}
% \end{macro}
% \end{macro}
-
+%
%
%
% \subsection{Borrowing from internals of other kernel modules}
@@ -1585,8 +1585,8 @@
%
% \end{description}
% \end{macro}
-
-
+%
+%
%
%
% \begin{macro}{\hook_new:n}
@@ -1650,7 +1650,7 @@
}
% \end{macrocode}
% \end{macro}
-
+%
%
%
% \begin{macro}{\@@_declare:n}
@@ -1670,9 +1670,9 @@
}
% \end{macrocode}
% \end{macro}
-
-
-
+%
+%
+%
% \begin{macro}{\hook_new_reversed:n}
%
% Declare a new hook. The default ordering of code chunks is
@@ -1689,7 +1689,7 @@
}
% \end{macrocode}
% \end{macro}
-
+%
% \begin{macro}{\hook_new_pair:nn}
% A shorthand for declaring a normal and a (matching) reversed hook in one go.
% \begin{macrocode}
@@ -1698,8 +1698,8 @@
}
% \end{macrocode}
% \end{macro}
-
-
+%
+%
% \begin{macro}{\@@_include_legacy_code_chunk:n}
% The \LaTeX{} legacy concept for hooks uses with hooks the
% following naming scheme in the code: \cs{@...hook}.
@@ -1828,10 +1828,10 @@
}
% \end{macrocode}
% \end{macro}
-
-
-
-
+%
+%
+%
+%
% \begin{macro}{\hook_gput_code:nnn}
% \begin{macro}{\@@_gput_code:nnn,\@@_gput_code:nxv,\@@_hook_gput_code_do:nnn}
%
@@ -2559,16 +2559,16 @@
}
% \end{macrocode}
% \end{macro}
-
-
+%
+%
% \begin{macro}{\g_@@_used_prop}
% All hooks that receive code (for use in debugging display).
% \begin{macrocode}
\prop_new:N\g_@@_used_prop
% \end{macrocode}
% \end{macro}
-
-
+%
+%
%
% \begin{macro}[EXP]{\@@_tl_csname:n,\@@_seq_csname:n}
% It is faster to pass a single token and expand it when necessary
@@ -2580,7 +2580,7 @@
% \end{macrocode}
% \end{macro}
%
-
+%
%
%
% \begin{macro}{\l_@@_labels_seq,\l_@@_labels_int,\l_@@_front_tl,
@@ -2620,8 +2620,8 @@
%
% \end{itemize}
% \end{macro}
-
-
+%
+%
% \begin{macro}{\@@_initialize_single:NNNn,\@@_initialize_single:cccn}
%
% \cs{@@_initialize_single:NNNn} implements the sorting of the code
@@ -2799,9 +2799,9 @@
\cs_generate_variant:Nn \@@_initialize_single:NNNn {ccc}
% \end{macrocode}
% \end{macro}
-
-
-
+%
+%
+%
% \begin{macro}{\@@_tl_gput:NV,\@@_clist_gput:NV}
% These append either on the right (normal hook) or on the left
% (reversed hook). This is setup up in
@@ -2811,8 +2811,8 @@
\cs_new:Npn \@@_clist_gput:NV {\ERROR}
% \end{macrocode}
% \end{macro}
-
-
+%
+%
%
% \begin{macro}{\@@_apply_label_pair:nnn,\@@_label_if_exist_apply:nnnF}
%
@@ -2867,10 +2867,10 @@
}
% \end{macrocode}
% \end{macro}
-
-
-
-
+%
+%
+%
+%
% \begin{macro}{\@@_apply_rule:nnn}
% This is the code executed in steps T2 and T3 while looping through
% the matrix This is part of step T3. We are about to apply the next
@@ -2972,7 +2972,7 @@
}
% \end{macrocode}
% \end{macro}
-
+%
% \begin{macro}{
% \@@_apply_-rule_<:nnn,
% \@@_apply_-rule_>:nnn,
@@ -2990,8 +2990,8 @@
\cs_new_eq:cc { @@_apply_-rule_xW:nnn } { @@_apply_rule_xW:nnn }
% \end{macrocode}
% \end{macro}
-
-
+%
+%
% \begin{macro}{\@@_msg_pair_found:nnn}
% A macro to avoid moving this many tokens around.
% \begin{macrocode}
@@ -3004,8 +3004,8 @@
}
% \end{macrocode}
% \end{macro}
-
-
+%
+%
% \begin{macro}{\@@_debug_label_data:N}
%
% \begin{macrocode}
@@ -3023,9 +3023,9 @@
}
% \end{macrocode}
% \end{macro}
-
-
-
+%
+%
+%
% \begin{macro}{\hook_log:n}
% This writes out information about the hook given in its argument
% onto the terminal and the \texttt{.log} file.
@@ -3310,7 +3310,7 @@
}
% \end{macrocode}
% \end{macro}
-
+%
% \subsection{Querying a hook}
%
% Simpler data types, like token lists, have three possible states; they
@@ -3353,7 +3353,7 @@
}
% \end{macrocode}
% \end{macro}
-
+%
% \begin{macro}[pTF]{\hook_if_exist:n}
% A canonical way to test if a hook exists. A hook exists if the
% token list that stores the sorted code for that hook,
@@ -3371,7 +3371,7 @@
}
% \end{macrocode}
% \end{macro}
-
+%
% \begin{macro}[pTF]{\@@_if_exist:n}
% An internal check if the hook has already been declared with
% \cs{@@_declare:n}. This means that the hook was already used somehow
@@ -3400,8 +3400,8 @@
}
% \end{macrocode}
% \end{macro}
-
-
+%
+%
% \begin{macro}{\g_@@_execute_immediately_clist}
% List of hooks that from no on should not longer receive code.
% \begin{macrocode}
@@ -3465,8 +3465,8 @@
%
% \subsection{\LaTeXe{} package interface commands}
%
-
-
+%
+%
% \begin{macro}{\NewHook,\NewReversedHook,\NewMirroredHookPair}
% Declaring new hooks \ldots
% \begin{macrocode}
@@ -3475,7 +3475,7 @@
\NewDocumentCommand \NewMirroredHookPair { mm }{ \hook_new_pair:nn {#1}{#2} }
% \end{macrocode}
% \end{macro}
-
+%
% \begin{macro}{\AddToHook}
%
% \begin{macrocode}
@@ -3487,7 +3487,7 @@
}
% \end{macrocode}
% \end{macro}
-
+%
% \begin{macro}{\AddToHookNext}
%
% \begin{macrocode}
@@ -3495,8 +3495,8 @@
{ \hook_gput_next_code:nn {#1} {#2} }
% \end{macrocode}
% \end{macro}
-
-
+%
+%
% \begin{macro}{\RemoveFromHook}
%
% \begin{macrocode}
@@ -3526,7 +3526,7 @@
% \begin{macrocode}
\seq_gpush:Nn \g_@@_name_stack_seq { }
% \end{macrocode}
-
+%
%
% Two commands keep track of the stack: when a file is input,
% \cs{@@_curr_name_push:n} pushes an (empty by default) label to the
@@ -3581,16 +3581,16 @@
\newcommand \UseOneTimeHook { \hook_use_once:n }
% \end{macrocode}
% \end{macro}
-
-
-
+%
+%
+%
% \begin{macro}{\ShowHook}
%
% \begin{macrocode}
\cs_new_protected:Npn \ShowHook { \hook_log:n }
% \end{macrocode}
% \end{macro}
-
+%
% \begin{macro}{\DebugHooksOn,\DebugHooksOff}
%
% \begin{macrocode}
@@ -3598,9 +3598,9 @@
\cs_new_protected:Npn \DebugHooksOff { \hook_debug_off: }
% \end{macrocode}
% \end{macro}
-
-
-
+%
+%
+%
% \begin{macro}{\DeclareHookRule}
%
% \begin{macrocode}
@@ -3608,7 +3608,7 @@
{ \hook_gset_rule:nnnn {#1}{#2}{#3}{#4} }
% \end{macrocode}
% \end{macro}
-
+%
% \begin{macro}{\DeclareDefaultHookRule}
% This declaration is only supported before \verb=\begin{document}=.
% \begin{macrocode}
@@ -3637,10 +3637,10 @@
{ \hook_if_empty:nTF {#1} }
% \end{macrocode}
% \end{macro}
-
-
+%
+%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%5
-
+%
% \subsection{Internal commands needed elsewhere}
%
% Here we set up a few horrible (but consistent) \LaTeXe{} names to
@@ -3721,5 +3721,7 @@
%
% \Finale
%
-
-
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\endinput
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
diff --git a/base/ltshipout.dtx b/base/ltshipout.dtx
index 51a47f8e..112fa471 100644
--- a/base/ltshipout.dtx
+++ b/base/ltshipout.dtx
@@ -329,6 +329,17 @@
% reliable inside the output routine!
% \end{variable}
%
+% \begin{variable}{\PreviousTotalPages}
+% \begin{syntax}
+% \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}
@@ -687,13 +698,13 @@
%
% \begin{macrocode}
\@@_get_box_size:N \l_shipout_box
- \@kernel at before@shipout at 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 at before@shipout at 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
@@ -749,12 +760,12 @@
%
%
% \begin{macro}{\@kernel at after@shipout at lastpage,
-% \@kernel at before@shipout at foreground}
+% \@kernel at before@shipout at background}
% And here are the internal kernel hooks going before or after the
-% public ones.
+% public ones where needed.
% \begin{macrocode}
\let\@kernel at after@shipout at lastpage\@empty
-\let\@kernel at before@shipout at foreground\@empty
+\let\@kernel at before@shipout at background\@empty
% \end{macrocode}
% \end{macro}
%
@@ -1177,7 +1188,7 @@
% 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.
@@ -1314,6 +1325,25 @@
% \end{macro}
%
%
+% \begin{macro}{\PreviousTotalPages,\@kernel at 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 at 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 at addto@macro\@kernel at before@begindocument
+ {\ifnum\@abspage at last<\maxdimen
+ \xdef\PreviousTotalPages{\@abspage at last}\fi}
+% \end{macrocode}
+% \end{macro}
%
%
% \section{Legacy \LaTeXe{} interfaces}
@@ -1347,38 +1377,41 @@
%
% \section{Internal commands needed elsewhere}
%
-% \begin{macro}{\@expl@@shipout at add@firstpage at material@Nn,
-% \@expl@@shipout at add@background at box@n,
-% \@expl@@shipout at add@foreground at box@n,
-% \@expl@@shipout at add@background at picture@n,
-% \@expl@@shipout at add@foreground at picture@n}
-% Some internals 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 at add@firstpage at material@@Nn,
+% \@expl@@@shipout at add@background at box@@n,
+% \@expl@@@shipout at add@foreground at box@@n,
+% \@expl@@@shipout at add@background at picture@@n,
+% \@expl@@@shipout at add@foreground at picture@@n}
+% Some internals needed elsewhere.
+%
% \begin{macrocode}
-\cs_set_eq:NN \@expl@@shipout at add@firstpage at material@Nn
+\cs_set_eq:NN \@expl@@@shipout at add@firstpage at material@@Nn
\__shipout_add_firstpage_material:Nn
% \end{macrocode}
%
% \begin{macrocode}
-\cs_set_eq:NN \@expl@@shipout at add@background at box@n
+\cs_set_eq:NN \@expl@@@shipout at add@background at box@@n
\__shipout_add_background_box:n
% \end{macrocode}
%
% \begin{macrocode}
-\cs_set_eq:NN \@expl@@shipout at add@foreground at box@n
+\cs_set_eq:NN \@expl@@@shipout at add@foreground at box@@n
\__shipout_add_foreground_box:n
% \end{macrocode}
%
% \begin{macrocode}
-\cs_set_eq:NN \@expl@@shipout at add@background at picture@n
+\cs_set_eq:NN \@expl@@@shipout at add@background at picture@@n
\__shipout_add_background_picture:n
% \end{macrocode}
%
% \begin{macrocode}
-\cs_set_eq:NN \@expl@@shipout at add@foreground at picture@n
+\cs_set_eq:NN \@expl@@@shipout at add@foreground at picture@@n
\__shipout_add_foreground_picture:n
% \end{macrocode}
% \end{macro}
@@ -1539,7 +1572,7 @@
% \hook{shipout/firstpage} hook is filled.
% \begin{macrocode}
\def \AtBeginShipoutFirst
- {\@expl@@shipout at add@firstpage at material@Nn \AtBeginShipoutFirst}
+ {\@expl@@@shipout at add@firstpage at material@@Nn \AtBeginShipoutFirst}
% \end{macrocode}
% \end{macro}
%
@@ -1557,16 +1590,16 @@
% We don't expose them.
% \begin{macrocode}
\let \AtBeginShipoutAddToBox
- \@expl@@shipout at add@background at box@n
+ \@expl@@@shipout at add@background at box@@n
\let \AtBeginShipoutAddToBoxForeground
- \@expl@@shipout at add@foreground at box@n
+ \@expl@@@shipout at add@foreground at box@@n
% \end{macrocode}
%
% \begin{macrocode}
\let \AtBeginShipoutUpperLeft
- \@expl@@shipout at add@background at picture@n
+ \@expl@@@shipout at add@background at picture@@n
\let \AtBeginShipoutUpperLeftForeground
- \@expl@@shipout at add@foreground at picture@n
+ \@expl@@@shipout at add@foreground at picture@@n
% \end{macrocode}
% \end{macro}
%
diff --git a/base/testfiles-lthooks2/shipout2-004.lvt b/base/testfiles-lthooks2/shipout2-004.lvt
index 1e769590..e362b36d 100644
--- a/base/testfiles-lthooks2/shipout2-004.lvt
+++ b/base/testfiles-lthooks2/shipout2-004.lvt
@@ -11,12 +11,17 @@
\DebugShipoutsOn
+\START
+
+\typeout{PreviousTotalPages (preamble) = \PreviousTotalPages}
\AtEndDvi{\typeout{Last page?}}
+\OMIT
\begin{document}
+\TIMO
-\START
+\typeout{PreviousTotalPages (in body) = \PreviousTotalPages}
A \begin{figure}[p] A \end{figure} \newpage
B \begin{figure}[p] B \end{figure} \newpage
@@ -26,4 +31,6 @@ C \begin{figure}[p] C \end{figure} \newpage
D
+\typeout{PreviousTotalPages (at end) = \PreviousTotalPages}
+
\end{document}
diff --git a/base/testfiles-lthooks2/shipout2-004.tlg b/base/testfiles-lthooks2/shipout2-004.tlg
index 75c05f67..32d7666f 100644
--- a/base/testfiles-lthooks2/shipout2-004.tlg
+++ b/base/testfiles-lthooks2/shipout2-004.tlg
@@ -1,5 +1,7 @@
This is a generated file for the l3build validation system.
Don't change this file in any respect.
+PreviousTotalPages (preamble) = 0
+PreviousTotalPages (in body) = 5
Absolute page = 1 (target: 5)
[1
]
@@ -7,6 +9,7 @@ Absolute page = 2 (target: 5)
[2]
Absolute page = 3 (target: 5)
[3]
+PreviousTotalPages (at end) = 5
Absolute page = 4 (target: 5)
Completed box being shipped out [4]
\vbox(633.0+0.0)x407.0
diff --git a/base/testfiles/tlb-latexrelease-rollback-003-often.luatex.tlg b/base/testfiles/tlb-latexrelease-rollback-003-often.luatex.tlg
index a3248b41..2bd5304a 100644
--- a/base/testfiles/tlb-latexrelease-rollback-003-often.luatex.tlg
+++ b/base/testfiles/tlb-latexrelease-rollback-003-often.luatex.tlg
@@ -169,6 +169,13 @@ Applying: [....-..-..] Hook management file on input line ....
Skipping: [....-..-..] Hook management (files) on input line ....
Skipping: [....-..-..] Hook management (files) on input line ....
Applying: [....-..-..] Hook management (files) on input line ....
+Skipping: [....-..-..] File substitution on input line ....
+Applying: [....-..-..] File substitution on input line ....
+Skipping: [....-..-..] Setting current file name on input line ....
+Skipping: [....-..-..] Setting current file name on input line ....
+Applying: [....-..-..] Setting current file name on input line ....
+Skipping: [....-..-..] Disable packages on input line ....
+Applying: [....-..-..] Disable packages on input line ....
Skipping: [....-..-..] Hook mangement (shipout) on input line ....
Applying: [....-..-..] The hook management (shipout) on input line ....
LaTeX Info: Redefining \AtBeginDvi on input line ....
@@ -595,6 +602,13 @@ Skipping: [....-..-..] Hook management (files) on input line ....
Applying: [....-..-..] Hook management (files) on input line ....
LaTeX Info: Redefining \InputIfFileExists on input line ....
Already applied: [....-..-..] Hook management (files) on input line ....
+Skipping: [....-..-..] File substitution on input line ....
+Applying: [....-..-..] File substitution on input line ....
+Skipping: [....-..-..] Setting current file name on input line ....
+Applying: [....-..-..] Setting current file name on input line ....
+Already applied: [....-..-..] Setting current file name on input line ....
+Skipping: [....-..-..] Disable packages on input line ....
+Applying: [....-..-..] Disable packages on input line ....
Skipping: [....-..-..] Hook mangement (shipout) on input line ....
Applying: [....-..-..] The hook management (shipout) on input line ....
LaTeX Info: Redefining \AtBeginDvi on input line ....
diff --git a/base/testfiles/tlb-latexrelease-rollback-003-often.tlg b/base/testfiles/tlb-latexrelease-rollback-003-often.tlg
index 10395b52..2d3824d6 100644
--- a/base/testfiles/tlb-latexrelease-rollback-003-often.tlg
+++ b/base/testfiles/tlb-latexrelease-rollback-003-often.tlg
@@ -167,6 +167,13 @@ Applying: [....-..-..] Hook management file on input line ....
Skipping: [....-..-..] Hook management (files) on input line ....
Skipping: [....-..-..] Hook management (files) on input line ....
Applying: [....-..-..] Hook management (files) on input line ....
+Skipping: [....-..-..] File substitution on input line ....
+Applying: [....-..-..] File substitution on input line ....
+Skipping: [....-..-..] Setting current file name on input line ....
+Skipping: [....-..-..] Setting current file name on input line ....
+Applying: [....-..-..] Setting current file name on input line ....
+Skipping: [....-..-..] Disable packages on input line ....
+Applying: [....-..-..] Disable packages on input line ....
Skipping: [....-..-..] Hook mangement (shipout) on input line ....
Applying: [....-..-..] The hook management (shipout) on input line ....
LaTeX Info: Redefining \AtBeginDvi on input line ....
@@ -587,6 +594,13 @@ Skipping: [....-..-..] Hook management (files) on input line ....
Applying: [....-..-..] Hook management (files) on input line ....
LaTeX Info: Redefining \InputIfFileExists on input line ....
Already applied: [....-..-..] Hook management (files) on input line ....
+Skipping: [....-..-..] File substitution on input line ....
+Applying: [....-..-..] File substitution on input line ....
+Skipping: [....-..-..] Setting current file name on input line ....
+Applying: [....-..-..] Setting current file name on input line ....
+Already applied: [....-..-..] Setting current file name on input line ....
+Skipping: [....-..-..] Disable packages on input line ....
+Applying: [....-..-..] Disable packages on input line ....
Skipping: [....-..-..] Hook mangement (shipout) on input line ....
Applying: [....-..-..] The hook management (shipout) on input line ....
LaTeX Info: Redefining \AtBeginDvi on input line ....
diff --git a/base/testfiles/tlb-latexrelease-rollback-003-often.xetex.tlg b/base/testfiles/tlb-latexrelease-rollback-003-often.xetex.tlg
index b889950b..7bbd6b2f 100644
--- a/base/testfiles/tlb-latexrelease-rollback-003-often.xetex.tlg
+++ b/base/testfiles/tlb-latexrelease-rollback-003-often.xetex.tlg
@@ -167,6 +167,13 @@ Applying: [....-..-..] Hook management file on input line ....
Skipping: [....-..-..] Hook management (files) on input line ....
Skipping: [....-..-..] Hook management (files) on input line ....
Applying: [....-..-..] Hook management (files) on input line ....
+Skipping: [....-..-..] File substitution on input line ....
+Applying: [....-..-..] File substitution on input line ....
+Skipping: [....-..-..] Setting current file name on input line ....
+Skipping: [....-..-..] Setting current file name on input line ....
+Applying: [....-..-..] Setting current file name on input line ....
+Skipping: [....-..-..] Disable packages on input line ....
+Applying: [....-..-..] Disable packages on input line ....
Skipping: [....-..-..] Hook mangement (shipout) on input line ....
Applying: [....-..-..] The hook management (shipout) on input line ....
LaTeX Info: Redefining \AtBeginDvi on input line ....
@@ -596,6 +603,13 @@ Skipping: [....-..-..] Hook management (files) on input line ....
Applying: [....-..-..] Hook management (files) on input line ....
LaTeX Info: Redefining \InputIfFileExists on input line ....
Already applied: [....-..-..] Hook management (files) on input line ....
+Skipping: [....-..-..] File substitution on input line ....
+Applying: [....-..-..] File substitution on input line ....
+Skipping: [....-..-..] Setting current file name on input line ....
+Applying: [....-..-..] Setting current file name on input line ....
+Already applied: [....-..-..] Setting current file name on input line ....
+Skipping: [....-..-..] Disable packages on input line ....
+Applying: [....-..-..] Disable packages on input line ....
Skipping: [....-..-..] Hook mangement (shipout) on input line ....
Applying: [....-..-..] The hook management (shipout) on input line ....
LaTeX Info: Redefining \AtBeginDvi on input line ....
diff --git a/base/testfiles/tlb-rollback-004-often.luatex.tlg b/base/testfiles/tlb-rollback-004-often.luatex.tlg
index db7f7821..78eb0581 100644
--- a/base/testfiles/tlb-rollback-004-often.luatex.tlg
+++ b/base/testfiles/tlb-rollback-004-often.luatex.tlg
@@ -224,6 +224,13 @@ Skipping: [....-..-..] Hook management (files) on input line ....
Applying: [....-..-..] Hook management (files) on input line ....
LaTeX Info: Redefining \InputIfFileExists on input line ....
Already applied: [....-..-..] Hook management (files) on input line ....
+Skipping: [....-..-..] File substitution on input line ....
+Applying: [....-..-..] File substitution on input line ....
+Skipping: [....-..-..] Setting current file name on input line ....
+Applying: [....-..-..] Setting current file name on input line ....
+Already applied: [....-..-..] Setting current file name on input line ....
+Skipping: [....-..-..] Disable packages on input line ....
+Applying: [....-..-..] Disable packages on input line ....
Skipping: [....-..-..] Hook mangement (shipout) on input line ....
Applying: [....-..-..] The hook management (shipout) on input line ....
LaTeX Info: Redefining \AtBeginDvi on input line ....
diff --git a/base/testfiles/tlb-rollback-004-often.tlg b/base/testfiles/tlb-rollback-004-often.tlg
index 0e6cd8d9..aa1e605b 100644
--- a/base/testfiles/tlb-rollback-004-often.tlg
+++ b/base/testfiles/tlb-rollback-004-often.tlg
@@ -222,6 +222,13 @@ Skipping: [....-..-..] Hook management (files) on input line ....
Applying: [....-..-..] Hook management (files) on input line ....
LaTeX Info: Redefining \InputIfFileExists on input line ....
Already applied: [....-..-..] Hook management (files) on input line ....
+Skipping: [....-..-..] File substitution on input line ....
+Applying: [....-..-..] File substitution on input line ....
+Skipping: [....-..-..] Setting current file name on input line ....
+Applying: [....-..-..] Setting current file name on input line ....
+Already applied: [....-..-..] Setting current file name on input line ....
+Skipping: [....-..-..] Disable packages on input line ....
+Applying: [....-..-..] Disable packages on input line ....
Skipping: [....-..-..] Hook mangement (shipout) on input line ....
Applying: [....-..-..] The hook management (shipout) on input line ....
LaTeX Info: Redefining \AtBeginDvi on input line ....
diff --git a/base/testfiles/tlb-rollback-004-often.xetex.tlg b/base/testfiles/tlb-rollback-004-often.xetex.tlg
index 1c35e5bf..2b620bde 100644
--- a/base/testfiles/tlb-rollback-004-often.xetex.tlg
+++ b/base/testfiles/tlb-rollback-004-often.xetex.tlg
@@ -222,6 +222,13 @@ Skipping: [....-..-..] Hook management (files) on input line ....
Applying: [....-..-..] Hook management (files) on input line ....
LaTeX Info: Redefining \InputIfFileExists on input line ....
Already applied: [....-..-..] Hook management (files) on input line ....
+Skipping: [....-..-..] File substitution on input line ....
+Applying: [....-..-..] File substitution on input line ....
+Skipping: [....-..-..] Setting current file name on input line ....
+Applying: [....-..-..] Setting current file name on input line ....
+Already applied: [....-..-..] Setting current file name on input line ....
+Skipping: [....-..-..] Disable packages on input line ....
+Applying: [....-..-..] Disable packages on input line ....
Skipping: [....-..-..] Hook mangement (shipout) on input line ....
Applying: [....-..-..] The hook management (shipout) on input line ....
LaTeX Info: Redefining \AtBeginDvi on input line ....
More information about the latex3-commits
mailing list.