Glossary & cross-references

Every Wit term, defined once and tied to its AST kind or source symbol. Below the terms: building a glossary or cross-references from your own data.

Nodes and definitions

Node: A named structure used with @name: a core name or an author definition.
Node use: One use of a node (AST nodeUse), with its params, an optional body (null when closeless) and an inline flag.
Parenthesis form: (name … name) — the same use as @name … name@, for any known node.
Closeless use: A use of a definition without ::body::, or of br, hr or img: it takes no body and needs no close.
Value-block use: @name(…): … !! — a use whose long body is closed by !! alone on its line.
Definition: A named template declared with #name (AST nodeDef); shapes block, single-line, value-block.
Header: #name(a, literal b) — the definition's parameters in order (AST HeaderParam). Optional; without it parameters are inferred from the placeholders.
Data definition: A definition whose value is a record, collection or scalar (AST dataDef).
Core vocabulary: The 52 names that need no definition (CORE_VOCAB_NAMES).
Opaque node: @node(type: x, …) — passes every parameter to the renderer (RESERVED_OPAQUE).
Entry list: The list built by +#name: … !! entries across every file, in the order met, each once; render it with a loop.

Parameters

Parameter: A key: value in a use's glued parens (AST Param); name is null for a positional value.
Positional value: A value without a key, bound in header order: @cite(Weil, 1952). Cannot hold a comma.
Literal parameter: A header parameter marked literal — its value is used exactly as written. href and src are literal.
Placeholder: ::name:: (AST interpolation) — where a parameter's value goes in a definition body.
Body slot: ::body:: (AST bodySlot) — where a use's body goes. A definition without one takes no body.
paramsSource: How a use's parameters were written: parens or none.
argsRaw: The text inside a use's (…), kept so the expander can split it against the definition's declared parameters.

Data

Record: { key: value } (AST record); a value runs to the next key:.
Form-fill record: A value-block definition whose lines are all key: value.
Collection: [ a, b ] (AST collection).
DataValue: String, number, boolean, null, record or collection — shared by data definitions, parameters and @load.
Access path: @a.b.0 (AST AccessPath); keys match loosely, numbers index from 0.
Loop position: @item.index, @item.count, @item.last inside (each … as item).
Condition: The test in (if …): a truthy path, or @path is value.

Raw, files, scripts

Raw node: @@name … name@@ — a verbatim body; {{path}} holes still fill.
Frozen node: @@@name … name@@@ — verbatim, nothing fills.
Reference: reference ./file.wit (AST reference) — pull in another file's definitions and entries.
Script: <% … %> or @scriptCall(fn, …) — JavaScript run at expand time; inline, the value is inserted. lh is the bridge to the document's data.
load: @load alias load@ — external data, turned into a data definition before resolve.
DataLoader / DataSource: The host function, or plain { alias: value } object, that @load reads from.
Stray marker: A structural character no open construct can use; it is turned back into prose (parser-stray.ts).

Pipeline

Stages: lex → parse → load → resolve → expand → render.
Closeless scan: Before parsing, the definitions in every referenced file are scanned for names without ::body:: (scanCloseless).
Unresolved marker: <span class="wit-unresolved"> for a missing field.
Output modes: --fragment (the article only), --raw (reset-only page), default (styled page).

Build a glossary from data

Keep the terms as a collection of records and loop them 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.

Edit the data and every view that reads it changes.

Cross-references

Give each thing an id field and link to it with (a(href: #fig-lamp) … a). For a bibliography that collects across chapter files, each chapter adds +#sources: … !! entries and the main file loops @sources — see additive partials.