The guide's glossary is a definition list, and the site's tutor links its pointers into the guide

On the site the glossary is a <dl> of terms and meanings inside its
<details>, with no stray count, so a text browser reads each term then
its meaning. The tutor page links docs/typ/<chapter>.typ to that page,
each "-> Guide: <section>" to the guide's section of that title (read
from guide.typ's headings), and URLs; the tutor itself keeps its text.

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

3 files changed, 30 insertions, 6 deletions

diff --git a/docs/site/site.css b/docs/site/site.css
index 260a1b35..6f8836ee 100644
--- a/docs/site/site.css
+++ b/docs/site/site.css
@@ -132,7 +132,6 @@ body { margin:0; min-height:100vh; background:var(--field) radial-gradient(color
 .glossary { margin:1.4em 0; }
 .glossary summary { cursor:pointer; list-style-position:inside; }
 .glossary summary h3, .glossary summary p { display:inline; margin:0; }
-.glossary summary .count { font:20px var(--pixel); color:var(--dim); margin-left:.4em; }
 .vh { position:absolute; width:1px; height:1px; overflow:hidden; clip-path:inset(50%); white-space:nowrap; }
 .colophon { font:15px var(--pixel); color:var(--dim); text-align:center; }
 .colophon a { color:var(--leaf); }
@@ -217,3 +216,8 @@ main[data-page="builtins"] .content h4 + p { margin-top:0; }
 /* a recording inside a chapter */
 .content .clip.inline { margin:1.2em 0; max-width:640px; }
 .clip.inline video { display:block; width:100%; height:auto; aspect-ratio:960/700; background:var(--deep); }
+.glossary dl { margin:.6em 0 0; display:grid; grid-template-columns:minmax(8em, max-content) 1fr; }
+.glossary dt, .glossary dd { margin:0; padding:5px 9px; }
+.glossary dt { font-weight:600; color:var(--leaf); }
+.glossary dt:nth-of-type(odd), .glossary dt:nth-of-type(odd) + dd { background:color-mix(in srgb, var(--tag) 70%, transparent); }
+@media (max-width:600px) { .glossary dl { grid-template-columns:1fr; } .glossary dd { padding-top:0; } }
diff --git a/docs/site/site.typ b/docs/site/site.typ
index f50a8d9b..47903d6e 100644
--- a/docs/site/site.typ
+++ b/docs/site/site.typ
@@ -254,11 +254,27 @@
 /// chords it writes 1-2 (hold 1, click 2) become the docs' mouse glyphs,
 /// each with its hidden words, inside the preformatted block.
 #let tutor-text(t) = {
+  // the guide's sections by title, for "-> Guide: Modes, Config"
+  let guide-sections = (:)
+  for m in read("../typ/guide.typ").matches(regex("(?m)^= (.+?) <([a-z0-9-]+)>$")) {
+    guide-sections.insert(m.captures.at(0), m.captures.at(1))
+  }
+  let tokens = regex("\\bB([123])\\b|\\b([123])-([123])\\b|docs/typ/([a-z]+)\\.typ|(?m)(?:^ -> Guide: )(.+)$|https://[^\\s)]+")
   let at = 0
-  for m in t.matches(regex("\\bB([123])\\b|\\b([123])-([123])\\b")) {
+  for m in t.matches(tokens) {
     t.slice(at, m.start)
-    if m.captures.at(0) != none { btn("B" + m.captures.at(0)) }
-    else { chord("B" + m.captures.at(1), "B" + m.captures.at(2)) }
+    let (b, c1, c2, page, sections) = m.captures
+    if b != none { btn("B" + b) }
+    else if c1 != none { chord("B" + c1, "B" + c2) }
+    else if page != none { link(page + ".html", m.text) }
+    else if sections != none {
+      " -> Guide: "
+      sections.split(", ").map(name => {
+        let l = guide-sections.at(name, default: none)
+        if l != none { link("guide.html#" + l, name) } else { name }
+      }).join(", ")
+    }
+    else { link(m.text, m.text) }
     at = m.end
   }
   t.slice(at)
diff --git a/docs/typ/style.typ b/docs/typ/style.typ
index 9753eedf..f651878f 100644
--- a/docs/typ/style.typ
+++ b/docs/typ/style.typ
@@ -329,9 +329,13 @@
 /// and the table; in HTML a <details> that starts closed, its summary the
 /// heading and the count, so a reader who knows the words skips them.
 #let glossary(title, lbl, ..cells) = context if html-out() {
+  // a real definition list, so a text browser reads term, then meaning
   html.elem("details", attrs: (class: "glossary"), {
-    html.elem("summary", [#heading(title) #lbl #html.elem("span", attrs: (class: "count"), "(" + str(calc.quo(cells.pos().len(), 2)) + ")")])
-    pairs(..cells)
+    html.elem("summary", [#heading(title) #lbl])
+    html.elem("dl", for (term, meaning) in cells.pos().chunks(2) {
+      html.elem("dt", term)
+      html.elem("dd", meaning)
+    })
   })
 } else {
   [#heading(title) #lbl]