Skip to content

docs(books): mark the live parameters, give the card its column back - #204

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

docs(books): mark the live parameters, give the card its column back#204
kfox merged 1 commit into
mainfrom
docs/reference-live-marks

Conversation

@kfox

@kfox kfox commented Aug 3, 2026

Copy link
Copy Markdown
Owner

PR 5 of 8 in the reference-guide review stack, on top of #200#203 (all merged, so this branches from main).

The introduction's Notation section promised that a parameter marked live could be moved during a show. Nothing was marked anywhere. Two different powers wear that word, so this marks them apart.

Appendices A and B: two marks

  • *Live-tunable* — a MIDI knob, a pad or the web console can move it mid-show; the mark names the target string that reaches it, so [color].dither_strength says mode.dither_strength.
    The join is an explicit alias map, not a bare-name match: [color].dither is mode.dither_method (a name match would miss it), and a name match would also mark [audio].dither, which is the 4-bit DAC's noise shaping and has nothing to do with the display pipeline. A test resolves both ends of every entry, and asserts [audio].dither stays unmarked.
  • *Menu-live*FieldDoc.apply == "live", the metadata the on-C64 menu builds its panel from (overlays/menu.py), which was in the introspect model and read but never printed. Four scene keys carry it. A scene's palette_mode carries both, which is exactly why the two are worded apart.

The Notation section now says which is which; the on-C64 menu section in Chapter 6 points at the *menu-live* mark, so "which knobs does the panel offer" has an answer that is a property of the key rather than a list to maintain.

Appendix E: parameters spelled as targets

source.speed, not speed — the string a cc_map entry has to carry. A line can now be copied into a mapping unchanged, and it matches Appendix F's target column verbatim. A test pins every source.*/effect.* printed in Appendix E to a row Appendix F has.

The performance card gets Declared by back

The data was already in the LiveTargetDoc.owners tuple the card builder read and discarded. Raw owners will not fit a 3.5in column (source.speed has fourteen), so it compresses: the sole owner where there is one, otherwise a count in the group's noun — `moire2`, 14 generators, 3 modes — and all when the count equals the registry. Without the column a performer has no way to know that a knob mapped to source.ring_freq is dead unless moire2 is the generator on screen; 01-controls.md gains two lines saying how to read it.

Verification

  • make lint typecheck clean; full suite 3307 tests OK.
  • make reference-appendices && git diff --exit-code docs/ clean; --check reports all 10 generated files fresh.
  • build_book.py --check passes for all three books; make books renders all three.
  • Read the artefacts: the marks set correctly in the reference PDF (the "Appendix F" in each mark links through), Appendix E's holder-prefixed names still fit the fixed identity column, and the card is still two pages — the first draft of the 01-controls.md paragraph pushed it to three, so it was cut to two lines.

No hardware needed.

The introduction's Notation section promised that a parameter marked *live*
could be moved during a show. Nothing was marked anywhere.

Two different things wear that word, so they are marked apart. Appendices A
and B now mark a field *live-tunable* and name the target a knob reaches it
by; the join is an explicit alias map rather than a bare-name match, because
[color].dither is mode.dither_method (a name match would miss it, and would
falsely mark [audio].dither, which is the DAC's noise shaping). A field whose
apply metadata is "live" — the metadata the on-C64 menu builds its panel from,
read but never printed until now — is marked *menu-live*. palette_mode carries
both, which is why the wording has to distinguish them. Notation says which is
which; the menu section points at the mark.

Appendix E prints a generator's or effect's parameters as the target string a
cc_map takes (source.speed, not speed), so a line can be copied into a mapping
unchanged and matches Appendix F verbatim.

The card's live-target page gets *Declared by* back. The data was already in
the LiveTargetDoc the builder read and discarded; raw owners will not fit a
3.5in column (source.speed has fourteen), so it compresses to the sole owner
or a count in the group's noun. Without it a performer has no way to know that
a knob on source.ring_freq is dead unless moire2 is on screen. Still two pages.
@kfox
kfox merged commit dd8890b into main Aug 3, 2026
14 checks passed
@kfox
kfox deleted the docs/reference-live-marks branch August 3, 2026 22:53
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