latex-compile

Compile a LaTeX document, fix all errors and all aesthetic issues so the PDF is clean and the log is empty — without ever altering content to make things fit.

When to invoke

After any edit to a .tex file. Also invoke before committing.

Input

The user may specify one or more files: /latex-compile brief.tex workbook.tex. Default: workbook.tex. Work from the project root (wherever CLAUDE.md lives).

1. Compile — always force a real pass, capture stdout

Critical: never trust the `.log` for warnings. When latexmk decides targets are up-to-date it skips compilation and leaves a stale log that under-reports (or zeroes out) overfull warnings. Force a real pdflatex pass and capture its stdout:

pdflatex -interaction=nonstopmode <file> > /tmp/tex.txt 2>&1

Run twice when cross-references, TOC, or forward \refs changed (or a manual \label bibliography needs a second pass to resolve \cite).

Always use `grep -a`. pdflatex embeds binary font-path bytes in its output, so plain grep treats the stream as binary and matches nothing. Every grep below uses -a.

2. Collect ALL issues from the fresh stdout

grep -anE "^! |LaTeX Error|Undefined|Overfull|Underfull|multiply defined|Font (shape|Warning)|File .*not found" /tmp/tex.txt

3. Fix fatal errors first

The ! … line and the l.<N> line below it locate the fault.

• Undefined control sequence → check macro definitions / \newcommand spelling
• Missing `{`/`}` → stray brace; count braces around the line
• Missing `$` → stray char in math, or a fragile macro in a section title →

\DeclareRobustCommand or \texorpdfstring

• `\begin{X}` without `\end{X}` → find the unclosed environment
• `File not found` → add \usepackage or report the missing dependency

Recompile and repeat until the fatal grep is empty.

4. Undefined references and citations

• Label/cite exists in the document → just add a second compile pass.
• Label exists only in a different file (cross-file \ref) → it can never resolve.

Replace \ref{label} with the section/theorem title as literal text — e.g. `\S\,Title of that section''. Never leave a dangling \ref that prints ??`.

5. Overfull hboxes — triage, then REFORMAT (never reword)

Overfulls come in three flavors: in paragraph at lines N--M, in alignment at lines N--M, and detected at line N (math/box mode — the wide row is a line or two above N).

Triage by overrun magnitude:

• > 10pt — runs off the page → fix
• 5–10pt — noticeable → fix if quick
• < 5pt — below visual threshold → leave; \hfuzz=1pt / \emergencystretch=3em in

the preamble absorbs these silently

Hard rule: do not change mathematical content, wording, table data, or abbreviate headers to make things fit. Fix overflow only by changing layout:

• Inline `$…$` that overruns → promote to a \[ … \] display
• Long single-line display → break before a relational operator (=, \le, \to).

In align, end the line with \notag\\ then &\quad continuation. Keep the `\label` and number — \notag goes only on continuation lines, never the labelled one

• Long boxed equation → \boxed{\begin{aligned} … \end{aligned}}
• Wide smallmatrix-bracket display → split the multi-integral/product across two

align lines, or wrap the whole display in {\small … }

• Wide table → \small / \footnotesize / \resizebox{\textwidth}{!}{…} —

do NOT abbreviate headers or cells

• Overflowing prose → \begin{sloppypar}…\end{sloppypar}; or split a long unbreakable

\texttt/\code token across two \code{…} units at a natural boundary; or set multi-line code as a verbatim / \begin{quote}\small\ttfamily\raggedright … \end{quote} block (raggedright avoids the new overfull but yields harmless underfulls)

• Single wide inline token → \allowbreak at a factor boundary, or promote to display

6. Other aesthetic issues

• Underfull hbox (badness ≥ 1000) → restructure so the last line fills; for a genuinely

ragged/centred context it's expected — suppress locally with \hbadness=1000 only if unavoidable. (Beware: \emergencystretch can turn a sub-\hfuzz overfull into a noisy underfull — prefer fixing the overfull or leaving it under \hfuzz.)

• Widows/orphans → \widowpenalty=10000 \clubpenalty=10000 in the preamble; for one

case, \needspace{3\baselineskip} or a manual break before the paragraph.

• Alignment → in align, every row needs the same number of &; remove blank lines

inside align (spurious gap) and a stray trailing \\ on the last row.

• Fonts → OT1 warnings: ensure \usepackage[T1]{fontenc}. Use \bfseries/\itshape,

not \bf/\it. Harmless: \code{}/\texttt inside a bold section title falls back to medium typewriter (CM has no bold tt) — a Font Info, not a warning; leave it.

• Typography → thin space \, before units / between adjacent integrals; \ldots/\dots

not ...; `` …'' ` not "…"; e.g.\ /cf.\ ` to avoid double sentence-spacing.

7. hyperref / PDF-bookmark and Unicode gotchas

• A macro or math in a \section/\subsection title makes hyperref choke building the PDF

bookmark — Token not allowed in a PDF string (harmless) or Illegal parameter number in \Hy@… (a real error, from a multi-arg macro like a smallmatrix-bracket in the title). Wrap the title: \section{\texorpdfstring{<TeX with macros>}{plain-text bookmark}}.

• Literal Unicode (ω, π, … in code listings or prose) under pdflatex+inputenc needs

\DeclareUnicodeCharacter{03C9}{\ensuremath{\omega}} (and {03C0}{…\pi} etc.) in the preamble, or it errors with Unicode character … not set up for use with LaTeX. In a verbatim block prefer ASCII (Pi, names) — declarations don't fully apply there.

8. Verify

Recompile with pdflatex (same > /tmp/tex.txt capture), re-run the §2 grep on the fresh stdout, and confirm: no ! errors, targeted overfulls gone or < 5pt, no new issues, refs/cites resolved.

9. Report

Compiled <file>: N pages.
Errors fixed: <list or "none">
Aesthetic fixes: <list with the layout rule used, or "none">
Remaining warnings: <list or "none — log is clean">

If a warning is genuinely unavoidable, say so and explain why it is harmless.