docs: make the published snippets run (#475)

* docs: make the published snippets run

Six documented text styles set fontName(FontName.HELVETICA_BOLD) with no
decoration. The font name selects the family and the decoration selects the
face within it, so every one of those headings rendered regular. The timeline
recipe was the sharpest case: it presents itself as the default title style
while TimelineBuilder.defaultTitleStyle() does set BOLD, so a reader copying it
to change only the size silently lost a working default.

Five module READMEs opened a session, built a document graph and closed it
without rendering anything, so the "usage" each one advertised produced no
artifact. Each now shows the smallest complete path and is titled accordingly.
templates/ and testing/ additionally state that neither artifact can open a
session on its own — testing/ is the trap, since it carries PDFBox at compile
scope while graph-compose-render-pdf, the only artifact registering a
FontMetricsProvider, is absent.

core/README.md contradicted itself eight lines apart: the backend is discovered
"at render time" above, "at create()" below. Verified against a bare
graph-compose-core classpath — create() throws MissingBackendException before
any render call. render-pdf/README.md and the root README carried the same
misplacement.

toImages() with no arguments does not exist; three places advertised it. The
signature is toImages(int dpi).

The first code block in the root README calls buildPptx on exactly the
classpath its own install snippet produces, where it fails; it now names
graph-compose-render-pptx, and the elided body no longer looks like a method
the reader should have. The module list links each published README — eight of
the ten had no inbound link from anywhere — and a Next steps block points at
the five-minute first-document path, which the landing page never mentioned.

examples/README.md documented rethemeing through InvoiceTemplateV2, removed in
2.0, linked a source file that does not exist, and carried a committed preview
for it; the single-example run command named the wrong class and could not be
copy-pasted.

Each corrected module snippet compiles against the published 2.1.0 artifacts;
the core and emoji ones were executed and write their PDF.

* docs: name the family, and split the two backend lookups

The corrected snippets paired FontName.HELVETICA_BOLD with
DocumentTextDecoration.BOLD while the surrounding prose explained that the name
selects the family and the decoration selects the face. Both halves then read
as "bold", which invites the conclusion that both are required. FontLibrary
resolves HELVETICA_BOLD, COURIER_BOLD and the other face constants back to
their base family (FontLibrary.java:25-34), so the suffix contributes nothing
to the result. Rendering both forms and reading the font resource out of the
PDF confirms it: HELVETICA_BOLD + BOLD and HELVETICA + BOLD both resolve to
Helvetica-Bold, HELVETICA_BOLD + DEFAULT resolves to Helvetica, and the same
holds for Courier. The six snippets and the README hello-world now name the
family they mean.

MissingBackendException's own Javadoc still described one lookup at the output
call, and claimed the explicit render/export paths never throw. There are two
lookups. The DocumentSession constructor calls refreshMeasurementServices()
(DocumentSession.java:114), which resolves a FontMetricsProvider through
BackendProviders.fontMetrics() — so a classpath without one fails while the
session is being constructed, before any content is added. The format backend
is resolved separately, at the output call. The explicit paths skip the second
lookup, not the first: the session they render from still had to open.

Author: DemchaAV

CHANGELOG.md

@@ -36,6 +36,45 @@ follow semantic versioning; release dates are ISO 8601.
   taller than a page still anchors by its first line, because its keep-together
   request is ignored anyway.
 
+### Documentation
+
+- **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
+  decoration. The name selects the family and the decoration selects the face
+  within it, so each of those headings rendered regular. The timeline snippet was
+  the sharpest: it presents itself as the default title style, while
+  `TimelineBuilder` does set `BOLD` — a reader copying it to change only the size
+  lost a working default. The snippets now name the family they mean
+  (`FontName.HELVETICA`, `FontName.COURIER`) rather than a `*_BOLD` constant that
+  `FontLibrary` resolves to that same family, so the pair reads as one choice
+  each instead of `BOLD` twice.
+- **Module usage examples reach an artifact.** The `core`, `render-pdf`,
+  `templates`, `testing` and `emoji` READMEs opened a session, built a document
+  graph and closed it without rendering anything. Each now shows the smallest
+  complete path, and the `templates` and `testing` READMEs state that neither
+  artifact can open a session without `graph-compose-render-pdf`.
+- **`MissingBackendException` is located where it fires.** `core/README.md`,
+  `render-pdf/README.md` and the root README said a missing backend surfaces when
+  you ask for a PDF; it surfaces at `create()`, because opening a session resolves
+  the font metrics. `core/README.md` said both things eight lines apart. The
+  exception's own Javadoc described a single lookup at the output call; it now
+  separates the two that exist — the measurement provider resolved when the
+  session opens, and the format backend resolved at the output call — and records
+  that the explicit `render` / `export` paths skip only the second.
+- **`toImages()` takes a dpi.** Three places advertised a no-argument overload
+  that does not exist; the signature is `toImages(int dpi)`.
+- **The PowerPoint snippet names the artifact it needs.** The first code block in
+  the root README calls `buildPptx` on the classpath the README's own install
+  snippet produces, where it fails.
+- **Every published module README is reachable** from the module list in the root
+  README; eight of the ten had no inbound link from anywhere.
+- **A gallery entry for a deleted example is gone.** `examples/README.md`
+  documented rethemeing through `InvoiceTemplateV2`, a type removed in 2.0, linked
+  a source file that no longer exists, and carried a committed preview for it. The
+  single-example run command also named the wrong class, so it could not be
+  copy-pasted.
+
 ## v2.1.0 — 2026-07-26
 
 ### Highlights

README.md

@@ -47,12 +47,14 @@
 
 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()) {
-    compose(doc);        // one description
+    // … describe the page (see Hello world below)
     doc.buildPdf();      // print-ready PDF
     doc.buildPptx(deck); // editable PowerPoint
 }
