Node use & the bare reference

Every structure in Wit is a node: a name that wraps content. This page covers how a use opens and closes, the parenthesis form, uses that need no close, and how the same handle reaches into data.

Open, close, body

@name opens, name@ closes, and everything between is the body. Indentation is cosmetic; only the open and close count.

@aside
Every recipe serves four unless noted.
aside@

Fold in the @em cold em@ butter.

<aside><p>Every recipe serves four unless noted.</p></aside>
<p>Fold in the <em>cold</em> butter.</p>

A use that fills its own lines is a block; inside a sentence it stays inline. You never mark which.

The parenthesis form

(name … name) is the same use, easier to type. Parameters glue to the name as usual. Prefer it for one-line uses.

(h2 Ingredients h2)

Fold in the (em cold em) butter, then see (a(href: /recipes/pastry/) the pastry guide a).

<h2>Ingredients</h2>
<p>Fold in the <em>cold</em> butter, then see <a href="/recipes/pastry/">the pastry guide</a>.</p>

It also works around a block — (section on one line, section) on a later one. It opens only when a known node name and a space, line break or its params follow the (, and the matching name) closes it in the same paragraph. Every other parenthesis is prose:

Bake (about 20 minutes) until (a) golden or (b) crisp.

That stays one plain paragraph.

The bare reference

A handle with nothing attached inserts a definition — the usual way to reuse a named phrase or cite a source mid-sentence.

#weil: Weil (1952) !!

Attention, as @weil argued, is a moral act.

That renders <p>Attention, as Weil (1952) argued, is a moral act.</p>. A bare reference with no definition is E_UNRESOLVED_REFERENCE.

Uses that need no close

A definition without ::body:: takes no body, so its uses are closeless wherever they sit:

#signoff
— The editors, Ledbury Gazette
signoff#

Thanks for reading.
@signoff

<p>Thanks for reading. — The editors, Ledbury Gazette</p>

Closing one anyway — @signoff See you next week. signoff@ — is E_BODY_WITHOUT_SLOT, not a silently dropped body. The void core names br, hr and img never take a body either.

A use whose definition has ::body::, or a core container such as section or aside, must be closed when it opens a block; otherwise you get E_UNCLOSED_NODE. A close pairs with the nearest open of the same name, so nested uses pair like brackets.

Attaching a node to a word

@name may follow a letter directly when the name is a known node — for formulas, units and footnote marks. Email addresses stay prose.

CO@sub 2 sub@ levels rose to 420 ppm@sup † sup@. Write to ed@gazette.org.

<p>CO<sub>2</sub> levels rose to 420 ppm<sup>†</sup>. Write to ed@gazette.org.</p>

Where the name ends

A name is letters, digits, _ and -. The first other character ends it, so a comma or a sentence-final period stays prose: @paper-stats, @chapter_one, and @weil. resolves three definitions. Names are case-sensitive — @Weil does not find #weil.

Data in prose

Wherever a bare reference works, so does a dotted path into data:

#book: { title: The Salt Road, edition: 2 } !!

You are reading edition @book.edition of @book.title.

That renders You are reading edition 2 of The Salt Road. A missing field renders an unresolved marker instead of failing the build (see Data).

Common mistakes

• Leaving a container open — @aside with no aside@ is E_UNCLOSED_NODE.
• Giving a body to a definition with no ::body:: slot — add the slot, or drop the close.
• Expecting @Weil to match #weil — names are exact.
• Expecting a typo to always fail the build — an undefined name is E_UNRESOLVED_REFERENCE, but a missing field on a defined record (@book.isbn) only renders a marker.

See also

Parameters · Defining nodes · Data access · Gotchas · Core vocabulary