[latex3-commits] [git/LaTeX3-latex3-latex3] master: largely empty shell of hook discussion paper (ac7efe7)

[Frank Mittelbach]

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

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

commit ac7efe7351e2d857b6d45b83fc06debf1358f25e
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Mon Nov 26 15:34:15 2018 +0100

    largely empty shell of hook discussion paper


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

ac7efe7351e2d857b6d45b83fc06debf1358f25e
 .gitignore                         |    4 ++
 discussionpapers/2018-11-hooks.tex |   83 ++++++++++++++++++++++++++++++++++++
 discussionpapers/README.md         |   17 ++++++++
 3 files changed, 104 insertions(+)

diff --git a/.gitignore b/.gitignore
index fce3145..460896a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,3 +16,7 @@ xpackages/xfrontm/*.log
 xpackages/xfrontm/*.lot
 xpackages/xfrontm/*.toc
 *.*~
+*.toc
+*.aux
+*.log
+*.gz
diff --git a/discussionpapers/2018-11-hooks.tex b/discussionpapers/2018-11-hooks.tex
new file mode 100644
index 0000000..50888dd
--- /dev/null
+++ b/discussionpapers/2018-11-hooks.tex
@@ -0,0 +1,83 @@
+\documentclass{article}
+
+
+\title{Thoughts on Hooks in code}
+\author{Frank Mittelbach \and
+%                        \and  
+%                        \and  
+  \LaTeX{} Project Team}
+
+\date{2018-11-26}
+
+\newcounter{hook}
+
+\newenvironment{hook}[3][new]  % new/exists, area, name 
+               {\refstepcounter{hook}%
+                 \begin{itemize}\item[\textbf{(\thehook)}]\textbf{#3} (#2/\textit{#1})}
+               {\end{itemize}}
+
+\newcommand\cs[1]{\texttt{\textbackslash #1}}               
+\newcommand\pkg[1]{\texttt{#1}}               
+
+\begin{document}
+
+\maketitle
+
+\tableofcontents
+
+\section{Introduction}
+
+This document collects some thoughts on places for hooks (i.e., code
+interfaces where other code can add material for execution. 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.
+
+For each hook we document
+\begin{itemize}
+\item a ``name'';
+\item the area where it applies;
+\item whether it is ``new'' or does already exist (if so where);
+\item and the major reason why it would be beneficial.
+\end{itemize}
+If there are several distinct use cases each could be added using
+\cs{item}. You can cross reference hooks using
+\cs{label}/\cs{ref}.
+
+
+
+\section{Document structure}
+
+\begin{hook}[kernel]{doc-structure}{begin-document}
+\end{hook}
+
+\begin{hook}[kernel]{doc-structure}{end-document}
+\end{hook}
+
+
+\section{Heading commands}
+
+\begin{hook}{heading}{before-break}
+\item
+  Near deading commands it is helpful if one can issue \cs{mark}
+  commands, e.g. \cs{PutMark} from \pkg{xmarks} to support running
+  header or footer setup. This has to be possible directly after
+  heading title (where it is currently supported through commands like
+  \cs{sectionmark}) but also directly before the break to determine
+  the placement of the heading (e.g., at the very top of a page/column
+  or elsewhere). The mark needs to come after the heading has done its
+  magic with any preceding space, it can't hide such space from the
+  command. In other words it need to happen basically in the middle of
+  \cs{addpenalty}.
+\item
+  For L3 the galley concept might be able to handle this properly, but
+  most likely also need more than one point of code injection.
+\end{hook}
+
+
+%\section{}
+
+%\section{}
+
+\end{document}
diff --git a/discussionpapers/README.md b/discussionpapers/README.md
new file mode 100644
index 0000000..e8a2656
--- /dev/null
+++ b/discussionpapers/README.md
@@ -0,0 +1,17 @@
+# The LaTeX3 Development Repository (discussion papers)
+
+## Overview
+
+This is basically a pool area to dump thoughts (both on L3 as well as
+on 2e and interface to 2e). The pending on how it grows this may get
+split or moved eventually. None of what is discussed here is final or
+should be taken as the direction that we want to take things!
+
+
+## Development team
+
+LaTeX3 is developed by [The LaTeX3 Project](https://latex-project.org).
+
+## Copyright
+
+This README file is copyright 2018 The LaTeX3 Project.