fix(omml): correct LaTeX output for fractions, math operators, and functions

[giulio-leone]

Summary

Fixes three related correctness bugs in OMML-to-LaTeX conversion (docling/backend/docx/latex/omml.py and latex_dict.py):

Bug A — Fraction raised to a power: missing grouping braces

When <m:sSup> (superscript) has an <m:f> (fraction) as its base, the converter emitted:

\frac{(x-c)}{v}^{2}

which is ambiguous — LaTeX applies ^2 only to the closing brace of the denominator, not the whole fraction.

Fix: Added dedicated do_ssub, do_ssup, and do_ssubsup handler methods that detect complex base expressions (fractions, radicals) and wrap them in grouping braces:

{\frac{(x-c)}{v}}^{2}

Bug B — EN DASH and CIRCUMFLEX escaped as text-mode macros

Characters U+2013 EN DASH and U+005E CIRCUMFLEX inside <m:r><m:t> math runs were converted to \text{\textendash} and \text{\textasciicircum}, producing invalid math-mode LaTeX.

Fix: Added a _MATH_CHAR_MAP that intercepts these characters before the pylatexenc text encoder and maps them to their math-mode equivalents (- and ^).

Bug C — log (and other standard functions) not mapped to LaTeX commands

An <m:func> element with name log fell through to the text fallback, producing italic log instead of upright \log.

Fix: Added 15 missing standard math functions to the FUNC dict: log, ln, exp, det, gcd, deg, hom, ker, dim, arg, inf, sup, lim, Pr.

Closes #3120

[github-actions]

✅ DCO Check Passed

Thanks @giulio-leone, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

🟢 Require two reviewer for test updates

Wonderful, this rule succeeded.

When test data is updated, we require two reviewers

• #approved-reviews-by >= 2

[dolfim-ibm]

@giulio-leone let's add the example documents linked to the issue as tests

[codecov]

Codecov Report

❌ Patch coverage is 76.31579% with 9 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
docling/backend/docx/latex/omml.py	76.31%	9 Missing ⚠️

📢 Thoughts on this report? Let us know!

[giulio-leone]

@dolfim-ibm Done — added three minimal DOCX test documents, one per bug:

• omml_frac_superscript.docx — Bug A: fraction as superscript base (validates braces grouping)
• omml_text_escapes_in_math.docx — Bug B: en-dash and caret inside math runs (validates math-mode operators)
• omml_func_log.docx — Bug C: log function recognition (validates \log output)

Each file has matching groundtruth (md, json, itxt).

[giulio-leone]

Pushed a follow-up fix for the CI regression. The earlier OMML change correctly grouped fraction bases, but it also double-wrapped nested <sup>/<sub> containers in existing equations (^{^{2}}, _{_{0}}). I switched that handling to unwrap only inside sSub/sSup/sSubSup, which restores the historical equations.docx output while keeping the fraction-grouping fix intact.

[M-Hassan-Raza]

Thanks for tackling these OMML cases. Bug A looks headed in the right direction, but I think bug B is still not fully fixed.

The caret path still seems to end up as x-y\\^2 rather than a real superscript form. From the code, it looks like ^ gets mapped in process_unicode() and then escaped again later, so the operator is still wrong in the final LaTeX. The new omml_text_escapes_in_math snapshot also seems to encode that same output, so I don’t think the regression is actually closed yet.

I’d also add a fixture for the delimiter-wrapped log\\left(x\\right) shape from the issue. The current omml_func_log test seems to prove \\log(x), which is useful, but it doesn’t quite cover the exact form reported in #3120.

PSA: I am new to this coedbase so I could be wrong, in which case please feel free to discard this comment.

[giulio-leone]

Hi @dolfim-ibm, @M-Hassan-Raza — thanks for the review! I'll add the example documents from the linked issue as tests and take another look at the caret/superscript handling in process_unicode() to fix bug B properly. Will push an update.

[giulio-leone]

Thanks @dolfim-ibm @M-Hassan-Raza for the detailed feedback!

