Skip to content

docs(readme): lead with the engine's own banner, and stop calling a shipped backend planned - #508

Closed
DemchaAV wants to merge 1 commit into
developfrom
feat/readme-hero-banner
Closed

docs(readme): lead with the engine's own banner, and stop calling a shipped backend planned#508
DemchaAV wants to merge 1 commit into
developfrom
feat/readme-hero-banner

Conversation

@DemchaAV

@DemchaAV DemchaAV commented Aug 4, 2026

Copy link
Copy Markdown
Owner

Why

The engine deck contradicted itself on its own first page. The Output Backends
column listed PPTX as Planned, next to a version badge reading v2.1.0 — the
release that shipped it, and the release whose copy of that very deck is published as
engine-deck.pptx. The page also called the library one for "structured business PDF
documents" and ended its pipeline at "PDFBox writes the bytes", both written when PDF was
the only output.

That first page is also, by design, a banner — it is literally the deck's Banner
section — and the composition to render it standalone already existed behind
EngineDeckExample.renderBannerImage, cropped tight, no page chrome, straight to a
raster through the image backend. It wrote to nothing the repository kept. Meanwhile
README opened with a 300px logo.

What

  • EngineDeckData.backends(): PPTX becomes the live @Beta backend, ordered ahead of
    the semantic-only DOCX export. Tagline and pipeline step 4 cover both formats.
  • README leads with that banner, linked to the PDF of the same composition.
  • GenerateAllExamples now renders engine-banner.pdf as well. Without it a committed
    engine-banner.pdf would be a preview nothing refreshes — which the drift gate
    refuses, correctly. Now the release re-renders it like every other preview.
  • New "The engine, explained by the engine" section: the deck, the twin PDF/PPTX
    pair, the feature catalogue, the master showcase and the Maven Central banner.
  • Benchmark snapshot refreshed to a five-run median; both decks and their layout
    baselines re-rendered.

renderBannerImage's Javadoc claimed to be the source of
repository_showcase_render.png. It is not, and has not been since the module-first
EngineDeckV2Example took that over — cut-release.ps1 re-renders the module-first hero
through ReadmeBannerV2Renderer. The two heroes are different compositions with
different jobs, and the Javadoc now says which is which.

On the numbers

None of the deck's prose needed changing for the new data, which is what drawing it from
the result file is for. Each claim verified against the fresh median:

Claim on page 4 Fresh data
"the time lead over iText widens" 2.38x at 40 rows → 3.50x at 200 → 4.25x at 1000
"JasperReports closes to roughly the same render time at 1000 rows" 38.5 ms vs 40.0 ms — 4% apart
"stays markedly lighter on memory than both rivals throughout" 2.5–2.7x vs Jasper, 3.0–3.5x vs iText

At 1000 rows Jasper renders marginally faster in this run and the deck's chart shows it.
Same picture the previous snapshot painted (64.08 vs 64.77 ms, GraphCompose ahead by 1%)
— parity either way, inside a run-to-run spread that ranged 0.72x–1.03x across the five.

Every library also got ~1.65x faster than the July snapshot while peak heap moved under
1%. GraphCompose cannot speed up iText or JasperReports, so that is the machine, not the
code — worth knowing before reading perf-smoke's "IMPROVED" verdict against a baseline
captured on the older state.

Tests

./mvnw -B -ntp clean verifyBUILD SUCCESS.

  • CommittedAssetDriftTest named the two previews that moved — engine-deck.pdf and
    engine-deck-v2.pdf — and confirmed maven-banner.pdf did not.
  • Both deck layout baselines updated deliberately after diffing them: the only structural
    change is the tagline growing from one line to two (13.4pt → 28.1pt) and the sections
    below shifting by that height. No node added, removed or retyped.
  • The catalogue was rendered with -Dgraphcompose.examples.displayVersion=2.1.0. Without
    it a render off develop prints 2.1.1, a coordinate nobody can resolve; that pin is
    what examples/pom.xml holds the drift gate to.
  • Every relative link and image path in README resolves, checked mechanically.

…hipped backend planned

The engine deck's first page listed PPTX as "Planned" beside a version badge
reading v2.1.0 — the release that shipped it, and the release whose own copy of
that deck is published as a .pptx. The page described the library as generating
"structured business PDF documents" and its pipeline as ending in "PDFBox writes
the bytes", both written when PDF was the only output. PPTX is now the live
@beta backend it is, and the prose covers both formats.

README's hero is that same opening page, on a page cropped to wrap it and
rendered straight to a raster through the image backend — the composition was
already there behind renderBannerImage, writing to nowhere the repository kept.
GenerateAllExamples now renders it as a document too, so engine-banner.pdf is a
published preview the drift gate refreshes and compares like any other, rather
than a file only one entry point could produce.

A new section gathers the five documents that explain the engine by being its
output, each with what it shows and the example that renders it.

The benchmark pages are redrawn from a fresh five-run median. The shape is
unchanged: the lead over iText widens with size (2.4x at 40 rows to 4.3x at
1000), JasperReports reaches parity on render time at 1000 rows, and
GraphCompose stays 2.7x lighter than it on peak heap. None of the deck's prose
needed changing for the new numbers, which is the point of drawing them from the
result file.

Also corrects renderBannerImage's Javadoc: it claimed to be the source of
repository_showcase_render.png, which the module-first EngineDeckV2Example has
rendered since, and which cut-release re-renders on a tag.
@DemchaAV
DemchaAV force-pushed the feat/readme-hero-banner branch from 3d84b3c to b5e6765 Compare August 4, 2026 18:19
@DemchaAV DemchaAV changed the title docs(readme): lead with the banner, and stop calling a shipped backend planned docs(readme): lead with the engine's own banner, and stop calling a shipped backend planned Aug 4, 2026
@DemchaAV

DemchaAV commented Aug 4, 2026

Copy link
Copy Markdown
Owner Author

Reverted — the ask was different: keep maven-banner as it is and give it the remaining pages, in the shape engine-deck has. Reopening as a fresh change.

@DemchaAV DemchaAV closed this Aug 4, 2026
@DemchaAV
DemchaAV deleted the feat/readme-hero-banner branch August 4, 2026 18:22
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