question

#Where a question is written

A question is canvas content. It is written in a scene's detail, where a table or a paragraph of the canvas is written, and never in the prose: the narrative makes the argument, and the canvas is where the reader acts on it. The detail is laid out in the order it is written, so a question written after a graph sits beneath it, and the reader answers with the graph still in view. It does not take one of the scene's two environment slots, so a scene can hold a graph, a code environment and any number of questions.

Hide code

@let(
    archard: 0.028 * x * y * 60 / 1000
)

canvas.graph{
    surface(expression: {{archard}}; range: [0, 42])
}(
    x axis label: load, kN
    y axis label: speed, rpm
    x domain: [2, 6]
    y domain: [800, 2000]
)

question#read-off:maths{
    Read the wear at $4$ kN and $1200$ rpm off the chart,
    to one decimal place.
}(
    expect: 0.028 * 4 * 1200 * 60 / 1000
    form: rounded(1)
)

A question inside a cue arrives on that step, beside the prose that sets it up. Every question needs an #id: the reader's answers are kept under it, so moving a question to another scene keeps them, and the compiler refuses a question without one.

#The three kinds

respond: fills the head's slot and decides what the reader answers with, and which other attributes the question takes.

• text — a typed word or phrase. expect: lists the accepted answers, any of which is right, compared ignoring case and spacing.
• choice — one or more of the body's options, each marked correct or not. multiple lets the reader tick several, and scores the share they got right; shuffle reorders the options for each reader.
• maths — a value, an expression or a tuple, judged by what it is worth rather than how it is written. The next section is about this kind.

Hide code

question#rise:choice{
    Which of these raise the wear rate?

    option{ A heavier load }(correct)
    option{ A faster disc }(correct)
    option{ A thicker lubricant film }
    option{ A shorter run }
}(
    multiple
    marks: 2
)

#Marking a maths answer

A maths question has one kind of answer, and expect: says what shape it takes: a number (expect: 8.1), an expression (expect: w / (L v t)), or a tuple in brackets (expect: (2016, 6.72)). The reader types into one field whatever the shape, and a preview beneath it typesets the answer as it was read, so 1/2x shows as a half times x before the reader checks it. A half-typed answer previews as much of itself as can be read, and nothing complains while the reader is typing. Pressing Check on an answer that cannot be read says why, and costs no attempt. The field grows to several lines for a long answer — Enter starts a new line, and ⌘ or Ctrl with Enter checks — and scrolls past six.

The answer is plain text, and a bar of shortcuts beneath the field types the parts that are awkward to type or to spell: roots, powers, pi, e^, ln, the trigonometric functions, abs and vec. More opens two further rows — inverse and hyperbolic functions, !, choose and perm, and the Greek letters. A function's shortcut puts its brackets round whatever is selected.

• nrt(x) is the nth root, for any whole n from 2: 2rt(x) is the square root, 3rt(x) the cube root, 4rt(x) the fourth. An odd root of a negative number is the real one, so 3rt(-8) is -2.
• n! is the factorial, and binds tighter than anything else: 2n! is 2(n!). choose(n, r) and perm(n, r) count combinations and permutations.
• pi is π and e is Euler's number, except in scientific notation: 2.81e-5 is a number.

#Equivalence

An expression is right when it takes the same value as the expectation. Both are evaluated at a fixed spread of points, and they are equivalent when every point where both are defined agrees — so x*x answers x^2, and a factorised or reordered answer is as right as the one the author wrote. The points are the same every time, so the same answer always gets the same verdict. A comparison with too few points defined on both sides, such as a logarithm sampled mostly outside its domain, is indeterminate: the reader is told the answer could not be checked, never that it is wrong.

A number is an expression with no letters, compared the same way: 8.1, 8.10 and 81/10 are one value.

#Letters

variables: lists the letters an answer may use, and is x when left out. The expectation may use no others — the compiler refuses one — and an answer using another is marked incorrect, with the letter named. Letters keep their case, so L and l are different letters.

A Greek letter is written by its name and is one letter: alpha is α, Alpha is Α, Omega is Ω, and variables: lists it the same way (variables: alpha, t). Case decides here too, so pi is the constant and Pi is the capital letter Π. A run of letters spelling a Greek name is read as that letter — xi is ξ, not x times i — so write x*i or x i for the product.

_ subscripts a letter, and a subscripted letter is a letter of its own: x_1 and x_2 are different letters, v_max and alpha_0 are letters too, and variables: lists them the same way. The subscript is the run of letters and digits after the _, so a product of two needs a space: x_1 x_2.

#Tuples and vectors

An answer with several parts is a tuple, (3, -1), or a vector, vec(3, -1). They are different answers: a tuple is a list of values — a point, a pair of solutions — and a vector is one quantity with components, previewed as a column. A tuple answers only a tuple and a vector only a vector. Either is compared component by component, in order, each component as an expression in its own right. An answer of the wrong kind or size, or a single value where several are expected, is marked incorrect and told what shape was asked for.

A vector is a value like any other, so an answer can do arithmetic with it: vec(1, 2) + vec(3, 4), 2 vec(1, 2), vec(k, t) / 2. Vectors add to vectors of the same size and scale by numbers; a product of two vectors, a vector as a power or inside a function, has no meaning here and cannot be checked. Under form: simplified, arithmetic left undone on vectors is as unfinished as it is on numbers.

Hide code

question#gradient:maths{
    With $w = kLvt$, write the gradient $\nabla w$ with respect
    to $L$ and $v$.
}[
    Each partial derivative holds every other letter constant.
](
    expect: vec(k v t, k L t)
    variables: k, L, v, t
    marks: 2
)

#Form

Equivalence cannot see how an answer is written. When the writing is the point, form: asks for one of three forms, checked after the value is found to be right.

• exact — no decimals: 1/3 or sqrt(2), not 0.333 or 1.414.
• simplified — nothing left to do: no arithmetic between two numbers except a fraction in lowest terms, and no x/x, *1, +0 or sqrt(4).
• rounded(n) — a number written to exactly n decimal places, equal to the expectation rounded to n. The expectation is written exactly and the rounding is the question's, so expect: 8.064; form: rounded(1) wants 8.1.

An answer with the right value in the wrong form is marked incorrect, and the reader is told the value was right and what form to give it in — the picture at the top of this page. A reader who has done the mathematics and written it unhelpfully has not made the same mistake as one who has it wrong, and is not told they have.

#Attempts, feedback and Show answer

Every answer is checked with Check, and each Check spends an attempt. attempts: caps them; left out, the reader can try as often as they like. The question closes when the answer is right, when the last attempt is spent, or when the reader chooses Show answer — offered on every question. A closed question takes no more answers, marks the right options or shows the right answer, and shows its detail: the feedback the author held back until then.

Hide code

question#name-it:text{
    What is a curve joining the points of equal value called?
}[
    A mapmaker draws them for height. Here they join the
    settings that wear the pin equally.
](
    expect: contour, level set, isoline
)

An option's own detail is shown as soon as it is part of a checked answer, open or closed, which is where to address the misunderstanding that option stands for.

#Reading the result in prose

A question publishes five derived attributes, and the prose reads them as it reads any other: {{#q.score}} for the marks awarded, {{#q.verdict}} for the verdict as a word, {{#q.response}} for what the reader answered, and {{#q.correct}} as yes or no. The score is a number, so a total across questions is one expression; correct and answered are true or false, and the compiler refuses them in arithmetic:

scene{
    ## What you have

    Four marks were available in this section, and you have
    {{#read-off.score + #recover.score + #rise.score}}.
}