docs(examples): rebuild the Book template flagship on the v1.9 book primitives#245
Merged
Conversation
…rimitives The Book template example — the document whose construction drove the v1.9 book work — still assembled itself the old way: three DocumentSessions glued with PDFBox PDFMergerUtility, a throwaway layoutSnapshot() pass to learn chapter page numbers, and a hand-computed dot-leader width. It also reached into PDFBox (pulled in transitively), was untracked, and ran in no batch. Rebuilt on the APIs that replaced each workaround, in one DocumentSession: a full-bleed wave cover via pageMargins(page(1, zero())); a clickable addTableOfContents(...) whose DOTS leaders and live page numbers resolve in one pass from chapter anchors; DocumentPageNumbering(showOnFirstPage=false) to leave the cover unnumbered; section bookmark(...) plus viewerPreferences(openOutline()) so the reader opens on the outline. No org.apache.pdfbox, no two-pass probe, no manual leader math. Wired into GenerateAllExamples and the examples README flagship gallery, with a committed preview.
Drop the stale 'Contents' bookmark from the outline description (the table of contents emits no outline entry — the panel lists the cover and each chapter), and move the example's import into the features.* group. Refresh the committed book-template preview so its contents leaders sit on the baseline, matching the TOC leader fix.
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
The
BookTemplateExampleis the document whose construction drove the whole v1.9 book-primitives series (#228–#244) — but it was never migrated onto the APIs that series shipped. It still assembled itself the old way (and was untracked, reaching into PDFBox transitively, wired into no batch):DocumentSessions glued with PDFBoxPDFMergerUtility,layoutSnapshot()pass to learn chapter page numbers,This closes the loop: the flagship now renders without any of the workarounds the series removed.
What changed
Rebuilt the book in one
DocumentSession, each part on the API that replaced its workaround:PDFMergerUtilitypageMargins(List.of(PageMarginRule.page(1, DocumentInsets.zero())))— page 1 bleeds, the rest keep book marginslayoutSnapshot()probe for TOC numbersaddTableOfContents(...)resolving each chapter's page in one pass from itsanchor(...)LEADER_WIDTH, square dashesDocumentLeader.DOTS— aline().fill()leader with round capsDocumentPageNumbering.builder().showOnFirstPage(false)bookmark(...)+chrome().viewerPreferences(openOutline())No
org.apache.pdfboximport, no two-pass probe, no manual leader math. Wired intoGenerateAllExamplesand the examples README flagship gallery, with a committed preview.Verification
./mvnw -f examples/pom.xml compile— green. Runs:Wrote …/book-template.pdf(6 pages).fitzconfirms internal links → page index 2 / 5); the outline lists Cover + both chapters; the cover page carries no footer number.Follow-up to the book-template gap series; this is the end-to-end proof that G1–G8 are closed.