Questions

#Where a question is written

A question is written in a scene's detail, with the canvas content. The detail is laid out in the order it is written, so a question written after a graph sits beneath it. A question is not an environment and does not take one of the scene's two environment places.

Show code

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

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)
)

Inside a cue in the detail, a question arrives on that cue's step. It is refused in the scene's body and inside an environment:

scene{
    question#name-it:text{
        What is a line of equal height called?
    }(
        expect: contour
    )
}

The reader's answers are kept under the question's #id, so a question moved to another scene keeps the answers already given to it. A question without one is refused: A question needs an id to remember the reader's answer by — write question#name:….

respond:, written in the head's slot, is the kind of answer: text, choice or maths. The body is the prompt and the detail is feedback, shown once the question closes. marks: is what a right answer scores, 1 when left out.

#Text answers

The reader types a word or a phrase. expect: lists the accepted answers, and the answer is right when it matches any one of them, ignoring case, spaces at either end and repeated spaces within. The first accepted answer is the one shown when the question closes without a right answer.

question#name-it:text{
    What is a curve joining points of equal value called?
}(
    expect: contour, level set, isoline
)

#Choice answers

The reader picks from the question's options. An option's body is the answer as shown, and correct marks a right one. A choice has at least two options, and exactly one marked correct:

question#shape:choice{
    What shape is a contour of $f(L, v) = Lv$?

    option{ A hyperbola }(correct)
    option{ A straight line }
    option{ A circle }
}

A second option marked correct is refused: Question '#shape' has 2 options marked correct; a choice without 'multiple' has exactly one.

multiple lets the reader tick any number, and needs at least one option marked correct. The score is the right options ticked less the wrong ones, as a share of the right options, never below 0, so ticking every option scores nothing. An answer between nothing and full marks has the verdict partial.

Show 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
)

shuffle shows the options in an order drawn for each reader, kept with their answer so it is the same when they return. A single-answer choice with two options and attempts: above 1 draws a warning, since the second attempt cannot be wrong.

#Maths answers

expect: is one value: a number (expect: 8.1), an expression (expect: w / (L v t)), a tuple (expect: (2016, 6.72)), a vector or a matrix. The reader's answer is judged by what it is worth, not how it is spelt: it must be the same shape as the expectation, use only the allowed letters, take the same value, and, where form: asks, be written in that form.

#Typing an answer

The reader types the answer as plain text into one field, whatever its shape. Enter starts a new line and ⌘ or Ctrl with Enter checks. Beneath the field, a preview typesets the answer as it was read, so 1/2x shows as a half times x. While the answer cannot be read, the preview shows as much of its beginning as can be. Checking an answer that cannot be read says why and spends no attempt.

A bar of shortcuts under the field inserts the text for what is awkward to type: square and cube roots, a power, pi, e^, ln, sin, cos, tan, abs, vec and mat. More opens a row of functions — the fourth root, the inverse and hyperbolic trigonometric functions, !, choose and perm — and a row of 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: 3rt(x) is the cube root. An odd root of a negative number is the real one, so 3rt(-8) is -2.
• n! is the factorial and binds tighter than a power: 2n! is 2(n!). choose(n, r) and perm(n, r) count combinations and permutations.
• pi is π and e is Euler's number, except straight after a number and before a whole number: 2.81e-5 is scientific notation.
• ×, ·, ÷, −, π, √, ² and ³ are read as their typed spellings, and ** as ^.

#Equivalence

An expression is right when it takes the same value as the expectation. Both are evaluated at the same 24 points, each letter drawn from −5 to 5, 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 fixed, so an answer gets the same verdict every time. A number is compared the same way at one point: 8.1, 8.10 and 81/10 are one value.

Where fewer than five of the points are defined on both sides — a logarithm, say, whose argument is negative over most of the range — the verdict is indeterminate: the reader is told the answer could not be checked and to try writing it another way, not that it is wrong. It spends an attempt and scores nothing.

#Letters

variables: lists the letters an answer may use, and is x when left out. An answer using another letter is marked incorrect, with the letter named. An expectation in letters other than x lists them:

question#recover:maths{
    Archard's law is $w = kLvt$. Write it for $k$.
}(
    expect: w / (L v t)
    variables: w, L, v, t
)

