From 2d215efbdecb0524c39b1ae4150cdf3d8e916fb2 Mon Sep 17 00:00:00 2001 From: DemchaAV Date: Mon, 3 Aug 2026 15:12:14 +0100 Subject: [PATCH] docs(readme): install and a runnable example come before the second showcase MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ninety-one lines and twelve images stood between the title and ## Installation. Most of that was a second showcase: thirty-five lines demonstrating the PowerPoint backend, with two renders and a screenshot, before the reader had seen one line of the authoring API. A reader who came for a PDF met a beta deck exporter first. That section moves below "Next steps" — after a reader has written a document, "the same session also emits a deck" is a payoff rather than a detour. Install now sits fifty-two lines in, behind nine images, seven of which are badges. The "Upgrading from 1.x" note moves into Installation, where an upgrader is already headed. Two directional words invert with the move and are fixed. Hello world opened with eight imports and eight public types while the tutorial it links to two lines below opened with four. The minimal version leads now, copied from that tutorial so it is the same first program; the styled one keeps its place directly beneath under the heading it was always earning, "Make it cinematic", and points at the committed preview of the example that renders the whole family. The ## Hello world heading itself is unchanged: an in-page link depends on it and no test validates anchors. Also links docs/capabilities.md from the landing page — until now it was reachable only through the documentation index. ./mvnw -B -ntp clean verify — BUILD SUCCESS, 692 tests in the closing module. DocumentationCoverageTest still finds all four canonical tokens; the styled block remains their only source. DocumentationSnippetCompileTest compiles the new fence under a fresh id. --- CHANGELOG.md | 19 +++ README.md | 115 ++++++++++++------ docs/first-document.md | 5 + .../features/text/SectionPresetsExample.java | 2 +- 4 files changed, 101 insertions(+), 40 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0d7ccc52..5c3992ac 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -201,6 +201,25 @@ follow semantic versioning; release dates are ISO 8601. ### Documentation +- **The landing page lets you run it before it finishes selling it.** Ninety-one lines + and twelve images stood between the title and `## Installation`, most of them a second + showcase: thirty-five lines demonstrating the PowerPoint backend, with two renders and + a screenshot, before the reader had seen one line of the authoring API. That section + now sits after "Next steps", where a reader who has already written a document can + appreciate that the same session emits a deck; install is reached in fifty-two lines + and nine images, seven of which are badges. The "Upgrading from 1.x" note moves into + Installation, where an upgrader is already headed. +- **The first snippet a reader copies is a file they can run.** "Hello world" opened + with eight imports and eight public types — colours, text styles, a font, a page + background, a soft panel, an accent strip — before the reader had rendered anything. + It now opens with four types and a complete `Hello.java`: paste, run, get a PDF. The + styled version keeps its place directly beneath as "Make it cinematic", which is what + it was always demonstrating, and points at the committed preview of the example that + renders the whole family. The first-document guide keeps its snippets as statements — + three `main` wrappers would bury what it is teaching — and now says so, pointing at + the README for the complete file rather than leaving the reader to discover that its + code does not compile on its own. Also: the feature map, `docs/capabilities.md`, is + now reachable from the landing page rather than only through the documentation index. - **The last three documents that put `MissingBackendException` at the render call.** An earlier pass moved the module READMEs and the exception's own Javadoc onto `create()` and stopped at the repository root, so the troubleshooting entry, the 2.0 diff --git a/README.md b/README.md index d6d38b46..3f3fb99d 100644 --- a/README.md +++ b/README.md @@ -23,9 +23,6 @@ > 🟢 **Latest stable**: [v2.1.0](https://github.com/DemchaAV/GraphCompose/releases/tag/v2.1.0) — the **PowerPoint** release: `graph-compose-render-pptx` turns the same resolved layout into an editable deck — one page per slide, geometry-identical to the PDF, text and panels as native shapes. Ships as `@Beta`. **[What each backend supports ↓](docs/architecture/backend-capability-matrix.md)** >  ·  🟡 **In development**: v2.1.1 on `develop` — see [CHANGELOG.md](./CHANGELOG.md). ->  ·  ⬆️ **Upgrading from 1.x?** `graph-compose` stays a drop-in for PDF with no code change; see the [2.0 modules migration guide](./docs/migration/v2.0.0-modules.md) ->  ·  See [API stability policy](./docs/api-stability.md) for tier definitions. -

Live Showcase  ·  @@ -44,42 +41,6 @@ ☝ This banner is itself a GraphCompose document — view the full module-first deck (PDF), rendered by EngineDeckV2Example: the module graph, native vector charts, and real comparative benchmarks, all drawn by the engine. It renders its own marketing.

-## One source → a PDF and an editable PowerPoint deck - -The same `DocumentSession` emits both. The PDF backend prints the resolved layout; the PPTX backend (**beta**) rebuilds it as slides. Both consume the same resolved layout graph, so page and slide frames and every positioned element share the same geometry — text, panels, tables, and vectors arrive in PowerPoint as **native, editable shapes**, not screenshots (the page below lands as 69 native shapes; only its clip-masked logo art is a picture). Glyphs are rasterised by the viewer, so the exact text rendering depends on the fonts installed on the viewing machine; see the [backend capability matrix](docs/architecture/backend-capability-matrix.md) for per-feature fidelity. - -PowerPoint output needs `graph-compose-render-pptx` on the classpath in addition to `graph-compose`; without it `buildPptx` fails with a `MissingBackendException` naming the artifact. See [Which artifact?](#installation) below. - - -```java -Path deck = Path.of("twin-output.pptx"); -try (DocumentSession doc = GraphCompose.document(Path.of("twin-output.pdf")) - .pageSize(DocumentPageSize.SLIDE_16_9) - .create()) { - // … describe the page (see Hello world below) - doc.buildPdf(); // print-ready PDF - doc.buildPptx(deck); // editable PowerPoint -} -``` - - - - - - - - - - -
twin-output.pdf — rendered by the PDF backendtwin-output.pptx — the same page, as PowerPoint itself renders it
The twin-output page rendered from the PDFThe same page exported as a PNG by PowerPoint from the generated .pptx
- -

- The generated deck open in PowerPoint with the headline text frame selected for editing -

-

- ☝ 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: PDF · PPTX · source (TwinOutputExample, one page, source included). -

- ## Why GraphCompose - **Author intent, not coordinates.** Fluent DSL for sections, paragraphs, tables, lists, layer stacks, themes — the engine handles measurement, pagination, and rendering. @@ -109,6 +70,9 @@ That coordinate renders PDF out of the box: it aggregates the lean `graph-compos engine plus the `graph-compose-render-pdf` backend, so existing 1.x callers upgrade with **no code change**. +> ⬆️ **Upgrading from 1.x?** `graph-compose` stays a drop-in for PDF with no code change; see the [2.0 modules migration guide](./docs/migration/v2.0.0-modules.md). +>  ·  See [API stability policy](./docs/api-stability.md) for tier definitions. +
Which artifact? — the 2.0 module split, when you want to take less or more @@ -162,6 +126,42 @@ pinned to v1.6.5 and earlier but is no longer the documented install option. ## Hello world + +```java +import com.demcha.compose.GraphCompose; +import com.demcha.compose.document.api.DocumentPageSize; +import com.demcha.compose.document.api.DocumentSession; + +import java.nio.file.Path; + +class Hello { + public static void main(String[] args) throws Exception { + try (DocumentSession document = GraphCompose.document(Path.of("hello.pdf")) + .pageSize(DocumentPageSize.A4) + .margin(24, 24, 24, 24) + .create()) { + + document.pageFlow(page -> page + .module("Summary", module -> module.paragraph("Hello GraphCompose"))); + + document.buildPdf(); + } + } +} +``` + +Save it as `Hello.java` and run it — that is the whole file. `create()` opens the session, +`pageFlow` describes the page, `buildPdf()` writes it: no coordinates, no page-break +arithmetic. + +### Make it cinematic + +The same page with the engine's visual primitives: a page background, a soft panel, an +accent strip and two text styles. Nothing here is a workaround — panels and accents are +nodes, and the engine places them. [`SectionPresetsExample`](./examples/src/main/java/com/demcha/examples/features/text/SectionPresetsExample.java) +renders the whole family; its output is committed as +[section-presets.pdf](./assets/readme/examples/section-presets.pdf). + ```java import com.demcha.compose.GraphCompose; @@ -216,6 +216,42 @@ For a Spring Boot `@RestController` streaming the PDF straight to the response, - [**Getting started**](./docs/getting-started.md) — DSL or templates, and how to choose; the first-render walk-through. - [**Examples gallery**](./examples/README.md) — every runnable example, with a PDF you can preview without building anything. +## One source → a PDF and an editable PowerPoint deck + +The same `DocumentSession` emits both. The PDF backend prints the resolved layout; the PPTX backend (**beta**) rebuilds it as slides. Both consume the same resolved layout graph, so page and slide frames and every positioned element share the same geometry — text, panels, tables, and vectors arrive in PowerPoint as **native, editable shapes**, not screenshots (the page below lands as 69 native shapes; only its clip-masked logo art is a picture). Glyphs are rasterised by the viewer, so the exact text rendering depends on the fonts installed on the viewing machine; see the [backend capability matrix](docs/architecture/backend-capability-matrix.md) for per-feature fidelity. + +PowerPoint output needs `graph-compose-render-pptx` on the classpath in addition to `graph-compose`; without it `buildPptx` fails with a `MissingBackendException` naming the artifact. See [Which artifact?](#installation) above. + + +```java +Path deck = Path.of("twin-output.pptx"); +try (DocumentSession doc = GraphCompose.document(Path.of("twin-output.pdf")) + .pageSize(DocumentPageSize.SLIDE_16_9) + .create()) { + // … describe the page (see Hello world above) + doc.buildPdf(); // print-ready PDF + doc.buildPptx(deck); // editable PowerPoint +} +``` + + + + + + + + + + +
twin-output.pdf — rendered by the PDF backendtwin-output.pptx — the same page, as PowerPoint itself renders it
The twin-output page rendered from the PDFThe same page exported as a PNG by PowerPoint from the generated .pptx
+ +

