Skip to content

docs(docx): record what the semantic backend drops#446

Merged
DemchaAV merged 1 commit into
developfrom
docs/readme-capability-accuracy
Jul 26, 2026
Merged

docs(docx): record what the semantic backend drops#446
DemchaAV merged 1 commit into
developfrom
docs/readme-capability-accuracy

Conversation

@DemchaAV

Copy link
Copy Markdown
Owner

Why

The DOCX page stated its limits in one sentence — "coverage is narrower than the PDF backend" — and the root README's support table named four dropped drawing kinds (shape, line, ellipse, barcode). Those are the geometry drops, and they are the ones a reader can predict: Word owns the flow, so fixed-layout drawing has nowhere to go.

Everything a Word reader would actually be surprised by went unmentioned on both pages. Verified against DocxSemanticBackend:

  • Hyperlinks are dropped entirely — zero hyperlink code in the module. InlineTextRun carries a linkTarget; writeParagraph never reads it. The label text survives, the destination does not.
  • No bookmarks, no outline, no headers/footers, no watermark — no createHeader/createFooter/bookmark call anywhere in the module.
  • Per-run styling is flattened. writeParagraph calls applyStyle(docRun, node.textStyle()) — the paragraph's style — for every run, so a bold or accent-coloured segment inside a RichText paragraph exports in the base style.
  • STRIKETHROUGH is droppedapplyStyle handles BOLD / ITALIC / BOLD_ITALIC / UNDERLINE and lets the rest fall through default -> {}.

Two matrix cells were wrong in opposite directions

Row Was Now Evidence
Text decorations ⚠️ DocxSemanticBackend.applyStyle maps UNDERLINE to Word's single underline; only STRIKETHROUGH falls through
Paragraph — lines, runs, alignment ⚠️ runs lose their own textStyle and linkTarget

The first understated the backend, the second overstated it. Both are single symbols standing in for a mixed reality.

Core's bring-your-own-backend route did not work as written

core/README.md offered "add graph-compose-render-pdf, or implement the FixedLayoutBackendProvider SPI". That SPI alone is not enough: DocumentSession's constructor calls refreshMeasurementServices()BackendProviders.fontMetrics(), which throws MissingBackendException when nothing publishes a FontMetricsProvider — and render-pdf is the only shipped artifact that does. So a custom backend built to that instruction fails at create(), before any render call. The page now names both halves of the SPI, and says the failure happens at create() rather than at render time.

render-docx/README.md and scripts/release-smoke/README.md already stated this correctly; core's page was the one that did not.

Verified clean

render-pdf, wrapper, bundle, templates, testing, examples, qa, web, benchmarks, fonts, emoji, docs, docs/recipes, release-smoke, and both template guides. The testing snippet resolves to the real assertMatches(LayoutSnapshot, String) overload; PDF's one non-✅ matrix row is n/a (raster-slide mode, where the PDF raster is the source), so "full DSL coverage" holds; version pins are consistent at the pre-cut 2.0.0 with fonts/emoji on their independent 1.0.0; docs/templates/v1-classic/ is correctly marked archived.

Verification

./mvnw -B -ntp clean verify over the eight-module reactor — BUILD SUCCESS, 0 failures. DocumentationSnippetCompileTest + DocumentationExamplesTest re-run against the final file state — 16 tests, 0 failures.

The DOCX page stated its limits as "coverage is narrower than the PDF
backend" and named four dropped drawing kinds. Everything a Word reader
would actually be surprised by went unmentioned: hyperlinks are dropped
entirely, there are no bookmarks, headers/footers or watermark, and a
mixed-style RichText paragraph is written with every run in the
paragraph's own style, so per-run bold or colour is lost.

Two capability-matrix cells were wrong in opposite directions. Text
decorations were marked unsupported for DOCX although underline maps to
Word's single underline and only STRIKETHROUGH falls through; the
paragraph row was marked fully supported although runs lose their own
style and link target.

Core's page offered "implement the FixedLayoutBackendProvider SPI" as the
bring-your-own-backend route. A session resolves font metrics as it
opens, so that SPI alone throws at create(); the page now says both
halves are needed and which artifact ships one.
@DemchaAV
DemchaAV merged commit 2099476 into develop Jul 26, 2026
10 checks passed
@DemchaAV
DemchaAV deleted the docs/readme-capability-accuracy branch July 26, 2026 00:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant