Skip to content

docs: stop offering an examples-local type, and drop the counts that keep rotting #482

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
DemchaAV merged 4 commits into from
Aug 1, 2026
Merged

docs: stop offering an examples-local type, and drop the counts that keep rotting #482

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
98a2acf
docs: stop offering an examples-local type, and drop the counts that …
DemchaAV Aug 1, 2026
9dff48f
docs: say what the cover letter actually uses, and police the form th…
DemchaAV Aug 1, 2026
ceb7900
docs: scan every published page, and every code block that is not a q…
DemchaAV Aug 1, 2026
bf10de6
Merge branch 'develop' into docs/last-untrue-text
DemchaAV Aug 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,25 @@ follow semantic versioning; release dates are ISO 8601.

### Documentation

- **The example catalogue stops offering a type that ships nowhere.** Its entry-point
table introduced the cover letter as a `BusinessTheme.modern()` document, and
`BusinessTheme` is a record local to the examples module — a reader adding the
dependency and reaching for it finds nothing to import. The rows and prose now say
what the examples demonstrate, the advanced section that quotes the helper says
plainly that it is examples-local and names `BrandTheme` as the shipping equivalent,
and a guard rejects the factory-call form on any README while leaving the quotation
of an example's own source alone.
- **The last hardcoded counts are gone.** The example catalogue named a number of
generated documents and a number of committed previews; both sat well below the real
inventory, having been reconciled by hand once already and drifted again since. The
banner caption stated a line count for the example it links, and named the module graph
by a version the image itself no longer shows. All four are removed rather than
corrected — a count in prose has no owner and nothing to keep it true, so correcting
one only resets the clock.
- **The contributing guide's commit examples match the convention it asks for.** It
pointed at two subjects from the 1.5 line as the shape to copy, while the repository
has moved to Conventional Commits and the pull-request template requires that shape in
a title. The examples are two real recent subjects instead.
- **Documented headings render bold, and say why.** Six snippets across the
getting-started guide, the root README and the theme, timeline, rich-text and
preset-authoring recipes set `fontName(FontName.HELVETICA_BOLD)` without a
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ Almost all work targets **`develop`**, the ongoing 2.x line. The `1.x` branch ta
git checkout -b feature/short-description
```
Use `feature/...` for new functionality, `fix/...` for bug fixes, and `docs/...` for documentation-only changes. Issue-prefixed names (`42/fix/short-description`) are also welcome — convenient when the branch closes a specific issue.
3. **Commit small, focused changes.** Each commit message should describe the *why*, not just the *what*. Recent commits on `develop` (`Prepare v1.5.0 release`, `Align public docs with the canonical surface`) are reasonable length and structure templates.
3. **Commit small, focused changes.** Subjects follow Conventional Commits — `type(scope): the concrete effect` — the same shape the [pull request template](.github/pull_request_template.md) asks of a PR title. Say the *why*, not only the *what*. `git log --oneline -20` on `develop` is the reference; `fix(font): the donut-centre KPI renders the weight it declares` and `ci(guards): run every guard the job names, and compile docs-only pull requests` are the shape.
4. **Run the validation gate locally** before opening a PR:
```bash
./mvnw -B -ntp clean verify
Expand Down
4 changes: 2 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@
</p>

<p align="center">
<sub>☝ This banner is itself a GraphCompose document — <a href="./assets/readme/examples/engine-deck-v2.pdf"><b>view the full module-first deck (PDF)</b></a>, rendered by <a href="./examples/src/main/java/com/demcha/examples/flagships/EngineDeckV2Example.java"><code>EngineDeckV2Example</code></a>: the 2.0 module graph, native vector charts, and real comparative benchmarks, all drawn by the engine. It renders its own marketing.</sub>
<sub>☝ This banner is itself a GraphCompose document — <a href="./assets/readme/examples/engine-deck-v2.pdf"><b>view the full module-first deck (PDF)</b></a>, rendered by <a href="./examples/src/main/java/com/demcha/examples/flagships/EngineDeckV2Example.java"><code>EngineDeckV2Example</code></a>: the module graph, native vector charts, and real comparative benchmarks, all drawn by the engine. It renders its own marketing.</sub>
</p>

