Is there a LaTeX 3 transition guide for users (not gurus)?

Question

To my eternal horror – reading a remark by egreg to some other post – I discovered that LaTeX 3 has been incorporated in the standard LaTeX kernel since 2020. I had missed it completely. Blame the strange COVID-19 year.

I think it is time for me and other end users (not internals wizards) to start learning more, too. It would be a shame if it stayed less noticed. Is there a document that promotes the end user transition?

Presumably, it could answer some basic questions:

Why is LaTeX 3 better for end users than LaTeX 2e?
How should one go about learning to use it?
What should I now do differently?

For example, presumably, I should use some new commands (e.g., \NewDocumentEnvironment instead of newenvironment).

Pointers are appreciated.

PS: My wish that the name space for macros defined by end users would allow trailing digits, did not seem to have come true :-(.

A better phrasing of that statement is: the expl3 programming layer was incorporated into the LaTeX2e kernel. LaTeX2e usage stays the same for end users (so much so that you didn't notice it :). Of course, moving forward, documentation will be updated to recommend newer and more powerful interfaces, but old things will still work for the forseeable future (forever, likely, given the backwards compatibility tradition in the TeX community) — Phelype Oleinik, Feb 11 '22 at 03:17
Do you have a particular task in mind? How do you like to learn? Expl3 is too big for "a" tutorial; on the other hand, it is consistently and logically structured, so is easy to follow. — Cicada, Feb 11 '22 at 04:03
Regarding your PS: in the next latex (already available as latex-dev) you will be able to define a command with digits with \ExpandArgs{c}\newcommand{blub123}[1]{Hallo #1!} and then use it with \UseName{blub123}{world}. — Ulrike Fischer, Feb 11 '22 at 08:50
Alan Xiang has written a LaTeX 3 tutorial which also helps you getting used to interface3.pdf. — Ulrich Diez, Feb 11 '22 at 19:44
Thank you for your question which spurred me on to ask a follow up https://tex.stackexchange.com/questions/633551. — Peter Wilson, Feb 11 '22 at 19:47
@UlrikeFischer: I assume that command names with digits require some wrapper (\UseName for example). Otherwise, a command named \frac12 might cause some problems. — robjohn, Feb 13 '22 at 10:45
Related question latex3 - How to make the transition from LaTeX2e to expl3 syntax? - TeX - LaTeX Stack Exchange (without much useful answer though?) — user202729, May 18 '22 at 16:01

score 47 · Answer 1 · edited Feb 14 '22 at 04:45

There is no LaTeX 3. The change that occurred was that the expl3 package which was initially conceived as "experimental latex 3" has been incorporated into the LaTeX format as a permanent stable enhancement, the "L3 programming layer".

On the terminal in every job, LaTeX reports this as:

LaTeX2e <2021-11-15> patch level 1
L3 programming layer <2022-02-05>

As a programming layer, you would not expect "end users" to be using this directly, but they will be using commands that are written using these commands.

Notable user level commands written in this L3 programming layer are

fontspec so all the font handling in LuaTeX and XeTeX
siunitx for consistent display of values and units.
ltcmd (part of the LaTeX format, formerly xparse) \NewDocumentCommand and related constructs providing enhanced alternatives to \newcommand
The new hook system re-implementing hooks such as \AtBeginDocument, with many more hooks allowing patching general commands, environments and packages via \AddToHook.
The new keys system based on l3keys package but providing a much enhanced keyval system, that is now available to package writers, both for commands and also in the latest release as a new key-val based package option system (this is very new and probably not used by any packages yet).

At a lower level, the format now includes other L3 programming layer modules that don't have user level interfaces yet but l3color has the back end support for a color system along the lines of xcolor, l3backend has back end support for graphics inclusion which could allow a re-implementation of graphicx, and support for linking which should allow build in support for features currently provided by hyperref.

Currently a lot of work is being done to improved PDF accessibility tagging, all of which is written in the L3 programming layer, but it will finally not require much or any "end user" action at all. Their documents should just generate more accessible PDF due to internal enhancements.

The above code is all by LaTeX team members, but other packages by LaTeX contributors such as the new extended tables package, tabularray are also written using more or less purely L3 code.

Note on your final PS regarding name parsing note that the L3 programming layer, like LaTeX2e is not a new executable. It is written in TeX, and runs on the same engines with the same primitive behaviour. So the catcode mechanism that underlies the basic TeX token parsing that governs the rules about the characters allowed in command names is unchanged. Making digits letters (catcode 11) so they are allowed in command names, makes it hard to use them in other constructs, and L3 can not change TeX.

score 23 · Answer 2 · edited May 19 '22 at 23:12

23

In addition to David's extensive answer, one point to look at is usrguide3.pdf if you look for "what is relevant for me as a user". It will contain additions to LaTeX (which are likely to be written internally in the L3 programming layer) that are relevant and new.

As usual, documentation is a hard thing, so this is probably always lagging behind somewhat (e.g., the whole hook management system is only in lthooks-doc so far --- on the other hand that is mainly of interest for programmers and less so for users.

The other starting point is to take a look at ltnews.pdf(all newsletters) or the recent ones, e.g., ltnews30.pdf to ltnews34.pdf, all accessible via texdoc ltnews34, etc.

edited May 19 '22 at 23:12

kjetil b halvorsen

522

answered Feb 11 '22 at 17:02

Frank Mittelbach

77,146

thx, frank, for all the work. yes, docs are hard. at some point, I hope someone will write a 10-page document that is a transition guide more than a reference guide. in the meantime, I (as an enduser) will start transitioning over to expl3. incidentally, it probably would be easy to provide a script that stabs at converting old style macro arguments to new style macro arguments. – ivo Welch Feb 11 '22 at 17:24
2

These are some great pointers to the documentation! Essentially all of them are new to me — which makes me wonder: How discoverable are they? Is there some kind of index of all the various "core documenation" for LaTeX (enumerating things suchs as usrguide3, interface3, lthooks-doc, ...)? – Wisperwind Feb 14 '22 at 09:38
@Wisperwind the question then is how discoverable is that overview? I think you can't win. But for what it is worth: all LaTeX releases have been accompanied by a newletter ltnewsXX for the last 30 years and we also announce new stuff on https://www.latex-project.org where you can subscribe to a newfeed. And the core docs are also listed on that web site for LaTeX. Hope that helps. – Frank Mittelbach Feb 14 '22 at 10:32
Where you can find usrguide3.pdf online (on CTAN)? – Jakub Narębski Feb 15 '22 at 20:04
@JakubNarębski texdoc usrguide3 in a shell. Locating it on ctan is harder: it is in latex/base but not listed in the pdf's on the front page, so you have to browser the directory of files. – Andrew Swann Feb 16 '22 at 09:13
Having now looked at usrguide3, it seems to cover much of the material in the xparse documentation. – Andrew Swann Feb 16 '22 at 09:16
1

@AndrewSwann it covers the parts that we think should be moved forward and have been placed into the format. xparse was "x" as in experimental and some ideas turned out to be not really useful or say, good enough to promote. xparse is a superset though, so if you want the others you can load xparse instead of just using the LaTeX format. – Frank Mittelbach Feb 16 '22 at 17:50
1

@FrankMittelbach Thank you for the explanation. That makes sense. – Andrew Swann Feb 17 '22 at 09:53

Is there a LaTeX 3 transition guide for users (not gurus)?

2 Answers2

Linked