Statements and admonitions

LibreTimes Markdown has two families of labelled block, and they look alike in the source: :::theorem and :::warning are both a fence, a name and a body. On the page they are different things, and the difference is the point. A statement is part of the mathematics. An admonition is the author speaking to the reader about the text. This page explains why they are kept apart, why only one of them is numbered, and how to tell which one a passage needs.

Two kinds of labelled text

A mathematics text has always had two voices. One is the theory itself: definitions, theorems, lemmas, proofs, examples, remarks. Each is a unit a reader looks for, cites and checks, and each has carried the same typography for over a century: a bold label at the start of a paragraph, the name of the result in parentheses, the statement of a theorem in italics, a proof ending with a tombstone.

:::theorem[Lagrange]
The order of a subgroup divides the order of the group.
:::
 
:::proof
The cosets of the subgroup partition the group, and all have its size.
:::

The other voice is editorial: "you can skip this on a first reading", "this is the faster way", "check your units before you go on". It is not part of the theory, and a printed book sets it apart in a margin note or a box.

:::tip
Read the proof of the lemma only after the theorem; it uses nothing else.
:::

Statements are the first voice and admonitions the second. The full lists are in the syntax reference.

Run-in or boxed

A statement renders run-in: its label is the first words of its first line, and the text continues on the same line. It is a paragraph of the argument with a label in front of it, so it sits in the flow of the text with no frame. A reader skimming for Theorem finds it by the bold word, as in any printed text.

An admonition renders as a box: a coloured frame with a title bar holding the kind's name. The frame says "this is not the argument", which is exactly what an aside should say. It also means admonitions cost something: every box pulls the eye, so a page with many of them reads as a page of interruptions.

No kind is both

note, warning and caution are admonitions, never statements. The two families share no name, and that rule is there because breaking it broke pages. When the read side and the editor once disagreed about which family :::note belonged to, a published note printed its label twice, and a warning built its box twice, one inside the other. A word that names an aside is an admonition, and a mathematical remark is a :::remark.

Why statements are numbered and admonitions are not

A number exists to be cited. "By Theorem 3.2" sends a reader to one place in the text, in a lecture, in a paper that cites the lecture, in an exam that cites the course. Every statement kind is a unit that can be cited, so statements carry numbers.

Nobody cites "Tip 3". An admonition is read where it stands or not at all, so a number on it would be noise, and it gets none.

Today a statement's number is the one you give it. Automatic numbering is not yet on the published page, so a theorem with no number is labelled Theorem. and one with a name Theorem (Lagrange). A source's own numbering is kept with number=, or with a number in the label slot:

:::theorem{number=3.2}
Every bounded monotone sequence converges.
:::
 
:::problem[4]
Prove that $\sqrt{2}$ is irrational.
:::

Write a theorem and its proof shows how to number a whole set of results and refer to them by anchor.

Labels follow the document's language

You always write the kind in English, and the page prints its label in the document's language: a :::theorem in a Russian lecture is Теорема, a :::warning in a German one Warnung. The reader's interface language does not change it, because the label is part of the text: a Russian lecture read by someone with an English interface is still a Russian lecture, and a citation of "Теорема 2" must find the word it names.

Two escape hatches keep the vocabulary closed without boxing anyone in:

• label="…" replaces the printed word for one block and keeps everything else about the kind. :::proof{label="Sketch of proof"} still ends with ∎; :::warning{label="Before the exam"} keeps the warning's colour.
• :::statement[Proposition] is a statement whose label is your own word. Neither is translated, because a word you chose is part of what you wrote.

Why the families are closed

There is no :::proposition and no :::question. A new kind would have to be taught to the editor, to the import from LaTeX and Word, to the labels in every language and to every export, and a document using it would break the day one of them lagged. A label on an existing kind gives the same page with none of that: :::theorem{label="Proposition"} prints Proposition and behaves as a theorem everywhere else.

The two families map to two things in LaTeX as well. Statements are amsthm environments, which is why a .tex file's theorems and proofs import as statements. Admonitions have no counterpart there, and a Word document's Note or Warning style imports as an admonition.

Choosing one

Ask what the reader will do with the passage.

Two mistakes are common. A definition written as a :::note loses its label, its place in the argument and its LaTeX counterpart. And an aside written as a :::remark reads as part of the theory, so a reader who skips remarks on a first pass skips your warning as well.