[latex3-commits] [git/LaTeX3-latex3-latex2e] pre_shipout: Housekeeping (1769b7db)

[Marcel Fabian Krüger]

Repository : https://github.com/latex3/latex2e
On branch  : pre_shipout
Link       : https://github.com/latex3/latex2e/commit/1769b7dbdd511922e10e5008bb883cdf3d275378

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

commit 1769b7dbdd511922e10e5008bb883cdf3d275378
Author: Marcel Fabian Krüger <tex at 2krueger.de>
Date:   Wed Jan 6 11:15:17 2021 +0100

    Housekeeping


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

1769b7dbdd511922e10e5008bb883cdf3d275378
 base/changes.txt      |  5 +++++
 base/doc/ltnews33.tex | 11 +++++++++++
 base/ltshipout.dtx    | 15 +++++++++------
 3 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/base/changes.txt b/base/changes.txt
index 487bb2e2..e764fc5c 100644
--- a/base/changes.txt
+++ b/base/changes.txt
@@ -6,6 +6,11 @@ completeness or accuracy and it contains some references to files that
 are not part of the distribution.
 ================================================================================
 
+2021-01-06  Marcel Krüger  <Marcel.Krueger at latex-project.org>
+
+	* ltshipout.dtx:
+	Define and call Lua callback pre_shipout_filter.
+
 2020-12-22  Frank Mittelbach  <Frank.Mittelbach at latex-project.org>
 
 	* ltfssaxes.dtx (subsection{Changing to a new series}):
diff --git a/base/doc/ltnews33.tex b/base/doc/ltnews33.tex
index f3341e7a..0dc75038 100644
--- a/base/doc/ltnews33.tex
+++ b/base/doc/ltnews33.tex
@@ -139,6 +139,17 @@ the name. The coding has now been slightly altered to allow for this.
 \githubissue{427}
 
 
+\subsection{Add a Lua callback to ltshipout to provide a uniform location for applying custom attributes}
+
+Just before shipping out a page, a new Lua\TeX\ callback
+``\texttt{pre_shipout_filter}'' is now called to allow final
+adjustments to the box to be shipped out. This is particularly for
+Lua\TeX\ packages which flag certain elements of the page (e.g. using
+attributes or properties) in order to apply certain effects to these
+elements at shipout. An example for this is the \pkg{luacolor}
+package which could insert the color commands using this callback.
+
+
 
 \subsection{Provide hook in \cs{selectfont}}
 
diff --git a/base/ltshipout.dtx b/base/ltshipout.dtx
index dd38f706..26fad6d2 100644
--- a/base/ltshipout.dtx
+++ b/base/ltshipout.dtx
@@ -31,8 +31,8 @@
 %%% From File: ltshipout.dtx
 %
 %    \begin{macrocode}
-\providecommand\ltshipoutversion{v1.0d}
-\providecommand\ltshipoutdate{2020/12/06}
+\providecommand\ltshipoutversion{v1.0e}
+\providecommand\ltshipoutdate{2021/01/06}
 %    \end{macrocode}
 %
 %<*driver>
@@ -294,14 +294,16 @@
 % \subsection{Provided Lua\TeX\ callbacks}
 % 
 %  \begin{variable}{pre_shipout_filter}
-%    Under Lua\TeX, additionally the \texttt{pre_shipout_filter} callback is
-%    provided. The signature is
+%    Under Lua\TeX{} the \texttt{pre_shipout_filter} Lua callback is
+%    provided which gets called immediately before the shipout primitive gets invoked.
+%    The signature is
 %    \begin{verbatim}
 %     function(<node> head)
-%       return true | false | <node> newhead
+%       return true
 %     end
 %    \end{verbatim}
-%    This callback is invoked after all \TeX-level hooks described above.
+%    The \texttt{head} is the list node corresponding to the box to be shipped out.
+%    The return value should always be \texttt{true}.
 %  \end{variable}
 %
 % \subsection{Information counters}
@@ -609,6 +611,7 @@
 %
 %  \begin{macro}{\@@_finalize_box:}
 %    For Lua\TeX{} invoke the \texttt{pre\_shipout\_filter} callback.
+%  \changes{v1.0e}{2021/01/06}
 %    \begin{macrocode}
 \sys_if_engine_luatex:TF
   {