Replace the \nopagebreak that glued a confined in-callout table to its
preceding prose with a conditional \needspace, so the breakable foldbox
can break right before a table that will not fit instead of shoving the
whole callout (and a large gap) onto the next page.
Margin figures rerouted through \marginpar are typeset in the output routine,
so one shipped out next to a crimson heading inherited that crimson color (the
original \marginnote typeset at the definition point, always black). Add
\normalcolor inside the \marginpar so margin captions are always black.
The confined-table shim emitted the caption via \captionof with no vertical
spacing, and the callout sets parskip=2pt, so the caption jammed against the
preceding body text above and the table rule below. Add 8pt above / 3pt below
so it reads like a normal table caption.
Two callout/listing layout refinements:
1. Regression fix: the in-callout longtable->tabular shim dropped the
\footnotesize that the original longtable got from
\AtBeginEnvironment{longtable}{\footnotesize}, so confined tables rendered
at the callout's larger font and over-wrapped (squished look, e.g. the
wildlife-monitoring table in nn_architectures Example). Add \footnotesize
to the confined tabular to match.
2. \needspace{6\baselineskip} before codelisting floats so a listing that
would only get a caption + 2-3 lines at a page bottom moves whole to the
next page instead of stubbing.
Refine the in-callout longtable->tabular shim to typeset the caption above
the table (matching body tables) instead of below. Pandoc emits \caption
before \toprule, so we defer \begin{tabular} to the first \toprule: the
caption is typeset first, then the table. The stored colspec is expanded via
\expandafter into tabular's preamble (array does not expand preamble macros).
Verified on full vol1: all in-callout tables render with captions above,
0 unresolved cross-references, no LaTeX warnings, margin oracle unchanged.
Quarto emits every pipe table as \longtable, which runs LaTeX's output
routine to page-break and therefore escapes any tcolorbox callout: the box
closes early and the table + trailing content render unframed (the 'broken
callout' symptom in tall worked-example callouts).
Inside our callouts (new flag \ifmfxInCallout, set by the fbx/fbxSimple
environments) \longtable is redefined to a plain non-breaking tabular
confined to the box. The shim matches Pandoc's fixed longtable shape:
redirects \caption/\label, swallows the caption-row \tabularnewline, gobbles
the repeated header and foot scaffolding (\endfirsthead..\endlastfoot), and
adds a closing rule. Captioned tables re-emit via \captionof{table} + the
saved label so cross-references still resolve. Body (non-callout) longtables
are untouched and still page-break normally.
Verified on full vol1: all 41 in-callout tables now render framed inside
their boxes (Lighthouse, Napkin Math 2.8, mixed-precision FP/BF16, ...);
0 unresolved cross-refs; margin oracle unchanged; no LaTeX warnings.
Known cosmetic: in-callout captions render below the table (vs above).
Quarto emits every .column-margin block as \marginnote, which the marginnote
package places at a fixed position UNMANAGED by marginfix (which only governs
\marginpar). A tall margin figure anchored low therefore runs straight off
the bottom past the footer. Rerouting \marginnote -> \marginpar hands it to
marginfix, which floats it up to stay on the page, exactly as it already does
for the 544 \sidenote marginpars.
Guarded with \ifinner so the reroute only applies in outer par mode: inside a
callout/box/float (where \marginpar is illegal and raises 'Not in outer par
mode') it falls back to the original \marginnote. \long defs handle the blank
lines in figure bodies.
vol1 effect: bottom-overflows 21 -> 4, top 12 -> 0, overlaps 0; the worst
offenders (Lighthouse 6.1, the Cliff figure, KWS) now float up intact.
Clean up the 13 algorithm blocks so they render well in the narrow text
column, in both PDF and HTML:
- Inline triangle comments (pdf-right-comment: false) so comments stay glued
to their statement instead of stranding at the right margin; set
html-comment-delimiter to the triangle so web matches print.
- Forbid mid-word hyphenation in the algorithmic environment via a guarded,
begin-document-deferred rule in header-includes.tex.
- Fix bare \quad / \ spacing macros that broke the HTML pseudocode.js parser
(reverse-mode AD, Adam, FlashAttention).
- Tighten the few comments/statements that wrapped, and move loop-purpose
comments onto the for-headers (tiled GEMM, PTQ, backprop, FlashAttention,
power-of-two routing).
- Drop manual \textbf from the 1F1B warm-up/drain phase labels.
- Gloss the mini-batch SGD prose handoff to describe the loop rather than only
announce the algorithm.
The shared titlepage extension (before-body.tex) calls \copyrightpage and
\dedicationpage unconditionally since the Vol I front-matter layout pass,
but both macros were \newcommand-ed only in tex/frontmatter-vol1.tex,
which Vol II does not include — its PDF build died with 'Undefined
control sequence \copyrightpage'. Mirror the \halftitle pattern:
\providecommand no-ops in header-includes.tex, \renewcommand in the
vol1 include.
Resolved conflict in ml_ops.qmd: kept PR #1826's relocation of the
'Optimal retraining interval' subsection to after the fraud-detection
example, and carried local dev's margin figure (vol1_ml_ops_margin_002.svg)
into the relocated subsection.
1. nn_architectures: remove \renewcommand{\arraystretch}{1.1} from
5 instances inside $$...$$ math blocks (display math). Pandoc
was macro-expanding \arraystretch (set to 1.25 by earlier chapter
ml_systems' raw-LaTeX \begingroup blocks), producing the broken
\renewcommand{1.25}{1.1} in the rendered LaTeX. The 6th
\renewcommand in this file (inside a {=latex} block at line 5042)
is safe and untouched.
2. header-includes.tex: add \providecommand{\tcbbreak}{} fallback.
PR #1789 (callout-audit) introduced \tcbbreak in 3 chapter QMDs
to force tcolorbox page-breaks, but the macro isn't defined by
the local foldbox extension. The fallback no-ops cleanly when
tcolorbox doesn't provide it.
Surfaced by CI Linux Vol I PDF build (run 26151749093, job
76922049346). Both errors reproduce locally and are fixed by these
two changes. Vol I PDF builds cleanly post-fix.
Half-title is the structural transition page between front-matter and
main matter. Standard academic-textbook convention (H&P, CLRS,
Tanenbaum, Bryant & O'Hallaron, Goodfellow et al., Murphy) is black
type on the half-title. Crimson on this page reads as a marketing
signal; the accent color belongs on chapter openings, part dividers,
caption labels, and drop caps where it identifies the book at a glance.
Dropping the \color{crimson} directive lets the half-title inherit body
black, matching the copyedit theme behavior.
Under LuaLaTeX + newpxtext + helvet, a bare \sffamily silently falls
back to Latin Modern Roman (not Helvetica as the package comment
claims), leaving chapter-opener mini-TOC entries, margin-figure stack
labels, rotated Data labels, Fleet Stack Part I-IV labels, and About
page stack captions in a visibly different typeface from the body.
Swap \sffamily -> \rmfamily in every TikZ font declaration and inline
caption for the chapter-opener/stack macros so all margin content
renders in the book's Palatino body font. Each swap carries a comment
explaining the fallback bug to prevent regressions.
The chapter mini-TOC on each chapter opener page now renders in the
volume accent (Crimson for Vol1, ETHZ Blue for Vol2) instead of the
global toccolor (black) — it's a decorative complement to the chapter
number/title, not a long readability list.
Also wraps the mini-TOC's \localtableofcontents in a \hypersetup group
that pins linkcolor to accentcolor; etoc bypasses the global
\contentsline wrapper, so without this override hyperref's broken link
colour fallback (#800000 maroon) was bleeding through onto the entry
text.
Reserve ETHZ blue accent for chapter headings, division pages, and body
cross-references. Black TOC entries match Vol1 and the standard scholarly
convention for readability.
The initial half-title implementation hooked \halftitle into the
redefined \frontmatter macro in tex/header-includes.tex, which meant
the half-title printed at the very start of the front matter, BEFORE
the Quarto titlepage extension's coverpage block. The resulting PDF
sequence was half-title -> cover art -> title page, which is backwards
from the standard academic book sequence.
The Quarto titlepage extension is local to this repo at
_extensions/mlsysbook-ext/titlepage/before-body.tex. Rather than
fighting the upstream extension, edit the local copy to add a
\halftitle injection point at the seam between the coverpage block
and the titlepage block. This produces the standard sequence:
page 1 cover art (dust-jacket style, rendered by Quarto coverpage)
page 2 half-title (rendered by \halftitle defined per volume)
page 3 blank verso
page 4 title page (rendered by Quarto titlepage extension)
Revert the \frontmatter redefinition in tex/header-includes.tex to its
original form (no longer calls \halftitle — the extension template
calls it directly). Keep the \providecommand{\halftitle}{} default so
the extension's \halftitle call is a no-op when no per-volume half-
title file is loaded.
Update the header comments in tex/halftitle-vol1.tex and
tex/halftitle-vol2.tex to describe the new injection point accurately.
Verified by smoke build of vol1 and vol2 dedication-only PDFs, visual
inspection of pages 1-4 in each:
- Vol1: Harvard crimson half-title, sequence cover -> half-title
-> blank -> title, dedication still centered via TikZ
- Vol2: ETH Zurich blue half-title, same sequence, dedication still
centered via TikZ
Four front-matter rendering bugs fixed in one batch because they all
touch the same set of preamble/include files and share a review surface.
1. Dedication centering (vol1 + vol2): the existing pattern wrapped the
italic block in two \vspace*{\fill} stretches, but Quarto auto-emits
\chapter*{Dedication} at the top of the file (inferred from the
filename), and that heading consumed vertical space the \vfills
could not compensate for. The italic text was landing at ~57% from
the top instead of true page midline. Fixed by anchoring the italic
block to (current page.center) via a TikZ overlay, which is
independent of any heading layout above it.
2. Half-title pages (vol1 + vol2): vol1 had a 2-line stub with a
"currently empty - half-title page disabled" comment; vol2 had a
real half-title but with stale "Advanced Machine Learning Systems"
text from an earlier draft. Implemented a clean per-volume hook by
adding \providecommand{\halftitle}{} in header-includes.tex (default
empty) and modifying the \frontmatter redefinition to call \halftitle
after \originalfrontmatter. New per-volume tex/halftitle-volX.tex
files \renewcommand the macro with the right title text. This fires
from inside the redefined \frontmatter — which the Quarto titlepage
extension calls via \begin{frontmatter} — so the half-title prints
before the title page block. Vol2 production was also incorrectly
loading tex/before-body-includes.tex (the vol1 stub) instead of
tex/before-body-includes-vol2.tex; fixed.
3. Copyedit color cascade (vol1 + vol2): the copyedit PDFs going to
the MIT Press copy editor were rendering chapter headings, TOC
entries, and links in Harvard crimson (vol1) or ETH Zurich blue
(vol2). Added new tex/theme-colors-volX-copyedit.tex files that
define accentcolor as #000000; loaded via include-in-header BEFORE
header-includes.tex so the existing \providecolor{accentcolor} is a
no-op and the existing \colorlet{crimson}{accentcolor} alias chain
cascades black through every \color{crimson} site (chapter
headings, sidenotes, page headers, TikZ overlays, half-title).
Hyperref's linkcolor needed a separate fix because Quarto's Pandoc
template emits its own \hypersetup{linkcolor=Maroon,...} in the
preamble AFTER include-in-header runs; wrapping the override in
\AtBeginDocument{} defers it until after the template's hypersetup,
guaranteeing black TOC/Appendices/Index links throughout.
4. Removed leftover \setcounter{chapter}{2} debug from
header-includes.tex (committed in 41724c362, "Update TikZ figures
in vol1/ch3", on 2026-04-02). This line had been forcing the first
numbered chapter in BOTH volumes to render as Chapter 3 since that
commit. Removing it restores Introduction as Chapter 1.
Verified by smoke-build of vol1 dedication-only PDF, vol2 dedication-
only PDF, and vol2 trimmed copyedit PDF (frontmatter + introduction).
Half-title text, dedication centering, color cascade, and chapter
numbering all confirmed visually.
Removes hardcoded \setcounter{chapter}{7} from header-includes.tex and
adds \setcounter{chapter}{0} to Vol1 YAML configs, matching the Vol2
pattern. Prevents recurring merge conflicts from single-chapter renders.
Zeljko Hrcek
Zeljko HrcekandGitHub
Vijay Janapa Reddi