VesperaZephyr/agent-skills

LaTeX Math Book Re-typesetting Engineering Skill

Goal and Scope

An engineering methodology and pitfalls database for high-fidelity re-typesetting of scanned/PDF math monographs into compilable, searchable, and navigable LaTeX source code. Real-world sources:

• Western: Conway's A Course in Functional Analysis GTM 96 full re-typesetting (436 pages, 11 chapters + 3 appendices, 0 compilation errors / 0 dead links / 1606 internal jumps).

• Chinese: Xu Senlin and Xue Chunhua's Mathematical Analysis (Volume One) full re-typesetting (551 pages, 6 chapters + preface + references, 40 chapter source files, 23 original TikZ graphics, 0 errors / 0 missing characters / 0 undefined references / 0 Overfull / PDF layer ?? 0).

• Per-chapter page numbering western: Serre's Abelian l-Adic Representations and Elliptic Curves full re-typesetting (203 original pages → 129 pages, preface + 4 chapters + two bibliographies + index, per-chapter page numbers I-1/II-42/B-5/Index-3, 0 errors / 0 undefined / 0 duplicate labels, manually numbered statement environments + biblatex sortkey to lock original book numbers).

• Single-volume continuous page numbering western: Samuel's Algebraic Theory of Numbers full re-typesetting (110 original pages of text → 104 pages, section bare numbering Theorem 1/(1), references [1]–[9], exercises per chapter, index V.2 links; 371 labels / 846 internal link targets / 922 PDF Link annotations / 110 Q.E.D., 0 errors / 0 dead links / link color实测 (0,0,178)).

• Applicable to: re-typesetting (not translation). Four routes: ① Springer GTM single-counter format (gtmitem shared counter, numbering \thesection.\arabic{gtmitem}); ② Chinese books with custom cls (xeCJK + Fandol, chapter-based files + generator output); ③ Per-chapter page numbering monographs with custom cls (\chapcode + redefining \thepage, manually numbered statement environments); ④ Single-volume continuous page numbering monographs with bare section numbering (keyword-based counters + restart per section, \folio only sets division start). Graphics follow the "General Math Illustrations" section below: editable redraws use native TikZ; faithful reuse can retain the original vector PDF.

• Not applicable to: pure translation projects of the mathtranslation type (belongs to the mathtranslation skill).

When to Use

• User says "re-typeset book X" "typeset PDF into LaTeX" "fix cross-references" "fix overfull" "equation number misalignment" "OCR garbled text".
• Before starting a re-typesetting project, must first establish discipline red lines.
• Compilation shows multiply defined / undefined references / numbering misalignment / many overfull boxes.

Hard Discipline (Red Lines, Confirm Before Starting)

