[latex3-commits] [git/LaTeX3-latex3-latex3] master: more thoughts on hooks (e7e942b23)

[Frank Mittelbach]

Repository : https://github.com/latex3/latex3
On branch  : master
Link       : https://github.com/latex3/latex3/commit/e7e942b23f86bf0dac31f7f15ea776ff8c106fee

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

commit e7e942b23f86bf0dac31f7f15ea776ff8c106fee
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Sun Jun 30 19:52:48 2019 +0200

    more thoughts on hooks


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

e7e942b23f86bf0dac31f7f15ea776ff8c106fee
 .gitignore                                     |  4 ++
 discussionpapers/2019-06-thoughts-on-hooks.tex | 80 +++++++++++++++++++++++---
 2 files changed, 77 insertions(+), 7 deletions(-)

diff --git a/.gitignore b/.gitignore
index 460896ae3..037602c2b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,3 +20,7 @@ xpackages/xfrontm/*.toc
 *.aux
 *.log
 *.gz
+*.glo
+*.hd
+*.idx
+*.out
diff --git a/discussionpapers/2019-06-thoughts-on-hooks.tex b/discussionpapers/2019-06-thoughts-on-hooks.tex
index 3ab528fa7..e24137732 100644
--- a/discussionpapers/2019-06-thoughts-on-hooks.tex
+++ b/discussionpapers/2019-06-thoughts-on-hooks.tex
@@ -7,8 +7,7 @@
 %                        \and  
   \LaTeX{} Project Team}
 
-%\date{2018-11-29}
-\date{2019-06-24}
+\date{2019-06-30}
 
 \newcounter{hook}
 \newcounter{config}
@@ -31,6 +30,7 @@
 \renewcommand\arg[1]{\textit{#1}}      % don't need the math Op in this document I hope :-)
 
 \usepackage[T1]{fontenc}
+\usepackage{csquotes}
 
 \begin{document}
 
@@ -106,6 +106,12 @@ One could also think of \arg{name} to be optional defaulting to the
 current package/class name to encourage people to use that as the name
 normally.
 
+[2019/06/30] One important aspect not covered above is the question of
+what is stored with respect to \arg{code}. In most cases it should be
+the unexpanded code, but we will also need a version of all commands
+above that stored the expansion (protected expansion) in case values
+current at the time of setup need to be stored.
+
 
 Existing hook interface commands such as \cs{AtBeginDocument} would
 still be supported as follows:
@@ -160,13 +166,56 @@ even if they technically have inputs (like the current page box or the
 \cs{footins} box etc.).
 
 
+
+\subsection{Distinction between configuration points and hooks}
+
+As a rule of thumb, any place where the result of executing \arg{code}
+requires a certain specific outcome then it is normally a
+configuration point and not a general hook, e.g., \enquote{the code
+  write something into a certain box} or \enquote{the code runs a
+  specific set of other code fragments and all it is supposed to do is
+  to decide the order or not run some of them}.  There could be
+excepts and boundary cases but I think as a basic rule this makes
+sense.
+
+In contrast if we don't make any (or not much) assumptions on what
+could be executed and what the side effects are supposed to be then it
+is most likely a general hook.
+
+
+
+
+\subsection{Thoughts on current \texttt{l3hooks} interfaces}
+
+In \texttt{l3hooks} we currently have the following type of interfaces
+that would need some merging with the thoughts above.
+
+\subsubsection{Next viz all (or what is called \enquote{repeated hooks})}
+
+First of all there is the idea of executing some code only once a hook
+is reached the next time, e.g., \enquote{do something on the next
+  page} in contrast to \enquote{do something on every page}. The
+question to resolve here seems to me what is the relationship between
+code of the different types. Probably the easiest way to handle this
+is to execute \enquote{next} code always after \enquote{all} code.
+
+However, is this general enough or is more control needed?
+
+
+\subsubsection{Document viz repeated hooks}
+
+In short I'm not yet convinced that the distinction is useful, is it?
+If so how/why? Example please.
+
+
+
+
 \section{Hooks and config points in various places}
 
-Collected
-are existing \LaTeXe{} hooks (both by the kernel and/or by package) as
-well a hooks that do not exist but would be beneficial to have for one
-or the other reason. As of now it mainly discusses the \LaTeXe{}
-situation.
+In this section we collect existing \LaTeXe{} hooks (both by the
+kernel and/or by package) as well a hooks that do not exist but would
+be beneficial to have for one or the other reason. As of now it mainly
+discusses the \LaTeXe{} situation.
 
 For each hook/config point we document
 \begin{itemize}
@@ -220,6 +269,12 @@ If there are several distinct use cases each could be added using
   If not then my proposal would be to deprecate it in favor of a
   ``normal'' hook at the same place (i.e., implemented as a token
   list) that would fit into the general model outlined above.
+\item
+  [2019/06/30] The current thinking is that the use of a box for
+  storage was mainly done to help preserving space in the early
+  \LaTeXe{} days, so it should be possible to drop that in favor of a
+  hook where the code is stored like any other hook in form of a token
+  list.
 \end{hook}
 
 \begin{hook}{\cs{@outputpage}}{firstshipout}
@@ -241,6 +296,17 @@ If there are several distinct use cases each could be added using
   into both \texttt{firstshipout} and \texttt{shipout}.
 \end{hook}
 
+The above is probably not general enough in the light of what
+\pkg{atbegshi} implements (fill in correct details \ldots{} not done):
+
+\begin{hook}[atbegshi]{\cs{@outputpage}}{shipoutbox}
+\item
+\end{hook}
+
+\begin{hook}[atbegshi]{\cs{@outputpage}}{forgroundshipoutbox}
+\item
+\end{hook}
+
 
 
 \subsubsection{Making columns}