Callouts

#Prose before a callout

The four callouts are narrative content: definition, note, example and task are legal in a scene's body and in no canvas. Each has one job, and each is introduced by the prose it interrupts: at least a sentence stands before the first callout in a scene, and two never stack with nothing between them. A run of callouts is a scene whose argument has been replaced by its asides.

#definition and the glossary

term: is the implicit attribute — the word being defined — and the body is the definition. Terms are collected into glossaries across many documents, so a definition is read by people who never saw the scene it came from, beside definitions written by other authors. Two rules follow from that, and both are about the first few words.

#A term that survives on its own

The term names its own subject. Divisibility is a term; Measures is a word the scene happened to be using, and in a list it is either meaningless or somebody else's. A term is rich text, so notation is part of it where the notation is the name — $\epsilon$-$\delta$ continuity.

#Naming the kind of thing first

The body opens by naming what kind of thing the term is — a method, a theorem, a probability, a relation, a rule, a quantity, a data structure, a task. Someone meeting the word cold needs its category before its content. It is named as the grammatical head of a sentence rather than as a label before a colon, and the sentence continues as prose:

• Linking by a fixed rule over the comparison vector. — a gerund, so the reader is never told what kind of thing this is.
• A linkage method: a fixed rule over the comparison vector. — a tag welded to a fragment.
• A linkage method that applies a fixed rule to the comparison vector, requiring a set combination of agreements on every pair.

An opening formula fails the same test from the other side. $ax + by = \gcd(a, b)$ for some integers $x$ and $y$ is the statement itself; a theorem stating that for any integers $a$ and $b$ there are integers $x$ and $y$ with $ax + by = \gcd(a, b)$ is a definition of it.

definition{
    A quantity that stays the same under a given transformation.
}(
    term: Invariant
)

#What earns a definition

One threshold, held across the document. Every term the document relies on later, defined where it is first used is a workable one. The document's own flagship concept is defined under it too — it is the term most likely to be looked up, and being obvious to the author is not a reason to leave it out of the glossary. Bodies stay glossary-length: a sentence or two, the equation where the concept is mathematical, and no editorial tail.

#note as an aside

A note holds something set aside from the line of argument: a piece of history, a related result, a warning about a case the document does not cover. The test is whether a reader who skips it loses the thread. Content that is the next step of the argument is a paragraph, and putting it in a note tells the reader they may skip the argument.

#example as a worked case

An example works an instance: values in, the steps, the result. An example that re-explains the idea in other words is a paragraph that has been boxed, and the box is making a promise about specificity the content does not keep.

#task and its held-back half

A task poses an exercise. Its optional detail is the half held back — a hint or the solution — rendered inside the callout and collapsed until the reader asks for it, so a task with an answer keeps the answer out of sight rather than out of the document.

task{
    Show that the residuals of the quadratic fit sum to zero.
}[
    Every least-squares fit with an intercept term does: the normal
    equation for the intercept IS that sum set to zero.
](
    title: Why the intercept forces it
)