plurimath 0.11.16 → 0.11.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (189) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/dependent-tests.yml +2 -2
  3. data/.github/workflows/docs.yml +26 -0
  4. data/.github/workflows/gum-reference.yml +48 -0
  5. data/.github/workflows/performance-ci-legs.yml +54 -0
  6. data/.github/workflows/performance.yml +99 -0
  7. data/.github/workflows/roundtrip-cases.yml +33 -0
  8. data/.rubocop_todo.yml +0 -138
  9. data/Gemfile +13 -0
  10. data/Rakefile +2 -0
  11. data/docs/asciimath.adoc +578 -0
  12. data/docs/core-model-contract.adoc +748 -0
  13. data/docs/gum-evaluation.adoc +368 -0
  14. data/docs/latex.adoc +335 -0
  15. data/docs/mathml.adoc +638 -0
  16. data/docs/native-evaluation-request.md +28 -0
  17. data/docs/numeric-request.md +19 -0
  18. data/docs/omml.adoc +589 -0
  19. data/docs/performance-contract.adoc +279 -0
  20. data/docs/pma.adoc +949 -0
  21. data/docs/quantity-request.md +19 -0
  22. data/docs/uncertainty-asciimath-tree.md +2 -3
  23. data/docs/uncertainty.adoc +401 -425
  24. data/docs/unicodemath.adoc +453 -0
  25. data/docs/unitsml.adoc +414 -0
  26. data/lib/plurimath/asciimath/constants.rb +0 -98
  27. data/lib/plurimath/asciimath/mapper/rules.rb +1400 -0
  28. data/lib/plurimath/asciimath/mapper.rb +148 -0
  29. data/lib/plurimath/asciimath/parse.rb +26 -18
  30. data/lib/plurimath/asciimath/parser.rb +25 -11
  31. data/lib/plurimath/asciimath/slice_adapter.rb +1 -1
  32. data/lib/plurimath/asciimath.rb +1 -1
  33. data/lib/plurimath/catalog.rb +4 -5
  34. data/lib/plurimath/cli/convert.rb +3 -2
  35. data/lib/plurimath/cli.rb +2 -1
  36. data/lib/plurimath/configuration.rb +3 -0
  37. data/lib/plurimath/evaluation_request/quantity.rb +254 -0
  38. data/lib/plurimath/evaluation_request.rb +160 -0
  39. data/lib/plurimath/latex/constants.rb +0 -84
  40. data/lib/plurimath/latex/mapper.rb +418 -0
  41. data/lib/plurimath/latex/parse.rb +28 -288
  42. data/lib/plurimath/latex/parser.rb +49 -4
  43. data/lib/plurimath/latex.rb +1 -1
  44. data/lib/plurimath/math/core.rb +266 -1
  45. data/lib/plurimath/math/evaluation/accuracy.rb +62 -0
  46. data/lib/plurimath/math/evaluation/calibration.rb +85 -0
  47. data/lib/plurimath/math/evaluation/compiled_polynomial.rb +99 -0
  48. data/lib/plurimath/math/evaluation/compiled_rational.rb +131 -0
  49. data/lib/plurimath/math/evaluation/conformity.rb +133 -0
  50. data/lib/plurimath/math/evaluation/correlated_normal_sampler.rb +74 -0
  51. data/lib/plurimath/math/evaluation/covariance.rb +173 -0
  52. data/lib/plurimath/math/evaluation/distribution_sampler.rb +126 -0
  53. data/lib/plurimath/math/evaluation/evaluator.rb +236 -22
  54. data/lib/plurimath/math/evaluation/grouped_statistics.rb +56 -0
  55. data/lib/plurimath/math/evaluation/gum.rb +410 -0
  56. data/lib/plurimath/math/evaluation/implicit_model.rb +66 -0
  57. data/lib/plurimath/math/evaluation/monte_carlo.rb +198 -0
  58. data/lib/plurimath/math/evaluation/quantity_evaluator.rb +127 -0
  59. data/lib/plurimath/math/evaluation/result.rb +45 -0
  60. data/lib/plurimath/math/evaluation/statistics.rb +102 -0
  61. data/lib/plurimath/math/evaluation/taylor.rb +162 -0
  62. data/lib/plurimath/math/evaluation/wichmann_hill.rb +40 -0
  63. data/lib/plurimath/math/evaluation.rb +22 -0
  64. data/lib/plurimath/math/formula/mrow.rb +6 -1
  65. data/lib/plurimath/math/formula.rb +22 -4
  66. data/lib/plurimath/math/function/abs.rb +3 -1
  67. data/lib/plurimath/math/function/arccos.rb +1 -1
  68. data/lib/plurimath/math/function/arcsin.rb +1 -1
  69. data/lib/plurimath/math/function/arctan.rb +1 -1
  70. data/lib/plurimath/math/function/bar.rb +2 -1
  71. data/lib/plurimath/math/function/base.rb +2 -1
  72. data/lib/plurimath/math/function/binary_function.rb +1 -1
  73. data/lib/plurimath/math/function/ceil.rb +3 -1
  74. data/lib/plurimath/math/function/color.rb +2 -1
  75. data/lib/plurimath/math/function/cos.rb +1 -1
  76. data/lib/plurimath/math/function/cosh.rb +1 -1
  77. data/lib/plurimath/math/function/cot.rb +1 -1
  78. data/lib/plurimath/math/function/coth.rb +1 -1
  79. data/lib/plurimath/math/function/csc.rb +1 -1
  80. data/lib/plurimath/math/function/csch.rb +1 -1
  81. data/lib/plurimath/math/function/ddot.rb +2 -1
  82. data/lib/plurimath/math/function/dot.rb +2 -1
  83. data/lib/plurimath/math/function/exp.rb +1 -1
  84. data/lib/plurimath/math/function/fenced.rb +5 -3
  85. data/lib/plurimath/math/function/floor.rb +3 -1
  86. data/lib/plurimath/math/function/font_style/bold.rb +1 -1
  87. data/lib/plurimath/math/function/font_style/double_struck.rb +1 -1
  88. data/lib/plurimath/math/function/font_style/fraktur.rb +1 -1
  89. data/lib/plurimath/math/function/font_style/italic.rb +1 -1
  90. data/lib/plurimath/math/function/font_style/monospace.rb +1 -1
  91. data/lib/plurimath/math/function/font_style/normal.rb +22 -1
  92. data/lib/plurimath/math/function/font_style/sans-serif.rb +1 -1
  93. data/lib/plurimath/math/function/font_style/script.rb +1 -1
  94. data/lib/plurimath/math/function/frac.rb +2 -1
  95. data/lib/plurimath/math/function/hat.rb +2 -1
  96. data/lib/plurimath/math/function/int.rb +3 -2
  97. data/lib/plurimath/math/function/lg.rb +1 -1
  98. data/lib/plurimath/math/function/linebreak.rb +2 -1
  99. data/lib/plurimath/math/function/ln.rb +1 -1
  100. data/lib/plurimath/math/function/log.rb +4 -1
  101. data/lib/plurimath/math/function/longdiv.rb +3 -0
  102. data/lib/plurimath/math/function/mpadded.rb +2 -1
  103. data/lib/plurimath/math/function/msgroup.rb +3 -0
  104. data/lib/plurimath/math/function/multiscript.rb +4 -0
  105. data/lib/plurimath/math/function/nary.rb +9 -3
  106. data/lib/plurimath/math/function/norm.rb +3 -1
  107. data/lib/plurimath/math/function/obrace.rb +2 -1
  108. data/lib/plurimath/math/function/oint.rb +3 -2
  109. data/lib/plurimath/math/function/overleftrightarrow.rb +2 -1
  110. data/lib/plurimath/math/function/overset.rb +2 -1
  111. data/lib/plurimath/math/function/power.rb +1 -1
  112. data/lib/plurimath/math/function/power_base.rb +1 -1
  113. data/lib/plurimath/math/function/prod.rb +3 -2
  114. data/lib/plurimath/math/function/sec.rb +1 -1
  115. data/lib/plurimath/math/function/sech.rb +1 -1
  116. data/lib/plurimath/math/function/semantics.rb +35 -0
  117. data/lib/plurimath/math/function/sin.rb +1 -1
  118. data/lib/plurimath/math/function/sinh.rb +1 -1
  119. data/lib/plurimath/math/function/sqrt.rb +3 -2
  120. data/lib/plurimath/math/function/sum.rb +3 -2
  121. data/lib/plurimath/math/function/table/align.rb +1 -1
  122. data/lib/plurimath/math/function/table/bmatrix.rb +1 -1
  123. data/lib/plurimath/math/function/table/cases.rb +4 -0
  124. data/lib/plurimath/math/function/table/multline.rb +1 -1
  125. data/lib/plurimath/math/function/table/pmatrix.rb +1 -1
  126. data/lib/plurimath/math/function/table/split.rb +1 -1
  127. data/lib/plurimath/math/function/table/vmatrix.rb +1 -1
  128. data/lib/plurimath/math/function/table.rb +19 -2
  129. data/lib/plurimath/math/function/tan.rb +1 -1
  130. data/lib/plurimath/math/function/tanh.rb +1 -1
  131. data/lib/plurimath/math/function/td.rb +4 -0
  132. data/lib/plurimath/math/function/ternary_function.rb +2 -2
  133. data/lib/plurimath/math/function/text.rb +3 -0
  134. data/lib/plurimath/math/function/tilde.rb +2 -1
  135. data/lib/plurimath/math/function/tr.rb +3 -0
  136. data/lib/plurimath/math/function/ubrace.rb +2 -1
  137. data/lib/plurimath/math/function/ul.rb +2 -1
  138. data/lib/plurimath/math/function/unary_function.rb +1 -1
  139. data/lib/plurimath/math/function/uncertainty.rb +26 -11
  140. data/lib/plurimath/math/function/underset.rb +2 -1
  141. data/lib/plurimath/math/function/unitsml.rb +18 -6
  142. data/lib/plurimath/math/function/vec.rb +2 -1
  143. data/lib/plurimath/math/number.rb +30 -12
  144. data/lib/plurimath/math/symbol_index.rb +10254 -0
  145. data/lib/plurimath/math/symbol_table.rb +89 -0
  146. data/lib/plurimath/math/symbols/paren.rb +7 -0
  147. data/lib/plurimath/math/symbols/symbol.rb +30 -3
  148. data/lib/plurimath/math/symbols.rb +81 -5
  149. data/lib/plurimath/math.rb +8 -0
  150. data/lib/plurimath/mathml/parser.rb +2 -0
  151. data/lib/plurimath/mathml/translator.rb +17 -3
  152. data/lib/plurimath/native_kernel.rb +64 -0
  153. data/lib/plurimath/omml/parser.rb +1 -0
  154. data/lib/plurimath/omml/translator.rb +2 -1
  155. data/lib/plurimath/pma.rb +19 -0
  156. data/lib/plurimath/unicode_math/constants.rb +0 -258
  157. data/lib/plurimath/unicode_math/mapper/capture_order.rb +142 -0
  158. data/lib/plurimath/unicode_math/mapper/rules.rb +4086 -0
  159. data/lib/plurimath/unicode_math/mapper.rb +146 -0
  160. data/lib/plurimath/unicode_math/parse.rb +54 -294
  161. data/lib/plurimath/unicode_math/parser.rb +71 -2
  162. data/lib/plurimath/unicode_math.rb +1 -2
  163. data/lib/plurimath/unitsml.rb +0 -1
  164. data/lib/plurimath/utility.rb +34 -12
  165. data/lib/plurimath/version.rb +1 -1
  166. data/lib/plurimath.rb +42 -3
  167. data/plurimath.gemspec +3 -1
  168. data/scripts/check_gum_references.rb +69 -0
  169. data/scripts/check_suite_budget.rb +329 -0
  170. data/scripts/docs/asciimath_tables.rb +363 -0
  171. data/scripts/docs/core_inventory.rb +432 -0
  172. data/scripts/docs/format_specs.rb +672 -0
  173. data/scripts/generate_symbol_index.rb +118 -0
  174. data/scripts/measure_require.rb +362 -0
  175. data/scripts/replay_asciimath_corpus.rb +7 -7
  176. data/scripts/replay_stage_roundtrips.rb +242 -0
  177. data/scripts/require_baseline.json +34 -0
  178. data/scripts/roundtrip_cases.rb +462 -0
  179. metadata +97 -16
  180. data/lib/plurimath/asciimath/transform.rb +0 -1395
  181. data/lib/plurimath/latex/transform.rb +0 -1006
  182. data/lib/plurimath/unicode_math/parsing_rules/absence_rules.rb +0 -150
  183. data/lib/plurimath/unicode_math/parsing_rules/common_rules.rb +0 -136
  184. data/lib/plurimath/unicode_math/parsing_rules/constants_rules.rb +0 -136
  185. data/lib/plurimath/unicode_math/parsing_rules/helper.rb +0 -13
  186. data/lib/plurimath/unicode_math/parsing_rules/masked.rb +0 -84
  187. data/lib/plurimath/unicode_math/parsing_rules/sub_sup.rb +0 -281
  188. data/lib/plurimath/unicode_math/parsing_rules.rb +0 -14
  189. data/lib/plurimath/unicode_math/transform.rb +0 -4058
