Selecting canvas content

#A mark's effect on the reader's understanding

A mark belongs on the canvas when its presence changes what the reader understands. Relevance and accuracy are not sufficient: a mark whose removal leaves the argument equally clear is decoration, and competes for attention with the marks carrying the argument.

#The detail read on its own

A detail can be opened full screen, without the narrative beside it. What is on the canvas therefore has to hold as a picture: the marks named by their own label:, the axes saying what they hold, the environment's title: naming its subject where it takes one. The body is what a lecturer says and the detail is what is on the board — and a board that reads only while someone is talking over it is a board with the labels missing.

#Four failure modes

• Restating the prose. A text mark repeating the adjacent sentence adds nothing to it.
• Decorative accuracy. Gridlines, ticks and axis labels the argument never refers to. show-grid, show-ticks and show-axes control each independently.
• Simultaneous reveal. Four curves drawn at once where the argument concerns one. cue reveals each as the prose reaches it.
• Unlabelled marks named by position. A mark the prose calls the upper line carries a label: instead.

#Two environments maximum, one claim each

A scene detail holds at most two canvas environments, and direction and ratioarrange them — data beside the code producing it, a function beside its residuals. A third environment is a compile error rather than a layout decision:

Leave direction at its default auto. A split canvas is read twice — in the column beside the prose and again full-screen in presentation — and the axis that works in one is the wrong one in the other, so auto stacks the pair while reading and sets them side by side while presenting. Naming horizontal or vertical outright is for a split whose axis is part of what it says, not for the arrangement that looked right in whichever of the two you happened to be in when you wrote it.

scene{
    Three things at once.
}[
    canvas.graph{ curve(expression: x^2) }
    canvas.graph{ curve(expression: x^3) }
    canvas.code{ lines{ y = x ** 2 } }(language: python)
]

#The empty detail

A scene detail is optional. A scene stating a definition, posing a question or drawing a conclusion may carry none; a canvas left standing from the preceding argument describes that argument rather than the current one.