Wit

Changelog

Release history for Wit. The format follows Keep a Changelog and is driven by Changesets; pre-1.0, the version stays in the 0.x range and breaking changes are allowed with notes.

0.3.0 — unreleased

A syntax redesign: one way to pass parameters, a real body slot, and prose that never turns into structure by accident. Breaking — run wit migrate <dir> -w on 0.2 sources.

Language

  • Parameters live only in glued parens, @img(src: a.png, alt: A lamp). A value runs to the next key: the node declares, so commas and colons need no quoting; parentheses inside a value balance; parameters may span lines, and a blank line before ) is E_UNCLOSED_PAREN.
  • Definition headers #cite(author, year): positional values @cite(Weil, 1952), literal parameters, and E_UNKNOWN_PARAM, E_MISSING_PARAM, E_TOO_MANY_ARGUMENTS, E_POSITIONAL_WITHOUT_HEADER.
  • ::body:: is the body slot; ... is always prose. A use's body is always content.
  • Closeless uses: a definition without ::body:: takes no body and its uses need no close, across referenced files; closing one is E_BODY_WITHOUT_SLOT. A close pairs with the nearest open of its name.
  • The parenthesis form (name … name) for any known node, including names defined in referenced files; with both ends on lines of their own it spans paragraphs.
  • Value-block uses @name(…): … !!.
  • Loop positions @x.index, @x.count, @x.last; those field names are reserved (E_RESERVED_FIELD).
  • +#name entries form a list, collected once from every file and rendered with a loop.
  • Conditions test simple definitions and parameters ((if ::met::)); quoted values compare their text; statements inside a line stay inline. A definition inside (if) or (each) is E_CONDITIONAL_DEFINITION.
  • A known node may follow a word: H@sub 2 sub@O.
  • Numbers render as written (0.050); quoted and loaded values are literal text.
  • A file's own definition overrides a referenced one; a referenced file's top-level @@style applies; a folder reference reads its main.wit.

Templates

reference wit/paper — bundled templates with shared pieces (title, author, abstract, chapter, …): document, paper, thesis, report, letter, article, book, manuscript. wit build --template thesis swaps one without editing the file.

Academic writing

Numbered headings, figures, tables and equations; @ref(id) cross-references; @contents; footnotes (fn … fn) as endnotes; citations @cite(id, p. 117) from #sources records or a BibTeX file — books, articles, chapters, theses, reports, web pages — in APA 7, MLA 9 or Chicago author-date, with @bibliography, or in a house style defined as #wit_reference / #wit_citation; native Markdown footnotes; templates wit/apa and wit/mla; PDF bookmarks. See Papers & theses.

Removed

Pipe parameters |k v| and capture lists ||a, b|| (E_PIPE_SYNTAX_REMOVED); { … } calls and space-separated parens (E_REMOVED_SYNTAX); colon-scatter and form-fill use bodies (now prose); the ... body slot; key - value (E_MALFORMED_RECORD); equals (E_MALFORMED_STATEMENT); mid-body parameter switching. See the removed-syntax table.

Tooling

  • wit migrate <file|dir>… [-w] rewrites 0.2 sources, reading the definitions of every referenced file.
  • wit fmt --check; wit fmt never changes what a document renders.
  • wit check runs the full build pipeline over several files; errors name the file they are in.
  • wit tokens [--parser] shows how a snippet lexes.
  • wit build --paper a4|a5|letter|legal sets the page size.
  • Warnings — W_UNRESOLVED_FIELD, W_UNUSED_DEFINITION, W_SUSPECT_PARAM — from wit check and wit build.
  • Strict arguments for parse, tokens and fmt. CSV/TSV sources read quoted fields; a source's run is relative to the sources file; @load works in referenced files and node bodies; asset paths in referenced files are rebased; a PDF build fails rather than keep a stale PDF.
  • VS Code: 0.3 highlighting, errors from referenced files, :: completion of the enclosing definition's parameters.

Fixed

  • Ordinary prose keeps every character: (if any), [...], !!, P(A|B), a line starting with "reference", Word: text lines, emails and C#.
  • Emphasis works next to non-ASCII letters; \ escapes any punctuation; a leading byte-order mark is dropped.
  • Scripts run inside node bodies; the lh bridge's word count, lh.set and lh.inject work.
  • Tables: sections, schema labels, rows from a parameter; figure parameters, id and class render.
  • Markdown: nested lists indent, prose is escaped, math is delimited.
  • A referenced file may use what its parent or a sibling defines. A value block keeps its paragraphs, and one without its !! is E_UNCLOSED_DEFINITION. A comment or prose line above a block no longer changes it; (else) / (end) may touch a word; a lone | is text; + entry lists render one entry per paragraph and loop over record fields.
  • A one-line definition without !! ends at its line; pre and code keep their lines; a flag set to false is off; references in any letter case resolve; readable highlighting in dark mode.

0.2.1

A bug-fix release. wit --version reports 0.2.1.

Fixed

  • Collection index access now resolves. Reaching into a collection by number — @findings.0.claim, @list.1, and nested @r.items.1 — previously rendered as an unresolved marker. Numeric indexing now works in prose, conditionals, and iteration access; an out-of-range or non-numeric index degrades gracefully instead of throwing.

Changed

  • Package repository / homepage / bugs URLs now point at github.com/PurpleReverie/witlang (repo renamed; the @witlang/* npm names are unchanged).

0.2.0

wit --version reports 0.2.0, matching the published packages.

Language features

  • Literal and frozen raw nodes (@@name … @@, @@@name … @@@) with {{path}} interpolation inside raw-node bodies.
  • A styled render target and a Word/Docs-style default theme.
  • External data: the @load node pulls a JSON/CSV/TSV/lines/text result from a configured program (wit.sources.json) into a def.
  • @table |rows @data| — build a table from a referenced data collection.
  • Image sizing and placement (size, align) plus invisible @row / @col layout containers.
  • Core vocabulary grew to 52 names (adds div, span, cite, row, col).
  • Typed parameters and iterable captures; emphasis and escape fixes — a backslash now escapes @, #, |, and the emphasis marks in prose.

Tooling

  • wit fmt — re-indents a document to match its nesting without changing structure.
  • HTML-like indentation and PDF output (with a <base href> so relative assets resolve).

0.1.0 — initial public release

The first public release, which reported 0.1.0.

Packages

  • parser — lexer and parser producing a typed AST.
  • runtime — resolver and expander.
  • render-html — the HTML renderer.
  • render-markdown — the Markdown renderer.
  • cli — the wit command: parse, check, fmt, build, and tour.

Language features

  • Nodes, definitions, additive partials, records, and collections.
  • Data access, conditionals, iteration, and the script bridge.
  • The reserved core vocabulary — headings, inline marks, lists, links and media, tables, blocks, and sectioning; see the core vocabulary reference for the full list.
  • Tables in inline, schema-array, and schema-record forms.
  • The opaque @node pass-through.
  • The form-fill body shape and record-argument invocation.

See also

Roadmap covers what is planned next; Install includes the version smoke test.