docs(pptx): surface font substitution and say how to avoid it (#452)

* docs(pptx): surface font substitution and say how to avoid it

The backend already warns once per family whenever a deck will reference
a font instead of carrying it, and each message names what to do. The
examples silenced com.demcha.compose outright, so a reader running a deck
example saw none of it — the warnings fired into a muted logger. Raising
that logger to WARN costs 14 lines across all 87 generated documents,
because every warning is already deduplicated per family or per kind.

The module page said substitution was logged but not what it costs or how
to avoid it. It now states the three cases a font can land in — a
standard-14 name travelling as a metric-compatible viewer font with
identical widths and different letterforms, an embeddable binary family
travelling as itself, and a name-only family that depends on the viewer
having it installed — so a reader who needs glyph identity knows to use a
bundled family or register their own.

* docs(changelog): state the dedup rule instead of a line count

The entry pinned two numbers and both were wrong: the suite writes 93
documents, not 87, and emits 18 warning lines, not 14 — the earlier tally
matched on the render./docx. prefixes and missed the glyph.missing lines
and one node-drop warning.

Correcting them would only reset the clock, since adding one example
moves both. The entry now describes the property that keeps the output
short, and states the two dedup scopes accurately: a font substitution is
deduplicated per family per render, a capability note per kind for the
process.

Author: DemchaAV

CHANGELOG.md

@@ -182,6 +182,17 @@ shade), while others lose something the format cannot carry — see Known limita
 
 ### Documentation and examples
 
+- **The examples now show the engine's warnings.** Their logging config silenced
+  `com.demcha.compose` entirely, so a reader running a deck example never saw which
+  fonts the viewer would substitute or which capability had degraded — the warnings
+  fired into a muted logger. The output stays short because every warning is
+  deduplicated before it is logged: a font substitution once per family per render, a
+  capability note once per kind for the process.
+- **`render-pptx` documents how to get a glyph-identical deck.** Geometry matches the
+  PDF by construction, but glyphs are drawn by the viewer; the page now states the
+  three cases — a standard-14 name travels as a metric-compatible viewer font with
+  identical widths and different letterforms, an embeddable binary family travels as
+  itself, and a name-only family depends on the viewer having it installed.
 - **`TwinOutputExample`** — a single 16:9 page written once and emitted twice from the
   same session. The README gains a dual-output section showing the PDF render beside
   PowerPoint's own export of the generated slide, plus the deck open in PowerPoint with

examples/src/main/resources/logback.xml

@@ -7,7 +7,7 @@
 
     <logger name="org.apache.pdfbox" level="WARN"/>
     <logger name="org.apache.fontbox" level="WARN"/>
-    <logger name="com.demcha.compose" level="OFF"/>
+    <logger name="com.demcha.compose" level="WARN"/>
 
     <root level="ERROR">
         <appender-ref ref="CONSOLE"/>

render-pptx/README.md

@@ -67,9 +67,9 @@ the slide simply takes that size.
   [#413](https://github.com/DemchaAV/GraphCompose/issues/413).
 - **Glyphs are drawn by the viewer, not by GraphCompose.** Shape frames, line
   boxes and positions are fixed by the layout graph, but the actual glyph
-  rasterisation depends on the fonts installed on the viewing machine. Fonts are
-  embedded where the font's licensing bits allow it; otherwise PowerPoint
-  substitutes, and the backend logs which family was substituted.
+  rasterisation depends on the fonts available to the viewing machine. See
+  [Getting glyph-identical decks](#getting-glyph-identical-decks) for what that
+  costs and how to avoid it.
 - **Byte-for-byte reproducibility is opt-in.** The default path streams the deck
   with live timestamps. Pass
   `PptxFixedLayoutBackend.builder().deterministic(instant)` to pin the core
@@ -93,6 +93,40 @@ the slide simply takes that size.
 - **Multi-section documents** render into one deck; the sections must share a
   slide size.
 
+## Getting glyph-identical decks
+
+Geometry is identical to the PDF by construction — both backends consume the
+same resolved layout, and every line is pre-wrapped and absolutely placed, so
+PowerPoint can never reflow content. **Glyphs are the one thing PPTX cannot
+guarantee on its own**, because a deck names its fonts and the viewer draws
+them. Which of the three cases you land in depends on how the font reached the
+document, and the backend warns once per family for the two that are not exact:
+
+| How the font reached the document | In the deck | Glyphs |
+|---|---|---|
+| A standard-14 name (`FontName.HELVETICA`, `TIMES`, `COURIER`) | referenced as its metric-compatible viewer font — Arial, Times New Roman, Courier New | **widths identical, letterforms differ** |
+| A binary family whose licensing bits allow embedding | embedded in the deck | **identical everywhere** |
+| A family registered without binary sources, or one whose bits refuse embedding | referenced by name only | identical **if** the viewer has that font installed, otherwise the viewer substitutes |
+
+So for a deck that matches the PDF glyph for glyph, use a real font program
+rather than a PDF built-in — either a bundled family from `graph-compose-fonts`,
+or your own file registered on the session:
+
+```java
+try (DocumentSession document = GraphCompose.document()
+        .pageSize(DocumentPageSize.SLIDE_16_9)
+        .create()) {
+    document.registerFontFamily(myFamily);   // embedded when licensing allows
+    compose(document);
+    document.buildPptx(Path.of("deck.pptx"));
+}
+```
+
+Every substitution is announced at `WARN` under the key
+`render.pptx.font.substitution`, once per family per render, naming the font the
+document asked for and what the deck will reference instead. Embedded families
+log nothing — silence means the deck carries its own glyphs.
+
 ## When to depend on it
 
 Opt-in, at compile scope, when you want PowerPoint output. It is not pulled in