Without variables:, it is refused: Question '#recover' expects an answer using 'L', 't', 'v', 'w', which 'variables:' does not list (it lists x).

Letters keep their case, so L and l are different letters. A Greek letter is written and listed by its name and is one letter: alpha is α and Omega is Ω. pi is the constant and Pi the capital letter Π.

_ subscripts a letter, and the subscripted letter is a letter of its own: x_1, v_max and alpha_0 are each one letter, listed in variables: as written. The subscript runs over every letter and digit after the _, so the product of x_1 and x_2 is written x_1 x_2.

#Tuples, vectors and matrices

(3, -1) is a tuple, a list of values such as a point or a pair of solutions. vec(3, -1) is a vector, one quantity with components, previewed as a column. mat(1, 2, 3; 4, 5, 6) is a matrix written row by row: commas between the entries of a row, semicolons between rows. Each answers only its own kind, of the same size: a tuple does not answer a vector, nor a one-column matrix a vector, nor three rows of two a matrix of two rows of three. An answer of the wrong shape is marked incorrect, and the reader is told the shape asked for. A right shape is compared part by part, in order, each part as an expression in its own right.

Show 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
)

Vectors and matrices are values an answer can do arithmetic with. They add to others of the same size and scale by numbers: vec(1, 2) + vec(3, 4), 2 vec(1, 2), vec(k, t) / 2. A matrix multiplies a matrix whose rows match its columns, and a vector of that size; a square matrix takes a whole power of 1 or more. Any other combination — two vectors multiplied, a vector as a power or inside a function — cannot be read, and Check says why. So mat(2, 1; 1, 3) vec(3, -1) is a right answer to expect: vec(5, 0) unless the question asks for form: simplified.

question#product:maths{
    Multiply the quarter turn by the shear.
}(
    expect: mat(0, -1; 1, 0) mat(1, 1; 0, 1)
    form: simplified
)

#Form

Equivalence cannot see how an answer is written. form: asks for a form as well, checked once the value is right.

• exact — no number written with a decimal point: 1/3 or sqrt(2), not 0.333 or 1.414.
• simplified — no arithmetic between two numbers left undone, except a fraction of whole numbers in lowest terms; no *1, /1, +0, -0, ^1 or ^0; nothing divided by or taken from itself; no double negative; and no function of numbers that comes out whole, such as sqrt(4).
• rounded(n), for n from 0 to 10 — a number written to exactly n decimal places, equal to the expectation rounded to n, halves away from zero.

Only a number can be rounded, so rounded(n) on an expectation with letters is refused: Question '#slope' asks for a rounded answer, but its 'expect:' is an expression in x; only a number can be rounded.

An answer with the right value in the wrong form is marked incorrect and scores nothing, and the reader is told the value was right and what form to give it in.

#Checking, attempts and feedback

The reader checks an answer with Check, and each check spends an attempt. attempts: caps them, and the question shows how many are left; left out, there is no cap. The question closes when the answer is right, when the last attempt is spent, or when the reader chooses Show answer, which every question offers.

A closed question takes no more answers. A choice marks the reader's options right or wrong and the right ones they missed; a text or maths question not answered rightly states the answer. Then the question's detail is shown.

Show 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 detail is shown beneath it whenever the option is part of the last checked answer, while the question is open as well as once it closes.

A reader who returns finds their last answer in place and the question as they left it.

#Reading the result in prose

A question publishes five derived attributes, which prose reads as it reads any other:

• score — the marks awarded for the last answer, and 0 before there is one, so a total is a number from the start.
• verdict — unanswered, correct, partial, incorrect or indeterminate.
• response — the last answer as text: the words typed, the options' text joined with commas, or a maths answer as it was read.
• correct — whether the last answer was right, shown as yes or no.
• answered — whether the reader has checked an answer.

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

correct and answered are true or false, and arithmetic on them is refused: `{{#q.correct + 1}}`: `#q.correct` cannot be used in arithmetic: a `number` is required, and this is a `bool`.

Prose shows the reader's results but does not change with them. Nothing in a scene's body appears or disappears on an answer: @if is decided when the internote is compiled. What depends on the answer — the feedback, the right option, the worked solution — is the question's detail and its options' details.