+ The generated deck open in PowerPoint with the headline text frame selected for editing +

+

+ ☝ 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: PDF · PPTX · source (TwinOutputExample, one page, source included). +

+ ## What's new in 2.0 The **module-first** release: the single jar became a family of per-concern artifacts, so you install exactly what you render, and `graph-compose` stayed a drop-in for PDF callers. Everything the 1.9 line added ships unchanged. @@ -355,6 +391,7 @@ The index routes by what you are doing — first document, using or authoring a template, extending the engine, running in production. The entry points most people want directly: +- **Capabilities** — [the feature map](./docs/capabilities.md): every capability with its stability tier and the guide that covers it - **Templates** — [layered architecture](./docs/templates/v2-layered/README.md) (CV, cover letter, invoice, proposal on `BrandTheme`) · [which template system?](./docs/templates/which-template-system.md) for callers arriving from a pre-2.0 surface - **Recipes** — [the cookbook](./docs/recipes.md): tables, themes, shapes, transforms, page backgrounds, streaming, extending - **Operations** — [production rendering](./docs/operations/production-rendering.md) · [layout snapshot testing](./docs/operations/layout-snapshot-testing.md) · [troubleshooting](./docs/troubleshooting.md) diff --git a/docs/first-document.md b/docs/first-document.md index cf94f03c..5c6463c0 100644 --- a/docs/first-document.md +++ b/docs/first-document.md @@ -32,6 +32,11 @@ try (DocumentSession document = GraphCompose.document(Path.of("hello.pdf")) } ``` +Those are statements, not a file: they go inside a method — the +[README's Hello world](../README.md#hello-world) shows the same program as a complete +`Hello.java`. Every snippet on this page is written the same way, so the shape you are +reading is the GraphCompose part and nothing else. + `GraphCompose.document(path)` configures the output; `create()` returns the `DocumentSession`. Use try-with-resources so the session is always released, even if rendering fails. Inside the session, `pageFlow(...)` is the document body: diff --git a/examples/src/main/java/com/demcha/examples/features/text/SectionPresetsExample.java b/examples/src/main/java/com/demcha/examples/features/text/SectionPresetsExample.java index c78c74b5..dbcf7c17 100644 --- a/examples/src/main/java/com/demcha/examples/features/text/SectionPresetsExample.java +++ b/examples/src/main/java/com/demcha/examples/features/text/SectionPresetsExample.java @@ -16,7 +16,7 @@ import java.nio.file.Path; /** - * Runnable showcase for the v1.4 / v1.5 section preset shortcuts. + * Runnable showcase for the section preset shortcuts. * *

Demonstrates {@code pageBackground}, {@code band(color)}, * {@code softPanel(...)}, {@code headingBar(...)}, {@code accentLeft /