retex-engine 0.9.0

The TeX typesetting engine for retex
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

# 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

```sh
cargo build --release
```

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

## Usage

```sh
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:

```text
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](CONTRIBUTING.md#provenance-and-licensing-clean-room-rule).

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:

* `tex.web`: <https://ctan.org/tex-archive/systems/knuth/dist/tex/tex.web>
* `mf.web`: <https://ctan.org/tex-archive/systems/knuth/dist/mf/mf.web>
  (also on CTAN mirrors, e.g.
  <https://ctan.gonzaleztroyano.es/systems/knuth/dist/mf/mf.web>)
* `etex.ch`: <https://github.com/TeX-Live/texlive-source/blob/trunk/texk/web2c/etexdir/etex.ch>
  (TeX Live's source tree)

## Documentation

* [ROADMAP.md](ROADMAP.md): milestones and status
* [ARCHITECTURE.md](ARCHITECTURE.md): crate layout and design
* [CONTRIBUTING.md](CONTRIBUTING.md): engineering rules, provenance, testing
* [DEPENDENCIES.md](DEPENDENCIES.md): why each external crate is used

## License

CC0-1.0. See [LICENSE](LICENSE).