texforge 0.8.0

Self-contained LaTeX to PDF compiler CLI
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
116
117
118

---
title: Building
description: Compile to PDF, watch mode, and the texforge runtime directory.
order: 4
---

# Building

## `texforge build`

Compiles the project to `<title>.pdf` in the project root:

1. Copies sources into a temporary build directory (originals are never
   modified).
2. Renders embedded [diagram environments](diagrams.md) to PNG.
3. Invokes Tectonic on the entry point declared in `project.toml` and
   places the resulting PDF (named after the document title) in the
   project root.

On the first run texforge downloads the Tectonic binary into
`~/.texforge/bin/` automatically.

## Reproducible builds

By default a build embeds a current timestamp, so the same source produces a
different PDF on each run. For anything that compares outputs — visual
regression, build caching, meaningful diffs — texforge can pin the build time:

```bash
texforge build --reproducible
```

This sets `SOURCE_DATE_EPOCH` for the Tectonic invocation. With no explicit
value a fixed epoch is used (never "now"); a release can pin its own:

```bash
texforge build --reproducible=1700000000
```

The same behaviour can be made the default for a project in `project.toml`
(see [Configuration](configuration.md)); the `--reproducible` flag wins when
both are present.

**The guarantee, and its limit:** identical source plus an identical Tectonic
version yields an identical PDF. A different Tectonic version (or engine
updates within it) can still change the output, and the setting does not alter
the visible content of a document — it only pins the embedded time.

## Watch mode

`texforge build --watch` watches `.tex` files and rebuilds automatically:

```bash
texforge build --watch            # rebuild after 2s of inactivity (default)
texforge build --watch --delay 5  # custom debounce delay in seconds
```

The terminal shows a live session timer, build count and the result of the
last build. Press `Ctrl+C` to stop.

## Cleaning

```bash
texforge clean   # remove build artifacts
```

## Preview

`texforge preview` rasterizes the compiled PDF to PNG pages for quick visual review or for embedding in documentation:

```bash
# Rasterize all pages (writes to ./preview/)
texforge preview

# Single page
texforge preview --page 1

# Custom output directory
texforge preview --out ./previews

# Scale up for higher resolution (default: 1.0 pixel per PDF point)
texforge preview --scale 2.0
```

## PDF Inspection

Once built, the PDF can be inspected without re-compiling:

```bash
# Extract text as readers and accessibility tools see it
texforge pdf text

# Report pages, fonts, whether fonts are embedded, and metadata
texforge pdf info

# List which section opens each page (for diffing in version control)
texforge pdf pages

# Verify significant source words survived into the PDF
# (catches missing fonts, encoding issues, rendering bugs)
texforge pdf check
```

## Runtime directory

Texforge keeps its engine and template cache under `~/.texforge/`:

```
~/.texforge/
  bin/
    tectonic            # LaTeX engine (auto-installed on first build)
  templates/
    general/            # cached templates
    apa-general/
    ...
```

Deleting this directory is safe: everything is re-downloaded on demand.