Skip to content

docs(readme): make the hero the banner the release advertises - #561

Merged
DemchaAV merged 2 commits into
developfrom
docs/readme-maven-banner-hero
Aug 15, 2026
Merged

docs(readme): make the hero the banner the release advertises#561
DemchaAV merged 2 commits into
developfrom
docs/readme-maven-banner-hero

Conversation

@DemchaAV

@DemchaAVDemchaAV commented Aug 15, 2026

Copy link
Copy Markdown
Owner

Why

The image at the top of README was a page of the module-first deck, and the caption beside
it linked a third document again. The Maven banner is the one written to be seen first — it
names the coordinate, the version and the outputs, and the release re-renders it on every
version bump — and nothing on the front page pointed at it.

2.2 is the right-to-left line, and the banner said nothing about it.

What changed

  • The hero is page one of the Maven banner.ReadmeHeroRenderer replaces
    ReadmeBannerV2Renderer and writes the same assets/readme/repository_showcase_render.png,
    so the release keeps its staging list and the version stamped into the image still arrives
    from the version bump. One line of the script names the new class.
  • The banner gained a fifth page. Amiri, David Libre, the two Noto faces and Gothic A1
    each set a word, and where that word sits in its card is the direction it declared — Hebrew
    and Arabic to the right, the rest to the left. Three cards below say what the engine does
    with them: resolve the line through UAX Backport to Java 17 #9, shape Arabic before measuring it, hand each
    backend what its own text engine needs.
  • The README caption links maven-banner.pdf and the example that renders it. The gallery
    row and the showcase blurb stop calling the banner a single slide — it has been four pages
    since before this change.
  • EngineDeckV2Example.renderBannerImage is removed: the hero was its only caller, and
    the class comment that said the switch had not happened yet was written before it did.
  • A guard on the step that renders the hero. The class name and the output path are
    strings the compiler never reads: the script hands the class to exec:java as text, and one
    part of it writes the file while another stages it. Each half is now read out of the script
    rather than restated here, so a rename or a dropped staging line fails at test time instead
    of mid-cut. Driven from the script's own text in five broken states.
  • Two sentences that stopped being true in this release: the RTL examples entry still said
    a table cell has no direction, and the drift test still said nothing moved the version its
    previews are compared at.

Tests

./mvnw -B -ntp clean verifyBUILD SUCCESS.
./mvnw -B -ntp -f examples/pom.xml testBUILD SUCCESS, 75 tests.

Two guards moved with the fifth page: the deck's slide count and its committed preview. The
new page is native — the deck's only rasterised element is still the checkmark in the badge.
The hero renders at 2666×1500, the size of the file it replaces, and carries 2.1.1 rather
than the working tree's version.

Note

The deck goes from 41 KB to 1.3 MB. All of it is fonts: PowerPoint is handed each of the five
families whole rather than subset, and Gothic A1 alone is 688 KB compressed. The PDF grew by
16 KB, because a PDF embeds the glyphs it draws.

That is the page working rather than the page costing. A deck that sets Hebrew and Arabic and
carries no fonts is a deck that renders them on whatever the reader happens to have installed —
which is the problem the bundled families exist to end, and what anybody shipping a right-to-left
document pays too. Subsetting the embedded copy would cut it, and that is a backend change with
its own tests, not a reason to take a script off the page.

The image at the top of README was a page of the module-first deck, and the
caption beside it linked a third document again. The Maven banner is the one
written to be seen first — it names the coordinate, the version and the
outputs, and the release re-renders it on every version bump — and nothing on
the front page pointed at it.
So the hero is page one of that banner, written to the file it always was:
ReadmeHeroRenderer replaces ReadmeBannerV2Renderer at the same output path, so
the release script keeps its staging list and the version stamped into the
image keeps arriving from the same place. One line of the script names the new
class.
The banner gained a page for the release it is advertising. Amiri, David Libre,
the two Noto faces and Gothic A1 each set a word, and where that word sits in
its card is the direction it declared — Hebrew and Arabic to the right, the
rest to the left. Three cards below say what the engine does with them: resolve
the line through UAX #9, shape Arabic before measuring it, hand each backend
what its own text engine needs.
The deck now embeds those five families, which is where its size goes:
PowerPoint is handed each font whole rather than subset.
Two guards moved with the page — the deck's slide count, and its committed
preview. The deck's only rasterised element is still the checkmark in the
badge.
…s it
Three sentences the change above made false, and one it left behind.
The README caption said the banner embeds no images: the badge checkmark
rasterises in the PPTX, which the deck's own shape guard asserts by name. The
CHANGELOG said what re-renders the hero is unchanged, when that is the one part
that changed — the path and the step's place in the cut are what survived. The
gallery row and the showcase blurb called the banner a single slide; it has been
four pages since before this branch, and is five now. And the deck's banner
image method lost its only caller, next to a class comment written while the
release still pointed at it.
The step that renders the hero had no guard. Its two halves are strings the
compiler never reads — the script hands the class to exec:java as text, and one
part of it writes the file while another stages it — so a rename reaches the
maintainer as a cut that has already bumped the version. Both halves are now
read out of the script rather than restated in the test, driven from its text in
five broken states: the hero class renamed, another exec class renamed, the step
writing elsewhere, the staging line dropped, the step gone.
@DemchaAV
DemchaAVforce-pushed the docs/readme-maven-banner-hero branch from 913d13d to 93e8a64CompareAugust 15, 2026 11:00
@DemchaAV
DemchaAV merged commit fec2cba into developAug 15, 2026
14 checks passed
@DemchaAV
DemchaAV deleted the docs/readme-maven-banner-hero branch August 15, 2026 11:31
Sign up for freeto 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

@DemchaAV