Compatibility and validation
Generated documents use standard WordprocessingML and OMML. Conversion tests check saved content against independently written answers and official XML schemas. Document applications can still differ in fonts, equation layout and pagination.
What is checked
| Check | Purpose | Limit |
|---|---|---|
| Independent equation answers | Fractions, script roles, radicals, matrices, delimiters, variants and content | Does not compare pixels or interactive editing |
| Saved-document checks | Text order, math styles/layout, tables, merges, numbering, images and link targets | Covers selected properties |
| Official ECMA-376 schemas | Valid OMML and body element ordering | Valid structure is not proof of intended meaning |
| Mutation checks | Verify that representative equation damage is detected | Not every possible defect |
| Word automation | Open, export and resave example documents with Word 16 | One installed Word environment |
| LibreOffice checks | Count imported formula objects and test actual PDF math output | Layout can differ from Word |
The source corpus contains 44 manually authored base equations, 240 seeded combinations and 18 advanced inputs. The seeded set has 210 distinct input strings, including simple tokens; these are not 240 different complex reports. Advanced examples include nested block matrices, six-level continued fractions, integrals, partial derivatives, scientific prose, tables and images.
Inputs live in examples/assets/math-corpus/ and examples/assets/advanced-math/.
Independent answers live in tests/fixtures/; generated DOCX is not kept in Git.
Examples provide files suitable for manual review. The 30
runnable examples contain 224 native equations;
example 30 adds independent answers for inherited
defaults, compact/display limits, accents, CSS and template replacement.
Before rendering, each generated document must match the separately authored
tests/fixtures/example_equation_counts.json manifest. Counting only the formulas
already present in a DOCX would miss equations lost during conversion. Checks
also distinguish inline/display layout, effective math variants, nonbreaking
spaces, colors, sizes and fonts. Internal hyperlinks must have bookmark targets.
Fonts
The converter references fonts; it does not embed font files. Install fonts that contain the characters used in the document. An unavailable font or incomplete fallback can produce square glyphs, especially for CJK and mathematical alphabets.
CSS font-family applies to Latin, East Asian and complex-script font slots.
Without an explicit font, the Word template's defaults apply. Examples 24–28 use
Malgun Gothic; on other systems select an installed CJK font, such as Noto Sans CJK.
Neither font is bundled with the Python package.
LibreOffice
Install both Writer and Math. A minimal Writer-only installation may import text while leaving all equations blank, even when PDF export exits successfully. This was reproduced on LibreOffice 24.2.7.2; adding Math restored visible formulas in the same files. CJK and math fonts must also be available.
On Debian/Ubuntu:
sudo apt-get install libreoffice-writer libreoffice-math poppler-utils fonts-noto-cjk fonts-stix
To reproduce previews and automated checks, prepare a source checkout using the development setup. Run these commands from its root:
uv run --no-sync python -m examples.run_all
uv run --no-sync python scripts/render_examples.py --output examples/output/libreoffice-review
The check uses fresh temporary outputs, verifies formula counts in LibreOffice's
flat XML export, and requires a PDF text probe to confirm actual math rendering.
Missing or empty equations cause failure. pdftotext is required; pass
--soffice and --pdftotext if they are not on PATH. Existing outputs require
--force before replacement.
Writer 24.2 can also omit native OMML borders and cancellation marks. Select
math_target='libreoffice' to route those constructs through explicit recovery,
and to preserve upright chemical element names. Empty postscript pairs are
omitted to avoid placeholder squares. The default Word-target chemistry preview
illustrates the remaining enclosure difference; use image recovery when needed.
Native equations are not automatically replaced by images for a particular viewer. For unsupported input, choose explicit source or image recovery. An image is useful when a fixed appearance matters more than editability.
Known display differences
Phantom spacing, bevelled fractions, string quoting, accents and line wrapping can vary between document applications. Phantom content is intentionally hidden; reserved dimensions may differ. A skewed fraction can appear as a stacked fraction in LibreOffice. Compare the equation gallery with its input when these features matter. Structure checks do not certify visual equivalence.
LibreOffice can misparse quoted ms strings in Word-target documents, omit part
of the text or show a formula error. This is a content-loss limitation, not just
font substitution. math_target='libreoffice' rejects native ms before output;
select explicit source or image recovery for those strings. Example 30's PDF
illustrates this viewer limitation; its DOCX is intended for Word.
Reproduce the automated checks
uv run --no-sync python -m pytest -q
uv run --no-sync python scripts/check_math_mutations.py
uv run --no-sync python scripts/prepare_ecma_schema.py /tmp/mathml2docx-ecma376
uv run --no-sync python scripts/validate_math_schema.py --schemas /tmp/mathml2docx-ecma376
Schemas come from ECMA-376 and W3C xml.xsd, with hashes checked by the preparation script. They are not distributed in the package.
On Windows or WSL with Word installed:
python scripts/check_word.py --input examples/output --output examples/output/word-review
python scripts/check_word.py --input examples/output --output examples/output/word-mixed-review --examples 24_dense_report 25_research_report 26_template_workbook 27_advanced_latex --check-blocks
The tool opens inputs read-only and saves separate copies. Word may rewrite the
Unicode minus U+2212 as ASCII hyphen-minus; only the Word resave comparison accepts
that spelling difference inside math sequences. Independent converter answers
remain Unicode-exact. The report separates raw serialization changes from
effective differences. It resolves inherited formatting and known font-name
aliases, then checks every originally declared math color, size, font and
bold/italic property. Math script-family metadata on symbols without mathematical alphabet
variants (such as + and ∈) can be omitted from the effective comparison.
Letters, digits and mapped symbols such as ∂ and ∇ remain exact. Word can wrap an isolated math-only paragraph as display math;
that change is listed separately. An explicitly displayed equation becoming
inline still fails. Word web, macOS Word, accessibility and interactive equation
editing require separate review in the target environment.