@@ -119,8 +121,9 @@ engine plus the `graph-compose-render-pdf` backend, so existing 1.x callers upgr
 
 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`).
+the classpath — opening a session (`create()`) throws `MissingBackendException`, which
+names the artifact to add (`graph-compose-render-pdf`, already included in
+`graph-compose`).
 
 </details>
 
@@ -172,7 +175,7 @@ class Hello {
         DocumentColor panel = DocumentColor.rgb(244, 238, 228);
         DocumentColor accent = DocumentColor.rgb(196, 153, 76);
         DocumentTextStyle h1 = DocumentTextStyle.builder()
-                .fontName(FontName.HELVETICA_BOLD).size(28)
+                .fontName(FontName.HELVETICA).size(28)
                 .decoration(DocumentTextDecoration.BOLD)
                 .color(DocumentColor.rgb(20, 60, 75)).build();
         DocumentTextStyle body = DocumentTextStyle.builder()
@@ -201,6 +204,12 @@ class Hello {
 
 For a Spring Boot `@RestController` streaming the PDF straight to the response, see [`HttpStreamingExample`](./examples/src/main/java/com/demcha/examples/features/streaming/HttpStreamingExample.java).
 
+### Next steps
+
+- [**Your first document**](./docs/first-document.md) &mdash; the five-minute path from an empty project to a rendered PDF.
+- [**Getting started**](./docs/getting-started.md) &mdash; DSL or templates, and how to choose; the first-render walk-through.
+- [**Examples gallery**](./examples/README.md) &mdash; every runnable example, with a PDF you can preview without building anything.
+
 ## What's new in 2.0
 
 The **module-first** release &mdash; the single jar becomes a family of per-concern artifacts, so you install exactly what you render.
@@ -325,13 +334,13 @@ Full detail: [architecture overview](./docs/architecture/overview.md) &middot; [
 
 The repository is a Maven multi-module reactor: the root `pom.xml` is the build aggregator, so `./mvnw clean verify` at the root builds and tests **every** module (scope to one with `-pl :<artifactId>`; the lean engine lives in `core/`).
 
-- **Published to Maven Central**
-  - `graph-compose-core` (`core/`) &mdash; the lean document engine
-  - `graph-compose-render-pdf` · `-render-docx` · `-render-pptx` &mdash; render backends
-  - `graph-compose-templates` &mdash; built-in CV / cover-letter / invoice / proposal presets
-  - `graph-compose-testing` &mdash; snapshot &amp; visual-regression test helpers
-  - `graph-compose` &mdash; the drop-in wrapper (core + PDF); `graph-compose-bundle` &mdash; batteries-included (adds templates + fonts + emoji)
-- **Companion artifacts** (independent version lines) &mdash; `graph-compose-fonts`, `graph-compose-emoji`
+- **Published to Maven Central** &mdash; each links to its own README (what it is, when to depend on it, smallest complete example)
+  - [`graph-compose-core`](./core/README.md) (`core/`) &mdash; the lean document engine
+  - [`graph-compose-render-pdf`](./render-pdf/README.md) · [`-render-docx`](./render-docx/README.md) · [`-render-pptx`](./render-pptx/README.md) &mdash; render backends
+  - [`graph-compose-templates`](./templates/README.md) &mdash; built-in CV / cover-letter / invoice / proposal presets
+  - [`graph-compose-testing`](./testing/README.md) &mdash; snapshot &amp; visual-regression test helpers
+  - [`graph-compose`](./wrapper/README.md) (`wrapper/`) &mdash; the drop-in wrapper (core + PDF); [`graph-compose-bundle`](./bundle/README.md) &mdash; batteries-included (adds templates + fonts + emoji)
+- **Companion artifacts** (independent version lines) &mdash; [`graph-compose-fonts`](./fonts/README.md), [`graph-compose-emoji`](./emoji/README.md)
 - **Development only** (never published) &mdash; `qa` (architecture guards + visual regression), `coverage` (aggregate JaCoCo), `examples`, `benchmarks`
 
 See [CONTRIBUTING](./CONTRIBUTING.md) for the branch-routing table and the full build / verify flow.

assets/readme/examples/invoice-custom-theme.pdf

@@ -19,20 +19,22 @@ it, with **no PDFBox, POI, or template code** on its dependency tree.
 Most applications should depend on `graph-compose` (core + the PDF backend, the 1.x
 drop-in) or `graph-compose-bundle` (batteries included) instead.
 
-## Usage
+## Smallest complete example
 
-Author against the canonical surface; a render backend on the classpath is discovered
-through `ServiceLoader` at render time:
+Author against the canonical surface. Core cannot open a session on its own: `create()`
+resolves a `FontMetricsProvider` through `ServiceLoader`, so a core-only classpath throws
+`MissingBackendException` there — before any render call — and the message names the
+artifact to add. With `graph-compose-render-pdf` present the whole path works:
 
 ```java
