Pre-release of LaTeX for 2022-11-01 is ready for testing

We submitted the first pre-release version for the 2022-11-01 LaTeX kernel to CTAN recently. It should have made its way into TeX Live or should appear for everyone pretty soon.

It already contains most updates and improvements to the LaTeX format that will become part of the standard in November; thus testing them now will help identifying packages that need upgrading and finding any bugs lurking before that release hits the streets; see below for how to do this in a safe way.

The main highlight is briefly discussed below, further details plus smaller bug fixes and improvements not covered here can be found in the draft version of the LaTeX2e News Issue 36 newsletter.

New feature in the kernel (highlights)

For developers

The most important improvement in the LaTeX kernel is to offer a standard mechanism for receiving and manipulating key/value arguments in commands. This is implemented in the \DeclareDocumentCommand interfaces and offers a reliable method to allow an (optional) argument to contain either a key/value list or to interpret it as an ordinary argument if the content does not contain such a key/value list. In the latter case that content is interpreted as the value of the key whose name is specified in the command declaration. For example, the \caption command could be declared as

\DeclareDocumentCommand \caption {s ={short-text}+O{#3} +m}
       {...}

which means that it expects an optional star (s) and a mandatory argument that can contain \par commands (+m). It also has an optional argument (before the mandatory one) whose default – if not given – is the content of the mandatory one (+O{#3}), which is why it refers to #3. By prefixing this with ={short-text} we state that this optional argument should check for a key/value list and if no such list is found, should assign its argument content to the key short-text for further processing. Then such processing of the argument can always assume that it got a key/value list, either the one specified or the simple one with just the short-text key.

Right now, only the functionality is offered and that is largely targeted towards developers. However, the moment commands make use of that feature (and from the project team perspective we certainly intend to make use of it in upcoming releases) it becomes relevant for users as well, because then they will be able to specify key/value arguments in several places, while support for “free text arguments” is retained.

While technically this functionality can be used with any argument we intend to use it only for the first optional argument of a command and suggest that developers do likewise so that (most) LaTeX commands use a similar interface that makes it easy for users to work with, i.e.,

\cmd * [<arg with key/val or free text>] <other mandatory or optional arguments>

Simpler commands could, of course, offer

• no * form or
• an optional argument always expecting a key/value list or
• one without any key/value support or
• no optional argument whatsoever.

For developers and users

You may wonder what rules are used to determine that an argument is interpreted as a key/value list. They are fairly simple, but adequate (we hope) for nearly all use cases. Basically, the argument text is searched for one or more = signs that are neither within an explicit brace group {...} nor part of inline math mode, or more precisely not within $...$ or \(...\). Other constructs are not considered at the moment, e.g., if you really use \begin{math}...\end{math} or some display math that contains an equal sign, it will not work inside such an argument without adjustment. If the content is incorrectly interpreted as a key/value list, then the remedy for the user is to hide the content in a brace group, e.g.,

\caption[The form: \begin{math} a=b\end{math}]  {...}  % fails
\caption[{The form: \begin{math} a=b\end{math}}]{...}  % works

There is also a way to force interpretation as a key/value list by prepending =, to the argument which can be useful in some situations with valueless keys. More details can be found in the documentation.

Outlook

We expect to produce another pre-release before the next main release, but this will most likely only contain some further updates to the latex-lab code, and possible some minor updates to fix one or the other minor pending issue. Please help with the testing of this pre-release by using it for your documents or testing it against your own packages.

Processing your documents with the pre-release is straightforward. All you have to do is to replace the invocation command by appending -dev to the executable, e.g., on the command line you would run

• pdflatex-dev myfile or
• lualatex-dev myfile or
• xelatex-dev myfile

instead of using pdflatex, lualatex or xelatex. If you use an integrated editing environment, then it depends on the system how to configure it to use an alternative format; but in any case the necessary modification should be straightforward.

Enjoy — Frank & Joseph