latex-production

Files (2)

• SKILL.md
• log-patterns.md · references/

SKILL.md (first lines)

# latex-production

This file is the canonical Empirical Workflow Kit implementation. Runtime views
defined in `workflow.manifest.yaml` link here; edit only the canonical tree.

Adapted from `ericluo04/claude-academic-workflow` at commit `8958cc246e65cdf7c36604f397a1c1719b7e2c14`; see `THIRD_PARTY_NOTICES.md`. Read `runtime-profile.yaml` for local tool, state, PDF helper, and presentation-asset paths before running commands.

Compile a `.tex`, parse the log into a ranked report with correct `file:line`
attribution, and diff it against the previous build. The default is
compile-and-report only; nothing in the source is edited unless `--figures` is
passed.

Parsing detail (package tables, log regexes, file-stack rules, box thresholds,
state schema) is in [`references/log-patterns.md`](references/log-patterns.md).
Read it before steps 3 through 5. Diff-vs-last-compile is adapted from
`compiledeck` in [scunning1975/MixtapeTools](https://github.com/scunning1975/MixtapeTools).

Compilation and layout checks certify neither interpretation nor contribution.
If a figure repair changes a substantive caption, claim, or magnitude, apply
`../empirical-workflow/references/research-writing.md` and review its evidence;
do not rewrite the economic story as part of routine formatting.

## Options

| Option | Default | Meaning |
|---|---|---|
| positional path | required | Master `.tex`. Absolute path, or a basename to resolve. |
| `--engine=` | `auto` | Force `pdflatex` / `xelatex` / `lualatex`. |
| `--outdir=` | `build` | Aux directory (`latexmk -outdir`). |
| `--box-threshold=` | `5pt` | Overfull reporting gate. |
| `--figures` | off | Opt-in: run the step-6 review loop on every TikZ/pgfplots figure, then splice back. |
| `--max-iter=` | 5 | Rounds per figure in the `--figures` loop. |
| `--goal=` | from caption | What a figure should communicate. Passed to the reviewer verbatim. |
| `--output=` | `$RUN/final.tex` | Where an approved standalone figure lands when there is no master to splice into. |
| `--no-bib` | off | Skip the bib run (`-bibtex-`). |
| `--force` | off | Compile even if a conflicted copy is present. |
| `--clean` / `--clean-all` | off | `latexmk -c` / `-C`, then stop. |

## Resolving the file

Read `runtime-profile.yaml`. In order: use an absolute or cwd-relative path if given;
otherwise `Glob` the manuscript roots configured in `runtime-profile.yaml` and, if a
project name was mentioned, filter to that project directory; otherwise `Glob`
`*.tex` in the cwd and pick the one with `\documentclass`. Ask only if that
leaves zero or several plausible masters.

A `.tikz` path, or an inline TikZ block pasted into the request, has no master to
compile. Take it as `--figures` on that one block: skip steps 1 through 5 and go
to step 6 with the block as the single unit, wrapped as step 6 describes. There
is nothing to splice back, so the approved source goes to `--output` (default
`$RUN/final.tex`) and the path is reported.

## Step 0, pre-flight

1. `Read` the master.
2. Conflicted-copy guard. This setup assumes these projects sync through
   Dropbox (adjust to your machine), so compiling
   next to a stale sibling means reporting errors the user already fixed
   elsewhere. `Glob` the project directory recursively for `*conflicted copy*`
   (`.tex`, `.bib`, `.sty`, `.cls`). If any exist, stop and list them with
   mtimes so the user can resolve the conflict. `--force` overrides.
3. `--clean` / `--clean-all`: run `latexmk -c -outdir=<outdir> <file>` or
   `latexmk -C -outdir=<outdir> <file>` and stop.
4. Resolve `latexmk` and Ghostscript from the commands configured in `runtime-profile.yaml`.
   If the LaTeX command is unavailable, fail with `SETUP_MISSING:latexmk`.
   With `--figures`, also check the configured Ghostscript command; if absent, report
   `SETUP_MISSING:gs` and skip the figure pass, keeping the compile report.

## Step 1, detect engine and bib backend

Read the preamble plus any `\input`'d preamble file (§6 of the reference).
A `% !TEX program =` magic comment wins. Otherwise `fontspec` / `unicode-math` /
`\setmainfont` / `xeCJK` / `ctex` implies xelatex; `\directlua` / `luacode`
implies lualatex; else pdflatex. `--engine=` overrides both.

Bib backend, unless `--no-bib`: `biblatex` or `\addbibresource` means biber;
`natbib` plus `\bibliographystyle` means bibtex. Warn on a mismatch (biblatex
loaded with a leftover `\bibliographystyle`, or `\addbibresource` with no
biblatex).

Print the detection before compiling:

```
File:   <path>
Engine: xelatex  (\setmainfont in preamble)
Bib:    biber    (\addbibresource)
Outdir: build/
```

## Step 2, compile

```bash
latexmk -f "$ENGINE_FLAG" -interaction=nonstopmode -synctex=1 -outdir=<outdir> <file>
```

`ENGINE_FLAG` comes from the step-1 detection: `-pdf` (pdflatex), `-pdfxe`
(xelatex), `-pdflua` (lualatex).
`-f` matters: without it latexmk stops at the first failing pass, so the log
holds one error instead of all of them. Never pass `-halt-on-error`. Add
`-bibtex-` for `--no-bib`. A nonzero exit code is expected on a failed document
and is not a tooling failure; parse the log regardless.

## Step 3, parse the log

Read `<outdir>/<jobname>.log` and run the file-stack tracker from §3 so every
`file:line` lands on the right `\input`'d sub-file rather than the master. The
tracker must push a placeholder for non-path `(` as well, otherwise the parens
inside ordinary messages (`Overfull \hbox (15.83003pt too wide)`) pop real files
off the stack and every subsequent attribution is wrong.

Extract blocking errors (`! ...` plus the following `l.<N>`), undefined
refs/cites (§4), and boxes (§5).

## Step 4, rank and report

Lead with one verdict line, `BUILD OK` / `BUILD OK (with warnings)` /
`BUILD FAILED (N blocking)`, and the PDF path. Then, in this fixed order:

1. Blocking errors. `<file>:<line>` plus the `! ...` message. For

From bobbyZhong10/empirical-workflow-kit, MIT.

More from bobbyZhong10/empirical-workflow-kit