mirror of
https://github.com/harvard-edge/cs249r_book.git
synced 2026-11-09 10:39:41 -06:00
Vijay Janapa Reddi
38439425a6
The repository carried the book twice. publishing/quarto/contents/vol{1..4}/
was what every build and every check read; books/vol{1..4}/ was a second
tracked copy that fed nothing and had drifted badly, holding 3 vol3 chapters
against 30 in the live tree. A `book` symlink pointed at publishing/, so
book/quarto/ and publishing/quarto/ were one directory under two names, next
to a books/ that was a third thing. Editorial work kept landing in the copy
nothing rendered.
books/ is now the Quarto project root and the only place book sources live:
books/vol1..vol4 one directory per volume
books/shared/ frontmatter, backmatter, _partials, assets, tex,
filters, scripts, audits, publish, calc
books/config/ the per-volume quarto configs
books/_extensions/ Quarto needs these at the project root
books/index-vol{1..4}.qmd, references*.bib, _variables.yml, 404.qmd
books/_build/ render output, gitignored and disposable
The toolchain stays in publishing/ and is now unambiguous, since it no longer
contains any of the book. The `book` symlink is gone and the CLI is reached as
./binder from the repository root; publishing/binder resolves through the
symlink so invoking it from either place works.
Config paths are relative to the project root, so a chapter entry goes from
contents/vol1/introduction/introduction.qmd to vol1/introduction/introduction.qmd,
and shared material picks up a shared/ prefix. 5,204 path references were
rewritten across 401 files, plus 127 segment-built paths in Python that string
matching could not see, plus 795 ./book/binder references.
Verified rather than assumed: a single-chapter HTML render produces output
equivalent to the same build on dev, 432,901 bytes against 433,158, the same
18 images, zero unresolved cross-references on both. Scoped checks return
identical findings on both trees.
One behaviour genuinely changes. While the sources sat under contents/, the
checks resolved their default scan root to the Quarto project directory rather
than the content directory, so a bare `./binder check tables` matched no files
and always reported success. Now that the project root and the content root
are the same directory the default works, and it immediately surfaces 31
pre-existing findings in vol3 and vol4 that were always present and never
reported. Those are content issues to fix separately, not regressions from
this move.
docs/REPO_LAYOUT.md describes the result. docs/BOOKS_MIRROR_RETIREMENT.md
records what the retired mirror held, which commits landed only there, and how
to recover any of it from history.
1.7 KiB
1.7 KiB
MIT Press Assets
Scripts and generated files for MIT Press submission.
Figure List Generator
Extracts figure metadata from QMD source files and combines it with the figure-number and page manifest produced by the PDF build:
# From the quarto/ directory, before rendering:
python3 scripts/mit_press/generate_figure_list.py --clear
# Post-render runs automatically for the production PDF. To rerun it:
python3 scripts/mit_press/generate_figure_list.py
The generator writes FIGURE_LIST.txt into the active PDF output directory.
Run it only after a fresh render so the LaTeX manifest, figure numbers, and
page numbers correspond to the current manuscript.
Output Fields
| Field | Description |
|---|---|
| Figure Number | Chapter.Figure format (e.g., 1.1, 2.3) |
| Label | Source reference (e.g., fig-ai-timeline) |
| Caption | Full caption text |
| Alt-Text | Accessibility description |
Tracked submission logs
PERMISSIONS_FIGURES_VOL1.csvrecords source and permission status for every Volume I figure. It is source-based and can be maintained without a render.- The generated
FIGURE_LIST.txtis a build artifact and is intentionally not tracked in this directory.
Validate that the permissions log covers the current QMD figure inventory:
python3 scripts/mit_press/check_permissions_log.py
Before final submission, require every permission scope to be resolved:
python3 scripts/mit_press/check_permissions_log.py --require-resolved