Steps, timers, sweeps & parameters

#Four clocks for a change

A canvas changes in four ways, and each puts the change on a different clock.

• A step. === in the narrative starts a step, and a cue anchored to it (in: 1) fires when the reader advances to that sentence.
• A timer. An anchor with a time, in: 1 + 3s, fires three seconds after step 1 begins, whether or not the reader has reached the sentence it belongs to.
• A sweep. cue.slider runs a parameter across its range, starting at its at: anchor and taking duration:.
• A parameter. slider and selector give the change to the reader.

Motion documents the anchors and durations, Controls the controls and the parameters they set.

#New content on a step

New content — a mark, a label, an equation, a list item, a question — arrives on the step whose sentence introduces it. A step moves at the reader's pace, so the sentence at step two stands beside the canvas as it is at step two, and one anchor keeps the two together. A sentence about a mark not yet drawn is a caption written early; a mark drawn before its sentence is looked at before it is explained.

scene{
    A straight line through these readings runs above the middle
    ones and below both ends.

    ===

    A quadratic follows the bend the line could not.
}[
    graph{
        scatter#readings(x: 0, 1, 2, 3, 4, 5, 6; y: 0.1, 0.3, 1.0, 2.2, 4.1, 6.3, 9.0)
        fit(of: #readings; model: linear; colour: grey)

        cue{
            fit(of: #readings; degree: 2)
        }(
            in: 1
        )
    }
]

#A marker with nothing anchored to it

A step marker is a trigger on the timeline, not a paragraph break: paragraphs are separated by a blank line. A marker nothing is anchored to makes the reader advance a scene that then stands still, so a scene whose canvas never changes carries no markers, and each marker in one that does has something anchored to it. Nothing checks this. The compiler checks the other direction: an anchor past the last marker names a step that does not exist.

scene{
    One.

    ===

    Two.
}[
    graph{
        cue{
            point(x: 1; y: 1)
        }(
            in: 3
        )
    }
]

#Timers for timing that means something

A time offset is for motion whose timing is itself the content: a projectile in flight, a point travelling along a curve, one movement in several beats. There the seconds are what the reader watches. Content that is new belongs on a step instead, because a timer delivers it at a moment the reader may not have reached, or may have read well past.

#Sweeps for a process of change

A sweep is the form for a scene whose prose already describes a process of change — a bandwidth widening until the bumps smooth away, a reading dragged out until it pulls the fitted line round — and where the frames between the steps show what the steps cannot: the shape changing, not only the shapes before and after. Every frame is the real computation, a mark that is closed-form in the parameter or recomputes from it, so any frame the reader stops on is a true picture. A sweep added because the scene could be animated, with no change in the prose to show, is motion for its own sake.

The sweep starts on the step whose sentence describes it. !autoplay on the scene holds each animated step at its start until the reader presses play, for motion that has to be watched from the beginning.

scene{
    A kernel density estimate is a sum of bumps, one per reading,
    and the bandwidth is how wide each bump is.

    ===

    As the bandwidth widens, the three clusters merge into one.
}[
    graph{
        density(x: 1.0, 1.3, 1.5, 3.9, 4.2, 4.4, 7.8, 8.1; bandwidth: h)
        cue.slider:h(range: [0.2, 3]; name: bandwidth; at: 1; duration: 6s)
    }
](
    !autoplay
)

#Parameters and the range criterion

A parameter gives a change to the reader; a cue keeps it on the author's timeline. The criterion between them is the range. A change belongs to a parameter when one sentence stays true across the parameter's whole range, and to a cue otherwise. slider:k(range: [0, 5]) asserts that the narrative holds anywhere in [0, 5], since the reader can reach any value in it, so the prose describes the range rather than a point:

• Holds across the range: at degree one the fit misses the curvature; past three it chases the noise.
• Does not: the fit passes close to every point — true at one setting and false at most others.

Where a single value supports the sentence, that value is the author's, and a cue or a sweep shows it. A document exposes the degrees of freedom its argument covers, and no others.

#Leaving the authored path

A reader moving a parameter leaves the authored path, and moving it back returns the canvas to the state the narrative describes. The judgement is not that unnarrated states are unreachable, but that every state a document exposes is one its prose stays true in.

#Checking a parameter at both ends

The criterion is checked by moving each parameter to both ends of its range and rereading the scene. Prose that is then false is either a sentence to rewrite or a parameter that should have been a cue.