55 lines
5.6 KiB
Markdown
55 lines
5.6 KiB
Markdown
# Mathematical content
|
|
|
|
Use the math family declared by the selected template or an explicit project-local math-style input. Keep that declaration with the project; do not silently substitute the prose font or a different math family. An OpenType math font supplies mathematical glyphs and layout tables; its name alone neither installs it nor proves application rendering. Keep ordinary Chinese/English explanations in their prose role. Variables, operators, upright function names, units and grouping must retain the author's meaning.
|
|
|
|
## Supported native route
|
|
|
|
`scripts/math_component.py` creates structured expressions and the maintained `native_export.py` wrapper emits Office Math. The preserved upstream compiler remains unchanged. The wrapper uses its own `data-native-math="1"` group, not the upstream `data-pptx-replace-with` table/chart kinds.
|
|
|
|
Supported expression nodes:
|
|
|
|
| Input | Native structure |
|
|
|---|---|
|
|
| A nonempty string, or `text` with explicit plain/italic/bold/bold-italic style | `m:r` runs |
|
|
| `row` with ordered `items` | Ordered math expressions |
|
|
| `fraction` with `numerator` and `denominator` | `m:f` |
|
|
| `script` with `base` and `sub` and/or `sup` | `m:sSub`, `m:sSup`, `m:sSubSup` |
|
|
| `radical` with `body` and optional `degree` | `m:rad` |
|
|
| `delimiter` with `body`, `open`, `close` | `m:d` |
|
|
| `nary` with explicit operator, `body` and optional `lower`/`upper` | `m:nary` |
|
|
| Rectangular `matrix` with `rows` | `m:m` |
|
|
|
|
The initial operator set is sum, product, integral, union and intersection. Unknown node types/fields, malformed matrices, empty expressions, unsupported transforms and excessive nesting are rejected. This is an explicit expression interface, **not a general LaTeX/MathML parser**. Do not strip unknown commands or flatten unsupported expressions to make a conversion appear successful.
|
|
|
|
Use `render_math(data, style, theme, bounds, component_id, math_style=None)`:
|
|
|
|
```python
|
|
data = {
|
|
"schema_version": 1,
|
|
"display": "block",
|
|
"expression": {
|
|
"type": "fraction", "numerator": "a+b", "denominator": "c"
|
|
},
|
|
}
|
|
marker = render_math(data, style, theme, bounds, "equation-1", math_style)
|
|
page.append(marker)
|
|
```
|
|
|
|
`math_style` is an explicit external dictionary with `font_family`, a declared `text_role` and a theme `palette_index`. It can extend a project whose template does not yet have math roles. Without it, the template must declare `typography.families.math` and `math_display`/`math_inline` roles. The selected role supplies the actual point size; no arbitrary font-size field is accepted in component data. Keep the style declaration and generator in build inputs, and declare the math font in the destination environment. A project-local declaration does not rewrite a frozen template or certify a new template release.
|
|
|
|
`display: "block"` creates `a14:m > m:oMathPara > m:oMath`. `display: "inline"` creates `a14:m > m:oMath` in a standalone native equation frame; this first API does not yet mix prose and equations inside one flowing text frame. Use the ordinary logical paragraph policy for surrounding explanations and do not claim inline paragraph reflow from separately positioned objects.
|
|
|
|
The SVG contains complete JSON math metadata and a derived **linear text compatibility view**. Complex equations are not visually typeset by that SVG fallback. `native_export.py` validates it, compiles a temporary unique token, then replaces that token with native math at the declared bounds. No temporary token remains in the PPTX. Equations cannot be inside transformed source groups; regenerate their bounds instead. Math markers currently belong to authored pages, not Master/Layout definitions.
|
|
|
|
The resulting `mc:AlternateContent` has an Office Math choice and an ordinary linear-text fallback for applications without math support. The fallback preserves expression meaning but is not an editable equation or a faithful complex-equation preview. Inspect the supported choice in the target application. No online equation service, additional installed Skill, font download or global installation is invoked.
|
|
|
|
## Verification
|
|
|
|
- Check complete input expressions against OMML: correct fraction operands, script attachment, radical degree, delimiter grouping, limits and matrix dimensions. Ordinary Unicode text alone is not proof of an equation.
|
|
- Check the declared family, actual destination font identity and OpenType MATH table. Verify glyph coverage and actual use in the application/export; do not silently replace a missing math font. Fonts are referenced, not distributed or embedded by this wrapper.
|
|
- Inspect mathematical runs and control properties for the selected family, size and color. Confirm Office Math choice nodes are present, no WordprocessingML-only properties or temporary tokens remain, and Master/Layout/notes are preserved.
|
|
- Render the current native file in a math-capable application. Check symbols, fraction bars, radicals, scripts, operators/limits, equation bounds and clearance from neighboring content. An SVG compatibility view or prior unrelated render cannot substitute.
|
|
- Actual equation editing is a separate test: select and change a representative expression in a disposable copy, save, then confirm the resulting equation structure/content. Native XML establishes structure only.
|
|
|
|
Technical basis: Microsoft's [DrawingML math extension](https://learn.microsoft.com/en-us/openspecs/office_standards/ms-odrawxml/853b19c7-68a9-4f9a-a2ae-5e6cb0d02e62) and [native math example](https://learn.microsoft.com/en-us/openspecs/office_standards/ms-odrawxml/38b13e1f-1102-4bb7-819a-dd5d9abdb176). Font information: the [STIX project](https://www.stixfonts.org/) and its [official source](https://github.com/stipub/stixfonts).
|