Skip to content

docs(examples): add the twin-output dual-format hook example and README section#422

Merged
DemchaAV merged 2 commits into
developfrom
docs/twin-output-hook
Jul 19, 2026
Merged

docs(examples): add the twin-output dual-format hook example and README section#422
DemchaAV merged 2 commits into
developfrom
docs/twin-output-hook

Conversation

@DemchaAV

@DemchaAV DemchaAV commented Jul 19, 2026

Copy link
Copy Markdown
Owner

Stacked on #421 (the beta designation the README section references); retarget to develop before merging that parent.

Why

The dual-output story — one Java composition emitting a print-ready PDF and an editable PowerPoint deck with identical geometry — is the library's strongest hook, but nothing in the README demonstrated it. The Engine Deck row mentions buildPptx() in passing; there was no artifact a visitor could open, no visual proof the formats match, and no evidence the slides are actually editable.

What

  • TwinOutputExample (366 lines): a single 16:9 hook page in the release-banner visual language, written once and emitted twice from the same DocumentSessionbuildPdf() plus buildPptx(Path). The page states the hook itself: headline, the exact API call in a code panel, a layout-graph → two-backends diagram, and proof chips. Registered in GenerateAllExamples and ShowcaseMetadata.
  • README section "One source → a PDF and an editable PowerPoint deck", right under the hero banner: a self-contained snippet, the PDF render side by side with PowerPoint's own PNG export of the generated slide (not a re-render — the actual .pptx exported by the actual viewer), and a screenshot of the deck open in PowerPoint with a headline text frame selected and the formatting ribbon live. The committed slide lands 69 native shapes; the only picture is the clip-masked logo art, and the copy says exactly that.
  • The masthead tagline now says "structured business documents" and the Output support matrix's PPTX row is updated from the stale "Skeleton / not a real export yet" to Beta — the old row directly contradicted the hook section three screens above it.
  • Committed artifacts under assets/readme/: the three PNGs plus the openable twin-output.pdf / twin-output.pptx pair; a Twin Output row in the examples gallery; a CHANGELOG Documentation entry.

Verification

  • TwinOutputLayoutSnapshotTest pins the page geometry against a committed baseline (one baseline guards both artifacts, since both backends consume the same resolved layout); TwinOutputNativeShapeTest opens the generated .pptx with POI and asserts the slide stays native — exactly one picture (the clipped logo) and 60+ native shapes — so a clip-safety regression cannot silently falsify the README's editability claim.
  • Examples suite 37/37, qa suite 647/647, and the core README guard (canonical-fingerprint / legacy-API scan) green. The README snippet itself is illustrative and not compile-guarded — no repo gate compiles root-README fences — which is why it is written self-contained (Path deck declared, every call a real public-API method).
  • The committed .pptx verified structurally: 69 <p:sp> native shapes, 1 <p:pic> (the clipped logo), 0 groups.
  • Both README proof images are generated from the committed artifacts: the PDF side rasterized at 144 DPI, the PPTX side exported by PowerPoint itself via COM. The editing screenshot was captured from the live PowerPoint window with the text frame selected and shows the previous revision of the code card (one line shorter); functionally identical proof, retake pending.

@DemchaAV
DemchaAV changed the base branch from chore/pptx-beta-designation to develop July 19, 2026 20:07
@DemchaAV
DemchaAV force-pushed the docs/twin-output-hook branch from 5a61dea to ccc7e4b Compare July 19, 2026 20:08
@DemchaAV
DemchaAV merged commit eb06218 into develop Jul 19, 2026
10 checks passed
@DemchaAV
DemchaAV deleted the docs/twin-output-hook branch July 19, 2026 20:13
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