spb/llm-api-toolkits

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