Step-annotation columns overflow the PDF text block, clipping justifications off the page

[d-morrison]

Important

This issue's original measurements were wrong and have been replaced.
The corrected figures and instrument are below; the history is in the
comments.

CLAUDE.md asks every derivation step to carry a trailing justification.
When that justification sits in a third && column of an aligned block, it
adds its own width to the block, and wide derivations then overflow the text
block in the PDF profiles --- so the justification is clipped off the right
edge of the page, which is exactly the content the rule exists to supply.
HTML is unaffected, so the pre-commit checklist cannot see it.

Measurement

Against the book's own class and geometry (scrbook, twoside=off,
top=15mm bottom=20mm), with the text width read from the run via
\showthe\textwidth rather than assumed:

arm	text width	LaTeX errors	overfull	worst
origin/main (873b4a09)	418.25pt	0	1	47.2pt
#1138 before its fix	418.25pt	0	11	139.7pt
#1138 after its fix	418.25pt	0	0	---

So main's existing exposure is one box at 47pt --- small, but the count
grows with every chapter that gains step annotations.

Two instrument traps, both of which produced wrong numbers here

1. latex-macros is a submodule, so git show <ref>:latex-macros/macros.qmd
   returns empty. A harness that reads the macros that way compiles the
   comparison arm with no macros at all. That is what produced this issue's
   original "8 overfull, worst 153.4pt" for main, and the "~345pt text
   width" was assumed rather than measured. Read the macros from disk; the
   submodule pin is unchanged by Improve narrative flow and math derivations in count regression chapter #1138.
2. quarto pandoc does not process {{< include >}}, and injecting
   macros.qmd into a hand-assembled .tex after \begin{document} skips
   Pandoc's latex_macros expansion entirely. Either mistake makes macros
   such as \sb reach LaTeX unexpanded, which changes every width and
   invents errors. Concatenate macros.qmd's content into the document, or
   use quarto render --to latex. See
   #1152.

What does not work, and why

Shortening the annotation text. An aligned block's width is the sum of its
column maxima, so a third column holding the justification adds its width
to every row no matter how the rows are arranged; trimming words moves the
maximum slightly and nothing else. This was tried first in #1138 and took the
worst case only from 390.6pt to 139.7pt.

What works

Move the annotation onto its own row in column 2, so the width becomes the
maximum of equation and annotation rather than their sum:

&= \pi \cdot 1 + (1-\pi) e^{-\mu_0} \\
&\quad \text{(substituting the two conditional PMFs)} \\

Applied to all 40 annotated steps in the count-regression chapter, this gives
zero overfull boxes.

The open decision

Whether the rest of the book should adopt the column-2 style. It changes the
look of every annotated derivation, so it is a decision rather than a
cleanup, and #1138 deliberately confines it to its own chapter. A CI check
counting overfull boxes per chapter would keep the problem from growing
silently either way; it pairs naturally with #1152.

Filed by Claude Code (AI agent).

[d-morrison]

Update from #1138, which now has a working fix and a corrected measurement.

The measurement in the original report was wrong. latex-macros is a submodule, so git show origin/main:latex-macros/macros.qmd returns empty --- a harness that reads the macros that way compiles the main arm with no macros at all. Re-measured with the macros read from disk for both arms, and the text width read from the run rather than assumed:

revision	text width	errors	overfull	worst
origin/main	418.25pt	0	1	47.2pt
#1138 before the fix	418.25pt	0	11	139.7pt
#1138 after the fix	418.25pt	0	0	---

So main's existing problem is one box at 47pt, not eight at 153pt.

Shortening annotations cannot fix this, which is worth recording because it is the obvious first thing to try and it wastes a round. An aligned block's width is the sum of its column maxima, so a third column holding the justification adds its own width to every row regardless of how rows are arranged. Trimming the words moves the maximum a little and nothing else.

What works: move the annotation onto its own row in column 2 --

&= \pi \cdot 1 + (1-\pi) e^{-\mu_0} \\
&\quad \text{(substituting the two conditional PMFs)} \\

-- so the width becomes the maximum of equation and annotation instead of their sum. Applied to all 40 annotated steps in the count-regression chapter, this takes it to zero overfull boxes.

That leaves the question this issue is really about: whether the rest of the book should follow. It is a presentation change to every annotated derivation, so it is a decision rather than a cleanup, and #1138 deliberately confines it to its own chapter.

Posted by Claude Code (AI agent) --- not written by a human.

[d-morrison]

Replaced the body: the original headline figures ("~345pt text width", "8 overfull hboxes, worst 153.4pt" on main) were produced by a harness that read the macros with git show <ref>:latex-macros/macros.qmd, which returns empty for a submodule path --- so that arm compiled with no macros. The corrected figure for main is 1 box at 47.2pt.

The old reproduction recipe was also the bad instrument: it used quarto pandoc, which does not process {{< include >}}, in the same breath as warning "render through Quarto, never around it". Both traps are now written up explicitly, since each has produced a wrong conclusion in this PR.

Posted by Claude Code (AI agent) --- not written by a human.