Item	Requirement
Line endings	CRLF, UTF-8 without BOM (applies to all .tex/.cls/.py files)
Build	xelatex -interaction=batchmode main.tex × 3 (clear aux × 4 after label changes)
Quality red lines	0 compilation errors, 0 undefined references, 0 missing characters, 0 overfull for new chapters
Content source	Based on original book PDF images; OCR is for search index only
Content changes	Only edit the generator (make_chNN_secM.py) → assemble; never directly edit chapters/*.tex
Numbering	First choose the route according to the original book: GTM uses shared gtmitem counter; manually numbered monographs or exam papers can use raw display numbers + hidden anchor counters. Must not arbitrarily change original numbers for continuity
Formulas	Unnumbered display formulas use bare \[\] / align*, or equation\notag; strictly forbidden to number them
Graphics	Prioritize redrawing with native TikZ/PGFPlots; original reliable vector graphics can be retained directly as vector PDF. Forbidden to convert vector graphics to PNG first then claim lossless; bitmap images in the original book must record their original limitations

Original Book Page Number Mapping

Physical page = book page + offset (GTM96 offset = 15). First measure the offset; all subsequent "check with original book" operations locate by physical page.

General Math Illustrations: Fidelity, Readability, and Per-Figure Verification

This section applies to curves, surfaces, vector fields, coordinate grids, orientation/boundary, faceted geometry, etc.; commutative diagrams continue with the per-edge audit in the next section. Use the illustration fix workflow shared by both skills; do not mechanically apply the cropping or scaling ratios of one book to another.

First independently inventory the figures in the original book and the actual build chain, then create a per-figure ledger recording physical page/crop box, figure number, all sub-figures, labels, arrows/orientation, source assets, final PDF page, and verification evidence. Equal counts or identical file names do not rule out "wrong figure replacing the correct one"; check adjacent figures, especially multiple figures on the same page and side-by-side figure notes.

Prioritize retaining reliable vector content from the original book; use native TikZ/PGFPlots redrawing when Chinese localization, uniform font, or geometric corrections are needed. Before redrawing, list visible mathematical facts: coordinate/curve relationships, vector endpoints, level set numbers and values, orientation, boundary symbols, occlusion, and projection. Must not change these facts for aesthetics. Complex surface and field figures should not degenerate into meaning-similar schematics. Re-arranged sub-figures must preserve reading order, proportional meaning, and connection relationships.

400 DPI rendering is only bitmap; true vector reuse must preserve PDF paths/glyphs/transparency and review output. The path bounding box from the drawing package may contain curve control points or be constrained by internal clipping; must not blindly take the union nor directly intersect it with the crop box as truncation evidence. Automatic cropping only produces candidates; must visually check the complete original page, candidate figure, and final book page. Preserve thin arrows, distant labels, sub-figure numbers, and appropriate safe margins.

Figure width is determined by final font size and page space; no fixed minimum/maximum width for the entire book; use local \linewidth, maintain aspect ratio. Dense sub-figures can be enlarged or rearranged, but cannot be reduced by cropping edges/labels. Delivery requires a per-figure final page correspondence; compilation success, 256 figure numbers matching 256 files, or high pixel similarity are not substitutes for content, coverage, and visual verification.

Commutative Diagrams and Arrow Fidelity Review

This section specifically refers to commutative diagrams, exact sequence grids, pullback/pushout diagrams composed of nodes and morphisms; general geometric illustrations, curve plots, and formula matrices follow their respective rules. Use tikzcd for drawing or review; do not default to array for arrow diagrams. When finding existing drafts, do not just search for tikzcd: run the scripts/inventory_diagrams.py from the accompanying audit skill, covering all source files, input files, footnotes/appendices, and macro definitions actually involved in the build; classify each candidate as commutative diagram, formula/table, macro to expand, or pending. Arrow diagrams within array/aligned/matrix/CD/xymatrix are also included; ordinary matrices are not mechanically migrated due to containing a matrix environment.

For each figure, independently establish node grids and edge lists from the original book PDF and the re-typeset draft, then compare per edge: start point, end point, arrow head, injection hook end, double head/equals/no head line, solid/dashed lines, labels and side, empty nodes and zero rows/columns. r/l/u/d are geometric displacements; they cannot replace judgment of mapping direction; check explicit from/to, reverse arrow options, named nodes, and expanded macros. Injection must actually show the hook in the final PDF; surjection must show the double head. hook' only swaps the hook side; it does not reverse the arrow. \hookrightarrow in labels also does not change edge style. Check local options with \tikzcdset, every arrow/.style, and custom macro stacking order; subsequent rightarrow etc. settings may erase previous hook. Compilation success and hook appearing in source code do not replace endpoint verification.

Determine visible facts of nodes and arrows from the published original book image; original TeX, OCR, and mathematical semantics are only auxiliary evidence. Map physical pages of original book and re-typeset draft separately; do not use theorem/proof page numbers to directly infer the figure page. Look at the overall diagram structure first, then zoom in to check hooks, double heads, arrow endpoints, and cropping; also check isolated small samples and final book pages.

If image direct viewing is impossible, first confirm local image path and viewing tool, then retry once; path/tool errors are not equivalent to the model lacking visual capability. If still unable to visually check, follow the no-vision verification workflow of the accompanying skill: expand the grid by top-level &/\\ from source (preserving empty nodes and handling nested macros), check edge directions and effective styles; in the confirmed PDF crop region, examine text span and vector paths/glyphs, distinguishing three types of evidence: source topology, PDF geometry, and direct visual inspection. Failure to extract arrow head strokes from the PDF does not prove the original diagram lacks arrows. Record specific figures, edges, line numbers, original book pages/crop positions that cannot be confirmed; these details must be marked as pending; compilation success or OCR → cannot replace visual verification.

Key Pitfalls Quick Reference

Full table at references/pitfalls.md. Most frequent:

• PDF double-layer text trap: Original book contains HiddenHorzOCR hidden text layer; get_text() intermixes producing garbled text (Jf=ℋ, &i(=ℬ). Formulas must use get_pixmap rendering for visual confirmation.
• Shared counter for numbered equations: Numbered display formulas use gtmeq (increments counter); left-blank numbered ones use equation\notag (does not increment). Bare equation falls into the equation counter yielding chapter number.
• Claim numbering per chapter: Chapters 1/2 claim* without numbers; Chapters 3/4/9 claim with numbers.
• Do not add environment labels semantically: Many bare paragraphs in original book; wrapping in remark eats numbers and elevates all subsequent entries.
• Cross-references A-E (see references/crossref.md): \gtmtarget before \item misalignment, two styles of exercise blocks, regex \\S false hits, batch adding spaces secondary replacement + stale .aux false errors, zero chapter number / empty \ref{}.
• \pagestyle{empty} leakage (entire book loses headers and page numbers): Title page file sets \pagestyle{empty} but never restores, causing all continuation pages to have no headers and no page numbers. \thispagestyle only affects the first page; must explicitly restore \pagestyle{fancy} in each chapter/preliminary/bibliography/index header macro (see "Per-chapter Page Numbering Monograph Special Topics" below).

Per-chapter Page Numbering Monograph Special Topics (\chapcode Format)

Serre-type original books have independent page numbering per chapter with chapter prefixes (I-1…I-30, II-1…II-42, B-1…B-8, Index-1…Index-3); custom cls adds a whole class of pitfalls beyond the GTM shared counter route. Full version at references/chapcode-retypeset.md. Top five:

Symptom	Solution
Continuation pages lack headers and page numbers	\pagestyle{empty} leakage in front/titlepages.tex; explicitly restore \pagestyle{...} inside each head macro (\chapterhead/\fmhead/bib/index), not just \thispagestyle (only affects first page)
Page number format reset by \pagenumbering	Kernel \pagenumbering{roman} redefines \thepage; must separate "print format" from "counter", rebuild \thepage/\theHpage after each \pagenumbering (latter = printed page number, making anchor consistent with page number)
Preliminary folio jumps repeatedly / prints twice	\fmhead[folio#] only bumps when target folio > current value (only increments, never decrements), avoiding forward page jumps
Statement numbering does not match original book	Original book uses manual numbers (mixed numbered/unnumbered, often restarts): use "manual number parameter + hidden anchor counter", \begin{stmt}{LEMMA}{3}, empty second parameter for unnumbered
biblatex numbers scramble original book order	Custom sorting template + sortkey field per entry, locking refnumber to original book [1]–[88]
Printing by category loses exactly the last entry of each category	\addtocategory closing } on a new line → TeX reads newline as space, last key becomes xxx␠, biblatex records in .aux then cannot match entry. Fix: add % at end of last key line to eat newline. First check .aux for trailing spaces in \abx@aux@category{...} (defernumbers=true cannot fix)
TOC page numbers are dead links	hyperref does not generate page.<folio> targets for some pages; switch to \hyperref[<entry's own label>] (chapter chap:I/section sec:I.2/bibliography bib:main), \@ifundefined{r@…} fallback to \hyperlink{page.<folio>}

Four classes of page header conventions for per-chapter page numbering books (check per class against original book; full table in references/chapcode-retypeset.md): Body chapters (even page book title/odd page chapter short title), preliminary parts (section name replaces book title), main/supplementary bibliography, index (both sides only bare page numbers on outer edge).

Single-Volume Bare Numbering Monograph Special Topics (Samuel Type)

Single-volume, continuous Arabic page numbers, statements with keyword-based counters restarting bare numbers per section, formulas restart (1) per section, references [n], exercises per chapter. Full version at references/samuel-style-retypeset.md. Top nine:

Symptom	Solution
Statement number misalignment after named statement (Proposition 3 prints as 2)	Statement wrapper must unconditionally \refstepcounter; optional parameter only for printing the name
Page-by-page mismatch with scanned pages	Do not force per-page layout; only adjust \folio{n} at chapter/Supplement/Exercises/Bib/Index starts (only increments, never decrements)
Page headers must show section number range on page	\pagefirstsec + \afterpage to record first section of previous page; verso `folio
External reference chapter numbers incorrectly linked ([1], Algèbre, Chapter VI、Chapter V of [9])	Exclude by three rules based on [n] proximity to Chapter, of [n], \emph{Algèbre}; protect \divhead{Chapter X} first
Reference [n] point is not clickable	\item[\textbf{[n]}] \phantomsection\label{bib:n}; body text \hyperref[bib:n]{[n]} (display text locked)
Exercise reference chain broken	Inside \exitem, \refstepcounter{exno} + \label{exer:chapter.n}; \exchap{X} resets per chapter; Review Problems use R1/R2/R3 to avoid duplicate numbers with last chapter
List item (1)(2) no anchor	\item\label{prop:c.s.i}; body text still writes \hyperref[...]{(1)} because \ref from enumerate does not include parentheses
Bare reference audit full of false positives	Must block entire \hyperref[...]{...} (balanced curly braces); \[...] blocking requires re.S
.aux reports label missing / color source code does not match PDF	Parse \newlabel with balanced matching (entry format {{(1)}}); colors use 300 dpi sampling on Link rectangle to assert (0,0,178)

Build: when cls uses fontspec, pdflatex will always fail (fontspec requires XeTeX or LuaTeX); use lualatex/xelatex; latexmk residual fdb may still pull pdflatex, call directly if necessary.

Chinese Book (xeCJK) Special Topics

Chinese math book re-typesetting has a whole class of pitfalls not encountered with western books. Full version at references/cjk-retypeset.md. Top five:

Symptom	Solution
TikZ \draw/\fill/\path[domain=…] plot (…) parse failure	Switch to plot[smooth] coordinates{…}, coordinates computed in Python by scripts/gen_tikz_curve.py and injected
Missing character: … (U+6685) in font FandolSong	Fandol font family lacks rare characters; add \newCJKfontfamily\zmbhan{SimSun} fallback family in cls, body text 祖{\zmbhan 暅}
Pure CJK line 2–3pt Overfull, \hspace{0pt plus 3pt} ineffective, plus 1fil creates huge gap	Diagnose with \tracingparagraphs first; solution is local \begingroup\xeCJKsetup{CJKglue={\hskip 0pt plus 1pt}}…\endgroup for even loosening
Dense axis label overlap (2n / 2n+1 / 2n+2)	Follow original book's "offset sinking" or "oblique leader" layout methods; do not force a single line
Whole book contains \extref{6.3.2} plain text reference	Backfill to theorem~\ref{thm:6.3.2} after target chapter is output, and only edit the generator source then regenerate

Three "normal phenomena" easily mistaken for defects in Chinese books: xelatex fatal: memory exhausted (transient memory pressure, rerun succeeds), blank page at end of text (\makebibliography inner \cleardoublepage, matches original odd/even parity = expected format), OCR cross-page truncation missing problems (must check against facsimile pages problem by problem).

Cross-reference Completion (Seven Rounds Progressive)

Hard-coded references in body text (Theorem X.Y / (2.3) / Exercise N / Section N) → hyperlink \ref/\eqref complete strategy, see references/crossref.md: first standardize label names (kind:c.s.i), add sec:/exercise: labels, then convert chapter → intra-chapter parentheses → intra-chapter bare numbers progressively, verifying compilation each round.

Single-volume bare numbering books have three additional objects not covered by crossref.md: reference [n] (anchor on entry line, body text uses \hyperref[bib:n]{[n]}), exercise numbers per chapter (exer:c.n, Review Problems use R prefix), list item (1)(2) (\item\label{...}). Two more must remain plain text: external work's own Chapter numbers, original book typographical errors (e.g., "§4, Proposition 2" but the section only has Proposition 1—retain printed text, link to real target, and record in STATE.md). See references/samuel-style-retypeset.md.

Accompanying Audit Skills (Installed, Call as Needed)

• latex-eq-numbering-audit — Numbered formulas verified against original book item by item
• latex-display-layout-audit — Display formula layout (over-wrap / false alignment)
• latex-footnote-fidelity-audit — All footnotes present
• latex-ocr-math-defect-audit — OCR quietly corrupted mathematics
• commutative diagram audit skill — Old-style figure candidate inventory, per-edge direction/hook/double-head verification, style override check and no-vision evidence workflow
• latex-bookmark-anchor-audit — PDF bookmark anchors
• mathtranslation — xelatex/biber compilation and visual verification (references/build-verify.md)

Acceptance Criteria

See references/verification.md: 4 passes after clearing aux with exit=0; 0 errors / 0 duplicates / 0 undefined / 0 dead links; exercise numbers continuous per section; CRLF/BOM compliance; original book numbering inconsistencies kept as plain text and audited.

Three additional items for Chinese books (run scripts/verify_cjk_book.py main.pdf --log main.log --bib-page N once): PDF text layer ?? 0 instances, Missing character 0 instances, backfilled references resolve to numbers (not original text) in PDF.

One additional item for per-chapter page numbering books: run scripts/dump_page_heads.py main.pdf to dump top/bottom text strip per page, assert every continuation page has header and page number, every first page has no header and centered bare page number at bottom, and page number format (I-2 / B-5 / Index-3 / Roman numeral) is correct. TOC page number hyperlinks additionally use --check-toc-links to assert all page.* named targets resolve.

Two additional items for single-volume bare numbering books: scripts/audit_internal_links.py asserts all \ref/\eqref/\pageref/\hyperref targets are 0 missing (not just \ref); scripts/check_link_color.py main.pdf --expect 0,0,178 uses pixel sampling to assert link color (colorlinks in source is not evidence). Bare reference scanning uses scripts/audit_bare_xrefs.py, remaining items must be individually judged as "list label/external reference" and not actual references.

Key Scripts

• scripts/audit_text_refs.py: Scans .tex to list hard-coded references not yet converted to \ref (checklist for work start, does not modify files).
• scripts/rebuild_exercise_labels.py: Safely rebuilds exercise:c.s.i (default dry-run, correctly handles same-line \gtmtarget and manual exercise blocks).
• scripts/gen_tikz_curve.py: plot[domain=…] unavailable under xeCJK cls; computes parametric/cartesian/polar curves into plot[smooth] coordinates{…} literals (--wrap directly outputs complete \draw).
• scripts/verify_cjk_book.py: Full book final checker (?? residuals / bookmark count / backfilled reference landing / bibliography entries / missing characters); exits with 1 if any hard threshold fails; must run before delivery.
• scripts/dump_page_heads.py: Per-chapter page numbering book header/page number final checker. Dumps top/bottom text strip per page, reports running head and folio per page; --check-toc-links additionally asserts all page.* named targets in TOC resolve.
• scripts/audit_internal_links.py: Checks all \ref/\eqref/\pageref/\hyperref[...] against main.aux (\newlabel curly brace balanced; automatically skips work/bak/render/build backup directories); exits with 1 if any missing.
• scripts/audit_bare_xrefs.py: First blocks entire already-linked text, math, \item[...]/\pdfbookmark[...] optional params, then enumerates bare Theorem 3 / (4) / [3] / exercise 8, outputs STMT/PAREN/FORM/BIB/EXERC counts.
• scripts/check_link_color.py: Renders PDF, performs non-white pixel histogram for each Link rectangle, asserts link text color; --expect 0,0,178 corresponds to blue!70!black, prevents \hypersetup overwrite.

Resources

• references/discipline.md — Document class / counter quick reference, page number mapping, bibliography area typographic parameters
• references/pitfalls.md — All western book pitfalls (OCR / numbered formulas / Claim / environment labels / overfull / cross-references A–E)
• references/cjk-retypeset.md — Chinese book special topics (TikZ curves / missing character fallback / CJKglue loosening / label overlap / extref backfill / memory exhausted / biber bibliography / single output entry point)
• references/chapcode-retypeset.md — Per-chapter page numbering monograph special topics (\chapcode page number mechanism / \pagestyle{empty} leakage / four header conventions / manually numbered statements / biblatex sortkey locking / TOC page number hyperlinks)
• references/samuel-style-retypeset.md — Single-volume bare numbering monograph special topics (keyword-based/section-restart numbering, \folio only sets division start, header section number range, external reference chapter exclusion, bib:n and exer: anchors, list item references, .aux balanced parsing, link color pixel acceptance)
• references/crossref.md — Cross-reference seven-round completion strategy + exercise rebuild algorithm + plain text preservation list
• references/verification.md — Build commands, acceptance checklist, CRLF/BOM check
• scripts/audit_text_refs.py — Hard-coded reference scanner
• scripts/rebuild_exercise_labels.py — Exercise label safe rebuilder
• scripts/gen_tikz_curve.py — Parametric/cartesian/polar curves → plot[smooth] coordinates{…} snippets
• scripts/verify_cjk_book.py — Final book checker (PDF layer ?? / bookmarks / backfilled reference landing / bibliography entries / missing characters)
• scripts/dump_page_heads.py — Per-chapter page numbering book header/page number + TOC page number hyperlink final checker
• scripts/audit_internal_links.py — All internal link targets (\ref/\eqref/\pageref/\hyperref) verified against aux
• scripts/audit_bare_xrefs.py — Bare reference enumeration after blocking already-linked text (STMT/PAREN/FORM/BIB/EXERC)
• scripts/check_link_color.py — PDF Link rectangle pixel sampling, asserts link color (default 0,0,178)

Chinese Recalled Exam Paper Collection

For multiple schools, multiple years' exams, each paper with independent problem numbers and scores, when re-typesetting and reviewing simultaneously, read Recalled Exam Papers Special Topics. Must separately identify errors in draft vs. original problem; check headers/footers discarded by OCR for hidden problem numbers; do not declare first round screening as full problem proof before completing per-problem verification.

Bounded Parallelism and Page-Level OCR Sources

When a full book task requires reducing a single agent's context, refer to Bounded Sub-agents, OCR Page-Level Sources and Index Mapping. Covers file ownership, agent handoff, revision table dedup, math font and statement scope, PDF hash binding verification, and proven methods from Ahlfors draft for cross-page paragraph relocation, multi-volume partial page number restart, multiple figures per block, index semantic grouping final review, suspect resolution, cross-page footnote review, and editorial corrections recording.