Skip to content

Commit

Permalink
added ltnews entry ; updates to the document
Browse files Browse the repository at this point in the history
  • Loading branch information
@FrankMittelbach
FrankMittelbach committed Feb 15, 2025
1 parent 0c7019a commit bca773e
Show file tree
Hide file tree
Showing 2 changed files with 140 additions and 10 deletions.
124 changes: 121 additions & 3 deletions base/doc/ltnews41.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,8 @@
\usepackage{color}

\providecommand\hook[1]{\texttt{#1}}
\providecommand\socket[1]{\texttt{#1}}
\providecommand\plug[1]{\texttt{#1}}

\providecommand\meta[1]{$\langle$\textrm{\itshape#1}$\rangle$}
\providecommand\option[1]{\texttt{#1}}
Expand Down Expand Up @@ -186,13 +188,125 @@ \section{Replacement for the legacy mark mechanism}
See~\cite{41:ltmarks} for details on the extended functionality.


\section{Configurable 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 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 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
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\Dash 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\Dash 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}=
\verb= {=\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 more configuration possibilities, mainly for class
developers; more documentation on those can be found in
\cite[\S54 ltoutput.dtx]{41:source2e}.



\section{News from Tagged PDF project}

The \texttt{testphase} key now takes also the value \texttt{latest}.
This will load all modules that we recommend
so that it is not necessary to specify individual modules. The list of loaded modules
will be adjusted as needed when the project progresses. It is also written to the log.
This will load all modules that we recommend so that it is not
necessary to specify individual modules. The list of loaded modules
will be adjusted as needed when the project progresses. For reference,
it is also written to the log.


\emph{to write}
Expand Down Expand Up @@ -634,6 +748,10 @@ \subsection{\pkg{array}:\ Improve preamble setup code for \texttt{p} and friends
\emph{The \texttt{ltmarks.dtx} code}. June 2025.
\url{https://latex-project.org/help/documentation/ltmarks-doc.pdf}

\bibitem{41:source2e} \LaTeX{} Project Team.
\emph{The \LaTeXe{} Sources}. June 2025.
\url{https://latex-project.org/help/documentation/source2e.pdf}

\end{thebibliography}

\end{document}
26 changes: 19 additions & 7 deletions base/ltoutput.dtx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@
%<*driver>
% \fi
\ProvidesFile{ltoutput.dtx}
[2025/02/14 v1.4m LaTeX Kernel (Output Routine)]
[2025/02/15 v1.4m LaTeX Kernel (Output Routine)]
% \iffalse
\documentclass{ltxdoc}
\GetFileInfo{ltoutput.dtx}
Expand Down Expand Up @@ -1253,13 +1253,13 @@
% the page processing in the output routine. They are
% implemented as mirrored hooks.
%
% Technically, they are executed at the start and end of the internal
% Technically, they are executed at the start and the end of the internal
% \LaTeXe{} \cs{@outputpage} command, respectively.
%
%
% \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
% 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.
Expand All @@ -1269,7 +1269,7 @@
% the column processing in the output routine. They are
% implemented as mirrored hooks.
%
% Technically, they are executed at the start and end of the internal
% Technically, they are executed at the start and the end of the internal
% \LaTeXe{} \cs{@makecol} command, respectively.
%
% \end{description}
Expand Down Expand Up @@ -1385,16 +1385,28 @@
%
% \item[\plug{floats-footnotes}]
%
% All excess space has to be distributed across the existing
% 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, i.e., this plug is
% assigned to the socket.
% swapped. This is the \LaTeX{} defaultfor newer document,
% 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}
%
Expand Down

0 comments on commit bca773e

Please sign in to comment.