fix(docx): split multiple OMML equations into separate formula items

[giulio-leone]

Summary

When a DOCX paragraph contains multiple sibling <m:oMath> elements (e.g. two separate equations on one line), the converter concatenated them into a single LaTeX string because element.iter() walks all descendants depth-first, mixing children from different oMath nodes.

Root Cause

_handle_equations_in_text() used element.iter() (deep iteration) to collect both text runs and math elements. With multiple sibling <m:oMath> elements:

<w:p>
</w:p>

iter() would visit the children of the first oMath AND the second oMath and its children — all interleaved. The result was a single concatenated equation string.

Fix

1. Direct-children-first iteration: Check for oMath elements at the direct child level. If found, iterate direct children only, converting each oMath sibling independently. Falls back to the original deep iteration when oMath elements are nested inside wrapper elements like oMathPara.

2. Split standalone multi-equation paragraphs: When a paragraph contains only equations (no surrounding text) and has more than one equation, each is now emitted as a separate FORMULA document item instead of merging into one.

Before / After

Before: A paragraph with equations E = mc^2 and F = ma produced:

FORMULA: "E = mc^2 F = ma"

After: Two separate items:

FORMULA: "E = mc^2"
FORMULA: "F = ma"

Closes #3121

[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 can you please add the document attached to the linked issue as a test?

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[giulio-leone]

@dolfim-ibm Done — added tests/data/docx/omml_multi_equation_paragraph.docx (a minimal DOCX with two sibling oMath elements separated by a text run) along with matching groundtruth files (md, json, itxt).

The test document validates that the fix correctly splits the equations into two separate FormulaItem entries instead of concatenating them.

[giulio-leone]

Pushed a follow-up CI fix. The new fixture itself was fine, but I had generated the .itxt snapshot with the wrong exporter. I regenerated omml_multi_equation_paragraph.docx.itxt using the same _export_to_indented_text(max_text_len=70, explicit_tables=False) path that test_backend_msword.py actually validates.

[M-Hassan-Raza]

Thanks for putting this together. The fix direction looks right, but I don’t think the new fixture is covering the exact failing shape from #3121.

The issue is specificlly about a single paragraph made up only of sibling m:oMath elements, with no text runs between them. On current main, that case still collapses into one display block and the equation ordder gets scrambled. The fixture added here looks more like formula-text-formula inline content, which current main already seems to handle correctly.

I’d suggest adding a regression fixture that matches the issue attachment more directly: one paragraph, multiple sibling m:oMath nodes, no intervening text. That would make it much clearer that this PR is locking down the reported bug and not a nearby case.

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 detailed feedback! I'll add the test document from the linked issue and update the fixture to properly cover the exact failing shape (sibling m:oMath elements with no text runs between them). Will push an update shortly.

[giulio-leone]

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

I've now:

1. Replaced the test document with the real Word file from issue Multiple OMML equations in one paragraph concatenated into a single display block #3121 (the ~37 KB document from @smroels containing three sibling <m:oMath> elements in one paragraph)
2. Regenerated all groundtruth files for the new document

The conversion correctly produces three separate equation blocks:

$$a=b$$
$$c=d$$
$$e=f$$

Ready for re-review!

[giulio-leone]

Hi team! 👋 The mergify bot indicates this PR requires two reviewers for test updates. 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 taking care of the feedback. Could you please re-run your pre-commit toolchain to ensure the tests pass?

uv run pre-commit install # only once in your dev setup
uv run pre-commit run --all-files # you can make a new commit and it will do this for you automatically.

[giulio-leone]

I reran the requested formatting/tooling pass and pushed the result.

Local verification

• uv run --python 3.12 pre-commit run --all-files ✅
• uv run --python 3.12 pytest tests/test_backend_msword.py -q ✅ (17 passed, 1 xfailed, 1 xpassed)

Real DOCX proof on the issue fixture

I also re-ran the actual conversion on tests/data/docx/omml_multi_equation_paragraph.docx and compared origin/main against this PR branch.

• origin/main produced 1 concatenated formula item: c=de=fa=b
• this PR branch produced 3 separate formula items: a=b, c=d, e=f

The markdown export matches that behavior as well:

• origin/main => one $$c=de=fa=b$$ block
• this PR => three separate formula blocks

The only new commit on the branch is the formatter rerun requested by CI / review:

• 7f3faed style(docx): rerun ruff formatter for msword backend

[giulio-leone]

Rebased this PR onto current main and reran the requested tooling/test path on the refreshed head.

Validation (clean passes on rebased 57d9d35):

• uv run pre-commit run --files docling/backend/msword_backend.py tests/test_backend_msword.py
• uv run pytest tests/test_backend_msword.py::test_e2e_docx_conversions -q
• repeated the same no-diff pass a second time

Exact-source proof on the same real DOCX fixture (tests/data/docx/omml_multi_equation_paragraph.docx):

• rebased branch 57d9d35: emits 3 separate formulas: a=b, c=d, e=f
• current origin/main 4e650af: still emits 1 malformed concatenated formula: c=de=fa=b

So the refreshed branch still fixes the actual regression on top of current main, and the worktree is clean after validation.

[dolfim-ibm]

lgtm

[giulio-leone]

PR refresh — 2026-03-23

Cherry-picked onto current main (f0e3d1d) — was previously on 4e650af. Branch fix/omml-multi-equation-paragraph 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-multi-equation-paragraph @ 84cc70b
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 c78617f.

What changed

• removed the unused tag_name binding in the direct oMath iteration path of docling/backend/msword_backend.py
• added the required DCO remediation commit for 84cc70b55e96804f32590215a3eab31a0c280586

This is the smallest possible change to close the still-open review thread without altering the equation-splitting logic.

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 fixture

Using the same real DOCX fixture (omml_multi_equation_paragraph.docx) with both current main code and the refreshed branch code:

• branch:
  • a=b
  • c=d
  • e=f
• main:
  • c=de=fa=b

So the refreshed head still fixes the reported multi-equation paragraph bug on top of current main, and the remaining PR blockers from review + DCO are now addressed.

[ceberam]

@giulio-leone please check my comments on the other PR
#3122 (review)

Do you plan to add more commits or do you consider the PR final?

[giulio-leone]

Pushed a small follow-up in 46ddaec for the latest test-structure review note on tests/test_backend_msword.py.

What changed:

• promoted the shared MsWordDocumentBackend setup into a module-scoped pytest fixture
• rewired the touched tests to reuse that fixture instead of rebuilding the backend each time

Validation (run twice, no code changes between passes):

• uv run pre-commit run --files tests/test_backend_msword.py
• uv run pytest tests/test_backend_msword.py -q
• result on both passes: 24 passed, 1 xfailed, 1 xpassed

No additional contributor-side changes are planned on this PR from my side unless new review feedback appears.

[giulio-leone]

Small DCO-only refresh on top of the fixture-reuse follow-up: the live PR head is now signed commit 8ebb44d, which replaces 46ddaec with the same code change plus the required sign-off so the DCO gate can pass.

No code-path changes beyond the already-described fixture reuse; validation evidence from the earlier comment is still the relevant proof.

[giulio-leone]

@ceberam Thanks — from my side I consider #3123 final now.

I already checked and answered the question on #3122 in a separate PR comment there, and on this PR the latest head 8ebb44d is only the signed replacement for the earlier fixture-reuse follow-up so that DCO can pass again.

So no further contributor-side commits are planned on #3123 unless new review feedback appears.

[ceberam]

Thanks @giulio-leone for your contribution 🏆

[dosubot]

Documentation Updates

1 document(s) were updated by changes in this PR:

What are the detailed pipeline options and processing behaviors for PDF, DOCX, PPTX, and XLSX files in the Python SDK?

View Changes

@@ -80,6 +80,11 @@
 - **Key Options**:
     - Enrichment options (code, formula, chart, image description)
     - **Header/Footer Export**: Only supported via Python API by setting `included_content_layers={ContentLayer.BODY, ContentLayer.FURNITURE}`; default export excludes header/footer
+- **Processing**:
+    - **Multiple Equations in Paragraphs**: When a DOCX paragraph contains multiple sibling OMML equations (e.g., multiple `<m:oMath>` elements), each equation is extracted as a separate `FORMULA` item in the document structure. This applies to both:
+        - **Standalone equation paragraphs**: Paragraphs containing only equations (no surrounding text) produce multiple separate `FORMULA` items, one for each equation
+        - **Inline equations**: Multiple equations within text-containing paragraphs are preserved as distinct formula items
+    - Previously, multiple sibling equations in a single paragraph were concatenated into a single LaTeX string, but this has been fixed to maintain each equation as a separate document item
 - **Notes**: Header/footer are automatically detected as FURNITURE layer. CLI/Serve API exports only BODY. [Example](https://app.dosu.dev/097760a8-135e-4789-8234-90c8837d7f1c/documents/e596ee79-fc7f-43a4-90e2-74891e0cf12f).
 
 ---

^{How did I do? Any feedback?}