[latex3-commits] [git/LaTeX3-latex3-latex2e] gh410: more documentation on emulations and wrapper commands for #410 (610bddd4)

[Frank Mittelbach]

Repository : https://github.com/latex3/latex2e
On branch  : gh410
Link       : https://github.com/latex3/latex2e/commit/610bddd4d1157592270a4989e8e45af55c10dc74

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

commit 610bddd4d1157592270a4989e8e45af55c10dc74
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Tue Oct 13 13:20:27 2020 +0200

    more documentation on emulations and wrapper commands for #410


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

610bddd4d1157592270a4989e8e45af55c10dc74
 base/ltfilehook.dtx | 13 +++++----
 base/ltshipout.dtx  | 76 ++++++++++++++++++++++++++++++++++++++++++++---------
 2 files changed, 71 insertions(+), 18 deletions(-)

diff --git a/base/ltfilehook.dtx b/base/ltfilehook.dtx
index 24ba88f5..3c280967 100644
--- a/base/ltfilehook.dtx
+++ b/base/ltfilehook.dtx
@@ -32,7 +32,7 @@
 %
 %    \begin{macrocode}
 \providecommand\ltfilehookversion{v1.0b}
-\providecommand\ltfilehookdate{2020/09/26}
+\providecommand\ltfilehookdate{2020/10/13}
 %    \end{macrocode}
 %
 %<*driver>
@@ -75,7 +75,7 @@
 %    \ltfilehookversion\ dated \ltfilehookdate, \copyright\ \LaTeX\
 %    Project.}}
 %
-% \author{Frank Mittelbach}
+% \author{Frank Mittelbach, Phelype Oleinik, \LaTeX{} Project Team}
 %
 % \maketitle
 %
@@ -339,9 +339,12 @@
 %
 % \subsection{High-level interfaces for \LaTeX{}}
 %
-%    We do not provide any high-level \LaTeX{} commands (like
-%    \pkg{filehook} or \pkg{scrlfile} do) but think that for package
-%    writers the commands from for hook management are sufficient.
+%    We do not provide any additional wrappers around the hooks (like
+%    \pkg{filehook} or \pkg{scrlfile} do) because we believe that for
+%    package writers the high-level commands from the hook management,
+%    e.g., \cs{AddToHook}, etc.\
+%    are sufficient and in fact easier to work with, given that the hooks
+%    have consistent naming conventions.
 %
 %
 %
diff --git a/base/ltshipout.dtx b/base/ltshipout.dtx
index 8f0422c8..006af1f0 100644
--- a/base/ltshipout.dtx
+++ b/base/ltshipout.dtx
@@ -32,7 +32,7 @@
 %
 %    \begin{macrocode}
 \providecommand\ltshipoutversion{v1.0c}
-\providecommand\ltshipoutdate{2020/09/27}
+\providecommand\ltshipoutdate{2020/10/13}
 %    \end{macrocode}
 %
 %<*driver>
@@ -75,7 +75,7 @@
 %    \ltshipoutversion\ dated \ltshipoutdate, \copyright\ \LaTeX\
 %    Project.}}
 %
-% \author{Frank Mittelbach}
+% \author{Frank Mittelbach, \LaTeX{} Project Team}
 %
 % \maketitle
 %
@@ -229,6 +229,10 @@
 %    \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
@@ -238,10 +242,16 @@
 %    \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}
 %
@@ -356,9 +366,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 apropriate kernel hooks
+%    directly instead of loading the emulation.
 %
 %
 % \subsection{Emulating \pkg{atbegshi}}
@@ -434,6 +450,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 +470,49 @@
 %   \end{syntax}
 % \end{function}
 %
+%    However, most use cases for \pkg{everyshi} are attempts to put
+%    some picture or text into the background or forground 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 coordiates 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  }