Gotchas & anti-patterns

Read this when Wit does something you did not expect. Ordinary prose stays prose; the surprises are a short list, each with its fix.

Prose that safely looks like syntax

None of these needs an escape — each renders exactly as typed:

Contact jane.doe@uni.edu about C# and F#, see https://x.org/docs#intro, or
tweet #MeToo. Report effects (if any) in the table. The result was
surprising!! The data [...] were incomplete. We compute P(A|B) and |x|.
It took ~5 minutes to reach ~/data. I multiplied 5*6*7 in snake_case_names.

Also prose: a line starting with the word "reference" and no path, doi:10.1/abc-style identifiers, and label lines such as Interviewer: How was it? — inside node bodies too.

Parentheses must touch the name

@weil (1952) is a reference followed by a year in parentheses; @weil(1952) passes a parameter. For a use to take parameters, the ( must be glued to the name.

A statement glued to a word

Once a statement is open in the paragraph, (else) and (end) may touch the word before them: (if @draft)draft(else)final(end). An (if glued to a word is prose.

A close pairs with the nearest open

See @a(href: a.org) here, and @a(href: b.org) the second site a@.

<p>See <a href="a.org"></a> here, and <a href="b.org">the second site</a>.</p>

The first link has no body. Close each use, or use the parenthesis form: (a(href: a.org) here a).

Values run to the next declared key

A word: inside a value is part of the value unless word is a parameter of that node. So a misspelt key does not fail — @card(title: Alpha, colour: red) gives title the value Alpha, colour: red when #card(title) declares only title. Only an unknown first key is E_UNKNOWN_PARAM. A positional value cannot start with word: — it reads as a key. Pass it by name.

Typos: errors versus markers

An undefined name — @weill, @boook.title — is E_UNRESOLVED_REFERENCE. A missing field on a defined record — @book.isbn — renders an unresolved marker and the build goes on. Search the output for wit-unresolved before publishing.

Data traps

• [ red green blue ] is one item. Separate items with commas or newlines.
• A space ends a data path: @keeper.years at post reads only @keeper.years. Use @keeper.yearsAtPost or @keeper.years_at_post.
• index, count and last are reserved field names — E_RESERVED_FIELD.
• In prose use @book.title. {{book.title}} works only in raw bodies, and ::title:: only inside definitions.

Do and avoid

See also

Escapes · Parameters · Data · Conditionals · Errors