[latex3-commits] [latex3/latex2e] latexlab/rcb: clean up documentation for latex-lab-new-or-2 (d505589e)
github at latex-project.org
github at latex-project.org
Tue Jul 25 16:52:49 CEST 2023
Repository : https://github.com/latex3/latex2e
On branch : latexlab/rcb
Link : https://github.com/latex3/latex2e/commit/d505589efba0cca0622f91ba3936290fc969f9b4
>---------------------------------------------------------------
commit d505589efba0cca0622f91ba3936290fc969f9b4
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Tue Jul 25 16:52:49 2023 +0200
clean up documentation for latex-lab-new-or-2
>---------------------------------------------------------------
d505589efba0cca0622f91ba3936290fc969f9b4
required/latex-lab/latex-lab-new-or-2.dtx | 193 +++++++++++++++++++++++-------
1 file changed, 153 insertions(+), 40 deletions(-)
diff --git a/required/latex-lab/latex-lab-new-or-2.dtx b/required/latex-lab/latex-lab-new-or-2.dtx
index c219dc9a..b742f44c 100644
--- a/required/latex-lab/latex-lab-new-or-2.dtx
+++ b/required/latex-lab/latex-lab-new-or-2.dtx
@@ -17,8 +17,9 @@
%
% for those people who are interested or want to report an issue.
%
-\def\ltlabneworIIdate{2023-07-20}
-\def\ltlabneworIIversion{0.85a}
+\def\ltlabneworIIdate{2023-07-25}
+\def\ltlabneworIIversion{0.85b}
+
%<*driver>
\documentclass{l3doc}
\EnableCrossrefs
@@ -39,17 +40,25 @@
% \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}}
-% \providecommand\socket[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 replaceable code blocks}
@@ -85,11 +94,15 @@
% \begin{description}
% \item[\cs{@outputbox at append} (1 argument)]
%
+% \DescribeMacro[noprint]{@outputbox at append}
+%
% This general purpose command alters the \cs{@outputbox} box by
% appending material to it.
%
% \item[\cs{@outputbox at appendfootnotes} (0 arguments)]
%
+% \DescribeMacro[noprint]{@outputbox at appendfootnotes}
+%
% This command appends the footnotes to the \cs{@outputbox} (if
% there are any). If not, then it does nothing.
%
@@ -97,17 +110,26 @@
% \item[\cs{@outputbox at attachtopfloats} (0 arguments)]
% \item[\cs{@outputbox at attachbottomfloats} (0 arguments)]
%
+% \DescribeMacro[noprint]{@outputbox at attachfloats}
+% \DescribeMacro[noprint]{@outputbox at attachtopfloats}
+% \DescribeMacro[noprint]{@outputbox at attachbottomfloats}
+%
% Attaching top and bottom floats can usually be done in one
% go, but for special layouts we might want more control so we
% provide also separate commands.
%
% \item[\cs{@outputbox at reinsertbskip} (0 arguments)]
%
+% \DescribeMacro[noprint]{@outputbox at reinsertbskip}
+%
% Reinsert the bottom skip of the \cs{@outputbox} that was
% saved before.
%
% \item[Testing for existence of material]
%
+% \DescribeMacro[noprint]{@if at footnotes@TF}
+% \DescribeMacro[noprint]{@if at 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 at footnotes@TF} and
@@ -115,8 +137,54 @@
% (names are likely to change).
%
% \end{description}
-% This socket cannot be empty but needs appropriate code; a
-% default is already given in the kernel.
+%
+% \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 clases 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.
+%
+% \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}
%
%-----------------------
%
@@ -126,7 +194,10 @@
% 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 pargraph this socket gets
+% the plug \plug{para} assigned which is defined elsewhere.
%
% \end{description}
%
@@ -149,9 +220,9 @@
% \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}
@@ -161,6 +232,8 @@
\def \@makecol {%
% \end{macrocode}
% We start with 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 at before@cclv
% \end{macrocode}
@@ -181,8 +254,8 @@
\xdef\@freelist{\@freelist\@midlist}%
\global \let \@midlist \@empty
% \end{macrocode}
-% Here we have the configurable part. This socket is supposed to add floats and
-% footnotes as appropriate to the \cs{@outputbox}.
+% 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}
\UseSocket{@makecol/outputbox}%
% \end{macrocode}
@@ -256,7 +329,7 @@
% \begin{macro}{\@outputbox at 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
@@ -317,18 +390,20 @@
%
%
%
-% \begin{macro}{\@kernel at before@cclv}
-% \begin{macro}{\@kernel at before@footins}
+% \begin{macro}{\@kernel at before@cclv,
+% \@kernel at before@footins}
% These two commands are internal kernel hooks intended for tagging
% 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 at before@cclv{}
\providecommand\@kernel at before@footins{}
% \end{macrocode}
% \end{macro}
-% \end{macro}
%
%
%
@@ -377,7 +452,7 @@
% 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 socket 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 at handlesplitfootnotes
% \end{macrocode}
@@ -389,13 +464,22 @@
% \begin{macrocode}
\@outputbox at 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 at before@footins
+% \end{macrocode}
+%
+% \begin{macrocode}
\color at 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 at current\endcsname
\unvbox \footins
@@ -461,7 +545,7 @@
%
%
%
-% \begin{macro}{@makecol/footnote}
+% \begin{socketdecl}{@makecol/footnote}
%
% The socket allowing the manipulation of \cs{footins} box
% (result needs to be moved back in there). Used when footnotes are
@@ -470,8 +554,7 @@
% \begin{macrocode}
\NewSocket{@makecol/footnotes}{0}
% \end{macrocode}
-%
-% \end{macro}
+% \end{socketdecl}
%
%
%
@@ -523,20 +606,23 @@
% \subsection{The \cs{@makecol} configuration}
%
%
-% \begin{macro}{@makecol/outputbox}
+% \begin{socketdecl}{@makecol/outputbox}
% We have one socket that is supposed to augment the \cs{@outputbox}
-% by attching floats and footnotes with appropriate spacing.
+% by attaching floats and footnotes with appropriate spacing.
%
% \begin{macrocode}
\NewSocket{@makecol/outputbox}{0}
% \end{macrocode}
-% \end{macro}
+% \end{socketdecl}
%
-% The following replaceable code alternatives are available for
+% 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} {%
+\NewSocketPlug {@makecol/outputbox}{space-footnotes-floats} {%
\@if at footnotes@TF
{\@outputbox at append{\vfill}}%
{\@if at bfloats@TF
@@ -547,9 +633,13 @@
\@outputbox at attachfloats
}
% \end{macrocode}
+% \end{plugdecl}
%
+% \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} {%
+\NewSocketPlug {@makecol/outputbox}{floats-footnotes-space} {%
\@outputbox at attachfloats
\@if at footnotes@TF
{\@outputbox at append{\vfill}}%
@@ -557,7 +647,10 @@
\@outputbox at appendfootnotes
}
% \end{macrocode}
+% \end{plugdecl}
%
+% \begin{plugdecl}{footnotes-space-floats}
+% As before but the \cs{vfill} is between footnotes and floats.
% \begin{macrocode}
\NewSocketPlug {@makecol/outputbox}{footnotes-space-floats} {%
\@outputbox at appendfootnotes
@@ -567,7 +660,13 @@
\@outputbox at attachfloats
}
% \end{macrocode}
+% \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 at footnotes@TF
@@ -579,19 +678,19 @@
\@outputbox at 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 at attachfloats
\@outputbox at appendfootnotes
- \@outputbox at reinsertbskip
-}
-% \end{macrocode}
-%
-% \begin{macrocode}
-\NewSocketPlug {@makecol/outputbox}{footnotes-floats} {%
- \@outputbox at appendfootnotes
- \@outputbox at attachfloats
% \end{macrocode}
% We do reinsert the bottom skip from \cs{newpage} if it
% was taken out earlier. This is, strictly speaking, not necessary
@@ -603,12 +702,25 @@
\@outputbox at reinsertbskip
}
% \end{macrocode}
-% The \texttt{footnote-floats} one is is the default used by
-% \LaTeX{}, it can be overwritten either through \pkg{footmisc} or
-% by assigning any of the other replaceable block code chunks.
+%
+% \end{plugdecl}
+%
+% \begin{plugdecl}{footnotes-floats}
+% \begin{macrocode}
+\NewSocketPlug {@makecol/outputbox}{footnotes-floats} {%
+ \@outputbox at appendfootnotes
+ \@outputbox at attachfloats
+ \@outputbox at 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}
%
%
%
@@ -626,6 +738,7 @@
%
% \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}
More information about the latex3-commits
mailing list.