diff --git a/README.adoc b/README.adoc index c5bbe54..596da33 100644 --- a/README.adoc +++ b/README.adoc @@ -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). diff --git a/metanorma.yml b/metanorma.yml index d33dc37..b6190ac 100644 --- a/metanorma.yml +++ b/metanorma.yml @@ -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" diff --git a/sources/pm-1007/document.adoc b/sources/pm-1007/document.adoc new file mode 100644 index 0000000..5cb38c8 --- /dev/null +++ b/sources/pm-1007/document.adoc @@ -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[] diff --git a/sources/pm-1007/sections/00-foreword.adoc b/sources/pm-1007/sections/00-foreword.adoc new file mode 100644 index 0000000..1c30c56 --- /dev/null +++ b/sources/pm-1007/sections/00-foreword.adoc @@ -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. diff --git a/sources/pm-1007/sections/00-introduction.adoc b/sources/pm-1007/sections/00-introduction.adoc new file mode 100644 index 0000000..ad874a8 --- /dev/null +++ b/sources/pm-1007/sections/00-introduction.adoc @@ -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. diff --git a/sources/pm-1007/sections/01-scope.adoc b/sources/pm-1007/sections/01-scope.adoc new file mode 100644 index 0000000..3dd4516 --- /dev/null +++ b/sources/pm-1007/sections/01-scope.adoc @@ -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. diff --git a/sources/pm-1007/sections/02-normrefs.adoc b/sources/pm-1007/sections/02-normrefs.adoc new file mode 100644 index 0000000..2758283 --- /dev/null +++ b/sources/pm-1007/sections/02-normrefs.adoc @@ -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". diff --git a/sources/pm-1007/sections/03-terms.adoc b/sources/pm-1007/sections/03-terms.adoc new file mode 100644 index 0000000..990a6d7 --- /dev/null +++ b/sources/pm-1007/sections/03-terms.adoc @@ -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 diff --git a/sources/pm-1007/sections/04-conventions.adoc b/sources/pm-1007/sections/04-conventions.adoc new file mode 100644 index 0000000..60369ad --- /dev/null +++ b/sources/pm-1007/sections/04-conventions.adoc @@ -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. diff --git a/sources/pm-1007/sections/05-artifact.adoc b/sources/pm-1007/sections/05-artifact.adoc new file mode 100644 index 0000000..519f825 --- /dev/null +++ b/sources/pm-1007/sections/05-artifact.adoc @@ -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. diff --git a/sources/pm-1007/sections/06-preparation.adoc b/sources/pm-1007/sections/06-preparation.adoc new file mode 100644 index 0000000..744c21c --- /dev/null +++ b/sources/pm-1007/sections/06-preparation.adoc @@ -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 `α`. `&` 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 `α`), 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. diff --git a/sources/pm-1007/sections/07-structure.adoc b/sources/pm-1007/sections/07-structure.adoc new file mode 100644 index 0000000..a484f77 --- /dev/null +++ b/sources/pm-1007/sections/07-structure.adoc @@ -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 `α` 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. diff --git a/sources/pm-1007/sections/08-model.adoc b/sources/pm-1007/sections/08-model.adoc new file mode 100644 index 0000000..009fe00 --- /dev/null +++ b/sources/pm-1007/sections/08-model.adoc @@ -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. diff --git a/sources/pm-1007/sections/09-plurimath.adoc b/sources/pm-1007/sections/09-plurimath.adoc new file mode 100644 index 0000000..3561764 --- /dev/null +++ b/sources/pm-1007/sections/09-plurimath.adoc @@ -0,0 +1,152 @@ +== Plurimath behaviour around the grammar + +=== Status + +.Status of the parts +[cols="3,1,3", options="headers"] +|=== +|Part |Status |Where + +|Reading LaTeX with the `latexmath` gem and mapping its typed model +|implemented +|https://github.com/plurimath/plurimath/issues/531[plurimath#531] + +|Writing LaTeX +|implemented +| + +|Measurement results written as plain LaTeX +|implemented +|https://github.com/plurimath/plurimath/pull/496[plurimath#496] + +|Reading measurement results from LaTeX (for example `siunitx`) +|proposed +|https://github.com/plurimath/plurimath/issues/524[plurimath#524] +|=== + +=== Reading + +`Plurimath::Math.parse(text, :latex)` creates a `Plurimath::Latex::Parser`, which calls `Latexmath.parse(text, decimal: Plurimath.configuration.decimal)` and maps the returned `Latexmath::Model::Document` to a `Plurimath::Math::Formula` with `Plurimath::Latex::Mapper`. The preparation of the input is the one of the clause "Preparation of the input". + +.Reading a formula (produced at the pinned `plurimath` commit) +[source,ruby] +---- +Plurimath::Math.parse("\\frac{a}{b} + \\sqrt{x}", :latex).to_asciimath +---- + +[source] +---- +frac(a)(b) + sqrt(x) +---- + +LaTeX takes the `locale:` parse option. It sets the decimal marker that `latexmath` is called with, so `1,5` is one number under a comma locale and two numbers with a comma between them otherwise: + +[source,ruby] +---- +Plurimath::Math.parse("1,5", :latex).value.map(&:class) +---- + +[source] +---- +[Plurimath::Math::Number, Plurimath::Math::Symbols::Comma, Plurimath::Math::Number] +---- + +[source,ruby] +---- +Plurimath::Math.parse("1,5", :latex, locale: :de).value.map(&:class) +---- + +[source] +---- +[Plurimath::Math::Number] +---- + +`latexmath` is a runtime dependency. If it cannot be loaded, the parser raises `Plurimath::Math::MissingDependencyError` with the Gemfile line to add. + +=== Writing + +`Formula#to_latex` joins the output of each node with a space. It needs no LaTeX package beyond what the output commands themselves need. It takes the keyword options `formatter:` (default `nil`), `unitsml:` (default `{}`) and `options:` (default `nil`). `formatter:` and `unitsml:` work as for MathML (PM 1003). `options:` is a prepared options hash and takes the place of the other two. + +[source,ruby] +---- +Plurimath::Math.parse("frac(a)(b) + sqrt(x) + sum_(i=1)^n i", :asciimath).to_latex +---- + +[source] +---- +\frac{a}{b} + \sqrt{x} + \sum_{i = 1}^{n} i +---- + +[source,ruby] +---- +Plurimath::Math.parse(%q("speed" = d/t), :asciimath).to_latex +---- + +[source] +---- +\text{speed} = \frac{d}{t} +---- + +[source,ruby] +---- +Plurimath::Math.parse("alpha + oo", :asciimath).to_latex +---- + +[source] +---- +\alpha + \infty +---- + +[source,ruby] +---- +Plurimath::Math.parse("color(red)(x)", :asciimath).to_latex +---- + +[source] +---- +{\color{red} x} +---- + +=== Constructs + +Each row below is read as LaTeX, written as AsciiMath, and written back as LaTeX from the same formula. The "Written back" column is what `Formula#to_latex` gives, so a difference from the input shows what is normalised or lost: + +* spaces are put around operators and between terms, and `\left` and `\right` are followed by a space; +* `\binom` becomes a matrix between braces, and `\operatorname` is dropped; +* `\sin x` is written as `\sin{x}`. + +Two rows fail. The grammar has no `cases` environment, so `\begin{cases}` is refused. `\overbrace` with only a label above it is read, but the mapper builds no node for it, so writing the formula raises `Plurimath::Math::ParseError`; `\overbrace` reads when it has both a subscript and a superscript. + +.Constructs read and written back (produced at the pinned `plurimath` commit) +[cols="2,3l,3l,3l",options="header"] +|=== +|Construct |Input |AsciiMath |Written back +|Number |12.5 |12.5 |12.5 +|Letter |x |x |x +|Superscript |x^{2} |x^(2) |x^{2} +|Subscript |x_{i} |x_(i) |x_{i} +|Both scripts |x_{i}^{2} |x_(i)^(2) |x_{i}^{2} +|Fraction |\frac{a}{b} |frac(a)(b) |\frac{a}{b} +|Binomial |\binom{n}{k} |{[n], [k]} |\left \{\begin{matrix}n \\ k\end{matrix}\right \} +|Square root |\sqrt{x} |sqrt(x) |\sqrt{x} +|Root with index |\sqrt[3]{x} |root(3)(x) |\sqrt[3]{x} +|Sum with limits |\sum_{i=1}^{n} i |sum_(i = 1)^(n) i |\sum_{i = 1}^{n} i +|Integral |\int_{0}^{1} f(x) dx |int_(0)^(1) f (x) d x |\int_{0}^{1} f ( x ) d x +|Limit |\lim_{x \to 0} x |lim_(x to 0) x |\lim_{x \to 0} x +|Function name |\sin x |sinx |\sin{x} +|Operator name |\operatorname{sgn} x |sgn x |sgn x +|Symbols |\alpha + \infty |alpha + oo |\alpha + \infty +|Relation |x \le y |x le y |x \le y +|Brackets |\left( x \right) |left( x right) |\left ( x \right ) +|Bracket on one side |\left\{ x \right. |left{ x right |\left \{ x \right . +|Matrix |\begin{matrix} a & b \\ c & d \end{matrix} |{:[a, b], [c, d]:} |\begin{matrix}a & b \\ c & d\end{matrix} +|Matrix in brackets |\begin{pmatrix} a & b \end{pmatrix} |([a, b]) |\begin{pmatrix}a & b\end{pmatrix} +|Cases |\begin{cases} a & b \end{cases} |refused: Plurimath::Math::ParseError |- +|Text |\text{if} |"if" |\text{if} +|Font |\mathbf{x} |mathbf(x) |\mathbf{x} +|Upright font |\mathrm{d}x |rm(d) x |\mathrm{d} x +|Accent |\hat{x} |hat(x) |\hat{x} +|Overline |\overline{x} |bar(x) |\overline{x} +|Brace with label |\overbrace{x}^{n} |raises Plurimath::Math::ParseError |raises Plurimath::Math::ParseError +|Colour |\color{red}{x} |color(red)(x) |{\color{red} x} +|=== diff --git a/sources/pm-1007/sections/10-uncertainty.adoc b/sources/pm-1007/sections/10-uncertainty.adoc new file mode 100644 index 0000000..5510a09 --- /dev/null +++ b/sources/pm-1007/sections/10-uncertainty.adoc @@ -0,0 +1,41 @@ +== Measurement uncertainty + +LaTeX has no marker for a measurement result. Plurimath writes the visible form only, in plain math with no package, and reads it back as ordinary numbers, brackets and text, never as an uncertainty. LaTeX is therefore an output-only format for measurement results. The forms in all formats are in PM 1002. + +[source,ruby] +---- +Plurimath::Math.parse("ustd(1.230, 0.004)", :asciimath).to_latex +---- + +[source] +---- +1.230(0.004) +---- + +[source,ruby] +---- +Plurimath::Math.parse("ucov(1.024, 0.983, 1.088, 0.95, shortest)", :asciimath).to_latex +---- + +[source] +---- +1.024,\ [0.983, 1.088],\ p = 0.95 +---- + +Reading the interval form back gives no uncertainty node: + +[source,ruby] +---- +Plurimath::Math.parse("1.024,\\ [0.983, 1.088],\\ p = 0.95", :latex).to_asciimath +---- + +[source] +---- +1.024 , " " [0.983 , 1.088] , " " p = 0.95 +---- + +=== What LaTeX output loses + +* *The interval kind.* A coverage interval written as LaTeX does not say whether it is the shortest or the probabilistically symmetric interval. +* *The category.* Standard, expanded and coverage-interval results are told apart only by their layout; reading the LaTeX back gives no uncertainty node. +* *The unit as a unit.* A UnitsML unit is written as its rendered symbols, such as `\mathrm{m}`; it cannot be read back as a unit. diff --git a/sources/pm-1007/sections/11-errors.adoc b/sources/pm-1007/sections/11-errors.adoc new file mode 100644 index 0000000..61d8e56 --- /dev/null +++ b/sources/pm-1007/sections/11-errors.adoc @@ -0,0 +1,21 @@ +== Errors + +=== Refusal by the grammar + +Input the grammar does not match raises `Latexmath::ParseError`. The error gives the position as a character and byte offset in the caller's text, and the position in the rewritten text as `grammar_char_offset` and `grammar_byte_offset`. The wording of the message is not part of the contract. Input nested deeper than the native engine allows is parsed with the Ruby engine by default, or raises `Latexmath::NestingTooDeep` when the native engine is requested. + +=== Refusal at the Plurimath boundary + +`Plurimath::Math.parse(text, :latex)` raises `Plurimath::Math::ParseError` when `latexmath` refuses the text, including text with no formula (empty, or only spaces and newlines). The parser first turns `Latexmath::ParseError` into a `Parsanol::ParseFailed` at the position the grammar reports; the error the caller gets has no `cause`. + +[source,ruby] +---- +Plurimath::Math.parse("\\frac{a}{", :latex) +---- + +[source] +---- +raises Plurimath::Math::ParseError +---- + +A parse refusal is a refusal of the text by the grammar. It is distinct from a failure to write a formula that was read: `\overbrace` with only a label reads, and writing it raises `Plurimath::Math::ParseError` because the mapper builds no node for it (clause "Constructs"). diff --git a/sources/pm-1007/sections/12-conformance.adoc b/sources/pm-1007/sections/12-conformance.adoc new file mode 100644 index 0000000..fd68b26 --- /dev/null +++ b/sources/pm-1007/sections/12-conformance.adoc @@ -0,0 +1,34 @@ +== Conformance + +=== General + +Conformance to this document is the implementation of the LaTeX reader per the clauses on preparation, structure and the typed model, and of the writer per the clause on Plurimath behaviour, against the artifact pinned in the clause "The grammar artifact". + +=== Conformance classes + +.Conformance classes +[cols="1,3,3", options="headers"] +|=== +|Class |Licenses the implementation to claim |Replay requirements + +|read-latex +|reads the notation of this document and refuses what the grammar refuses +|the `corpus/latex/` rows of the testsuite, and the `stages/latex/` generation pinned by `spec/fixtures/testsuite-pin.yml` of the `latexmath` gem + +|write-latex +|writes LaTeX from the formula tree +|the `latex` target of every `corpus/*/` case, byte for byte +|=== + +=== The corpora + +* `spec/model/parse_spec.rb` of the `latexmath` gem checks the public parse and its errors. +* `spec/corpus/replay_corpus_spec.rb` and `spec/stage_cases/` of the `latexmath` gem replay the stage corpus generation pinned in `spec/fixtures/testsuite-pin.yml` (plurimath-testsuite `stages/latex/`, commit `337262eda0483ceaa43a02cc52362c5b721e5eb3`, generation 3). +* `spec/parser/oracle_parity_spec.rb` of the `latexmath` gem compares the raw tree with captures of the Plurimath parser. +* `spec/conformance/shared_corpus_spec.rb` of the `plurimath` gem replays every `corpus/` case, comparing each target byte for byte. At testsuite commit `337262eda0483ceaa43a02cc52362c5b721e5eb3` these are 125 `corpus/latex/` inputs read (groups `accents`, `colour`, `fences`, `fonts`, `frac`, `left-right`, `matrices`, `mod`, `nary`, `numbers`, `operators`, `over-under`, `powers`, `quoted-text`, `roots`, `symbols`, `unary-functions`, `whitespace`), 14 `corpus/latex/rejections.yaml` inputs refused, and 780 `corpus/*/` cases with a `latex` output in 74 payloads. +* The roundtrip generation of the testsuite has no LaTeX targets, because LaTeX output is not read back as an uncertainty. +* The `stages/latex/` generations are replayed by the `latexmath` gem, not by the `plurimath` gem. + +=== Claims + +A claim names the artifact checksum of the clause "The grammar artifact" and the testsuite commit and generation. An implementation against a moved artifact makes a different claim. diff --git a/sources/pm-1007/sections/90-annex-a.adoc b/sources/pm-1007/sections/90-annex-a.adoc new file mode 100644 index 0000000..8624723 --- /dev/null +++ b/sources/pm-1007/sections/90-annex-a.adoc @@ -0,0 +1,71 @@ +== Annex A: examples of the typed model + +These results were produced by parsing each input with `Latexmath.parse` at the pinned `latexmath` commit and printing the non-empty fields of the model. A symbol is shown as `MathSymbol(spelling)`. The root of the expression is a `LatexTree`. Fields inside each class are printed in the order the class declares them, not in input order. + +[source] +---- +a^2 + LatexTree(power: Power(supscript: Supscript(number: "2"), symbols: MathSymbol("a"))) + +x_i^2 + LatexTree(power_base: PowerBase(subscript: Subscript(symbols: MathSymbol("i")), + supscript: Supscript(number: "2"), symbols: MathSymbol("x"))) + +\frac{a}{b} + LatexTree(binary: Binary(binary: Binary(literal: "frac"), + first_value: FirstValue(expression: Expression(symbols: MathSymbol("a"))), + second_value: SecondValue(expression: Expression(symbols: MathSymbol("b"))))) + +{a \over b} + LatexTree(over: Over(dividend: Dividend(items: [ItemsItem(symbols: MathSymbol("a"))]), + divisor: Divisor(items: [ItemsItem(symbols: MathSymbol("b"))]))) + +\sqrt[3]{x} + LatexTree(binary: Binary(first_value: FirstValue(expression: Expression(items: [ItemsItem(number: "3")]), + lparen: "[", rparen: "]"), root: "sqrt", + second_value: SecondValue(expression: Expression(symbols: MathSymbol("x"))))) + +\sin x + LatexTree(unary_functions: UnaryFunctions(first_value: FirstValue(symbols: MathSymbol("x")), unary: "sin")) + +\sum_{i=1}^{n} i + LatexTree(ternary_class: TernaryClass(subscript: Subscript(expression: Expression( + expression: Expression(expression: Expression(number: "1"), sequence: Sequence(operant: "=")), + sequence: Sequence(symbols: MathSymbol("i")))), + supscript: Supscript(expression: Expression(symbols: MathSymbol("n"))), + ternary_functions: "sum", third_value: ThirdValue(symbols: MathSymbol("i")))) + +\left( x \right) + LatexTree(left_right: LeftRight(expression: Expression(symbols: MathSymbol("x")), + left: "\\left", left_paren: LeftParen(literal: "("), + right: "\\right", right_paren: RightParen(literal: ")"))) + +\left( x + LatexTree(left_right: LeftRight(expression: Expression(symbols: MathSymbol("x")), + left: "\\left", left_paren: LeftParen(literal: "("))) + +\begin{pmatrix} a & b \\ c & d \end{pmatrix} + LatexTree(environment: Environment(ending: Ending(environment: Environment(literal: "pmatrix")), + environment: Environment(literal: "pmatrix"), + table_data: TableData(expression: Expression(expression: Expression(expression: Expression( + expression: Expression(expression: Expression(expression: Expression(symbols: MathSymbol("d")), + sequence: Sequence(operant: "&")), sequence: Sequence(symbols: MathSymbol("c"))), + sequence: Sequence(row_break: "\\\\")), sequence: Sequence(symbols: MathSymbol("b"))), + sequence: Sequence(operant: "&")), sequence: Sequence(symbols: MathSymbol("a"))))) + +\mathbf{x} + LatexTree(fonts: "mathbf", intermediate_exp: IntermediateExp(expression: Expression(symbols: MathSymbol("x")))) + +\text{if } x + LatexTree(expression: Expression(symbols: MathSymbol("x")), + sequence: Sequence(first_value: FirstValue(text_list: "if "), text: "text")) + +\alpha + LatexTree(symbols: MathSymbol("alpha")) + +1.5 + LatexTree(number: "1.5") + +\frac{a} + Latexmath::ParseError at char 8 +---- diff --git a/sources/pm-1007/sections/91-annex-b.adoc b/sources/pm-1007/sections/91-annex-b.adoc new file mode 100644 index 0000000..89487aa --- /dev/null +++ b/sources/pm-1007/sections/91-annex-b.adoc @@ -0,0 +1,8 @@ +== Annex B: open questions + +These points are not specified; the notation described here is what the pinned artifact does. + +* Whether the mismatch between `\begin{name}` and `\end{other}` should be refused: not specified. +* Whether `\left` without `\right` is intended or a legacy leniency: not specified. +* The meaning of the model for commands that the legacy grammar keeps without a dedicated class (for example `\rule`): not specified beyond the captures. +* Reading measurement results from LaTeX: proposed, https://github.com/plurimath/plurimath/issues/524[plurimath#524]. diff --git a/sources/pm-1007/sections/98-bibliography.adoc b/sources/pm-1007/sections/98-bibliography.adoc new file mode 100644 index 0000000..fb1633f --- /dev/null +++ b/sources/pm-1007/sections/98-bibliography.adoc @@ -0,0 +1,8 @@ +[bibliography] +== Bibliography + +* [[[plurimath-repo,nofetch(Plurimath repository)]]] — https://github.com/plurimath/plurimath +* [[[latexmath-repo,nofetch(latexmath repository)]]] — https://github.com/plurimath/latexmath +* [[[pm-testsuite,nofetch(plurimath-testsuite)]]] — the pinned corpus repository and its generations +* [[[pm1005-b,nofetch(PM 1005)]]] of this series +* [[[pm1006-b,nofetch(PM 1006)]]] of this series diff --git a/sources/pm-1008/document.adoc b/sources/pm-1008/document.adoc new file mode 100644 index 0000000..e3d1f5c --- /dev/null +++ b/sources/pm-1008/document.adoc @@ -0,0 +1,53 @@ += The PM UnicodeMath notation +:docnumber: 1008 +:edition: 1 +:ref-docnumber: PM 1008:2026(E) +:copyright-year: 2026 +:revdate: 2026-11-10 +:language: en +:script: Latn +:title: Plurimath specifications -- The PM UnicodeMath 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-coverage.adoc[] + +include::sections/10-plurimath.adoc[] + +include::sections/11-uncertainty.adoc[] + +include::sections/12-errors.adoc[] + +include::sections/13-conformance.adoc[] + +include::sections/90-annex-a.adoc[] + +include::sections/91-annex-b.adoc[] + +include::sections/98-bibliography.adoc[] diff --git a/sources/pm-1008/sections/00-foreword.adoc b/sources/pm-1008/sections/00-foreword.adoc new file mode 100644 index 0000000..ff4c7b1 --- /dev/null +++ b/sources/pm-1008/sections/00-foreword.adoc @@ -0,0 +1,30 @@ +== Foreword + +=== General + +This document is the eighth document of the Plurimath specifications series. It specifies the UnicodeMath notation that Plurimath reads and writes: the grammar that accepts it, the typed model the grammar produces, what Plurimath makes of that model, how measurement results and units are carried, what does not survive a round trip, and the corpora that check all of this. + +UnicodeMath is the linear format of Unicode Technical Note 28 (UTN 28). The notation specified here is the subset, and the variations of it, that Plurimath read at Plurimath 0.11.17 (commit `e7ab4a5186c9be96f62d670574bc2c72f9365ad4`), when the grammar was still part of the `plurimath` gem. The grammar now lives in the `umath` gem and is carried by a checksummed artifact (clause "The grammar artifact"). It does not read all of UTN 28. Where this document and the implementation disagree, the disagreement is a defect in one of the two. + +This document is the PM UnicodeMath 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 |The LaTeX math notation +|1008 |The PM UnicodeMath notation |This document: the UnicodeMath notation +|=== + +=== Maintainers + +This document is maintained by the Plurimath project at https://github.com/plurimath/plurimath. diff --git a/sources/pm-1008/sections/00-introduction.adoc b/sources/pm-1008/sections/00-introduction.adoc new file mode 100644 index 0000000..e5f5db8 --- /dev/null +++ b/sources/pm-1008/sections/00-introduction.adoc @@ -0,0 +1,7 @@ +== Introduction + +UnicodeMath is a linear notation: a formula is one line of text in which fractions, scripts, roots and matrices are written with operator characters and brackets. Plurimath reads a subset of it and a few variations, and writes it with the conventions of this document. Measurement results are carried in it with the intent form `ⓘ(...)` and units with the argument form `ⓐ(...)`. + +The grammar accepts what Plurimath accepted at the pinned commit; it is not a validator of UTN 28. For each construct of UTN 28 the corpus shows whether the grammar reads it, refuses it, or is silent (clause "Coverage of UTN 28"). 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 `umath` gem. The second describes what Plurimath does around the grammar: reading, writing, measurement results and units, round trips, errors; its content is taken from the `plurimath` gem. diff --git a/sources/pm-1008/sections/01-scope.adoc b/sources/pm-1008/sections/01-scope.adoc new file mode 100644 index 0000000..013a02f --- /dev/null +++ b/sources/pm-1008/sections/01-scope.adoc @@ -0,0 +1,41 @@ +== 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 coverage of UTN 28 as the corpus shows it; +* the reading of UnicodeMath into the formula tree of PM 1001 and the writing of the tree as UnicodeMath; +* the carrying of measurement results with `ⓘ` and of units with `ⓐ`, and what does not survive a round trip; +* 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: UTN 28 itself, the formula tree (PM 1001), the uncertainty node and its marker grammar (PM 1002), or the general reader and writer interfaces (PM 1003). + +=== 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 marker grammar carried inside `ⓘ(...)`, and the round-trip matrix + +|1003 Format interfaces +|the general reader and writer interfaces; this document is the UnicodeMath notation they refer to + +|1005 The AsciiMath notation +|the notation used in the examples to show the tree +|=== + +=== Audience + +Implementers of a UnicodeMath reader or writer for the Plurimath tree, and maintainers of the `umath` grammar and its artifact. diff --git a/sources/pm-1008/sections/02-normrefs.adoc b/sources/pm-1008/sections/02-normrefs.adoc new file mode 100644 index 0000000..180ba4c --- /dev/null +++ b/sources/pm-1008/sections/02-normrefs.adoc @@ -0,0 +1,11 @@ +[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. +* [[[utn28,nofetch(Unicode Technical Note 28)]]] — UnicodeMath, a Nearly Plain-Text Encoding of Mathematics, version 3.2 (April 13, 2023), https://www.unicode.org/notes/tn28/. +* [[[umath-docs,nofetch(umath docs/unicodemath.adoc)]]] — the notation page of the `umath` gem, at the commit named in the clause "The grammar artifact". +* [[[umath-artifact,nofetch(umath grammar artifact)]]] — `grammars/umath.parg` and the files generated from it, with the checksums of the clause "The grammar artifact". diff --git a/sources/pm-1008/sections/03-terms.adoc b/sources/pm-1008/sections/03-terms.adoc new file mode 100644 index 0000000..6497c30 --- /dev/null +++ b/sources/pm-1008/sections/03-terms.adoc @@ -0,0 +1,27 @@ +== Terms and definitions + +For the purposes of this document, the following terms and definitions apply. + +=== grammar +the PARG grammar `grammars/umath.parg` of the `umath` gem, generated from the legacy UnicodeMath grammar of Plurimath at the commit named in the Foreword + +=== artifact +the compiled form of the grammar, `artifacts/umath.json`, with its bindings and the checksum file `artifacts/umath.checksums.txt` + +=== rewritten text +the copy of the input that the grammar reads, produced by the preparation steps + +=== typed model +the tree of `Umath::Model` classes that parsing returns; `Umath::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::UnicodeMath::Mapper` + +=== intent form +the form `ⓘ("marker"visible)` that carries a measurement result + +=== argument form +the form `ⓐ(unit ...)` that carries a unit diff --git a/sources/pm-1008/sections/04-conventions.adoc b/sources/pm-1008/sections/04-conventions.adoc new file mode 100644 index 0000000..6e66a1a --- /dev/null +++ b/sources/pm-1008/sections/04-conventions.adoc @@ -0,0 +1,13 @@ +== Conventions + +=== General + +UnicodeMath text is shown verbatim in monospace. Model classes and fields are named as the `umath` 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. The format name of the reader is `:unicode`; the writer method is `to_unicodemath`. + +=== Provenance of the content + +The notation clauses are taken from `docs/unicodemath.adoc` of the `umath` gem, and the clauses on reading, writing, measurement results, round trips and errors from `docs/unicodemath.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. diff --git a/sources/pm-1008/sections/05-artifact.adoc b/sources/pm-1008/sections/05-artifact.adoc new file mode 100644 index 0000000..9d2a81d --- /dev/null +++ b/sources/pm-1008/sections/05-artifact.adoc @@ -0,0 +1,39 @@ +== 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 + +|`umath` repository |https://github.com/plurimath/unicodemath, commit `ef11954aa61034a529150922faa6ea02e8274b18`, gem version 0.1.0 +|`umath` notation page |`docs/unicodemath.adoc` at that commit +|origin of the grammar |the legacy UnicodeMath grammar of Plurimath at commit `e7ab4a5186c9be96f62d670574bc2c72f9365ad4` (Plurimath 0.11.17) +|`plurimath` repository |https://github.com/plurimath/plurimath, commit `f04c688fbfaa6ccdf019af03b34ec0fc0d229226` +|`plurimath` format page |`docs/unicodemath.adoc` at that commit +|testsuite for the `plurimath` gem |https://github.com/plurimath/plurimath-testsuite, commit `337262eda0483ceaa43a02cc52362c5b721e5eb3` +|testsuite for the `umath` gem |https://github.com/plurimath/plurimath-testsuite, commit `85c7be8fd56f0cc64b4869e74716acc4f0dbe746`, `stages/unicode/` generation 4 +|=== + +=== Pinned checksums + +.Checksums of the artifact (`artifacts/umath.checksums.txt`, edition 2, compiler 1.3.134) +[cols="3,5", options="headers"] +|=== +|File |SHA-256 + +|`grammars/umath.parg` |`8fbf980d93a4e7a47638c795ae86c519626956b6a68a65d1e36b610587602fcc` +|`artifacts/umath.json` |`703824533584b29e17ee807a30868c9f6923e26d0ee40c9a0a7b6c7de793220f` +|`model/umath.lml.json` |`4714028eb15188f2d36543d1e272802556207cf056923868ef57ff8911220839` +|=== + +The artifact checksum recorded by the compiler is `sha256:a58c0bb7778b56b503d6b0aaf1a8d3a1c171de7e509dcaa0e655b59088657c2f`, and its source hash is the checksum of `grammars/umath.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. diff --git a/sources/pm-1008/sections/06-preparation.adoc b/sources/pm-1008/sections/06-preparation.adoc new file mode 100644 index 0000000..433d766 --- /dev/null +++ b/sources/pm-1008/sections/06-preparation.adoc @@ -0,0 +1,9 @@ +== Preparation of the input + +The grammar reads a rewritten copy of the input. The steps are specified in full in the parser contract of the `umath` gem. In short: + +* A `#` starts an equation label. The text after the last `#` becomes the document's `label`; a `#` inside `✎(...)` does not count. +* Every non-ASCII character becomes a hexadecimal character reference, so `α` reaches the grammar as `α`. `&` and `"` stay as they are. +* Everything from the first `⫷` to the last `⫸` is a comment and is removed. +* `\\` becomes `\`, and `\uXXXX` escapes become the character they name. +* Leading and trailing whitespace is removed. diff --git a/sources/pm-1008/sections/07-structure.adoc b/sources/pm-1008/sections/07-structure.adoc new file mode 100644 index 0000000..fd696c7 --- /dev/null +++ b/sources/pm-1008/sections/07-structure.adoc @@ -0,0 +1,102 @@ +== Structure of a formula + +The root rule is `expression`. An expression is a sequence of elements. +Elements may be separated by spaces, by relational symbols such as `=` or +`≤`, and by operators. An element is one of the constructs below, or a plain +operand: a letter, a number, a symbol or a bracketed group. + +=== Fractions + +.Fraction forms +[cols="2,3", options="headers"] +|=== +|Form |Meaning + +|`a/b`, `a\over b` |fraction (`Frac`, with `numerator` and `denominator`) +|`a⁄b`, `a\sdiv b`, `a\sfrac b` |bevelled fraction +|`a⊘b`, `a\ndiv b` |fraction not in display style +|`a∕b`, `a\ldiv b` |linear fraction +|`a¦b`, `a\atop b` |stack without a bar +|`a⒞b`, `a\choose b` |binomial +|`½`, `⅓` and the other vulgar fraction characters |a fraction symbol +|=== + +A superscript character, a fraction bar and a subscript character, such as +`ᵃ/ₙ`, make a small fraction (`mini_numerator`, `mini_denominator`). + +=== Scripts + +`_` gives a subscript and `^` a superscript, in either order. A script is +one operand or a bracketed group; the brackets of `x_(i+1)` are not part of +the script. Unicode subscript and superscript characters, such as `x²` or +`xᵢ`, are read as scripts too. The grammar also has rules for scripts written before a base +(`pre_subsup`). + +=== Large operators + +Characters such as `∑`, `∏`, `∫`, `∮`, `⋃` and `⋂`, and command names such +as `\sum`, `\bigcup` and `\amalg`, are n-ary operators (capture +`nary_class`). They take limits as scripts and an operand after them. + +=== Functions + +The function names + +`arccos arcsin arctan arg cos cosh cot csc csch def deg det dim erf exp gcd +hom Im inf ker lim ln log max min mod Pr Re sec sech sin sinh sup tan tanh tg` + +are read as functions (capture `unary_functions`) and take the operand that +follows (class `UnarySubsup` for `sin x`). + +=== Roots + +* `√x`, `\sqrt x` is a square root, `∛x` a cube root and `∜x` a fourth + root. +* `√(n&x)` is the `n`-th root of `x`. +* `⒭`, `\root` take the index and then the radicand. + +=== Matrices and arrays + +`■(a&b@c&d)` is a matrix: `@` separates rows and `&` separates cells. The +grammar also reads the bracketed matrix characters `⒨`, `⒱`, `⒩`, `ⓢ`, +`Ⓢ`, `█` and `Ⓒ`, and `\array`. A matrix character followed by one digit, +such as `■3`, is an identity matrix of that size +(`identity_matrix_number`). + +=== Brackets + +`(`, `[`, `{` and their closers make a bracketed group; so do commands such +as `\langle`, `\lceil`, `\lfloor`, `\lbrack` and `\begin`, with their +closers. A group may mix a bracket with `|`. In the model the brackets are +`open_paren` and `close_paren`, both of class `Paren`. + +=== Accents, enclosures and styling + +* Combining accents after an operand, such as `x̂` or `x⃗`, are accents + (capture `accents`). Overlays and marks below are `diacritics_accents`. +* Horizontal brackets `⏞`, `⏟`, `⎴`, `⎵`, `⏜`, `⏝`, `⏠`, `⏡` take the + operand that follows (`hbrack`). +* `▭(...)`, `\rect(...)` is an enclosure, `⟡(...)`, `\phantom(...)` a + phantom. The grammar has a box rule for `□`, but it matches the raw + character, which preprocessing has already encoded, so `□a` is read as + the symbol `□` followed by `a` (Annex A). +* `✎(colour&x)`, `\color(...)` sets a colour and `☁(...)`, `\backcolor(...)` + a background colour. +* `ⓘ(...)` carries an intent, and `ⓐ(...)` an argument function. +* Font commands such as `\mbf`, `\mit`, `\Bbb`, `\mscr`, `\mfrak`, + `\msans` and `\mtt` followed by a letter set a font. A mathematical + alphanumeric character such as `𝐱` is read as a Unicode symbol, not as a + font. `ᅲ(...)` is monospace text. + +=== Symbols and numbers + +Each symbol in the model is a `MathSymbol` (or a `SymbolNode` or `Paren`) +with `spelling` (the text matched, such as `α` for `α` or `alpha` for +`\alpha`), `value` (its Unicode text from `data/umath-symbols.json`) and +`kind`. A spelling the catalog lacks has kind `unlisted`. + +Numbers are kept as written. `1.5` is a `DecimalNumber` with `whole`, +`decimal` and `fractional`. The decimal marker is `.` unless the caller +passes `decimal: ","` or `decimal: "٫"`. Hexadecimal, binary and octal +numbers are separate forms. + diff --git a/sources/pm-1008/sections/08-model.adoc b/sources/pm-1008/sections/08-model.adoc new file mode 100644 index 0000000..5c76026 --- /dev/null +++ b/sources/pm-1008/sections/08-model.adoc @@ -0,0 +1,3 @@ +== The typed model + +`Umath.parse` returns a `Umath::Model::Document` with `expression`, `label` and `decimal`. Input with no formula gives a document whose `expression` is nil. The model has 74 generated classes plus `Document`; captures that can hold a whole expression share the class `Model::Expression`. Every field with its type is listed in `model/umath.lml.json`, whose checksum is pinned in the clause "The grammar artifact". diff --git a/sources/pm-1008/sections/09-coverage.adoc b/sources/pm-1008/sections/09-coverage.adoc new file mode 100644 index 0000000..3e794ab --- /dev/null +++ b/sources/pm-1008/sections/09-coverage.adoc @@ -0,0 +1,11 @@ +== Coverage of UTN 28 + +The constructs are taken from UTN 28 version 3.2 (April 13, 2023). The mapping from construct to corpus rows is `docs/utn28-coverage.yml` of the `umath` gem. Its script `scripts/utn28_coverage.rb` parses every mapped row, checks that its outcome is the one the row expects, and writes the table in `docs/unicodemath.adoc` of the `umath` gem; with `--check` it fails when the table is out of date. The table is not copied here, because it is regenerated from the corpus: the full table is the one in that file at the commit named in the clause "The grammar artifact". + +The table lists 82 constructs of UTN 28 version 3.2. Of the 82 constructs, 25 are covered, 1 is refused and 56 are untested. + +* Covered means that every row listed for the construct parses to the model the row expects. +* Refused means that the rows give input UTN 28 defines and that the grammar refuses it on purpose. The one such construct is the alignment mark `&` outside a matrix, `a&=b` (UTN 28 section 3.23). +* Untested means that no row exercises the construct, so the corpus does not show whether the grammar reads it. An untested construct may still be read by the grammar. + +Rows that give incomplete input, such as a trailing `/` or an unclosed bracket, are refused by the grammar; they are listed with their construct and do not change its status. diff --git a/sources/pm-1008/sections/10-plurimath.adoc b/sources/pm-1008/sections/10-plurimath.adoc new file mode 100644 index 0000000..4f876c4 --- /dev/null +++ b/sources/pm-1008/sections/10-plurimath.adoc @@ -0,0 +1,228 @@ +== Plurimath behaviour around the grammar + +=== Status + +.Status of the parts +[cols="3,1,3", options="headers"] +|=== +|Part |Status |Where + +|Reading UnicodeMath with the `umath` gem and mapping its typed model +|implemented +|https://github.com/plurimath/plurimath/pull/555[plurimath#555]; issue https://github.com/plurimath/plurimath/issues/531[plurimath#531] + +|Writing UnicodeMath +|implemented +| + +|Measurement results as `ⓘ("marker" ...)`, read and written +|implemented +|https://github.com/plurimath/plurimath/pull/496[plurimath#496], https://github.com/plurimath/plurimath/pull/497[plurimath#497], https://github.com/plurimath/plurimath/pull/502[plurimath#502], https://github.com/plurimath/plurimath/pull/506[plurimath#506] + +|Units as `ⓐ(unit ...)`, multi-letter symbols as quoted upright text +|implemented +|https://github.com/plurimath/plurimath/pull/507[plurimath#507], https://github.com/plurimath/plurimath/pull/549[plurimath#549] +|=== + +=== Reading + +The format name is `:unicode`. `Plurimath::Math.parse(text, :unicode)` creates a `Plurimath::UnicodeMath::Parser`, which calls `Umath.parse(text, decimal: Plurimath.configuration.decimal)` and turns the returned typed model into a `Plurimath::Math::Formula` with `Plurimath::UnicodeMath::Mapper`. `umath` is a runtime dependency; if it cannot be loaded, the parser raises `Plurimath::Math::MissingDependencyError` with the Gemfile line to add. + +The `umath` gem prepares the text before its grammar runs, in the way Plurimath did before the grammar moved (the clause "Preparation of the input"). Plurimath splits off the label itself, in the same way. Together they: + +. split the text at every `#`, except one inside `✎(...)`. The text before the first `#` is the formula and the text after the last `#` is the label of a labelled row; anything between is dropped. A `#` inside a quoted string is split too; +. write every non-ASCII character, and every character that HTML escapes other than `&` and `"`, as a hexadecimal character reference; +. remove everything from the first `⫷` to the last `⫸`, which UnicodeMath uses for comments; +. replace `\\` by `\` and turn each `\u` escape into a character reference; +. strip leading and trailing whitespace. + +.Reading a formula (produced at the pinned `plurimath` commit) +[source,ruby] +---- +Plurimath::Math.parse("(a)/(b) + √(x)", :unicode).to_asciimath +---- + +[source] +---- +frac(a)(b) + sqrt(x) +---- + +A `\u` escape takes up to five hexadecimal digits, which are copied into the reference as written, and drops up to five letters or digits that follow them. The symbol table only knows references without leading zeros, so `\u3b1` is read as α but `α` stays an unknown character, and in `αx` the `x` is lost: + +[source,ruby] +---- +Plurimath::Math.parse("\\u3b1+1", :unicode).to_latex +---- + +[source] +---- +\alpha + 1 +---- + +[source,ruby] +---- +Plurimath::Math.parse("\\u03B1+1", :unicode).to_latex +---- + +[source] +---- +α + 1 +---- + +[source,ruby] +---- +Plurimath::Math.parse("\\u03B1x+1", :unicode).to_latex +---- + +[source] +---- +α + 1 +---- + +The label is the text after the last `#`: + +[source,ruby] +---- +Plurimath::Math.parse("E=mc^2#(1)", :unicode).to_mathml +---- + +[source,xml] +---- + + + + + + (1) + + + + E + = + + m + + c + 2 + + + + + + + + +---- + +[source,ruby] +---- +Plurimath::Math.parse("x#(1)#(2)", :unicode).to_asciimath +---- + +[source] +---- +mlabeledtr(x)("(2)") +---- + +[source,ruby] +---- +Plurimath::Math.parse(%q("a#b"), :unicode) +---- + +[source] +---- +raises Plurimath::Math::ParseError +---- + +UnicodeMath takes the `locale:` parse option, which sets the decimal marker: + +[source,ruby] +---- +Plurimath::Math.parse("1,5", :unicode, locale: :de).value.map(&:class) +---- + +[source] +---- +[Plurimath::Math::Number] +---- + +The writer method is `to_unicodemath`, but the input format is `:unicode`; `:unicodemath` is not a format name: + +[source,ruby] +---- +Plurimath::Math.parse("x^2", :unicodemath) +---- + +[source] +---- +raises Plurimath::Math::InvalidTypeError +---- + +=== Writing + +`Formula#to_unicodemath` joins the output of each node with a space, then replaces every character reference with its character and every ` / ` with `/`. It takes the keyword options `formatter:` (default `nil`), `unitsml:` (default `{}`) and `options:` (default `nil`). `formatter:` and `unitsml:` work as for MathML (PM 1003). `options:` is a prepared options hash and takes the place of the other two. + +[source,ruby] +---- +Plurimath::Math.parse("x^2 + frac(a)(b) + sqrt(x)", :asciimath).to_unicodemath +---- + +[source] +---- +x^(2) + (a)/(b) + √(x) +---- + +[source,ruby] +---- +Plurimath::Math.parse("alpha + oo", :asciimath).to_unicodemath +---- + +[source] +---- +α + ∞ +---- + +=== Constructs + +Each row below is read as UnicodeMath, written as AsciiMath, and written back as UnicodeMath from the same formula. A difference between the input and the "Written back" column shows what the writer normalises or changes: + +* scripts, fractions and roots are written with brackets, and operators with spaces around them; +* the operand of a large operator such as `∑` or `∫` is written after `▒` in `〖〗`; +* a function name is followed by U+2061 FUNCTION APPLICATION, which is invisible; +* a combining accent or overline is written after its base in brackets; +* `a¦b`, which UTN 28 defines as a stack without a bar, is read as a fraction, and written back with `¦`; +* a matrix in round brackets is written with `⒨`; a matrix with a bracket on one side is read with the right bracket as an unknown character, and written back as `Ⓢ`; +* a bold letter such as `𝐱` is kept as its character, which AsciiMath can only write as a character reference. + +.Constructs read and written back (produced at the pinned `plurimath` commit) +[cols="2,3l,3l,3l",options="header"] +|=== +|Construct |Input |AsciiMath |Written back +|Number |12.5 |12.5 |12.5 +|Letter |x |x |x +|Superscript |x^2 |x^(2) |x^(2) +|Subscript |x_i |x_(i) |x_(i) +|Both scripts |x_i^2 |x_(i)^(2) |x_(i)^(2) +|Fraction |a/b |frac(a)(b) |(a)/(b) +|Stacked, no bar |a¦b |frac(a)(b) |(a)¦(b) +|Square root |√x |sqrt(x) |√(x) +|Cube root |∛x |root(3)(x) |√(3&x) +|Root with index |√(3&x) |root(3)(x) |√(3&x) +|Sum with limits |∑_(i=1)^n i |sum_(i = 1)^(n) i |∑_(i = 1)^(n)▒〖i〗 +|Integral |∫_0^1 f(x) dx |int_(0)^(1) f (x) d x |∫_(0)^(1)▒〖f (x)〗 d x +|Limit |lim_(x→0) x |lim_(x to 0) x |lim_(x → 0) x +|Function name |sin x |sinx |sin⁡x +|Symbols |α+∞ |alpha + oo |α + ∞ +|Control word |\alpha |alpha |α +|Relation |x≤y |x le y |x ≤ y +|Brackets |(x) |(x) |(x) +|Matrix |■(a&b@c&d) |[[a, b], [c, d]] |■(a&b@c&d) +|Matrix in brackets |(■(a&b@c&d)) |([a, b], [c, d]) |⒨(a&b@c&d) +|Matrix in brackets, short form |⒨(a&b) |([a, b]) |⒨(a&b) +|Bracket on one side |{■(a&b)┤ |{[a, b]┤ |Ⓢ(a&b) +|Text |"if" |"if" |"if" +|Bold letter |𝐱 |𝐱 |𝐱 +|Combining accent |x̂ |overset(^)(x) |(x)̂ +|Combining overline |x̅ |overset("P{overbar}")(x) |(x)̅ +|Brace with label |⏞(x)^n |overset(n)(obrace(x)) |⏞(x)^(n) +|=== diff --git a/sources/pm-1008/sections/11-uncertainty.adoc b/sources/pm-1008/sections/11-uncertainty.adoc new file mode 100644 index 0000000..1e76ae1 --- /dev/null +++ b/sources/pm-1008/sections/11-uncertainty.adoc @@ -0,0 +1,51 @@ +== Measurement uncertainty and units + +A measurement result is written in the intent form `ⓘ("marker"visible)`. The marker is the same string MathML puts in `intent`; its grammar is specified in PM 1002. On reading, the marker is used and the visible content is regenerated. + +[source,ruby] +---- +Plurimath::Math.parse("ustd(1.230, 0.004)", :asciimath).to_unicodemath +---- + +[source] +---- +ⓘ("standard-uncertainty(1.230,0.004)"1.230(0.004)) +---- + +The reader cannot take a marker string followed directly by `-`, so a negative value that would start the visible content is put in the invisible `〖〗` group. The marker is unchanged: + +[source,ruby] +---- +Plurimath::Math.parse("ustd(-1.230, 0.004)", :asciimath).to_unicodemath +---- + +[source] +---- +ⓘ("standard-uncertainty(-1.230,0.004)"〖-1.230〗(0.004)) +---- + +A unit is written as `ⓐ(unit ...)` after the visible content and is referred to by `$unit` in the marker. A unit symbol of more than one character is written as quoted upright text, `\mup"kg"`, because UnicodeMath reads `\mupkg` as an upright `k` followed by `g`: + +[source,ruby] +---- +Plurimath::Math.parse(%q(ustd(1.2, 0.1, "unitsml(kg)")), :asciimath).to_unicodemath +---- + +[source] +---- +ⓘ("standard-uncertainty(1.2,0.1,$unit)"1.2(0.1)ⓐ(unit \mup"kg")) +---- + +[source,ruby] +---- +Plurimath::Math.parse("ⓘ(\"standard-uncertainty(1.2,0.1,$unit)\"1.2(0.1)ⓐ(unit \\mup\"kg\"))", :unicode).to_asciimath +---- + +[source] +---- +ustd(1.2, 0.1, "unitsml(kg)") +---- + +=== Round trips + +A unit read from UnicodeMath comes back as its rendered formula, not as a UnitsML node; written on to AsciiMath it becomes `"unitsml(...)"` again when its symbols are ASCII letters. A multi-letter unit written by hand as `\mupkg`, and `µm`, do not come back as one unit. The cases are in the round-trip matrix of PM 1002. diff --git a/sources/pm-1008/sections/12-errors.adoc b/sources/pm-1008/sections/12-errors.adoc new file mode 100644 index 0000000..3dadee2 --- /dev/null +++ b/sources/pm-1008/sections/12-errors.adoc @@ -0,0 +1,9 @@ +== Errors + +=== Refusal by the grammar + +Input the grammar does not match raises `Umath::ParseError`, with `char_offset` and `byte_offset` in the caller's text. The wording of the message is not part of the contract. Input nested too deeply for the engine raises `Umath::NestingTooDeep`. + +=== Refusal at the Plurimath boundary + +`Plurimath::Math.parse(text, :unicode)` raises `Plurimath::Math::ParseError` when the grammar rejects the text or the transform cannot build a node; the original error is not kept as the `cause`. A marker that does not match the marker grammar raises `Plurimath::Errors::InvalidUncertainty` inside, which also reaches the caller as a `ParseError`. A parse refusal is a refusal of the text; it is distinct from a refusal to name the format, which raises `Plurimath::Math::InvalidTypeError` (clause "Reading"). diff --git a/sources/pm-1008/sections/13-conformance.adoc b/sources/pm-1008/sections/13-conformance.adoc new file mode 100644 index 0000000..2d46b4f --- /dev/null +++ b/sources/pm-1008/sections/13-conformance.adoc @@ -0,0 +1,39 @@ +== Conformance + +=== General + +Conformance to this document is the implementation of the UnicodeMath reader per the clauses on preparation, structure and the typed model, and of the reader and writer per the clauses on Plurimath behaviour and on measurement results, against the artifact pinned in the clause "The grammar artifact". + +=== Conformance classes + +.Conformance classes +[cols="1,3,3", options="headers"] +|=== +|Class |Licenses the implementation to claim |Replay requirements + +|read-unicodemath +|reads the notation of this document and refuses what the grammar refuses +|the `corpus/unicode/` rows of the testsuite, and the `stages/unicode/` generation pinned by `spec/fixtures/testsuite-pin.yml` of the `umath` gem + +|write-unicodemath +|writes UnicodeMath from the formula tree +|the `unicodemath` target of every `corpus/*/` case, byte for byte + +|roundtrip-unicodemath +|writes a formula as UnicodeMath and reads it back, with the lossless, lossy and refused cases of the roundtrip generation +|the `stages/roundtrip/` generation pinned by `spec/fixtures/roundtrip-pin.yml` of the `plurimath` gem +|=== + +=== The corpora + +* `spec/model/` of the `umath` gem checks construction of the model and its shape. +* `spec/corpus/replay_corpus_spec.rb` and `spec/stage_cases/` of the `umath` gem replay the stage corpus generation pinned in `spec/fixtures/testsuite-pin.yml` (plurimath-testsuite `stages/unicode/`, commit `85c7be8fd56f0cc64b4869e74716acc4f0dbe746`, generation 4, 72 cases). +* The oracle specs of the `umath` gem compare the raw tree with captures of the Plurimath parser. +* `spec/conformance/shared_corpus_spec.rb` of the `plurimath` gem replays every `corpus/` case, comparing each target byte for byte. At testsuite commit `337262eda0483ceaa43a02cc52362c5b721e5eb3` these are 20 `corpus/unicode/` inputs read (groups `fences`, `numbers`, `operators`, `symbols`), 52 `corpus/unicode/rejections.yaml` inputs refused, and 780 `corpus/*/` cases with a `unicodemath` output in 74 payloads. +* `spec/conformance/stage_roundtrips_spec.rb` of the `plurimath` gem replays the roundtrip generation pinned in `spec/fixtures/roundtrip-pin.yml`: `stages/roundtrip/generations/000001/payloads/` has 46 cases written as `unicode` and read back, of which 33 are lossless, 9 lossy and 4 refused. +* `spec/plurimath/unicode_math/uncertainty_spec.rb`, `spec/plurimath/unicode_math/uncertainty_units_spec.rb` and `spec/plurimath/fixtures/uncertainty/contract.yml` of the `plurimath` gem check the marker and units. +* The `stages/unicode/` generations are replayed by the `umath` gem, not by the `plurimath` gem. + +=== Claims + +A claim names the artifact checksum of the clause "The grammar artifact" and the testsuite commit and generation. An implementation against a moved artifact makes a different claim. diff --git a/sources/pm-1008/sections/90-annex-a.adoc b/sources/pm-1008/sections/90-annex-a.adoc new file mode 100644 index 0000000..335a020 --- /dev/null +++ b/sources/pm-1008/sections/90-annex-a.adoc @@ -0,0 +1,80 @@ +== Annex A: examples of the typed model + +These results were produced by parsing each input with `Umath.parse` at the pinned `umath` commit and printing the non-empty fields of the model. A symbol is shown as `MathSymbol(spelling)`; the spelling is the encoded text the grammar matched. Fields inside each class are printed in the order the class declares them, not in input order. + +[source] +---- +a/b + Expression(frac: Frac(denominator: Expression(factor: Expression(atom: Atom(alphanumeric: MathSymbol("b")))), + numerator: Expression(atom: Atom(alphanumeric: MathSymbol("a"))))) + +x^2 + Expression(sup_exp: SupExp(base: Expression(symbol: SymbolNode(spelling: "x")), + sup: Expression(sup_script: Expression(operand: Operand(factor: Expression(digit: Digit(number: "2"))))))) + +√x + Expression(factor: Expression(root: RootNode(first_value: Expression(factor: Expression(atom: + Atom(alphanumeric: MathSymbol("x")))), root_symbol: MathSymbol("√")))) + +√(3&x) + Expression(factor: Expression(root: RootNode( + first_value: Expression(expr: Expression(empty: "", factor: Expression(digit: Digit(number: "3")))), + second_value: SecondValue(expr: Expression(empty: "", factor: Expression(atom: Atom(alphanumeric: MathSymbol("x")))))))) + +sin x + Expression(unary_subsup: UnarySubsup(first_value: Expression(factor: Expression(atom: + Atom(alphanumeric: MathSymbol("x")))), unary_functions: "sin")) + +(a+b) + Expression(factor: Expression(intermediate_exp: Expression(close_paren: Paren(spelling: ")"), + exp: Expression(exp: Expression(factor: Expression(atom: Atom(alphanumeric: MathSymbol("b")))), + operator: MathSymbol("+")), factor: Expression(atom: Atom(alphanumeric: MathSymbol("a"))), + open_paren: Paren(spelling: "(")))) + +■(a&b@c&d) + Expression(table: Table(array: ArrayNode( + tr: Tr(td: Td(exp: Expression(factor: Expression(atom: Atom(alphanumeric: MathSymbol("a"))))), + tds: Tds(td: Td(exp: Expression(factor: Expression(atom: Atom(alphanumeric: MathSymbol("b"))))))), + trs: Trs(tr: Tr(td: Td(exp: Expression(factor: Expression(atom: Atom(alphanumeric: MathSymbol("c"))))), + tds: Tds(td: Td(exp: Expression(factor: Expression(atom: Atom(alphanumeric: MathSymbol("d"))))))))), + matrixs: "■")) + +■3 + Expression(table: Table(identity_matrix_number: "3", matrixs: "■")) + +ᵃ/ₙ + Expression(frac: Frac(mini_denominator: MiniDenominator(sub_alpha: "ₙ"), + mini_numerator: MiniNumerator(sup_alpha: "ᵃ"))) + +(a¦b) + Expression(factor: Expression(intermediate_exp: Expression(close_paren: Paren(spelling: ")"), + frac: Frac(atop: "¦", denominator: Expression(factor: Expression(atom: Atom(alphanumeric: MathSymbol("b")))), + numerator: Expression(atom: Atom(alphanumeric: MathSymbol("a")))), open_paren: Paren(spelling: "(")))) + +x̂ + Expression(accents: Accents(empty: "", first_value: Expression(atom: Atom(alphanumeric: MathSymbol("x"))), + list: [ListItem(accent_symbols: MathSymbol("̂"))])) + +□a + Expression(factor: Expression(ordinary_symbols: MathSymbol("□")), + operand: Operand(factor: Expression(atom: Atom(alphanumeric: MathSymbol("a"))))) + +α + Expression(factor: Expression(ordinary_symbols: MathSymbol("α"))) + +\alpha + Expression(factor: Expression(ordinary_symbols: MathSymbol("alpha"))) + +𝐱 + Expression(factor: Expression(atom: Atom(char: Char(unicode_symbols: MathSymbol("𝐱"))))) + +1.5 + Expression(factor: Expression(decimal_number: DecimalNumber(decimal: ".", + fractional: Fractional(number: "5"), whole: Whole(number: "1")))) + +a#(1) + Expression(factor: Expression(atom: Atom(alphanumeric: MathSymbol("a")))), label "(1)" + +⫷c⫸x + Expression(factor: Expression(atom: Atom(alphanumeric: MathSymbol("x")))) +---- diff --git a/sources/pm-1008/sections/91-annex-b.adoc b/sources/pm-1008/sections/91-annex-b.adoc new file mode 100644 index 0000000..fcd626d --- /dev/null +++ b/sources/pm-1008/sections/91-annex-b.adoc @@ -0,0 +1,7 @@ +== Annex B: open questions + +These points are not specified; the notation described here is what the pinned artifact does. + +* The grammar spells `\cbrt` for both the cube root and the fourth root (rules `cbrt_symbols` and `qdrt_symbols`), so the fourth root has no command name of its own. Whether that is intended: not specified. +* When the examples of the `umath` page were generated, parsing `(`, `a/` and `\cbrt x` did not finish within several minutes, so that page shows no refusal example and no result for `\cbrt`. Whether these inputs are expected to be slow: not specified. +* Labels: parts between the first and the last `#` are dropped. Whether that is intended: not specified. diff --git a/sources/pm-1008/sections/98-bibliography.adoc b/sources/pm-1008/sections/98-bibliography.adoc new file mode 100644 index 0000000..8c53531 --- /dev/null +++ b/sources/pm-1008/sections/98-bibliography.adoc @@ -0,0 +1,8 @@ +[bibliography] +== Bibliography + +* [[[plurimath-repo,nofetch(Plurimath repository)]]] — https://github.com/plurimath/plurimath +* [[[umath-repo,nofetch(umath repository)]]] — https://github.com/plurimath/unicodemath +* [[[pm-testsuite,nofetch(plurimath-testsuite)]]] — the pinned corpus repository and its generations +* [[[pm1005-b,nofetch(PM 1005)]]] of this series +* [[[pm1007-b,nofetch(PM 1007)]]] of this series