[latex3-commits] [git/LaTeX3-latex3-latex2e] develop: some further cleanup (c994901e)

[Frank Mittelbach]

Repository : https://github.com/latex3/latex2e
On branch  : develop
Link       : https://github.com/latex3/latex2e/commit/c994901eda4828bf3792bd159e6802d20dc01ba4

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

commit c994901eda4828bf3792bd159e6802d20dc01ba4
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Thu Jan 6 22:26:29 2022 +0100

    some further cleanup


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

c994901eda4828bf3792bd159e6802d20dc01ba4
 base/ltshipout.dtx | 31 +++++++++++++++++++++----------
 1 file changed, 21 insertions(+), 10 deletions(-)

diff --git a/base/ltshipout.dtx b/base/ltshipout.dtx
index 8c99ab98..c2c9ee16 100644
--- a/base/ltshipout.dtx
+++ b/base/ltshipout.dtx
@@ -327,7 +327,10 @@
 % \subsection{Legacy \LaTeX{} commands}
 %
 % \begin{function}{\AtBeginDvi,\AtEndDvi}
-%    \cs{AtBeginDvi} is the existing \LaTeXe{} interface to fill the
+%    \begin{syntax}
+%      \cs{AtBeginDvi} \Arg{code}
+%    \end{syntax}
+ %    \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{.xdv}.
@@ -336,17 +339,23 @@
 %    kernel but only through the package \pkg{atenddvi}. It fills the
 %    \hook{shipout/lastpage} hook.
 %
+%    Neither interface can set a code label but uses the current default label.
+%
 % \end{function}
 %
 %    As these two wrappers have been available for a long time we
-%    continue offering them (but not enhancing them by providing
-%    support for code labels, for example).
+%    continue offering them (but not enhancing them, e.g., by providing
+%    support for code labels).
+%
+%    For new code we strongly 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 and it also allows you to set code labels if
+%    needed.
 %
-%    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.
+%    For this reason we do not provide any other ``new'' wrapper
+%    commands for the above hooks in the kernel, but only keep
+%    the existing ones for backward compatibility.
 %
 %
 % \subsection{Special commands for use inside the hooks}
@@ -2046,9 +2055,11 @@
 %
 %  \begin{macro}{\AtBeginShipout,\AtBeginShipoutNext}
 %    Filling hooks
+% \changes{v1.0l}{2022/01/06}{Correctly simulate \cs{AtBeginShipout}
+%    and \cs{AtBeginShipoutNext} without extending the syntax}
 %    \begin{macrocode}
-\protected \def \AtBeginShipout     {\AddToHook{shipout/before}}
-\protected \def \AtBeginShipoutNext {\AddToHookNext{shipout/before}}
+\protected \def \AtBeginShipout     #1{\AddToHook{shipout/before}{#1}}
+\protected \def \AtBeginShipoutNext #1{\AddToHookNext{shipout/before}{#1}}
 %    \end{macrocode}
 %  \end{macro}
 %