Skip to content

Tagging 1436 column-spanning #2124

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
FrankMittelbach wants to merge 4 commits into
base: develop
Choose a base branch
from
+86,329 −15
Open

Tagging 1436 column-spanning #2124

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
20473c5
draft fix for latex3/tagging-project#1436
FrankMittelbach Jun 21, 2026
f3caec1
news entry and \changes
FrankMittelbach Jun 21, 2026
a2339e2
Apply suggestions from code review
FrankMittelbach Jun 21, 2026
094cc85
another suggestion
FrankMittelbach Jun 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 25 additions & 2 deletions base/doc/ltnews44.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,9 @@
% extension .ins) which are part of the distribution.
%
% \fi
% Filename: ltnews43.tex
% Filename: ltnews44.tex
%
% This is issue 43 of LaTeX News.
% This is issue 44 of LaTeX News.

\NeedsTeXFormat{LaTeX2e}[2020-02-02]

Expand Down Expand Up @@ -179,6 +179,29 @@ \subsection{Revisiting the para-handling logic for block environment}
%
\taggingissue[s]{1402 and 1415 among others}


\subsection{Heading templates now support column spanning}

In twocolumn documents top-level headings usually start on a new page
and span both columns. In \LaTeXe{} this was hardwired and headings
such as \cs{chapter} showed this behavior. In the new template-based
implementation this is now more flexible and one sets this
independently from forcing a new page by setting the key
\texttt{column-spanning} to \texttt{true} (default for \cs{chapter})
or \texttt{false} (default for other headings). Thus
\begin{verbatim}
\section[column-spanning=true]{title}
\end{verbatim}
generates a one-off \cs{section} heading that spans both columns. Due
to the way the \LaTeX{} output routine is currently implemented that
automatically also starts a new page, i.e., one can't generate
spanning headings in the middle of a page (that can only be done with
the \pkg{multicol} package at the moment). That restriction may be
lifted when the output routine is redefined.
%
\taggingissue{1436}


%\section{Code improvements}

%\section{Bug fixes}
Expand Down
5 changes: 5 additions & 0 deletions required/latex-lab/changes.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
2026-06-21 Frank Mittelbach <Frank.Mittelbach@latex-project.org>

* latex-lab-sec-template.dtx (subsubsection{Templates of type \texttt{heading}}):
Support column-spanning for chapters and the like (tagging/1436)

2026-06-15 Frank Mittelbach <Frank.Mittelbach@latex-project.org>

* latex-lab-block.dtx (subsubsection{Tagging recipes}):
Expand Down
143 changes: 130 additions & 13 deletions required/latex-lab/latex-lab-sec-template.dtx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@
%
% https://github.com/latex3/latex2e/issues
%
\def\ltlabsecIIdate{2026-05-25}
\def\ltlabsecIIversion{0.9g}
\def\ltlabsecIIdate{2026-06-21}
\def\ltlabsecIIversion{0.9h}
%<*driver>
\DocumentMetadata{tagging=on,pdfstandard=ua-2}

