docs(reference): the generated index

CHANGELOG.md

@@ -106,6 +106,16 @@ the version and stamps it with the date.
   instead of a page with a big numeral on it. The anchor is GitHub's own, because
   the Markdown is the book: the same link resolves on github.com and in the PDF.
   One that resolves nowhere fails the build and names the nearest ones it knows.
+- **The Programmer's Reference Guide has an index**, and it is generated like
+  its appendices. Every name the program can utter goes in — configuration
+  sections and keys, command-line flags, scene types, overlays, display modes,
+  generators, effects and live-tune targets — against the sections of the book
+  that discuss it, the section written about the name first and the table it
+  appears in last. Section titles are entries too, so "Companding" and "The
+  Audio Slot" can be looked up by a reader who does not yet know which key they
+  mean. A key is listed bare, and again qualified with its section where two
+  sections share the name, which is the rule the book's own Notation section
+  states. Every locator is a link that works on github.com and in the PDF alike.
 - **The books' symbols no longer depend on the machine that built them.** Jost
   has no ✓ and no →, and Typst was filling them from whatever was installed — so
   the compatibility matrix was set in a heavy upright check locally and a thin

CLAUDE.md

@@ -84,8 +84,9 @@ directory of numbered Markdown plus a `book.toml` that
 [scripts/build_book.py](scripts/build_book.py) renders through the one shared
 [template](docs/shared/template.typ): [docs/guide/](docs/guide/README.md) (the
 User's Guide, read in order), [docs/reference/](docs/reference/README.md) (the
-Programmer's Reference Guide — seven chapters over ten appendices, of which A–I
-are generated by [scripts/gen_reference_appendices.py](scripts/gen_reference_appendices.py)
+Programmer's Reference Guide — seven chapters over ten appendices and an index,
+of which appendices A–I and the whole index are generated by
+[scripts/gen_reference_appendices.py](scripts/gen_reference_appendices.py)
 and regenerated with `make reference-appendices`), and
 [docs/card/](docs/card/README.md) (the two-page Performance Card, whose live-target
 table comes from that same pass). `make books` renders all three; each book's

Makefile

@@ -88,7 +88,7 @@ help:
 	@echo "  card       render docs/card/*.md to the Performance Card PDF (needs typst)"
 	@echo "  books      render every book"
 	@echo "  guide-figures  redraw the guide's placeholder figures"
-	@echo "  reference-appendices  regenerate the reference guide's appendices A-I"
+	@echo "  reference-appendices  regenerate the reference guide's appendices A-I + index"
 	@echo "  check      lint + typecheck + test"
 	@echo "  clean      remove build artifacts"
 
@@ -149,14 +149,16 @@ card: $(SYNC)
 
 books: guide reference card
 
-# Rewrite the Programmer's Reference Guide's generated appendices (A-I) and the
-# performance card's live-target table from the config metadata. Unlike the
-# books themselves this needs the project env, since it imports c64cast — which
-# is exactly why it is a separate script from build_book.py, and why its output
-# is committed: the release renders the PDFs with `uv run --no-project`.
+# Rewrite the Programmer's Reference Guide's generated appendices (A-I), its
+# index and the performance card's live-target table from the config metadata.
+# Unlike the books themselves this needs the project env, since it imports
+# c64cast — which is exactly why it is a separate script from build_book.py,
+# and why its output is committed: the release renders the PDFs with
+# `uv run --no-project`.
 # tests/test_reference_appendices.py fails if the committed files drift from
 # this output, so run it after changing any config field, overlay, generator,
-# effect, CLI flag, example config or install extra.
+# effect, CLI flag, example config or install extra — and after renaming a
+# section, which moves an anchor the index links at.
 reference-appendices: $(SYNC)
 	$(PY) scripts/gen_reference_appendices.py
 

docs/reference/01-introduction.md

@@ -35,6 +35,13 @@ installs.
 Appendix J is a glossary, which is hand-written because a machine has no
 opinion about which words a reader will not know.
 
+The index at the back is generated too, and from both halves at once: every
+name the program can utter, against the sections of this book that discuss it.
+A configuration key is listed bare, and again qualified with its section where
+two sections share the name. A section title in ordinary words — "Companding",
+"The Audio Slot" — is an entry in its own right, so the concept can be looked
+up by somebody who does not yet know what it is called.
+
 ## What Is Not
 
 Three things live outside this book on purpose.