-try (var doc = GraphCompose.document(out).create()) {
+Path out = Path.of("hello.pdf");
+try (DocumentSession doc = GraphCompose.document(out).create()) {
     doc.pageFlow().addParagraph("Hello").build();
-} // with graph-compose-render-pdf present, buildPdf() / toPdfBytes() / toImages() work
+    doc.buildPdf();                 // writes hello.pdf
+}
 ```
 
-A core-only classpath throws `MissingBackendException` at `create()` — before any render
-call, since the session resolves its font metrics as it opens — and the message names the
-artifact to add.
+`toPdfBytes()` and `toImages(int dpi)` are the in-memory counterparts.
 
 ## Install
 

core/README.md

@@ -1,24 +1,39 @@
 package com.demcha.compose.document.exceptions;
 
 /**
- * Raised when a document operation needs a fixed-layout render/measurement
- * backend but none is registered on the classpath.
+ * Raised when a document operation needs a backend that is not registered on
+ * the classpath.
  *
  * <p>Since GraphCompose 2.0 the engine and document model ship without a bundled
- * backend: rendering and text measurement are provided by a separate artifact
+ * backend: text measurement and rendering are provided by separate artifacts
  * (for example {@code io.github.demchaav:graph-compose-render-pdf} or
- * {@code io.github.demchaav:graph-compose-render-pptx}) discovered at
- * runtime through {@link java.util.ServiceLoader}. Calling a convenience output
- * method — {@code toPdfBytes()}, {@code buildPdf()}, {@code toImages()},
- * {@code toPptxBytes()}, {@code buildPptx(Path)} — or requesting
- * {@code layoutSnapshot()} without the matching artifact on the classpath
- * fails with this exception. The message names the artifact to add.</p>
+ * {@code io.github.demchaav:graph-compose-render-pptx}) discovered at runtime
+ * through {@link java.util.ServiceLoader}. Two distinct lookups can fail, at
+ * two different moments.</p>
+ *
+ * <p><strong>Measurement, at {@code create()}.</strong> Opening a
+ * {@code DocumentSession} resolves a {@code FontMetricsProvider}, because the
+ * session measures text as it builds. A classpath carrying no provider therefore
+ * fails while the session is being constructed — before any content is added and
+ * before any output method is reached. {@code graph-compose-render-pdf} is the
+ * only shipped artifact that registers one, so a bare {@code graph-compose-core}
+ * classpath cannot open a session at all.</p>
+ *
+ * <p><strong>Format backend, at the output call.</strong> Once the session is
+ * open, a convenience output method — {@code toPdfBytes()}, {@code buildPdf()},
+ * {@code toImages(int)}, {@code toPptxBytes()}, {@code buildPptx(Path)} —
+ * additionally resolves a fixed-layout backend for that format. Asking for PPTX
+ * output with only the PDF backend present fails here, at the call.</p>
+ *
+ * <p>The explicit {@code render(FixedLayoutBackend)} /
+ * {@code export(SemanticBackend)} paths skip the second lookup — they use the
+ * caller-supplied backend instead of the ServiceLoader — but not the first: the
+ * session they render from still had to open, and opening it needed a
+ * measurement provider.</p>
  *
  * <p>This is an unchecked exception: a missing backend is a build/classpath
  * configuration problem, not a per-call argument error, so user code is not
- * forced to catch it. The explicit {@code render(FixedLayoutBackend)} /
- * {@code export(SemanticBackend)} paths never throw it — they use a
- * caller-supplied backend instead of the ServiceLoader lookup.</p>
+ * forced to catch it. The message names the artifact to add.</p>
  *
  * @since 2.0.0
  */

core/src/main/java/com/demcha/compose/document/exceptions/MissingBackendException.java

@@ -40,6 +40,7 @@ values.
 import com.demcha.compose.GraphCompose;
 import com.demcha.compose.document.api.DocumentSession;
 import com.demcha.compose.document.style.DocumentColor;
+import com.demcha.compose.document.style.DocumentTextDecoration;
 import com.demcha.compose.document.style.DocumentTextStyle;
 import com.demcha.compose.font.FontName;
 
@@ -49,7 +50,10 @@ DocumentColor cream = DocumentColor.rgb(252, 248, 240);   // paper
 DocumentColor panel = DocumentColor.rgb(244, 238, 228);   // soft panel
 DocumentColor accent = DocumentColor.rgb(196, 153, 76);   // gold accent
 DocumentTextStyle h1 = DocumentTextStyle.builder()
-        .fontName(FontName.HELVETICA_BOLD).size(28)
+        // The name picks the family, the decoration picks the face within
+        // it. Without the decoration this heading renders regular Helvetica.
+        .fontName(FontName.HELVETICA).size(28)
+        .decoration(DocumentTextDecoration.BOLD)
         .color(DocumentColor.rgb(20, 60, 75)).build();
 
 try (DocumentSession document = GraphCompose.document(Path.of("output.pdf"))

docs/getting-started.md

@@ -28,13 +28,17 @@ pattern for status keywords ("Paid", "Overdue"). For anything beyond
 those, `style(text, DocumentTextStyle)` takes a fully explicit style:
 
 ```java
