Use order keys for heading templates

base/doc/ltnews44.tex

@@ -271,6 +271,7 @@ \subsection{Use the \key{order} key mechanism for theorem-like environments and
 By default the setting of the \key{note-format} key surrounds the note with parentheses.
 
 
+
 \subsection{Fix a color leakage in theorem-like environments}
 
 If the \key{body-decls} key was given a color specification then that
@@ -343,6 +344,59 @@ \subsection{Make \cs{item}\texttt{[]} produce an empty item label}
 \taggingissue{1557}
 
 
+\subsection{Use the \key{order} key mechanism for heading commands}
+
+In \LaTeX{} release 2026-06-01 we provided a reimplementation of
+heading commands using templates. The initial set of templates had
+only limited flexibility, modeling layouts closely related to those from
+the standard \LaTeX classes. As a consequence, they used keys such as
+\key{number-title-sep} to define the space between heading number and
+title on the assumption that both are placed exactly in that order.
+
+We have now written new extended the templates to allow for reordering
+of heading elements and more flexible spacing between them, but in
+that scenario such keys do no longer make sense and therefore have
+been replaced with more generic keys such as \key{separator-a},
+\key{separator-b}, etc. not taking a length value but accepting
+general code.
+
+
+If you have defined instances using the first template version
+then you can (for now) continue to use them simply by changing the
+template names in your instance declarations from \meta{name} to
+\meta{name}\texttt{-v1}, e.g., you have to change from
+\begin{verbatim}
+ \DeclareInstance
+     {heading}{chapter}{display} {...}
+ \DeclareInstance{headformat}
+     {heading}{chapter}{display} {...}
+
+ \DeclareInstance{heading}
+     {section}{hang} { ... }
+ \DeclareInstance{headformat}
+     {section}{hang} { ... }
+ ...
+\end{verbatim}
+  to 
+\begin{verbatim}
+ \DeclareInstance
+     {heading}{chapter}{display-v1} {...}
+ \DeclareInstance{headformat}
+     {heading}{chapter}{display-v1} {...}
+
+ \DeclareInstance{heading}
+     {section}{hang-v1} { ... }
+ \DeclareInstance{headformat}
+     {section}{hang-v1} { ... }
+ ...
+\end{verbatim}
+No other changes are necessary for now. However, going forward
+you should switch to the extended templates because the
+\texttt{-v1} templates will eventually be dropped. 
+%
+How to upgrade to the new templates is explained in \texttt{texdoc
+  latex-lab-sec-template}.
+
 
 \subsection{Support \key{force-unnumbered} key in heading templates}
 
@@ -411,7 +465,15 @@ \subsection{\cs{newlist} failed for \texttt{description} lists}
 
 
 
-%\section{New or improved commands}
+\section{New or improved commands}
+
+\subsection{Testing if a certain template is defined}
+
+To better support the declaration of template instances we now provide the
+conditional \cs{IfTemplateExistsTF} (and its \texttt{T} and \texttt{F}
+variants) so that it is possible to take different actions depending
+on whether or not a certain template is declared.
+
 
 
 
@@ -432,9 +494,11 @@ \subsection{Support for \cs{UseName} in template key bindings}
 
 \subsection{Further removal of \enquote{fake math} from the kernel}
 
-In the previous release, we removed most use of \enquote{fake math} (math mode not denoting a formula but used for positioning or manipulating text material) from the
-kernel~\cite{44:ltnews}. The use of \cs{underline} in text mode was missed in
-that update: this has now been addressed.
+In the previous release, we removed most use of \enquote{fake math}
+(math mode not denoting a formula but used for positioning or
+manipulating text material) from the kernel~\cite{44:ltnews}. The use
+of \cs{underline} in text mode was missed in that update: this has now
+been addressed.
 
 %\section{Bug fixes}
 

required/latex-lab/changes.txt

@@ -3,24 +3,63 @@
 	* latex-lab-names.dtx: avoid to use tagpdf internal:
 			use `\tag_if_tag_known:nT` to test if a tag exists.
 			use role/new-attribute* for the table attributes
-	* latex-lab-marginpar: avoid to use tagpdf internal, use \tag_struct_map_function:N to map over the stack. 
-	* latex-lab-block.dtx: remove unused \__tag_para_main_store_struct:, use symbolic names instead of para variables.
-	* latex-lab-sec.dtx: avoid to use tagpdf internals, use \tag_get:nN and use symbolic names.
-	* latex-lab-table.dtx: avoid to use tagpdf internals when adapting the header cells, avoid para-variables and use symbolic names instead.
-	* latex-lab-math.dtx: avoid to use tagpdf internals by simplifying `\@kernel@math@registered@begin` and using \tag_attr_new:ee.
+	* latex-lab-marginpar: avoid to use tagpdf internal, use \tag_struct_map_function:N
+	to map over the stack. 
+	* latex-lab-block.dtx: remove unused \__tag_para_main_store_struct:, use symbolic
+	names instead of para variables.
+	* latex-lab-sec.dtx: avoid to use tagpdf internals, use \tag_get:nN and
+	use symbolic names.
+	* latex-lab-table.dtx: avoid to use tagpdf internals when adapting the header
+	cells, avoid para-variables and use symbolic names instead.
+	* latex-lab-math.dtx: avoid to use tagpdf internals by simplifying
+	\@kernel@math@registered@begin and using \tag_attr_new:ee.
 	* latex-lab-float.dtx: avoid to use tagpdf internals
 
 2026-09-02  Benjamin Mako Hill  <mako@atdot.cc>
 
 	* latex-lab-footnotes.dtx (subsubsection{Making documents use the new \cs{@makefntext}}):
 	Report a proper error if \cs{@makefntext} cannot be patched (tagging/1577)
 
+2026-08-31  Frank Mittelbach  <Frank.Mittelbach@latex-project.org>
+
+	* latex-lab-minipage.dtx (subsection{Tagging commands}):
+	Don't use \UseStructureName for now but use the
+	variable \l__tag_para_tag_tl directly
+
 2026-08-27  Frank Mittelbach  <Frank.Mittelbach@latex-project.org>
 
 	* latex-lab-block.dtx (subsubsection{Implementation of \insttype{item} templates}):
 	Treat empty optional \item argument as an empty label (tagging/1557)
 
->>>>>>> develop
+2026-08-23  Frank Mittelbach  <Frank.Mittelbach@latex-project.org>
+
+	* latex-lab-sec-template.dtx (subsubsection{headformat templates interfaces}):
+	Use order key mechanism in headformat templates.
+
+	* latex-lab-firstaid.dtx:
+	Adjust AMS class fixes to new heading templates.
+
+2026-08-19  Frank Mittelbach  <Frank.Mittelbach@latex-project.org>
+
+	* latex-lab-template.dtx (section{The Implementation}):
+	Support special order key items ?, |, and, !.
+
+2026-08-14  Frank Mittelbach  <Frank.Mittelbach@latex-project.org>
+
+	* latex-lab-template.dtx:
+	Add support for special | item in order clists.
+	Add \IfValueLastOrderItemTF to do conditional formatting based on whether
+	or not last item had a value.
+
+2026-08-12  Frank Mittelbach  <Frank.Mittelbach@latex-project.org>
+
+	* latex-lab-sec-template.dtx (subsubsection{New \cs{@startsection}}):
+	Provide command to split off last token of a token list if it
+	is a macro with one argument (tagging/1521)
+
+	Split style argument of \@startsection based on type of
+	last token (tagging/1521)
+
 2026-08-10  Frank Mittelbach  <Frank.Mittelbach@latex-project.org>
 
 	* latex-lab-enumitem.dtx (subsubsection{\cs{newlist}}):

required/latex-lab/latex-lab-block.dtx

@@ -818,12 +818,12 @@
 %  
 % \begin{TemplateDescription}{thmstyle}{std}
 %
-%  \TemplateKey{separator-1}{tokenlist}
+%  \TemplateKey{separator-a}{tokenlist}
 %     {Separation to be applied between elements of the heading,
 %     typically a space command of some
 %     sort.}{\textbackslash\textvisiblespace }
 %
-%  \TemplateKey{separator-2}{tokenlist}
+%  \TemplateKey{separator-b}{tokenlist}
 %     {Additional separation to be applied between elements of the
 %     heading, typically a space command of some
 %     sort.}{\textbackslash\textvisiblespace }
@@ -849,8 +849,8 @@
 %  \TemplateKey{order}{commalist}
 %     {Order of elements in the environment caption/heading. Supported
 %     values are \texttt{title}, \texttt{number}, \texttt{punct},
-%     \texttt{separator-1}, \texttt{separator-2}, and
-%     \texttt{note}.}{title,separator-1,number,separator-2,note,punct}
+%     \texttt{separator-a}, \texttt{separator-b}, and
+%     \texttt{note}.}{title,separator-a,number,separator-b,note,punct}
 %
 %  \TemplateKey{title-decls}{tokenlist}
 %     {Declarations that are applied only to the caption
@@ -2251,12 +2251,12 @@
 %    \begin{macrocode}
 \DeclareInstance{thmstyle}{plain}{std}{
   ,caption-placement = unchained
-  ,separator-1       = \ 
-  ,separator-2       = \ 
+  ,separator-a       = \ 
+  ,separator-b       = \ 
   ,punct             = . 
   ,before-hspace     = 0pt
   ,after-hspace      = 5pt plus 1pt minus 1pt
-  ,order             = {title,separator-1,number,separator-2,note,punct}
+  ,order             = {title,separator-a,number,separator-b,note,punct}
   ,caption-decls     = \bfseries
   ,title-decls       = 
   ,number-decls      = \upshape
@@ -3615,15 +3615,15 @@
 %    \begin{macrocode}
 \DeclareTemplateInterface{thmstyle}{std}{4}{
    separator         : tokenlist = \       
-  ,separator-1       : tokenlist = \       
-  ,separator-2       : tokenlist = \       
+  ,separator-a       : tokenlist = \       
+  ,separator-b       : tokenlist = \       
   ,punct             : tokenlist = .
   ,caption-placement : choice {chained,unchained,standalone} = unchained
   ,caption-unbreakable : boolean = false
   ,before-hspace     : skip = 0pt
   ,after-hspace      : skip = 5pt
-  ,order             : commalist = {title,separator-1,number,punct,
-                                    separator-1,note}
+  ,order             : commalist = {title,separator-a,number,punct,
+                                    separator-a,note}
   ,caption-decls     : tokenlist =
   ,title-decls       : tokenlist =
   ,number-tag        : tokenlist = \UseStructureName{block/theorem-like/label}
@@ -5677,8 +5677,8 @@
 \DeclareTemplateCode{thmstyle}{std}{4}
 {
   ,separator       = \l_@@_separator_tl          % compatibility
-  ,separator-1     = name {l_@@_separator-1_tl}
-  ,separator-2     = name {l_@@_separator-2_tl}
+  ,separator-a     = name {l_@@_separator-a_tl}
+  ,separator-b     = name {l_@@_separator-b_tl}
   ,punct           = \l_@@_punct_tl
   ,caption-placement = {
      chained    = \bool_gset_false:N \g_@@_label_standalone_bool
@@ -5753,7 +5753,7 @@
            \template_process_order_clist:nnn
               { block }{ order }
               { note, number, punct, separator,
-                   separator-1, separator-2, title }
+                   separator-a, separator-b, title }
            \skip_horizontal:n { \l_@@_caption_after_skip }
          }
     }
@@ -7198,7 +7198,7 @@
     ,before-hspace:e = \tl_if_empty:nTF{#5}{0pt}{#5}
     ,body-decls      = {#4}
     ,punct           = {#7}
-    ,order           = {title,separator-1,number,separator-2,note,punct}
+    ,order           = {title,separator-a,number,separator-b,note,punct}
     ,number-decls    = \upshape
     ,note-decls      = \upshape\mdseries
 %    \end{macrocode}