From 28f08fb1a09f38a099ccf1039a7c2ddd4831c3e4 Mon Sep 17 00:00:00 2001 From: DemchaAV Date: Mon, 6 Jul 2026 01:51:49 +0100 Subject: [PATCH] docs: repoint moved-module links and refresh the source-tree map The module split relocated the built-in templates to graph-compose-templates and the PDF backend to graph-compose-render-pdf, which left doc links pointing at the old core src/main paths. Repoint those links to the new module paths (templates/src/main and render-pdf/src/main), and update the CONTRIBUTING repository map and the architecture overview so the render backends and templates are attributed to their modules (FontShowcase now lives in the core document.showcase package). Also fix a stale reference-template link in the v1 authoring guide (the removed InvoiceTemplateV2 / ProposalTemplateV2 point at the current ModernInvoice / ModernProposal presets) and note the batteries-included bundle now carries templates and emoji. --- CONTRIBUTING.md | 14 ++++++++------ docs/adr/0004-pdf-handler-spi-extension.md | 6 +++--- docs/api-stability.md | 2 +- docs/architecture/overview.md | 12 ++++++++---- docs/contributing/implementation-guide.md | 8 ++++---- docs/migration/v1.8.0-fonts.md | 3 ++- docs/templates/v1-classic/authoring.md | 2 +- docs/templates/v2-layered/README.md | 4 ++-- docs/templates/v2-layered/authoring-presets.md | 2 +- docs/templates/v2-layered/contributor-guide.md | 2 +- docs/templates/v2-layered/quickstart.md | 2 +- docs/templates/v2-layered/using-templates.md | 4 ++-- 12 files changed, 34 insertions(+), 27 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0744a53fe..6a5d917cc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -89,12 +89,14 @@ See [docs/contributing/release-process.md](./docs/contributing/release-process.m Public canonical authoring surface — `DocumentSession`, the DSL builders, semantic node records, public style values, table types, image types, backend-neutral output options (metadata / watermark / protection / header-footer), and snapshot DTOs - `src/main/java/com/demcha/compose/document/layout` Canonical functional layout pipeline: `LayoutCompiler`, `BuiltInNodeDefinitions`, `TableLayoutSupport`, `PreparedNode`, `PlacedFragment` -- `src/main/java/com/demcha/compose/document/backend/fixed/pdf` - PDF backend: `PdfFixedLayoutBackend`, fragment handlers, the option translators that bridge canonical types to PDFBox, and `FontShowcase` (bundled-font preview renderer) -- `src/main/java/com/demcha/compose/document/backend/semantic` - Semantic exporters: `DocxSemanticBackend` (Apache POI based), `PptxSemanticBackend` (manifest skeleton) -- `src/main/java/com/demcha/compose/document/templates/*` +- `render-pdf/src/main/java/com/demcha/compose/document/backend/fixed/pdf` — module **graph-compose-render-pdf** + PDF backend: `PdfFixedLayoutBackend`, fragment handlers, and the option translators that bridge canonical types to PDFBox +- `render-docx/` and `render-pptx/` — modules **graph-compose-render-docx** / **graph-compose-render-pptx** + Semantic exporters `DocxSemanticBackend` (Apache POI based) and `PptxSemanticBackend` (manifest skeleton), under `com.demcha.compose.document.backend.semantic.{docx,pptx}` +- `templates/src/main/java/com/demcha/compose/document/templates/*` — module **graph-compose-templates** Built-in templates (CV, cover letter, invoice, proposal, weekly schedule), DTOs, themes, registries, and scene composition helpers +- `src/main/java/com/demcha/compose/document/showcase` + `FontShowcase` (bundled-font preview renderer) — stays in the core engine - `src/main/java/com/demcha/compose/engine/*` Internal shared engine foundation under the canonical surface (measure, paginate, place, render). Not part of the recommended public API - `src/main/java/com/demcha/compose/font` @@ -170,7 +172,7 @@ not need any of them. `engine/components`. - PDF rendering logic for the legacy ECS renderer (deprecated; canonical PDF output goes through `com.demcha.compose.document.backend.fixed.pdf`) lives in - `src/main/java/com/demcha/compose/engine/render/pdf/ecs/handlers/`. + `render-pdf/src/main/java/com/demcha/compose/engine/render/pdf/ecs/handlers/`. Backend-only helper objects live in `com.demcha.compose.engine.render.pdf.ecs.helpers`, not in `components/renderable`. diff --git a/docs/adr/0004-pdf-handler-spi-extension.md b/docs/adr/0004-pdf-handler-spi-extension.md index 9ca8b9524..14d1ce12f 100644 --- a/docs/adr/0004-pdf-handler-spi-extension.md +++ b/docs/adr/0004-pdf-handler-spi-extension.md @@ -45,7 +45,7 @@ Concretely: Javadoc is rewritten to declare it a public extension point with stateless invariant. The "package-private" wording is gone. 2. A new method - [`PdfFixedLayoutBackend.Builder#addHandler(PdfFragmentRenderHandler)`](../../src/main/java/com/demcha/compose/document/backend/fixed/pdf/PdfFixedLayoutBackend.java) + [`PdfFixedLayoutBackend.Builder#addHandler(PdfFragmentRenderHandler)`](../../render-pdf/src/main/java/com/demcha/compose/document/backend/fixed/pdf/PdfFixedLayoutBackend.java) accepts a custom handler. It is additive: omitting it reproduces the existing default-handler set. Calling it with a payload type already covered by a default replaces the default for the resulting backend @@ -62,10 +62,10 @@ Concretely: ## Coverage -- [`PdfFragmentRenderHandler`](../../src/main/java/com/demcha/compose/document/backend/fixed/pdf/PdfFragmentRenderHandler.java) +- [`PdfFragmentRenderHandler`](../../render-pdf/src/main/java/com/demcha/compose/document/backend/fixed/pdf/PdfFragmentRenderHandler.java) Javadoc names `Builder.addHandler(...)` as the registration path and states the stateless invariant explicitly. -- [`PdfFixedLayoutBackend.Builder#addHandler`](../../src/main/java/com/demcha/compose/document/backend/fixed/pdf/PdfFixedLayoutBackend.java) +- [`PdfFixedLayoutBackend.Builder#addHandler`](../../render-pdf/src/main/java/com/demcha/compose/document/backend/fixed/pdf/PdfFixedLayoutBackend.java) is the new entry point. - [`PdfBackendExtensibilityTest`](../../src/test/java/com/demcha/compose/document/backend/fixed/pdf/PdfBackendExtensibilityTest.java) pins three behaviours: diff --git a/docs/api-stability.md b/docs/api-stability.md index ab6bc2dbf..6460e2805 100644 --- a/docs/api-stability.md +++ b/docs/api-stability.md @@ -64,7 +64,7 @@ are: - [`ChartSize`](../src/main/java/com/demcha/compose/document/chart/ChartSize.java) (Stable) - [`ChartSpec`](../src/main/java/com/demcha/compose/document/chart/ChartSpec.java) (Stable) -- [`CvSection`](../src/main/java/com/demcha/compose/document/templates/cv/data/CvSection.java) (Stable) +- [`CvSection`](../templates/src/main/java/com/demcha/compose/document/templates/cv/data/CvSection.java) (Stable) - [`DocumentLinkTarget`](../src/main/java/com/demcha/compose/document/node/DocumentLinkTarget.java) (Stable) - [`DocumentPaint`](../src/main/java/com/demcha/compose/document/style/DocumentPaint.java) (Stable) - [`DocumentPathSegment`](../src/main/java/com/demcha/compose/document/style/DocumentPathSegment.java) (Stable) diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index a30d2031b..97742958a 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -250,13 +250,17 @@ Canonical-first ordering — public roots come first, internal foundation last: - `com.demcha.compose.document.*` — **public canonical surface**. - Authoring API, layout graph, backends, exceptions, snapshots, and - built-in templates. + Authoring API, layout graph, exceptions, snapshots. The render backends + (`document.backend.fixed.pdf` in **graph-compose-render-pdf**, + `document.backend.semantic.*` in the docx / pptx modules) and the built-in + templates (`document.templates.*` in **graph-compose-templates**) share this + namespace but ship as separate, opt-in artifacts over `graph-compose-core`. - `com.demcha.compose.font.*` — public font names, backend-neutral family descriptors, registration, lookup, and showcase helpers. - `com.demcha.compose.engine.*` — **internal engine foundation**. - Measurement, layout resolution, pagination, render-pass session, and - PDF rendering systems. + Measurement, layout resolution, pagination, and render-pass session in + `graph-compose-core`; the PDF rendering systems (`engine.render.pdf.*`) ship + in **graph-compose-render-pdf**. - `com.demcha.compose.engine.text.*` — internal text utilities used by layout and render hot paths. - `com.demcha.compose.engine.text.markdown.*` — internal diff --git a/docs/contributing/implementation-guide.md b/docs/contributing/implementation-guide.md index 53130370a..2d9119677 100644 --- a/docs/contributing/implementation-guide.md +++ b/docs/contributing/implementation-guide.md @@ -259,7 +259,7 @@ Relevant files: - [TableBuilder.java](../../src/test/java/com/demcha/compose/testsupport/engine/assembly/TableBuilder.java) - [TableRow.java](../../src/main/java/com/demcha/compose/engine/components/renderable/TableRow.java) -- [TableCellBox.java](../../src/main/java/com/demcha/compose/engine/render/pdf/ecs/helpers/TableCellBox.java) +- [TableCellBox.java](../../render-pdf/src/main/java/com/demcha/compose/engine/render/pdf/ecs/helpers/TableCellBox.java) - [TableResolvedCell.java](../../src/main/java/com/demcha/compose/engine/components/content/table/TableResolvedCell.java) Rule of thumb: @@ -334,8 +334,8 @@ Important files: - [Render.java](../../src/main/java/com/demcha/compose/engine/render/Render.java) - [RenderPassSession.java](../../src/main/java/com/demcha/compose/engine/render/RenderPassSession.java) - [RenderStream.java](../../src/main/java/com/demcha/compose/engine/render/RenderStream.java) -- [PdfRenderingSystemECS.java](../../src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfRenderingSystemECS.java) -- [PdfRenderSession.java](../../src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfRenderSession.java) +- [PdfRenderingSystemECS.java](../../render-pdf/src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfRenderingSystemECS.java) +- [PdfRenderSession.java](../../render-pdf/src/main/java/com/demcha/compose/engine/render/pdf/ecs/PdfRenderSession.java) - [EntityRenderOrder.java](../../src/main/java/com/demcha/compose/engine/render/EntityRenderOrder.java) Migration rule for new engine components: @@ -448,7 +448,7 @@ Do not add a method there if the new object is only an internal helper for templ - container: [ModuleBuilder.java](../../src/test/java/com/demcha/compose/testsupport/engine/assembly/ModuleBuilder.java) - template-level composition helper: - [SectionDispatcher.java](../../src/main/java/com/demcha/compose/document/templates/cv/components/SectionDispatcher.java) + [SectionDispatcher.java](../../templates/src/main/java/com/demcha/compose/document/templates/cv/components/SectionDispatcher.java) ## Overlay primitive: `LayerStackNode` diff --git a/docs/migration/v1.8.0-fonts.md b/docs/migration/v1.8.0-fonts.md index f6903bc2d..6f6c36f74 100644 --- a/docs/migration/v1.8.0-fonts.md +++ b/docs/migration/v1.8.0-fonts.md @@ -61,7 +61,8 @@ version, and vice-versa. ### Option B — one coordinate, batteries included -Depend on the bundle, which pulls a compatible engine + fonts pair: +Depend on the bundle, which pulls a compatible batteries-included set — the +default PDF engine, the built-in templates, the fonts, and the colour emoji: ```xml diff --git a/docs/templates/v1-classic/authoring.md b/docs/templates/v1-classic/authoring.md index a5255b45f..23eeed76c 100644 --- a/docs/templates/v1-classic/authoring.md +++ b/docs/templates/v1-classic/authoring.md @@ -436,5 +436,5 @@ and | Snapshot-based regression workflow | [`recipes/extending.md` § 4](../../recipes/extending.md#4-validate-a-custom-nodes-layout-via-snapshots) | | Migrating from v1.4 to v1.5 | [`migration-v1-4-to-v1-5.md`](../../roadmaps/migration-v1-4-to-v1-5.md) | | Architecture decision records | [`adr/`](../../adr/) | -| Reference V2 templates | [`InvoiceTemplateV2`](../../../src/main/java/com/demcha/compose/document/templates/builtins/InvoiceTemplateV2.java), [`ProposalTemplateV2`](../../../src/main/java/com/demcha/compose/document/templates/builtins/ProposalTemplateV2.java) | +| Reference templates | [`ModernInvoice`](../../../templates/src/main/java/com/demcha/compose/document/templates/invoice/presets/ModernInvoice.java), [`ModernProposal`](../../../templates/src/main/java/com/demcha/compose/document/templates/proposal/presets/ModernProposal.java) | | Hand-built theme example | [`CustomBusinessThemeExample`](../../../examples/src/main/java/com/demcha/examples/features/themes/CustomBusinessThemeExample.java) | diff --git a/docs/templates/v2-layered/README.md b/docs/templates/v2-layered/README.md index 0c273abe3..290e1d8b6 100644 --- a/docs/templates/v2-layered/README.md +++ b/docs/templates/v2-layered/README.md @@ -113,10 +113,10 @@ The detailed contract for each layer is in ## See also - **Per-package JavaDocs**: - [`cv/package-info.java`](../../../src/main/java/com/demcha/compose/document/templates/cv/package-info.java) + [`cv/package-info.java`](../../../templates/src/main/java/com/demcha/compose/document/templates/cv/package-info.java) has the ASCII diagram and 4-step author walkthrough. - **AUTHORS.md**: - [`cv/AUTHORS.md`](../../../src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md) + [`cv/AUTHORS.md`](../../../templates/src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md) is the recipe cookbook — 7 hands-on recipes from "change a bullet glyph" to "add a new section subtype". - **Examples**: diff --git a/docs/templates/v2-layered/authoring-presets.md b/docs/templates/v2-layered/authoring-presets.md index 4b9e3f3b1..1d2e234f1 100644 --- a/docs/templates/v2-layered/authoring-presets.md +++ b/docs/templates/v2-layered/authoring-presets.md @@ -412,4 +412,4 @@ cover-letter-v2) following the same layered shape? → The full recipe cookbook (with code for every customisation combo): -[`cv/AUTHORS.md`](../../../src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md) +[`cv/AUTHORS.md`](../../../templates/src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md) diff --git a/docs/templates/v2-layered/contributor-guide.md b/docs/templates/v2-layered/contributor-guide.md index 4de4d60b3..ee4c662ef 100644 --- a/docs/templates/v2-layered/contributor-guide.md +++ b/docs/templates/v2-layered/contributor-guide.md @@ -64,7 +64,7 @@ data differs; the *layering* is identical. Mirror the CV v2 layout. Concrete example for invoice: ``` -src/main/java/com/demcha/compose/document/templates/invoice/ +templates/src/main/java/com/demcha/compose/document/templates/invoice/ ├── package-info.java ← ASCII diagram + 4-step walkthrough ├── AUTHORS.md ← recipe cookbook ├── data/ diff --git a/docs/templates/v2-layered/quickstart.md b/docs/templates/v2-layered/quickstart.md index f535564dd..21251b55c 100644 --- a/docs/templates/v2-layered/quickstart.md +++ b/docs/templates/v2-layered/quickstart.md @@ -150,5 +150,5 @@ touch a renderer. A new widget doesn't touch the data model. | Render your own CV with your data | [using-templates.md](using-templates.md) | | Make a new visual style | [authoring-presets.md](authoring-presets.md) | | Add a new template family to the library (invoice, cover-letter) | [contributor-guide.md](contributor-guide.md) | -| See hands-on recipes (change a bullet, swap colours, …) | [`cv/AUTHORS.md`](../../../src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md) | +| See hands-on recipes (change a bullet, swap colours, …) | [`cv/AUTHORS.md`](../../../templates/src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md) | | Run the shipped examples | [`examples/cv/v2/`](../../examples/src/main/java/com/demcha/examples/templates/cv/v2) | diff --git a/docs/templates/v2-layered/using-templates.md b/docs/templates/v2-layered/using-templates.md index 0f24d3d01..bcfaf31fd 100644 --- a/docs/templates/v2-layered/using-templates.md +++ b/docs/templates/v2-layered/using-templates.md @@ -291,7 +291,7 @@ BrandTheme theme = new BrandTheme( ``` For more recipes (compact spacing, alternative typography scales, -etc.) see [`cv/AUTHORS.md`](../../../src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md). +etc.) see [`cv/AUTHORS.md`](../../../templates/src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md). --- @@ -391,4 +391,4 @@ No GitHub, no Projects, no Tech Skills — and the API doesn't notice. [**authoring-presets.md**](authoring-presets.md) → Reference for every recipe (change bullet, swap colours, …) -[`cv/AUTHORS.md`](../../../src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md) +[`cv/AUTHORS.md`](../../../templates/src/main/java/com/demcha/compose/document/templates/cv/AUTHORS.md)