retex-lua 0.9.0

Embedded Lua and the LuaTeX Lua API for retex
Documentation

retex

A TeX engine written in Rust, designed as a drop-in replacement for lualatex: the same output (pixel-identical PDFs), 2× faster, and with automatic multi-pass compilation, so you never rerun by hand to get cross-references right.

Status: beta: complex TeX/LaTeX/LuaLaTex documents successfully and accurately compile, including eg complex TikZ, maths, graphics-heavy page. More testing for edge-case handling still required.

Building

cargo build --release

Requires Rust ≥ 1.93 and an installed TeX Live tree (retex reads the LaTeX macro files and fonts from it).

Usage

retex paper.tex

retex runs as many passes as the document needs, and BibTeX or biber when the bibliography changed, then reports errors and warnings with their source location:

error: Undefined control sequence \foo
  --> ./paper.tex:3:18
  |
3 | Some text with a \foo command that does not exist.
  |                  ^^^^
  = help: this command is not defined: check its spelling, or load the package that defines it
warning (LaTeX): Reference `sec:missing' on page 1 undefined.
  --> ./paper.tex:5
retex: wrote paper.pdf (1 page, 7 KB) in 0.10 s, 1 pass; 1 error, 1 warning (details in paper.log)

The log file is always the one LuaTeX writes. --compat=lualatex shows LuaTeX's exact terminal output instead. Run under the name luatex or lualatex, retex behaves like LuaTeX for tools that drive TeX themselves (latexmk, l3build): LuaTeX's terminal output and a single pass.

Only the PDF is written next to the document: the auxiliary files (.aux, .log, .toc, .bbl, …) go to a hidden directory, .retex/<job>-<hash>/ (one per document, ignored by git). --no-aux-dir keeps them next to the document, as do -shell-escape (external programs expect LuaTeX's file layout), --output-directory and --compat=lualatex.

retex --watch paper.tex stays running and rebuilds whenever a file the document uses changes. The preamble is processed once: rebuilds after an edit of the document body start where the document begins.

Clean-room provenance

retex is written from scratch and released under CC0. No code of another TeX implementation (LuaTeX, pdfTeX, XeTeX, luaotfload, HarfBuzz, ...) has been read, whatever its license. Behaviour is established from the output of lualatex on our own test documents, from values returned by LuaTeX's documented Lua API, and from published documentation and specifications. The complete policy is in CONTRIBUTING.md.

Three of Knuth's published programs and one change file are used as references for the algorithms retex shares with them:

file what it is used for
tex.web TeX: The Program, D. E. Knuth TeX82 semantics
etex.ch the e-TeX change file to tex.web, P. Breitenlohner and the NTS team e-TeX extensions
mf.web METAFONT: The Program, D. E. Knuth the random number generator LuaTeX shares with METAFONT

Why they are permissible:

  • They are published works whose terms allow unrestricted copying. tex.web and mf.web begin with: "Unlimited copying and redistribution of this file are permitted as long as this file is not modified. Modifications are permitted, but only if the resulting file is not named tex.web" (resp. mf.web). etex.ch authorizes copying as long as no changes are made to the copy. The two programs are also printed as volumes B and D of Computers & Typesetting. They are not under the GPL, MIT or Apache licenses: their terms govern copies of the files themselves.
  • retex neither copies nor modifies them. They are read as documentation, the way a textbook is; retex's code is an independent Rust implementation, and none of the files is part of this repository (they are kept outside it, under the ignored target/ directory, for reference).
  • They describe the reference behaviour. For TeX82, e-TeX and the METAFONT random number generator, these programs are the specification: LuaTeX documents its behaviour as that of TeX and e-TeX, and its random numbers follow METAFONT's generator.

Sources, with the license text at the top of each file:

Documentation

License

CC0-1.0. See LICENSE.