docs(docx): record what the semantic backend drops#446
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:InlineTextRuncarries alinkTarget;writeParagraphnever reads it. The label text survives, the destination does not.createHeader/createFooter/bookmark call anywhere in the module.writeParagraphcallsapplyStyle(docRun, node.textStyle())— the paragraph's style — for every run, so a bold or accent-coloured segment inside aRichTextparagraph exports in the base style.STRIKETHROUGHis dropped —applyStylehandlesBOLD/ITALIC/BOLD_ITALIC/UNDERLINEand lets the rest fall throughdefault -> {}.Two matrix cells were wrong in opposite directions
DocxSemanticBackend.applyStylemapsUNDERLINEto Word's single underline; onlySTRIKETHROUGHfalls throughtextStyleandlinkTargetThe 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.mdoffered "addgraph-compose-render-pdf, or implement theFixedLayoutBackendProviderSPI". That SPI alone is not enough:DocumentSession's constructor callsrefreshMeasurementServices()→BackendProviders.fontMetrics(), which throwsMissingBackendExceptionwhen nothing publishes aFontMetricsProvider— andrender-pdfis the only shipped artifact that does. So a custom backend built to that instruction fails atcreate(), before any render call. The page now names both halves of the SPI, and says the failure happens atcreate()rather than at render time.render-docx/README.mdandscripts/release-smoke/README.mdalready 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. Thetestingsnippet resolves to the realassertMatches(LayoutSnapshot, String)overload; PDF's one non-✅ matrix row isn/a(raster-slide mode, where the PDF raster is the source), so "full DSL coverage" holds; version pins are consistent at the pre-cut2.0.0with fonts/emoji on their independent1.0.0;docs/templates/v1-classic/is correctly marked archived.Verification
./mvnw -B -ntp clean verifyover the eight-module reactor — BUILD SUCCESS, 0 failures.DocumentationSnippetCompileTest+DocumentationExamplesTestre-run against the final file state — 16 tests, 0 failures.