Skip to content

docs(pptx): say what a partial capability actually costs#445

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

docs(pptx): say what a partial capability actually costs#445
DemchaAV merged 1 commit into
developfrom
docs/pptx-readme-accuracy

Conversation

@DemchaAV

Copy link
Copy Markdown
Owner

Why

render-pptx/README.md is the page GitHub renders for the artifact, and it carried the same overstatement the release notes did until #444: all ten partial capabilities described as rendering "natively with an approximated styling detail". Reading the matrix rows rather than the count shows only some are that. The others lose content the format cannot carry.

The opening sentence also lumped "links and navigation" together as native. Links are — hyperlinks and internal slide jumps render as real PowerPoint links. Bookmarks are the degraded half: PPTX has no outline tree, so the first bookmark on a page names its slide and the rest are dropped. A reader with a bookmark-heavy document was told the wrong thing about the one part that actually loses data.

What changed

  • The capability summary splits the partial group instead of characterising it as one thing.
  • Three content-losing cases added to Limitations to know before you ship: dropped bookmarks, the inline-SVG PNG fallback, and the unrepresentable metadata producer field.
  • The clip raster's resolution behaviour is recorded — it targets a 2048-pixel long edge clamped between native size and 4×, so a larger region renders at native resolution rather than downscaled, at a transient memory cost proportional to its size. The capability matrix has carried this since the clamp landed in #442; this page did not.

Every other claim on the page re-verified

Claim Result
not pulled in by graph-compose / -core / -bundle correct — bundle/pom.xml depends on wrapper + templates + fonts + emoji only
render-pdf at compile scope correct — no <scope> element
SLIDE_16_9 960 × 540, SLIDE_4_3 720 × 540 correct (DocumentPageSize:35/43)
renderToImages throws correct
determinism is opt-in correct
PptxSemanticBackend footnote the class is still shipped
install pin 2.0.0 correct pre-cut state — cut-release.ps1 flips it, VersionConsistencyGuardTest guards it
both doc links + migration guide resolve on disk

Verification

./mvnw -B -ntp clean verify — BUILD SUCCESS, 1522 tests, 0 failures.

The module README carried the same overstatement the release notes did: it
described all ten partial capabilities as rendering "natively with an
approximated styling detail". Reading the matrix rows rather than the count shows
only some are that. The others lose content the format cannot carry — bookmarks
after the first on a slide are dropped, parts of an inline SVG fall back to a
transparent PNG, and the metadata producer value has no OPC field.

The opening sentence also lumped "links and navigation" together as native. Links
are: hyperlinks and internal slide jumps render as real PowerPoint links.
Bookmarks are the degraded half, so a reader with a bookmark-heavy document was
told the wrong thing about the one part that loses data.

Split the summary so the partial group is not characterised as one thing, list
the three content-losing cases under limitations, and record the clip raster's
resolution behaviour — it targets a 2048-pixel long edge clamped between native
size and 4x, which the matrix has carried since the clamp landed but this page
did not.
@DemchaAV
DemchaAV merged commit 3a67ad6 into develop Jul 26, 2026
10 checks passed
@DemchaAV
DemchaAV deleted the docs/pptx-readme-accuracy branch July 26, 2026 00:26
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