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)nameis the construct, matched in any case. Some constructs also answer to an alias, which their reference page lists:scnforscene,imgforimage,!hfor!highlight.#idnames this instance so other constructs can refer to it (Identifiers & references).:valuesets the construct's implicit attribute (the implicit attribute).{ }is the body and[ ]the detail (Body & detail).( )is the attribute group (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.
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 :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 headingsh1toh4-— an item of a bulletedlist;1.— an item of a numbered one---— adivider===— astep
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.
$ 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.
{{ 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:(…),#islands*— the document header,*(…), first in the file{{ }}— an expression:{{2 * #f.slope}}//— a comment line\— an escape