papers/paperspec
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: scienting-math/1 sources and derived/math.jsonl; lode references; stress fixes

Browse Source 
Math content may say its source is in scienting-math/1's canonical TeX (form,
in no hash); derived/math.jsonl holds papermath's tree, symbols and issues,
and the validator now checks derived files. A symbol annotation names its
symbol by key; lode claim references use lode's tag and pin syntax. The zip
reader refuses entries zipfile cannot read, and checkpoint lines end in LF only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017R7sgDNvUGWY2zFPCq2JH6
This commit is contained in:
alexmandClaude committed 2026-10-17 06:44:28 -04:00
1 parent 8b5ee87275
commit 17880686fa
40 files changed
+750 -63
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

spec/09-figures-tables-equations.md
+78 -1
View File
@@ -34,4 +34,81 @@ For people, a cell can be shown as "Table 2, row CT–CT, column K_r" from its h
An equation keeps its source as written, `tex` from a conversion or `typst` from a draft, and its printed number as its `label`, so numbering never collides with a renderer's own.
An equation that the source numbers line by line (Eq. 3a) has `equation-line` children, each with its own label and source.
MathML is derived by a pinned tool and recorded, with the tool's name and version, in `derived/mathml.jsonl`.
A converter that respells TeX in the standard form of [9.4](#94-the-math-form) stores the respelled source and says so with `form` beside it ([3.7](03-nodes.md#37-math-forms)); the source as written stays in the witness.
MathML is derived by a pinned tool and recorded, with the tool's name and version, in `derived/mathml.jsonl`, and the form's reading of each formula in `derived/math.jsonl` ([12.7](12-package.md#127-derived-files)).
## 9.4 The math form
`scienting-math/1` is the standard form of a formula in a paper: one canonical TeX spelling, a tree read from it, a key for each symbol, and the issues a reader should look at.
A converter writes a package's equations and math runs in it, a reader renders and searches it, and a claim store reads a paper's equations and its own claims through it, so the two can be matched.
papermath is its reference implementation, and what papermath computes is what the form says; this section states what the specification relies on.
The identifier names a spelling of formulas, not a file format, so [registry/formats.json](../registry/formats.json) does not list it; its readings travel in a package's `derived/math.jsonl`.
The form reads TeX only.
**Canonical TeX** respells and never reinterprets, so it renders as the source did apart from presentation:
1. Unicode NFC, and a math character a converter handed over becomes its command: `−` is `-`, `≤` is `\leq`, `α` is `\alpha`.
2. Space is dropped, except inside text and where a command needs one before a letter (`\sin x`).
3. One spelling per meaning: `\le` is `\leq`, `\dfrac` and `\tfrac` are `\frac`, `\textrm` is `\text`, `x^{\prime}` is `x'`.
4. Presentation is dropped: `\displaystyle` and the other styles, `\big` and its sizes, `\color`, and `\left` and `\right` around ordinary delimiters.
5. Every argument and script is braced, and on one base the subscript comes first: `x_i^2` is `x_{i}^{2}`, `\frac12` is `\frac{1}{2}`.
6. `\tag` is lifted out as the label, and `\label`, `\nonumber` and `\notag` are dropped.
7. An environment goes by one name: `align`, `split` and `multline` are `aligned`, `equation` and `gather` are `gathered`.
8. A command outside the form's vocabulary is kept as written and reported.
Spelling a canonical source again gives it back unchanged.
**The tree** is the canonical TeX read as JSON.
A node is an array whose first item is a string, its kind; its other items are its parts: strings, null for a part that is absent, nodes, and groups, which are arrays whose first item is not a string.
Brackets group and leave no node.
| Kind | Parts | Is |
| --- | --- | --- |
| `num` | The digits | A number as printed, a decimal comma read as `.`. |
| `sym` | The key | A symbol. |
| `text` | The words | Words in the formula. |
| `const`, `oper` | The command | A constant, such as `\infty`, or an operator, such as `\partial`. |
| `dots`, `empty` | None | An ellipsis; nothing. |
| `add` | The terms | A sum, in which a subtracted term is a `neg` node, ± a `pm` and ∓ an `mp`, each with one part. |
| `mul` | The factors | A product, by juxtaposition or `\cdot`. |
| `times`, `div`, `op` | Two operands, after the operator's command for `op` | `\times`; `/` or `\div`; any other binary operator. |
| `frac`, `binom`, `sqrt`, `root` | Numerator and denominator; the radicand, after the index for `root` | Fractions, binomials and roots. |
| `pow`, `sub`, `prime`, `fact` | The base, and the script for `pow` and `sub` | Scripts, primes and factorials on what is not a symbol. |
| `apply` | The function's command, its argument, and its subscript if any | A named function: `\cos(x)`, `\log_{2} n`, `\max_{i} x_{i}`. |
| `lim` | The command, what is under it, the body | `\lim`, `\liminf` and `\limsup`. |
| `sum`, `prod`, `coprod`, `int`, `iint`, `iiint`, `oint`, `bigcup`, `bigcap` | The lower limit, the upper limit, the body | A big operator, whose body runs to the next sign outside brackets. |
| `abs`, `norm`, `angle`, `floor`, `ceil`, `braces` | The inside | A fence. |
| `interval` | The opening and closing brackets, the inside | Brackets that do not match, as in `[0, 1)`. |
| `rel` | Operands with a relation between each two | A relation or a chain; a continued line starts with null. |
| `list` | The formulas | Formulas side by side, at `,`, `;`, `\quad` or `\qquad` outside brackets. |
| `lines` | The lines | The lines of an `aligned` or `gathered` block. |
| `cases` | A group of value and condition for each case | Cases, a condition being null when there is none. |
| `matrix` | The environment, then a group of rows, each a group of cells | A matrix or array. |
| `opaque` | Canonical TeX | What the tree does not read. |
A tree with no `opaque` node is complete.
A later minor version of the form may add a kind, and a consumer that meets a kind it does not know reads that node as it reads `opaque`; `math.schema.json` therefore takes any lowercase kind, and its description lists these.
**A symbol** is a base, which is a letter, a Greek letter, or a font or accent command on a group (`\mathbf{F}`, `\hat{H}`), with any subscript, any superscript that names rather than raises (`R^{*}`, `A^{\dagger}`, `E^{\text{LJ}}`), and primes.
A text group alone is a symbol too, unless it holds several words, is a condition in `cases`, or is the set under a big operator.
A symbol's key is its canonical TeX with `\mathrm` spelled `\text`, `\ast` spelled `*`, `\prime` spelled `'`, and no space inside text: `K_r` and `K_{r}` have the key `K_{r}`, and `r_{\mathrm{eq}}` has the key `r_{\text{eq}}`.
The key is the one a lode claim store gives a symbol, so a symbol in a paper and the same symbol in a claim have one key, and a `symbol` annotation names its symbol by it ([18.4](18-layers.md#184-bodies)).
**Issues** never stop the reading; each is `{code, message, at}`, with `at` the canonical TeX it is about.
| Code | Means |
| --- | --- |
| `unbalanced` | A brace, bracket or fence does not close; with a brace, the whole formula is one `opaque` node. |
| `unknown-command` | A command outside the vocabulary, kept as written. |
| `label-or-power` | A superscript that may be a label written without `\text`, such as `E^{LJ}`, read as a power. |
| `script-on-group` | A script on a braced group rather than on a symbol. |
| `opaque` | A part the tree does not read. |
| `infix-fraction` | `\over`, `\choose` or `\atop`, rewritten as `\frac` or `\binom`. |
A later minor version may add a code.
**In a package**, the canonical source is the equation's or the math run's `source`, with `form` beside it ([3.7](03-nodes.md#37-math-forms)), and the rest is derived: one line of `derived/math.jsonl` per formula a pinned tool read, `{node, run, tool, form, tree, symbols, complete, issues, label?}`.
`run` is the index of the math run among the node's runs, or null for an equation or equation line, as in `derived/mathml.jsonl`; `symbols` lists the keys in the order the formula first writes them; `label` is the label the tool lifted from a `\tag`, omitted when the source has none, as a canonical source never does.
The schema is `math.schema.json`.
A validator checks what it can without implementing the form: that each line names a formula of the package (`doc.derived.node`), and that the formula is TeX, `complete` is true exactly when the tree has no `opaque` node, and `symbols` holds each `sym` key of the tree once (`doc.derived.math`).
`fixtures/packages/hale2026harmonic-damb/derived/math.jsonl` holds papermath's reading of the example's equation, of a math run that is one symbol, and of the run `_2` of "H₂O", which the tree cannot read alone.