summaryrefslogtreecommitdiff
path: root/macros/latex-dev/required/latex-lab/latex-lab-new-or-2.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex-dev/required/latex-lab/latex-lab-new-or-2.dtx')
-rw-r--r--macros/latex-dev/required/latex-lab/latex-lab-new-or-2.dtx341
1 files changed, 274 insertions, 67 deletions
diff --git a/macros/latex-dev/required/latex-lab/latex-lab-new-or-2.dtx b/macros/latex-dev/required/latex-lab/latex-lab-new-or-2.dtx
index 74d56d687f..d2011256b1 100644
--- a/macros/latex-dev/required/latex-lab/latex-lab-new-or-2.dtx
+++ b/macros/latex-dev/required/latex-lab/latex-lab-new-or-2.dtx
@@ -1,7 +1,7 @@
% \iffalse meta-comment
%
%% File: latex-lab-new-or-2.dtx
-% Copyright (C) 2022 The LaTeX Project
+% Copyright (C) 2022-2023 The LaTeX Project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
@@ -17,6 +17,9 @@
%
% for those people who are interested or want to report an issue.
%
+\def\ltlabneworIIdate{2023-09-04}
+\def\ltlabneworIIversion{0.85c}
+
%<*driver>
\documentclass{l3doc}
\EnableCrossrefs
@@ -31,41 +34,58 @@
%
% \title{The \texttt{latex-lab-testphase-new-or-2} code\thanks{}}
% \author{Frank Mittelbach, \LaTeX{} Project}
-%
+% % \date{v\ltlabneworIIversion\ \ltlabneworIIdate}
% \maketitle
%
% \newcommand\fmi[1]{\begin{quote} TODO: \itshape #1\end{quote}}
% \newcommand\NEW[1]{\marginpar{\mbox{}\hfill\fbox{New: #1}}}
% \providecommand\pkg[1]{\texttt{#1}}
%
+% \providecommand\hook[1]{\texttt{#1\DescribeHook[noprint]{#1}}}
+% \providecommand\socket[1]{\texttt{#1\DescribeSocket[noprint]{#1}}}
+% \providecommand\plug[1]{\texttt{#1\DescribePlug[noprint]{#1}}}
+%
+% \NewDocElement[printtype=\textit{socket},idxtype=socket,idxgroup=Sockets]{Socket}{socketdecl}
+% \NewDocElement[printtype=\textit{plug},idxtype=plug,idxgroup=Plugs]{Plug}{plugdecl}
+% \NewDocElement[printtype=\textit{hook},idxtype=hook,idxgroup=Hooks]{Hook}{hookdecl}
+%
+%
% \begin{abstract}
+% This code implements changes to the output routine intended to be
+% moved in the \LaTeX{} kernel at some point in the future.
% \end{abstract}
%
-% \section{Introduction}
-%
-% This code implements changes to the output routine.
%
%
%
+% \section{Introduction}
%
-% \section{Hooks and configuration points}
%
-% Note: the configuration points do not have an interface mechanism
-% yet and all their names are temporary right now.
+% \section{Hooks and replaceable code blocks}
%
%
-% \subsubsection{Configuration points}
+% \subsubsection{Replaceable code blocks (sockets)}
%
% To cater for different layouts with respect to text, footnotes,
-% and bottom-floats placements there are two configuration points for
+% and bottom-floats placements there are two sockets for
% now.
% \begin{description}
-% \item[\cs{@makecol@cfgpoint} (0 arguments)]
+% \item[\socket{@makecol/outputbox} (0 arguments)]
%
-% In this configuration point the \cs{@outputbox} (holding the
+% In code for this socket the \cs{@outputbox} (holding the
% galley text for the current column or page) is augmented by
% attaching floats and footnote areas together with appropriate
-% spacing. Before the code is run any existing glue at the bottom
+% spacing.
+%
+% Prior to calling the socket the output routine has already
+% decided which floats go into which area and which get deferred.
+% Therefore, the assumption is that the code in the socket attaches all
+% areas that contain floats. If this is not done, then the order
+% of floats is likely to be screwed up unless unused floats
+% are moved to the defer list in an appropriate way (for now we
+% don't offer any interface for that scenario).
+%
+% Before the code in the socket is run, any existing glue at the bottom
% of the \cs{@outputbox} is removed and stored in a safe
% place. If needed, it can be reinserted with one of the helper
% commands.
@@ -74,17 +94,25 @@
% \begin{description}
% \item[\cs{@outputbox@append} (1 argument)]
%
+% \DescribeMacro[noprint]{@outputbox@append}
+%
% This general purpose command alters the \cs{@outputbox} box by
% appending material to it.
%
% \item[\cs{@outputbox@appendfootnotes} (0 arguments)]
%
+% \DescribeMacro[noprint]{@outputbox@appendfootnotes}
+%
% This command appends the footnotes to the \cs{@outputbox} (if
% there are any). If not, then it does nothing.
%
% \item[\cs{@outputbox@attachfloats} (0 arguments)]
% \item[\cs{@outputbox@attachtopfloats} (0 arguments)]
% \item[\cs{@outputbox@attachbottomfloats} (0 arguments)]
+%
+% \DescribeMacro[noprint]{@outputbox@attachfloats}
+% \DescribeMacro[noprint]{@outputbox@attachtopfloats}
+% \DescribeMacro[noprint]{@outputbox@attachbottomfloats}
%
% Attaching top and bottom floats can usually be done in one
% go, but for special layouts we might want more control so we
@@ -92,11 +120,16 @@
%
% \item[\cs{@outputbox@reinsertbskip} (0 arguments)]
%
+% \DescribeMacro[noprint]{@outputbox@reinsertbskip}
+%
% Reinsert the bottom skip of the \cs{@outputbox} that was
% saved before.
%
% \item[Testing for existence of material]
%
+% \DescribeMacro[noprint]{@if@footnotes@TF}
+% \DescribeMacro[noprint]{@if@bfloats@TF}
+%
% There are a number of helpers to run conditional code
% depending on whether or not there are footnotes or bottom
% floats. They are \cs{@if@footnotes@TF} and
@@ -104,16 +137,67 @@
% (names are likely to change).
%
% \end{description}
-% This configuration point needs an appropriate definition; a
-% default is already given in the kernel.
%
-% \item[\cs{@makecol@cfgpointii} (0 arguments)]
+% \fmi{Decide on names for these helper commands. We could keep
+% them similar to the above (because they are only supposed to be
+% used by a few packages). However, we could alternatively use
+% CamelCase names, under the assumption that classes may also
+% directly define a plug for the socket, instead of loading a
+% support package such as \pkg{footmisc} (or in addition
+% to). --- decide}
+%
+% This socket cannot be empty but needs appropriate code; a set
+% of suitable plugs for it are already given in the kernel. These
+% are
+% \begin{description}
+% \item[\plug{space-footnotes-floats}]
+%
+% After the galley text there is a vertical \cs{vfill}
+% followed by any footnotes followed by the bottom floats, if any.
+%
+% \item[\plug{floats-footnotes-space}]
+%
+% As before but the \cs{vfill} is at the bottom (page is
+% ragged bottom).
+%
+% \item[\plug{footnotes-space-floats}]
+%
+% As before but the \cs{vfill} is between footnotes and floats.
%
-% This configuration point is used to manipulate the footnote
+% \item[\plug{space-floats-footnotes}]
+%
+% Here the footnotes come last.\footnote{There are two more
+% permutations, but neither of them has ever been requested so
+% they aren't set up by default --- doing that in a class
+% would be trivial though.}
+%
+% \item[\plug{floats-footnotes}]
+%
+% All excess space has to be distributed across the existing
+% glue on the page, e.g., within the text galley, the
+% separation between blocks, etc.
+% The order is text, floats, footnotes.
+%
+% \item[\plug{footnotes-floats}]
+%
+% As the previous one but floats and footnotes are
+% swapped. This is the \LaTeX{} default, i.e., this plug is
+% assigned to the socket.
+%
+% \end{description}
+%
+%-----------------------
+%
+% \item[\socket{@makecol/footnotes} (0 arguments)]
+%
+% This socket is used to manipulate the footnote
% material inside \cs{box}\cs{footins}. It if contains code, it
% is supposed to do some processing of that box and then write
% the result back into it (and nothing else!). By default it
-% does nothing.
+% does nothing, i.e., has the \plug{noop} assigned.
+%
+% If (short) footnotes are run as a paragraph this socket gets
+% the plug \plug{para} assigned which is defined elsewhere.
%
% \end{description}
%
@@ -123,28 +207,32 @@
% \section{The Implementation}
%
% \begin{macrocode}
-%<*code>
+%<*package>
% \end{macrocode}
%
% \subsection{File declaration}
% \begin{macrocode}
\ProvidesPackage{latex-lab-testphase-new-or-2}
- [2022-11-04 v0.1c changes to the output routine]
+ [\ltlabneworIIdate\space v\ltlabneworIIversion\space
+ Changes to the output routine]
% \end{macrocode}
+%
% \subsection{\cs{@makecol} reimplementation}
%
% In order for other packages to prepend or append code to
-% \cs{@makecol}, they can use the generic command hooks
-% \texttt{cmd/@makecol/before} and \texttt{cmd/@makecol/after}, so
-% there is nothing we need to do here.
+% \cs{@makecol} the generic command hooks
+% \texttt{cmd/@makecol/before} and \texttt{cmd/@makecol/after} can
+% be used, so for now there is nothing we need to do for this.
%
%
% \begin{macro}{\@makecol}
% \cs{@makecol} is shortened a lot, basically all the hardwired
-% code in the middle has moved into a configuration point.
+% code in the middle has moved into a socket.
% \begin{macrocode}
\def \@makecol {%
- \@kernel@before@cclv
+% \end{macrocode}
+% Save away box 255 as \cs{@outputbox} to make it available for further adjustments.
+% \begin{macrocode}
\setbox\@outputbox \box\@cclv
% \end{macrocode}
% The only real addition is the next command which either does
@@ -153,25 +241,31 @@
% \begin{macrocode}
\@outputbox@removebskip
% \end{macrocode}
-% Any ``here'' floats in the \cs{@outputbox} are now handled so we
+% Now a kernel hook for tagging.
+% \fmi{The name is likely to change and it probably will eventually
+% be replaced with a socket.}
+% \begin{macrocode}
+ \@kernel@tagsupport@@makecol
+% \end{macrocode}
+% When this code is run any ``here'' floats in the \cs{@outputbox} are already handled, so we
% recycle their registers and put them back to the \cs{@freelist}.
% \begin{macrocode}
\let\@elt\relax
\xdef\@freelist{\@freelist\@midlist}%
\global \let \@midlist \@empty
% \end{macrocode}
-% Here we have the configurable part.
-% \fmi{Interface to configuration points will change in the future}
+% Here we have the configurable part. This socket is supposed to add floats,
+% footnotes and stretchable vertical space as appropriate to the \cs{@outputbox}.
% \begin{macrocode}
- \@makecol@cfgpoint
+ \UseSocket{@makecol/outputbox}%
% \end{macrocode}
-% The we deal with any \cs{enlargethispage} or run the normal code
+% Then we deal with any \cs{enlargethispage} or run the normal code
% to build a column.
% \begin{macrocode}
\ifvbox\@kludgeins
- \@makespecialcolbox
+ \@make@specialcolbox
\else
- \@makenormalcolbox
+ \@make@normalcolbox
\fi
\global \maxdepth \@maxdepth
}
@@ -188,10 +282,10 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\@makenormalcolbox}
+% \begin{macro}{\@make@normalcolbox}
% Taken out of \cs{@makecol} for readability.
% \begin{macrocode}
-\def \@makenormalcolbox {%
+\def \@make@normalcolbox {%
\setbox\@outputbox \vbox to\@colht {%
\@texttop
\@outputbox@depth \dp\@outputbox
@@ -204,10 +298,10 @@
% \end{macro}
%
%
-% \begin{macro}{\@makespecialcolbox}
+% \begin{macro}{\@make@specialcolbox}
% Make the colbox when \cs{enlargethispage} was used.
% \begin{macrocode}
-\def \@makespecialcolbox {%
+\def \@make@specialcolbox {%
\@outputbox@append {\vskip-\@outputbox@depth}%
\@tempdima \@colht
\ifdim \wd\@kludgeins>\z@
@@ -235,7 +329,7 @@
% \begin{macro}{\@outputbox@removebskip}
%
% This is really a bug fix for the kernel but one we only
-% automatically make in new documents using \cs{DocumentMetadata}.
+% automatically make in new documents that are using \cs{DocumentMetadata}.
% \fmi{may make optional for legacy docs}
% If
% \cs{raggedbottom} is in force, footnotes get attached to the main
@@ -248,7 +342,7 @@
% short, but the footnotes are not pushed to the bottom.
%
% In \pkg{footmisc} \cs{@outputbox@removebskip} is only applied when
-% \pkg{footmisc} is called with with an option specifying the
+% \pkg{footmisc} is called with an option specifying the
% footnote placement, i.e., not in the default case.
% In new documents we apply it always.
% \begin{macrocode}
@@ -270,6 +364,7 @@
\ifnum \gluestretchorder\@tempskipa>\z@
\vskip-\@tempskipa
% \end{macrocode}
+%
% \begin{macro}{\@outputbox@reinsertbskip}
% We also record the value so that it can be reinserted
% elsewhere. As we have to do this globally, we also need to
@@ -295,25 +390,28 @@
%
%
%
-% \begin{macro}{\@kernel@before@cclv}
-% \begin{macro}{\@kernel@before@footins}
+% \begin{macro}{\@kernel@before@cclv,
+% \@kernel@before@footins}
% These two commands are internal kernel hooks intended for tagging
-% support in case that is active. By default they do nothing (and
+% support in case that is active. They should not be altered by package code!
+% By default they do nothing (and
% may have been defined already by \cs{DocumentMetadata}).
+% \fmi{The names might change and perhaps each of them is turned
+% into a socket named something like \socket{tagsupport/before/cclv}
+% or similar.}
% \begin{macrocode}
\providecommand\@kernel@before@cclv{}
\providecommand\@kernel@before@footins{}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
%
%
%
% \subsection{The output routine configuration components}
%
-% Here we provide the components that are used to define
-% \cs{@makecol@cfgpoint}.
+% Here we provide the components that are used to define code for the
+% \socket{@makecol/outputbox} socket.
%
%
% \begin{macro}{\@outputbox@append}
@@ -346,7 +444,7 @@
% \begin{macro}{\@outputbox@appendfootnotes}
%
% This command appends the footnotes to the \cs{@outputbox} (if
-% there are any). If not then it does nothing.
+% there are any). If not, then it does nothing.
% \begin{macrocode}
\def\@outputbox@appendfootnotes {%
\ifvoid\footins \else
@@ -354,22 +452,34 @@
% First come two configuration points: what to do if we are in a split
% footnote situation and a second one that does some manipulation
% of the \cs{footins} box before it gets appended.
-% \fmi{this code will get revised as part of CP handling in the future}
+% \fmi{The code for handling split footnotes will get revised as part of socket handling in the future}
% \begin{macrocode}
\@makecol@handlesplitfootnotes
- \@makecol@cfgpointii
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \UseSocket{@makecol/footnotes}%
% \end{macrocode}
% Then the footnotes are appended:
% \begin{macrocode}
\@outputbox@append{%
\vskip \skip\footins
+% \end{macrocode}
+% This is a kernel hook for tagging.
+% \fmi{The name is likely to change and it probably will eventually
+% be replaced with a socket.}
+% \begin{macrocode}
\@kernel@before@footins
+% \end{macrocode}
+%
+% \begin{macrocode}
\color@begingroup
\normalcolor
\footnoterule
% \end{macrocode}
% Support for \pkg{pdfcolfoot}, eventually this can go once color
-% is properly supported.
+% is properly supported. The csname is constructed in case it
+% doesn't exist.
% \begin{macrocode}
\csname pdfcolfoot@current\endcsname
\unvbox \footins
@@ -435,17 +545,16 @@
%
%
%
-% \begin{macro}{\@makecol@cfgpointii}
+% \begin{socketdecl}{@makecol/footnote}
%
-% Configuration point to support manipulation of footins box
-% (result needs to be moved back in there). Used by the
-% \texttt{para} option.
-% \fmi{Interface will change in the future}
+% The socket allowing the manipulation of \cs{footins} box
+% (result needs to be moved back in there). Used when footnotes are
+% reformatted into a single paragraph by the
+% \texttt{para} option of \pkg{footmisc}. By default it does nothing.
% \begin{macrocode}
-\let \@makecol@cfgpointii \@empty
+\NewSocket{@makecol/footnotes}{0}
% \end{macrocode}
-%
-% \end{macro}
+% \end{socketdecl}
%
%
%
@@ -497,27 +606,124 @@
% \subsection{The \cs{@makecol} configuration}
%
%
-% \begin{macro}{\@makecol@cfgpoint}
+% \begin{socketdecl}{@makecol/outputbox}
+% We have one socket that is supposed to augment the \cs{@outputbox}
+% by attaching floats and footnotes with appropriate spacing.
+%
+% \begin{macrocode}
+\NewSocket{@makecol/outputbox}{0}
+% \end{macrocode}
+% \end{socketdecl}
+%
+% The following plugs are available for
+% this socket:
+%
+% \begin{plugdecl}{space-footnotes-floats}
+% After the galley text there is a vertical \cs{vfill} followed by
+% any footnotes followed by the bottom floats, if any.
+% \begin{macrocode}
+\NewSocketPlug {@makecol/outputbox}{space-footnotes-floats} {%
+ \@if@footnotes@TF
+ {\@outputbox@append{\vfill}}%
+ {\@if@bfloats@TF
+ {\@outputbox@append{\vfill}}%
+ {\@outputbox@reinsertbskip}%
+ }%
+ \@outputbox@appendfootnotes
+ \@outputbox@attachfloats
+}
+% \end{macrocode}
+% \end{plugdecl}
%
-% Here is only the configuration for the default case for now,
-% others are provided by \pkg{footmisc}.
+% \begin{plugdecl}{floats-footnotes-space}
+% As before but the \cs{vfill} is at the bottom (page is ragged
+% bottom).
+% \begin{macrocode}
+\NewSocketPlug {@makecol/outputbox}{floats-footnotes-space} {%
+ \@outputbox@attachfloats
+ \@if@footnotes@TF
+ {\@outputbox@append{\vfill}}%
+ {\@outputbox@reinsertbskip}%
+ \@outputbox@appendfootnotes
+}
+% \end{macrocode}
+% \end{plugdecl}
%
+% \begin{plugdecl}{footnotes-space-floats}
+% As before but the \cs{vfill} is between footnotes and floats.
% \begin{macrocode}
- \def\@makecol@cfgpoint {%
- \@outputbox@appendfootnotes
- \@outputbox@attachfloats
+\NewSocketPlug {@makecol/outputbox}{footnotes-space-floats} {%
+ \@outputbox@appendfootnotes
+ \@if@bfloats@TF
+ {\@outputbox@append{\vfill}}%
+ {\@outputbox@reinsertbskip}%
+ \@outputbox@attachfloats
+}
% \end{macrocode}
-% We do, however, reinsert the bottom skip from \cs{newpage} if it
+% \end{plugdecl}
+%
+% \begin{plugdecl}{space-floats-footnotes}
+% Here the footnotes come last.\footnote{There are two more
+% permutations, but neither of them has ever been requested so
+% they aren't set up by default --- doing that in a class
+% would be trivial though.}
+% \begin{macrocode}
+\NewSocketPlug {@makecol/outputbox}{space-floats-footnotes} {%
+ \@if@footnotes@TF
+ {\@outputbox@append{\vfill}}%
+ {\@if@bfloats@TF
+ {\@outputbox@append{\vfill}}%
+ {\@outputbox@reinsertbskip}}%
+ \@outputbox@attachfloats
+ \@outputbox@appendfootnotes
+}
+% \end{macrocode}
+% \end{plugdecl}
+%
+%
+%
+% \begin{plugdecl}{floats-footnotes}
+% All excess space has to be distributed across the existing
+% glue on the page, e.g., within the text galley, the
+% separation between blocks, etc.
+% The order is text, floats, footnotes.
+% \begin{macrocode}
+\NewSocketPlug {@makecol/outputbox}{floats-footnotes} {%
+ \@outputbox@attachfloats
+ \@outputbox@appendfootnotes
+% \end{macrocode}
+% We do reinsert the bottom skip from \cs{newpage} if it
% was taken out earlier. This is, strictly speaking, not necessary
% in most cases, but it is a \cs{vfil} while \cs{raggedbottom} is
% only generating \verb=\vspace{0pt plus .0001fil}=, so if you have
% several \cs{vfil} on the page before the \cs{newpage} you would
% alter the space distribution if one is taken out.
% \begin{macrocode}
- \@outputbox@reinsertbskip
- }
+ \@outputbox@reinsertbskip
+}
% \end{macrocode}
-% \end{macro}
+%
+% \end{plugdecl}
+%
+% \begin{plugdecl}{footnotes-floats}
+% \begin{macrocode}
+\NewSocketPlug {@makecol/outputbox}{footnotes-floats} {%
+ \@outputbox@appendfootnotes
+ \@outputbox@attachfloats
+ \@outputbox@reinsertbskip
+}
+% \end{macrocode}
+% The \texttt{footnote-floats} plug is the default used by
+% \LaTeX{}; it can be overwritten either through \pkg{footmisc} or
+% by assigning any of the other plugs (or by coding yet another
+% plug for the socket).
+% \begin{macrocode}
+\AssignSocketPlug {@makecol/outputbox}{footnotes-floats}
+% \end{macrocode}
+% \end{plugdecl}
+%
+%
+%
%
%
% \section {Replacement for the \pkg{footmisc} package}
@@ -532,13 +738,14 @@
%
% \section {Temp stuff that is related but should go to the kernel}
%
+% This is the code from \texttt{latex-lab-footnotes.dtx}.
% \begin{macrocode}
\input{latex-lab-footnotes.ltx}
% \end{macrocode}
%
%
% \begin{macrocode}
-%</code>
+%</package>
% \end{macrocode}
%
% \Finale