4

In LaTeX News, Issues 1–36, it is written:

Auto-detecting key/value arguments To allow extension of the core LATEX syntax, ltcmd now supports a =... modifier when grabbing arguments. This modifier instructs LATEX that the argument should be passed to the underlying code as a set of key/values. If the argument does not “look like” a set of key/values, it will be converted into a single key/value pair, with the argument to = specifying the name of that key. For example, the \caption command could be defined as \DeclareDocumentCommand\caption {s ={short-text}+O{#3} +m}{...}

What is the API utility of this kind of feature?

projetmbc
  • 13,315

1 Answers1

12

If you have an existing command like

\section[short version]{long version of title}

and would like to get to a key/val future

\section[pdfoutline=very short, page-head=quite short,
        toc=medium length]{long version of title}

this gives you a way to support both syntaxes by spotting there is no = in

  \section[short version]{long version of title}

and defining it to mean

\section[toc=short version]{long version of title}

enter image description here

Here I show a debug definition that shows how the argument #2 is always exposed as a keyval list even if the legacy form \section[short version] is used, so this allows new functionality with multiple keys to be defined.

\documentclass{article}

\DeclareDocumentCommand\section {s ={short-text}+O{#3} +m}{%
\par
\bigskip
Section:\par
\IfBooleanTF{#1}%
   {no number}%
   {number}\par
options: \texttt{\detokenize{#2}}\par
main text:  \texttt{\detokenize{#3}}\par 
}


\begin{document}


\section{aaaa}


\section*[short text]{a section}


\section[toc=a sec., 
         page-head =this text, 
         pdfbookmark= A SECTION]{another section}


\end{document}
David Carlisle
  • 757,742
  • Ok, it remains to parse the keys, and the value as usual. So this is a good feature. – projetmbc Mar 19 '23 at 17:31
  • 1
    @projetmbc I added an example – David Carlisle Mar 19 '23 at 17:32
  • 1
    @projetmbc yes it just sets up the input, you can use keyval or l3keys or pgf or whatever to actually process the keys – David Carlisle Mar 19 '23 at 17:35
  • @barbarabeeton done – David Carlisle Mar 19 '23 at 17:54
  • This assumes that all keys have to be followed by an = sign, and seems so exclude section titles containing = signs, at least in their short titles. –  Mar 20 '23 at 03:08
  • @gandolf you can have Boolean keys with no value as long as they are not the only key on an instance. you can have = so long it is in a brace or $ group if you take an existing command such as section or caption and extend its syntax there are always theoretical possibilities of clashes, we tried several things and this seemed the most reasonable balance. – David Carlisle Mar 20 '23 at 07:03
  • This assumes that the user did precisely what you think they do. Any user who did something extraordinary on their own will be at a great risk of having their older documents throwing errors. Really hope that experiments like this do not become part of the kernel. –  Mar 20 '23 at 18:36