docs: check that the docs' headline figures match their committed data

Nothing had ever verified that a number written in prose matches the
reference data file committed beside it. The figure is written once from
a run; the prose is edited around it afterwards and the data file is
regenerated independently, so drift is silent.

All 19 headline figures across four censuses -- the eff-bit census, the
plateau census, the top-level rotation census and the eff-bit alpha test
-- currently agree with their data files.

The checker had to be numeric, and the first attempt is the reason it is
a script rather than a grep: comparing strings reported almost every
figure as a mismatch, because the data files write 14709 where the docs
write "14 709" with a thin space, and the docs round 33.66 to 33.7. A
consistency check that fails on formatting trains you to ignore it, so
the tolerance is explicit: exact against the data, within 0.05 against
the doc to allow rounding.

Also ran the full disc-gated workspace suite (build-reborn test, which
wires SYLPHEED_DISC -- without it the disc tests self-skip and green
means almost nothing), covering this session's three decoder changes:
rotation_deg on Keyframe, the scale-0 fix in blit/fill_quad, and the
flags field on T8adImage. 122 passed / 0 failed across the four suites
that had completed; the long disc-gated integration tests
(records_roundtrip_disc, first_header_word_is_record0_hash) were still
running and are not counted here.
This commit is contained in:
Sylpheed RE agent
2026-08-29 03:42:13 +00:00
parent 714a26769d
commit 6d9214fd07
2 changed files with 57 additions and 0 deletions

View File

@@ -712,3 +712,12 @@ agent's loop prompt, i.e. nowhere durable. See [`README.md`](README.md) for the
call, but only if the negative space is written down — additive blend, name,
lifetime, premultiplied alpha — so the next attempt starts where this one ended
rather than at the beginning.
* **Nothing was checking that a doc's figures match its committed data.** A
number is written once from a run and then lives in prose that gets edited
around it; the data file beside it is regenerated independently. All 19
headline figures across four censuses do currently agree
(`tools/re-capture/doc_figure_check.py`), which is worth knowing rather than
assuming — but the checker had to be written **numerically**, because the first
version grepped for the doc's formatting (`14 709` with a thin space, `33.7`
rounded from `33.66`) and reported almost every figure as a mismatch. A
consistency check that fails on formatting will train you to ignore it.