From 83f06b47b59e0f52d8ea1ad7f7a2166244726419 Mon Sep 17 00:00:00 2001 From: DemchaAV Date: Sun, 26 Jul 2026 01:19:59 +0100 Subject: [PATCH] docs(pptx): say what a partial capability actually costs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- render-pptx/README.md | 34 +++++++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/render-pptx/README.md b/render-pptx/README.md index acd64358..7a818bf6 100644 --- a/render-pptx/README.md +++ b/render-pptx/README.md @@ -11,13 +11,17 @@ compiled in core before either of them runs. ## Status **Experimental (`@Beta`), first shipped in 2.1.0.** The backend is complete -enough for production decks: text, tables, shapes, images, gradients, links and -navigation, headers/footers/watermarks, and multi-section documents all arrive as -native PowerPoint objects rather than pictures. Across the 38 capabilities the -matrix tracks, 24 map to a native equivalent, 10 render natively with an -approximated styling detail (distinct per-corner radii collapse to one value, -numeric dash arrays map to the nearest preset, some inline SVG layers fall back -to a transparent PNG), and 4 are not supported at all — see the limitations below. +enough for production decks: text, tables, shapes, images, gradients, hyperlinks +and slide jumps, headers/footers/watermarks, and multi-section documents all +arrive as native PowerPoint objects rather than pictures. + +Across the 38 capabilities the matrix tracks, 24 map to a native equivalent and 4 +are not supported at all. The remaining 10 are partial, and not all in the same +way. Some render natively with an approximated styling detail — distinct +per-corner radii collapse to one value, numeric dash arrays map to the nearest +preset, a radial gradient uses the closest DrawingML shade. Others lose something +the format cannot carry: bookmarks beyond the first on a slide, parts of an inline +SVG, the metadata producer field. Both kinds are listed under limitations below. The `@Beta` marker covers the *API shape* (`PptxFixedLayoutBackend`, its builder, and the `PptxFragmentRenderHandler` seam), which may still change in a minor @@ -54,8 +58,11 @@ the slide simply takes that size. - **Clipping falls back to a raster island.** A clipped composite is re-rendered through the PDF backend and placed as a picture, so that region loses text - editability and any run-level links inside it. It is pixel-accurate and can be - switched off with `PptxFixedLayoutBackend.builder().clipRasterFallback(false)`. + editability and any run-level links inside it. It is pixel-accurate — the raster + targets a 2048-pixel long edge, clamped between native size and 4×, so a region + larger than that is rendered at native resolution rather than downscaled, at a + transient memory cost proportional to its size. Switch it off with + `PptxFixedLayoutBackend.builder().clipRasterFallback(false)`. True vector clipping is tracked in [#413](https://github.com/DemchaAV/GraphCompose/issues/413). - **Glyphs are drawn by the viewer, not by GraphCompose.** Shape frames, line @@ -74,6 +81,15 @@ the slide simply takes that size. backend — POI's slide rasteriser cannot honour embedded fonts. The session-level `toImage(...)` / `toImages(...)` are unaffected: they resolve the PDF backend explicitly. +- **Bookmarks do not survive as a tree.** PPTX has no outline concept, so the + first bookmark on a page names its slide and further bookmarks on that page are + dropped with a debug note. A bookmark-heavy document loses most of its + navigation structure; hyperlinks and internal slide jumps are unaffected. +- **Inline SVG is native only for simple layers.** Arbitrary clips, exact + dash/cap/join styles and off-viewBox art fall back to a transparent PNG, and + gradient paints use their primary colour. +- **Document metadata loses its producer value** — OPC core properties have no + equivalent field. - **Multi-section documents** render into one deck; the sections must share a slide size.