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 /