feat: the page says which of pos(t) and t is the position

[FBumann]

Stacked on #31, which is the base branch here — the diff is one commit. Retarget to main once #31 lands.

What this changes

#31 fixes the ambiguity in the file. This fixes it in the page, where it survived: position(snapshot) == 0 prints pos(t) = 0 and snapshot >= 3 prints t \ge 3, both an index-ish thing against a small integer, with nothing saying which way the unmarked one goes. And the reader's own convention says the opposite of this language's — papers write their sets as {1, …, T}, where the index is the ordinal and nothing needs marking — so a reader recovers a different model from the one the file holds, which is the failure #31 names.

The mark stays on the position: a coordinate is what a dimension denotes everywhere else in the language, and a position is derived from whichever index resolution produced, so the derived thing is what gets converted in view. What is added is the legend that makes the unmarked side readable, plus two corrections to what a position prints.

pos is introduced where it is used, gated the way the translation notes are — one note for the symbol, one for the grouped form, one for the size, each only where that form printed:

$\mathrm{pos}(t)$ denotes where index $t$ sits along its dimension's own order — the order shift walks, not the order labels sort in — counted from $0$. The index itself stays the coordinate, so $t$ compares against labels and $\mathrm{pos}(t)$ against positions.

A group rides a subscript, $\mathrm{pos}_{\mathrm{season_of}(t)}(t)$. As a second argument it sat exactly where the first one's integer sits and said nothing about "within" — the same shape an edge fill has, which already rides its translation as a subscript.

A position counted from the end prints against the size: $\mathrm{pos}(t) = \lvert\mathcal{T}\rvert - 1$, and $\lvert\mathcal{T}_{\mathrm{season_of}(t)}\rvert - 1$ where the count is grouped. The order runs 0 to |T| - 1, so -1 printed as itself was an equation asserting a position the legend had just ruled out — Python's index sugar, read as math.

A dimension compared against a number names its coordinates in the set legend: index t — snapshot (int coordinates). That is the one comparison a reader can take for a position; every other coordinate prints as prose and could not be.

Positions stay 0-based on the page, as in the file, so a clause reads off one and writes into the other.

Why not the alternatives

Considered and rejected on the record, so they are not rediscovered later:

• Marking both sides (coord(t) >= 3 beside pos(t) = 0) taxes the common case, and contradicts the reason the conversion moved left in feat: position(dim) replaces index(dim, i), converting on the left #31: only one side should ever be marked.
• A typographic distinction (font, accent, \hat t for ordinals) is invisible at body-text size, does not survive plain text, and all three formats would have to agree on it.
• Inverting the page — letting t range over {1..|T|} per the paper convention and printing values as \tau_t — is the only coherent inversion, and it is nearly free everywhere except a value comparison. It costs the symbol correspondence between page and file, which is what feat: position(dim) replaces index(dim, i), converting on the left #31 says it is protecting.
• Order relations (t \succ t_1 with the set enumerated in the legend) are more conventional than pos(t) > 1, but they are a second surface for one construct. The order relation now appears only in the legend line, where it says what pos counts along.

Scope

|·| is a Format method rather than an OPERATOR_NAMES entry: that vocabulary is infix spellings, and the Typst gate compiles every one of them between two operands. Three formats spell it (\lvert…\rvert, abs(…), LaTeX's via Markdown).

The golden model gains last, the from-the-end pair it had no case for — which is what holds the new arms of the walk to output someone has read, under the fixture's three censuses. docs/reference/notation.md is regenerated.

Checks

pixi.sh is unreachable from this environment, so the gates ran on a 3.13 venv at the versions pixi.toml pins, plus prettier@3.9.3 and typos fetched directly: 377 passed (including the three Typst compile tests, which cover abs(cal(T)) and the subscripted pos — they skip without the bindings), ruff check and format clean, pyrefly 0 errors, prettier clean on the touched files, typos clean, reuse lint compliant.

One thing found on the way, not fixed here

tools/notation.py cannot run end-to-end in this repo: its PIECEWISE map points at four example models that stayed behind in fluxopt/lpspec at the extraction (#17), so _curves() raises FileNotFoundError. Nothing runs --check in tests or CI — here or upstream — so the page has been drifting from the models it claims to be generated from with nothing to say so. Its docstring also cites tests/test_docs_site.py, which does not exist here.

For this PR the fixture-derived half was regenerated normally and the curve rows carried over verbatim, with the one substitution this change makes to them applied (pos(b) = -1 → pos(b) = |B| - 1). All four models render clean against this repo's language unchanged, so porting them back plus a five-line --check guard is the fix — worth its own PR.

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34190920 | 📁 Comparing 24b0e55 against latest (05c7219)

  🔍 Preview build  

40 files changed · ± 37 modified · - 3 deleted

± Modified

• 404.html
• index.html
• CHANGELOG/index.html
• contributing/index.html
• installation/index.html
• about/ceiling/index.html
• about/what-counts-as-language/index.html
• reference/language/index.html
• reference/notation/index.html
• reference/typeset/index.html
• and 27 more...

- Deleted

• examples/index.html
• examples/dispatch/index.html
• examples/operators/index.html

[FBumann]

Folded into #31 rather than reviewed as a stack: it rewrites lines #31 itself writes — walk.py, the three format modules, notation.md and all four goldens — so a reviewer of the stack would read the same generated lines change twice, and #31's own body already promises this work ("the typeset follows"). One idea, reviewed once.

The commit is on claude/new-session-divgg4 unchanged (b583803, a fast-forward from 937b2ee after rebasing onto #31's move to the new main). This PR's body has been merged into #31's description, the four rejected alternatives included.

Closing — nothing here is abandoned.

---

Generated by Claude Code