docs(books): mark the live parameters, give the card its column back - #204
Merged
Conversation
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.
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 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_strengthsaysmode.dither_strength.The join is an explicit alias map, not a bare-name match:
[color].ditherismode.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].ditherstays 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'spalette_modecarries 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, notspeed— the string acc_mapentry has to carry. A line can now be copied into a mapping unchanged, and it matches Appendix F'stargetcolumn verbatim. A test pins everysource.*/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.ownerstuple the card builder read and discarded. Raw owners will not fit a 3.5in column (source.speedhas fourteen), so it compresses: the sole owner where there is one, otherwise a count in the group's noun —`moire2`,14 generators,3 modes— andallwhen the count equals the registry. Without the column a performer has no way to know that a knob mapped tosource.ring_freqis dead unlessmoire2is the generator on screen;01-controls.mdgains two lines saying how to read it.Verification
make lint typecheckclean; full suite3307 tests OK.make reference-appendices && git diff --exit-code docs/clean;--checkreports all 10 generated files fresh.build_book.py --checkpasses for all three books;make booksrenders all three.01-controls.mdparagraph pushed it to three, so it was cut to two lines.No hardware needed.