Grammar

How a line is read as prose or a construct: the head and its three sections, marker spellings, escapes and sigils.

On this page

#Prose lines and paragraphs

Chalk is read a line at a time. A line that does not open a construct is prose. Consecutive prose lines join into one paragraph, separated by a space, and a blank line ends the paragraph. Indentation in prose is ignored.

scene{
    A body falls a distance
    proportional to the square of the time.

    The constant of proportionality is g/2.
}

That body holds two paragraphs. A line whose first characters are // is a comment and is dropped without ending the paragraph around it (Comments).

#Constructs

#The shape of a construct

A construct is written as a head followed by up to three bracketed sections:

name#id:value{body}[detail](attributes)

Every part after the name is optional, but the order is fixed: #id before :value, and the sections in the order body, detail, attributes, each at most once. A section may run over as many lines as it needs, so long as its brackets balance. Once the last section closes, nothing else may follow on that line.

curve#flight:x^2(colour: blue)
image:photo.jpg(caption: The apparatus)
scene{
    The narrative.
}[
    graph{
        curve(expression: x^2)
    }
](
    loop
)
scene{
    The narrative.
}(loop)[
    graph{
        curve(expression: x^2)
    }
]

[parse]sections on node `scene` are out of order or duplicated

#When a line is a construct

A line opens a node only when a bracket follows its head. An empty attribute group supplies the bracket: image:photo.jpg() is the image.

Warning
Without a bracket the line is prose, which is why Note: this is important compiles as a paragraph although note is a node, and why image:photo.jpg on its own is a sentence.

A micronode is written inside a line of text, with ! before its name, and is held to the same test: !cite:#fs1969() is a citation, and !cite:#fs1969 is literal text. A name after ! that no micronode has, followed by a bracket, is an error.

A directive begins its own line, with @ before its name, and is recognised by the name alone, so @include:overview.part.chalk needs no bracket. Its sections may come in any order. Written in the middle of a line, @ is an ordinary character; at the start of a line, a name no directive has is an error.

@note{
    Check the units.
}

[unknown-identifier]unknown directive `@note`

#Spelling

#Marker spellings

Some constructs are written with a marker instead of a name. A line marker opens its line and must be followed by a space, so #Results is prose:

  • # , ## , ###  and ####  — the headings h1 to h4
  • -  — an item of a bulleted list; 1.  — an item of a numbered one
  • --- — a divider
  • === — a step

Inline delimiters wrap a run of text:

  • **…** — bold
  • *…* — italic
  • `…` — inline code
  • $…$ — inline maths
  • ==…== — !highlight

A delimiter opens only when its closer follows within the same paragraph. Unpaired, it is literal, so a single * or $ prints as itself.

Warning
Two $ in one paragraph always pair: It costs $5 and $10 sets 5 and as maths, and the compiler warns that words are set as maths.

#Escapes

A backslash makes the marker, delimiter, sigil or bracket after it literal: It costs \$5 and \$10, \*, \`, \!, \#, and \\ for a backslash. Before any other character the backslash is kept, which is what leaves $\pi$ intact. Inside an attribute group, \; is a literal semicolon.

Warning
{{ has no escape: it always opens an expression.

#Sigils

  • # — names an instance, or refers to one: curve#flight, of: #flight
  • . — a kind within a namespace, cue.trace, axis.label; or a member of an instance, #islands.area
  • : — the implicit attribute, after the head: image:photo.jpg
  • ! — a micronode: !teal{…}; in an attribute group, a negated boolean: !endpoints
  • @ — a directive: @let(…), @data#islands
  • * — the document header, *(…), first in the file
  • {{ }} — an expression: {{2 * #f.slope}}
  • // — a comment line
  • \ — an escape

Last updated