docs(reference): restructure - #202
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
Inside the Machine→ The Link and the Memory MapEverything Outside→ Inputs 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 Ncross-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 atdocs/architecture.mdfor why each module is built the way it is. Appending rather than inserting keeps chapters 1–6 numbered as they are, and satisfiestest_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
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.