+import com.demcha.compose.document.style.DocumentTextDecoration;
 import com.demcha.compose.document.style.DocumentTextStyle;
 import com.demcha.compose.font.FontName;
 
 section.addRich(rich -> rich
         .plain("Code: ")
         .style("RT-2026-04", DocumentTextStyle.builder()
-                .fontName(FontName.COURIER_BOLD)
+                // Fully explicit means both halves: the name selects the
+                // family, the decoration selects the face within it.
+                .fontName(FontName.COURIER)
+                .decoration(DocumentTextDecoration.BOLD)
                 .size(10)
                 .build()));
 ```

docs/recipes/rich-text.md

@@ -99,13 +99,16 @@ paper colour rather than pure white:
 
 ```java
 import com.demcha.compose.document.style.DocumentColor;
+import com.demcha.compose.document.style.DocumentTextDecoration;
 import com.demcha.compose.document.style.DocumentTextStyle;
 import com.demcha.compose.font.FontName;
 
 DocumentColor cream = DocumentColor.rgb(252, 248, 240);
 DocumentColor panel = DocumentColor.rgb(244, 238, 228);
 DocumentTextStyle h1 = DocumentTextStyle.builder()
-        .fontName(FontName.HELVETICA_BOLD).size(28)
+        // The name picks the family, the decoration picks the face within it.
+        .fontName(FontName.HELVETICA).size(28)
+        .decoration(DocumentTextDecoration.BOLD)
         .color(DocumentColor.rgb(20, 60, 75)).build();
 
 try (DocumentSession document = GraphCompose.document(Path.of("output.pdf"))

docs/recipes/themes.md

@@ -73,12 +73,18 @@ numbered discs crowd a narrow timeline.
 Timeline-wide defaults and per-entry overrides:
 
 ```java
+import com.demcha.compose.document.style.DocumentTextDecoration;
 import com.demcha.compose.document.style.DocumentTextStyle;
 import com.demcha.compose.font.FontName;
 
 section.addTimeline(timeline -> timeline
         .titleStyle(DocumentTextStyle.builder()
-                .fontName(FontName.HELVETICA_BOLD)
+                // The name picks the family, the decoration picks the face
+                // within it — the built-in title default sets BOLD, so a style
+                // that overrides it must set it too or the title turns regular
+                // while only the size was meant to change.
+                .fontName(FontName.HELVETICA)
+                .decoration(DocumentTextDecoration.BOLD)
                 .size(11)
                 .build())
         .metaStyle(DocumentTextStyle.builder()
@@ -87,7 +93,8 @@ section.addTimeline(timeline -> timeline
                 .build())
         .entry(TimelineMarker.dot(8, accent), e -> e
                 .title("Launch", DocumentTextStyle.builder()  // per-entry override
-                        .fontName(FontName.HELVETICA_BOLD)
+                        .fontName(FontName.HELVETICA)
+                        .decoration(DocumentTextDecoration.BOLD)
                         .size(13)
                         .build())
                 .meta("June 2026")

docs/recipes/timelines.md

@@ -293,7 +293,8 @@ widget takes a colour parameter).
 ```java
 private void renderHeader(SectionBuilder section, CvIdentity identity) {
     DocumentTextStyle nameStyle = DocumentTextStyle.builder()
-        .fontName(FontName.HELVETICA_BOLD)
+        .fontName(FontName.HELVETICA)
+        .decoration(DocumentTextDecoration.BOLD)   // the name picks the family, this picks the face
         .size(theme.typography().sizeHeadline())
         .color(NAME_COLOR)
         .build();