[latex3-commits] [git/LaTeX3-latex3-latex2e] docu: document that shipout/before and /after are not for typesetting material that is returned to the main galley (6a34a75a)

[Frank Mittelbach]

Repository : https://github.com/latex3/latex2e
On branch  : docu
Link       : https://github.com/latex3/latex2e/commit/6a34a75a7fbdea04a123c6fec00204c3c21580e7

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

commit 6a34a75a7fbdea04a123c6fec00204c3c21580e7
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Mon Jan 25 23:26:02 2021 +0100

    document that shipout/before and /after are not for typesetting material that is returned to the main galley


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

6a34a75a7fbdea04a123c6fec00204c3c21580e7
 base/ltshipout.dtx | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/base/ltshipout.dtx b/base/ltshipout.dtx
index ac66c68e..565f35f5 100644
--- a/base/ltshipout.dtx
+++ b/base/ltshipout.dtx
@@ -33,7 +33,7 @@
 %
 %    \begin{macrocode}
 \providecommand\ltshipoutversion{v1.0i}
-\providecommand\ltshipoutdate{2021/01/22}
+\providecommand\ltshipoutdate{2021/01/25}
 %    \end{macrocode}
 %
 %<*driver>
@@ -195,6 +195,16 @@
 %       cases. It can make use of \cs{ShipoutBox} (which doesn't yet
 %       include the background and foreground material).
 %
+%       \textbf{Note:} It is not possible (or say advisable) to try
+%       and use this hook to typeset material with the intention to
+%       return it to main vertical list, it will go wrong and give
+%       unexpected results in many cases---for starters it will appear
+%       after the current page not before or it will vanish or the
+%       vertical spacing will be wrong!
+%    \end{description}
+%  \end{variable}
+%
+%    \begin{description}
 %    \item[\hook{shipout/background}]
 %
 %       This hook adds a picture environment into the background of
@@ -233,6 +243,9 @@
 %       not discarded at the last minute). It should only contain
 %       \cs{special} or similar commands needed to direct post processors
 %       handling the \texttt{.dvi} or \texttt{.pdf} output.\footnotemark
+%  \footnotetext{In
+%         \LaTeXe{} that was already existing, but implemented using a box
+%         register with the name \cs{@begindvibox}.}
 %
 %       ^^A \fmi{not sure it has to be that restrictive.}
 %
@@ -263,11 +276,13 @@
 %       point (but in contrast to \hook{shipout/before} it now
 %       includes the background and foreground material).
 %
+%       \textbf{Note:} Just like \hook{shipout/before} this hook is
+%       not meant to be used for adding adding typeset material back
+%       to the main vertical list---it might vanish or the
+%       vertical spacing will be wrong!
+%
 %
 %    \end{description}
-%  \end{variable}\footnotetext{In
-%         \LaTeXe{} that was already existing, but implemented using a box
-%         register with the name \cs{@begindvibox}.}
 %
 %    As mentioned above the hook \hook{shipout/before} is executed
 %    first and can manipulate the prepared shipout box stored in