Merge branch 'develop' into or-consolidation-integrate

base/doc/clsguide.tex

@@ -34,15 +34,15 @@
 \usepackage{csquotes}
 
 \title{\LaTeX\ for package and class authors\\current version}
-\author{\copyright~Copyright 2023--2024, \LaTeX\ Project Team.\\
+\author{\copyright~Copyright 2023--2025, \LaTeX\ Project Team.\\
    All rights reserved.%
    \footnote{This file may distributed and/or modified under the
      conditions of the \LaTeX{} Project Public License, either version 1.3c
      of this license or (at your option) any later version. See the source
     \texttt{clsguide.tex} for full details.}%
 }
 
-\date{2024-11-27}
+\date{2025-02-17}
 
 \NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}}
 \NewDocumentCommand\marg{m}{\arg{#1}}
@@ -55,6 +55,12 @@
 \makeatother
 \providecommand\url[1]{\texttt{#1}}
 
+\providecommand\hook[1]{\texttt{#1}}
+\providecommand\socket[1]{\texttt{#1}}
+\providecommand\plug[1]{\texttt{#1}}
+
+
+
 \begin{document}
 
 \maketitle
@@ -1450,6 +1456,118 @@ \subsection{Preparing link targets}
 \end{decl}
 This changes the name of the next target that will be created.
 
+
+\section{Configuring the Output routine}
+
+For nearly 40 years \LaTeX's output routine (the mechanism to paginate
+the document and attach footnotes, floats and headers \& footers) was
+a largely hardwired algorithm with a limited number of configuration
+possibilities.  Packages or classes that attempted to alter one or the
+other aspect of the process had to overwrite the internals with the
+usual problems: incompatibilities and out of date code whenever
+something was changed in \LaTeX{}.
+
+To improve this situation and to support the production of accessible
+PDF documents we started in 2024 to refactor the output routine and
+have added a number of hooks and sockets, so that packages that want
+to adjust the output routine can do so safely without the dangers
+associated with that in the past.
+
+For packages, we implemented the following hooks:
+\begin{description}
+\item[\hook{build/page/before}, \hook{build/page/after}]
+   These two hooks enable packages to prepend or append code to
+   the page processing in the output routine. They are
+   implemented as mirrored hooks.
+
+   Technically, they are executed at the start and the end of the
+   internal \LaTeXe{} \cs{@outputpage} command, respectively.  A
+   number of packages alter that command to place code in exactly
+   these two places---they can now simply add their code to the
+   hooks instead.
+
+\item[\hook{build/page/reset}]
+   Packages that set up special conventions for text in the main
+   galley (such as catcode changes, etc.)\ can use this hook to
+   undo these changes within the output routine, so that they
+   aren't applied to unrelated material, e.g., the text for
+   running header or footers.
+
+\item[\hook{build/column/before}, \hook{build/column/after}]
+   These two hooks enable packages to prepend or append code to
+   the column processing in the output routine. They are
+   implemented as mirrored hooks.
+
+   Technically, they are executed at the start and the end of the
+   internal \LaTeXe{} \cs{@makecol} command, respectively.  A
+   number of packages alter \cs{@makecol} to place code in exactly
+   these two places---they can now simply add their code to the
+   hooks instead.
+\end{description}
+
+We also added a number of sockets for configuring the algorithm and to
+support tagging. One socket that is of interest for class files but
+also for user in the document preamble is
+\socket{build/column/outputbox}. It defines how the column text, the
+column floats (top and bottom) and the footnotes are combined,
+i.e. their order and spacing. To change the layout all one has to do
+is to assign a different predefined plug to the socket with
+\begin{flushleft}
+  \verb= \AssignSocketPlug{build/column/outputbox}{=\meta{plug-name}\verb=}=
+\end{flushleft}
+The predeclared plugs are the following:
+\begin{description}
+\item[\plug{space-footnotes-floats}]
+
+   After the galley text there is a vertical \cs{vfill}
+   followed by the footnotes, followed by the bottom floats, if any.
+
+\item[\plug{floats-footnotes-space}]
+
+   As before but the \cs{vfill} is at the bottom (the 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 is 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 for newer documents, i.e., this plug is
+   assigned to the socket when \cs{DocumentMetadata} is used.
+
+\item[\plug{footnotes-floats-legacy}]
+
+   As the previous one but \LaTeX{}'s bottom skip bug is not
+   corrected, i.e., in ragged bottom designs where footnotes
+   are supposed to be directly attached to the text, they suddenly
+   appear at the bottom of the page when the page is ended with
+   \cs{newpage} or \cs{clearpage}.
+   While this is clearly a bug, it was the case since the days
+   of \LaTeX~2.09; thus for
+   compatibility we continue to support this behavior.
+\end{description}
+There are a few more configuration possibilities but they are so
+specialized that we have only documented them in the \LaTeX{} source
+in chapter 54 (which can be viewed with \texttt{texdoc source2e}).
+
+
+
 \section{Commands superseded for new material}
 
 A small number of commands were introduced as part of \LaTeXe{} in the

base/doc/ltnews41.tex

@@ -201,7 +201,7 @@ \section{Configurable output routine}
 To improve this situation and to support the production of accessible
 PDF documents we started to refactor the output routine and added a
 number of hooks and sockets, so that packages that want to adjust the
-output routine can do so safely with out the dangers associated with
+output routine can do so safely without the dangers associated with
 that in the past.
 
 For packages, we implemented the following hooks:

base/ltoutput.dtx

@@ -37,7 +37,7 @@
 %<*driver>
 % \fi
 \ProvidesFile{ltoutput.dtx}
-             [2025/02/15 v1.4m LaTeX Kernel (Output Routine)]
+             [2025/02/17 v1.4m LaTeX Kernel (Output Routine)]
 % \iffalse
 \documentclass{ltxdoc}
 \GetFileInfo{ltoutput.dtx}
@@ -1340,12 +1340,12 @@
 %      \item[Testing for existence of material]
 %
 %        \DescribeMacro[noprint]{@if@footnotes@TF}
-%        \DescribeMacro[noprint]{@if@bfloats@TF}
+%        \DescribeMacro[noprint]{@if@bottomfloats@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
-%        \cs{@if@bfloats@TF}
+%        \cs{@if@bottomfloats@TF}
 %        (names are likely to change).
 %   
 %      \end{description}
@@ -2410,11 +2410,11 @@
 %  \end{macro}
 %
 %
-%  \begin{macro}{\@if@bfloats@TF}
+%  \begin{macro}{\@if@bottomfloats@TF}
 % \changes{v1.4m}{2025/02/14}{Macro added}
 %    Test if bottom floats are around.
 %    \begin{macrocode}
-\def\@if@bfloats@TF{%
+\def\@if@bottomfloats@TF{%
   \ifx \@botlist\@empty
     \expandafter\@secondoftwo
   \else
@@ -2454,7 +2454,7 @@
 \NewSocketPlug {build/column/outputbox}{space-footnotes-floats} {%
   \@if@footnotes@TF
       {\@outputbox@append{\vfill}}%
-      {\@if@bfloats@TF
+      {\@if@bottomfloats@TF
         {\@outputbox@append{\vfill}}%
         {\@outputbox@reinsertbskip}%
       }%
@@ -2483,7 +2483,7 @@
 %    \begin{macrocode}
 \NewSocketPlug {build/column/outputbox}{footnotes-space-floats} {%
   \@outputbox@appendfootnotes
-  \@if@bfloats@TF
+  \@if@bottomfloats@TF
       {\@outputbox@append{\vfill}}%
       {\@outputbox@reinsertbskip}%
   \@outputbox@attachfloats
@@ -2500,7 +2500,7 @@
 \NewSocketPlug {build/column/outputbox}{space-floats-footnotes} {%
   \@if@footnotes@TF
       {\@outputbox@append{\vfill}}%
-      {\@if@bfloats@TF
+      {\@if@bottomfloats@TF
         {\@outputbox@append{\vfill}}%
         {\@outputbox@reinsertbskip}}%
   \@outputbox@attachfloats
@@ -2710,7 +2710,7 @@
 %<latexrelease>
 %<latexrelease> \let \@if@flushbottom@TF \@undefined
 %<latexrelease> \let \@if@footnotes@TF \@undefined
-%<latexrelease> \let \@if@bfloats@TF \@undefined
+%<latexrelease> \let \@if@bottomfloats@TF \@undefined
 %<latexrelease>
 %<latexrelease>\EndIncludeInRelease
 %<*2ekernel>