Callouts

#Prose around a callout

definition, note, example and task are narrative content: a scene's body takes them, and its detail refuses them with a content-policy error. Each is an interruption of the prose, and the prose says why it is there. A callout that opens a scene, or two stacked with nothing between them, moves the reader from aside to aside with no argument connecting them. A run of callouts is a scene whose argument has been replaced by its asides.

task is covered with the question it sets, in Questions & tasks.

#Definition and the glossary

term: is the implicit attribute — the word being defined — and the body is the definition. A map's glossary gathers the definitions from every internote in it, so a definition is read by people who never saw the scene it came from, beside definitions written by other authors. Both judgements below follow from that.

#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 glossary 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. Someone meeting the word cold needs its category before its content. The category is the grammatical head of a sentence that continues as prose, not a label before a colon:

• Linking by a fixed rule over the comparison vector. A gerund: 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)$ defines it.

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

#Which terms get one

One test, held across the document, decides which terms get a definition. Every term the document relies on later, defined where it is first used is a workable one. The document's own central concept is defined under it too: it is the term most likely to be looked up, and being obvious to the author is no reason to leave it out of the glossary. A body stays glossary-length — a sentence or two, the equation where the concept is mathematical — because it is read in a list.

#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 boxing it as 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 boxed paragraph, and the box promises a specificity the content does not deliver.