data/docs/omml.adoc ADDED
@@ -0,0 +1,589 @@
1
+ = OMML in Plurimath
2
+ :toc:
3
+
4
+ This page specifies the Office Math Markup Language (OMML) that Plurimath
5
+ reads and writes: how input is parsed, the shape of the output and its
6
+ options, how measurement results are hidden in a phantom, what does not
7
+ survive a round trip through Word or through Plurimath itself, the errors,
8
+ and the corpora that check all of this. It is part of the specification set
9
+ tracked in https://github.com/plurimath/plurimath/issues/525[#525].
10
+
11
+ The option table, the namespace table, the element tables, the examples and
12
+ the corpus counts on this page are generated (see <<regenerating>>). Each example is Ruby code that
13
+ the generator runs; the block after it is what that code returned. In OMML
14
+ examples the namespace declarations on `m:oMathPara`, which are the same for
15
+ every output and listed in <<writing>>, are shown as `xmlns:m="..." ...`.
16
+
17
+ == Status
18
+
19
+ [cols="3,1,3"]
20
+ |===
21
+ |Part |Status |Where
22
+
23
+ |Reading OMML through the omml gem's typed model
24
+ |implemented
25
+ |https://github.com/plurimath/plurimath/pull/414[#414],
26
+ https://github.com/plurimath/plurimath/pull/463[#463]
27
+
28
+ |Writing OMML
29
+ |implemented
30
+ |
31
+
32
+ |Measurement results as a hidden phantom marker, read and written
33
+ |implemented
34
+ |https://github.com/plurimath/plurimath/pull/496[#496],
35
+ https://github.com/plurimath/plurimath/pull/497[#497],
36
+ https://github.com/plurimath/plurimath/pull/504[#504],
37
+ https://github.com/plurimath/plurimath/pull/505[#505]
38
+
39
+ |Decimal runs read as numbers
40
+ |implemented
41
+ |https://github.com/plurimath/plurimath/pull/503[#503]
42
+
43
+ |Explicit unit spacing kept in Word output
44
+ |implemented
45
+ |https://github.com/plurimath/plurimath/pull/518[#518]
46
+
47
+ |Checking that Word keeps the hidden phantom when an equation is edited
48
+ |proposed
49
+ |https://github.com/plurimath/plurimath/issues/524[#524]
50
+ |===
51
+
52
+ [[reading]]
53
+ == Reading
54
+
55
+ `Plurimath::Math.parse(text, :omml)` hands the text to
56
+ `Plurimath::Omml::Parser`, which calls `::Omml.parse(text)` from the omml gem
57
+ and turns the typed model into a `Plurimath::Math::Formula` with
58
+ `Plurimath::Omml::Translator`. Both an `m:oMathPara` and a bare `m:oMath` are
59
+ accepted.
60
+
61
+ The text of an `m:r` run is read as text, except for numbers and function
62
+ names. A run that Word writes for a variable is therefore not an identifier
63
+ after reading. An `m:sty` style is kept as a font:
64
+
65
+ // BEGIN GENERATED example read-styled
66
+ [source,ruby]
67
+ ----
68
+ Plurimath::Math.parse('<m:oMath xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math"><m:r><m:rPr><m:sty m:val="i"/></m:rPr><m:t>x</m:t></m:r></m:oMath>', :omml).to_asciimath
69
+ ----
70
+
71
+ [source]
72
+ ----
73
+ ii("x")
74
+ ----
75
+ // END GENERATED example read-styled
76
+
77
+ An element that the omml model does not know is dropped without an error:
78
+
79
+ // BEGIN GENERATED example read-unknown
80
+ [source,ruby]
81
+ ----
82
+ Plurimath::Math.parse('<m:oMath xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math"><m:foo/></m:oMath>', :omml).to_asciimath.inspect
83
+ ----
84
+
85
+ [source]
86
+ ----
87
+ ""
88
+ ----
89
+ // END GENERATED example read-unknown
90
+
91
+ An `m:oMathPara` inside an `m:oMath` or inside an argument is read as its
92
+ content, the same way as the outer `m:oMathPara`:
93
+
94
+ // BEGIN GENERATED example read-nested-para
95
+ [source,ruby]
96
+ ----
97
+ Plurimath::Math.parse('<m:oMath xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math"><m:sSup><m:e><m:oMathPara><m:oMath><m:r><m:t>x</m:t></m:r></m:oMath></m:oMathPara></m:e><m:sup><m:r><m:t>2</m:t></m:r></m:sup></m:sSup></m:oMath>', :omml).to_asciimath
98
+ ----
99
+
100
+ [source]
101
+ ----
102
+ "x"^(2)
103
+ ----
104
+ // END GENERATED example read-nested-para
105
+
106
+ The translator raises `Plurimath::Omml::UnsupportedNodeError` for a model
107
+ node it has no rule for; `Plurimath::Math.parse` reports it as a
108
+ `ParseError` (see <<errors>>). The omml model reads the WordprocessingML
109
+ elements below in the `m:` namespace, and Plurimath has no node for them, so
110
+ they are refused there. Written with the `w:` prefix, the model does not
111
+ know them, and they are dropped like any unknown element.
112
+
113
+ * Inside `m:oMath` or an argument: the revision containers `m:ins`,
114
+ `m:del`, `m:moveFrom` and `m:moveTo`, and the range markers
115
+ `m:bookmarkStart`, `m:bookmarkEnd`, `m:commentRangeStart`,
116
+ `m:commentRangeEnd`, `m:moveFromRangeStart`, `m:moveFromRangeEnd`,
117
+ `m:moveToRangeStart`, `m:moveToRangeEnd`, `m:permStart`, `m:permEnd`,
118
+ `m:proofErr`, and the `m:customXml...RangeStart` and
119
+ `m:customXml...RangeEnd` elements.
120
+ * Inside `m:r`: `m:sym`, `m:ptab`, `m:fldChar`, `m:footnoteReference`,
121
+ `m:endnoteReference`, `m:commentReference`, `m:object`, `m:pict`,
122
+ `m:drawing` and `m:ruby`.
123
+
124
+ [[writing]]
125
+ == Writing
126
+
127
+ `Formula#to_omml` returns one `m:oMathPara` holding one `m:oMath`, indented
128
+ by two spaces. The `m:oMathPara` element always declares these namespaces,
129
+ taken from `Plurimath::Math::Formula::OMML_NAMESPACES`:
130
+
131
+ // BEGIN GENERATED omml-namespaces
132
+ [cols="1,3"]
133
+ |===
134
+ |Declaration |Namespace
135
+
136
+ |`xmlns:m` |`http://schemas.openxmlformats.org/officeDocument/2006/math`
137
+ |`xmlns:mc` |`http://schemas.openxmlformats.org/markup-compatibility/2006`
138
+ |`xmlns:mo` |`http://schemas.microsoft.com/office/mac/office/2008/main`
139
+ |`xmlns:mv` |`urn:schemas-microsoft-com:mac:vml`
140
+ |`xmlns:o` |`urn:schemas-microsoft-com:office:office`
141
+ |`xmlns:r` |`http://schemas.openxmlformats.org/officeDocument/2006/relationships`
142
+ |`xmlns:v` |`urn:schemas-microsoft-com:vml`
143
+ |`xmlns:w` |`http://schemas.openxmlformats.org/wordprocessingml/2006/main`
144
+ |`xmlns:w10` |`urn:schemas-microsoft-com:office:word`
145
+ |`xmlns:w14` |`http://schemas.microsoft.com/office/word/2010/wordml`
146
+ |`xmlns:w15` |`http://schemas.microsoft.com/office/word/2012/wordml`
147
+ |`xmlns:wne` |`http://schemas.microsoft.com/office/word/2006/wordml`
148
+ |`xmlns:wp` |`http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing`
149
+ |`xmlns:wp14` |`http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing`
150
+ |`xmlns:wpc` |`http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas`
151
+ |`xmlns:wpg` |`http://schemas.microsoft.com/office/word/2010/wordprocessingGroup`
152
+ |`xmlns:wpi` |`http://schemas.microsoft.com/office/word/2010/wordprocessingInk`
153
+ |`xmlns:wps` |`http://schemas.microsoft.com/office/word/2010/wordprocessingShape`
154
+ |===
155
+ // END GENERATED omml-namespaces
156
+
157
+ // BEGIN GENERATED writer-options
158
+ `Plurimath::Math::Formula#to_omml` in `lib/plurimath/math/formula.rb` takes these keyword options:
159
+
160
+ [cols="1,1"]
161
+ |===
162
+ |Option |Default
163
+
164
+ |`display_style:` |`displaystyle`
165
+ |`split_on_linebreak:` |`false`
166
+ |`formatter:` |`nil`
167
+ |`unitsml:` |`{}`
168
+ |===
169
+ // END GENERATED writer-options
170
+
171
+ * `display_style:` defaults to the display style the formula was read with.
172
+ It decides how limits are placed: under and over the operator in display
173
+ style, as scripts otherwise (see the two `lim` examples).
174
+ * `split_on_linebreak:` writes one `m:oMath` per line of the formula, with an
175
+ `m:r` holding a `br` element between them, inside the same `m:oMathPara`.
176
+ The `br` has no namespace prefix (it is not `w:br`), as the example
177
+ shows.
178
+ * `formatter:` and `unitsml:` work as for MathML (see
179
+ link:mathml.adoc#writing[MathML in Plurimath]).
180
+
181
+ Script elements such as `m:sSup` carry an `m:ctrlPr` with Cambria Math run
182
+ properties:
183
+
184
+ // BEGIN GENERATED example write
185
+ [source,ruby]
186
+ ----
187
+ Plurimath::Math.parse("x^2", :asciimath).to_omml
188
+ ----
189
+
190
+ [source,xml]
191
+ ----
192
+ <m:oMathPara xmlns:m="..." ...>
193
+ <m:oMath>
194
+ <m:sSup>
195
+ <m:sSupPr>
196
+ <m:ctrlPr>
197
+ <w:rPr>
198
+ <w:rFonts w:ascii="Cambria Math" w:hAnsi="Cambria Math"/>
199
+ <w:i/>
200
+ </w:rPr>
201
+ </m:ctrlPr>
202
+ </m:sSupPr>
203
+ <m:e>
204
+ <m:r>
205
+ <m:t>x</m:t>
206
+ </m:r>
207
+ </m:e>
208
+ <m:sup>
209
+ <m:r>
210
+ <m:t>2</m:t>
211
+ </m:r>
212
+ </m:sup>
213
+ </m:sSup>
214
+ </m:oMath>
215
+ </m:oMathPara>
216
+ ----
217
+ // END GENERATED example write
218
+
219
+ // BEGIN GENERATED example limits-display
220
+ [source,ruby]
221
+ ----
222
+ Plurimath::Math.parse("lim_(x->0) x", :asciimath).to_omml
223
+ ----
224
+
225
+ [source,xml]
226
+ ----
227
+ <m:oMathPara xmlns:m="..." ...>
228
+ <m:oMath>
229
+ <m:limLow>
230
+ <m:limLowPr>
231
+ <m:ctrlPr>
232
+ <w:rPr>
233
+ <w:rFonts w:ascii="Cambria Math" w:hAnsi="Cambria Math"/>
234
+ <w:i/>
235
+ </w:rPr>
236
+ </m:ctrlPr>
237
+ </m:limLowPr>
238
+ <m:e>
239
+ <m:limUpp>
240
+ <m:limUppPr>
241
+ <m:ctrlPr>
242
+ <w:rPr>
243
+ <w:rFonts w:ascii="Cambria Math" w:hAnsi="Cambria Math"/>
244
+ <w:i/>
245
+ </w:rPr>
246
+ </m:ctrlPr>
247
+ </m:limUppPr>
248
+ <m:e>
249
+ <m:r>
250
+ <m:t>lim</m:t>
251
+ </m:r>
252
+ </m:e>
253
+ <m:lim>
254
+ <m:r>
255
+ <m:t>&#8203;</m:t>
256
+ </m:r>
257
+ </m:lim>
258
+ </m:limUpp>
259
+ </m:e>
260
+ <m:lim>
261
+ <m:r>
262
+ <m:t>x</m:t>
263
+ </m:r>
264
+ <m:r>
265
+ <m:t>&#x2192;</m:t>
266
+ </m:r>
267
+ <m:r>
268
+ <m:t>0</m:t>
269
+ </m:r>
270
+ </m:lim>
271
+ </m:limLow>
272
+ <m:r>
273
+ <m:t>x</m:t>
274
+ </m:r>
275
+ </m:oMath>
276
+ </m:oMathPara>
277
+ ----
278
+ // END GENERATED example limits-display
279
+
280
+ // BEGIN GENERATED example limits-inline
281
+ [source,ruby]
282
+ ----
283
+ Plurimath::Math.parse("lim_(x->0) x", :asciimath).to_omml(display_style: false)
284
+ ----
285
+
286
+ [source,xml]
287
+ ----
288
+ <m:oMathPara xmlns:m="..." ...>
289
+ <m:oMath>
290
+ <m:sSubSup>
291
+ <m:sSubSupPr>
292
+ <m:ctrlPr>
293
+ <w:rPr>
294
+ <w:rFonts w:ascii="Cambria Math" w:hAnsi="Cambria Math"/>
295
+ <w:i/>
296
+ </w:rPr>
297
+ </m:ctrlPr>
298
+ </m:sSubSupPr>
299
+ <m:e>
300
+ <m:r>
301
+ <m:t>lim</m:t>
302
+ </m:r>
303
+ </m:e>
304
+ <m:sub>
305
+ <m:r>
306
+ <m:t>x</m:t>
307
+ </m:r>
308
+ <m:r>
309
+ <m:t>&#x2192;</m:t>
310
+ </m:r>
311
+ <m:r>
312
+ <m:t>0</m:t>
313
+ </m:r>
314
+ </m:sub>
315
+ <m:sup>
316
+ <m:r>
317
+ <m:t>&#8203;</m:t>
318
+ </m:r>
319
+ </m:sup>
320
+ </m:sSubSup>
321
+ <m:r>
322
+ <m:t>x</m:t>
323
+ </m:r>
324
+ </m:oMath>
325
+ </m:oMathPara>
326
+ ----
327
+ // END GENERATED example limits-inline
328
+
329
+ // BEGIN GENERATED example linebreak
330
+ [source,ruby]
331
+ ----
332
+ Plurimath::Math.parse("a = b \\\\ c = d", :latex).to_omml(split_on_linebreak: true)
333
+ ----
334
+
335
+ [source,xml]
336
+ ----
337
+ <m:oMathPara xmlns:m="..." ...>
338
+ <m:oMath>
339
+ <m:r>
340
+ <m:t>a</m:t>
341
+ </m:r>
342
+ <m:r>
343
+ <m:t>=</m:t>
344
+ </m:r>
345
+ <m:r>
346
+ <m:t>b</m:t>
347
+ </m:r>
348
+ </m:oMath>
349
+ <m:r>
350
+ <br/>
351
+ </m:r>
352
+ <m:oMath>
353
+ <m:r>
354
+ <m:t>c</m:t>
355
+ </m:r>
356
+ <m:r>
357
+ <m:t>=</m:t>
358
+ </m:r>
359
+ <m:r>
360
+ <m:t>d</m:t>
361
+ </m:r>
362
+ </m:oMath>
363
+ </m:oMathPara>
364
+ ----
365
+ // END GENERATED example linebreak
366
+
367
+ [[elements]]
368
+ == Elements
369
+
370
+ The first table lists, for each OMML element that the omml model reads into
371
+ a class, the translator method that turns it into a Plurimath node. It is
372
+ read from the `case` statement of the translator, and the element names are
373
+ found by following the omml model's XML mappings from `m:oMathPara` and
374
+ `m:oMath`. An element marked "ignored" is read but gives no node. The
375
+ WordprocessingML elements, and the `m:` elements with Word names such as
376
+ `m:bibliography`, are listed because the model reaches them from a run.
377
+
378
+ // BEGIN GENERATED elements-read
379
+ `translate_omml_node` in `lib/plurimath/omml/translator.rb` handles these model classes:
380
+
381
+ [cols="2,2,3",options="header"]
382
+ |===
383
+ |Element |Model class |Read by
384
+ |`m:acc` |`CTAcc` |`accent_to_plurimath`
385
+ |`m:argPr` |`CTOMathArgPr` |ignored, no node
386
+ |`m:bar` |`CTBar` |`bar_to_plurimath`
387
+ |`m:bibliography, m:citation, m:equation, m:group, m:picture, m:richText` |`CTEmpty` |ignored, no node
388
+ |`m:borderBox` |`CTBorderBox` |`border_box_to_plurimath`
389
+ |`m:box` |`CTBox` |`box_to_plurimath`
390
+ |`m:boxPr` |`CTBoxPr` |ignored, no node
391
+ |`m:ctrlPr` |`CTCtrlPr` |ignored, no node
392
+ |`m:d` |`CTD` |`delimiter_to_plurimath`
393
+ |`m:deg, m:den, m:e, m:fName, m:lim, m:num, m:sub, m:sup` |`CTOMathArg` |`wrapped_omml_children`
394
+ |`m:eqArr` |`CTEqArr` |`equation_array_to_plurimath`
395
+ |`m:f` |`CTF` |`fraction_to_plurimath`
396
+ |`m:fPr` |`CTFPr` |ignored, no node
397
+ |`m:fldData, m:t` |`CTText` |`typed_text_to_plurimath`
398
+ |`m:func` |`CTFunc` |`function_to_plurimath`
399
+ |`m:groupChr` |`CTGroupChr` |`group_character_to_plurimath`
400
+ |`m:limLow` |`CTLimLow` |`lower_limit_to_plurimath`
401
+ |`m:limUpp` |`CTLimUpp` |`upper_limit_to_plurimath`
402
+ |`m:m` |`CTM` |`matrix_to_plurimath`
403
+ |`m:mr` |`CTMR` |`matrix_row_to_plurimath`
404
+ |`m:nary` |`CTNary` |`nary_to_plurimath`
405
+ |`m:oMath` |`OMath` |`formula_from_omml_children`
406
+ |`m:oMath` |`CTOMath` |`formula_from_omml_children`
407
+ |`m:oMathPara` |`OMathPara` |`flattened_formula_from_omml_children`
408
+ |`m:oMathPara` |`CTOMathPara` |`flattened_formula_from_omml_children`
409
+ |`m:oMathParaPr` |`CTOMathParaPr` |ignored, no node
410
+ |`m:phant` |`CTPhant` |`phantom_to_plurimath`
411
+ |`m:r` |`CTR` |`run_to_plurimath`
412
+ |`m:rPr` |`CTRPR` |`math_run_properties_to_plurimath`
413
+ |`m:rPr, w:rPr` |`CTRPr` |`word_run_properties_to_plurimath`
414
+ |`m:rad` |`CTRad` |`radical_to_plurimath`
415
+ |`m:sPre` |`CTSPre` |`prescript_to_plurimath`
416
+ |`m:sSub` |`CTSSub` |`subscript_to_plurimath`
417
+ |`m:sSubSup` |`CTSSubSup` |`sub_sup_to_plurimath`
418
+ |`m:sSup` |`CTSSup` |`superscript_to_plurimath`
419
+ |`w:annotationRef, w:continuationSeparator, w:cr, w:dayLong, w:dayShort, w:endnoteRef, w:footnoteRef, w:lastRenderedPageBreak, w:monthLong, w:monthShort, w:noBreakHyphen, w:pgNum, w:separator, w:softHyphen, w:tab, w:yearLong, w:yearShort` |`CTWordprocessingEmpty` |ignored, no node
420
+ |`w:br` |`CTBr` |`Math::Function::Linebreak.new`
421
+ |`w:delInstrText, w:delText, w:instrText` |`CTWordprocessingText` |ignored, no node
422
+ |===
423
+ // END GENERATED elements-read
424
+
425
+ The second table lists the elements that `Formula#to_omml` writes for each
426
+ construct, in document order and without repeats. `m:oMathPara`, `m:oMath`
427
+ and the property elements (names ending in `Pr`, with their content) are
428
+ left out.
429
+
430
+ // BEGIN GENERATED elements-written
431
+ [cols="2,2l,4l",options="header"]
432
+ |===
433
+ |Construct |AsciiMath |Elements
434
+ |Number and letter |2x |m:r m:t
435
+ |Operator |a + b |m:r m:t
436
+ |Superscript |x^2 |m:sSup m:e m:r m:t m:sup
437
+ |Both scripts |x_i^2 |m:sSubSup m:e m:r m:t m:sub m:sup
438
+ |Fraction |frac(a)(b) |m:f m:num m:r m:t m:den
439
+ |Square root |sqrt(x) |m:rad m:deg m:e m:r m:t
440
+ |Root with index |root(3)(x) |m:rad m:deg m:r m:t m:e
441
+ |Sum with limits |sum_(i=1)^n i |m:nary m:sub m:r m:t m:sup m:e
442
+ |Integral |int_0^1 f(x) dx |m:nary m:sub m:r m:t m:sup m:e m:d
443
+ |Limit |lim_(x->0) x |m:limLow m:e m:limUpp m:r m:t m:lim
444
+ |Function name |sin x |m:func m:fName m:r m:t m:e
445
+ |Brackets |(x) |m:d m:e m:r m:t
446
+ |Absolute value |abs(x) |m:d m:e m:r m:t
447
+ |Matrix |[[a, b], [c, d]] |m:d m:e m:m m:mr m:r m:t
448
+ |Text |"if" |m:r m:t
449
+ |Font |bb(x) |m:r m:t
450
+ |Accent |hat(x) |m:limUpp m:e m:r m:t m:lim
451
+ |Overline |bar(x) |m:bar m:e m:r m:t
452
+ |Brace with label |overbrace(x)(n) |m:limUpp m:e m:r m:t m:lim m:d
453
+ |Colour |color(red)(x) |m:r m:t
454
+ |Line break |a \\ b |m:r m:t
455
+ |===
456
+ // END GENERATED elements-written
457
+
458
+ [[uncertainty]]
459
+ == Measurement uncertainty
460
+
461
+ OMML has no attribute for meaning, so a measurement result is an `m:box`
462
+ whose `m:e` starts with a hidden, zero-size `m:phant` holding the marker
463
+ text. The visible content follows in the same `m:e`, and a unit is the one
464
+ inner `m:box` after the phantom. The
465
+ marker grammar and the reading rules are in
466
+ link:uncertainty.adoc#markers[Measurement uncertainty].
467
+
468
+ // BEGIN GENERATED example uncertainty
469
+ [source,ruby]
470
+ ----
471
+ Plurimath::Math.parse("ustd(1.230, 0.004)", :asciimath).to_omml
472
+ ----
473
+
474
+ [source,xml]
475
+ ----
476
+ <m:oMathPara xmlns:m="..." ...>
477
+ <m:oMath>
478
+ <m:box>
479
+ <m:e>
480
+ <m:phant>
481
+ <m:phantPr>
482
+ <m:show m:val="off"/>
483
+ <m:zeroWid m:val="on"/>
484
+ <m:zeroAsc m:val="on"/>
485
+ <m:zeroDesc m:val="on"/>
486
+ </m:phantPr>
487
+ <m:e>
488
+ <m:r>
489
+ <m:rPr>
490
+ <m:sty m:val="p"/>
491
+ </m:rPr>
492
+ <m:t>standard-uncertainty(1.230,0.004)</m:t>
493
+ </m:r>
494
+ </m:e>
495
+ </m:phant>
496
+ <m:r>
497
+ <m:t>1.230</m:t>
498
+ </m:r>
499
+ <m:d>
500
+ <m:dPr>
501
+ <m:begChr m:val="("/>
502
+ <m:sepChr m:val=""/>
503
+ <m:endChr m:val=")"/>
504
+ </m:dPr>
505
+ <m:e>
506
+ <m:r>
507
+ <m:t>0.004</m:t>
508
+ </m:r>
509
+ </m:e>
510
+ </m:d>
511
+ </m:e>
512
+ </m:box>
513
+ </m:oMath>
514
+ </m:oMathPara>
515
+ ----
516
+ // END GENERATED example uncertainty
517
+
518
+ A phantom counts as a marker only when its `m:show` value is `off`, `0` or
519
+ `false`. A hidden phantom whose runs spell a marker but that also holds
520
+ anything other than `m:r` runs, or a box with more than one inner `m:box`,
521
+ raises `Plurimath::Errors::InvalidUncertainty` in the reader, which reaches
522
+ the caller of `Plurimath::Math.parse` as a `Plurimath::Math::ParseError`.
523
+
524
+ [[round-trip]]
525
+ == Round trips and Word
526
+
527
+ * Plurimath writes identifiers as plain `m:r` runs and reads plain runs as
528
+ text, so a formula written to OMML and read back is not `==` to the
529
+ original: its identifiers have become text. Numbers and function names come
530
+ back unchanged.
531
+ +
532
+ // BEGIN GENERATED example readback
533
+ [source,ruby]
534
+ ----
535
+ Plurimath::Math.parse(Plurimath::Math.parse("x^2 + 2", :asciimath).to_omml, :omml).to_asciimath
536
+ ----
537
+
538
+ [source]
539
+ ----
540
+ "x"^(2) + 2
541
+ ----
542
+ // END GENERATED example readback
543
+ * The uncertainty marker is the exception. A result written and read back is
544
+ `==` to the original, except that its unit comes back as the rendered
545
+ formula (see link:uncertainty.adoc#round-trip[the round-trip matrix]).
546
+ * An OMML consumer that ignores hidden phantoms shows the marker text as
547
+ ordinary text. Whether Word keeps the phantom when the equation is edited,
548
+ and how it displays it, has not been tested (#524).
549
+
550
+ [[errors]]
551
+ == Errors
552
+
553
+ `Plurimath::Math.parse(text, :omml)` raises `Plurimath::Math::ParseError`
554
+ when the XML cannot be parsed, the omml model rejects it, or the translator
555
+ meets a node it does not support. The original error is not kept as the
556
+ `cause`. OMML takes no parse options; passing `locale:` raises
557
+ `Plurimath::Math::ParseOptionError`.
558
+
559
+ [[conformance]]
560
+ == Conformance
561
+
562
+ // BEGIN GENERATED conformance
563
+ Shared testsuite at `51d64ea4006f29df085445e469e74190aa6758c5` (the `submodules/plurimath-testsuite` commit):
564
+
565
+ [cols="3,1,3"]
566
+ |===
567
+ |Rows |Cases |Groups
568
+
569
+ |`corpus/omml/`, inputs read |190 |`accents`, `boxes`, `delimiters`, `equation-arrays`, `fractions`, `functions`, `group-characters`, `limits`, `matrices`, `nary`, `partial-render`, `roots`, `runs`, `scripts`
570
+ |`corpus/omml/rejections.yaml`, inputs refused |9 |`rejections`
571
+ |`corpus/*/`, cases with `omml` output |780 |74 payloads
572
+ |`stages/roundtrip/generations/000001/payloads/`, written as `omml` and read back |46 |28 lossless, 14 lossy, 4 refused
573
+ |===
574
+ // END GENERATED conformance
575
+
576
+ * `spec/conformance/shared_corpus_spec.rb` replays every `corpus/` case
577
+ above with the Ox engine, comparing each target byte for byte.
578
+ * `spec/conformance/stage_roundtrips_spec.rb` replays the roundtrip
579
+ generation pinned in `spec/fixtures/roundtrip-pin.yml`.
580
+ * `spec/plurimath/omml/uncertainty_spec.rb` and
581
+ `spec/plurimath/fixtures/uncertainty/contract.yml` check the marker.
582
+ * The omml gem has its own specs for the OMML model.
583
+
584
+ [[regenerating]]
585
+ == Regenerating this page
586
+
587
+ The generated regions are written by `scripts/docs/format_specs.rb`, as
588
+ described in link:mathml.adoc#regenerating[MathML in Plurimath]. Do not edit
589
+ them by hand.