From cf7aabcd6fa1dcec9809ddc0413432e469b1afec Mon Sep 17 00:00:00 2001 From: Frank Mittelbach Date: Mon, 17 Feb 2025 20:18:05 +0100 Subject: [PATCH] Or consolidation (#1663) * dependencies update * give the tagging sockets a default (just in case) * updates after review added a section to clsguide renamed one internal command --- base/doc/clsguide.tex | 122 +++++++++++++++++- base/doc/ltnews41.tex | 2 +- base/ltoutput.dtx | 18 +-- base/lttagging.dtx | 35 ++++- .../changing-@makecol-dependencies.md | 54 +++----- .../changing-@startcolumn-dependencies.md | 86 ++++++++++++ 6 files changed, 266 insertions(+), 51 deletions(-) create mode 100644 required/latex-lab/changing-@startcolumn-dependencies.md diff --git a/base/doc/clsguide.tex b/base/doc/clsguide.tex index 69fa7433a..da336ac60 100644 --- a/base/doc/clsguide.tex +++ b/base/doc/clsguide.tex @@ -34,7 +34,7 @@ \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 @@ -42,7 +42,7 @@ \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 diff --git a/base/doc/ltnews41.tex b/base/doc/ltnews41.tex index 063b96812..7ec8b97b1 100644 --- a/base/doc/ltnews41.tex +++ b/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: diff --git a/base/ltoutput.dtx b/base/ltoutput.dtx index 33855442c..a069068d2 100644 --- a/base/ltoutput.dtx +++ b/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 @@ % % \let \@if@flushbottom@TF \@undefined % \let \@if@footnotes@TF \@undefined -% \let \@if@bfloats@TF \@undefined +% \let \@if@bottomfloats@TF \@undefined % %\EndIncludeInRelease %<*2ekernel> diff --git a/base/lttagging.dtx b/base/lttagging.dtx index 9530bda96..a69447aa1 100644 --- a/base/lttagging.dtx +++ b/base/lttagging.dtx @@ -33,7 +33,7 @@ %<*driver> % \fi \ProvidesFile{lttagging.dtx} - [2025/02/14 v1.0m LaTeX Kernel (tagging support)] + [2025/02/16 v1.0n LaTeX Kernel (tagging support)] % \iffalse \documentclass{l3doc} \GetFileInfo{lttagging.dtx} @@ -321,6 +321,12 @@ \NewSocket{tagsupport/toc/contentsline/before}{1} \NewSocket{tagsupport/toc/contentsline/after}{1} % \end{macrocode} +% +% \changes{v1.0n}{2025/02/16}{Initialize tagging sockets with 1 or 2 arguments} +% \begin{macrocode} +\AssignSocketPlug{tagsupport/toc/contentsline/before}{noop} +\AssignSocketPlug{tagsupport/toc/contentsline/after}{noop} +% \end{macrocode} % \end{socketdecl} % % \begin{socketdecl}{tagsupport/toc/starttoc/before, @@ -331,6 +337,12 @@ \NewSocket{tagsupport/toc/starttoc/before}{1} \NewSocket{tagsupport/toc/starttoc/after}{1} % \end{macrocode} +% +% \changes{v1.0n}{2025/02/16}{Initialize tagging sockets with 1 or 2 arguments} +% \begin{macrocode} +\AssignSocketPlug{tagsupport/toc/starttoc/before}{noop} +\AssignSocketPlug{tagsupport/toc/starttoc/after}{noop} +% \end{macrocode} % \end{socketdecl} % % \begin{socketdecl}{tagsupport/toc/leaders/before, @@ -423,6 +435,11 @@ % \begin{macrocode} \NewSocket{tagsupport/tbl/colspan}{1} % \end{macrocode} +% +% \changes{v1.0n}{2025/02/16}{Initialize tagging sockets with 1 or 2 arguments} +% \begin{macrocode} +\AssignSocketPlug{tagsupport/tbl/colspan}{noop} +% \end{macrocode} % \end{socketdecl} % @@ -516,6 +533,11 @@ \NewSocket{tagsupport/caption/begin}{1} \NewSocket{tagsupport/caption/end}{0} % \end{macrocode} +% +% \changes{v1.0n}{2025/02/16}{Initialize tagging sockets with 1 or 2 arguments} +% \begin{macrocode} +\AssignSocketPlug{tagsupport/caption/begin}{noop} +% \end{macrocode} % \end{socketdecl} % % \begin{socketdecl}{tagsupport/caption/label/begin, @@ -549,6 +571,17 @@ \NewSocket{tagsupport/build/page/header}{2} \NewSocket{tagsupport/build/page/footer}{2} % \end{macrocode} +% +% \changes{v1.0n}{2025/02/16}{Initialize tagging sockets with 1 or 2 arguments} +% \begin{macrocode} +\NewSocketPlug{tagsupport/build/page/header}{transparent}{#2} +\NewSocketPlug{tagsupport/build/page/footer}{transparent}{#2} +% \end{macrocode} +% +% \begin{macrocode} +\AssignSocketPlug{tagsupport/build/page/header}{transparent} +\AssignSocketPlug{tagsupport/build/page/footer}{transparent} +% \end{macrocode} % \end{socketdecl} % \end{socketdecl} % diff --git a/required/latex-lab/changing-@makecol-dependencies.md b/required/latex-lab/changing-@makecol-dependencies.md index ca4312002..8308c2b4c 100644 --- a/required/latex-lab/changing-@makecol-dependencies.md +++ b/required/latex-lab/changing-@makecol-dependencies.md @@ -364,28 +364,6 @@ -#### /usr/local/texlive/2024/texmf-dist/tex/latex/latex-lab/latex-lab-testphase-new-or-2.sty - -``` -\def \@makecol {% -``` - -Not relevant, will vanish - -#### /usr/local/texlive/2024/texmf-dist/tex/latex/latex-lab/latex-lab-testphase-new-or-1.sty - -``` -\patchcmd\@makecol - {\typeout{Patching \string\@makecol\space for tagging}}{\PATCHerror } -\patchcmd\@makecol - {\typeout{Patching \string\@makecol\space for tagging}}{\PATCHerror } - \def\@makecol{% -``` - -Not relevant, will vanish - - - #### /usr/local/texlive/2024/texmf-dist/tex/latex/arabi/fmultico.sty ``` @@ -469,7 +447,7 @@ Rollback version. Rollback probably only works if the format is rolled back as w ------------------------------- -## Files ok but should use hook `{cmd/@makecol/before}` +## Files ok but should use hook `{build/column/before}` #### /usr/local/texlive/2024/texmf-dist/tex/latex/fancyhdr/fancyhdr.sty @@ -479,7 +457,7 @@ Rollback version. Rollback probably only works if the format is rolled back as w \def\@makecol{\ifvoid\footins\f@nch@footnotefalse\else\f@nch@footnotetrue\fi ``` - - Ok, but should be handled by a hook `{cmd/@makecol/before}` + - Ok, but should be handled by a hook `{build/column/before}` #### /usr/local/texlive/2024/texmf-dist/tex/latex/widows-and-orphans/widows-and-orphans.sty @@ -488,7 +466,7 @@ Rollback version. Rollback probably only works if the format is rolled back as w \tl_put_left:Nn \@makecol { \__fmwao_test_for_widows_etc: } ``` - - Ok, but should be handled by a hook `{cmd/@makecol/before}` + - Ok, but should be handled by a hook `{build/column/before}` #### /usr/local/texlive/2024/texmf-dist/tex/latex/ncctools/manyfoot.sty @@ -498,7 +476,7 @@ Rollback version. Rollback probably only works if the format is rolled back as w \def\@makecol{\MFL@joinnotes\MFL@makecol} ``` - - Ok, but should be handled by a hook `{cmd/@makecol/before}` + - Ok, but should be handled by a hook `{build/column/before}` #### /usr/local/texlive/2024/texmf-dist/tex/latex/changebar/changebar.sty @@ -508,7 +486,7 @@ Rollback version. Rollback probably only works if the format is rolled back as w \let\@makecol\cb@makecol ``` - - Ok, but should be handled by a hook `{cmd/@makecol/before}` and `{cmd/@makecol/after}` + - Ok, but should be handled by a hook `{build/column/before}` and `{build/column/after}` #### /usr/local/texlive/2024/texmf-dist/tex/latex/pbalance/pbalance.sty @@ -524,7 +502,7 @@ Rollback version. Rollback probably only works if the format is rolled back as w \apptocmd{\@makecol}{\@PBcollectColumnUsedHeight} ``` - - Ok, but should be handled by a hook `{cmd/@makecol/before}` and `{cmd/@makecol/after}` + - Ok, but should be handled by a hook `{build/column/before}` and `{build/column/after}` #### /usr/local/texlive/2024/texmf-dist/tex/latex/yafoot/dblfnote.sty @@ -536,7 +514,7 @@ Rollback version. Rollback probably only works if the format is rolled back as w \let\@makecol\dfn@makecol ``` - - Probably ok, but should use `{cmd/@makecol/before}` and `{cmd/@makecol/after}` + - Probably ok, but should use `{build/column/before}` and `{build/column/after}` - Also need perhaps a bit of thoughts how to swap stuff in and out (in case `\twocolumn` is in force) @@ -547,7 +525,7 @@ Rollback version. Rollback probably only works if the format is rolled back as w \def\@makecol{% ``` - - Ok, but should be handled by hook `{cmd/@makecol/before}` + - Ok, but should be handled by hook `{build/column/before}` - Also questionable if this is still necessary or helpful @@ -555,7 +533,7 @@ Rollback version. Rollback probably only works if the format is rolled back as w ------------------------------- -## Files ok but should use hook `{cmd/@makecol/after}` +## Files ok but should use hook `{build/column/after}` #### /usr/local/texlive/2024/texmf-dist/tex/latex/aastex/aastex631.cls @@ -563,7 +541,7 @@ Rollback version. Rollback probably only works if the format is rolled back as w \let\LS@makecol=\@makecol \def\@makecol{\LS@makecol\LS@rot}% ``` - - Ok, but should be handled by a hook `{cmd/@makecol/after}` + - Ok, but should be handled by a hook `{build/column/after}` #### /usr/local/texlive/2024/texmf-dist/tex/latex/rotpages/rotpages.sty @@ -573,7 +551,7 @@ Rollback version. Rollback probably only works if the format is rolled back as w \def\@makecol{\SC@makecol\SC@processpage}% ``` - - Ok, but should be handled by a hook `{cmd/@makecol/after}` + - Ok, but should be handled by a hook `{build/column/after}` #### /usr/local/texlive/2024/texmf-dist/tex/latex/graphics/lscape.sty @@ -583,7 +561,7 @@ Rollback version. Rollback probably only works if the format is rolled back as w \def\@makecol{\LS@makecol\LS@rot}% ``` - - Ok, but should be handled by a hook `{cmd/@makecol/after}` + - Ok, but should be handled by a hook `{build/column/after}` #### /usr/local/texlive/2024/texmf-dist/tex/latex/flexipage/flexipage.sty @@ -593,7 +571,7 @@ Rollback version. Rollback probably only works if the format is rolled back as w \def\@makecol{\flx@LS@makecol\flx@LS@rot}% ``` -Ok, but should be handled by a hook `{cmd/@makecol/after}` +Ok, but should be handled by a hook `{build/column/after}` @@ -604,7 +582,7 @@ Ok, but should be handled by a hook `{cmd/@makecol/after}` \def\@makecol{% ``` - - Ok, but should be handled by a hook `{cmd/@makecol/after}` + - Ok, but should be handled by a hook `{build/column/after}` - Tagging probably doesn't work without tagging the side nodes explicitly. @@ -618,7 +596,7 @@ Ok, but should be handled by a hook `{cmd/@makecol/after}` \cs_set_protected_nopar:Npn\@makecol{ ``` - - Ok, but should be handled by a hook `{cmd/@makecol/after}` + - Ok, but should be handled by a hook `{build/column/after}` @@ -629,7 +607,7 @@ Ok, but should be handled by a hook `{cmd/@makecol/after}` \gdef\@makecol{% ``` - - Ok, but should be handled by a hook `{cmd/@makecol/after}` + - Ok, but should be handled by a hook `{build/column/after}` #### /usr/local/texlive/2024/texmf-dist/tex/latex/lineno/lineno.sty diff --git a/required/latex-lab/changing-@startcolumn-dependencies.md b/required/latex-lab/changing-@startcolumn-dependencies.md new file mode 100644 index 000000000..57e328ec7 --- /dev/null +++ b/required/latex-lab/changing-@startcolumn-dependencies.md @@ -0,0 +1,86 @@ + +# Files containing `\@startcolumn` + +## Files with no support + +#### /usr/local/texlive/2024/texmf-dist/tex/latex/accessibility/accessibility.sty + +``` + \let\original@startcolumn\@startcolumn% + \renewcommand{\@startcolumn}{% +``` + +## Files ok + +#### /usr/local/texlive/2024/texmf-dist/tex/latex/flowfram/flowfram.sty + +``` + \@opcol \@startcolumn + \@whilesw \if@fcolmade \fi {\@opcol \@startcolumn }% +``` + +#### /usr/local/texlive/2024/texmf-dist/tex/latex/sttools/cuted.sty + +``` + \@startcolumn + {\@opcol \@startcolumn}% +``` + +#### /usr/local/texlive/2024/texmf-dist/tex/latex/base/fltrace.sty + +``` + \@startcolumn + \@opcol\@startcolumn}% +\def \@startcolumn {% +``` + + +#### /usr/local/texlive/2024/texmf-dist/tex/latex/paracol/paracol.sty + +``` + \@startcolumn + \@whilesw\if@fcolmade\fi{\@opcol \@startcolumn}% + \@startcolumn \@whilesw\if@fcolmade\fi{\@opcol\@startcolumn}% +``` + +#### /usr/local/texlive/2024/texmf-dist/tex/latex/rotpages/rotpages.sty + +``` + \def\@startcolumn{\relax}% +``` + +basically disables it within some env. + + +## Files ok but should use hook `{cmd/@startcolumn/before} + +#### /usr/local/texlive/2024/texmf-dist/tex/latex/hypdvips/hypdvips.sty + +``` +\global\let\pp@backup@@startcolumn\@startcolumn +\gdef\@startcolumn{% +``` + +## Files to check + + +#### /usr/local/texlive/2024/texmf-dist/tex/latex/tools/ftnright.sty + +``` +\def\@startcolumn{% +``` + +`\@xstartcol` is old `\@startcolumn`. Redef is complex + + + + +#### /usr/local/texlive/2024/texmf-dist/tex/latex/platex-tools/pxftnright.sty + +``` +% * \@startcolumn is redefined +\def\@startcolumn{% +``` + +should follow ftnright rewrite +