QA procedure in detail
Each step names the command, the pass criterion, and what to do when it fails. Commands are
node scripts/latex.mjs <command> <main.tex>.
0. Know the toolchain
status lists the tools found. Without latexmk the tool runs its own loop (engine, bibliography
tool, engine up to three more times). Without biber a biblatex document cannot resolve
citations; without pandoc there is no Word conversion. Choose the engine the document was
written for: fontspec, unicode-math or polyglossia in the preamble mean XeLaTeX or LuaLaTeX.
1. Clean build from scratch
compile --clean (or qa, which always cleans). Pass: success: true, a page count, no
entry in errors.
A build that only works with yesterday's auxiliary files is not reproducible: stale .aux,
.bbl or .toc files hide missing citations and wrong numbers. The clean build removes only the
tool's own .latex-build/ directory.
When it fails, read errors[0]: file, line, message, the source context and a one-line
explanation. Fix that one and rebuild. --keep-going lists every error in one pass when there
are many independent ones (for instance a batch of missing figures).
shell_commands_blocked lists what the document tried to run through \write18. That is a
finding to report to the user, not something to enable.
2. Zero undefined references and citations
log gives undefined_references and undefined_citations with file and input line. refs
gives the same from the sources, plus the list of labels that do exist — usually the fix is a
typo (fig:resutls) or a label that was renamed.
Pass: both lists empty after the final run. A ?? or a bold [key] in the PDF is the
visible form of this failure.
3. No duplicate label
refs → duplicate_labels, each with every location. Duplicates make references point to the
last definition; the PDF looks fine and is wrong. Copy-pasted floats are the usual source.
4. No pending rerun
log → rerun_needed. With latexmk this is false at the end unless the document never converges
(a page number that oscillates between two values, typically from \pageref near a page break).
5. Overfull boxes under the threshold
overflow --hbox 1. Each overfull hbox comes with file, line range, size in points and the source
line. Pass: none above the threshold. Use 1 pt for a final manuscript; anything under 1 pt is
not visible.
Fixes, mildest first:
| Cause | Fix |
|---|---|
| A word TeX cannot hyphenate | \- at the allowed break points, or \hyphenation{...} in the preamble |
| A long URL or DOI | \url{} with the xurl package |
| Inline math that cannot break | reword, or display the formula |
| A table wider than the text | fewer columns, tabularx with X columns, a smaller \tabcolsep; scaling the whole table is the last resort |
| A tight paragraph | reword; microtype; locally \emergencystretch=1em |
Do not silence the warning with \hfuzz or a global \sloppy: the text still sticks out.
Underfull boxes (loose lines, short pages) are counted but do not fail the check.
6. Decks: no frame overflows
beamer → overflowing_frames. See beamer-overflow.md.
7. Every float is referenced
refs → unreferenced_floats: figures and tables whose label nothing refers to. Journals ask
that every float be cited in the text, and an unreferenced float often means a paragraph was cut.
A float with no label at all is not listed — give every float a label.
unused_labels (sections, equations) is advisory: an unused section label is harmless.
8. Bibliography
bib reports the backend the document expects (\usepackage{biblatex} → Biber unless
backend=bibtex; \bibliography{} → BibTeX), the backend whose log is in the build directory,
the entries it could not find, and entries without author, title or year.
Pass: the expected backend ran, missing_entries is empty, no error.
refs adds unused_bib_entries (advisory) and duplicate_bib_keys (fix: BibTeX keeps one and
may not say which).
9. Consistent numbering
numbering lists every label with its number, page and kind, and the captions as typeset.
Use it to:
- check numbers written by hand anywhere (abstract, cover letter, reply to referees);
- spot
same_number_shared: two labels with the same kind and number. Legitimate inside one float; otherwise a\labelsits before its\captionand carries the section number; - confirm that appendix floats are numbered as intended (A1, A2 …).
text --from N --to M shows what was typeset on those pages, to verify a sentence or a caption
as it appears in the PDF.
10. Report
State the engine, the page count, which checks passed, and each remaining failure with its file
and line. Say plainly what was not checked: content, figures' appearance, anything positioned
absolutely on slides, and — for Word files — everything listed under does_not_survive.