Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ ISO-style specifications for the Plurimath stack, organized as **series with par
- Part 4 — Evaluation (bindings, propagation, Monte Carlo, conformity decisions; Annex A: the H.1.7 second-order derivation)
- **asciimath** — the legacy input language: Part 1 the language; Part 2 extension channels
- **pma** — the featureful strict input language: Part 1 the language
- **PM LaTeX** (PM 1007) and **PM UnicodeMath** (PM 1008) — the LaTeX and UnicodeMath notations Plurimath reads and writes, each with its grammar artifact checksums pinned

The companion **UnitsML** series (units, quantities, conversions, the register, XML) lives in [unitsml/docs](https://github.com/unitsml/docs). Dependency direction: asciimath/pma → math model → UnitsML semantics; the only inter-series seams are the unit-expression content grammar (UnitsML 6), the units semantics (UnitsML 4/5), and the conformance corpora (UnitsML 8).

Expand Down
2 changes: 2 additions & 0 deletions metanorma.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ metanorma:
- sources/pm-1004/document.adoc
- sources/pm-1005/document.adoc
- sources/pm-1006/document.adoc
- sources/pm-1007/document.adoc
- sources/pm-1008/document.adoc

collection:
organization: "Plurimath"
Expand Down
51 changes: 51 additions & 0 deletions sources/pm-1007/document.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
= The PM LaTeX notation
:docnumber: 1007
:edition: 1
:ref-docnumber: PM 1007:2026(E)
:copyright-year: 2026
:revdate: 2026-11-10
:language: en
:script: Latn
:title: Plurimath specifications -- The PM LaTeX notation
:doctype: standard
:status: draft-standard
:committee: Plurimath
:committee-type: technical
:mn-document-class: ribose
:docfile: document.adoc
:mn-output-extensions: xml,html,doc
:local-cache:

include::sections/00-foreword.adoc[]

include::sections/00-introduction.adoc[]

include::sections/01-scope.adoc[]

include::sections/02-normrefs.adoc[]

include::sections/03-terms.adoc[]

include::sections/04-conventions.adoc[]

include::sections/05-artifact.adoc[]

include::sections/06-preparation.adoc[]

include::sections/07-structure.adoc[]

include::sections/08-model.adoc[]

include::sections/09-plurimath.adoc[]

include::sections/10-uncertainty.adoc[]

include::sections/11-errors.adoc[]

include::sections/12-conformance.adoc[]

include::sections/90-annex-a.adoc[]

include::sections/91-annex-b.adoc[]

include::sections/98-bibliography.adoc[]
30 changes: 30 additions & 0 deletions sources/pm-1007/sections/00-foreword.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
== Foreword

=== General

This document is the seventh document of the Plurimath specifications series. It specifies the LaTeX math notation that Plurimath reads and writes: the grammar that accepts it, the typed model the grammar produces, what Plurimath makes of that model, what LaTeX output loses, and the corpora that check all of this.

The notation is the LaTeX math that Plurimath read when its LaTeX grammar was still part of the `plurimath` gem. The grammar now lives in the `latexmath` gem and is carried by a checksummed artifact (clause "The grammar artifact"). Where this document and the implementation disagree, the disagreement is a defect in one of the two.

This document is the PM LaTeX document of the specification set tracked in https://github.com/plurimath/plurimath/issues/525[plurimath#525].

=== Documents in the series

.Documents in the series
[cols="1,3,2", options="headers"]
|===
|Number |Title |Subject

|1001 |Math model |The formula tree, the node classes, the registry, the rendering surfaces
|1002 |Uncertainty model |The uncertainty node, its categories, its encodings
|1003 |Format interfaces |The readers and writers per format
|1004 |Evaluation |Numeric evaluation of trees
|1005 |The AsciiMath notation |The complete AsciiMath surface
|1006 |The pma notation |The featureful notation
|1007 |The PM LaTeX notation |This document: the LaTeX math notation
|1008 |The PM UnicodeMath notation |The UnicodeMath notation
|===

=== Maintainers

This document is maintained by the Plurimath project at https://github.com/plurimath/plurimath.
7 changes: 7 additions & 0 deletions sources/pm-1007/sections/00-introduction.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
== Introduction

Plurimath reads LaTeX math, not TeX. There is no macro expansion, no `\def` and no catcode handling. The grammar is a fixed set of commands, symbols and environments. A formula is a sequence of terms; each term can carry a subscript and a superscript; some commands take arguments in braces or brackets.

The grammar is not a LaTeX validator. It accepts what Plurimath accepted at the pinned commit, including some forms that LaTeX itself would not, and it refuses what Plurimath refused. This document records that behaviour so that it can be implemented again, in another runtime, and checked against the same corpora.

The document has two halves. The first describes the notation the grammar accepts and the model it builds; its content is taken from the `latexmath` gem. The second describes what Plurimath does around the grammar: reading, writing, measurement results, loss, errors; its content is taken from the `plurimath` gem.
40 changes: 40 additions & 0 deletions sources/pm-1007/sections/01-scope.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
== Scope

=== General

This document specifies:

* the preparation of the input before the grammar runs;
* the structure of a formula and the constructs the grammar accepts;
* the typed model each construct becomes;
* the reading of LaTeX into the formula tree of PM 1001 and the writing of the tree as LaTeX;
* the writing of measurement results as LaTeX and what is lost;
* the errors at the reading boundary;
* the artifact the grammar is generated into, with its checksums;
* conformance, and the corpora that enforce it.

This document does not specify: the formula tree (PM 1001), the uncertainty node (PM 1002), the general reader and writer interfaces (PM 1003), the macro language of TeX, or the reading of measurement results from LaTeX, which is proposed and not implemented (clause "Status").

=== Relationship to the series

.Relationship to the series
[cols="1,3", options="headers"]
|===
|Document |Relationship to this one

|1001 Math model
|the tree the reader builds and the writer starts from

|1002 Uncertainty model
|the node whose LaTeX form is the plain visible layout of clause "Measurement uncertainty"

|1003 Format interfaces
|the general reader and writer interfaces; this document is the LaTeX notation they refer to

|1005 The AsciiMath notation
|the notation used in the examples to show the tree
|===

=== Audience

Implementers of a LaTeX reader or writer for the Plurimath tree, and maintainers of the `latexmath` grammar and its artifact.
10 changes: 10 additions & 0 deletions sources/pm-1007/sections/02-normrefs.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
[bibliography]
== Normative references

The following documents are referred to in the text.

* [[[pm1001,nofetch(PM 1001 (math model))]]] of this series.
* [[[pm1002,nofetch(PM 1002 (uncertainty model))]]] of this series.
* [[[pm1003,nofetch(PM 1003 (format interfaces))]]] of this series.
* [[[latexmath-docs,nofetch(latexmath docs/latex.adoc)]]] — the notation page of the `latexmath` gem, at the commit named in the clause "The grammar artifact".
* [[[latexmath-artifact,nofetch(latexmath grammar artifact)]]] — `grammars/latex.parg` and the files generated from it, with the checksums of the clause "The grammar artifact".
24 changes: 24 additions & 0 deletions sources/pm-1007/sections/03-terms.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
== Terms and definitions

For the purposes of this document, the following terms and definitions apply.

=== grammar
the PARG grammar `grammars/latex.parg` of the `latexmath` gem, generated from the LaTeX grammar of Plurimath at the commit named in the clause "The grammar artifact"

=== artifact
the compiled form of the grammar, `artifacts/latex.json`, with its bindings and the checksum file `artifacts/latex.checksums.txt`

=== rewritten text
the copy of the input that the grammar reads, produced by the preparation steps

=== typed model
the tree of `Latexmath::Model` classes that parsing returns; `Latexmath::Model::Document` is its root

=== capture
a named part of a grammar rule; the captures give the fields of the typed model

=== mapper
the part of the `plurimath` gem that turns the typed model into a formula tree, `Plurimath::Latex::Mapper`

=== construct
a form of the notation, such as a script, a fraction or an environment
13 changes: 13 additions & 0 deletions sources/pm-1007/sections/04-conventions.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
== Conventions

=== General

LaTeX text is shown verbatim in monospace. Model classes and fields are named as the `latexmath` gem names them. Formula-tree nodes are named in the terms of PM 1001. AsciiMath is used in examples to show a formula tree, in the notation of PM 1005.

=== Provenance of the content

The notation clauses are taken from the `docs/latex.adoc` page of the `latexmath` gem, and the clauses on reading, writing, loss and errors from `docs/latex.adoc` of the `plurimath` gem. The exact commits are named in the clause "The grammar artifact". Examples marked as produced were run at those commits.

=== Status

Each part of the behaviour is stated as implemented or proposed. A part that is not stated as proposed is implemented at the pinned commits.
38 changes: 38 additions & 0 deletions sources/pm-1007/sections/05-artifact.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
== The grammar artifact

=== The artifact pattern

The grammar of this notation is carried by a checksummed artifact, in the pattern of the asciimath and pma artifacts: the grammar source is committed together with the files generated from it and their checksums, and consumers verify the checksums before use. The artifact bytes are authoritative. This document states the notation; the artifact makes it runnable; the two are not copied into each other. Where this document quotes the grammar, the quotation is a statement of what the pinned artifact accepts, and it is valid only for the checksums below.

=== Pinned sources

.Sources of this document
[cols="2,4", options="headers"]
|===
|Item |Pin

|`latexmath` repository |https://github.com/plurimath/latexmath, commit `70b0f48dec837647be9e06efa4a675ac7dce2629`, gem version 1.0.0
|`latexmath` notation page |`docs/latex.adoc` at that commit
|origin of the grammar |the LaTeX grammar of Plurimath at commit `e7ab4a5186c9be96f62d670574bc2c72f9365ad4`
|`plurimath` repository |https://github.com/plurimath/plurimath, commit `f04c688fbfaa6ccdf019af03b34ec0fc0d229226`
|`plurimath` format page |`docs/latex.adoc` at that commit
|testsuite |https://github.com/plurimath/plurimath-testsuite, commit `337262eda0483ceaa43a02cc52362c5b721e5eb3`
|===

=== Pinned checksums

.Checksums of the artifact (`artifacts/latex.checksums.txt`, edition 2, compiler 1.3.134)
[cols="3,5", options="headers"]
|===
|File |SHA-256

|`grammars/latex.parg` |`f0694ce57b0f3e99e536b3749eb6b9c56570e4311b1d7aca0047c9e25a668cbf`
|`artifacts/latex.json` |`7ec430367616556f1ca163ced6d7db10af00298ec5ac527e942fbf99afdc7590`
|`model/latex.lml.json` |`b39479e2751d37c2b4d2d42f7dd630173d0360d1e9b03c1d035bd24f7f7c0f84`
|===

The artifact checksum recorded by the compiler is `sha256:a54e622526283de67b9a3d0dbb532558c75b296b5644e88f5f99ca24685ce82d`, and its source hash is the checksum of `grammars/latex.parg` above. The checksums of the four runtime bindings (Ruby, Rust, TypeScript, Python) are in the same checksum file. The three file checksums above were recomputed from the files at the pinned commit when this document was written.

=== Rule for the excerpts

An excerpt of the grammar in this document is normative only as a statement about the pinned artifact. A change of the grammar changes the checksums; an implementation then makes a different claim (clause "Conformance"), and this document is revised to the new pin. The grammar is never edited by hand in this document.
13 changes: 13 additions & 0 deletions sources/pm-1007/sections/06-preparation.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
== Preparation of the input

The grammar reads a rewritten copy of the input, not the input itself. The steps are specified in full in the parser contract of the `latexmath` gem. In short:

* Spaces are removed, except a space after a backslash (`\ `), and newlines are removed.
* Every non-ASCII character, and the characters `<`, `>` and `'`, become hexadecimal character references such as `&#x3b1;`. `&` and `"` stay as they are.
* The contents of `\text{...}` and `\mbox{...}` are put back exactly as written, spaces and non-ASCII characters included.

So `\alpha` and `α` reach the grammar as different text (`\alpha` and `&#x3b1;`), and both are symbols. Spaces never separate terms: `ab` and `a b` are the same input.

=== The decimal marker

The decimal marker is `.` unless the caller passes `decimal: ","` or `decimal: "٫"`. The grammar has one entry for each marker, and only the chosen marker is read as part of a number.
65 changes: 65 additions & 0 deletions sources/pm-1007/sections/07-structure.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
== Structure of a formula

The root rule is `expression`.

* An expression is one or more terms in a row. `{a \over b}` and `a \over b` divide the terms before `\over` by the terms after it (captures `dividend` and `divisor`).
* A term (rule `sequence`) is one of the constructs below. When none of the special forms applies, it is an operand, optionally with scripts.
* An operand (rule `intermediate_exp`) is a single symbol, number or command, a group in braces `{...}`, or a bracketed group: an opening bracket, an optional expression and a closing bracket. The closing bracket may be missing; the model then records it as absent.

=== Scripts

`_` gives a subscript and `^` a superscript. Both may be given, in either order. A script is one operand: one letter, one number, one command or one group. So `x^ab` is `x` with superscript `a`, followed by `b`, while `x^10` has the superscript `10`, because a digit string is one number.

.Scripts and their model classes
[cols="2,3", options="headers"]
|===
|Form |Model

|`a_b` |`Base` with `subscript`
|`a^b` |`Power` with `supscript`
|`a_b^c`, `a^c_b` |`PowerBase` with `subscript` and `supscript`
|===

Large operators `\sum`, `\prod`, `\int` and `\oint` take their limits as scripts and the operand after them as `third_value` (class `TernaryClass`). A function name followed by `\limits`, such as `\max\limits_{i}`, is the `limits` form.

=== Fractions and other two-argument commands

These commands take two arguments (capture `binary`): `\frac`, `\binom`, `\overset`, `\underset`, `\stackrel`, `\color`, and also `\lim`, `\log` and `\inf`, which take their scripts as arguments. `\sqrt{x}` is a square root; `\sqrt[n]{x}` takes the index in brackets as `first_value`. `\rule` takes up to three optional arguments. `\bmod`, `\pmod` and `\mod` stand between two operands (capture `under_over`).

=== One-argument commands

Function names and accents with one argument (capture `unary_functions`):

`\arccos \arcsin \arctan \bar \cancel \cos \cosh \cot \coth \csc \ddot \deg \det \dim \dot \exp \gcd \hat \hom \ker \lg \liminf \limsup \ln \max \min \overline \phantom \sec \sin \sinh \sup \tan \tanh \tilde \underbrace \vec`

The argument may be omitted, may be a bracketed operand or may be a `\left ... \right` group. Each of these may also carry scripts.

`\overbrace` takes its argument and the label above it (capture `underover`).

=== Fonts and text

Font commands take one argument. The model keeps the command name as the text field `fonts` next to the argument:

`\Bbb \bf \cal \displaystyle \mathbb \mathbf \mathbfit \mathbold \mathcal \mathds \mathfrak \mathit \mathrm \mathsf \mathsfbf \mathsfbfit \mathsfit \mathtt \mbf \mbfit \mbfitsans \mbfsans \mfrak \mit \msans \mscr \mtt \rm \textbf \textit \textrm`

`\text{...}` and `\mbox{...}` hold literal text, kept as the caller wrote it: the field `text` names the command and `first_value` holds the text. `\operatorname{...}` holds the name of an operator.

=== Brackets

`\left` and `\right` enclose a group (model class `LeftRight`). The bracket after `\left` or `\right` may be `.` or missing. The grammar accepts `\left( x` with no `\right`. Recognised brackets include `(`, `)`, `[`, `]`, `\{`, `\}`, `\lbrace`, `\rbrace`, `\lbrack`, `\rbrack`, `\langle`, `\rangle`, `\lfloor`, `\rfloor`, `\lceil`, `\rceil`, `|`, `\vert`, `\Vert`, `\|` and `\backslash`, together with their Unicode characters.

=== Environments

`\begin{name} ... \end{name}` reads an environment whose rows are separated by `\\` (attribute `row_break`) and whose cells are separated by `&`. A starred name and an optional argument in brackets are accepted. `\begin{array}{...}` takes its column specification as `args`. The grammar also has a command form, `\matrix{...}` and the like, for the names `matrix`, `pmatrix`, `bmatrix`, `Bmatrix`, `vmatrix`, `Vmatrix`, `align`, `split`, `multline` and `array`.

The grammar does not check that the name after `\end` matches the name after `\begin`. The typed model does not build rows and cells: the body of the environment is the same nested expression as any other formula, and `&` and `\\` appear in it as an `operant` and a `row_break` (Annex A). `\substack` takes one operand.

=== Symbols and numbers

* A single ASCII letter is a symbol.
* A command name from the symbol table, such as `\alpha` or `\leq`, is a symbol. The table, `data/latex-symbols.json` of the `latexmath` gem, has 3,280 spellings at the pinned commit. A character reference such as `&#x3b1;` is also looked up there.
* `"` is a literal symbol, and the ASCII punctuation `! # $ % & ' * + , - . / : ; < = > ? @ ^ _ |` reads as operators.
* Numbers are digit strings, with an optional decimal part: `1`, `1.5`, `.5`. Hexadecimal (`0x1F`), binary (`0b101`) and octal (`0o17`) numbers are separate forms.
* `\ ` is a space and `\;` a thick space.

Each symbol in the model is a `MathSymbol` with three fields: `spelling` (the text matched), `value` (its Unicode text from the table) and `kind` (`symbol`, `open` or `close`). A spelling the table lacks stands for itself.
5 changes: 5 additions & 0 deletions sources/pm-1007/sections/08-model.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
== The typed model

`Latexmath.parse` returns a `Latexmath::Model::Document` with `expression` (the formula) and `decimal` (the marker). Input with no formula gives a document whose `expression` is nil. The model has 33 generated classes; the names follow the grammar captures (`Binary`, `UnaryFunctions`, `LeftRight`, `Environment`, `TableData`, `PowerBase` and so on). Every field with its type is listed in `model/latex.lml.json`, whose checksum is pinned in the clause "The grammar artifact".

The model is generated from the grammar and is not edited by hand. The model does not specify the meaning of commands that the legacy grammar kept without a dedicated class, such as `\rule`, beyond their captures.
Loading
Loading