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, 42 insertions, 17 deletions

diff --git a/docs/typ/style.typ b/docs/typ/style.typ
index 467577cc..9e98838d 100644
--- a/docs/typ/style.typ
+++ b/docs/typ/style.typ
@@ -22,27 +22,39 @@
 )
 #let mono = "DejaVu Sans Mono"
 
-/// Topic ids for #doc. Each names the document that holds the topic today;
-/// as topics move into docs/typ the value becomes the HTML page or chapter.
+/// Topic ids for #doc: each names a chapter (an id in `chapters`) and,
+/// optionally, the label of a section in it. Old ids stay so older calls
+/// keep working.
 #let topics = (
-  tags: "docs/tags.md",
-  fs: "docs/fs.md",
-  config: "docs/config.md",
-  themes: "docs/themes.md",
-  keys: "docs/helix-keys.md",
-  detached: "docs/detached.md",
+  guide: ("guide", none),
+  cheatsheet: ("cheatsheet", none),
+  scripting: ("scripting", none),
+  reference: ("reference", none),
+  themes: ("themes", none),
+  building: ("building", none),
+  tags: ("guide", none),
+  fs: ("reference", none),
+  config: ("guide", "config"),
+  keys: ("guide", "keys"),
+  detached: ("guide", "sessions"),
 )
 
+/// Set by a wrapper that holds every chapter (the book, the HTML): #doc
+/// then links to the chapter or section. Alone (the A4 sheet) it names it.
+#let doc-links = state("doc-links", false)
+
 /// The book's and the HTML's reading order. `file` is the content file
 /// in docs/typ, or none while the topic is not written yet (the outputs
 /// then show a placeholder). Wrappers include each with heading offset 1,
-/// so a file's `=` headings sit under its chapter title.
+/// so a file's `=` headings sit under its chapter title, labelled
+/// `ch-<id>`.
 #let chapters = (
-  (id: "guide", title: "Guide", file: none),
+  (id: "guide", title: "Guide", file: "guide.typ"),
   (id: "cheatsheet", title: "Cheatsheet", file: "cheatsheet.typ"),
-  (id: "scripting", title: "Scripting", file: none),
-  (id: "reference", title: "Reference", file: none),
-  (id: "building", title: "Building", file: none),
+  (id: "scripting", title: "Scripting", file: "scripting.typ"),
+  (id: "reference", title: "Reference", file: "reference.typ"),
+  (id: "themes", title: "Themes", file: "themes.typ"),
+  (id: "building", title: "Building", file: "building.typ"),
 )
 
 /// The tutor, shown as it is in the editor (`Tutor`), from the repo root.
@@ -154,11 +166,24 @@
   )
 }
 
-/// Where the full story is: a topic id from `topics`, and a section in it.
+/// Where the full story is: a topic id from `topics`, and a section label
+/// in it. A link where the wrapper holds the chapters, else its name.
 #let doc(id, section: none) = {
-  let to = topics.at(id) + if section != none { "#" + section } else { "" }
-  context if html-out() { link(to)[→ #to] } else {
-    text(fill: palette.num)[→#m(to, fill: palette.num)]
+  let (chapter, default) = topics.at(id)
+  let section = if section != none { section } else { default }
+  let title = chapters.find(c => c.id == chapter).title
+  let to = label(if section != none { section } else { "ch-" + chapter })
+  let named = title + if section != none { ": " + section.replace("-", " ") } else { "" }
+  context {
+    if doc-links.get() {
+      let found = query(to)
+      let shown = if found.len() > 0 and found.first().func() == heading {
+        if section != none [#title: #found.first().body] else [#title]
+      } else [#named]
+      link(to, text(fill: palette.num)[→ #shown])
+    } else {
+      text(fill: palette.num)[→ #named]
+    }
   }
 }