[Tex/LaTex] Moving to LaTeX3 for package authors

documentationexpl3latex3package-writing

I would like to write a package using as much of LaTeX3 stuff as possible (in particular expl3, xparse and xtemplate).

What should I read to learn these?

In particular: I know that there are good introductions to expl3 and xparse. I remember having read something very nice on xtemplate (with examples etc.), but could not find it (I googled the LaTeX3 project site, CTAN, the TUGboat and PracTeX journal). Can anyone help me finding that?

Best Answer

For programming packages that implement new functionality for LaTeX2e what you mainly need is the programming layer of LaTeX3.

xparse additionally offers you some help for defining user interfaces in 2e style with optional arguments or star forms etc, but you can think of this as the syntactic sugar on top of the functionality your package provides. And in the opposite direction, xparse is also quite useful standalone, i.e., if you define commands using 2e methods and just want to have a more powerful user interface setup.

template finally is something that I think is right but not ready so I would use this only with caution. I'll expect later this year to to see more of the designer interface foundation layer to become available, but right now you would need to be at least prepared for possibly larger interface changes. You asked for documentation on templates: there is of course the template file itself: template.dtx but there is also a short paper by Lars and some related articles on the project website.

The LaTeX3 programming layer

Concerning documentation of the programmin layer of LaTeX3 (aka expl3) I suggest reading the following documentation (in order):

expl3.pdf

Some introductory notes on some of the concepts

interface3.pdf

The full interface description of all functions of the LaTeX3 programming layer as released. There are a number of modules that are not yet part of the stable kernel (in the directory l3kernel), but what is in this document is the description of everything we consider "stable".

Smaller changes are possible though and programmers making use of l3kernel are strongly encouraged to subscribe to the LaTeX-L mailing list: announcements concerning the deprecation or modification of functions are made on the list.

This document is a reference document so functions are document by module and not really a manual for learning the language --- sorry the latter doesn't yet exist. It also doesn't give you many examples of how to use the constructs but rather documents the specific interfaces.

source3.pdf (don't read (initially) :-)

For understanding of how this is implemented one can read source3.pdf which gives both the specification as well as the full documented code. However, I suggest not to start with this for a couple of reasons:

  • The core modules implement data structures and functions that are essential for building higher-level constructs. For this reason they are (at least if they are likely to be needed often) tailored for speed and that means that some of the tricks used there are not appropriate for coding outside the kernel
  • The core modules are build on top of the primitives of TeX so they can only partially make use of the core concepts of expl3. For example, you will find a lot (about 450) uses of \exp_after:wN (also known to us as \expandafter) while I would claim that in normal expl3 programming outside the kernel this command should never or hardly ever be used.

How to use the programming layer

A better starting point for looking at how to use the LaTeX3 programming layer are the examples that have been given in replies to questions on this site and also perhaps something like the higher-level modules. At this point in time in the kernel directory there is only l3coffins.dtxthat I would recommend for this. More will follow over time.

Related Question