Layout & content

#What a canvas holds

A scene's detail [ ] is its canvas. It holds canvas environments — graph, code, region, flowchart, logic and network, two at most or one grid of them — and, around them, content that belongs to no environment: paragraphs, headings, lists, equations, tables, images and questions. Scenes & steps lists everything the detail accepts and the refusal for anything else.

The canvas is drawn in the order it is written: a table written above a graph sits above it. A run of content between environments is set as one block.

scene{
    The distance a dropped stone has fallen, as a curve and as a table.
}[
    ## Distance fallen from rest

    graph{
        curve(expression: 4.9x^2; domain: [0, 3])
    }(
        x-domain: [0, 3]
    )

    table{
        $t$ (s) | Distance (m)
        1       | 4.9
        2       | 19.6
        3       | 44.1
    }
]

A control — slider, selector or their cue twins — written in the detail outside any environment belongs to the scene: it sits in the footer under the canvas, not where it is written. Controls has the rest.

#Two environments side by side

Two environments in a detail are split, and the scene's direction arranges them: auto, the default, stacks them while the internote is read beside its narrative and sets them side by side in presentation; horizontal sets them side by side and vertical stacks them, in both. ratio is the first environment's share of the split over the second's — 3/2, 3:2 or a positive number — and the shares are equal when it is left out.

Show code

graph{
    curve(expression: 4.9x^2; domain: [0, 3])
}(
    x-domain: [0, 3]
)
code{
    lines{
        def fallen(t):
            return 4.9 * t ** 2
    }
}(
    language: python
)

The same pair with the graph given three fifths of the split:

scene{
    The curve and the code that computes it.
}[
    graph{
        curve(expression: 4.9x^2; domain: [0, 3])
    }
    code{
        lines{
def fallen(t):
    return 4.9 * t ** 2
        }
    }(
        language: python
    )
](
    ratio: 3/2
)

On a scene with fewer than two environments, a direction other than auto or any ratio draws a warning: 'direction'/'ratio' only apply when the detail declares two canvas environments. On a scene with a grid neither has any effect. A third environment outside a grid is an error:

scene{
    Three falls.
}[
    graph{
        curve(expression: 4.9x^2)
    }
    graph{
        curve(expression: 1.6x^2)
    }
    graph{
        curve(expression: 12.4x^2)
    }
]

#A grid of environments

A grid lays one to nine environments out in rows and columns, placed across and then down. columns, the implicit attribute, is 1, 2 or 3: grid:3{…}. Left out, the grid takes the column count whose cells come out nearest square on the reader's canvas, so a pair stacks beside the narrative and sits side by side in presentation. Each environment keeps its own frame and cues, and the scene's steps and parameters reach every one. Content written around the grid stays outside it, above or below, across the whole canvas.

Show code

grid{
    graph{
        curve(x: cos(t); y: sin(t); t: [0, 2 * pi]; colour: purple; fill)
    }
    graph:xyz{
        vector(dx: 1; dy: 0; dz: -2; colour: blue)
        vector(dx: 1; dy: 2; dz: 4; colour: teal)
        vector(dx: 7; dy: 1; dz: 0; colour: red)
    }(
        aspect: equal
    )
}

equation{
    \text{area of } T(S) = |\det A| \cdot \text{area of } S
}

The grid's body holds environments only; a table or paragraph inside it is refused with that list. A scene with a grid holds all its environments in it, and holds one grid. Each breach is an error:

• A scene with a grid holds its environments in the grid; write 'graph' inside it
• A scene detail holds one grid; found 2
• A grid holds at most 9 environments, three by three; found 10
• A grid holds environments, and this one has none

scene{
    Three falls.
}[
    grid{
        graph{
            curve(expression: 4.9x^2)
        }
        graph{
            curve(expression: 1.6x^2)
        }
    }
    graph{
        curve(expression: 12.4x^2)
    }
]

#Tables

A table's body is one row per line, split into cells on | (or the character in delimiter). Each cell takes inline Chalk — maths, bold, a colour. The first row is the header unless header-row: false; header-column, footer-row and footer-column style the other edges. title is a caption above the table.

scene{
    Area and species on three of the islands.
}[
    table{
        Island     | Area (km²) | Species
        Baltra     | 25.09      | 58
        Bartolomé  | 1.24       | 31
        Santa Cruz | 903.82     | 444
    }(
        title: Three of the Galápagos
        highlight-rows: 4
    )
]

highlight-rows, highlight-columns and highlight-cells count from 1. Columns may be letters, and a cell is a letter and a row, B4, or a block, A2-C3.

Bound to a @data dataset, a table takes its rows from it and ignores its body. The column names are the header row, columns picks and orders them, and the cells are shown as plain text.

@data#islands{
    island     | area   | species
    Baltra     | 25.09  | 58
    Bartolomé  | 1.24   | 31
    Santa Cruz | 903.82 | 444
}

scene{
    Species against area.
}[
    table:#islands(
        columns: island, species
        highlight-cells: B4
    )
]

A table bound to a dataset that is not attached shows the reason in place of its rows. A table is on the canvas for the whole scene: a cue cannot bring one in, and one written inside a cue is refused.

#Images

An image's source, its implicit attribute, is the name of a file attached to the internote or a URL beginning https:, data: or /. caption is rich text set under the image, and its plain text is the image's alt text; an image without one has none.

scene{
    The transect at low tide.
}[
    img:transect.jpg(caption: The transect at low tide, from the north end)
]

Unlike a table, an image can arrive on a step inside a cue:

scene{
    The transect at low tide.
    ===
    The same transect six hours later.
}[
    image(source: low-tide.jpg; caption: Low tide)
    cue{
        image(source: high-tide.jpg; caption: High tide)
    }(
        in: 1
    )
]

In the narrative an image is refused, with the list of what the narrative takes:

scene{
    The transect at low tide.
    image(source: transect.jpg)
}