The book and the HTML hold every topic, and #doc links to its chapter or section

chapters now names guide, cheatsheet, scripting, reference, themes and
building. #doc takes the chapter ids, keeps the old ones mapped onto
them (tags and fs to the guide and the reference, config, keys and
detached to their guide sections), and links in the book and the HTML,
where a doc-links state says every chapter is there; on the A4 sheet it
names the chapter and section. The reference points at the scripting
and building chapters by #doc instead of in words, and the guide heading
for pardes FILE and --wait keeps its two dashes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

1 files changed, 10 insertions, 5 deletions

diff --git a/docs/typ/README b/docs/typ/README
index f1eff604..509cec39 100644
--- a/docs/typ/README
+++ b/docs/typ/README
@@ -15,10 +15,12 @@ docs/typ: the Typst documentation corpus
                      Wrappers hold layout only, never facts.
 
 Chapters: `chapters` in style.typ lists them in reading order (guide,
-cheatsheet, scripting, reference, building), each with its content file,
+cheatsheet, scripting, reference, themes, building), each with its content file,
 or none while it is not written (the outputs show a placeholder). To add
 a topic, write docs/typ/<id>.typ and set its `file`. Wrappers include it
-with heading offset 1, so its = headings sit under the chapter title.
+with heading offset 1, so its = headings sit under the chapter title,
+which is labelled ch-<id>. Labels on headings must be unique across all
+the topics, since the book and the HTML hold them all.
 
 Build (from the repo root):
 
@@ -58,9 +60,12 @@ new function instead.
   file(p)          a 9P path.                 #file("pane/N/addr")
   cmd(c)           a shell line, as a block.  #cmd("echo Save > $m/pane/$n/ctl")
   doc(id, section:)
-                   a pointer to a topic, by id from `topics` in style.typ
-                   (tags fs config themes keys detached).
-                   #doc("fs", section: "look-and-exec")
+                   a pointer to a chapter, or a section of it by the label
+                   on its heading. Ids: guide cheatsheet scripting
+                   reference themes building (and the older tags fs
+                   config keys detached, mapped in `topics`). A link in
+                   the book and the HTML; on the A4 sheet, its name.
+                   #doc("building", section: "listeners")
   pairs(split:, ..cells)
                    a two-column table, a thing and its meaning, rows on
                    alternating tints; split: 2 sets it as two tables side