Mathematics, and what the document knows

AsciiDoc was chosen over Markdown for one reason: it has notation for mathematics that is part of the language rather than bolted onto it.

Inline, written stem:[...], it sits in a sentence: the Pythagorean relation \(a^2 + b^2 = c^2\) reads as prose. Set apart, it takes a block of its own:

\[\sum_{k=1}^{n} k = \frac{n(n+1)}{2}\]

The parser does not read that notation. It carries it through literally, the same way a code span is carried through literally, and hands it to whatever renders mathematics on the page. Reading it would mean having opinions about a language it has no business having opinions about.

The document answers for itself

Rendering mathematics in a browser costs a script and a stylesheet, and most pages hold none. So the question is which pages need them.

The wrong way to answer it is to make the author declare it, with a :math: true attribute at the top of every page that has an equation in it. Authors forget. Then the page is wrong, and the fix is remembering.

The right way is to ask the document, because the document already knows:

(anchor:page-uses-stem-p page)

The page holds mathematics or it does not, and the tree can say which without anyone declaring anything. The same principle governs the excerpt, the title and the tags. Where a document can answer a question about itself, it is asked.

Where anchor stops

anchor stops at the answer. It ships no math renderer, because it ships no JavaScript at all — that is a stated non-goal, not an omission.

So this page's equations are notation in a stem element, and what to do about them belongs to a layout. That division is the honest one: the generator knows what the document contains, and the person who chose the typeface decides what to load.