Expand All @@ -42,6 +42,7 @@
%
%
% \newcommand\key[1]{\texttt{#1}}
% \newcommand\keyvalue[1]{\texttt{#1}}
%
%
% \NewDocumentCommand\fmi{sO{}m}
Expand Down Expand Up @@ -536,6 +537,8 @@
%
% \begin{TemplateDescription}{heading}{\meta{all}}
%
% \changes{0.9h}{2026-06-21}{Support \texttt{column-spanning} key (tagging/1436)}
%
% \TemplateKey{name}{tokenlist}
% {Referencable name of the heading instance. String that
% is acceptable in csnames for use in building counter
Expand Down Expand Up @@ -577,6 +580,16 @@
% paragraph handling of a following paragraph, etc.}
% {}
%
%
% \TemplateKey{column-spanning}{boolean}
% {If true produces a heading that spans columns in
% \texttt{twocolumn} typesetting. Requires
% \key{placement} \texttt{=} \keyvalue{top} (and adjusts
% if necessary) and only has an effect
% if the columns are produced via the \texttt{twocolumn}
% class option and not when using \env{multicol}. This
% might get extended when we refactor the OR handling.}{false}
%
% \TemplateKey{prefix}{tokenlist}
% {A fixed string, such as \enquote{Chapter}, that can be
% used together with the number (if any) to form a
Expand Down Expand Up @@ -1543,19 +1556,21 @@
% \begin{template}{heading display}
% The \texttt{display} template produces a display heading, i.e.,
% one that has vertical space before and after it.
% \changes{0.9h}{2026-06-21}{Support \texttt{column-spanning} key (tagging/1436)}
% \begin{macrocode}
\DeclareTemplateInterface{heading}{display}{9}
{
, name : tokenlist
, parent-name : tokenlist
, reset-counter : tokenlist
, level : integer = 0
, name : tokenlist
, parent-name : tokenlist
, reset-counter : tokenlist
, level : integer = 0
% \end{macrocode}
% The \key{placement} key sets default values for the keys
% \key{start-code} and \key{final-code}.
% \begin{macrocode}
, placement : choice {page , top , normal } = normal
, mark-cmd : function(1) =
, placement : choice {page , top , normal } = normal
, column-spanning : boolean = false
, mark-cmd : function(1) =
%
% many more keys for layout settings are missing for now
, para-indent : choice { true , false } = false
Expand Down Expand Up @@ -1690,6 +1705,15 @@
,normal = \@@_debug_typeout:n{ A~ normal~ heading }
\tl_set:Nn \l_@@_placement_tl { normal }
}
% \end{macrocode}
%
% \changes{0.9h}{2026-06-21}{Support \texttt{column-spanning} key
% (tagging/1436)}
% \begin{macrocode}
, column-spanning = \l_@@_column_spanning_bool
% \end{macrocode}
%
% \begin{macrocode}
, mark-cmd = \@@_mark_cmd:n
% \end{macrocode}
% For now we make use of the legacy coding for indentation of
Expand Down Expand Up @@ -1752,6 +1776,28 @@
% \begin{macrocode}
\tl_if_empty:oF {#1} { \SetTemplateKeys{heading}{display}{#1} }
% \end{macrocode}
%
% If \key{column-spanning} is requested but we are not typesetting
% in two columns we turn it off to avoid using \cs{@topnewpage} as
% this would be wrong. Otherwise we check the placement value and
% adjust it if necessary.
% \changes{0.9h}{2026-06-21}{Support \texttt{column-spanning} key
% (tagging/1436)}
% \begin{macrocode}
\bool_if:NT \l_@@_column_spanning_bool
{
\if@twocolumn
\str_if_eq:VnF \l_@@_placement_tl {top}
{
\@@_debug_typeout:n {column-spanning~ requires~
placement=top.~ Adjusted!}
\tl_set:Nn \l_@@_placement_tl {top}
}
\else
\bool_set_false:N \l_@@_column_spanning_bool
\fi
}
% \end{macrocode}
% Based on the \key{placement} key we set up \cs{l_@@_start_code_tl}
% and \cs{l_@@_final_code_tl}. These two variables can also be set
% with the keys \key{start-code} and \key{final-code} in which case
Expand Down Expand Up @@ -1846,13 +1892,45 @@
\@@_debug_typeout:n{use~ 'headformat'~instance:~
\l_@@_headformat_instance_tl }
\use:e {
% \end{macrocode}
%
% As long as we don't have a decent interface for the OR we have to
% use \cs{@topnewpage} for getting spanning headings (which means
% we are really using a top float box. That in turn means we have
% to get all the vertical spacing and so inside this box so there
% is a lot of back and forth based on the value of
% \cs{l_@@_column_spanning_bool} for now.
% \changes{0.9h}{2026-06-21}{Support \texttt{column-spanning} key
% (tagging/1436)}
% \begin{macrocode}
\bool_if:NT \l_@@_column_spanning_bool
{ \exp_not:n {
\@topnewpage [
\dim_compare:nNnF{\l_@@_after_penalty_skip}={0pt}
{ \vspace* \l_@@_after_penalty_skip }
}
}
\UseInstance{headformat} { \l_@@_headformat_instance_tl }
{ \exp_not:o \UnusedTemplateKeys }
{ \exp_not:o { \l_@@_typeset_prefix_tl } }
{ \exp_not:o { \l_@@_typeset_number_tl } }
{ \exp_not:n { #3 } }
{ \exp_not:o { \use_i:nn #9 } }
{ \exp_not:o { \use_ii:nn #9 } }
% \end{macrocode}
%
% \changes{0.9h}{2026-06-21}{Support \texttt{column-spanning} key
% (tagging/1436)}
% \begin{macrocode}
\bool_if:NT \l_@@_column_spanning_bool
{
\skip_vertical:N \l_@@_after_skip
% \end{macrocode}
% Add the final vspace after the heading and close the
% \cs{@topnewpage} which has an optional argument.
% \begin{macrocode}
]
}
}
%
% --- handle marks, toc-entry, bookmark, nameref, and label
Expand All @@ -1864,8 +1942,18 @@
% Restore \texttt{secnumdepth}
% \begin{macrocode}
\int_gset:Nn\c@secnumdepth{\l_@@_saved_secnumdepth_tl}
\par \nobreak
\skip_vertical:N \l_@@_after_skip
\par
% \end{macrocode}
% If we have a spanning heading then the vertical skip is handled
% inside \cs{@topnewpage} and not here.
% \changes{0.9h}{2026-06-21}{Support \texttt{column-spanning} key
% (tagging/1436)}
% \begin{macrocode}
\bool_if:NF \l_@@_column_spanning_bool
{
\nobreak
\skip_vertical:N \l_@@_after_skip
}
% --- prepare next paragraph (defaults to \cs{@afterheading}
%
\l_@@_final_code_tl
Expand All @@ -1877,7 +1965,7 @@
%
%
%
% \begin{macro}{}
% \begin{macro}{\if@openright}
%
% \begin{macrocode}
\AddToHook{begindocument}{
Expand Down Expand Up @@ -1917,6 +2005,15 @@
,normal = \@@_debug_typeout:n{ A~ normal~ heading }
\tl_set:Nn \l_@@_placement_tl { normal }
}
% \end{macrocode}
%
% \changes{0.9h}{2026-06-21}{Support \texttt{column-spanning} key
% (tagging/1436)}
% \begin{macrocode}
, column-spanning = \l_@@_column_spanning_bool
% \end{macrocode}
%
% \begin{macrocode}
, mark-cmd = \@@_mark_cmd:n
% \end{macrocode}
% In a runin heading you can't set up paragraph indentation of the
Expand Down Expand Up @@ -1974,6 +2071,17 @@
\tl_set_eq:Nc \theheading { the \l_@@_name_tl }
\tl_if_empty:oF {#1} { \SetTemplateKeys{heading}{runin}{#1} }
% \end{macrocode}
% For now we don't support column-spanning in this template.
% \changes{0.9h}{2026-06-21}{Support \texttt{column-spanning} key
% (tagging/1436)}
% \begin{macrocode}
\bool_if:NT \l_@@_column_spanning_bool
{
\@@_debug_typeout:n {column-spanning~ is~
not~ (yet)~ supported~ for~ runin~ headings!}
\bool_set_false:N \l_@@_column_spanning_bool
}
% \end{macrocode}
%
% \begin{macrocode}
\tl_if_empty:oT \l_@@_start_code_tl
Expand Down Expand Up @@ -2411,9 +2519,17 @@
% If \cs{l_@@_start_code_tl} holds code, we assume that it handles
% pagination, e.g., a \cs{clearpage}, etc. We therefore only add
% the skip that would follow the penalty.
%
% And we do nothing at all when we have a spanning heading. Then
% this vspace is done inside \cs{@topnewpage}.
% \changes{0.9h}{2026-06-21}{Support \texttt{column-spanning} key
% (tagging/1436)}
% \begin{macrocode}
\dim_compare:nNnF{\l_@@_after_penalty_skip}={0pt}
{ \vspace* \l_@@_after_penalty_skip }
\bool_if:NF \l_@@_column_spanning_bool
{
\dim_compare:nNnF{\l_@@_after_penalty_skip}={0pt}
{ \vspace* \l_@@_after_penalty_skip }
}
}
}
% \end{macrocode}
Expand Down Expand Up @@ -2627,6 +2743,7 @@
, name = chapter
, level = 0
, placement = top
, column-spanning = true
, after-penalty-vspace = 50pt
, after-vspace = 40pt
, prefix = \@chapapp
Expand Down
Loading