Glossary & cross-references

Every Wit term, defined once, grounded in the AST kinds and source symbols so guide and reference prose can link a word to its precise meaning. Below the terms: how to build a glossary or cross-reference set from your own data.

Nodes and definitions

Node: A reusable content unit invoked with @name; either a core-vocab built-in or an author definition.
Node use: An invocation of a node (AST nodeUse); carries a paramsSource, a closeStyle, an optional body, and an inline flag.
Definition: A named template declared with #name (AST nodeDef); three shapes — single-line, value-block, block.
Data def: A named value declared with #name: value (AST dataDef); its value is a DataValue.
Core vocabulary: The 52 reserved node names that need no definition (CORE_VOCAB_NAMES) and ship built-in renderers.
Reserved name: A core-vocab name or the opaque node(isReservedNodeName); the resolver skips binding lookup for these.
Opaque node: @node(type X …) — a universal pass-through: dispatches to core vocab if type is one, else a <div data-*>.
Partial (additive): A +#name definition that contributes to a merged def across the file or project instead of redefining it.

Parameters and calls

Param: A named or positional argument to a node use (AST Param); optionally carries a typedValue.
paramsSource: How a use's params were written: parens, pipes, record, form-fill, none, or mixed.
closeStyle: How a use terminates: named (a matching close), parens (self-closing), or bare.
Form-fill: The bare-opener plus key: value lines call form (paramsSource: form-fill); needs two or more content lines.
Colon-scatter: A single-line @name k:v k2:v2 name@ body form; classified internally as paramsSource: pipes.
Flag param: A valueless param: a trailing bang in a pipe or a bare flag in parens.

Data and access

Record: An ordered key/value map, a brace literal (AST record); hyphen delimiter in data-defs, hyphen or colon at call sites.
Collection: An ordered list, a bracket literal (AST collection).
DataValue: The six-kind value union — string, number, boolean, null, record, collection — shared by defs, captures, and load.
Access path: A dotted lookup @a.b.c (AST AccessPath) with fuzzy key matching; numeric indexing currently renders unresolved.
Condition: The test in (if …): existence (a path) or a comparison (is / equals).
Iteration: (each @collection as item) … (end) (AST eachStatement); the element is referenced with @item.

Templating and holes

Capture: A named hole a def declares (#name ||a, b||), filled by the caller's params and referenced with ::a::.
Interpolation: ::name:: (AST interpolation), the substitution point for a capture. Distinct from the raw hole.
Raw-body interpolation: {{path}} — an expand-time hole valid only inside @@ raw bodies; supports dotted access; frozen @@@ disables it.
Body slot: ... (AST bodySlot), the placeholder in a block def where the invocation's body is inserted.

Raw and reference

Raw node: @@name … name@@ (raw): body is one verbatim Text node, re-interpolated only for {{…}}.
Frozen node: @@@name … name@@@ (raw + frozen): even {{…}} passes through untouched.
Reference directive: reference "path" — pulls definitions from another file into the current one.
Script: A <% … %> block or call; effects run at expand, output is omitted; lh is the data bridge.
load: The external-data directive @load … load@; rewritten into a data def by the load pass before resolve.
DataLoader / DataSource: The host-supplied seam load calls — a function or a plain { alias: value } dictionary.

Rendering and pipeline

Inline-context element: A core element that strips a single leading paragraph from its body (flattenIfInline).
Void element: A core element with no body or close — br, hr, img.
Unresolved fallback: The <span class="wit-unresolved"> a renderer emits for a name or capture that bound to nothing.
Pipeline stages: lex → parse → resolve → expand → render; the loadpass sits between parse and resolve.
Output pathways: The three HTML shapes: --fragment (bare article), --raw (reset-only page), default (styled document).

Build a glossary from data

Define terms once as data, then render the list from that source. Model the glossary as a collection of records and iterate it into a <dl>:

source

#glossary: [
  { term - Attention, gloss - A moral faculty of focus. },
  { term - Fresnel, gloss - A stepped lens for lighthouses. }
]

@dl
(each @glossary as g) @dt @g.term dt@ @dd @g.gloss dd@ (end)
dl@

result

Attention: A moral faculty of focus.
Fresnel: A stepped lens for lighthouses.

Read each field with data access — @g.term — not a capture hole. Edit the data and every view that reads it updates.

Cross-references and a shared bibliography

Give each referenced thing a unique id field and read it wherever you cite it. Keep the citation call shape uniform so every reference reads the same way. For a bibliography that assembles across chapter files, combine data with additive partials: each chapter contributes with +#bibliography and the master renders the merged node.

What is not built in

Automatic numbering

("Figure 3") and back-links("see above") are not core features. Either carry the numbers in your data, or compute them in a <% %> script (see Derived content). The core language gives the single source of truth and the views; numbering is a renderer or script concern.

Common mistakes

Mixing ::term:: and @g.term for the same read — use data access @g.term outside a definition body.
Assuming numbering and back-links are automatic — they are not.