I've now:

1. Replaced all 3 test documents with the real Word files from issue OMML-to-LaTeX conversion produces incorrect output for fractions, math operators, and functions #3120 (the ~37 KB documents from @smroels, not my minimal ~1.2 KB programmatic fixtures)
2. Fixed Bug B (caret/superscript): escape_latex was re-escaping the ^ that process_unicode had correctly mapped from U+005E. Now do_r restores math-mapped characters after escaping.
   • Before: x - y\^2 ❌
   • After: x - y^2 ✅
3. Regenerated all groundtruth files for the new test documents

Bugs A and C were already working correctly with the new test documents:

• Bug A: ${\frac{(x-c)}{v}}^{2}$ ✅ (fraction properly grouped)
• Bug C: \log(\left(x\right)) ✅ (\log recognized)

Ready for re-review!

[giulio-leone]

Hi team! 👋 The mergify bot indicates this PR requires two reviewers for test updates. @M-Hassan-Raza has already provided valuable feedback which I've addressed. Could a second reviewer (@PeterStaar-IBM, @cau-git, or @ceberam) take a look when convenient? The DCO check is now passing and all groundtruth files have been regenerated. Thank you!

[cau-git]

@giulio-leone Thanks for these updates. Could you please check why this test is failing?

=========================== short test summary info ============================
FAILED tests/test_backend_msword.py::test_e2e_docx_conversions - AssertionError: export to indented-text failed on tests/data/groundtruth/docling_v2/omml_frac_superscript.docx
assert False
 +  where False = verify_export('item-0 at level 0: unspecified: group _root_\n  item-1 at level 1: section: group header-0\n    item-2 at level 2: section_header: Issue 1: Fraction as superscript base not grouped\n      item-3 at level 3: text: The equation below raises a frac ... }^2 or \\left(\\frac{(x-c)}{v}\\right)^2.\n      item-4 at level 3: formula: {\\frac{(x-c)}{v}}^{2}', ('tests/data/groundtruth/docling_v2/omml_frac_superscript.docx' + '.itxt'), generate=False)
 +    where 'tests/data/groundtruth/docling_v2/omml_frac_superscript.docx' = str(PosixPath('tests/data/groundtruth/docling_v2/omml_frac_superscript.docx'))
