Comments

// for a line and @ignore for a block, and the literal bodies where // is kept as text.

On this page

#// comment lines

A line whose first characters, after any indentation, are // is a comment. It is dropped and leaves nothing behind: the lines either side of it in a paragraph still join into one paragraph. A comment line is read between constructs, in prose, among the rows of a table or @data body, and as an entry of a multi-line attribute group.

// Scene 2 picks up the fit from scene 1.
scene{
    A straight line
    // degree 1 on purpose: the residuals are the point
    captures the trend.
}[
    graph{
        scatter(x: 1, 2, 3, 4; y: 1.1, 1.9, 3.2, 3.9)
    }(
        // the window starts at zero so the intercept shows
        x domain: [0, 5]
        y domain: [0, 5]
    )
]

The body holds one paragraph, A straight line captures the trend.

Warning
A // after other text on the same line is part of that text: Real text. // trailing compiles to a paragraph that ends in // trailing.

#@ignore for a block

@ignore drops its whole body without reading it, so what is inside need not compile. Its braces must still balance. Like any directive it begins its own line, and it may stand wherever a construct may: between scenes, in a scene's body, in an environment.

graph{
    curve(expression: x^2)
    @ignore{
        curve(expression: x^3; colour: grey)
    }
}

Unlike a // line, an @ignore in the middle of prose ends the paragraph before it. It takes no attributes and no :value.

#// in a literal body

In a literal body, the code of a lines chunk or the TeX of an equation, // is text and is kept. A comment in the environment's language reaches the rendered code.

code{
    lines{
        // the loop runs once per reading
        for (const r of readings) total += r;
    }
}(
    language: javascript
)

#Writing guidance

  • Source style — The conventions that keep a .chalk file legible to the next person editing it by hand.

Last updated