diff --git a/README.md b/README.md index 91ebc7c3..224057e9 100644 --- a/README.md +++ b/README.md @@ -81,6 +81,24 @@ Core document APIs stay source- and binary-compatible with v1.8 — v1.9 is dependencies { implementation("io.github.demchaav:graph-compose:2.0.0") } ``` +> **Which artifact? (2.0 module split).** `graph-compose` above is the drop-in default — +> it renders PDF out of the box because it aggregates the lean `graph-compose-core` engine +> plus the `graph-compose-render-pdf` backend, so existing 1.x callers upgrade with **no +> code change**. Reach for a different coordinate only to take less or more: +> +> | Goal | Depend on | +> |---|---| +> | **PDF — the 1.x default** | `graph-compose` | +> | **Batteries-included** (PDF + templates + fonts + emoji) | `graph-compose-bundle` | +> | **Lean core, bring your own backend** | `graph-compose-core` | +> | **Built-in CV / cover-letter / invoice / proposal templates** | add `graph-compose-templates` | +> | **DOCX / PPTX export** | add `graph-compose-render-docx` / `graph-compose-render-pptx` | +> +> Every 2.0 coordinate shares the `graph-compose` version (the fonts and emoji companions +> keep their own lines). A bare `graph-compose-core` renders nothing until a backend is on +> the classpath — asking it to build a PDF throws `MissingBackendException`, which names the +> artifact to add (`graph-compose-render-pdf`, already included in `graph-compose`). + > **Bundled fonts (from v1.8.0).** The curated Google fonts no longer ship > inside the engine jar — they live in an independently-versioned > companion artifact so an engine upgrade never re-downloads ~18 MB of diff --git a/docs/templates/v2-layered/quickstart.md b/docs/templates/v2-layered/quickstart.md index 865f1fb0..f535564d 100644 --- a/docs/templates/v2-layered/quickstart.md +++ b/docs/templates/v2-layered/quickstart.md @@ -3,6 +3,11 @@ **5 minutes.** What it is, why it's structured this way, and a working example that renders a CV PDF. +> **Dependency.** The ready-made presets ship in the opt-in +> `graph-compose-templates` artifact — they are **not** bundled in `graph-compose`. Add it +> next to `graph-compose` (or depend on `graph-compose-bundle`, which includes both). See +> the [README install matrix](../../../README.md#installation). + --- ## What you get diff --git a/docs/templates/v2-layered/using-templates.md b/docs/templates/v2-layered/using-templates.md index d572068a..0f24d3d0 100644 --- a/docs/templates/v2-layered/using-templates.md +++ b/docs/templates/v2-layered/using-templates.md @@ -8,6 +8,10 @@ theme variants. If you haven't read [quickstart.md](quickstart.md), do that first — it sets up the conceptual model in 5 minutes. +> **Dependency.** These presets ship in the opt-in `graph-compose-templates` artifact (not +> bundled in `graph-compose`); add it, or use `graph-compose-bundle`. See the +> [README install matrix](../../../README.md#installation). + --- ## Table of contents diff --git a/docs/templates/which-template-system.md b/docs/templates/which-template-system.md index 2cb37e12..327b6098 100644 --- a/docs/templates/which-template-system.md +++ b/docs/templates/which-template-system.md @@ -6,6 +6,10 @@ invoice, proposal}`, every preset a final class with a `create(BrandTheme)` factory returning a `DocumentTemplate<…>`. GraphCompose 2.0 ships no other template system. +> **Dependency.** These presets ship in the opt-in `graph-compose-templates` artifact — not +> bundled in `graph-compose`. Add it, or depend on `graph-compose-bundle`. See the +> [README install matrix](../../README.md#installation). + Through the 1.x line this page was a decision guide between two parallel surfaces. On the 2.0 line the decision is gone; what remains here is the naming history (so old commit messages and ADRs still make sense) and the diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 3537240b..6382f1c2 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -37,10 +37,32 @@ fall back to inline content with a one-time capability warning. Use DOCX only for paragraph / list / table / image / section content. Per-feature mapping: [canonical ↔ legacy parity matrix](architecture/canonical-legacy-parity.md). +## `MissingBackendException` when rendering + +**Cause.** You depend on `graph-compose-core` (the lean 2.0 engine) but no render +backend is on the classpath. The core carries the `DocumentSession` authoring API and a +`ServiceLoader` seam, but the actual renderer ships separately — so `document.buildPdf()` +/ `toPdfBytes()` / `toImages()` throws `MissingBackendException` until a backend is +discoverable. + +**Fix.** Add the PDF backend, or depend on `graph-compose` (which already bundles it): + +```xml + + io.github.demchaav + graph-compose-render-pdf + 2.0.0 + +``` + +The exception message names the exact artifact to add. Plain `graph-compose` and +`graph-compose-bundle` both include the PDF backend out of the box — only a deliberately +lean `graph-compose-core` needs this. + ## `NoClassDefFoundError` at runtime -GraphCompose marks one heavy, rarely-needed dependency **optional** so -PDF-only consumers don't pay for it. If you use DOCX export, add the +GraphCompose keeps the heavier office backends in **separate** artifacts so +PDF-only consumers don't pay for them. If you use DOCX export, add the dependency to **your** project. **DOCX export** — `document.export(new DocxSemanticBackend())` ships in the