[latex3-commits] [git/LaTeX3-latex3-latex2e] shipout-lastpage: implementation but no rollback (6d36d727)

[Frank Mittelbach]

Repository : https://github.com/latex3/latex2e
On branch  : shipout-lastpage
Link       : https://github.com/latex3/latex2e/commit/6d36d7276685fa8c8a4dd6b28910d183018d3ca1

>---------------------------------------------------------------

commit 6d36d7276685fa8c8a4dd6b28910d183018d3ca1
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Sun May 8 13:27:44 2022 +0200

    implementation but no rollback


>---------------------------------------------------------------

6d36d7276685fa8c8a4dd6b28910d183018d3ca1
 base/changes.txt                         |  6 +++++
 base/doc/ltnews35.tex                    | 14 +++++++++++
 base/ltshipout.dtx                       | 26 +++++++++++++++++----
 base/testfiles-lthooks2/shipout2-017.lvt | 40 ++++++++++++++++++++++++++++++++
 base/testfiles-lthooks2/shipout2-017.tlg | 13 +++++++++++
 5 files changed, 95 insertions(+), 4 deletions(-)

diff --git a/base/changes.txt b/base/changes.txt
index 7dee0404..bbf31549 100644
--- a/base/changes.txt
+++ b/base/changes.txt
@@ -6,6 +6,12 @@ completeness or accuracy and it contains some references to files that
 are not part of the distribution.
 ================================================================================
 
+2022-05-08  Frank Mittelbach  <Frank.Mittelbach at latex-project.org>
+
+	* ltshipout.dtx (subsection{Handling the end of job hook}):
+	Handle case where shipout/lastpage is run too early and issue
+	a warning (gh/813)
+
 2022-04-21  Joseph Wright <Joseph.Wright at latex-project.org>
 
 	* ltfinal.dtx (subsection{Lccodes and uccodes}):
diff --git a/base/doc/ltnews35.tex b/base/doc/ltnews35.tex
index 3edfd91d..162ce50f 100644
--- a/base/doc/ltnews35.tex
+++ b/base/doc/ltnews35.tex
@@ -695,6 +695,20 @@ been fixed in the latest release.
 \sxissue{q/637565}
 
 
+\subsection{Warn if \hook{shipout/lastpage} hook is executed too early}
+
+The hook \hook{shipout/lastpage} is intended to place \cs{special}s
+into the last page shipped out. This is needed for some use cases,
+e.g., tagging. If that hook is nonempty and the user has added additional
+pages since the last run, then \LaTeX{} executes this hook too early,
+but until now without giving any indication that the document needs
+rerunning. This has now been corrected and an appropriate warning is
+given.
+%
+\githubissue{813}
+
+
+
 \section{Changes to packages in the \pkg{amsmath} category}
 
 
diff --git a/base/ltshipout.dtx b/base/ltshipout.dtx
index 09495dde..2daf1c0a 100644
--- a/base/ltshipout.dtx
+++ b/base/ltshipout.dtx
@@ -32,8 +32,8 @@
 %%% From File: ltshipout.dtx
 %
 %    \begin{macrocode}
-\providecommand\ltshipoutversion{v1.0l}
-\providecommand\ltshipoutdate{2022/01/06}
+\providecommand\ltshipoutversion{v1.0m}
+\providecommand\ltshipoutdate{2022/05/08}
 %    \end{macrocode}
 %
 %<*driver>
@@ -1723,15 +1723,33 @@
           \gdef\string\@abspage at last {\int_use:N \g_shipout_readonly_int}}
      \fi
 %    \end{macrocode}
-%    But we may have guessed wrongly earlier and we still have to run the
+%    But we may have guessed wrongly earlier and have run it too early
+%    or we still have to run the
 %    \hook{shipout/lastpage} even though there is no page to place
 %    it into. If that is the case we make a trivial extra page and put
 %    it there. This temporary page will then vanish again on the next
 %    run but helps to keep pdf viewers happy.
+%    In either case we should put out an appropriate ``rerun'' warning.
+% \changes{v1.0m}{2022/05/08}{Handle case where shipout/lastpage is
+%    run too early (gh/813)}
 %    \begin{macrocode}
-      \bool_if:NF \g_@@_lastpage_handled_bool
+      \bool_if:NTF \g_@@_lastpage_handled_bool
          {
 %    \end{macrocode}
+%    If the hook was already executed, we have to test if that total
+%    shipouts match the shipouts from last run (because that
+%    corresponds to the page it was executed). If not we output a warning.
+%    \begin{macrocode}
+           \int_compare:nNnF \@abspage at last = \g_shipout_readonly_int
+            {
+              \@latex at warning@no at line{Hook~ 'shipout/lastpage'~ executed~
+                   on~ wrong~ page.~ Rerun~ to~ correct~ this}%
+            } 
+         }
+         {
+%    \end{macrocode}
+%    If the hook was not run, we need to add an extra page and place
+%    it there.
 %    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
diff --git a/base/testfiles-lthooks2/shipout2-017.lvt b/base/testfiles-lthooks2/shipout2-017.lvt
new file mode 100644
index 00000000..bb7ee083
--- /dev/null
+++ b/base/testfiles-lthooks2/shipout2-017.lvt
@@ -0,0 +1,40 @@
+\RequirePackage[enable-debug]{expl3}
+\ExplSyntaxOn
+\debug_on:n { check-declarations , deprecation }
+\ExplSyntaxOff
+
+\documentclass[a4paper]{article}
+
+
+\input{regression-test}
+
+\AddToHook{shipout/lastpage}{\label{LastPage}}
+
+\DebugShipoutsOn
+
+%\showoutput
+
+\gdef\extendthistest{0}
+
+\begin{document}
+
+\makeatletter
+\immediate\write\@auxout {\detokenize{\gdef\extendthistest{1}}}
+\makeatother
+
+\START
+
+Lastpage: \pageref{LastPage}
+
+
+\ifnum\extendthistest> 0  % second or third run
+  \typeout{========== adding more material in second run}
+  \newpage A  \newpage B
+\else
+  \typeout{========== no extra material added}
+\fi
+
+\end{document}
+
+
+
diff --git a/base/testfiles-lthooks2/shipout2-017.tlg b/base/testfiles-lthooks2/shipout2-017.tlg
new file mode 100644
index 00000000..f535e74d
--- /dev/null
+++ b/base/testfiles-lthooks2/shipout2-017.tlg
@@ -0,0 +1,13 @@
+This is a generated file for the l3build validation system.
+Don't change this file in any respect.
+========== adding more material in second run
+Absolute page = 1 (target: 1)
+Executing lastpage hook on page 1
+[1
+]
+Absolute page = 2 (target: 1)
+[2]
+Absolute page = 3 (target: 1)
+[3]
+LaTeX Warning: Hook 'shipout/lastpage' executed on wrong page. Rerun to correct this.
+(shipout2-017.aux)