docs(pptx): describe the shipped fixed-layout backend#437
Merged
Conversation
…evelopment The per-capability cells already list the PPTX fixed-layout backend as implemented (✅/⚠️ ), but the backend descriptor still read "(in development)" — which the legend defines as "not usable yet". That contradicts the README and docs/api-stability.md, where the backend ships as @beta (Experimental). Restate the descriptor as implemented and shipping @beta so the capability matrix agrees with the policy and the changelog.
The roadmap still described 2.0 as in flight on the retired `2.0-dev` branch preparing GA, named v1.9.x the current stable, and listed real PPTX export under "Later" as a manifest skeleton — contradicting the code, README and changelog. Retarget it: "Now" is the 2.1 line (the fixed-layout PPTX @beta backend plus the keep-with-next pagination work), 2.0.0 is the current stable line, and PPTX moves from "manifest skeleton" to a beyond-beta graduation item. Drop the two post-2.0 items that have since shipped — the ArchUnit module-boundary guards and the cross-module coverage aggregator.
The module landing page for graph-compose-render-pptx still told readers that `.pptx` emission "is not built out yet" and to depend on the artifact "not for production slide export" — against 37 shipped production classes, a registered SPI, and the headline feature of the release. docs/capabilities.md listed the PPTX methods as Stable while the code marks them `@Beta`, and CONTRIBUTING sent contributors to `2.0-dev`, a branch that no longer exists. Rewrite render-pptx/README.md around the fixed-layout backend: what it produces, a first deck, the limitations worth knowing before shipping (raster fallback for clipped regions, viewer-side glyph rendering, opt-in determinism, unimplemented `renderToImages`, PDF-only chrome options), and the fact that a PPTX consumer also resolves the PDF stack because the backend reuses its font measurement and raster pass. Quantify the capability picture rather than promising blanket native output: of the 38 tracked capabilities, 24 map to a native equivalent, 10 render natively with an approximated styling detail, and 4 are unsupported. Correct the stability tier in docs/capabilities.md to Experimental (`@Beta`) so it agrees with the annotations and with docs/api-stability.md, and add the two `document.backend.fixed.pptx` packages to the §4 tier lookup, which the page's own maintenance rule requires. Refresh the frozen "New in" table to 2.1.0. Give PPTX a path in the docs: an Output backends section in the index and a PowerPoint section in getting-started, whose snippet carries a `doc-example` marker so it is compiled against the live API. Soften the root README's geometry promise to the capability matrix's own wording — frames and positions match, glyphs are rasterised by the viewer. Retarget ROADMAP to the 2.1 line, drop the "manifest skeleton" entry, and replace every `2.0-dev` reference in CONTRIBUTING with the post-GA branch roles. Install snippets are left alone: cut-release.ps1 rewrites the per-module ones in the release commit and VersionConsistencyGuardTest requires them to name the latest published release until then. Verified: full reactor `clean verify` green (1508 tests, 0 failures); core guards 402/402 and the documentation snippet guard green against the final text.
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
1 participant
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
render-pptx/README.md— the page GitHub renders for the module — still says.pptxemission "is not built out yet" and tells readers to depend on the artifact "not for production slide export". That is against 37 shipped production classes, a registered SPI, and the headline feature of 2.1.docs/capabilities.mdlists the PPTX methods as Stable while the code marks them@Beta, contradictingdocs/api-stability.md.CONTRIBUTING.mdsends contributors to2.0-dev, a branch that no longer exists on origin, anddocs/README.md/docs/getting-started.mdhave zero PPTX mentions.What changed
render-pptx/README.mdrewritten around the fixed-layout backend: what it produces, a first deck, and the limitations worth knowing before shipping — raster fallback for clipped regions, viewer-side glyph rendering, opt-in determinism, unimplementedrenderToImages, PDF-only chrome options — plus the fact that a PPTX consumer also resolves the PDF stack, because the backend reuses its font measurement and raster pass.PptxSemanticBackendis demoted to a footnote.docs/capabilities.mdPPTX row →Experimental (@Beta, first shipped in 2.1.0); the "New in" table, frozen at 1.9.0, gains a 2.1.0 section.docs/api-stability.md§4 gains bothdocument.backend.fixed.pptxpackages — the page's own maintenance rule requires it in the same commit.docs/README.mdgains an Output backends section;docs/getting-started.mdgains a PowerPoint output section whose snippet carries adoc-examplemarker, soDocumentationSnippetCompileTestnow compiles it against the live API. That file previously had no marked snippets at all.README.mdgeometry promise softened to the capability matrix's own wording: frames and positions match, glyphs are rasterised by the viewer.ROADMAP.mdretargeted to the 2.1 line, "manifest skeleton" entry dropped;CONTRIBUTING.md2.0-devreplaced with the post-GA branch roles in all eight places;canonical-legacy-parity.mdno longer lists PPTX as a v1.6 stretch goal.Install snippets are untouched:
cut-release.ps1rewrites the per-module ones in the release commit, andVersionConsistencyGuardTestrequires them to name the latest published release until then.Verification
./mvnw -B -ntp clean verify— BUILD SUCCESS, 1508 tests, 0 failures.DocumentationSnippetCompileTestre-run against the final text after the last edit.