Tips for LaTeX3 beginners

Last updated August 7, 2022
While current stable version is LaTeX2e, LaTeX3 is already delivered as expl3 as the “L3 programming layer”. It provide a unified programming layer for package author and experienced user.
This blog post will not be the thorough tutorial, but rather a complement.

Where to Start?

Before using LaTeX3, you should have a basic idea in LaTeX such as syntax, toolchains, packages et al. Then, following materials are what you need now.

Some Introduction blog posts


  • expl3: Refered when needed.
  • xprase: Help to define user command like \newcommand.

Minimal Example for Class Author

% main.tex \documentclass{test} \begin{document} \hello \end{document}
% test.cls \RequirePackage{expl3} \ProvidesExplClass{test}{2022-01-01}{0.1.0}{Minimal Example Class} % Expl3 syntax start from here. \NewDocumentCommand { \hello } { } { hello, world! \par 你好,世界! } % For CJK user, or you may load `book` \LoadClass{ctexbook}

Global Variables and Local Variables

Global variables should be assigned globally and may get the proper value whenever you want.
Local variables does not have this assumption.

Equivlent to \renewcommand

Although xparse provides \RenewDocumentCommand as equivlent to renew a user command. But I suggest you only use it in global level and with \NewDocumentCommand, in order to provide user interface. In the other circumstances, for example, to redefine a variable provided by other package, then \cs_set:Npn should be your choice.
\RenewDocumentCommand sometimes does work as expect, while \cs_set:Npn always does.

Generate Variation

Usually, expl3 only ship functions with common variants: there is \tl_if_empty:NTF and also \tl_if_empty:nTF . But if you have want to expand the first variable, then you don’t have \tl_if_empty:xTF by default.
\cs_generate_variant:Nn is the one you need to generate these variations.
\tl_new:N \tmp_a_tl \tl_new:N \tmp_b_tl \tl_set:Nn \tmp_a_tl { \tmp_b_tl } \cs_generate_variant:Nn \tl_if_empty:nTF {x} \tl_if_empty:nT { \aaa } {hi} \tl_if_empty:xT { \aaa } {hello} % The output will be `hello`.

l3keys usage

In expl3 , package l3keys provide a consistent approach to define and process the key-value interface.
process documentoptions before loading the class.
local variable init