= 1 failed, 289 passed, 8 skipped, 2 xfailed, 50 warnings in 520.12s (0:08:40) =
Error: Process completed with exit code 1.```

[giulio-leone]

Rebased this branch onto current main and fixed the remaining contributor-side E2E breakage.

Root cause: the OMML converter changes were still producing the expected output, but two groundtruth .itxt files had been regenerated in the wrong format (markdown-like prose instead of the repo's real indented-text export). That is why tests/test_backend_msword.py::test_e2e_docx_conversions could fail on omml_frac_superscript.docx.itxt even though the converter output itself was correct.

What I changed:

• regenerated tests/data/groundtruth/docling_v2/omml_frac_superscript.docx.itxt
• regenerated tests/data/groundtruth/docling_v2/omml_func_log.docx.itxt

Strict verification run from the rebased head (75dde05):

• .venv/bin/pytest tests/test_backend_msword.py::test_e2e_docx_conversions -q
• repeated the same command a second time with no code changes in between
• both passes: 1 passed

Real DOCX branch-vs-main proof on the same three OMML fixtures:

• omml_frac_superscript.docx
  • branch: formula: {\frac{(x-c)}{v}}^{2}
  • main: formula: \frac{(x-c)}{v}^{2}
• omml_func_log.docx
  • branch: formula: y = \log(\left(x\right))
  • main: formula: y = log\left(x\right)
  • main also still logs Function not supported, will default to text: log
• omml_text_escapes_in_math.docx
  • branch: formula: x - y^2
  • main: formula: x \text{ \textendash } y \text{ \textasciicircum } 2

So the branch still carries real converter fixes vs current main; the last failing E2E issue on this PR was the stale/wrong .itxt groundtruth, which is now aligned with the actual export format.

[PeterStaar-IBM]

@giulio-leone Please run this command a few times,

 uv run pre-commit run --all-files

[giulio-leone]

PR refresh — 2026-03-23

Cherry-picked onto current main (f0e3d1d) — was previously on 4e650af. Branch fix/omml-latex-conversion-bugs force-pushed to fork.

Test validation (double-pass):

• tests/test_backend_msword.py
• Pass 1: 19 passed, 1 xfailed, 1 xpassed ✅
• Pass 2: 19 passed, 1 xfailed, 1 xpassed ✅

All tests pass. PR is ready for review.

[giulio-leone]

✅ Validation Evidence

Branch: fix/omml-latex-conversion-bugs @ 08001d9
Status: 0 commits behind upstream main

Double-pass test results (strict identical runs, no code changes between passes):

Pass 1: 19 passed, 1 xfailed, 1 xpassed, 1 warning  ✅
Pass 2: 19 passed, 1 xfailed, 1 xpassed, 1 warning  ✅

Test file: tests/test_backend_msword.py

Branch pushed to fork. CI is the authoritative gate.

[dolfim-ibm]

@giulio-leone please apply the DCO fix commit, then we can finalize the PR.

[giulio-leone]

Addressed the remaining contributor-side blockers on refreshed head c7a5f2f.

What changed

• applied the exact ruff-format normalization that the failing code-checks / lint (3.12) job wanted in docling/backend/docx/latex/omml.py
• added the required DCO remediation commit for 08001d9c5ce1e4c12e31031529b15454d664f85e

Double-pass local gate

Ran these twice back-to-back with no code changes between passes:

• uv run pre-commit run --all-files
• uv run pytest tests/test_backend_msword.py -q

Both passes were clean:

• 19 passed, 1 xfailed, 1 xpassed, 1 warning

Real DOCX proof on the issue fixtures

Using the same three real DOCX fixtures from this branch and loading each with both current main code and the refreshed branch code:

• omml_frac_superscript.docx
  • branch: {\frac{(x-c)}{v}}^{2}
  • main: \frac{(x-c)}{v}^{2}
• omml_text_escapes_in_math.docx
  • branch: x - y^2
  • main: x \text{ \textendash } y \text{ \textasciicircum } 2
• omml_func_log.docx
  • branch: y = \log(\left(x\right))
  • main: y = log\left(x\right)

So the refreshed head keeps the intended converter fixes vs current main, and the remaining PR blockers from lint + DCO are now addressed.

[ceberam]

Thanks @giulio-leone for fixing all those details!
Approving the PR to help move this important fix forward.
I just added a question that could be resolved in another PR, if needed.
Also, a comment regarding the tests for the future:

• it is very helpful that you cover the changes with tests
• however it would be good to group the same type of test data in a single docx document instead of creating small docs for each edge case. It is easier to maintain and faster to run with our CI/CD checks. We already have equations.docx, where we used to add edge cases.
• try to add the backend type as a prefix in new test files (in this case, docx_), since the ground truth files they all go in the same directory and in this way they get grouped by backend. We did not do it at the beginning but we try to stick to this pattern recently.
• try to avoid statements in the test files that can create confusion in the long term (even if it is dummy text for testing). If you write:

  The equation below uses U+2013 EN DASH as minus and U+005E as caret.
  Expected LaTeX: x - y^2
  Docling produces: x \text{ \textendash } y\text{ \textasciicircum }2_
  

  a user/contributor that reads this test file in the future may get confused, since it is no longer what Docling produces.

[giulio-leone]

On the broader wrapping question from the latest review: I’m treating this PR as final for the three concrete regressions from #3120.

I have not broadened the change to operators like \sum / \int because I do not yet have a failing DOCX fixture showing those shapes need the same grouping rule, and I’d rather avoid widening the OMML conversion surface speculatively. If we get a reproducible example for those operators, I’m happy to handle that in a focused follow-up PR.