## One source → a PDF <i>and</i> an editable PowerPoint deck
Expand Down Expand Up @@ -77,7 +77,7 @@ try (DocumentSession doc = GraphCompose.document(Path.of("twin-output.pdf"))
<img src="./assets/readme/twin-output-editing.png" alt="The generated deck open in PowerPoint with the headline text frame selected for editing" width="820"/>
</p>
<p align="center">
<sub>☝ The generated deck open in PowerPoint — the headline is a selected, editable text frame, and the ribbon is live because the slide is built from native shapes. Artifacts: <a href="./assets/readme/examples/twin-output.pdf"><b>PDF</b></a> · <a href="./assets/readme/examples/twin-output.pptx"><b>PPTX</b></a> · <a href="./examples/src/main/java/com/demcha/examples/flagships/TwinOutputExample.java"><b>source</b></a> (<code>TwinOutputExample</code>, ~370 lines, page included).</sub>
<sub>☝ The generated deck open in PowerPoint — the headline is a selected, editable text frame, and the ribbon is live because the slide is built from native shapes. Artifacts: <a href="./assets/readme/examples/twin-output.pdf"><b>PDF</b></a> · <a href="./assets/readme/examples/twin-output.pptx"><b>PPTX</b></a> · <a href="./examples/src/main/java/com/demcha/examples/flagships/TwinOutputExample.java"><b>source</b></a> (<code>TwinOutputExample</code>, one page, source included).</sub>
</p>

## Why GraphCompose
Expand Down
25 changes: 15 additions & 10 deletions examples/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,10 +34,10 @@ Generated PDFs land in `examples/target/generated-pdfs/`. The same

`GenerateAllExamples` renders the whole catalogue in one pass — the CV and
cover-letter presets plus invoices, proposals, a schedule, the feature
demos, and the flagships. The showcase site surfaces the full generated
catalogue (~53 PDFs); a curated 39-PDF subset is committed under
[`assets/readme/examples/`](../assets/readme/examples/) for the previews
linked below.
demos, and the flagships. The showcase site publishes the whole generated
catalogue; a curated subset is committed under
[`assets/readme/examples/`](../assets/readme/examples/) so the previews
linked below open straight from GitHub.

## Gallery — pick by your goal

Expand All @@ -58,7 +58,7 @@ are with the canonical DSL, then jump to its detailed section below.
|---|---|---|
| [CV — single template](#cv-single-template) | One CV via `ModernProfessional.create()` on a `CvDocument` | [PDF](../assets/readme/examples/cv-modern-professional.pdf) · [Source](src/main/java/com/demcha/examples/templates/cv/CvFileExample.java) |
| [Invoice — cinematic V2](#invoice-cinematic-v2) | `ModernInvoice + BrandTheme.invoiceModern()` — the recommended invoice path | [PDF](../assets/readme/examples/invoice-cinematic.pdf) · [Source](src/main/java/com/demcha/examples/templates/invoice/InvoiceCinematicFileExample.java) |
| [Cover Letter](#cover-letter) | One-page `BusinessTheme.modern()` cover letter with section presets | [PDF](../assets/readme/examples/cover-letter.pdf) · [Source](src/main/java/com/demcha/examples/templates/coverletter/CoverLetterFileExample.java) |
| [Cover Letter](#cover-letter) | One-page cover letter composed in the canonical DSL, section presets carrying the hierarchy | [PDF](../assets/readme/examples/cover-letter.pdf) · [Source](src/main/java/com/demcha/examples/templates/coverletter/CoverLetterFileExample.java) |
| [Module-first Profile](#module-first-profile) | Authoring directly against `DocumentSession.module(...).paragraph(...)` — DSL-direct, no template | [PDF](../assets/readme/examples/module-first-profile.pdf) · [Source](src/main/java/com/demcha/examples/flagships/ModuleFirstFileExample.java) |
| **Engine Showcase** | Single-page cinematic brand promo — semantic-graph → polished-PDFs visual metaphor with rounded clip frame, magazine headline lockup, KPI cards, capability columns; source of the README hero image | [Source](src/main/java/com/demcha/examples/flagships/EngineShowcase.java) |
| **Engine Deck** | Multi-page **landscape** capability deck — page 1 is a banner infographic (DSL code → engine → backends → **real rendered-document thumbnails**), then an authoring-pipeline walkthrough, and two pages of **real benchmark data** (GraphCompose vs iText 9 vs JasperReports) loaded from a bundled result file and drawn as tables + native charts; the landscape companion to Engine Showcase. The same composition also renders as a **geometry-identical PowerPoint deck** (one page = one editable slide) through `buildPptx(Path)` | [PDF](../assets/readme/examples/engine-deck.pdf) · [Source](src/main/java/com/demcha/examples/flagships/EngineDeckExample.java) · [PPTX source](src/main/java/com/demcha/examples/flagships/EngineDeckPptxExample.java) |
Expand Down Expand Up @@ -138,10 +138,11 @@ are with the canonical DSL, then jump to its detailed section below.

### Cover letter

A one-page modern cover letter — `BusinessTheme.modern()` drives every
colour and font choice; section presets (`softPanel`, `accentLeft`,
`accentTop`) carry the visual hierarchy; opening rich-text strip
highlights the candidate's headline.
A one-page modern cover letter composed straight in the canonical DSL.
Section presets (`softPanel`, `accentLeft`, `accentTop`) carry the visual
hierarchy and an opening rich-text strip highlights the candidate's
headline. Its colours come from a theme helper local to this module, not
from library API — the shipping equivalent is `BrandTheme`.

<!-- doc-example-ignore: quotes a runnable example; the source it is taken from is compiled and executed by the examples module -->
```java
Expand Down Expand Up @@ -1130,11 +1131,15 @@ The same composition also emits an editable PowerPoint deck (`BusinessReportPptx
### Master showcase

Fictional "Q2 sample report" combining the canonical surface
end-to-end: `BusinessTheme` + page background + hero with rotated
end-to-end: a theme record + page background + hero with rotated
shape container + branded QR + executive summary + zebra-striped
totals table + accent-bordered highlight cards + Code 128 footer
barcode. Reference it when composing your own multi-page documents.

The `BusinessTheme` record it uses is a helper local to this module, not
library API — the shipping equivalent is `BrandTheme` and the layered
presets. Declare your own record the same way, or start from `BrandTheme`.

The same composition also emits an editable PowerPoint deck (`MasterShowcasePptxExample` — each page becomes one slide; rich text, the advanced table, and chrome stay native shapes, and only the rotated clip-masked seal and the barcodes rasterise).

[📄 View PDF](../assets/readme/examples/master-showcase.pdf) ·
Expand Down
Loading
Loading