From 3a37c95e9a7dbd4db50d76f66bbacc1695c4e71b Mon Sep 17 00:00:00 2001 From: DemchaAV Date: Mon, 3 Aug 2026 16:49:22 +0100 Subject: [PATCH] docs(nav): one recipe catalogue, and the unreachable pages are reachable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The cookbook page and the recipe folder's index each carried a hand-maintained table of all twenty-two recipe pages. They agreed on which pages exist and disagreed on ten descriptions in each direction — the folder index named PDF417 and DataMatrix among the barcode symbologies while the cookbook did not; the cookbook was fuller on themes, transforms and page backgrounds. Neither was a subset, so neither could simply replace the other. Merged into the page the README and the documentation index both point at, taking the better description of each pair. The folder file keeps the one job GitHub gives it, being what you see when you open the directory, and says where the catalogue is rather than holding a copy that drifts. The documentation index stops describing the two as an index and a coverage map; they were the same list. The archive index named its files in code spans rather than links, so the folder's own table of contents led nowhere, and implementation-guide.md was not listed at all. All three are linked now, with what replaced the third. The two notes beside the committed benchmark baseline — the pre-optimization capture and the before/after it was ratcheted against — had no inbound link from anywhere in the repository. The benchmark guide names them where it explains the baseline they produced. The starting-point table asked three "yes" questions — a known template family, pixel-level control, a re-usable new document type — so a reader generating an ordinary report from data matched none of them and fell off the end of the table. The DSL is the default answer, not a fallback. ./mvnw -B -ntp clean verify — BUILD SUCCESS, 692 tests in the closing module. --- CHANGELOG.md | 20 ++++++++++++++++++ docs/README.md | 2 +- docs/archive/README.md | 5 +++-- docs/getting-started.md | 1 + docs/operations/benchmarks.md | 17 ++++++++++++--- docs/recipes.md | 22 +++++++++---------- docs/recipes/README.md | 40 +++++++---------------------------- 7 files changed, 58 insertions(+), 49 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 62af1961d..5c133ce85 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -201,6 +201,26 @@ follow semantic versioning; release dates are ISO 8601. ### Documentation +- **One recipe catalogue instead of two.** The cookbook page and the folder index each + carried a hand-maintained table of all twenty-two recipe pages. They happened to agree + on which pages exist and disagreed on ten of the descriptions — the folder index named + PDF417 and DataMatrix among the barcode symbologies, the cookbook did not; the cookbook + was fuller on themes, transforms and page backgrounds. Merged into the page both the + README and the documentation index point at, taking the better description of each + pair, so nothing is lost. The folder file keeps the one job GitHub gives it — being + what you see when you open the directory — and now says where the catalogue is instead + of holding a copy that drifts. +- **Documents nobody could reach are reachable.** The archive index named its three + files in code spans rather than links, so the folder's own table of contents did not + actually lead anywhere, and one of the three was not listed at all. The two benchmark + notes sitting beside the committed baseline had no inbound link from anywhere; the + benchmark guide names them now, and says what they are — an April 2026 capture and the + before/after of the optimization round it belonged to, six weeks older than the + baseline file and unrelated to it. +- **The starting-point table has an answer for the ordinary document.** Its three rows + each asked a "yes" question — a known template family, pixel-level control, a re-usable + new type — and a reader generating an ordinary report from data matched none of them + and fell off the end. The DSL is the default, not the fallback, and the table says so. - **The example catalogue stops calling current code legacy.** Two examples sat under a heading reading "🗄️ Legacy — pre-rebuild examples kept for downstream callers still on V1; do not start new code here", pointing at a V1 → V2 migration guide. There is no diff --git a/docs/README.md b/docs/README.md index 7e952f5a6..75840dc5d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -79,7 +79,7 @@ Kept for anyone stepping through the 1.x line one minor at a time. Nothing here ### Recipes (cookbook-style howtos) -- **[recipes.md](recipes.md)** — index of all recipes (coverage map in [recipes/README.md](recipes/README.md)). +- **[recipes.md](recipes.md)** — the catalogue: every recipe page and what it covers. - **[recipes/charts.md](recipes/charts.md)** — native vector bar/line/area/pie charts. - **[recipes/keep-together.md](recipes/keep-together.md)** — blocks that never split at a page break. - **[recipes/shapes.md](recipes/shapes.md)** — cards, dividers, lines, ellipses, images. diff --git a/docs/archive/README.md b/docs/archive/README.md index b3da7048f..8817d02a6 100644 --- a/docs/archive/README.md +++ b/docs/archive/README.md @@ -22,5 +22,6 @@ The current docs live under [`docs/`](../) at the repository root: | File | Why archived | | --- | --- | -| `v1.2-roadmap.md` | Roadmap planning notes for the v1.2 release. Superseded by `CHANGELOG.md` for shipped features and by the Phase A–F execution plan for in-flight work. | -| `migration-v1-1-to-v1-2.md` | Migration guide from v1.1 to v1.2. Both versions are out of support; v1.4 → v1.5 callers should follow the migration doc at `docs/roadmaps/migration-v1-4-to-v1-5.md`. | +| [`v1.2-roadmap.md`](v1.2-roadmap.md) | Roadmap planning notes for the v1.2 release. Superseded by `CHANGELOG.md` for shipped features and by the Phase A–F execution plan for in-flight work. | +| [`migration-v1-1-to-v1-2.md`](migration-v1-1-to-v1-2.md) | Migration guide from v1.1 to v1.2. Both versions are out of support; v1.4 → v1.5 callers should follow the migration doc at `docs/roadmaps/migration-v1-4-to-v1-5.md`. | +| [`implementation-guide.md`](implementation-guide.md) | Implementation notes for an engine model 2.0 removed. The current route for adding a node, a handler or a backend is [`docs/contributing/extension-guide.md`](../contributing/extension-guide.md), with [`docs/architecture/package-map.md`](../architecture/package-map.md) for where things live. | diff --git a/docs/getting-started.md b/docs/getting-started.md index bccf89c49..6dc7801ca 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -19,6 +19,7 @@ tree to choose the right one for the document you're rendering. | Is your document one of the template families (CV, cover letter, invoice, proposal)? | Yes | **Layered template preset.** Skip ahead to "Templates". | | Do you need pixel-level control over a one-off PDF? | Yes | **Raw DSL** (`DocumentSession.pageFlow(...)`). | | Do you need a re-usable scene for a *new* business document type? | Yes | **Custom template that wraps the DSL.** Implement `DocumentTemplate` and take a `BrandTheme` for visual coherence. | +| Anything else — a report, a statement, a brochure, one-off or generated from data | — | **Raw DSL.** This is the default answer, not a fallback: the DSL is the authoring surface, and templates are presets built on it. Continue with "Quick start" below. | The DSL and the templates compose against the SAME `DocumentSession` — a template can also live alongside hand-written DSL inside one diff --git a/docs/operations/benchmarks.md b/docs/operations/benchmarks.md index b8f184a82..b6f18c64b 100644 --- a/docs/operations/benchmarks.md +++ b/docs/operations/benchmarks.md @@ -284,7 +284,9 @@ cleanest numbers. `baselines/current-speed-full.json` is a committed median `current-speed` report that `11-verdict-current-speed` judges new runs against (hard gate: average -latency ±10%; peak heap is advisory, GC-timing noisy). Refresh it **only** for an +latency ±10%; peak heap is advisory, GC-timing noisy). + +Refresh it **only** for an intended, verified improvement so the gate ratchets down — never to turn a red gate green. Capture a median of **≥5** runs on the branch that defines the new reference, with the IDE closed: @@ -312,8 +314,17 @@ java -cp "$cp" com.demcha.compose.BenchmarkMedianTool current-speed $runs cp -f target/benchmarks/aggregates/current-speed/full/latest.json baselines/current-speed-full.json ``` -The baseline is machine-class-specific; the JSON records provenance -(`timestamp`, `profile`, `sourceRuns`). Validate the refresh against a *fresh* +The baseline is machine-class-specific; the JSON records its own provenance +(`timestamp`, `profile`, `sourceRuns`) — read those rather than inferring where the +numbers came from. Two older notes share the folder and are **historical context +only**: [`baselines/BASELINE_SUMMARY.md`](../../baselines/BASELINE_SUMMARY.md) is a +smoke-profile capture from April 2026, taken before a round of engine optimization, +and [`baselines/COMPARISON.md`](../../baselines/COMPARISON.md) is that round's +before/after. Neither produced this baseline and neither tracks it: the JSON was first +cut six weeks later as a separate full-profile median when the verdict gate landed, and +has been re-measured independently since. + +Validate the refresh against a *fresh* run — not one of the five that built the median — on that branch; it should score NEUTRAL and exit `0`: diff --git a/docs/recipes.md b/docs/recipes.md index e66431a3c..81700d01c 100644 --- a/docs/recipes.md +++ b/docs/recipes.md @@ -16,19 +16,19 @@ authoring API; public application code should not import | [Shape-as-container](recipes/shape-as-container.md) | `addCircle` / `addEllipse` / `addContainer` with `ClipPolicy` (clipped layered children) | | [Transforms and z-index](recipes/transforms.md) | `rotate` / `scale` mixin, per-layer `zIndex` for overlays | | [Page backgrounds](recipes/page-backgrounds.md) | `pageBackground` / `pageBackgrounds`, `PageBackgroundFill` columns, bands, point-based fills, layering | -| [Layered page design](recipes/layered-page-design.md) | Choosing between page backgrounds, rows, layer stacks, and canvases | +| [Layered page design](recipes/layered-page-design.md) | Page background vs. row vs. layer stack vs. canvas — choosing the layer | | [Absolute placement](recipes/absolute-placement.md) | `addCanvas` + `position(x, y)` for pixel-precise certificates and badges | | [Tables](recipes/tables.md) | Row span, zebra rows, totals row, repeated header on page break | -| [Rich text](recipes/rich-text.md) | `RichText` mixed-style runs, inline links/images/shapes, SVG icons, emoji shortcodes, checkboxes | -| [Lists](recipes/lists.md) | `addList`, marker customisation, nested lists with per-depth markers | -| [Timelines](recipes/timelines.md) | `addTimeline`: markers on a connector rail, geometry and text-style controls | -| [Barcodes](recipes/barcodes.md) | QR / Code 128 / EAN / UPC and friends, tinting, quiet zone | -| [Images](recipes/images.md) | Sources, sizing precedence, fit modes, images in rows and cards | -| [PDF chrome](recipes/pdf-chrome.md) | Metadata, watermarks, running header/footer placeholders, protection, links, bookmarks | -| [In-PDF navigation](recipes/in-pdf-navigation.md) | Anchors + internal `linkTo` links: clickable contents, heading jumps, bidirectional footnotes, inline-graphic links | -| [Translucency](recipes/translucency.md) | `DocumentColor.rgba` / `withOpacity`, alpha coverage, layered tints | -| [DOCX export](recipes/docx-export.md) | Semantic export, node mapping, fallbacks and skipped kinds | -| [Snapshot testing](recipes/snapshot-testing.md) | Layout-snapshot regression testing in consumer projects | +| [Rich text](recipes/rich-text.md) | `RichText` mixed-style runs in one paragraph: bold/accent/styled segments, inline links, inline images, inline SVG icons, emoji shortcodes, inline shapes and checkboxes | +| [Lists](recipes/lists.md) | `addList`: quick bulleted lists, marker customisation, nested lists with per-depth markers, spacing and styled items | +| [Timelines](recipes/timelines.md) | `addTimeline`: markers (dot / circle / numbered / square) on a connector rail, geometry and text-style controls, pagination opt-ins | +| [Barcodes](recipes/barcodes.md) | QR / Code 128 / Code 39 / EAN / UPC / PDF417 / DataMatrix, tinting, quiet zone, card centring | +| [Images](recipes/images.md) | Sources (bytes/path), sizing precedence, STRETCH/CONTAIN/COVER fit modes, images in rows and cards | +| [PDF chrome](recipes/pdf-chrome.md) | Metadata, watermarks, running header/footer with `{page}/{pages}/{date}`, protection, links and outline bookmarks | +| [In-PDF navigation](recipes/in-pdf-navigation.md) | Named `anchor(...)` destinations + internal `linkTo(...)` links: clickable tables of contents, `#heading`-style jumps, bidirectional footnotes, inline-graphic links — native PDF GoTo actions | +| [Translucency](recipes/translucency.md) | `DocumentColor.rgba` / `withOpacity`: which primitives honour alpha, byte-identity for opaque colours, layered tints | +| [DOCX export](recipes/docx-export.md) | Semantic DOCX export: 1:1 node mapping, chart/shape-container fallbacks, skipped kinds | +| [Snapshot testing](recipes/snapshot-testing.md) | Layout-snapshot regression testing in consumer projects, baseline update flow | | [Streaming and output](recipes/streaming.md) | `buildPdf` / `writePdf` / `toPdfBytes`, DOCX export, layout snapshots, header / footer chrome, guide lines | | [Extending GraphCompose](recipes/extending.md) | New semantic node, fluent setter, render backend, snapshot-based regression tests | diff --git a/docs/recipes/README.md b/docs/recipes/README.md index a16f1d68f..f3055321c 100644 --- a/docs/recipes/README.md +++ b/docs/recipes/README.md @@ -1,34 +1,10 @@ # Recipes -Task-oriented guides: each page shows how to use one slice of the canonical -API, with copy-pasteable snippets verified against the current release. - -## Available recipes - -| Recipe | Covers | -|---|---| -| [charts.md](charts.md) | Native vector bar / line / area / pie-donut charts: data–spec–style layers, axis & grid toggles, point markers, value-label halos, legend placement, translucent area fills | -| [rich-text.md](rich-text.md) | `RichText` mixed-style runs in one paragraph: bold/accent/styled segments, inline links, inline images, inline SVG icons, emoji shortcodes, inline shapes and checkboxes | -| [lists.md](lists.md) | `addList`: quick bulleted lists, marker customisation, nested lists with per-depth markers, spacing and styled items | -| [timelines.md](timelines.md) | `addTimeline`: markers (dot / circle / numbered / square) on a connector rail, geometry and text-style controls, pagination opt-ins | -| [keep-together.md](keep-together.md) | `keepTogether()` / `keepEntriesTogether()` — blocks that relocate whole instead of orphaning a heading at a page break | -| [shapes.md](shapes.md) | Filled cards, dividers, accent bars, lines, spacers, ellipses, images | -| [shape-as-container.md](shape-as-container.md) | Circles/ellipses/rounded cards holding clipped children, `ClipPolicy` | -| [absolute-placement.md](absolute-placement.md) | `CanvasLayerNode` — children at explicit (x, y) | -| [layered-page-design.md](layered-page-design.md) | Page background vs. row vs. layer stack vs. canvas — choosing the layer | -| [page-backgrounds.md](page-backgrounds.md) | Per-page fills: sidebars, bands, layered tints | -| [transforms.md](transforms.md) | Rotation, scaling, skewing | -| [tables.md](tables.md) | Tabular layouts: columns, headers, zebra rows, composed cells | -| [themes.md](themes.md) | `BrandTheme` factories and custom token bundles | -| [barcodes.md](barcodes.md) | QR / Code 128 / Code 39 / EAN / UPC / PDF417 / DataMatrix, tinting, quiet zone, card centring | -| [images.md](images.md) | Sources (bytes/path), sizing precedence, STRETCH/CONTAIN/COVER fit modes, images in rows and cards | -| [pdf-chrome.md](pdf-chrome.md) | Metadata, watermarks, running header/footer with `{page}/{pages}/{date}`, protection, links and outline bookmarks | -| [in-pdf-navigation.md](in-pdf-navigation.md) | Named `anchor(...)` destinations + internal `linkTo(...)` links: clickable tables of contents, `#heading`-style jumps, bidirectional footnotes, inline-graphic links — native PDF GoTo actions | -| [translucency.md](translucency.md) | `DocumentColor.rgba` / `withOpacity`: which primitives honour alpha, byte-identity for opaque colours, layered tints | -| [docx-export.md](docx-export.md) | Semantic DOCX export: 1:1 node mapping, chart/shape-container fallbacks, skipped kinds | -| [snapshot-testing.md](snapshot-testing.md) | Layout-snapshot regression testing in consumer projects, baseline update flow | -| [streaming.md](streaming.md) | Streaming PDFs to HTTP responses | -| [extending.md](extending.md) | Extension patterns: custom nodes via the `NodeDefinition` SPI | - -Every shipped feature now has a recipe; the runnable -[examples](../../examples/README.md) remain the end-to-end references. +Task-oriented guides: each page shows how to use one slice of the canonical API, with +copy-pasteable snippets verified against the current release. + +The catalogue — every page in this folder and what it covers — lives one level up, in +**[`docs/recipes.md`](../recipes.md)**. That is the page the root README and the +documentation index point at, so it is the one kept current; this file used to carry a +second copy of the same table, and two hand-maintained copies of one list only ever +agree until they don't.