CI workflows repeated a ~20-line tlmgr install block inline. Consolidate
to two requirements files that work locally and in CI:
pdf/apt-requirements.txt - system packages (librsvg2-bin)
pdf/tex-requirements.txt - 24 TeX packages
New Makefile target 'make install-deps' reads both files, calling
apt-get + tlmgr. Skips sections when the tool is not on PATH (no-op
on macOS, effective on Ubuntu CI).
CI workflows simplified to 'make install-deps && make pdf', matching
local dev exactly. Adding a dependency now means editing one file,
not two.
Quarto's post-render cleanup leaves *_files/ auxiliary dirs around
when chapter sources live outside the project root (our case:
pdf/_quarto.yml references ../modules/*.qmd). These accumulated
at both pdf/modules/*_files and pdf/getting-started_files etc.
Add a rm -rf *_files to the Quarto project's root so all stale
auxiliary dirs get cleaned with one command.
The user was confused about which PDF was 'official' when Quarto's
post-render cleanup error occasionally left a stray copy at the
top-level pdf/ dir. This tightens the Makefile so every build ends
with exactly ONE TinyTorch-Guide.pdf:
- pre-build: rm -f pdf/TinyTorch-Guide.pdf (stray from past runs)
- post-build: if top-level copy exists after _build/ produced one,
rm it — _build/ is authoritative
- end banner: prominently prints
FINAL PDF (the only shippable file):
pdf/_build/TinyTorch-Guide.pdf (X.XM)
in a box — impossible to miss
make clean also upgraded to remove pdf/.quarto/ cache and any
index.tex/log/aux intermediates, so a full reset leaves zero PDFs
anywhere in the repo. .gitignore already covers all these; the
Makefile changes only affect local filesystem state.
The mid-recipe '# ...' lines were being consumed as part of the joined
shell command (via backslash-newline continuation) and masked the
self-heal mv. Move the explanatory comment above the recipe so Make
recipe body is pure shell.
- Running headers: verso shows 'Chapter N · Title' on outer-left, recto
shows 'N.M · Section' on outer-right, small caps navy. Wordmark
centered. Page numbers on outer-edge in footer. Follows H&P / CLRS /
Swift Book convention.
- Book-style paragraph typography: parskip=0pt plus 0.5pt, parindent=1.2em.
First-line indent instead of web-style paragraph gaps.
- List of Figures + List of Tables: lof: true / lot: true in YAML front
matter. One page each, makes 350-page guide's figures navigable.
- Callout title convention documented in preamble comment. Six types
keyed off emoji prefix (Check Your Understanding ✅, Systems
Implication ⚡, Historical Context 📚, Exercise 🎯, Pitfall ⚠️,
Checkpoint 🚦). Reuses Quarto's 5 shipped classes; no new LaTeX.
- Makefile self-heal: when Quarto post-render cleanup errors and
leaves the PDF at top-level pdf/ instead of pdf/_build/, detect
and move it to the canonical location.
The Makefile was copying pdf/_build/TinyTorch-Guide.pdf up to
pdf/TinyTorch-Guide.pdf as "local-dev convenience" so `open
pdf/TinyTorch-Guide.pdf` would work. This created two copies of the
same artifact at different paths — confusing when the user asked which
was authoritative.
Simplify to a single source of truth at pdf/_build/TinyTorch-Guide.pdf:
- Makefile: remove the `cp "$(PDF_BUILD)" "$(PDF_OUT)"` step. PDF_OUT
now IS the _build path. Help text and distclean target updated
accordingly.
- tools/measure-pdf-images.py: default PDF path updated from
pdf/TinyTorch-Guide.pdf to pdf/_build/TinyTorch-Guide.pdf.
CI workflows (tinytorch-build-pdfs.yml and tinytorch-update-pdfs.yml)
already point at pdf/_build/TinyTorch-Guide.pdf from the earlier
consistency pass (commit 7d9eab7ed era), so they're unaffected.
Local dev uses `open pdf/_build/TinyTorch-Guide.pdf` or an `open`
wrapper — one extra path segment, zero ambiguity about which file is
the real artifact.
Makefile:
- pdf/_quarto.yml writes to pdf/_build/ (via output-dir). The publish
workflow (tinytorch-publish-live.yml) expects the artifact at the
stable path pdf/TinyTorch-Guide.pdf. Copy _build/TinyTorch-Guide.pdf
up to pdf/ after render so publish finds it.
getting-started.qmd:
- Replace the mermaid "Your TinyTorch Journey" graph with a figure div
embedding 00_journey-diag-1.svg. Mermaid renders inconsistently in
the PDF pipeline; a hand-authored SVG gives identical output across
HTML and PDF and matches the book's figure grammar.
Diagrams:
- 00_journey-diag-1.svg: new 5-stage journey diagram (Install → Setup
→ Start → Complete → Milestone) with feedback loop back to Start.
- 00_big-picture-module-flow.svg: three-panel overview (Foundation,
Architecture, Optimization) leading to Capstone. Staged for a
future big-picture chapter; not yet referenced.
Style-guide conformance for both SVGs is a follow-up pass.
Brings the TinyTorch lab guide's Quarto project in line with
book/quarto/, the only other in-tree Quarto publication that builds
both web and PDF outputs from a single source. The previous name had
three redundancies:
- already under tinytorch/, so "site-" prefix wasn't disambiguating
- also produces the PDF lab guide, so "site-" was misleading
- the top-level site/ dir made "site-quarto" read as "the site's
quarto config" rather than "the tinytorch site, in quarto"
After this rename the convention is straightforward:
book/quarto/ -> the textbook (web + PDF)
tinytorch/quarto/ -> the TinyTorch lab guide (web + PDF)
mlsysim/docs/ -> mlsysim API reference (kept as docs/, since it
really is API reference, not a publication)
Touches 7 GitHub workflows, both .gitignore files, the rename target's
own self-references (Makefile, _quarto.yml configs, STYLE.md,
measure-pdf-images.py), and 6 copies of subscribe-modal.js plus a few
shared scripts/configs whose comments documented the old path.
Verified: rebuilt pdf/TinyTorch-Guide.pdf (2.1M) cleanly from the new
location with 'make pdf' from tinytorch/quarto/.
