[latex3-commits] [git/LaTeX3-latex3-latex2e] lthooks: adding kern at before/after commands (bccf289f)
Frank Mittelbach
frank.mittelbach at latex-project.org
Sat Jul 11 16:34:20 CEST 2020
Repository : https://github.com/latex3/latex2e
On branch : lthooks
Link : https://github.com/latex3/latex2e/commit/bccf289f24d700069608abfa48c4f85456fafd2f
>---------------------------------------------------------------
commit bccf289f24d700069608abfa48c4f85456fafd2f
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Sat Jul 11 16:34:20 2020 +0200
adding kern at before/after commands
>---------------------------------------------------------------
bccf289f24d700069608abfa48c4f85456fafd2f
base/ltfilehook.dtx | 2 +-
base/lthooks.dtx | 70 +++++++++++++++++++++++++++++++++++++++++++++--------
base/ltshipout.dtx | 39 +++++++++++++++++++----------
3 files changed, 87 insertions(+), 24 deletions(-)
diff --git a/base/ltfilehook.dtx b/base/ltfilehook.dtx
index acee2b3f..9d241053 100644
--- a/base/ltfilehook.dtx
+++ b/base/ltfilehook.dtx
@@ -237,7 +237,7 @@
% Executing code before the final \cs{clearpage}, means that the
% code is processed while the last page of the included material is
% still under construction. Executing code after it means that all
-% floats from inside the include file are placed placed (which
+% floats from inside the include file are placed (which
% might have added further pages) and the final page has finished.
%
% Because of these different scenarios we offer hooks in three
diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index 432278fe..eba27fd7 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -251,7 +251,7 @@
%\begin{verbatim}
% \AddToHook{env/quote/before}{}
%\end{verbatim}
-% because that only \enquote{adds} a further empty chunk of of code to
+% because that only \enquote{adds} a further empty chunk of code to
% the hook. Adding \cs{normalsize} would work but that means the hook
% then contained \cs{small}\cs{normalsize} which means to font size
% changes for no good reason.
@@ -281,7 +281,7 @@
% \end{function}\footnotetext{There is
% no mechanism to reorder such code chunks (or delete them).}
%
-% \subsection{Default labels}
+% \subsubsection{Default labels}
% \label{sec:default-label}
%
% It is best practice to use \cs{AddToHook} in packages or classes
@@ -846,6 +846,41 @@
%
%
%
+% \subsection{Private \LaTeX{} kernel hooks}
+%
+% There are a few places where it is absolutely essential for
+% \LaTeX{} to function correctly that code is executed in a precisely
+% defined order. Even that could have been implemented with the
+% hook management (by adding various rules to ensure the
+% appropriate ordering with respect to other code added by
+% packages). However, this makes every document unnecessary
+% slow, because there has to be sorting even through the result is
+% predetermined. Furthermore it forces package writers to
+% unnecessarily add such rules if they add further code to the hook
+% (or break \LaTeX{}).
+%
+% For that reason such code is not using the hook management, but
+% instead private kernel commands directly before or after a public
+% hook with the following naming
+% convention: \cs{@kernel at before@\meta{hookname}} or
+% \cs{@kernel at after@\meta{hookname}}. For example, in
+% \cs{enddocument} you find
+%\begin{verbatim}
+% \UseHook{enddocument}%
+% \@kernel at after@enddocument
+%\end{verbatim}
+% which means first the user/package-accessible \hook{enddocument}
+% hook is executed and then the internal kernel hook. As their name
+% indicates these kernel commands should not be altered by third-party
+% packages, so please refrain from that in the interest of
+% stability and instead use the public hook next to it.\footnote{As
+% with everything in \TeX{} there is not enforcement of this rule,
+% and by looking at the code it is easy to find out how the kernel
+% adds to them. The main reason of this section is therefore to say
+% \enquote{please don't do that, this is unconfigurable code!}}
+%
+%
+%
% \subsection{Legacy \LaTeXe{} interfaces}
%
% \LaTeXe{} offered a small number of hooks together with commands to
@@ -1041,9 +1076,6 @@
% one.\footnote{We could make \cs{AtEndDocument} just fill the
% \hook{env/document/end} but maybe that is a bit confusing.}
%
-% \fmi{starting to be in favor of dropping it and using the generic
-% one only}
-%
% When this hook is executed there may be still unprocessed
% material (e.g., floats on the deferlist) and the hook may add
% further material to be typeset. After it, \cs{clearpage} is
@@ -3283,7 +3315,7 @@
% \begin{macro}{\document}
%
% \begin{macrocode}
-\expandafter\def\expandafter\document\expandafter{%
+\def\document{%
% \end{macrocode}
% We do cancel the grouping as part of the \cs{begin} handling
% (this is now done inside \cs{begin} instead) so that the
@@ -3294,10 +3326,6 @@
% \end{macrocode}
%
% \begin{macrocode}
- \expandafter\let\csname g__hook_env/document/begin_code_tl\endcsname\@empty
-% \end{macrocode}
-%
-% \begin{macrocode}
\ifx\@unusedoptionlist\@empty\else
\@latex at warning@no at line{Unused global option(s):^^J%
\@spaces[\@unusedoptionlist]}%
@@ -3342,6 +3370,7 @@
% \let\AtBeginDocument\@firstofone
% \@begindocumenthook
\UseOneTimeHook{begindocument}%
+ \@kernel at after@begindocument
% \end{macrocode}
%
% \begin{macrocode}
@@ -3364,10 +3393,24 @@
% \end{macrocode}
%
% \begin{macrocode}
+\let\@kernel at after@begindocument\@empty
% \end{macrocode}
% \end{macro}
%
%
+% \begin{macro}{\@kernel at hook@begindocument}
+%
+% \begin{macrocode}
+\edef\@kernel at hook@begindocument{%
+% \begin{macrocode}
+ \expandafter\let
+ \expandafter\noexpand\csname
+ g__hook_env/document/begin_code_tl\endcsname
+ \noexpand\@empty}
+% \end{macrocode}
+%
+% \end{macrocode}
+% \end{macro}
% \section{Hooks in \cs{enddocument}}
%
%
@@ -3389,9 +3432,11 @@
% \begin{macrocode}
\def\enddocument{%
\UseHook{enddocument}%
+ \@kernel at after@enddocument
\@checkend{document}%
\clearpage
\UseHook{enddocument/afterlastpage}%
+ \@kernel at after@enddocument at afterlastpage
\begingroup
\if at filesw
\immediate\closeout\@mainaux
@@ -3410,6 +3455,11 @@
\UseHook{enddocument/end}%
\deadcycles\z@\@@end}
% \end{macrocode}
+% The two kernel hooks above are used by the shipout code.
+% \begin{macrocode}
+\let\@kernel at after@enddocument\@empty
+\let\@kernel at after@enddocument at afterlastpage\@empty
+% \end{macrocode}
% \end{macro}
%
%
diff --git a/base/ltshipout.dtx b/base/ltshipout.dtx
index 05ab028b..d6e198bd 100644
--- a/base/ltshipout.dtx
+++ b/base/ltshipout.dtx
@@ -17,8 +17,8 @@
% for those people who are interested or want to report an issue.
%
% \begin{macrocode}
-\providecommand\ltshipoutversion{v0.5i}
-\providecommand\ltshipoutdate{2020/07/09}
+\providecommand\ltshipoutversion{v0.6b}
+\providecommand\ltshipoutdate{2020/07/11}
% \end{macrocode}
%
%<*driver>
@@ -679,6 +679,7 @@
%
% \begin{macrocode}
\@@_get_box_size:N \l_shipout_box
+ \@kernel at before@shipout at foreground
\hook_if_empty:nF {shipout/foreground}
{ \@@_add_foreground_picture:n
{ \hook_use:n {shipout/foreground} } }
@@ -701,7 +702,8 @@
{ \hook_if_empty:nF {shipout/lastpage}
{ \@@_debug:n { \typeout{Executing~ lastpage~ hook~
on~ page~ \int_use:N \g_shipout_readonly_int } }
- \_@@_add_foreground_box:n { \UseHook{shipout/lastpage} }
+ \_@@_add_foreground_box:n { \UseHook{shipout/lastpage}
+ \@kernel at after@shipout at lastpage }
}
\bool_gset_true:N \g_@@_lastpage_handled_bool
}
@@ -722,6 +724,15 @@
+% \begin{macro}{\@kernel at after@shipout at lastpage,\@kernel at before@shipout at foreground}
+%
+% \begin{macrocode}
+\let\@kernel at after@shipout at lastpage\@empty
+\let\@kernel at before@shipout at foreground\@empty
+% \end{macrocode}
+% \end{macro}
+
+
% \begin{macro}{\@@_execute_firstpage_hook: }
% This command adds any specials into a box and adds that to the
% very beginning of the first box shipped out. After that we
@@ -996,7 +1007,7 @@
%
% Setting the constants this way is courtesy of Bruno.
% \begin{macrocode}
-\AtBeginDocument{
+\tl_gput_right:Nn \@kernel at after@begindocument {
\tl_const:Nx \c_@@_horigin_tl
{
\cs_if_exist_use:NTF \pdfvariable { horigin }
@@ -1132,11 +1143,11 @@
% \begin{macro}{\enddocument}
+%
% Instead of using the hooks \hook{enddocument} and
-% \hook{enddocument/afterlastpage} we should add this code
-% directly to \cs{enddocument} to avoid cluttering the hooks with
-% data that is always there.
-% \fmi{move into \cs{enddocument}}
+% \hook{enddocument/afterlastpage} we add this code to private
+% kernel hooks to be 100\% when it is executed and to avoid
+% cluttering the hooks with data that is always there.
%
% Inside \cs{enddocument} there is a \cs{clearpage}. Just before
% that we execute this code here. There is a good change that we
@@ -1148,9 +1159,9 @@
% be wrong but then rerunning the document will give us the correct
% value next time around.
%
-% \fmi{move this out of the hook and directly into \cs{enddocument}}
+% \begin{macro}{\@kernel at after@enddocument}
% \begin{macrocode}
-\AddToHook{enddocument}{
+\g at addto@macro \@kernel at after@enddocument {
\int_compare:nNnT \@abspage at last = \maxdimen
{
% \end{macrocode}
@@ -1160,14 +1171,15 @@
}
}
% \end{macrocode}
+% \end{macro}
%
+% \begin{macro}{\@kernel at after@enddocument at afterlastpage}
% Once the \cs{clearpage} has done its work inside \cs{enddocument}
% we know for sure how many pages this document has, so we record
% that in the \texttt{.aux} file for the next run.
%
-% \fmi{move this out of the hook and directly into \cs{enddocument}}
% \begin{macrocode}
-\AddToHook{enddocument/afterlastpage}{
+\g at addto@macro \@kernel at after@enddocument at afterlastpage {
% \end{macrocode}
% There is one special case: If no output is produced then there is
% no point in a) recording the number as 0 will never match the
@@ -1195,7 +1207,7 @@
% \begin{macrocode}
\bool_if:NF \g_@@_lastpage_handled_bool
{ \tex_shipout:D\vbox to\textheight{
- \hbox{\UseHook{shipout/lastpage}}
+ \hbox{\UseHook{shipout/lastpage} \@kernel at after@shipout at lastpage }
% \end{macrocode}
% This extra page could be totally empty except for the hook
% content, but to help the user understanding why it is there we
@@ -1216,6 +1228,7 @@
}
% \end{macrocode}
% \end{macro}
+% \end{macro}
More information about the latex3-commits
mailing list.