Skip to content

docs(reference): restructure - #202

Merged
kfox merged 1 commit into
mainfrom
docs/reference-restructure
Aug 3, 2026
Merged

docs(reference): restructure#202
kfox merged 1 commit into
mainfrom
docs/reference-restructure

Conversation

@kfox

@kfox kfox commented Aug 3, 2026

Copy link
Copy Markdown
Owner

PR 3 of 8 in the reference-guide review follow-through. Prose and structure only — no code, no hardware.

What changes

Two chapter titles that did not say what was in them.

  • Chapter 5 Inside the MachineThe Link and the Memory Map
  • Chapter 6 Everything OutsideInputs and Outputs — which is what its filename has said all along, and what a reader scanning the contents for MIDI, WLED or recording can actually find.

Neither number moves, so every Chapter N cross-reference in either direction still lands where it did.

Chapter 5 was two books. A memory map and a write budget, then a Python extension API — contributor material sitting inside a user-facing volume, after a frame budget. "Writing Your Own Scene" and "Writing Your Own Overlay or Generator" move to a new Chapter 7, Extending c64cast (08-extending.md), with a short opener saying who it is for and pointing at docs/architecture.md for why each module is built the way it is. Appending rather than inserting keeps chapters 1–6 numbered as they are, and satisfies test_book_build's "digit chapter numbers are exactly 1..N" rule with no renumbering.

The book kept a promise it was breaking. The introduction says a subject belonging to two chapters is written once and referred to from the other; ASID and the MIDI scene were written twice, near-verbatim. Chapter 2's catalogue entries now carry what a configuration needs — the keys, the extra, the ports — and defer the mechanism to Chapter 4. Two facts that only the shrunk copies carried (multitimbral's last-note priority; where to find the ASID hosts) were moved rather than dropped.

Counts updated: 01-introduction.md, docs/reference/README.md, CLAUDE.md, and the changelog's own description of the book (which has not shipped yet, so its "Six chapters" entry is corrected in place rather than amended).

Verification

make lint                                                  # clean
uv run python -m unittest discover -s tests -q             # 3297 tests, OK
make reference-appendices && git diff --exit-code docs/    # no generated drift
make books                                                 # all three PDFs render

Read the artefact as well: the contents page lists both new titles and the new chapter, and the Chapter 7 opener page renders with its three section bullets in white on the accent page.

Two chapter titles that did not say what was in them, and one chapter that
was two books.

Chapter 5 becomes "The Link and the Memory Map" and chapter 6 becomes
"Inputs and Outputs" — which is what its filename has said all along, and
what a reader scanning the contents for MIDI or WLED or recording can find.
Neither number moves, so no cross-reference in either direction moves.

Chapter 5 also stops being half a contributor's manual. Writing a scene, an
overlay, a generator or an effect leaves it for a new chapter 7, "Extending
c64cast", appended rather than inserted so chapters 1 to 6 keep their
numbers. Its opener says plainly who it is for and points at
docs/architecture.md for the reasoning behind each module.

The introduction promises that a subject belonging to two chapters is
written once and referred to from the other; ASID and the MIDI scene were
written twice, near-verbatim. Chapter 2's catalogue entries now carry what a
configuration needs — the keys, the extra, the ports — and defer the
mechanism to chapter 4.

make books, make reference-appendices (no drift), full suite.
@kfox
kfox merged commit dd95ce6 into main Aug 3, 2026
18 checks passed
@kfox
kfox deleted the docs/reference-restructure branch August 3, 2026 19:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant