From 7114c04aa5dcb41998b67671b6b495fad58a06f2 Mon Sep 17 00:00:00 2001 From: Martin Hinshelwood Date: Wed, 23 Sep 2026 15:25:15 +0100 Subject: [PATCH 1/4] Add layered PDF recipe, cover credits and translation-team contributor files PDFs: Get-GuidePdfPlan now builds the recipe only from committed configuration, layered platform -> /pdf -> guide -> edition with . variants. Adds default cover, licence, back, running header/footer and style templates, the reviewed callouts and Hugo image filters, CJK font keys, RTL support and per-download overrides. Removes the per-run HeaderPaths/LuaFilterPaths/FontOverrides parameters and the Kanban-specific cover-page.tex. Contributors: data/contributions/..yml holds translation teams; localizedNames per record; Get-GuideCredits resolves authors (role creator), contributors and translators for PDFs. Website translator displays read the data files, including PDF-only translations. Prepare blocks retired front matter (author, translators, fonts, dir), invalid contributor records and PDF settings, and warns on missing creators, translators and PDF labels. Discovery reads declared downloads and records language direction. The sample site is migrated. Spec: docs/architecture/guide-pdf-and-contributors.md Co-Authored-By: Claude Opus 5.5 --- docs/architecture/current-system.md | 5 +- .../guide-pdf-and-contributors.md | 314 ++++++++++++++++++ .../content/Guide1/2020.12/index.md | 5 - .../content/Guide1/2020.12/index.min.md | 6 - .../content/Guide1/2020.7/index.md | 6 - .../content/Guide1/2020.7/index.min.md | 6 - .../content/Guide1/2025.5/index.md | 6 - .../content/Guide1/2025.5/index.min.md | 6 - .../content/Guide2/2025.7/index.md | 5 - .../content/Guide2/2025.7/index.min.md | 5 - .../data/contributions/guide1.min.yml | 8 + .../data/contributions/guide1.yml | 32 +- .../data/contributions/guide2.min.yml | 6 + .../data/contributions/guide2.yml | 29 +- examples/reference-guide-site/i18n/en.yaml | 3 + examples/reference-guide-site/i18n/min.yaml | 3 + examples/reference-guide-site/pdf/README.md | 14 + examples/reference-guide-site/pdf/pdf.ja.yaml | 5 + examples/reference-guide-site/pdf/pdf.yaml | 5 + .../instructions/guide-site.md | 1 + .../skills/guide.contributions/SKILL.md | 12 +- .../skills/guide.genpdfs/SKILL.md | 10 +- .../components/guide/guide-translators.html | 6 +- .../translations/community-translations2.html | 14 +- .../_partials/functions/get-contributors.html | 10 +- .../_partials/functions/get-participants.html | 6 +- .../_partials/functions/get-translators.html | 25 ++ .../functions/localize-contributor.html | 17 + .../Assessment/Get-GuideAssessment.ps1 | 8 + .../Contracts/site-policy.schema.json | 4 + .../Get-GuideCredits.ps1 | 147 ++++++++ .../New-GuideContributions.ps1 | 6 +- .../Update-GuideContributions.ps1 | 21 +- .../GuideInventory/Get-GuideInventory.ps1 | 5 +- .../OpenGuidePlatform.PowerShell.Core.psd1 | 2 +- .../OpenGuidePlatform.PowerShell.Core.psm1 | 2 + .../PdfPublishing/Get-GuidePdfPlan.ps1 | 144 +++++++- .../PdfPublishing/Resolve-GuidePdfRecipe.ps1 | 227 +++++++++++++ .../PdfPublishing/Test-GuidePdfCache.ps1 | 3 +- .../PdfPublishing/templates/back.tex | 8 + .../PdfPublishing/templates/body-start.tex | 5 + .../PdfPublishing/templates/cover-page.tex | 39 --- .../PdfPublishing/templates/cover.tex | 42 +++ .../templates/filters/callouts.lua | 75 +++++ .../templates/filters/callouts.tex | 21 ++ .../templates/filters/hugo-images.lua | 9 + .../PdfPublishing/templates/labels.yaml | 11 + .../PdfPublishing/templates/licence.tex | 12 + .../PdfPublishing/templates/page-footer.tex | 5 + .../PdfPublishing/templates/page-header.tex | 15 + .../PdfPublishing/templates/pdf.yaml | 14 + .../PdfPublishing/templates/rtl.tex | 8 + .../PdfPublishing/templates/style.tex | 13 + .../README.md | 19 ++ .../Discovery/New-GuideSiteDiscovery.ps1 | 29 +- tests/Core/Assessment.Tests.ps1 | 12 + tests/Core/Discovery.Tests.ps1 | 27 ++ tests/Core/GuideCredits.Tests.ps1 | 93 ++++++ tests/Core/GuidePdfRecipe.Tests.ps1 | 133 ++++++++ tests/Core/HugoGuideRendering.Tests.ps1 | 19 +- 60 files changed, 1569 insertions(+), 179 deletions(-) create mode 100644 docs/architecture/guide-pdf-and-contributors.md create mode 100644 examples/reference-guide-site/data/contributions/guide1.min.yml create mode 100644 examples/reference-guide-site/data/contributions/guide2.min.yml create mode 100644 examples/reference-guide-site/pdf/README.md create mode 100644 examples/reference-guide-site/pdf/pdf.ja.yaml create mode 100644 examples/reference-guide-site/pdf/pdf.yaml create mode 100644 system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/functions/get-translators.html create mode 100644 system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/functions/localize-contributor.html create mode 100644 system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/Get-GuideCredits.ps1 create mode 100644 system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Resolve-GuidePdfRecipe.ps1 create mode 100644 system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/back.tex create mode 100644 system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/body-start.tex delete mode 100644 system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/cover-page.tex create mode 100644 system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/cover.tex create mode 100644 system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/filters/callouts.lua create mode 100644 system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/filters/callouts.tex create mode 100644 system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/filters/hugo-images.lua create mode 100644 system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/labels.yaml create mode 100644 system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/licence.tex create mode 100644 system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/page-footer.tex create mode 100644 system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/page-header.tex create mode 100644 system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/pdf.yaml create mode 100644 system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/rtl.tex create mode 100644 system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/style.tex create mode 100644 tests/Core/GuideCredits.Tests.ps1 create mode 100644 tests/Core/GuidePdfRecipe.Tests.ps1 diff --git a/docs/architecture/current-system.md b/docs/architecture/current-system.md index 2997b0c8..8585aab7 100644 --- a/docs/architecture/current-system.md +++ b/docs/architecture/current-system.md @@ -28,7 +28,8 @@ The **PowerShell filesystem walk**, not `hugo list all`, creates the `guides`, ` | Guide | Recursively find `_index.md` under the configured content directory; keep a directory when that file's front matter has `type: guide` and `layout: root` and at least one accepted edition. Guide `id` is its path relative to the content directory. | | Edition/version | Inspect immediate child directories of the guide. Keep one when it contains `index.md`, its layout is not `translations`, `history`, `root` or `details`, and its front matter has either `type: guide` or a `version` field. Use the `version` field as edition `id` when present; otherwise use the directory name. | | Language | Collect languages from edition-root `index*.md` filenames and from recognised PDF suffixes. `index.md` means the configured default language; `index..md` supplies ``. | -| PDF/download | Find `*.pdf` recursively inside the edition. A filename ending `..pdf` is assigned to that language; a PDF without a recognised suffix is assigned to the configured default language. Store its path relative to the edition and mark its inferred handling `supplied`. | +| PDF/download | Find `*.pdf` recursively inside the edition, plus any path declared in `/pdf///pdf[.].yaml` `downloads`. A filename ending `..pdf` is assigned to that language; a PDF without a recognised suffix is assigned to the configured default language. Store its path relative to the edition with the declared handling, otherwise `supplied`. | +| Language direction | Record `direction` (or the older `languageDirection`) for each configured language in `wrapper.languageDirections`. | For each collected language, the code reads the corresponding `index.md` or `index..md` body and infers `web` when populated, `pdf-only` when the body is empty but a matching PDF exists, `web` for the empty default-language source, or `fallback` to the default language otherwise. It also records required guide-root, history and translations wrapper files for active guide languages. These are the rules in the [source walk and entry construction](../../system/OpenGuidePlatform.PowerShell.GuideSiteBuild/Discovery/New-GuideSiteDiscovery.ps1); they describe what the code currently recognises, not a proposed content format. @@ -64,7 +65,7 @@ The [build-stage script](../../system/OpenGuidePlatform.PowerShell.GuideSiteBuil ## PDF evidence and preservation -[`Get-GuidePdfPlan` and `New-GuidePdf`](../../system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Get-GuidePdfPlan.ps1) select only a download declared `generated`, read `index.md` or `index..md`, and pass language to Pandoc as metadata. They check tools/fonts, render in staging and check the PDF header before publishing. Replacement requires the existing output's expected SHA256. Supplied and protected downloads cannot be selected for generation. [`Get-GuideAssessment`](../../system/OpenGuidePlatform.PowerShell.Core/Assessment/Get-GuideAssessment.ps1) flags `lang` in Hugo front matter as deprecated. +[`Get-GuidePdfPlan` and `New-GuidePdf`](../../system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Get-GuidePdfPlan.ps1) select only a download declared `generated`, read `index.md` or `index..md`, and pass language to Pandoc as metadata. The recipe is [resolved](../../system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Resolve-GuidePdfRecipe.ps1) from platform templates and the site's `pdf/` folder by guide, edition and language; cover credits come from [contributor data](../../system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/Get-GuideCredits.ps1). Template parts are rendered with the generated metadata before the main Pandoc run. See [Guide PDFs and contributor records](guide-pdf-and-contributors.md). They check tools/fonts, render in staging and check the PDF header before publishing. Replacement requires the existing output's expected SHA256. Supplied and protected downloads cannot be selected for generation. [`Get-GuideAssessment`](../../system/OpenGuidePlatform.PowerShell.Core/Assessment/Get-GuideAssessment.ps1) flags `lang` in Hugo front matter as deprecated, blocks the retired `author`, `translators`, font and `dir` keys, and validates contributor data and PDF settings. [`New-GuidePdf`](../../system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Get-GuidePdfPlan.ps1) returns a v1 receipt with guide, edition, language, input/output hashes, configuration hash, toolchain, environment digest and optional cache key. [`Save-GuidePdfReceipt` and `Get-GuidePdfReceipts`](../../system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Get-GuidePdfReceipts.ps1) save and validate declared receipts; Prepare calls the latter without rerunning Pandoc. [`Test-GuidePdfCache`](../../system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Test-GuidePdfCache.ps1) uses content/recipe/tool/environment evidence rather than timestamps. The returned PDF result says visual review is required; neither receipt validation nor source discovery assesses translation quality. diff --git a/docs/architecture/guide-pdf-and-contributors.md b/docs/architecture/guide-pdf-and-contributors.md new file mode 100644 index 00000000..752dc1b4 --- /dev/null +++ b/docs/architecture/guide-pdf-and-contributors.md @@ -0,0 +1,314 @@ +# Guide PDFs and contributor records + +Status: platform part (actions 1 and 3, and section 5) implemented on branch `feature/guide-pdf-and-contributors`; consumer adoption (actions 2 and 4) not started. Section 9 records where the implementation differs from the original draft. + +## 1. Purpose and scope + +Every generated guide PDF gets a cover page with the title, edition, date, authors, contributors and translators, and every part of the PDF can be overridden per site, guide, edition and language. To make that possible, contributor and translator records move to one data format, and PDF settings move out of guide Markdown into a dedicated site folder. + +The work is delivered as four actions: + +1. Platform: new contributor record format (section 3). +2. Consumers: adopt the contributor format (section 7). +3. Platform: new PDF format (section 4). +4. Consumers: adopt the PDF format (section 7). + +Actions 1 and 3 ship in one coordinated platform release so each consumer performs a single preview update and one adoption branch. Prepare validation (section 5) ships in the same release. + +Out of scope: renaming guide identifiers or published PDF filenames, regenerating any PDF without an explicit `generated` declaration and visual review, translation quality, and Hugo module refactoring (E14). + +## 2. Current state + +Observed in KanbanGuides and ScrumGuide-ExpansionPack on 2026-09-23. + +PDF generation (`PdfPublishing/Get-GuidePdfPlan.ps1`) runs Pandoc with XeLaTeX and Pandoc's default LaTeX template. It passes only `--pdf-engine`, `-interaction=nonstopmode`, `lang` and an empty `keywords`. Header files, Lua filters and font overrides are per-invocation parameters; nothing records a site's approved recipe. The shipped `templates/cover-page.tex` is not wired to any invocation and contains Kanban-specific fixed text. ScrumGuide-ExpansionPack still tracks its retired recipe in `scripts/` (`Create-GuidePDFs.ps1`, `callouts-latex.lua`, `callouts-header.tex`, `callouts.lua`, `cover-page.tex`); its cover is the same template with Scrum-specific fixed text. + +PDF settings live in guide front matter: `mainfont`, `sansfont`, `monofont` and, for Persian, `dir`. Values are identical for every file of a language, with two exceptions in ScrumGuide-ExpansionPack: Japanese uses Times New Roman/Arial (no CJK glyphs), and `de` 2025.6 declares no fonts. + +Contributors are recorded in three inconsistent places: + +| Record | Location | Consumers | +|---|---|---| +| Authors | `author:` in every translation's front matter, and again as `role: creator` in `site/data/contributions/.yml` | JSON-LD `person.html`, Kanban home page | +| Contributors | `site/data/contributions/.yml` (`.yml` or `.yaml`) filtered by edition | `get-contributors.html` | +| Translators | `translators:` in some translations' front matter; names in body text for others; nothing for many | `guide-translators.html`, `community-translations2.html` | + +Known data defects are listed per consumer in section 7. + +## 3. Contributor records + +### 3.1 Files + +``` +site/data/contributions/ +├── .yml ← guide source: creators, contributors, reviewers +└── ..yml ← one translation team: translators, translation reviewers +``` + +`` is the content language code exactly as used in `index..md`. New files use `.yml`. Hugo does not treat the language suffix in data specially; layouts read `hugo.Data.contributions` with the key `.`. + +A subfolder per guide is not used because it would collide with the existing `.yml` key. + +### 3.2 Record schema + +Both files are YAML lists of records: + +| Field | Required | Meaning | +|---|---|---| +| `name` | yes | Display name | +| `role` | yes | One of the roles in 3.3, lower case | +| `contributions` | yes | Edition identifiers (`"2025.7"`) this record applies to | +| `weight` | no | Sort order, ascending; default 100 | +| `localizedNames` | no | Map of language code to the name as displayed in that language | +| `githubUsername`, `gravatarHash`, `url`, `founder` | no | Unchanged from today | + +Example `the-kanban-guide.yml` record with a Persian spelling, and `the-kanban-guide.fa.yml`: + +```yaml +- name: John Coleman + role: creator + contributions: ["2020.7", "2020.12", "2025.5"] + weight: 1 + localizedNames: + fa: جان کولمن +``` + +```yaml +- name: Pedram Keshavarzi + githubUsername: pedicurus + url: https://www.agile-gap.com/p/pedram-keshavarzi + role: translator + contributions: ["2025.5"] + weight: 6 +``` + +Within a file a person appears once, identified by `githubUsername` when present, otherwise by `name`. + +### 3.3 Roles + +| File | Roles | Shown as | +|---|---|---| +| `.yml` | `creator` | Authors | +| | `contributor`, `reviewer`, `involved` | Contributors (which roles appear is decision D3) | +| `..yml` | `translator` | Translators | +| | `reviewer` | Translation reviewers (decision D4) | + +Existing values are normalised on adoption: `Translator` → `translator`, `Reviewer` and `translation reviewer` → `reviewer`. Other values are refused by validation. + +### 3.4 Resolution for a page or PDF + +For guide `g`, edition `e`, language `l`: + +- Authors: records in `g.yml` with `role: creator` and `e` in `contributions`. +- Contributors: other records in `g.yml` for `e`, filtered by the roles selected. +- Translators: records in `g.l.yml` for `e`. Absent for the source language. +- Names: `localizedNames[l]` when present, otherwise `name`. +- Order: `weight`, then `name`. + +### 3.5 Retired front matter + +`translators:` is removed from all translation files and no longer read. `author:` is retired as well (decision D2). No platform layout reads guide `author` (the JSON-LD `person.html` reads `author` only on creator profile pages); the KanbanGuides home page (site-owned) reads it and is updated during adoption. + +### 3.6 Platform changes + +- Hugo module: `functions/get-translators.html` implements 3.4 for translation teams (data key matched case-insensitively, so `es-ES` files serve `es-es` pages); `guide-translators.html`, `community-translations2.html` (including PDF-only translations) and `get-participants.html` use it. `functions/localize-contributor.html` applies `localizedNames`, and `get-contributors.html` returns localised records. Language files join the existing all-guides list. +- `baseof.html` keeps the deprecated `.Language.LanguageDirection`: the platform supports Hugo 0.146+, and `.Language.Direction` only exists from 0.158. +- Core ContributorManagement: `New-GuideContributions` and `Update-GuideContributions` accept an optional language and address `..yml`. Existing `.yaml` files remain addressable until renamed. +- Skill `guide.contributions`: documents language files and the role set. + +## 4. PDF format + +### 4.1 Location + +Site-owned PDF configuration lives under `/pdf/` (for current consumers, `site/pdf/`). It is outside `content/` so Hugo does not publish templates as page resources, and it follows `site.source` so no additional setting is needed. + +### 4.2 Layering + +Most specific wins: + +| Level | Folder | +|---|---| +| Platform default | `system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/` | +| Site | `site/pdf/` | +| Guide | `site/pdf//` | +| Edition | `site/pdf///` | + +At every level a file may carry a language suffix (`cover.fa.tex`, `pdf.ja.yaml`). For a given level the language-suffixed file is applied after the unsuffixed one. + +### 4.3 Files + +| File | Part | Combination | +|---|---|---| +| `pdf.yaml` | Settings (4.4) | Merged key by key; lists replace | +| `cover.tex` | Cover page | Most specific file replaces | +| `page-header.tex`, `page-footer.tex` | Running header and footer | Most specific file replaces | +| `style.tex` | LaTeX preamble: colours, headings, spacing | Most specific file replaces | +| `licence.tex` | Licence and attribution page | Most specific file replaces | +| `back.tex` | Back page or colophon | Most specific file replaces | +| `filters/*.lua` | Pandoc Lua filters | Accumulate by filename; a same-named file at a more specific level replaces | +| `images/*` | Assets referenced by templates | Resource path, most specific first | + +Two fixed platform files are not overridable: `body-start.tex`, added after the front parts so the body starts on page 1, and `rtl.tex`, added for right-to-left languages to define `\LR`/`\RL`, which Pandoc's babel setup for XeTeX omits. A filter's optional `filters/.tex` is raw LaTeX included in the preamble with it. + +The name `header.tex` is not used because Pandoc's `--include-in-header` means the preamble, not the running header. + +### 4.4 `pdf.yaml` keys + +```yaml +mainfont: Times New Roman +sansfont: Arial +monofont: Courier New +CJKmainfont: "" # required for Japanese/Chinese/Korean line breaking; also CJKsansfont, CJKmonofont +papersize: a4 # a4 | letter +geometry: margin=2.2cm +fontsize: 11pt +toc: false +tocDepth: 2 +watermark: "" # e.g. set for preview translations +licence: "" # licence page text; no licence page when empty +parts: [cover, licence, body, back] +cover: + tagline: "" # e.g. "Based on the Scrum Guide 2020" + contributorRoles: [contributor, reviewer] + translatorRoles: [translator] +downloads: # edition level only + - path: pdf/.pdf + handling: supplied # supplied | protected | generated; default supplied + papersize: letter # per-download overrides: papersize, geometry, fontsize, watermark +``` + +Unknown keys are refused. `downloads` replaces the policy inventory removed during adoption and is the only place a PDF becomes eligible for generation. + +When `cover.tagline` is empty and the edition's front matter has `forked_from`, the default cover shows "Based on" followed by the source guide's title and edition. + +### 4.5 What is no longer read from front matter + +`mainfont`, `sansfont`, `monofont` and `dir` are removed from guide front matter and not read. There is no front-matter override; a single translation that needs different settings gets `site/pdf///pdf..yaml`. + +Text direction comes from Hugo's `languages..direction` (Hugo 0.158+; the older `languageDirection` key is deprecated but still honoured). Pandoc language metadata continues to come from the filename; `lang` stays out of front matter. + +### 4.6 Cover data + +Core writes a Pandoc metadata file per PDF and passes it with `--metadata-file`: + +| Variable | Source | +|---|---| +| `title`, `short_title`, `date` | Translation front matter | +| `edition` | Edition folder name | +| `guide` | Guide identifier | +| `authors`, `contributors`, `translators` | Section 3.4; each item has `name`, `role` and, when known, `url` | +| `tagline` / `based_on` | `cover.tagline`, or `forked_from` resolved to title and edition | +| `labels.*` | Effective i18n catalogue for the language (4.7) | +| `logo` | `content//images/-logo.png` when present | +| `licence`, `watermark` | `pdf.yaml` | +| `dir` | Set to `rtl` only for right-to-left languages (Pandoc loads bidi support whenever `dir` is set) | + +In right-to-left documents, text values without any right-to-left characters (Latin names, untranslated labels) are wrapped in left-to-right spans so their word order and punctuation survive. Pandoc's own title block is suppressed (`title` and `author` are cleared on the command line); the cover replaces it, and `title-meta`/`author-meta` keep the PDF properties. + +Templates use Pandoc template syntax, for example `$for(translators)$$translators.name$$sep$ · $endfor$`. + +### 4.7 Labels + +Labels come from the site i18n catalogue: platform English defaults, then the site catalogue for the source language, then the PDF language. Ids: `pdf_authors_label`, `pdf_contributors_label`, `pdf_translators_label`, `pdf_edition_label`, `pdf_based_on_label` and `pdf_callout_note`, `_tip`, `_important`, `_warning`, `_caution` (callout default titles). Prepare warns when a language with a generated PDF lacks any of them. + +### 4.8 Platform defaults + +The platform ships a complete default set: `pdf.yaml`, `labels.yaml`, `cover.tex`, `page-header.tex`, `page-footer.tex`, `style.tex`, `licence.tex`, `back.tex`, `filters/callouts.lua` with `filters/callouts.tex`, and `filters/hugo-images.lua`. The callouts filter and image handling come from ScrumGuide-ExpansionPack `scripts/`; review fixed three defects there: body text after the marker line became the title, titles were escaped incorrectly, and emoji icons are absent from the configured fonts (removed). Callout titles are translatable. Defaults contain no guide- or site-specific text. The old `templates/cover-page.tex` is removed. + +### 4.9 Core changes + +- `Get-GuidePdfPlan` resolves the layered files and settings itself. The per-invocation `HeaderPaths`, `LuaFilterPaths` and `FontOverrides` parameters are removed so the approved recipe is always the committed configuration (decision D6). +- The plan lists every resolved file with the level it came from, the merged settings and the generated metadata. All of these, the contributor data files and the i18n catalogue entries used are fingerprinted. +- Template parts are rendered first, each with its own Pandoc call (`--template --metadata-file`), because Pandoc does not expand variables in included files. The main call then uses `--include-in-header` (rtl support, style, running header/footer, filter preambles), `--include-before-body` (cover, licence, body start) and `--include-after-body` (back page), one `--lua-filter` per resolved filter, `--metadata-file`, `-V` for settings and `--resource-path` for the edition folder and `images/` folders. +- Generation is refused when a required font is not installed, as today. + +### 4.10 File naming for new PDFs + +New generated downloads use `/pdf/...pdf`. Existing published filenames are preserved and declared explicitly in `downloads`. + +## 5. Validation in Prepare + +Prepare reports, and the build fails on: + +- `translators`, `author`, `mainfont`, `sansfont`, `monofont` or `dir` in guide front matter; +- a contributor record without `name`, `role` or `contributions`, with an unknown role, or duplicated within a file; +- an edition in `contributions` that has no edition folder; +- a data file for a guide or language that does not exist; +- unknown `pdf.yaml` keys or a `downloads` path outside the edition; +- two data files for the same key differing only by `.yml`/`.yaml`. + +Prepare warns on a web translation with no translator record and an edition with no creator (only when the site has a `data/contributions` folder), and on a missing PDF label translation for a language with a generated PDF. Findings use the existing assessment scopes: contributor files `guide`, missing creators `edition`, missing translators `translation`, PDF settings `download`, labels `wrapper`. + +## 6. Rollout + +1. Agree this document and the decisions in section 8. +2. Implement sections 3–5 in the platform with tests; ship one preview release. +3. For each consumer, on a review branch: `./build.ps1 Update -ring preview`, apply section 7, run the full build, compare `Get-GuidePdfPlan` output before and after for every existing download, and review the diff. +4. Generate only downloads declared `generated`; render representative pages including RTL and CJK and record visual approval. +5. KanbanGuides first, then ScrumGuide-ExpansionPack, then remaining consumers. + +## 7. Consumer adoption + +### 7.1 Common steps + +- Move `translators:` into `..yml`; move names recorded only in body text into records; keep the body acknowledgement sections. +- Add `localizedNames` where front matter `author` used a localised spelling; then remove `author:`. +- Normalise roles (3.3); rename `.yaml` data files to `.yml`. +- Create `site/pdf/pdf.yaml` and language files for fonts; remove `mainfont`, `sansfont`, `monofont` and `dir` from front matter. +- Declare `downloads` for every existing PDF (default `supplied`). +- Remove retired PDF scripts and templates. + +### 7.2 KanbanGuides + +- Minimal PDF configuration: `site/pdf/pdf.yaml` (Times New Roman, Arial, Courier New), `pdf.fa.yaml` (HMXRoya), `pdf.ja.yaml` (Noto Serif JP, Noto Sans JP). Removes 3–4 lines from each of 32 translation files. +- Translators: structured for `ja` and `fa` only. Body text only for `es-ES` and `pl` (2025 editions) and `fr` (open-guide-to-kanban 2025.7). None for `es-419` or any 2020 translation. +- `site/hugo.yaml` already uses the current `direction: rtl` key for `fa`; built Persian pages carry `dir="rtl"`. +- `site/layouts/index.html` shows `.Params.author` from the latest edition; switch it to `functions/get-contributors.html` creators before removing `author`. +- Remove `.agents/skills/guide.genpdfs/cover-page.tex` once the platform default replaces it. +- `min` is a test language; confirm it stays excluded from production. + +### 7.3 ScrumGuide-ExpansionPack + +- Retire `scripts/Create-GuidePDFs.ps1`, `GuidePdfLanguage.ps1` and its test, `callouts*.lua`, `callouts-header.tex` and `cover-page.tex` after the callouts recipe is in the platform defaults. +- `site/hugo.yaml` uses the deprecated `languageDirection` key for `fa` and `tlh`; rename to `direction`. +- `pdf.ja.yaml` must set CJK fonts; current Japanese PDFs would need them for any regeneration. +- `cover.tagline: Based on the Scrum Guide 2020` at site level replaces fixed cover text. +- Three filename conventions exist: `scrum-guide-expansion-pack..pdf` (2025.6, does not match guide identifier `scrum-guide-expanded`, plus an `en-us` variant), `...pdf` (2026.1). All preserved via `downloads`. +- `strategy-as-an-empirical-capability/2026.1/pdf/strategy.2026.1.en.pdf` appears to be a stray duplicate; confirm before declaring it. +- Translators: structured for 2025.6 `es`, `fa`, `ja`, `ro`; body only for `pl`; none for `it` (six guides), `nl`, `pt`, `de`, `tlh`. `es` lists Marc Lluva twice. Roles include `contributor` and `translation reviewer`. Japanese translator names exist only in Japanese script. +- Authors: front matter and data disagree for `product-thinking` (three authors vs two creators and one contributor), `holistic-testing` (extra contributor) and `scrum-on-one-page` (no front-matter author). Author order differs between front matter and data; weights must reproduce the intended order. +- `planguage` has no contributions file. +- Three data files use `.yaml`. +- 2026.1 translations of `scrum-guide-expanded` other than `it` are empty and cannot produce a PDF. +- `tlh` is a test language with a published PDF; confirm production exclusion. +- The guide identifier `emergent-strategy-and-depoyment` is misspelt; it is part of live URLs and is not changed here. + +## 8. Decisions + +Recommendations were accepted when implementation was requested on 2026-09-23. + +| # | Decision | Implemented | +|---|---|---| +| D1 | PDF configuration location | `/pdf/` | +| D2 | Authors source | Data file `role: creator`; front-matter `author` retired | +| D3 | Roles shown as contributors on the cover | `contributor`, `reviewer`; `involved` excluded (configurable with `cover.contributorRoles`) | +| D4 | Translation reviewers on the cover | Not by default; `cover.translatorRoles: [translator, reviewer]` adds them to the translators list (see section 9) | +| D5 | Localised names | `localizedNames` per record, in whichever file holds the record | +| D6 | Keep per-invocation PDF overrides | No; committed configuration only | +| D7 | Paper-size variants | Per-download override in `downloads` | +| D8 | New PDF filename pattern | `...pdf` | +| D9 | Default part order | cover, licence, body, back | +| D10 | Licence page source | Platform default text parameterised by a `licence` key in `pdf.yaml`; body licence paragraphs unchanged | + +## 9. Implementation notes + +Differences from the original draft, found while implementing and checking real output (English, Persian and Japanese PDFs generated with Pandoc 3.10 and MiKTeX XeLaTeX and inspected page by page): + +- Added `CJKmainfont`, `CJKsansfont` and `CJKmonofont`: without `CJKmainfont` Pandoc does not load xeCJK and Japanese lines do not break. +- Added the `licence` key (D10) and per-download `geometry`, `fontsize` and `watermark` overrides. +- The licence text appears on the licence page only, not on the cover and back page as first drafted. +- Removed the unused `pdf_page_label`; added translatable callout titles. +- Added the fixed `body-start.tex` and `rtl.tex` includes (section 4.3) and left-to-right wrapping of Latin text in right-to-left covers and headers; the running header mirrors for right-to-left documents. +- D4: translation reviewers are not a separate cover group. They can be listed with translators through `cover.translatorRoles`; the website still shows the whole translation team. +- Contributor warnings apply only to sites that keep `data/contributions`, so sites without contributor data are not asked for it. +- Core exposes `Get-GuideCredits` (resolved credits) and `Get-GuidePdfDeclaredDownloads` (used by discovery). Discovery records `wrapper.languageDirections`, added to the site-policy schema. diff --git a/examples/reference-guide-site/content/Guide1/2020.12/index.md b/examples/reference-guide-site/content/Guide1/2020.12/index.md index 52867902..e39bf94c 100644 --- a/examples/reference-guide-site/content/Guide1/2020.12/index.md +++ b/examples/reference-guide-site/content/Guide1/2020.12/index.md @@ -4,12 +4,7 @@ description: Comprehensive Guide 1 for best practices date: 2020-12-01T09:00:00Z keywords: - Guide 1 -author: - - Jane Smith type: guide -mainfont: "Times New Roman" -sansfont: "Arial" -monofont: "Courier New" sitemap: priority: 0.6 --- diff --git a/examples/reference-guide-site/content/Guide1/2020.12/index.min.md b/examples/reference-guide-site/content/Guide1/2020.12/index.min.md index e42e04ca..6b0634fd 100644 --- a/examples/reference-guide-site/content/Guide1/2020.12/index.min.md +++ b/examples/reference-guide-site/content/Guide1/2020.12/index.min.md @@ -8,14 +8,8 @@ date: 2020-12-01T09:00:00Z keywords: - Guide 1 -author: - - Jane Banana Smith - - Anonymous Banana Author type: guide -mainfont: "Times New Banana" -sansfont: "Ari-Banana" -monofont: "Courier Peel" translationDraft: true sitemap: priority: 0.6 diff --git a/examples/reference-guide-site/content/Guide1/2020.7/index.md b/examples/reference-guide-site/content/Guide1/2020.7/index.md index 10051be6..4ddd4d66 100644 --- a/examples/reference-guide-site/content/Guide1/2020.7/index.md +++ b/examples/reference-guide-site/content/Guide1/2020.7/index.md @@ -4,13 +4,7 @@ description: This document aims to be a unifying reference for the community by date: 2020-07-01T09:00:00Z keywords: - Guide 1 -author: - - Jane Smith - - Anonymous Author type: guide -mainfont: "Times New Roman" -sansfont: "Arial" -monofont: "Courier New" sitemap: priority: 0.6 aliases: diff --git a/examples/reference-guide-site/content/Guide1/2020.7/index.min.md b/examples/reference-guide-site/content/Guide1/2020.7/index.min.md index 1d5bfcab..7ed75fd6 100644 --- a/examples/reference-guide-site/content/Guide1/2020.7/index.min.md +++ b/examples/reference-guide-site/content/Guide1/2020.7/index.min.md @@ -8,14 +8,8 @@ date: 2020-07-01T09:00:00Z keywords: - Guide 1 -author: - - Jane Banana Smith - - Anonymous Banana Author type: guide -mainfont: "Times New Banana" -sansfont: "Ari-Banana" -monofont: "Courier Peel" sitemap: priority: 0.6 diff --git a/examples/reference-guide-site/content/Guide1/2025.5/index.md b/examples/reference-guide-site/content/Guide1/2025.5/index.md index 7ace038c..dda0bbb8 100644 --- a/examples/reference-guide-site/content/Guide1/2025.5/index.md +++ b/examples/reference-guide-site/content/Guide1/2025.5/index.md @@ -6,13 +6,7 @@ version: 2025.5 keywords: - Guide 1 - Best Practices -author: - - Jane Smith - - Anonymous Author type: guide -mainfont: "Times New Roman" -sansfont: "Arial" -monofont: "Courier New" sitemap: priority: 0.6 guide_whatis: | diff --git a/examples/reference-guide-site/content/Guide1/2025.5/index.min.md b/examples/reference-guide-site/content/Guide1/2025.5/index.min.md index 36d4f3b5..ac9daf1f 100644 --- a/examples/reference-guide-site/content/Guide1/2025.5/index.min.md +++ b/examples/reference-guide-site/content/Guide1/2025.5/index.min.md @@ -8,14 +8,8 @@ version: 2025.5 keywords: - Guide 1 -author: - - Jane Banana Smith - - Anonymous Banana Author type: guide -mainfont: "Times New Banana" -sansfont: "Ari-Banana" -monofont: "Courier Peel" sitemap: priority: 0.6 diff --git a/examples/reference-guide-site/content/Guide2/2025.7/index.md b/examples/reference-guide-site/content/Guide2/2025.7/index.md index 8070cf3f..eab168e1 100644 --- a/examples/reference-guide-site/content/Guide2/2025.7/index.md +++ b/examples/reference-guide-site/content/Guide2/2025.7/index.md @@ -4,14 +4,9 @@ short_title: Guide 2 description: Guide 2 is a free, community-driven reference for applying advanced practices in knowledge work. It defines the core practices and metrics necessary to improve flow, optimize value delivery, and enhance team sustainability. This guide supports scalable implementations across diverse industries and complements other agile, lean, and flow-based approaches. keywords: - Guide 2 -author: - - Jane Smith date: 2025-07-02T09:00:00Z type: guide forked_from: guide1/2025.5 -mainfont: "Times New Roman" -sansfont: "Arial" -monofont: "Courier New" sitemap: priority: 1.0 aliases: diff --git a/examples/reference-guide-site/content/Guide2/2025.7/index.min.md b/examples/reference-guide-site/content/Guide2/2025.7/index.min.md index 3dd68028..9b02815c 100644 --- a/examples/reference-guide-site/content/Guide2/2025.7/index.min.md +++ b/examples/reference-guide-site/content/Guide2/2025.7/index.min.md @@ -7,14 +7,9 @@ description: > Works with Agiley, Lean-y, and flowy-wowy ways. All da bananas welcome! 🍌 keywords: - Guide 2 -author: - - Johnny Banana date: 2025-07-02T09:00:00Z type: guide forked_from: guide-1/2025.5 -mainfont: "Times New Banana" -sansfont: "Ari-Banana" -monofont: "Courier Peel" sitemap: priority: 1.0 aliases: diff --git a/examples/reference-guide-site/data/contributions/guide1.min.yml b/examples/reference-guide-site/data/contributions/guide1.min.yml new file mode 100644 index 00000000..52728884 --- /dev/null +++ b/examples/reference-guide-site/data/contributions/guide1.min.yml @@ -0,0 +1,8 @@ +# Minionese translation team for Guide 1. Roles: translator, reviewer. +- name: Banana Translator + role: translator + contributions: + - "2020.7" + - "2020.12" + - "2025.5" + weight: 1 diff --git a/examples/reference-guide-site/data/contributions/guide1.yml b/examples/reference-guide-site/data/contributions/guide1.yml index 70220059..89d2cccd 100644 --- a/examples/reference-guide-site/data/contributions/guide1.yml +++ b/examples/reference-guide-site/data/contributions/guide1.yml @@ -1,20 +1,25 @@ -# Contributions Data -# This file contains information about all contributors to the Guide 1 - -# All contributors in a flat list -- name: Martin Hinshelwood - gravatarHash: a9a55b4384e0420e376f441384d0c13fdadb9d39e72892ac60c3e89c3079d10d - githubUsername: mrhinsh - url: https://nkdagility.com/company/people/martin-hinshelwood/ +# Contributors to Guide 1. Authors are the records with role: creator. +# Roles: creator, contributor, reviewer, involved. Translation teams live in guide1..yml. +- name: Jane Smith + role: creator contributions: - "2020.7" - "2020.12" - "2025.5" - - "2025.7" - role: contributor - weight: 100 + weight: 1 founder: true -- name: Martin Hinshelwood 2 + localizedNames: + min: Jane Banana Smith +- name: Anonymous Author + role: creator + contributions: + - "2020.7" + - "2025.5" + weight: 2 + founder: true + localizedNames: + min: Anonymous Banana Author +- name: Martin Hinshelwood gravatarHash: a9a55b4384e0420e376f441384d0c13fdadb9d39e72892ac60c3e89c3079d10d githubUsername: mrhinsh url: https://nkdagility.com/company/people/martin-hinshelwood/ @@ -22,7 +27,6 @@ - "2020.7" - "2020.12" - "2025.5" - - "2025.7" role: contributor weight: 100 - founder: true \ No newline at end of file + founder: true diff --git a/examples/reference-guide-site/data/contributions/guide2.min.yml b/examples/reference-guide-site/data/contributions/guide2.min.yml new file mode 100644 index 00000000..60cacbb7 --- /dev/null +++ b/examples/reference-guide-site/data/contributions/guide2.min.yml @@ -0,0 +1,6 @@ +# Minionese translation team for Guide 2. Roles: translator, reviewer. +- name: Banana Translator + role: translator + contributions: + - "2025.7" + weight: 1 diff --git a/examples/reference-guide-site/data/contributions/guide2.yml b/examples/reference-guide-site/data/contributions/guide2.yml index 63c3480a..f1bbcd77 100644 --- a/examples/reference-guide-site/data/contributions/guide2.yml +++ b/examples/reference-guide-site/data/contributions/guide2.yml @@ -1,27 +1,18 @@ -# Contributors to the Guide 2 -# This file contains information about contributors to the original Guide 2 - -# Add contributors specific to the Guide 2 here -# Example structure: -# - name: Contributor Name -# githubUsername: username -# url: https://www.linkedin.com/in/profile/ -# contributions: -# - 2020.07 -# - 2020.12 -# - 2025.5 -# role: contributor -# weight: 100 -# Contributors to the Guide 2 -# This file contains information about contributors to the original Guide 2 +# Contributors to Guide 2. Authors are the records with role: creator. +# Roles: creator, contributor, reviewer, involved. Translation teams live in guide2..yml. +- name: Jane Smith + role: creator + contributions: + - "2025.7" + weight: 1 + founder: true + localizedNames: + min: Johnny Banana - name: Martin Hinshelwood gravatarHash: a9a55b4384e0420e376f441384d0c13fdadb9d39e72892ac60c3e89c3079d10d githubUsername: mrhinsh url: https://nkdagility.com/company/people/martin-hinshelwood/ contributions: - - "2020.7" - - "2020.12" - - "2025.5" - "2025.7" role: contributor weight: 100 diff --git a/examples/reference-guide-site/i18n/en.yaml b/examples/reference-guide-site/i18n/en.yaml index 7b63b805..e539729a 100644 --- a/examples/reference-guide-site/i18n/en.yaml +++ b/examples/reference-guide-site/i18n/en.yaml @@ -202,6 +202,9 @@ - id: contributors_label translation: "Contributors" +- id: translators_label + translation: "Translators" + - id: contributors_description translation: "The contributors listed below are a collection of all contributors across all guides and versions." diff --git a/examples/reference-guide-site/i18n/min.yaml b/examples/reference-guide-site/i18n/min.yaml index 0e57d8b6..f76262f4 100644 --- a/examples/reference-guide-site/i18n/min.yaml +++ b/examples/reference-guide-site/i18n/min.yaml @@ -491,6 +491,9 @@ - id: contributors_label translation: "Helper Minions" + +- id: translators_label + translation: "Translatey Minions" - id: download_table_contributed_by translation: "Made by da Helpers" diff --git a/examples/reference-guide-site/pdf/README.md b/examples/reference-guide-site/pdf/README.md new file mode 100644 index 00000000..956833ed --- /dev/null +++ b/examples/reference-guide-site/pdf/README.md @@ -0,0 +1,14 @@ +# PDF configuration + +Generated guide PDFs are configured here, outside `content/` so Hugo does not publish these files. Settings are layered; the most specific wins: + +| Level | Folder | +|---|---| +| Platform default | OpenGuidePlatform Core `PdfPublishing/templates/` | +| Site | `pdf/` | +| Guide | `pdf//` | +| Edition | `pdf///` | + +Each folder may contain `pdf.yaml` (settings, merged key by key), `cover.tex`, `licence.tex`, `back.tex`, `page-header.tex`, `page-footer.tex` and `style.tex` (Pandoc templates, most specific file wins), `filters/*.lua` with an optional companion `filters/.tex` preamble, and `images/`. Add `.` before the extension (`pdf.fa.yaml`, `cover.ja.tex`) for one language. + +Only downloads declared in an edition's `pdf.yaml` with `handling: generated` are ever generated; every other PDF is preserved as supplied. Cover credits come from `data/contributions/.yml` (role `creator` = authors) and `data/contributions/..yml` (translators). Do not put fonts, `dir`, `author` or `translators` in guide front matter. diff --git a/examples/reference-guide-site/pdf/pdf.ja.yaml b/examples/reference-guide-site/pdf/pdf.ja.yaml new file mode 100644 index 00000000..7d2cd4b5 --- /dev/null +++ b/examples/reference-guide-site/pdf/pdf.ja.yaml @@ -0,0 +1,5 @@ +# Japanese needs CJK fonts; CJKmainfont also enables Japanese line breaking. +mainfont: Noto Serif JP +sansfont: Noto Sans JP +monofont: Noto Sans JP +CJKmainfont: Noto Serif JP diff --git a/examples/reference-guide-site/pdf/pdf.yaml b/examples/reference-guide-site/pdf/pdf.yaml new file mode 100644 index 00000000..0809a131 --- /dev/null +++ b/examples/reference-guide-site/pdf/pdf.yaml @@ -0,0 +1,5 @@ +# Site PDF settings. Override per guide (pdf//pdf.yaml), per edition +# (pdf///pdf.yaml) and per language (pdf..yaml). +mainfont: Times New Roman +sansfont: Arial +monofont: Courier New diff --git a/system/OpenGuidePlatform.Agents.Integration/instructions/guide-site.md b/system/OpenGuidePlatform.Agents.Integration/instructions/guide-site.md index cb150baf..2ac84695 100644 --- a/system/OpenGuidePlatform.Agents.Integration/instructions/guide-site.md +++ b/system/OpenGuidePlatform.Agents.Integration/instructions/guide-site.md @@ -6,6 +6,7 @@ Use ./build.ps1 -Stage Serve -Target local for local development. Run a full bui Preserve the bespoke wrapper, supplied/protected PDFs and deliberate multilingual guide structure. Do not put lang in Hugo front matter; PDF generation passes Pandoc language metadata separately. +Guide credits live in data/contributions: .yml for creators (the authors) and contributors, ..yml for each translation team. PDF settings, templates and filters live in /pdf. Never put author, translators, mainfont, sansfont, monofont or dir in guide front matter. Never enable permanently excluded languages in production. Do not modify generated platform adapters, skills or the installation record by hand. Workflow callers are site-owned. Preserve site triggers, inputs and secrets; use the coordinated update to change OGP release references and regenerate the Actions lockfile. diff --git a/system/OpenGuidePlatform.Agents.Integration/skills/guide.contributions/SKILL.md b/system/OpenGuidePlatform.Agents.Integration/skills/guide.contributions/SKILL.md index 727a30ce..f26bbdd7 100644 --- a/system/OpenGuidePlatform.Agents.Integration/skills/guide.contributions/SKILL.md +++ b/system/OpenGuidePlatform.Agents.Integration/skills/guide.contributions/SKILL.md @@ -1,12 +1,14 @@ --- name: guide.contributions -description: "Create guide contributor YAML or apply a reviewed update to one existing contributor." +description: "Create guide or translation-team contributor YAML, apply a reviewed update to one existing contributor, or resolve an edition's credits." --- -Read [Core usage](../USAGE.md), load the consumer policy, and select the declared guide. Use `New-GuideContributions -WorkspaceRoot $WorkspaceRoot -Policy $policy -GuideId $GuideId -Contributors $Contributors` for a new file. Existing .yml and .yaml filenames are preserved; two matching files are ambiguous and require reconciliation. +Read [Core usage](../USAGE.md), load the consumer policy, and select the declared guide. Contributor data is the only source of guide credits: `data/contributions/.yml` holds the guide's own people (roles `creator`, `contributor`, `reviewer`, `involved`; creators are the authors) and `data/contributions/..yml` holds one translation team (roles `translator`, `reviewer`). Every record needs `name`, `role` and `contributions` (the edition identifiers it applies to); `weight` orders records and `localizedNames` maps a language code to the name shown in that language. Do not put `author` or `translators` in guide front matter; Prepare blocks them. -Records need a name and non-empty role. Preserve site-specific roles such as reviewer, supplied URLs, edition references and other contributor metadata; do not invent affiliations or contributions. Use `Get-GuideGravatar` only for an address the user supplied for that purpose. +Use `New-GuideContributions -WorkspaceRoot $WorkspaceRoot -Policy $policy -GuideId $GuideId -Contributors $Contributors [-Language $Language]` for a new file; `-Language` creates the translation-team file. Existing .yml and .yaml filenames are preserved; two matching files are ambiguous and require reconciliation. New files use .yml. -For an authorized update, read the original bytes and SHA-256 and prepare CandidateYaml with the minimal requested diff. Preserve comments, formatting, contributor order and every unselected record. Apply with `Update-GuideContributions -WorkspaceRoot $WorkspaceRoot -Policy $policy -GuideId $GuideId -ContributorName $Name -ExpectedSha256 $OriginalHash -CandidateYaml $CandidateYaml`. The command validates semantic scope and writes the candidate text exactly; it does not reconstruct formatting for you. Review the diff for comment/format preservation. +Preserve supplied URLs, edition references and other contributor metadata; do not invent affiliations, contributions or name spellings. Use `Get-GuideGravatar` only for an address the user supplied for that purpose. When moving names out of guide body text into records, copy them exactly and keep the body acknowledgement. -The update must select exactly one existing name; it cannot rename, add, remove or reorder contributors. A stale hash means re-read and review the changed file, never refresh the hash blindly to bypass the refusal. The cooperative lock cannot prevent edits by programs that ignore it. Use WhatIf to inspect the operation and run the consumer build after an authorized change. Report the changed path and verification result. \ No newline at end of file +For an authorized update, read the original bytes and SHA-256 and prepare CandidateYaml with the minimal requested diff. Preserve comments, formatting, contributor order and every unselected record. Apply with `Update-GuideContributions -WorkspaceRoot $WorkspaceRoot -Policy $policy -GuideId $GuideId -ContributorName $Name -ExpectedSha256 $OriginalHash -CandidateYaml $CandidateYaml [-Language $Language]`. The command validates semantic scope and writes the candidate text exactly; it does not reconstruct formatting for you. Review the diff for comment/format preservation. + +The update must select exactly one existing name; it cannot rename, add, remove or reorder contributors. A stale hash means re-read and review the changed file, never refresh the hash blindly to bypass the refusal. The cooperative lock cannot prevent edits by programs that ignore it. Use WhatIf to inspect the operation and run the consumer build after an authorized change; Prepare reports invalid roles, unknown editions, duplicates and missing creators or translators. `Get-GuideCredits` shows the authors, contributors and translators a PDF cover will use. Report the changed path and verification result. diff --git a/system/OpenGuidePlatform.Agents.Integration/skills/guide.genpdfs/SKILL.md b/system/OpenGuidePlatform.Agents.Integration/skills/guide.genpdfs/SKILL.md index 7cca5224..3c03ecf1 100644 --- a/system/OpenGuidePlatform.Agents.Integration/skills/guide.genpdfs/SKILL.md +++ b/system/OpenGuidePlatform.Agents.Integration/skills/guide.genpdfs/SKILL.md @@ -1,12 +1,14 @@ --- name: guide.genpdfs -description: "Plan, generate or replace a declared generated guide PDF using declared filenames, explicit language metadata and installed tools." +description: "Plan, generate or replace a declared generated guide PDF from the site's committed PDF configuration, contributor data and installed tools." --- -Read [Core usage](../USAGE.md). Select guide, edition, language and the exact download path declared in policy. Only generated downloads are eligible; supplied/protected resources are preserved. +Read [Core usage](../USAGE.md). Select guide, edition, language and the exact download path. Only downloads declared `handling: generated` in `/pdf///pdf.yaml` are eligible; every other PDF is supplied or protected and is preserved. -Use `Get-GuidePdfPlan` to inspect source, destination, arguments, fonts and fingerprints. Use `Get-GuidePdfToolchain` for diagnostics, then `New-GuidePdf` with the same selections. HeaderPaths, LuaFilterPaths and FontOverrides are explicit choices; preserve the consumer's approved PDF recipe. Do not silently substitute fonts or install packages. The command passes the filename/default language to Pandoc metadata and never needs lang in Hugo front matter. +The recipe is committed configuration, never per-run choices. Settings, templates and filters are layered: platform defaults, then `/pdf/`, `/pdf//` and `/pdf///`, with `.` variants (`pdf.fa.yaml`, `cover.ja.tex`) at any level. `pdf.yaml` keys merge; `cover.tex`, `licence.tex`, `back.tex`, `page-header.tex`, `page-footer.tex` and `style.tex` are Pandoc templates replaced by the most specific file; `filters/.lua` replaces a same-named filter and may have a companion `filters/.tex` preamble. Cover credits come from contributor data (see guide.contributions) and labels from the site i18n `pdf_*` ids. Fonts and direction never come from front matter; Japanese needs `CJKmainfont`. + +Use `Get-GuidePdfPlan` to inspect source, destination, resolved recipe files, settings, cover metadata, arguments, fonts and fingerprints. Use `Get-GuidePdfToolchain` for diagnostics, then `New-GuidePdf` with the same selections. Change the look by editing the site's PDF configuration in a reviewed change, not by passing options. Do not silently substitute fonts or install packages. The command passes the filename/default language to Pandoc metadata and never needs lang in Hugo front matter. For an authorized replacement, pass the reviewed existing PDF SHA-256 as ExpectedOutputSha256 to New-GuidePdf. A stale hash requires fresh review, not deleting the old file or blindly refreshing the hash. Failed generation preserves the previous PDF. Test-GuidePdfCache accepts the current plan, prior receipt and observed toolchain. Reuse requires an EnvironmentSha256 covering approved fonts, TeX packages and indirect resources; without that evidence it refuses reuse. Never invent this digest or use timestamps as proof of freshness. Cooperative locks do not prevent other editors ignoring them. -After generation, inspect the actual PDF and render representative pages, including RTL/CJK cases when applicable. A successful native command or PDF header is not visual approval. Record source/config/toolchain fingerprints and any font/tool warnings; keep published filenames unchanged. +After generation, inspect the actual PDF and render representative pages, including the cover and RTL/CJK cases when applicable. A successful native command or PDF header is not visual approval. Record source/config/toolchain fingerprints and any font/tool warnings; keep published filenames unchanged. diff --git a/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/components/guide/guide-translators.html b/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/components/guide/guide-translators.html index 6e49bd7b..4d0e89a8 100644 --- a/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/components/guide/guide-translators.html +++ b/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/components/guide/guide-translators.html @@ -1,4 +1,8 @@ -{{ $translators := .Params.translators }} +{{- $version := "" -}} +{{- range split .Path "/" -}} + {{- if and (ne . "") (findRE `^\d{4}\.\d+$` .) -}}{{- $version = . -}}{{- end -}} +{{- end -}} +{{ $translators := partial "functions/get-translators.html" (dict "guide" .Section "version" $version "language" .Language.Lang) }} {{ if $translators }}
diff --git a/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/components/translations/community-translations2.html b/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/components/translations/community-translations2.html index 1a161731..75dfb23f 100644 --- a/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/components/translations/community-translations2.html +++ b/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/components/translations/community-translations2.html @@ -73,6 +73,8 @@

{{ i18n "download_community_translations" . }}

{{- if .ReadOnline }} {{- $pageObj = $.Site.GetPage .RelPermalink }} {{- end }} + {{/* Translators come from data/contributions/..yml, so PDF-only translations are credited too */}} + {{- $translators := partial "functions/get-translators.html" (dict "guide" $guidePage.Section "version" .Version "language" .Language) }} @@ -91,9 +93,9 @@

{{ i18n "download_table_translations_by" $ }}:
- {{/* Use page object translators if available, otherwise fall back to community contributors */}} - {{- if and $pageObj $pageObj.Params.translators }} - {{- range $index, $translator := $pageObj.Params.translators }} + {{/* Credited translators, otherwise the community contributors label */}} + {{- if $translators }} + {{- range $index, $translator := $translators }} {{- if $index }},{{ end }} {{- if $translator.url }} @@ -159,9 +161,9 @@

{{- end }}
- {{/* Use page object translators if available, otherwise fall back to community contributors */}} - {{- if and $pageObj $pageObj.Params.translators }} - {{- range $index, $translator := $pageObj.Params.translators }} + {{/* Credited translators, otherwise the community contributors label */}} + {{- if $translators }} + {{- range $index, $translator := $translators }} {{- if $index }},{{ end }} {{- if $translator.url }} diff --git a/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/functions/get-contributors.html b/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/functions/get-contributors.html index 69b70e56..c973a84a 100644 --- a/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/functions/get-contributors.html +++ b/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/functions/get-contributors.html @@ -49,4 +49,12 @@ {{- $filtered = slice -}} {{- end -}} -{{- return $filtered -}} +{{- /* Show localizedNames. where a record provides one */ -}} +{{- $language := "" -}} +{{- with .Language -}}{{- $language = .Lang -}}{{- end -}} +{{- $localized := slice -}} +{{- range $filtered -}} + {{- $localized = $localized | append (partial "functions/localize-contributor.html" (dict "record" . "language" $language)) -}} +{{- end -}} + +{{- return $localized -}} diff --git a/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/functions/get-participants.html b/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/functions/get-participants.html index 5aa99573..883c63c0 100644 --- a/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/functions/get-participants.html +++ b/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/functions/get-participants.html @@ -6,7 +6,11 @@ {{ $creators:= $currentPageDefaultLang.Params.creators }} {{ $contributors := $currentPageDefaultLang.Params.contributors }} -{{ $translators:= .Params.translators }} +{{- $version := "" -}} +{{- range split .Path "/" -}} + {{- if and (ne . "") (findRE `^\d{4}\.\d+$` .) -}}{{- $version = . -}}{{- end -}} +{{- end -}} +{{ $translators := partial "functions/get-translators.html" (dict "guide" .Section "version" $version "language" .Language.Lang) }} {{/* Join all participants into a single slice */}} {{ $allParticipants := slice }} diff --git a/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/functions/get-translators.html b/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/functions/get-translators.html new file mode 100644 index 00000000..0a552574 --- /dev/null +++ b/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/functions/get-translators.html @@ -0,0 +1,25 @@ +{{- /* + Purpose: Translation team for one guide edition and language. + Input: dict "guide" (section / data key), "version" (edition id, optional) and "language". + Source: data/contributions/..yml (matched case-insensitively). + Returns: records for the edition, sorted by weight, with name replaced by + localizedNames. when present. +*/ -}} +{{- $guide := lower (string .guide) -}} +{{- $language := lower (string .language) -}} +{{- $version := string (.version | default "") -}} +{{- $records := slice -}} +{{- range $key, $list := hugo.Data.contributions -}} + {{- if eq (lower $key) (printf "%s.%s" $guide $language) -}} + {{- $records = $list -}} + {{- end -}} +{{- end -}} +{{- $result := slice -}} +{{- range $records -}} + {{- $editions := slice -}} + {{- range .contributions -}}{{- $editions = $editions | append (string .) -}}{{- end -}} + {{- if or (eq $version "") (in $editions $version) -}} + {{- $result = $result | append (partial "functions/localize-contributor.html" (dict "record" . "language" $language)) -}} + {{- end -}} +{{- end -}} +{{- return (sort $result "weight" "asc") -}} diff --git a/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/functions/localize-contributor.html b/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/functions/localize-contributor.html new file mode 100644 index 00000000..6a7a5707 --- /dev/null +++ b/system/OpenGuidePlatform.Hugo.Guides/layouts/_partials/functions/localize-contributor.html @@ -0,0 +1,17 @@ +{{- /* + Purpose: Display a contributor record in one language. + Input: dict "record" (contributor map) and "language". + Returns: the record, with name replaced by localizedNames. when present. +*/ -}} +{{- $record := .record -}} +{{- $language := lower (string .language) -}} +{{- $name := "" -}} +{{- with $record.localizedNames -}} + {{- range $key, $value := . -}} + {{- if and (eq (lower $key) $language) $value -}}{{- $name = $value -}}{{- end -}} + {{- end -}} +{{- end -}} +{{- if $name -}} + {{- $record = merge $record (dict "name" $name) -}} +{{- end -}} +{{- return $record -}} diff --git a/system/OpenGuidePlatform.PowerShell.Core/Assessment/Get-GuideAssessment.ps1 b/system/OpenGuidePlatform.PowerShell.Core/Assessment/Get-GuideAssessment.ps1 index ee196899..dddd8acd 100644 --- a/system/OpenGuidePlatform.PowerShell.Core/Assessment/Get-GuideAssessment.ps1 +++ b/system/OpenGuidePlatform.PowerShell.Core/Assessment/Get-GuideAssessment.ps1 @@ -52,6 +52,7 @@ function Get-GuideAssessment { }else{Add-Finding $translation.FindingCode translation $subject "Declared $($translation.Intent) content is not ready (body: $($translation.Body))." 'Restore the required body/resource or review the declared publication intent; preserve intentional PDF-only and fallback states.'} } if($translation.DeprecatedLang){Add-Finding DEPRECATED_LANG translation $subject 'The document contains deprecated lang front matter.' 'Remove lang from Hugo front matter; pass the filename/default language through Pandoc metadata.'} + if(@($translation.RetiredKeys).Count){Add-Finding FRONT_MATTER_RETIRED_KEY translation $subject "Front matter contains retired keys: $($translation.RetiredKeys -join ', ')." 'Move authors and translators to data/contributions/[.].yml and PDF fonts to pdf/pdf[.].yaml, then remove these keys; direction comes from the Hugo language configuration.'} foreach($download in $translation.Downloads){if(-not $download.Exists){Add-Finding DOWNLOAD_MISSING download "$subject/$($download.Path)" 'A declared download is missing.' 'Restore supplied/protected downloads; generate only resources declared generated.' $(if($download.Handling -eq 'generated'){'warning'}else{'blocker'})}} [ordered]@{language=$translation.Language;state=$translation.State;body=$translation.Body;downloads=@($translation.Downloads|ForEach-Object {[ordered]@{path=$_.Path;handling=$_.Handling}})} }) @@ -60,6 +61,13 @@ function Get-GuideAssessment { }) [ordered]@{id=$guide.id;editions=$editions} }) + # Contributor records and PDF configuration are site-wide source conventions. + $conventionScopes=@{CONTRIBUTOR_FILE_UNKNOWN='guide';CONTRIBUTOR_FILE_AMBIGUOUS='guide';CONTRIBUTOR_RECORD_INVALID='guide';CONTRIBUTOR_EDITION_UNKNOWN='guide';CREATORS_MISSING='edition';TRANSLATORS_MISSING='translation';PDF_SETTINGS_INVALID='download';PDF_LABEL_MISSING='wrapper'} + try { + foreach($finding in @(Get-GuideContributorFindings $WorkspaceRoot $Policy)+@(Get-GuidePdfSettingFindings $WorkspaceRoot $Policy)){ + Add-Finding $finding.Code $conventionScopes[$finding.Code] $finding.Subject $finding.Message $finding.Remediation $finding.Severity + } + } catch { Add-Finding SOURCE_CONVENTIONS_FAILED platform $Policy.siteId $_.Exception.Message 'Correct the contributor data or PDF settings and rerun Prepare.' } $policyJson=$Policy|ConvertTo-Json -Depth 100 -Compress [ordered]@{schemaVersion=1;sourceCommit=$SourceCommit;platformVersion=$PlatformVersion;policyDigest=[Convert]::ToHexString([Security.Cryptography.SHA256]::HashData([Text.Encoding]::UTF8.GetBytes($policyJson))).ToLowerInvariant();target=$Target;stage='Prepare';outcome=if(@($findings|Where-Object severity -eq blocker).Count){'fail'}else{'pass'};findings=@($findings.ToArray());inventory=[ordered]@{wrapper=[ordered]@{state=$wrapperState;languages=@($Languages)};guides=$guides}} } \ No newline at end of file diff --git a/system/OpenGuidePlatform.PowerShell.Core/Contracts/site-policy.schema.json b/system/OpenGuidePlatform.PowerShell.Core/Contracts/site-policy.schema.json index d798aadb..68aab0a2 100644 --- a/system/OpenGuidePlatform.PowerShell.Core/Contracts/site-policy.schema.json +++ b/system/OpenGuidePlatform.PowerShell.Core/Contracts/site-policy.schema.json @@ -16,6 +16,10 @@ "additionalProperties": false, "properties": { "discovery": { "const": "source" }, + "languageDirections": { + "type": "object", + "additionalProperties": { "enum": ["ltr", "rtl"] } + }, "sourcePath": { "type": "string", "minLength": 1, diff --git a/system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/Get-GuideCredits.ps1 b/system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/Get-GuideCredits.ps1 new file mode 100644 index 00000000..bbf7d6af --- /dev/null +++ b/system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/Get-GuideCredits.ps1 @@ -0,0 +1,147 @@ +$script:GuideContributorRoles=@('creator','contributor','reviewer','involved') +$script:GuideTranslationRoles=@('translator','reviewer') +$script:GuideRetiredFrontMatterKeys=@('author','translators','mainfont','sansfont','monofont','dir') + +function Get-GuideContributionFiles { + # Maps site/data/contributions/[.].(yml|yaml) to declared guides. + param([string]$WorkspaceRoot,[Collections.IDictionary]$Policy) + $relativeDirectory="$($Policy.wrapper.sourcePath)/data/contributions" + $directory=Resolve-GuideWorkspacePath $WorkspaceRoot $relativeDirectory + if(-not [IO.Directory]::Exists($directory)){return @()} + # Script blocks, not ForEach-Object : key access on hashtables honours -WhatIf. + $guideIds=@(foreach($guide in $Policy.guides){$guide.id}) + foreach($file in [IO.Directory]::GetFiles($directory)|Sort-Object){ + $name=[IO.Path]::GetFileName($file) + if($name -notmatch '^(?.+)\.(?ya?ml)$'){continue} + $base=$Matches['base'];$extension=$Matches['extension'] + $guideId=$null;$language=$null + foreach($id in $guideIds|Sort-Object Length -Descending){ + if($base -ieq $id){$guideId=$id;break} + if($base.StartsWith("$id.",[StringComparison]::OrdinalIgnoreCase)){ + $suffix=$base.Substring($id.Length+1) + if($suffix -match '^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$'){$guideId=$id;$language=$suffix;break} + } + } + [pscustomobject]@{Relative="$relativeDirectory/$name";Path=$file;Base=$base;Extension=$extension;GuideId=$guideId;Language=$language} + } +} + +function Read-GuideContributionFile { + param([string]$Path) + Import-Module powershell-yaml -MinimumVersion 0.4.12 -ErrorAction Stop + $text=[IO.File]::ReadAllText($Path).TrimStart([char]0xFEFF) + # Callers wrap the result in @(); records are emitted one by one. + if([string]::IsNullOrWhiteSpace(($text -split "`n"|Where-Object {$_ -notmatch '^\s*#'}) -join '')){return} + $records=ConvertFrom-Yaml $text -ErrorAction Stop + if($records -isnot [Collections.IList]){throw 'Expected a YAML list of contributor records.'} + foreach($record in $records){$record} +} + +function Get-GuideContributorRecords { + param([string]$WorkspaceRoot,[Collections.IDictionary]$Policy,[string]$GuideId,[string]$Language) + $matches=@(Get-GuideContributionFiles $WorkspaceRoot $Policy|Where-Object {$_.GuideId -ceq $GuideId -and "$($_.Language)" -ieq "$Language"}) + if($matches.Count -gt 1){throw "Ambiguous contributor files for $GuideId$(if($Language){".$Language"}): both .yml and .yaml exist."} + if(-not $matches.Count){return [pscustomobject]@{File=$null;Records=@()}} + [pscustomobject]@{File=$matches[0];Records=@(Read-GuideContributionFile $matches[0].Path)} +} + +function ConvertTo-GuideCredit { + param([Collections.IDictionary]$Record,[string]$Language) + $name=[string]$Record['name'] + $localized=$Record['localizedNames'] + if($Language -and $localized -is [Collections.IDictionary]){ + foreach($key in $localized.Keys){if($key -ieq $Language -and -not [string]::IsNullOrWhiteSpace([string]$localized[$key])){$name=[string]$localized[$key]}} + } + $url=if($Record['url']){[string]$Record['url']}elseif($Record['githubUsername']){"https://github.com/$($Record['githubUsername'])"}else{$null} + $credit=[ordered]@{name=$name;role=[string]$Record['role']} + if($url){$credit.url=$url} + $credit +} + +function Select-GuideCredits { + param([object[]]$Records,[string]$EditionId,[string[]]$Roles,[string]$Language) + $selected=@(foreach($record in $Records){ + if($record -isnot [Collections.IDictionary]){continue} + if([string]$record['role'] -notin $Roles){continue} + if(@($record['contributions']|ForEach-Object {[string]$_}) -notcontains $EditionId){continue} + [pscustomobject]@{Weight=$(if($null -ne $record['weight']){[double]$record['weight']}else{100});Name=[string]$record['name'];Record=$record} + }) + @($selected|Sort-Object Weight,Name|ForEach-Object {ConvertTo-GuideCredit $_.Record $Language}) +} + +function Get-GuideCredits { + <# + Resolves the authors, contributors and translators of one guide edition in one + language from site/data/contributions. Authors are records with role creator. + #> + [CmdletBinding()] + param([Parameter(Mandatory)][string]$WorkspaceRoot,[Parameter(Mandatory)][Collections.IDictionary]$Policy, + [Parameter(Mandatory)][string]$GuideId,[Parameter(Mandatory)][string]$EditionId,[Parameter(Mandatory)][string]$Language, + [string[]]$ContributorRoles=@('contributor','reviewer'),[string[]]$TranslatorRoles=@('translator')) + $selection=Get-GuideSelection $Policy $GuideId $EditionId + $base=Get-GuideContributorRecords $WorkspaceRoot $Policy $GuideId + $files=@($base.File|Where-Object {$_}|ForEach-Object Relative) + $translators=@() + if($Language -ine $selection.Edition.sourceLanguage){ + $translation=Get-GuideContributorRecords $WorkspaceRoot $Policy $GuideId $Language + $files+=@($translation.File|Where-Object {$_}|ForEach-Object Relative) + $translators=@(Select-GuideCredits $translation.Records $EditionId $TranslatorRoles $Language) + } + [pscustomobject]@{ + Authors=@(Select-GuideCredits $base.Records $EditionId @('creator') $Language) + Contributors=@(Select-GuideCredits $base.Records $EditionId $ContributorRoles $Language) + Translators=$translators + Files=$files + } +} + +function Get-GuideContributorFindings { + # Source-convention checks for contributor data; returns finding records for Prepare. + param([string]$WorkspaceRoot,[Collections.IDictionary]$Policy) + $findings=[Collections.Generic.List[object]]::new() + function Add($code,$subject,$message,$fix,$severity='blocker'){$findings.Add([pscustomobject]@{Code=$code;Severity=$severity;Subject=$subject;Message=$message;Remediation=$fix})} + # Sites that do not keep contributor data are not asked for it. + if(-not [IO.Directory]::Exists((Resolve-GuideWorkspacePath $WorkspaceRoot "$($Policy.wrapper.sourcePath)/data/contributions"))){return @()} + $files=@(Get-GuideContributionFiles $WorkspaceRoot $Policy) + foreach($group in $files|Group-Object {"$($_.GuideId)|$($_.Language)|$(if($_.GuideId){''}else{$_.Base})"}){ + if($group.Count -gt 1){Add CONTRIBUTOR_FILE_AMBIGUOUS $group.Group[0].Relative 'Both .yml and .yaml contributor files exist for the same guide and language.' 'Keep one file; new files use .yml.'} + } + $creatorEditions=@{} + $translatorKeys=@{} + foreach($file in $files){ + if(-not $file.GuideId){Add CONTRIBUTOR_FILE_UNKNOWN $file.Relative 'The contributor file does not match a declared guide.' 'Name contributor files .yml or ..yml using a declared guide identifier.';continue} + $guide=@($Policy.guides|Where-Object id -CEQ $file.GuideId)[0] + $editionIds=@($guide.editions|ForEach-Object {[string]$_.id}) + if($file.Language){ + $declared=@($guide.editions|ForEach-Object {$edition=$_;$_.translations|Where-Object {$_.language -ine $edition.sourceLanguage}|ForEach-Object {$_.language}}) + if($declared -inotcontains $file.Language){Add CONTRIBUTOR_FILE_UNKNOWN $file.Relative "No edition of $($file.GuideId) declares a $($file.Language) translation." 'Remove the file or add the translation it describes.';continue} + } + try{$records=@(Read-GuideContributionFile $file.Path)}catch{Add CONTRIBUTOR_RECORD_INVALID $file.Relative $_.Exception.Message 'Correct the YAML so the file is a list of contributor records.';continue} + $roles=if($file.Language){$script:GuideTranslationRoles}else{$script:GuideContributorRoles} + $seen=@{} + for($index=0;$index -lt $records.Count;$index++){ + $record=$records[$index];$subject="$($file.Relative)#$($index+1)" + if($record -isnot [Collections.IDictionary]){Add CONTRIBUTOR_RECORD_INVALID $subject 'Expected a contributor mapping.' 'Use name, role and contributions fields.';continue} + if([string]::IsNullOrWhiteSpace([string]$record['name'])){Add CONTRIBUTOR_RECORD_INVALID $subject 'The record has no name.' 'Add the display name.'}else{$subject="$($file.Relative)#$($record['name'])"} + if([string]$record['role'] -cnotin $roles){Add CONTRIBUTOR_RECORD_INVALID $subject "Role '$($record['role'])' is not allowed in this file." "Use one of: $($roles -join ', ')."} + $editions=@($record['contributions']|Where-Object {$null -ne $_}|ForEach-Object {[string]$_}) + if(-not $editions.Count){Add CONTRIBUTOR_RECORD_INVALID $subject 'The record lists no editions in contributions.' 'List the edition identifiers this person contributed to.'} + foreach($edition in $editions){if($edition -cnotin $editionIds){Add CONTRIBUTOR_EDITION_UNKNOWN $subject "Edition '$edition' is not an edition of $($file.GuideId)." 'Use an existing edition identifier.'}} + if($null -ne $record['localizedNames'] -and $record['localizedNames'] -isnot [Collections.IDictionary]){Add CONTRIBUTOR_RECORD_INVALID $subject 'localizedNames must map language codes to names.' 'Use localizedNames: { fa: ... }.'} + $identity=if($record['githubUsername']){"github:$($record['githubUsername'])".ToLowerInvariant()}else{"name:$($record['name'])".ToLowerInvariant()} + if($seen.ContainsKey($identity)){Add CONTRIBUTOR_RECORD_INVALID $subject 'The same person appears more than once in this file.' 'Merge the records; list every edition in one contributions list.'}else{$seen[$identity]=$true} + foreach($edition in $editions){ + if(-not $file.Language -and [string]$record['role'] -ceq 'creator'){$creatorEditions["$($file.GuideId)|$edition"]=$true} + if($file.Language -and [string]$record['role'] -ceq 'translator'){$translatorKeys["$($file.GuideId)|$edition|$($file.Language.ToLowerInvariant())"]=$true} + } + } + } + foreach($guide in $Policy.guides){foreach($edition in $guide.editions){ + if(-not $creatorEditions.ContainsKey("$($guide.id)|$($edition.id)")){Add CREATORS_MISSING "$($guide.id)/$($edition.id)" 'No contributor record with role creator lists this edition.' "Add the authors to data/contributions/$($guide.id).yml with role: creator." warning} + foreach($translation in $edition.translations){ + if($translation.language -ieq $edition.sourceLanguage -or $translation.intent -ne 'web'){continue} + if(-not $translatorKeys.ContainsKey("$($guide.id)|$($edition.id)|$($translation.language.ToLowerInvariant())")){Add TRANSLATORS_MISSING "$($guide.id)/$($edition.id)/$($translation.language)" 'This translation has no translator record.' "Add the translators to data/contributions/$($guide.id).$($translation.language).yml with role: translator." warning} + } + }} + @($findings.ToArray()) +} diff --git a/system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/New-GuideContributions.ps1 b/system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/New-GuideContributions.ps1 index 7e3f1a23..ecbcd492 100644 --- a/system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/New-GuideContributions.ps1 +++ b/system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/New-GuideContributions.ps1 @@ -1,12 +1,14 @@ function New-GuideContributions { [CmdletBinding(SupportsShouldProcess)] - param([Parameter(Mandatory)][string]$WorkspaceRoot,[Parameter(Mandatory)][System.Collections.IDictionary]$Policy,[Parameter(Mandatory)][string]$GuideId,[Parameter(Mandatory)][object[]]$Contributors) - $selection=Resolve-GuideContributionsPath $WorkspaceRoot $Policy $GuideId + param([Parameter(Mandatory)][string]$WorkspaceRoot,[Parameter(Mandatory)][System.Collections.IDictionary]$Policy,[Parameter(Mandatory)][string]$GuideId,[Parameter(Mandatory)][object[]]$Contributors,[string]$Language) + $selection=Resolve-GuideContributionsPath $WorkspaceRoot $Policy $GuideId $Language $relative=$selection.Relative;$path=$selection.Path Assert-GuideWriteAllowed $Policy $relative if ([IO.File]::Exists($path)) { throw 'Contributor file exists; review and edit it rather than replacing it.' } + $roles=if($Language){$script:GuideTranslationRoles}else{$script:GuideContributorRoles} foreach ($contributor in $Contributors) { if ([string]::IsNullOrWhiteSpace($contributor.name) -or [string]::IsNullOrWhiteSpace($contributor.role)) { throw 'Each contributor needs a name and a non-empty role.' } + if ([string]$contributor.role -cnotin $roles) { throw "Role '$($contributor.role)' is not allowed here. Use one of: $($roles -join ', ')." } } Import-Module powershell-yaml -MinimumVersion 0.4.12 -ErrorAction Stop $yaml=ConvertTo-Yaml -Data $Contributors diff --git a/system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/Update-GuideContributions.ps1 b/system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/Update-GuideContributions.ps1 index 957cd21b..f18de93b 100644 --- a/system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/Update-GuideContributions.ps1 +++ b/system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/Update-GuideContributions.ps1 @@ -1,15 +1,13 @@ function Resolve-GuideContributionsPath { - param([string]$WorkspaceRoot,[System.Collections.IDictionary]$Policy,[string]$GuideId) + param([string]$WorkspaceRoot,[System.Collections.IDictionary]$Policy,[string]$GuideId,[string]$Language) if (@($Policy.guides | Where-Object { $_.id -ceq $GuideId }).Count -ne 1) { throw 'Select one declared guide.' } - $base="$($Policy.wrapper.sourcePath)/data/contributions/$GuideId" - $existing=@(foreach($extension in @('yml','yaml')) { - $relative="$base.$extension" - $path=Resolve-GuideWorkspacePath $WorkspaceRoot $relative - if ([IO.File]::Exists($path)) { [pscustomobject]@{Path=$path;Relative=$relative} } - }) + if ($Language -and $Language -notmatch '^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$') { throw "Invalid language: $Language" } + # .yml holds the guide's own contributors; ..yml holds one translation team. + $existing=@(Get-GuideContributionFiles $WorkspaceRoot $Policy | Where-Object { $_.GuideId -ceq $GuideId -and "$($_.Language)" -ieq "$Language" }) if ($existing.Count -gt 1) { throw 'Ambiguous contributor files: both .yml and .yaml exist.' } - if ($existing.Count -eq 1) { return $existing[0] } - [pscustomobject]@{Path=(Resolve-GuideWorkspacePath $WorkspaceRoot "$base.yml");Relative="$base.yml"} + if ($existing.Count -eq 1) { return [pscustomobject]@{Path=(Resolve-GuideWorkspacePath $WorkspaceRoot $existing[0].Relative);Relative=$existing[0].Relative} } + $relative="$($Policy.wrapper.sourcePath)/data/contributions/$GuideId$(if($Language){".$Language"}).yml" + [pscustomobject]@{Path=(Resolve-GuideWorkspacePath $WorkspaceRoot $relative);Relative=$relative} } function Update-GuideContributions { [CmdletBinding(SupportsShouldProcess)] @@ -19,9 +17,10 @@ function Update-GuideContributions { [Parameter(Mandatory)][string]$GuideId, [Parameter(Mandatory)][string]$ContributorName, [Parameter(Mandatory)][ValidatePattern('^[a-fA-F0-9]{64}$')][string]$ExpectedSha256, - [Parameter(Mandatory)][string]$CandidateYaml + [Parameter(Mandatory)][string]$CandidateYaml, + [string]$Language ) - $selection=Resolve-GuideContributionsPath $WorkspaceRoot $Policy $GuideId + $selection=Resolve-GuideContributionsPath $WorkspaceRoot $Policy $GuideId $Language Assert-GuideWriteAllowed $Policy $selection.Relative if (-not [IO.File]::Exists($selection.Path)) { throw 'Contributor file is missing; use the new-file operation.' } $originalBytes=[IO.File]::ReadAllBytes($selection.Path) diff --git a/system/OpenGuidePlatform.PowerShell.Core/GuideInventory/Get-GuideInventory.ps1 b/system/OpenGuidePlatform.PowerShell.Core/GuideInventory/Get-GuideInventory.ps1 index befb8346..b5d327f8 100644 --- a/system/OpenGuidePlatform.PowerShell.Core/GuideInventory/Get-GuideInventory.ps1 +++ b/system/OpenGuidePlatform.PowerShell.Core/GuideInventory/Get-GuideInventory.ps1 @@ -8,11 +8,12 @@ function Get-GuideInventory { $translations=@(foreach ($translation in $edition.translations) { $name=if($translation.language -eq $edition.sourceLanguage){'index.md'}else{"index.$($translation.language).md"} $path=Resolve-GuideWorkspacePath $WorkspaceRoot "$relative/$name" - $body='missing';$frontMatterLang=$false + $body='missing';$frontMatterLang=$false;$retiredKeys=@() if (Test-Path -LiteralPath $path -PathType Leaf) { $document=Read-GuideDocument $path $body=if([string]::IsNullOrWhiteSpace($document.Body)){'empty'}else{'populated'} $frontMatterLang=$document.Metadata.Contains('lang') + $retiredKeys=@($script:GuideRetiredFrontMatterKeys|Where-Object { $document.Metadata.Contains($_) }) } $downloads=@(foreach($download in $translation.downloads){ $file=Resolve-GuideWorkspacePath $WorkspaceRoot "$relative/$($download.path)" @@ -37,7 +38,7 @@ function Get-GuideInventory { } } $state=Get-GuideTranslationState -Intent $translation.intent -Body $body -HasDownload (@($downloads|Where-Object Exists).Count -gt 0) -FallbackAvailable $fallbackAvailable - [pscustomobject]@{Language=$translation.language;Intent=$translation.intent;Source="$relative/$name";State=$state.State;Body=$body;FindingCode=$state.FindingCode;DeprecatedLang=$frontMatterLang;Downloads=$downloads} + [pscustomobject]@{Language=$translation.language;Intent=$translation.intent;Source="$relative/$name";State=$state.State;Body=$body;FindingCode=$state.FindingCode;DeprecatedLang=$frontMatterLang;RetiredKeys=$retiredKeys;Downloads=$downloads} }) [pscustomobject]@{Id=$edition.id;SourceLanguage=$edition.sourceLanguage;Translations=$translations} }) diff --git a/system/OpenGuidePlatform.PowerShell.Core/OpenGuidePlatform.PowerShell.Core.psd1 b/system/OpenGuidePlatform.PowerShell.Core/OpenGuidePlatform.PowerShell.Core.psd1 index eae6f49a..623a230a 100644 --- a/system/OpenGuidePlatform.PowerShell.Core/OpenGuidePlatform.PowerShell.Core.psd1 +++ b/system/OpenGuidePlatform.PowerShell.Core/OpenGuidePlatform.PowerShell.Core.psd1 @@ -4,7 +4,7 @@ GUID='67db96a0-183a-452a-a09a-494526b6cf60' Author='OpenGuidePlatform contributors' PowerShellVersion='7.4' - FunctionsToExport=@('Get-GuideTranslationWork','New-GuideTranslation','Test-GuideTranslation','Set-GuideTranslation','Get-GuideContent','Set-GuideContent','Read-GuideDocument','Get-GuideLegacyAliasTargets','Test-GuideLegacyAliases','Get-GuideForbiddenPaths','Save-GuidePdfReceipt','Get-GuidePdfReceipts','Resolve-GuideWorkspacePath','Get-GuideLanguage','Test-GuideWritePolicy','Get-GuideTranslationState','Get-GuidePolicyFinding','Test-GuidePublicationPolicy','Import-GuidePolicy','Get-GuideInventory','New-GuideTranslationScaffold','Set-GuideWrapperTranslation','Get-GuideGravatar','New-GuideEdition','New-GuideContributions','Update-GuideContributions','Get-GuidePdfPlan','Get-GuidePdfToolchain','New-GuidePdf','Test-GuidePdfCache','Get-GuideWrapperStatus','Get-GuideAssessment','Get-GuideDownloadRequirements','Test-GuideDownloadPublication') + FunctionsToExport=@('Get-GuideTranslationWork','New-GuideTranslation','Test-GuideTranslation','Set-GuideTranslation','Get-GuideContent','Set-GuideContent','Read-GuideDocument','Get-GuideLegacyAliasTargets','Test-GuideLegacyAliases','Get-GuideForbiddenPaths','Save-GuidePdfReceipt','Get-GuidePdfReceipts','Resolve-GuideWorkspacePath','Get-GuideLanguage','Test-GuideWritePolicy','Get-GuideTranslationState','Get-GuidePolicyFinding','Test-GuidePublicationPolicy','Import-GuidePolicy','Get-GuideInventory','New-GuideTranslationScaffold','Set-GuideWrapperTranslation','Get-GuideGravatar','New-GuideEdition','New-GuideContributions','Update-GuideContributions','Get-GuideCredits','Get-GuidePdfDeclaredDownloads','Get-GuidePdfPlan','Get-GuidePdfToolchain','New-GuidePdf','Test-GuidePdfCache','Get-GuideWrapperStatus','Get-GuideAssessment','Get-GuideDownloadRequirements','Test-GuideDownloadPublication') CmdletsToExport=@() VariablesToExport=@() AliasesToExport=@() diff --git a/system/OpenGuidePlatform.PowerShell.Core/OpenGuidePlatform.PowerShell.Core.psm1 b/system/OpenGuidePlatform.PowerShell.Core/OpenGuidePlatform.PowerShell.Core.psm1 index 09ec582e..e61312f0 100644 --- a/system/OpenGuidePlatform.PowerShell.Core/OpenGuidePlatform.PowerShell.Core.psm1 +++ b/system/OpenGuidePlatform.PowerShell.Core/OpenGuidePlatform.PowerShell.Core.psm1 @@ -10,6 +10,8 @@ $script:CoreRoot=$PSScriptRoot . (Join-Path $PSScriptRoot 'ContributorManagement/Get-GuideGravatar.ps1') . (Join-Path $PSScriptRoot 'EditionManagement/New-GuideEdition.ps1') . (Join-Path $PSScriptRoot 'ContributorManagement/New-GuideContributions.ps1') +. (Join-Path $PSScriptRoot 'ContributorManagement/Get-GuideCredits.ps1') +. (Join-Path $PSScriptRoot 'PdfPublishing/Resolve-GuidePdfRecipe.ps1') . (Join-Path $PSScriptRoot 'PdfPublishing/Get-GuidePdfPlan.ps1') . (Join-Path $PSScriptRoot 'ContributorManagement/Update-GuideContributions.ps1') diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Get-GuidePdfPlan.ps1 b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Get-GuidePdfPlan.ps1 index cd0019f5..ed2ffd05 100644 --- a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Get-GuidePdfPlan.ps1 +++ b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Get-GuidePdfPlan.ps1 @@ -1,6 +1,12 @@ function Get-GuidePdfPlan { + <# + Plans one generated PDF. The recipe comes only from committed configuration: + platform defaults, then /pdf, /pdf/ and + /pdf// (see Resolve-GuidePdfRecipe). Cover credits come + from data/contributions and labels from the site i18n catalogues. + #> [CmdletBinding()] - param([Parameter(Mandatory)][string]$WorkspaceRoot,[Parameter(Mandatory)][System.Collections.IDictionary]$Policy,[Parameter(Mandatory)][string]$GuideId,[Parameter(Mandatory)][string]$EditionId,[Parameter(Mandatory)][string]$Language,[Parameter(Mandatory)][string]$DownloadPath,[hashtable]$FontOverrides=@{},[string[]]$HeaderPaths=@(),[string[]]$LuaFilterPaths=@()) + param([Parameter(Mandatory)][string]$WorkspaceRoot,[Parameter(Mandatory)][System.Collections.IDictionary]$Policy,[Parameter(Mandatory)][string]$GuideId,[Parameter(Mandatory)][string]$EditionId,[Parameter(Mandatory)][string]$Language,[Parameter(Mandatory)][string]$DownloadPath) $selection=Get-GuideSelection $Policy $GuideId $EditionId $translations=@($selection.Edition.translations|Where-Object { $_.language -eq $Language }) if ($translations.Count -ne 1) { throw 'Select one declared translation.' } @@ -14,16 +20,108 @@ function Get-GuidePdfPlan { $inputPath=Resolve-GuideWorkspacePath $WorkspaceRoot "$($selection.RelativePath)/$filename" $document=Read-GuideDocument $inputPath if ([string]::IsNullOrWhiteSpace($document.Body)) { throw 'An empty translation has no PDF body to generate.' } + $retired=@(@($script:GuidePdfFontKeys)+@('dir')|Where-Object { $document.Metadata.Contains($_) }) + if ($retired.Count) { throw "PDF settings in front matter are no longer read ($($retired -join ', ')). Move them to $($Policy.wrapper.sourcePath)/pdf/pdf.yaml or pdf..yaml." } $resolvedLanguage=Get-GuideLanguage $filename $selection.Edition.sourceLanguage - $arguments=@($inputPath,'--pdf-engine=xelatex','--pdf-engine-opt=-interaction=nonstopmode','--metadata',"lang=$resolvedLanguage",'--metadata','keywords=') - $resources=@() - foreach ($path in $HeaderPaths) { $resolved=Resolve-GuideWorkspacePath $WorkspaceRoot $path;if(-not [IO.File]::Exists($resolved)){throw "Header missing: $path"};$resources+=$resolved;$arguments+=@('--include-in-header',$resolved) } - foreach ($path in $LuaFilterPaths) { $resolved=Resolve-GuideWorkspacePath $WorkspaceRoot $path;if(-not [IO.File]::Exists($resolved)){throw "Filter missing: $path"};$resources+=$resolved;$arguments+=@('--lua-filter',$resolved) } - $fonts=@{} - foreach($key in @('mainfont','sansfont','monofont')) { if($document.Metadata.Contains($key)){$fonts[$key]=$document.Metadata[$key]} } - foreach($key in $FontOverrides.Keys) { if($key -notin @('mainfont','sansfont','monofont')){throw "Unsupported font key: $key"};$fonts[$key]=$FontOverrides[$key];$arguments+=@('-V',"$key=$($FontOverrides[$key])") } - $fingerprints=@(foreach($path in @($inputPath)+$resources){[pscustomobject]@{Path=[IO.Path]::GetRelativePath([IO.Path]::GetFullPath($WorkspaceRoot),$path).Replace('\','/');Sha256=(Get-FileHash -LiteralPath $path -Algorithm SHA256).Hash.ToLowerInvariant()}}) - [pscustomobject]@{WorkspaceRoot=[IO.Path]::GetFullPath($WorkspaceRoot);Guide=$GuideId;Edition=$EditionId;Language=$resolvedLanguage;Input=$inputPath;Output=$output;RelativeOutput=$relative;Arguments=$arguments;Fonts=$fonts;Fingerprints=$fingerprints;ConfigurationSha256=[Convert]::ToHexString([Security.Cryptography.SHA256]::HashData([Text.Encoding]::UTF8.GetBytes(($Policy | ConvertTo-Json -Depth 40 -Compress)))).ToLowerInvariant()} + + $recipe=Resolve-GuidePdfRecipe $WorkspaceRoot $Policy $selection $resolvedLanguage $DownloadPath + $settings=$recipe.Settings + $cover=if($settings.cover -is [Collections.IDictionary]){$settings.cover}else{@{}} + $credits=Get-GuideCredits -WorkspaceRoot $WorkspaceRoot -Policy $Policy -GuideId $GuideId -EditionId $EditionId -Language $resolvedLanguage -ContributorRoles @($cover.contributorRoles) -TranslatorRoles @($cover.translatorRoles) + $labels=Get-GuidePdfLabels $WorkspaceRoot $Policy $resolvedLanguage $selection.Edition.sourceLanguage + $direction='ltr' + if ($Policy.wrapper.Contains('languageDirections') -and $Policy.wrapper.languageDirections -is [Collections.IDictionary]) { + foreach($key in $Policy.wrapper.languageDirections.Keys){ if($key -ieq $resolvedLanguage){ $direction=[string]$Policy.wrapper.languageDirections[$key] } } + } + + $title=[string]$document.Metadata['title'] + $metadata=[ordered]@{title=$title;'title-meta'=$title;edition=[string]$EditionId;guide=$GuideId;lang=$resolvedLanguage} + # Pandoc's LaTeX template loads bidi whenever dir is set, so only pass it for RTL. + if ($direction -eq 'rtl') { $metadata.dir='rtl' } + if ($document.Metadata['short_title']) { $metadata.short_title=[string]$document.Metadata['short_title'] } + $date=$document.Metadata['date'] + if ($date -is [datetime]) { $metadata.date=$date.ToString('yyyy-MM-dd',[Globalization.CultureInfo]::InvariantCulture) } + elseif ($date) { $metadata.date=([string]$date -replace 'T.*$','') } + $metadata.authors=@($credits.Authors);$metadata.contributors=@($credits.Contributors);$metadata.translators=@($credits.Translators) + $metadata.'author-meta'=(@($credits.Authors|ForEach-Object {$_.name}) -join ', ') + $metadata.labels=$labels.Labels + foreach($key in @('watermark','licence')){ if(-not [string]::IsNullOrWhiteSpace([string]$settings[$key])){ $metadata[$key]=[string]$settings[$key] } } + if (-not [string]::IsNullOrWhiteSpace([string]$cover.tagline)) { $metadata.tagline=[string]$cover.tagline } + $resources=@($recipe.Files|Where-Object Relative|ForEach-Object Relative) + if ($document.Metadata['forked_from'] -match '^(?.+)/(?[^/]+)$') { + $sourceGuide=@($Policy.guides|Where-Object { $_.id -ieq $Matches['guide'] }) + $sourceEditionId=$Matches['edition'] + if ($sourceGuide.Count -eq 1) { + $sourceEdition=@($sourceGuide[0].editions|Where-Object { [string]$_.id -ceq $sourceEditionId }) + if ($sourceEdition.Count -eq 1) { + $base="$($sourceGuide[0].contentRoot)/$($sourceEdition[0].path)" + foreach($name in @("index.$resolvedLanguage.md",'index.md')){ + $candidate=Resolve-GuideWorkspacePath $WorkspaceRoot "$base/$name" + if([IO.File]::Exists($candidate)){ $metadata.based_on=[string](Read-GuideDocument $candidate).Metadata['title'];$resources+="$base/$name";break } + } + } + } + } + $leaf=($GuideId -split '/')[-1] + foreach($logoName in @("$leaf-logo.png","$($leaf.ToLowerInvariant())-logo.png")|Select-Object -Unique){ + $logoRelative="$($selection.Guide.contentRoot)/images/$logoName" + $logo=Resolve-GuideWorkspacePath $WorkspaceRoot $logoRelative + if([IO.File]::Exists($logo)){ $metadata.logo=ConvertTo-GuideLatexPath $logo;$resources+=$logoRelative;break } + } + + if ($direction -eq 'rtl') { + foreach($key in @('title','short_title','tagline','based_on','licence','watermark')){ if($metadata.Contains($key)){ $metadata[$key]=Format-GuidePdfText $metadata[$key] $true } } + foreach($key in @($metadata.labels.Keys)){ $metadata.labels[$key]=Format-GuidePdfText $metadata.labels[$key] $true } + foreach($credit in @($metadata.authors)+@($metadata.contributors)+@($metadata.translators)){ $credit.name=Format-GuidePdfText $credit.name $true } + } + + $arguments=@($inputPath,'--pdf-engine=xelatex','--pdf-engine-opt=-interaction=nonstopmode','--metadata',"lang=$resolvedLanguage",'--metadata','keywords=','--metadata','title=','--metadata','author=') + if ($direction -eq 'rtl') { $arguments+=@('--metadata','dir=rtl') } + foreach($key in @($script:GuidePdfFontKeys)+@('papersize','geometry','fontsize')){ + if(-not [string]::IsNullOrWhiteSpace([string]$settings[$key])){ $arguments+=@('-V',"$key=$($settings[$key])") } + } + if ($settings.toc -eq $true) { $arguments+=@('--toc',"--toc-depth=$(if($settings.tocDepth){[int]$settings.tocDepth}else{2})") } else { $arguments+=@('--metadata','toc=false') } + $resourcePath=@([IO.Path]::GetDirectoryName($inputPath))+@($recipe.ResourcePaths) + $arguments+=@('--resource-path',($resourcePath -join [IO.Path]::PathSeparator)) + foreach($filter in $recipe.Filters){ $arguments+=@('--lua-filter',$filter.Lua) } + + # Template parts are rendered with the metadata before the main run; filter + # headers are raw LaTeX. Parts not listed in settings.parts are skipped. + $parts=@(if($settings.Contains('parts')){$settings.parts}else{$script:GuidePdfParts}) + $includes=[Collections.Generic.List[object]]::new() + $rtlSupport=Join-Path (Get-GuidePdfPlatformRoot) 'rtl.tex' + if($direction -eq 'rtl'){ $includes.Add([pscustomobject]@{Part='rtl';Placement='header';Path=$rtlSupport;Template=$false}) } + foreach($part in @('style','page-header','page-footer')){ if($recipe.Templates.Contains($part)){ $includes.Add([pscustomobject]@{Part=$part;Placement='header';Path=$recipe.Templates[$part];Template=$true}) } } + foreach($filter in $recipe.Filters|Where-Object Header){ $includes.Add([pscustomobject]@{Part="filter:$($filter.Name)";Placement='header';Path=$filter.Header;Template=$false}) } + foreach($part in $parts){ + if($part -eq 'body' -or -not $recipe.Templates.Contains($part)){continue} + $placement=if(@($parts).IndexOf($part) -lt @($parts).IndexOf('body')){'before'}else{'after'} + $includes.Add([pscustomobject]@{Part=$part;Placement=$placement;Path=$recipe.Templates[$part];Template=$true}) + } + $bodyStart=Join-Path (Get-GuidePdfPlatformRoot) 'body-start.tex' + if(@($includes|Where-Object Placement -eq 'before').Count){ + $lastBefore=[Array]::FindLastIndex($includes.ToArray(),[Predicate[object]]{param($item) $item.Placement -eq 'before'}) + $includes.Insert($lastBefore+1,[pscustomobject]@{Part='body-start';Placement='before';Path=$bodyStart;Template=$false}) + } + + $fonts=[ordered]@{} + foreach($key in $script:GuidePdfFontKeys){ if(-not [string]::IsNullOrWhiteSpace([string]$settings[$key])){ $fonts[$key]=[string]$settings[$key] } } + $workspaceFiles=@(@("$($selection.RelativePath)/$filename")+$resources+@($credits.Files)+@($labels.Files)|Select-Object -Unique) + $fingerprints=@(foreach($path in $workspaceFiles){ + $full=Resolve-GuideWorkspacePath $WorkspaceRoot $path + [pscustomobject]@{Path=$path;Sha256=(Get-FileHash -LiteralPath $full -Algorithm SHA256).Hash.ToLowerInvariant()} + }) + $platformFiles=@(@($recipe.Files|Where-Object Level -eq 'platform'|ForEach-Object Path)+@((Join-Path (Get-GuidePdfPlatformRoot) 'labels.yaml'),$bodyStart,$rtlSupport)) + $platformEvidence=@($platformFiles|Sort-Object -Unique|ForEach-Object { "$([IO.Path]::GetRelativePath((Get-GuidePdfPlatformRoot),$_).Replace('\','/'))=$((Get-FileHash -LiteralPath $_ -Algorithm SHA256).Hash)" }) -join "`n" + $metadataJson=$metadata|ConvertTo-Json -Depth 20 -Compress + [pscustomobject]@{ + WorkspaceRoot=[IO.Path]::GetFullPath($WorkspaceRoot);Guide=$GuideId;Edition=$EditionId;Language=$resolvedLanguage;Input=$inputPath;Output=$output;RelativeOutput=$relative + Arguments=$arguments;Includes=@($includes.ToArray());Metadata=$metadata;Settings=$settings;Fonts=$fonts;Recipe=@($recipe.Files|Select-Object Level,Kind,@{n='Path';e={if($_.Relative){$_.Relative}else{"platform/$([IO.Path]::GetRelativePath((Get-GuidePdfPlatformRoot),$_.Path).Replace('\','/'))"}}}) + Fingerprints=$fingerprints + MetadataSha256=[Convert]::ToHexString([Security.Cryptography.SHA256]::HashData([Text.Encoding]::UTF8.GetBytes($metadataJson))).ToLowerInvariant() + PlatformSha256=[Convert]::ToHexString([Security.Cryptography.SHA256]::HashData([Text.Encoding]::UTF8.GetBytes($platformEvidence))).ToLowerInvariant() + ConfigurationSha256=[Convert]::ToHexString([Security.Cryptography.SHA256]::HashData([Text.Encoding]::UTF8.GetBytes(($Policy | ConvertTo-Json -Depth 40 -Compress)))).ToLowerInvariant() + } } function Get-GuidePdfToolchain { [CmdletBinding()] @@ -37,8 +135,8 @@ function Get-GuidePdfToolchain { } function New-GuidePdf { [CmdletBinding(SupportsShouldProcess)] - param([Parameter(Mandatory)][string]$WorkspaceRoot,[Parameter(Mandatory)][System.Collections.IDictionary]$Policy,[Parameter(Mandatory)][string]$GuideId,[Parameter(Mandatory)][string]$EditionId,[Parameter(Mandatory)][string]$Language,[Parameter(Mandatory)][string]$DownloadPath,[hashtable]$FontOverrides=@{},[string[]]$HeaderPaths=@(),[string[]]$LuaFilterPaths=@(),[ValidatePattern('^[a-fA-F0-9]{64}$')][string]$ExpectedOutputSha256,[ValidatePattern('^[a-fA-F0-9]{64}$')][string]$EnvironmentSha256) - $plan=Get-GuidePdfPlan -WorkspaceRoot $WorkspaceRoot -Policy $Policy -GuideId $GuideId -EditionId $EditionId -Language $Language -DownloadPath $DownloadPath -FontOverrides $FontOverrides -HeaderPaths $HeaderPaths -LuaFilterPaths $LuaFilterPaths + param([Parameter(Mandatory)][string]$WorkspaceRoot,[Parameter(Mandatory)][System.Collections.IDictionary]$Policy,[Parameter(Mandatory)][string]$GuideId,[Parameter(Mandatory)][string]$EditionId,[Parameter(Mandatory)][string]$Language,[Parameter(Mandatory)][string]$DownloadPath,[ValidatePattern('^[a-fA-F0-9]{64}$')][string]$ExpectedOutputSha256,[ValidatePattern('^[a-fA-F0-9]{64}$')][string]$EnvironmentSha256) + $plan=Get-GuidePdfPlan -WorkspaceRoot $WorkspaceRoot -Policy $Policy -GuideId $GuideId -EditionId $EditionId -Language $Language -DownloadPath $DownloadPath $replacing=[IO.File]::Exists($plan.Output) if ($replacing -and -not $ExpectedOutputSha256) { throw 'PDF already exists; supply its reviewed ExpectedOutputSha256 to replace it.' } if ($ExpectedOutputSha256 -and (-not $replacing -or (Get-FileHash -LiteralPath $plan.Output).Hash -ne $ExpectedOutputSha256)) { throw 'PDF changed since review or is missing.' } @@ -50,7 +148,7 @@ function New-GuidePdf { $families=@(& $fontCommand.Source --format '%{family}\n') if($LASTEXITCODE -ne 0){throw 'Font enumeration failed.'} $available=@($families | ForEach-Object { $_ -split ',' } | ForEach-Object { $_.Trim() }) - foreach($font in $plan.Fonts.Values){if($font -notin $available){throw "Font is not installed: $font. Supply an explicit installed override; no fonts are installed or substituted automatically."}} + foreach($font in $plan.Fonts.Values){if($font -notin $available){throw "Font is not installed: $font. Install it or change the font in the site's pdf settings; no fonts are installed or substituted automatically."}} } if ($PSCmdlet.ShouldProcess($plan.Output,'Generate a guide PDF with explicit language metadata')) { [IO.Directory]::CreateDirectory([IO.Path]::GetDirectoryName($plan.Output))|Out-Null @@ -60,7 +158,25 @@ function New-GuidePdf { $temporary=Join-Path $tempDirectory 'guide.pdf' try { [IO.Directory]::CreateDirectory($tempDirectory)|Out-Null - $arguments=@($plan.Arguments)+@('-o',$temporary) + Import-Module powershell-yaml -MinimumVersion 0.4.12 -ErrorAction Stop + $metadataPath=Join-Path $tempDirectory 'metadata.yaml' + [IO.File]::WriteAllText($metadataPath,(ConvertTo-Yaml -Data $plan.Metadata),[Text.UTF8Encoding]::new($false)) + $empty=Join-Path $tempDirectory 'empty.md' + [IO.File]::WriteAllText($empty,'') + $arguments=@($plan.Arguments)+@('--metadata-file',$metadataPath) + $index=0 + foreach($include in $plan.Includes){ + $path=$include.Path + if($include.Template){ + # Render the part as a Pandoc template so it can use the cover metadata. + $path=Join-Path $tempDirectory ("{0:D2}-{1}.tex" -f $index++,($include.Part -replace '[^A-Za-z0-9-]','-')) + $renderExit=Invoke-GuidePandoc -Arguments @($empty,'--from','markdown','--to','latex','--template',$include.Path,'--metadata-file',$metadataPath,'-o',$path) + if($renderExit -ne 0){throw "Pandoc failed with exit code $renderExit while rendering the $($include.Part) template."} + } + $option=switch($include.Placement){'header'{'--include-in-header'}'before'{'--include-before-body'}'after'{'--include-after-body'}} + $arguments+=@($option,$path) + } + $arguments+=@('-o',$temporary) $nativeExit=Invoke-GuidePandoc -Arguments $arguments if($nativeExit -ne 0){throw "Pandoc failed with exit code $nativeExit."} if(-not [IO.File]::Exists($temporary)){throw 'Pandoc did not create a PDF.'} diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Resolve-GuidePdfRecipe.ps1 b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Resolve-GuidePdfRecipe.ps1 new file mode 100644 index 00000000..4ddd4ee5 --- /dev/null +++ b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Resolve-GuidePdfRecipe.ps1 @@ -0,0 +1,227 @@ +$script:GuidePdfFontKeys=@('mainfont','sansfont','monofont','CJKmainfont','CJKsansfont','CJKmonofont') +$script:GuidePdfSettingKeys=@('mainfont','sansfont','monofont','CJKmainfont','CJKsansfont','CJKmonofont','papersize','geometry','fontsize','toc','tocDepth','watermark','licence','parts','cover','downloads') +$script:GuidePdfCoverKeys=@('tagline','contributorRoles','translatorRoles') +$script:GuidePdfParts=@('cover','licence','body','back') +$script:GuidePdfTemplates=[ordered]@{style='header';'page-header'='header';'page-footer'='header';cover='before';licence='before';back='after'} +$script:GuidePdfHandling=@('supplied','protected','generated') + +function Get-GuidePdfPlatformRoot { Join-Path $script:CoreRoot 'PdfPublishing/templates' } + +function Get-GuidePdfLevels { + # Least to most specific. The platform level lives in the module, the others in /pdf. + param([string]$WorkspaceRoot,[Collections.IDictionary]$Policy,$Selection) + $site="$($Policy.wrapper.sourcePath)/pdf" + @( + [pscustomobject]@{Name='platform';Relative=$null;Path=(Get-GuidePdfPlatformRoot)} + [pscustomobject]@{Name='site';Relative=$site;Path=(Resolve-GuideWorkspacePath $WorkspaceRoot $site)} + [pscustomobject]@{Name='guide';Relative="$site/$($Selection.Guide.id)";Path=(Resolve-GuideWorkspacePath $WorkspaceRoot "$site/$($Selection.Guide.id)")} + [pscustomobject]@{Name='edition';Relative="$site/$($Selection.Guide.id)/$($Selection.Edition.path)";Path=(Resolve-GuideWorkspacePath $WorkspaceRoot "$site/$($Selection.Guide.id)/$($Selection.Edition.path)")} + ) +} + +function Read-GuidePdfSettingsFile { + param([string]$Path,[string]$Level,[string]$Display) + Import-Module powershell-yaml -MinimumVersion 0.4.12 -ErrorAction Stop + $settings=ConvertFrom-Yaml ([IO.File]::ReadAllText($Path).TrimStart([char]0xFEFF)) -ErrorAction Stop + if($null -eq $settings){return @{}} + if($settings -isnot [Collections.IDictionary]){throw "PDF settings must be a mapping: $Display"} + foreach($problem in @(Test-GuidePdfSettings $settings $Level)){throw "${Display}: $problem"} + $settings +} + +function Test-GuidePdfSettings { + # Returns problems as strings; an empty result means the settings are valid for that level. + param([Collections.IDictionary]$Settings,[string]$Level) + foreach($key in $Settings.Keys){ + if($key -cnotin $script:GuidePdfSettingKeys){"Unknown PDF setting '$key'."} + } + if($Settings.Contains('cover')){ + if($Settings.cover -isnot [Collections.IDictionary]){'cover must be a mapping.'} + else{foreach($key in $Settings.cover.Keys){if($key -cnotin $script:GuidePdfCoverKeys){"Unknown cover setting '$key'."}}} + } + if($Settings.Contains('parts')){ + $parts=@($Settings.parts) + foreach($part in $parts){if($part -cnotin $script:GuidePdfParts){"Unknown part '$part'. Use: $($script:GuidePdfParts -join ', ')."}} + if($parts -cnotcontains 'body'){'parts must include body.'} + } + if($Settings.Contains('downloads')){ + if($Level -ne 'edition'){'downloads may only be declared in an edition folder.'} + foreach($download in @($Settings.downloads)){ + if($download -isnot [Collections.IDictionary]){'Each download must be a mapping with a path.';continue} + $path=[string]$download.path + if($path -notmatch '^(?!/)(?!.*(?:^|/)\.\.(?:/|$))[^\\:]+\.pdf$'){"Download path '$path' must be a .pdf path inside the edition."} + if($download.Contains('handling') -and [string]$download.handling -cnotin $script:GuidePdfHandling){"Download handling '$($download.handling)' must be one of: $($script:GuidePdfHandling -join ', ')."} + foreach($key in $download.Keys){if($key -cnotin @('path','handling','papersize','geometry','fontsize','watermark')){"Unknown download setting '$key'."}} + } + } +} + +function Get-GuidePdfDeclaredDownloads { + <# + Reads the downloads declared in /pdf///pdf[.].yaml. + Discovery uses these to mark PDFs generated or protected; everything else is supplied. + #> + [CmdletBinding()] + param([Parameter(Mandatory)][string]$SourceDirectory,[Parameter(Mandatory)][string]$GuideId,[Parameter(Mandatory)][string]$EditionPath) + $directory=Join-Path (Join-Path (Join-Path $SourceDirectory 'pdf') $GuideId) $EditionPath + if(-not [IO.Directory]::Exists($directory)){return} + foreach($file in [IO.Directory]::GetFiles($directory,'pdf*.yaml')|Sort-Object){ + if([IO.Path]::GetFileName($file) -notmatch '^pdf(?:\.[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*)?\.yaml$'){continue} + $settings=Read-GuidePdfSettingsFile $file 'edition' "pdf/$GuideId/$EditionPath/$([IO.Path]::GetFileName($file))" + foreach($download in @($settings.downloads|Where-Object {$_})){ + [pscustomobject]@{Path=[string]$download.path;Handling=$(if($download.Contains('handling')){[string]$download.handling}else{'supplied'})} + } + } +} + +function Merge-GuidePdfSettings { + param([Collections.IDictionary]$Target,[Collections.IDictionary]$Source) + foreach($key in $Source.Keys){ + if($key -ceq 'downloads'){continue} + if($key -ceq 'cover' -and $Target[$key] -is [Collections.IDictionary] -and $Source[$key] -is [Collections.IDictionary]){ + foreach($inner in $Source[$key].Keys){$Target[$key][$inner]=$Source[$key][$inner]} + }elseif($Source[$key] -is [Collections.IDictionary]){ + $copy=[ordered]@{};foreach($inner in $Source[$key].Keys){$copy[$inner]=$Source[$key][$inner]};$Target[$key]=$copy + }else{$Target[$key]=$Source[$key]} + } +} + +function Resolve-GuidePdfRecipe { + <# + Resolves settings, template parts, filters and resource folders for one PDF. + Settings merge key by key (least to most specific, language file after the + plain file at each level). Template parts and same-named filters are replaced + by the most specific file. + #> + param([string]$WorkspaceRoot,[Collections.IDictionary]$Policy,$Selection,[string]$Language,[string]$DownloadPath) + $levels=@(Get-GuidePdfLevels $WorkspaceRoot $Policy $Selection) + $settings=[ordered]@{} + $files=[Collections.Generic.List[object]]::new() + function Use($level,$path,$kind){$files.Add([pscustomobject]@{Level=$level.Name;Kind=$kind;Path=$path;Relative=$(if($level.Relative){"$($level.Relative)/$([IO.Path]::GetRelativePath($level.Path,$path).Replace('\','/'))"}else{$null})})} + $download=$null + foreach($level in $levels){ + foreach($name in @('pdf.yaml',"pdf.$Language.yaml")){ + $path=Join-Path $level.Path $name + if(-not [IO.File]::Exists($path)){continue} + $display=if($level.Relative){"$($level.Relative)/$name"}else{"platform/$name"} + $values=Read-GuidePdfSettingsFile $path $level.Name $display + Merge-GuidePdfSettings $settings $values + if($level.Name -eq 'edition' -and $values.Contains('downloads')){ + $declared=@($values.downloads|Where-Object {[string]$_.path -ceq $DownloadPath}) + if($declared.Count){$download=$declared[-1]} + } + Use $level $path settings + } + } + if($download){foreach($key in $download.Keys){if($key -cnotin @('path','handling')){$settings[$key]=$download[$key]}}} + $templates=[ordered]@{} + foreach($part in $script:GuidePdfTemplates.Keys){ + foreach($level in $levels[($levels.Count-1)..0]){ + $found=@("$part.$Language.tex","$part.tex"|ForEach-Object {Join-Path $level.Path $_}|Where-Object {[IO.File]::Exists($_)}) + if($found.Count){$templates[$part]=$found[0];Use $level $found[0] template;break} + } + } + $filters=[ordered]@{} + foreach($level in $levels){ + $directory=Join-Path $level.Path 'filters' + if(-not [IO.Directory]::Exists($directory)){continue} + foreach($lua in [IO.Directory]::GetFiles($directory,'*.lua')|Sort-Object){ + $name=[IO.Path]::GetFileNameWithoutExtension($lua) + $header=[IO.Path]::ChangeExtension($lua,'.tex') + $filters[$name]=[pscustomobject]@{Name=$name;Level=$level;Lua=$lua;Header=$(if([IO.File]::Exists($header)){$header}else{$null})} + } + } + foreach($filter in $filters.Values){Use $filter.Level $filter.Lua filter;if($filter.Header){Use $filter.Level $filter.Header filter-header}} + $resources=@($levels[($levels.Count-1)..0]|ForEach-Object {Join-Path $_.Path 'images'}|Where-Object {[IO.Directory]::Exists($_)}) + [pscustomobject]@{Settings=$settings;Templates=$templates;Filters=@($filters.Values|Sort-Object Name);ResourcePaths=$resources;Files=@($files.ToArray());Download=$download} +} + +function Get-GuidePdfLabels { + # Platform English labels, then the site default language, then the PDF language. + param([string]$WorkspaceRoot,[Collections.IDictionary]$Policy,[string]$Language,[string]$DefaultLanguage) + Import-Module powershell-yaml -MinimumVersion 0.4.12 -ErrorAction Stop + $values=[ordered]@{} + $defaults=ConvertFrom-Yaml ([IO.File]::ReadAllText((Join-Path (Get-GuidePdfPlatformRoot) 'labels.yaml'))) + foreach($key in $defaults.Keys){$values[$key]=[string]$defaults[$key]} + $used=@() + foreach($catalogueLanguage in @($DefaultLanguage,$Language|Select-Object -Unique)){ + foreach($extension in @('yaml','yml')){ + $relative="$($Policy.wrapper.sourcePath)/i18n/$catalogueLanguage.$extension" + $path=Resolve-GuideWorkspacePath $WorkspaceRoot $relative + if(-not [IO.File]::Exists($path)){continue} + $catalogue=ConvertFrom-Yaml ([IO.File]::ReadAllText($path).TrimStart([char]0xFEFF)) + $entries=@{} + if($catalogue -is [Collections.IDictionary]){foreach($key in $catalogue.Keys){$entries[$key]=$catalogue[$key]}} + elseif($catalogue -is [Collections.IList]){foreach($entry in $catalogue){if($entry -is [Collections.IDictionary] -and $entry.Contains('id')){$entries[[string]$entry.id]=$entry.translation}}} + $applied=$false + foreach($key in @($values.Keys)){ + if(-not $entries.ContainsKey($key)){continue} + $value=$entries[$key] + if($value -is [Collections.IDictionary]){$value=if($value.Contains('other')){$value.other}elseif($value.Contains('translation')){$value.translation}else{$null}} + if(-not [string]::IsNullOrWhiteSpace([string]$value)){$values[$key]=[string]$value;$applied=$true} + } + if($applied){$used+=$relative} + break + } + } + $labels=[ordered]@{} + foreach($key in $values.Keys){$labels[($key -replace '^pdf_','' -replace '_label$','')]=$values[$key]} + [pscustomobject]@{Labels=$labels;Files=$used} +} + +function Get-GuidePdfSettingFindings { + # Source-convention checks for /pdf settings and PDF labels; returns finding records for Prepare. + param([string]$WorkspaceRoot,[Collections.IDictionary]$Policy) + $relativeRoot="$($Policy.wrapper.sourcePath)/pdf" + $root=Resolve-GuideWorkspacePath $WorkspaceRoot $relativeRoot + if([IO.Directory]::Exists($root)){ + foreach($file in [IO.Directory]::GetFiles($root,'pdf*.y*ml',[IO.SearchOption]::AllDirectories)|Sort-Object){ + $inside=[IO.Path]::GetRelativePath($root,$file).Replace('\','/') + $display="$relativeRoot/$inside" + $name=[IO.Path]::GetFileName($file) + if($name -notmatch '^pdf(?:\.[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*)?\.yaml$'){ + [pscustomobject]@{Code='PDF_SETTINGS_INVALID';Severity='blocker';Subject=$display;Message='PDF settings files are named pdf.yaml or pdf..yaml.';Remediation='Rename the file.'};continue + } + $folder=[IO.Path]::GetDirectoryName($inside).Replace('\','/') + $level=if(-not $folder){'site'} + elseif(@($Policy.guides|Where-Object {$_.id -ieq $folder}).Count){'guide'} + elseif(@($Policy.guides|ForEach-Object {$guide=$_;$_.editions|Where-Object {"$($guide.id)/$($_.path)" -ieq $folder}}).Count){'edition'} + else{$null} + if(-not $level){[pscustomobject]@{Code='PDF_SETTINGS_INVALID';Severity='blocker';Subject=$display;Message="Folder '$folder' is not a guide or edition.";Remediation='Place settings in pdf/, pdf// or pdf///.'};continue} + try{$null=Read-GuidePdfSettingsFile $file $level $display} + catch{[pscustomobject]@{Code='PDF_SETTINGS_INVALID';Severity='blocker';Subject=$display;Message=$_.Exception.Message;Remediation='Correct the PDF settings; see the platform pdf.yaml for the supported keys.'}} + } + } + # Labels: warn when a generated PDF's language has no translation for a PDF label. + Import-Module powershell-yaml -MinimumVersion 0.4.12 -ErrorAction Stop + $keys=@((ConvertFrom-Yaml ([IO.File]::ReadAllText((Join-Path (Get-GuidePdfPlatformRoot) 'labels.yaml')))).Keys) + $languages=@($Policy.guides|ForEach-Object {$_.editions}|ForEach-Object {$edition=$_;$_.translations|Where-Object {$_.language -ine $edition.sourceLanguage -and @($_.downloads|Where-Object {$_.handling -eq 'generated'}).Count}|ForEach-Object {$_.language}}|Sort-Object -Unique) + foreach($language in $languages){ + $present=@() + foreach($extension in @('yaml','yml')){ + $path=Resolve-GuideWorkspacePath $WorkspaceRoot "$($Policy.wrapper.sourcePath)/i18n/$language.$extension" + if(-not [IO.File]::Exists($path)){continue} + try{$catalogue=ConvertFrom-Yaml ([IO.File]::ReadAllText($path).TrimStart([char]0xFEFF))}catch{break} + $present=if($catalogue -is [Collections.IDictionary]){@($catalogue.Keys)}else{@($catalogue|Where-Object {$_ -is [Collections.IDictionary]}|ForEach-Object {$_['id']})} + break + } + $missing=@($keys|Where-Object {$_ -notin $present}|Sort-Object) + if($missing.Count){[pscustomobject]@{Code='PDF_LABEL_MISSING';Severity='warning';Subject="$($Policy.wrapper.sourcePath)/i18n/$language";Message="Generated PDFs in $language will use English for: $($missing -join ', ').";Remediation="Add translations for these ids to i18n/$language.yaml."}} + } +} + +function Format-GuidePdfText { + # Metadata strings are read as Markdown. In a right-to-left document, text + # without any RTL characters is wrapped in an LTR span so bidi keeps Latin + # word order (Pandoc writes \LR{...}). + param([string]$Text,[bool]$RightToLeft) + if(-not $RightToLeft -or [string]::IsNullOrWhiteSpace($Text) -or $Text -match '[֐-ࣿיִ-﷿ﹰ-]' -or $Text -notmatch '\p{L}'){return $Text} + # The trailing LEFT-TO-RIGHT MARK keeps closing punctuation with the Latin run. + '['+($Text -replace '([\\\[\]])','\$1')+[char]0x200E+']{dir=ltr}' +} + +function ConvertTo-GuideLatexPath { + # Raw LaTeX inline so Pandoc does not escape the path in templates. + param([string]$Path) + '`'+([IO.Path]::GetFullPath($Path).Replace('\','/'))+'`{=latex}' +} diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Test-GuidePdfCache.ps1 b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Test-GuidePdfCache.ps1 index 30abc668..b9d841e7 100644 --- a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Test-GuidePdfCache.ps1 +++ b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Test-GuidePdfCache.ps1 @@ -19,6 +19,7 @@ function Test-GuidePdfCache { } function Get-GuidePdfCacheKey { param($Plan,[object[]]$Toolchain,[string]$EnvironmentSha256) - $evidence=[ordered]@{Generator=(Get-FileHash -LiteralPath (Join-Path $script:CoreRoot 'PdfPublishing/Get-GuidePdfPlan.ps1')).Hash;Inputs=$Plan.Fingerprints;Policy=$Plan.ConfigurationSha256;Arguments=$Plan.Arguments;Fonts=$Plan.Fonts;Tools=$Toolchain;Environment=$EnvironmentSha256;Output=$Plan.RelativeOutput} + $generator=@('PdfPublishing/Get-GuidePdfPlan.ps1','PdfPublishing/Resolve-GuidePdfRecipe.ps1','ContributorManagement/Get-GuideCredits.ps1'|ForEach-Object {(Get-FileHash -LiteralPath (Join-Path $script:CoreRoot $_)).Hash}) -join ',' + $evidence=[ordered]@{Generator=$generator;Inputs=$Plan.Fingerprints;Policy=$Plan.ConfigurationSha256;Arguments=$Plan.Arguments;Includes=@($Plan.Includes|ForEach-Object {"$($_.Placement):$($_.Part)"});Metadata=$Plan.MetadataSha256;Platform=$Plan.PlatformSha256;Fonts=$Plan.Fonts;Tools=$Toolchain;Environment=$EnvironmentSha256;Output=$Plan.RelativeOutput} [Convert]::ToHexString([Security.Cryptography.SHA256]::HashData([Text.Encoding]::UTF8.GetBytes(($evidence|ConvertTo-Json -Depth 100 -Compress)))).ToLowerInvariant() } \ No newline at end of file diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/back.tex b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/back.tex new file mode 100644 index 00000000..2b760fe4 --- /dev/null +++ b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/back.tex @@ -0,0 +1,8 @@ +% OpenGuidePlatform default back page: a short colophon. +\clearpage +\thispagestyle{empty} +\vspace*{\fill} +\begin{center} +{\small $title$\par} +{\small $labels.edition$ $edition$$if(date)$ · $date$$endif$\par} +\end{center} diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/body-start.tex b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/body-start.tex new file mode 100644 index 00000000..0a39074a --- /dev/null +++ b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/body-start.tex @@ -0,0 +1,5 @@ +% Included after the front parts (cover, licence) so the guide body starts on +% a new page numbered 1. Raw LaTeX, not a template. +\clearpage +\pagenumbering{arabic} +\setcounter{page}{1} diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/cover-page.tex b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/cover-page.tex deleted file mode 100644 index 946efe10..00000000 --- a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/cover-page.tex +++ /dev/null @@ -1,39 +0,0 @@ -% Simple cover page LaTeX snippet for injection via --include-before-body -\begin{titlepage} - \centering - - % Title section - \vspace*{2cm} - {\Huge\bfseries $title$ \par} - \vspace{1cm} - - $if(description)$ - {\large $description$ \par} - \vspace{1.5cm} - $endif$ - - % Creators section - $if(author)$ - \vspace{1cm} - {\Large\textbf{Creators} \par} - \vspace{0.5cm} - - \begin{center} - {\large $author$ \par} - \end{center} - $endif$ - - \vfill - - % Footer information - {\small\textit{Open Guide to Kanban} \par} - {\small\textit{Based on the Kanban Guide 2025} \par} - - % Date - $if(date)$ - \vspace{0.5cm} - {\large $date$ \par} - $endif$ - -\end{titlepage} -\clearpage diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/cover.tex b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/cover.tex new file mode 100644 index 00000000..c3312f0c --- /dev/null +++ b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/cover.tex @@ -0,0 +1,42 @@ +% OpenGuidePlatform default cover. Pandoc template: variables come from the +% generated PDF metadata; write a literal dollar sign as $$. +\begin{titlepage} + \centering + \thispagestyle{empty} + $if(logo)$ + \vspace*{1cm} + \includegraphics[width=4cm,height=4cm,keepaspectratio]{$logo$}\par + \vspace{1.5cm} + $else$ + \vspace*{3cm} + $endif$ + {\Huge\bfseries $title$\par} + \vspace{0.8cm} + {\large $labels.edition$ $edition$$if(date)$ · $date$$endif$\par} + $if(tagline)$ + \vspace{0.5cm} + {\normalsize\itshape $tagline$\par} + $elseif(based_on)$ + \vspace{0.5cm} + {\normalsize\itshape $labels.based_on$ $based_on$\par} + $endif$ + $if(authors)$ + \vspace{2cm} + {\Large\bfseries $labels.authors$\par} + \vspace{0.3cm} + {\large $for(authors)$$authors.name$$sep$ · $endfor$\par} + $endif$ + $if(translators)$ + \vspace{1cm} + {\Large\bfseries $labels.translators$\par} + \vspace{0.3cm} + {\large $for(translators)$$translators.name$$sep$ · $endfor$\par} + $endif$ + $if(contributors)$ + \vspace{1cm} + {\bfseries $labels.contributors$\par} + \vspace{0.2cm} + {\small $for(contributors)$$contributors.name$$sep$, $endfor$\par} + $endif$ + \vfill +\end{titlepage} diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/filters/callouts.lua b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/filters/callouts.lua new file mode 100644 index 00000000..c4a8a234 --- /dev/null +++ b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/filters/callouts.lua @@ -0,0 +1,75 @@ +-- Render Hugo/Obsidian-style callouts as tcolorbox environments in PDF output. +-- > [!NOTE] Optional title +-- > Body... +-- Adapted from ScrumGuide-ExpansionPack scripts/callouts-latex.lua. Default +-- titles come from the translated labels in the PDF metadata (labels.callout_*), +-- titles are rendered through Pandoc so they are escaped correctly, and emoji +-- icons are omitted because the configured document fonts rarely contain them. +-- The companion callouts.tex supplies the preamble. + +local styles = { + note = {back = "cyan!5", frame = "cyan!50!blue"}, + tip = {back = "green!5", frame = "green!50!black"}, + important = {back = "yellow!10", frame = "yellow!50!orange"}, + warning = {back = "orange!10", frame = "orange!50!red"}, + caution = {back = "red!10", frame = "red!50!black"}, + highlight = {back = "gray!5", frame = "gray!30"}, +} + +local function marker(inlines) + if not inlines or #inlines == 0 or inlines[1].t ~= "Str" then return nil end + return inlines[1].text:match("^%[!([A-Za-z0-9_-]+)%]") +end + +local function latex_inline(inlines) + local doc = pandoc.Pandoc({pandoc.Plain(inlines)}) + return (pandoc.write(doc, "latex"):gsub("%s+$", "")) +end + +local function callout(el, labels) + local first = el.content[1] + if not first or first.t ~= "Para" then return nil end + local kind = marker(first.content) + if not kind then return nil end + kind = kind:lower() + local style = styles[kind] or styles.note + + -- The title is the rest of the marker line; later lines of the same + -- paragraph belong to the body. + local title_inlines, body_inlines = pandoc.List(), pandoc.List() + local in_body = false + for i = 2, #first.content do + local inline = first.content[i] + if not in_body and (inline.t == "SoftBreak" or inline.t == "LineBreak") then + in_body = true + elseif in_body then + body_inlines:insert(inline) + else + title_inlines:insert(inline) + end + end + while #title_inlines > 0 and title_inlines[1].t == "Space" do title_inlines:remove(1) end + local title = latex_inline(title_inlines) + if title == "" and kind ~= "highlight" then + local label = labels["callout_" .. kind] or labels["callout_note"] + title = label and latex_inline(pandoc.Inlines(pandoc.utils.stringify(label))) or "" + end + + local options = string.format("colback=%s,colframe=%s", style.back, style.frame) + if title ~= "" then options = options .. ",title={" .. title .. "}" end + + local blocks = pandoc.List({pandoc.RawBlock("latex", "\\begin{tcolorbox}[" .. options .. "]")}) + if #body_inlines > 0 then blocks:insert(pandoc.Para(body_inlines)) end + for i = 2, #el.content do blocks:insert(el.content[i]) end + blocks:insert(pandoc.RawBlock("latex", "\\end{tcolorbox}")) + return blocks +end + +function Pandoc(doc) + if not FORMAT:match("latex") then return nil end + local labels = {} + if doc.meta.labels then + for key, value in pairs(doc.meta.labels) do labels[key] = value end + end + return doc:walk({BlockQuote = function(el) return callout(el, labels) end}) +end diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/filters/callouts.tex b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/filters/callouts.tex new file mode 100644 index 00000000..66b853e0 --- /dev/null +++ b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/filters/callouts.tex @@ -0,0 +1,21 @@ +% Preamble for filters/callouts.lua (raw LaTeX, included as-is). +% Adapted from ScrumGuide-ExpansionPack scripts/callouts-header.tex. +\usepackage{tcolorbox} +\tcbuselibrary{skins,breakable} +\tcbset{ + breakable, + enhanced, + sharp corners, + boxrule=0.6pt, + left=8pt, + right=8pt, + top=5pt, + bottom=5pt, + parbox=false, + before skip=10pt, + after skip=10pt +} +\AtBeginEnvironment{tcolorbox}{% + \setlength{\parskip}{0.5em}% + \setlength{\parindent}{0pt}% +} diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/filters/hugo-images.lua b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/filters/hugo-images.lua new file mode 100644 index 00000000..cb4e2a83 --- /dev/null +++ b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/filters/hugo-images.lua @@ -0,0 +1,9 @@ +-- Hugo pages reference site-root images as "/images/x.png". Strip the leading +-- slash so Pandoc resolves them through --resource-path. +-- Adapted from ScrumGuide-ExpansionPack scripts/callouts-latex.lua. +function Image(el) + if el.src:sub(1, 1) == "/" and el.src:sub(1, 2) ~= "//" then + el.src = el.src:sub(2) + end + return el +end diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/labels.yaml b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/labels.yaml new file mode 100644 index 00000000..6b06579e --- /dev/null +++ b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/labels.yaml @@ -0,0 +1,11 @@ +# English fallbacks for PDF labels. Sites translate these ids in i18n/.yaml. +pdf_authors_label: Authors +pdf_contributors_label: Contributors +pdf_translators_label: Translators +pdf_edition_label: Edition +pdf_based_on_label: Based on +pdf_callout_note: Note +pdf_callout_tip: Tip +pdf_callout_important: Important +pdf_callout_warning: Warning +pdf_callout_caution: Caution diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/licence.tex b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/licence.tex new file mode 100644 index 00000000..5630e831 --- /dev/null +++ b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/licence.tex @@ -0,0 +1,12 @@ +% OpenGuidePlatform default licence page. Rendered only when a licence is set +% in pdf.yaml; the guide body keeps its own attribution text. +$if(licence)$ +\thispagestyle{empty} +\vspace*{\fill} +{\small +\noindent $title$\\ +$labels.edition$ $edition$$if(date)$ · $date$$endif$\par +\medskip +\noindent $licence$\par} +\clearpage +$endif$ diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/page-footer.tex b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/page-footer.tex new file mode 100644 index 00000000..6b0e0bd0 --- /dev/null +++ b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/page-footer.tex @@ -0,0 +1,5 @@ +% OpenGuidePlatform default running footer (LaTeX preamble, Pandoc template). +% Loaded after page-header.tex, which enables fancyhdr. +\usepackage{fancyhdr} +\fancyfoot[C]{\small\thepage} +\renewcommand{\footrulewidth}{0pt} diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/page-header.tex b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/page-header.tex new file mode 100644 index 00000000..7942b9aa --- /dev/null +++ b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/page-header.tex @@ -0,0 +1,15 @@ +% OpenGuidePlatform default running header (LaTeX preamble, Pandoc template). +% fancyhdr boxes are left-to-right, so right-to-left documents set the title +% with \RL and mirror the positions. +\usepackage{fancyhdr} +\pagestyle{fancy} +\fancyhf{} +$if(dir)$ +\fancyhead[R]{\small\RL{$if(short_title)$$short_title$$else$$title$$endif$}} +\fancyhead[L]{\small $labels.edition$ $edition$} +$else$ +\fancyhead[L]{\small $if(short_title)$$short_title$$else$$title$$endif$} +\fancyhead[R]{\small $labels.edition$ $edition$} +$endif$ +\renewcommand{\headrulewidth}{0.4pt} +\fancypagestyle{plain}{\fancyhf{}\renewcommand{\headrulewidth}{0pt}\fancyfoot[C]{\small\thepage}} diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/pdf.yaml b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/pdf.yaml new file mode 100644 index 00000000..68a30614 --- /dev/null +++ b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/pdf.yaml @@ -0,0 +1,14 @@ +# OpenGuidePlatform PDF defaults. Sites override any key in /pdf/pdf.yaml, +# per guide, per edition and per language (pdf..yaml). +papersize: a4 +geometry: margin=2.2cm +fontsize: 11pt +toc: false +tocDepth: 2 +watermark: "" +licence: "" +parts: [cover, licence, body, back] +cover: + tagline: "" + contributorRoles: [contributor, reviewer] + translatorRoles: [translator] diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/rtl.tex b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/rtl.tex new file mode 100644 index 00000000..f6a054e8 --- /dev/null +++ b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/rtl.tex @@ -0,0 +1,8 @@ +% Included for right-to-left PDFs (raw LaTeX, not a template). Pandoc's +% babel setup for XeTeX does not define \LR/\RL, which Pandoc emits for +% [text]{dir=ltr} spans and the platform uses for Latin names on covers. +\ifdefined\XeTeXrevision + \TeXXeTstate=1 + \providecommand{\LR}[1]{\beginL #1\endL} + \providecommand{\RL}[1]{\beginR #1\endR} +\fi diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/style.tex b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/style.tex new file mode 100644 index 00000000..6ff227d5 --- /dev/null +++ b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/style.tex @@ -0,0 +1,13 @@ +% OpenGuidePlatform default styling (LaTeX preamble, Pandoc template). +\usepackage{xcolor} +\usepackage{graphicx} +\definecolor{ogplink}{HTML}{1F5FA8} +\AtBeginDocument{\hypersetup{colorlinks=true,linkcolor=ogplink,urlcolor=ogplink,citecolor=ogplink}} +\setlength{\parskip}{0.6em} +\setlength{\parindent}{0pt} +$if(watermark)$ +\usepackage{draftwatermark} +\SetWatermarkText{$watermark$} +\SetWatermarkScale{0.6} +\SetWatermarkColor[gray]{0.9} +$endif$ diff --git a/system/OpenGuidePlatform.PowerShell.Core/README.md b/system/OpenGuidePlatform.PowerShell.Core/README.md index 2fe26ee4..6241349c 100644 --- a/system/OpenGuidePlatform.PowerShell.Core/README.md +++ b/system/OpenGuidePlatform.PowerShell.Core/README.md @@ -10,6 +10,25 @@ Capabilities include inventory and translation readiness, publication exclusions PDF language comes from the filename suffix or declared source language and is passed explicitly to Pandoc metadata. Source front matter does not need a lang field. Generation checks native failures and PDF format before publishing a new file; returned evidence includes input, policy, executable and output hashes. Visual review remains necessary. +### Guide credits + +`data/contributions/.yml` lists the guide's people with roles `creator` (the authors), `contributor`, `reviewer` or `involved`. `data/contributions/..yml` lists one translation team with roles `translator` or `reviewer`. Each record has `name`, `role` and `contributions` (edition identifiers); optional `weight` orders records and `localizedNames` gives the name to show in a language. `Get-GuideCredits` resolves an edition's authors, contributors and translators; the website and PDF covers use the same records. Prepare blocks invalid roles, unknown editions or files, duplicates and the retired front matter keys `author`, `translators`, `mainfont`, `sansfont`, `monofont` and `dir`, and warns when an edition has no creator or a web translation has no translator. + +### PDF configuration + +`Get-GuidePdfPlan` builds the recipe from committed configuration only, most specific last: + +| Level | Folder | +|---|---| +| Platform | `PdfPublishing/templates/` in this module | +| Site | `/pdf/` | +| Guide | `/pdf//` | +| Edition | `/pdf///` | + +`pdf.yaml` settings merge key by key, with `pdf..yaml` applied after `pdf.yaml` at each level: `mainfont`, `sansfont`, `monofont`, `CJKmainfont`, `CJKsansfont`, `CJKmonofont`, `papersize`, `geometry`, `fontsize`, `toc`, `tocDepth`, `watermark`, `licence`, `parts` (order of `cover`, `licence`, `body`, `back`) and `cover` (`tagline`, `contributorRoles`, `translatorRoles`). Edition-level `downloads` entries declare `path` and `handling` (`supplied`, `protected` or `generated`, default `supplied`) and may override page settings for that one file; discovery uses them, and only `generated` downloads can be planned. Unknown keys are refused. + +`cover.tex`, `licence.tex`, `back.tex`, `page-header.tex`, `page-footer.tex` and `style.tex` are Pandoc templates (write a literal `$` as `$$`); the most specific file, including a `..tex` variant, replaces the default. `filters/.lua` accumulate across levels, a same-named file replacing a less specific one, and an optional `filters/.tex` is included in the preamble. The platform ships a Hugo image-path filter and a callouts filter for `> [!NOTE]` blocks. Templates receive `title`, `short_title`, `date`, `edition`, `guide`, `authors`, `contributors`, `translators` (each with `name`, `role`, optional `url`), `labels` (from the site i18n ids `pdf_authors_label`, `pdf_contributors_label`, `pdf_translators_label`, `pdf_edition_label`, `pdf_based_on_label` and `pdf_callout_*`, with English defaults), `tagline`, `based_on` (from `forked_from`), `logo` (`content//images/-logo.png`), `licence`, `watermark` and, for right-to-left languages, `dir`. Direction comes from the Hugo language `direction` (or `languageDirection`). Pandoc's own title block is suppressed; the cover replaces it. Japanese and other CJK text needs `CJKmainfont`. + This module enforces the supplied policy, not the authenticity of that policy. GuideSite packages distribute these commands through installation and Update. Independent enforcement requires the AgentControls evaluator to be configured with an external trusted baseline; installing skills does not configure that enforcement. ## Correct an existing guide diff --git a/system/OpenGuidePlatform.PowerShell.GuideSiteBuild/Discovery/New-GuideSiteDiscovery.ps1 b/system/OpenGuidePlatform.PowerShell.GuideSiteBuild/Discovery/New-GuideSiteDiscovery.ps1 index 5c509b87..fb01e5fc 100644 --- a/system/OpenGuidePlatform.PowerShell.GuideSiteBuild/Discovery/New-GuideSiteDiscovery.ps1 +++ b/system/OpenGuidePlatform.PowerShell.GuideSiteBuild/Discovery/New-GuideSiteDiscovery.ps1 @@ -19,30 +19,32 @@ function New-GuideSiteDiscovery { $rootDocument=Read-GuideDocument $rootFile.FullName if($rootDocument.Metadata['type'] -ne 'guide' -or $rootDocument.Metadata['layout'] -ne 'root'){continue} $directory=$rootFile.DirectoryName + $guideId=[IO.Path]::GetRelativePath($content,$directory).Replace('\','/') $editions=@(foreach($editionDirectory in Get-ChildItem $directory -Directory){ $base=Join-Path $editionDirectory.FullName 'index.md' if(-not (Test-Path $base)){continue} $document=Read-GuideDocument $base if($document.Metadata['layout'] -in @('translations','history','root','details')){continue} if($document.Metadata['type'] -ne 'guide' -and -not $document.Metadata.Contains('version')){continue} - $pdfs=@(Get-ChildItem $editionDirectory.FullName -Filter '*.pdf' -Recurse -File) - $editionLanguages=@(@(Get-ChildItem $editionDirectory.FullName -Filter 'index*.md' -File|ForEach-Object {Language $_.Name})+@($pdfs|ForEach-Object {if($_.Name -match '\.([A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*)\.pdf$'){$Matches[1]}})|Sort-Object -Unique) + # Existing PDFs are supplied unless /pdf///pdf.yaml declares + # otherwise; a declared generated PDF may not exist yet. + $declared=@(Get-GuidePdfDeclaredDownloads -SourceDirectory $source -GuideId $guideId -EditionPath $editionDirectory.Name) + $pdfPaths=@(@(Get-ChildItem $editionDirectory.FullName -Filter '*.pdf' -Recurse -File|ForEach-Object {[IO.Path]::GetRelativePath($editionDirectory.FullName,$_.FullName).Replace('\','/')})+@($declared|ForEach-Object {$_.Path})|Where-Object {$_}|Sort-Object -Unique) + $editionLanguages=@(@(Get-ChildItem $editionDirectory.FullName -Filter 'index*.md' -File|ForEach-Object {Language $_.Name})+@($pdfPaths|ForEach-Object {if($_ -match '\.([A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*)\.pdf$'){$Matches[1]}})|Sort-Object -Unique) $translations=@(foreach($language in $editionLanguages){ $name=if($language -eq $default){'index.md'}else{"index.$language.md"} $file=Join-Path $editionDirectory.FullName $name $body=if(Test-Path $file){(Read-GuideDocument $file).Body}else{''} - $downloads=@(foreach($pdf in $pdfs){ - $pdfLanguage=if($pdf.Name -match '\.([A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*)\.pdf$'){$Matches[1]}else{$default} + $downloads=@(foreach($relative in $pdfPaths){ + $pdfLanguage=if($relative -match '\.([A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*)\.pdf$'){$Matches[1]}else{$default} if($pdfLanguage -ne $language){continue} - $relative=[IO.Path]::GetRelativePath($editionDirectory.FullName,$pdf.FullName).Replace('\','/') $owners=@($pages|Where-Object { $pageFile=[IO.Path]::GetFullPath((Join-Path $source $_.path)) [IO.Path]::GetDirectoryName($pageFile) -ieq $editionDirectory.FullName -and [IO.Path]::GetFileName($pageFile) -iin @('index.md',"index.$language.md") }|ForEach-Object {ArtifactRoute $_.permalink}|Sort-Object -Unique) - $download=@{path=$relative;handling='supplied';publicationRoots=$owners} - - $download + $handling=@($declared|Where-Object Path -CEQ $relative|ForEach-Object Handling|Select-Object -Last 1) + @{path=$relative;handling=$(if($handling){$handling[0]}else{'supplied'});publicationRoots=$owners} }) $intent=if(-not [string]::IsNullOrWhiteSpace($body)){'web'}elseif($downloads.Count){'pdf-only'}elseif($language -eq $default){'web'}else{'fallback'} $entry=@{language=$language;intent=$intent;downloads=$downloads} @@ -57,7 +59,7 @@ function New-GuideSiteDiscovery { $suffix=if($language -eq $default){''}else{".$language"} foreach($relative in @("_index$suffix.md","history/index$suffix.md","translations/index$suffix.md")){$requiredFiles.Add((Relative (Join-Path $directory $relative)))} } - @{id=([IO.Path]::GetRelativePath($content,$directory).Replace('\','/'));contentRoot=(Relative $directory);relationship=@{kind='independent'};protectSource=$false;editions=$editions} + @{id=$guideId;contentRoot=(Relative $directory);relationship=@{kind='independent'};protectSource=$false;editions=$editions} }) if(-not $guides.Count){throw 'No guides were found. Expected guide roots with type: guide, layout: root, and edition bundles with version metadata.'} $aliases=@(foreach($file in Get-ChildItem $content -Filter '*.md' -Recurse -File){ @@ -160,6 +162,13 @@ function New-GuideSiteDiscovery { } } } - $inventory=@{schemaVersion=1;siteId=(Split-Path $WorkspaceRoot -Leaf);wrapper=@{discovery='source';jsonIndexes=$indexes;jsonFileNames=@(Get-GuideJsonFileNames -Configuration $configuration);sourcePath=$SourcePath;requiredRoutes=$routes;requiredFiles=@($requiredFiles);requiredI18nKeys=@();integrationPoints=@();legacyAliases=$aliases};guides=$guides;publication=@{environments=$environments;permanentExclusions=@(if($hasMin){@{environment='production';subject='language';id='min';reason='Minionese must never be published to production.'}})};protectedPaths=@()} + # Hugo 0.158 renamed languageDirection to direction; accept either. + $directions=@{} + foreach($language in $configuration.languages.Keys){ + $settings=$configuration.languages[$language] + $direction=if($settings -is [Collections.IDictionary]){@($settings['direction'],$settings['languagedirection'])|Where-Object {$_ -in @('ltr','rtl')}|Select-Object -First 1} + if($direction){$directions[$language]=[string]$direction} + } + $inventory=@{schemaVersion=1;siteId=(Split-Path $WorkspaceRoot -Leaf);wrapper=@{discovery='source';languageDirections=$directions;jsonIndexes=$indexes;jsonFileNames=@(Get-GuideJsonFileNames -Configuration $configuration);sourcePath=$SourcePath;requiredRoutes=$routes;requiredFiles=@($requiredFiles);requiredI18nKeys=@();integrationPoints=@();legacyAliases=$aliases};guides=$guides;publication=@{environments=$environments;permanentExclusions=@(if($hasMin){@{environment='production';subject='language';id='min';reason='Minionese must never be published to production.'}})};protectedPaths=@()} return $inventory } diff --git a/tests/Core/Assessment.Tests.ps1 b/tests/Core/Assessment.Tests.ps1 index e40105ef..841d9d97 100644 --- a/tests/Core/Assessment.Tests.ps1 +++ b/tests/Core/Assessment.Tests.ps1 @@ -38,6 +38,18 @@ Describe 'Shared Prepare assessment and reports' { $markdown|Should -Match 'No guide fixes identified' $markdown|Should -Not -Match '\| Body \||pdf-only|guide.fa.pdf' } + It 'blocks retired front matter keys and invalid PDF settings' { + [IO.File]::WriteAllText((Join-Path $directory 'index.md'),"---`ntitle: Guide`nauthor: [Someone]`nmainfont: Arial`n---`nBody") + [IO.Directory]::CreateDirectory((Join-Path $workspace 'site/pdf'))|Out-Null + [IO.File]::WriteAllText((Join-Path $workspace 'site/pdf/pdf.yaml'),"unknown: true`n") + $result=Get-GuideAssessment $workspace $policy @('en') @{} ('a'*40) '0.0.0' + $result.outcome|Should -Be fail + $retired=@($result.findings|Where-Object code -eq FRONT_MATTER_RETIRED_KEY) + $retired.Count|Should -Be 1 + $retired[0].message|Should -Match 'author, mainfont' + @($result.findings|Where-Object code -eq PDF_SETTINGS_INVALID).Count|Should -Be 1 + } + It 'reports missing PDF generation as a PDF problem, without asking for a web body' -Skip:$true {} It 'reports a missing PDF as a PDF problem, without asking for a web body' { $edition.translations+=@{language='fa';intent='pdf-only';downloads=@(@{path='guide.fa.pdf';handling='supplied'})} $result=Get-GuideAssessment $workspace $policy @('en','fa') @{} ('a'*40) '0.0.0' diff --git a/tests/Core/Discovery.Tests.ps1 b/tests/Core/Discovery.Tests.ps1 index 354ec1d1..b664e75d 100644 --- a/tests/Core/Discovery.Tests.ps1 +++ b/tests/Core/Discovery.Tests.ps1 @@ -178,3 +178,30 @@ Describe 'Non-rendering Hugo metadata' { Test-Path "$fixture/public"|Should -BeFalse } } + +Describe 'PDF declarations and language direction in discovery' { + It 'marks declared downloads generated, keeps the rest supplied and records language direction' { + $fixture=Join-Path $TestDrive 'declared-pdfs' + New-Item "$fixture/content/guide/2024.1/pdf" -ItemType Directory -Force|Out-Null + New-Item "$fixture/pdf/guide/2024.1" -ItemType Directory -Force|Out-Null + foreach($ring in @('canary','preview','production')){''|Set-Content "$fixture/hugo.$ring.yaml"} + "---`ntype: guide`nlayout: root`n---"|Set-Content "$fixture/content/guide/_index.md" + "---`ntype: guide`nversion: 2024.1`n---`nBody"|Set-Content "$fixture/content/guide/2024.1/index.md" + "---`ntype: guide`n---`nمتن"|Set-Content "$fixture/content/guide/2024.1/index.fa.md" + 'supplied PDF bytes'|Set-Content "$fixture/content/guide/2024.1/pdf/guide.en.pdf" + "downloads:`n - path: pdf/guide.fa.pdf`n handling: generated`n"|Set-Content "$fixture/pdf/guide/2024.1/pdf.yaml" + Mock Get-GuideSourcePages -ModuleName OpenGuidePlatform.PowerShell.GuideSiteBuild { @() } + Mock Get-GuideHugoConfiguration -ModuleName OpenGuidePlatform.PowerShell.GuideSiteBuild { + @{Configuration=@{baseurl='https://example.test/';contentdir='content';defaultcontentlanguage='en';defaultcontentlanguageinsubdir=$false;languages=@{en=@{disabled=$false};fa=@{disabled=$false;direction='rtl'};he=@{disabled=$true;languagedirection='rtl'}};outputs=@{home=@()};outputformats=@{};mediatypes=@{}}} + } + $found=New-GuideSiteDiscovery -WorkspaceRoot $TestDrive -SourcePath declared-pdfs -ConfigFiles @('hugo.yaml') -Target preview + $translations=$found.guides[0].editions[0].translations + (($translations|Where-Object language -eq en).downloads|Where-Object path -eq 'pdf/guide.en.pdf').handling|Should -Be supplied + (($translations|Where-Object language -eq fa).downloads|Where-Object path -eq 'pdf/guide.fa.pdf').handling|Should -Be generated + $found.wrapper.languageDirections.fa|Should -Be rtl + $found.wrapper.languageDirections.he|Should -Be rtl + $found.wrapper.languageDirections.Contains('en')|Should -BeFalse + $found|ConvertTo-Json -Depth 50|Set-Content "$fixture/policy.json" + {Import-GuidePolicy "$fixture/policy.json"}|Should -Not -Throw + } +} diff --git a/tests/Core/GuideCredits.Tests.ps1 b/tests/Core/GuideCredits.Tests.ps1 new file mode 100644 index 00000000..d05ea1b6 --- /dev/null +++ b/tests/Core/GuideCredits.Tests.ps1 @@ -0,0 +1,93 @@ +BeforeAll { + $root=Split-Path (Split-Path $PSScriptRoot -Parent) -Parent + Import-Module (Join-Path $root 'system/OpenGuidePlatform.PowerShell.Core/OpenGuidePlatform.PowerShell.Core.psd1') -Force + function Find-ContributorIssues($Workspace,$Policy){InModuleScope OpenGuidePlatform.PowerShell.Core -Parameters @{Workspace=$Workspace;Policy=$Policy} {param($Workspace,$Policy) Get-GuideContributorFindings $Workspace $Policy}} + function Write-Fixture($relative,$text){$path=Join-Path $workspace $relative;[IO.Directory]::CreateDirectory([IO.Path]::GetDirectoryName($path))|Out-Null;[IO.File]::WriteAllText($path,$text)} +} +Describe 'Contributor records and credits' { + BeforeEach { + $policy=Get-Content -Raw (Join-Path $root 'tests/Contracts/fixtures/single-guide.site-policy.json')|ConvertFrom-Json -AsHashtable + $policy.protectedPaths=@() + $guide=$policy.guides[0];$edition=$guide.editions[0] + $guide.id='example' + $edition.translations=@(@{language='en';intent='web';downloads=@()},@{language='fa';intent='web';downloads=@()},@{language='es-ES';intent='web';downloads=@()}) + $edition.sourceLanguage='en' + $editionId=[string]$edition.id + $guide.editions=@($edition)+@(@{id='1999.1';path='1999.1';sourceLanguage='en';translations=@(@{language='en';intent='web';downloads=@()})}) + $workspace=Join-Path $TestDrive ([guid]::NewGuid().ToString('N')) + $data="$($policy.wrapper.sourcePath)/data/contributions" + Write-Fixture "$data/example.yml" @" +- name: Zoe Creator + role: creator + contributions: ["$editionId"] + weight: 2 +- name: Adam Creator + role: creator + contributions: ["$editionId"] + weight: 1 + localizedNames: + fa: آدام +- name: Rita Reviewer + githubUsername: rita + role: reviewer + contributions: ["$editionId"] +- name: Earlier Person + role: contributor + contributions: ["1999.1"] +- name: Ivy Involved + role: involved + contributions: ["$editionId"] +"@ + Write-Fixture "$data/example.fa.yml" "- name: Parisa Translator`n role: translator`n contributions: [`"$editionId`"]`n- name: Omid Reviewer`n role: reviewer`n contributions: [`"$editionId`"]`n" + } + It 'resolves authors, contributors and translators for one edition and language' { + $credits=Get-GuideCredits $workspace $policy example $editionId fa + @($credits.Authors|ForEach-Object {$_.name}) | Should -Be @('آدام','Zoe Creator') + @($credits.Contributors|ForEach-Object {$_.name}) | Should -Be @('Rita Reviewer') + $credits.Contributors[0].url | Should -Be 'https://github.com/rita' + @($credits.Translators|ForEach-Object {$_.name}) | Should -Be @('Parisa Translator') + $credits.Files | Should -Contain "$data/example.fa.yml" + } + It 'omits translators for the source language and honours selected roles' { + $credits=Get-GuideCredits $workspace $policy example $editionId en -ContributorRoles @('reviewer','involved') -TranslatorRoles @('translator','reviewer') + @($credits.Authors|ForEach-Object {$_.name}) | Should -Be @('Adam Creator','Zoe Creator') + @($credits.Contributors|ForEach-Object {$_.name}) | Should -Be @('Ivy Involved','Rita Reviewer') + @($credits.Translators).Count | Should -Be 0 + } + It 'creates and updates a translation team file' { + (New-GuideContributions $workspace $policy example @(@{name='Sofia';role='translator';contributions=@($editionId)}) -Language es-ES).Path | Should -Be "$data/example.es-ES.yml" + { New-GuideContributions $workspace $policy example @(@{name='Other';role='creator';contributions=@($editionId)}) -Language fr } | Should -Throw '*not allowed*' + $path=Join-Path $workspace "$data/example.fa.yml" + $original=[IO.File]::ReadAllText($path) + $candidate=$original.Replace("role: translator`n contributions","role: translator`n weight: 3`n contributions") + $result=Update-GuideContributions $workspace $policy example 'Parisa Translator' (Get-FileHash $path).Hash $candidate -Language fa + $result.Status | Should -Be updated + $result.Path | Should -Be "$data/example.fa.yml" + [IO.File]::ReadAllText($path) | Should -BeExactly $candidate + } + It 'reports no findings for valid data' { + @(Find-ContributorIssues $workspace $policy|Where-Object Severity -eq blocker).Count | Should -Be 0 + } + It 'reports invalid roles, unknown editions, duplicates and unknown files' { + Write-Fixture "$data/example.es-ES.yml" "- name: Ana`n role: Translator`n contributions: [`"$editionId`"]`n- name: Ana`n role: translator`n contributions: [`"2030.1`"]`n" + Write-Fixture "$data/unknown-guide.yml" "- name: Nobody`n role: creator`n contributions: [`"$editionId`"]`n" + Write-Fixture "$data/example.ja.yml" "- name: Kenji`n role: translator`n contributions: [`"$editionId`"]`n" + $codes=@(Find-ContributorIssues $workspace $policy|ForEach-Object Code) + $codes | Should -Contain CONTRIBUTOR_RECORD_INVALID + $codes | Should -Contain CONTRIBUTOR_EDITION_UNKNOWN + @($codes|Where-Object {$_ -eq 'CONTRIBUTOR_FILE_UNKNOWN'}).Count | Should -Be 2 + } + It 'warns about missing creators and translators only when the site keeps contributor data' { + Remove-Item (Join-Path $workspace "$data/example.fa.yml") + $findings=@(Find-ContributorIssues $workspace $policy) + @($findings|Where-Object Code -eq TRANSLATORS_MISSING|ForEach-Object Subject) | Should -Be @("example/$editionId/fa","example/$editionId/es-ES") + ($findings|Where-Object Code -eq TRANSLATORS_MISSING|Select-Object -First 1).Severity | Should -Be warning + Remove-Item (Join-Path $workspace $data) -Recurse + @(Find-ContributorIssues $workspace $policy).Count | Should -Be 0 + } + It 'flags ambiguous extensions' { + Write-Fixture "$data/example.yaml" "- name: Copy`n role: creator`n contributions: [`"$editionId`"]`n" + @(Find-ContributorIssues $workspace $policy|ForEach-Object Code) | Should -Contain CONTRIBUTOR_FILE_AMBIGUOUS + { Get-GuideCredits $workspace $policy example $editionId en } | Should -Throw '*Ambiguous*' + } +} diff --git a/tests/Core/GuidePdfRecipe.Tests.ps1 b/tests/Core/GuidePdfRecipe.Tests.ps1 new file mode 100644 index 00000000..ffdaccb0 --- /dev/null +++ b/tests/Core/GuidePdfRecipe.Tests.ps1 @@ -0,0 +1,133 @@ +BeforeAll { + $root=Split-Path (Split-Path $PSScriptRoot -Parent) -Parent + Import-Module (Join-Path $root 'system/OpenGuidePlatform.PowerShell.Core/OpenGuidePlatform.PowerShell.Core.psd1') -Force + function Write-Fixture($relative,$text){$path=Join-Path $workspace $relative;[IO.Directory]::CreateDirectory([IO.Path]::GetDirectoryName($path))|Out-Null;[IO.File]::WriteAllText($path,$text)} + function Get-Variable($plan,$name){for($i=0;$i -lt $plan.Arguments.Count-1;$i++){if($plan.Arguments[$i] -eq '-V' -and $plan.Arguments[$i+1] -like "$name=*"){return $plan.Arguments[$i+1].Substring($name.Length+1)}}} +} +Describe 'Layered PDF recipe' { + BeforeEach { + $policy=Get-Content -Raw (Join-Path $root 'tests/Contracts/fixtures/single-guide.site-policy.json')|ConvertFrom-Json -AsHashtable + $policy.protectedPaths=@();$policy.guides[0].protectSource=$false + $guide=$policy.guides[0];$edition=$guide.editions[0] + $edition.translations=@( + @{language='en';intent='web';downloads=@(@{path='pdf/guide.en.pdf';handling='generated'})}, + @{language='fa';intent='web';downloads=@(@{path='pdf/guide.fa.pdf';handling='generated'})}) + $policy.wrapper.languageDirections=@{fa='rtl'} + $workspace=Join-Path $TestDrive ([guid]::NewGuid().ToString('N')) + $content="$($guide.contentRoot)/$($edition.path)" + $pdf="site/pdf";$guidePdf="$pdf/$($guide.id)";$editionPdf="$guidePdf/$($edition.path)" + Write-Fixture "$content/index.md" "---`ntitle: Example Guide`nshort_title: Example`ndate: 2024-08-01`n---`nBody" + Write-Fixture "$content/index.fa.md" "---`ntitle: راهنمای نمونه`n---`nمتن" + Write-Fixture "site/data/contributions/$($guide.id).yml" "- name: Jane Author`n role: creator`n contributions: [`"$($edition.id)`"]`n" + Write-Fixture "site/data/contributions/$($guide.id).fa.yml" "- name: Parisa Translator`n role: translator`n contributions: [`"$($edition.id)`"]`n" + Write-Fixture "$pdf/pdf.yaml" "mainfont: Site Serif`nsansfont: Site Sans`nlicence: CC BY-SA 4.0`n" + Write-Fixture "$guidePdf/pdf.fa.yaml" "mainfont: Persian Serif`n" + Write-Fixture "$editionPdf/pdf.yaml" "papersize: letter`ndownloads:`n - path: pdf/guide.en.pdf`n handling: generated`n fontsize: 12pt`n" + } + It 'merges platform, site, guide, edition, language and download settings' { + $en=Get-GuidePdfPlan $workspace $policy $guide.id $edition.id en 'pdf/guide.en.pdf' + Get-Variable $en mainfont | Should -Be 'Site Serif' + Get-Variable $en papersize | Should -Be 'letter' + Get-Variable $en fontsize | Should -Be '12pt' + Get-Variable $en geometry | Should -Be 'margin=2.2cm' -Because 'the platform default applies' + $en.Fonts.mainfont | Should -Be 'Site Serif' + $fa=Get-GuidePdfPlan $workspace $policy $guide.id $edition.id fa 'pdf/guide.fa.pdf' + Get-Variable $fa mainfont | Should -Be 'Persian Serif' + Get-Variable $fa sansfont | Should -Be 'Site Sans' + Get-Variable $fa fontsize | Should -Be '11pt' -Because 'download overrides apply only to that download' + @($fa.Recipe|Where-Object Kind -eq settings|ForEach-Object Path) | Should -Contain "$guidePdf/pdf.fa.yaml" + $fa.Fingerprints.Path | Should -Contain "$guidePdf/pdf.fa.yaml" + } + It 'builds cover metadata from contributor data and suppresses the document title block' { + $plan=Get-GuidePdfPlan $workspace $policy $guide.id $edition.id en 'pdf/guide.en.pdf' + $plan.Metadata.title | Should -Be 'Example Guide' + $plan.Metadata.short_title | Should -Be 'Example' + $plan.Metadata.date | Should -Be '2024-08-01' + $plan.Metadata.authors[0].name | Should -Be 'Jane Author' + $plan.Metadata.licence | Should -Be 'CC BY-SA 4.0' + $plan.Metadata.labels.authors | Should -Be 'Authors' + $plan.Metadata.Contains('dir') | Should -BeFalse + $plan.Arguments | Should -Contain 'title=' + $plan.Arguments | Should -Contain 'lang=en' + $plan.Fingerprints.Path | Should -Contain "site/data/contributions/$($guide.id).yml" + } + It 'marks Latin credits left-to-right in right-to-left documents and adds RTL support' { + Write-Fixture 'site/i18n/fa.yaml' "- id: pdf_translators_label`n translation: مترجمان`n" + $plan=Get-GuidePdfPlan $workspace $policy $guide.id $edition.id fa 'pdf/guide.fa.pdf' + $plan.Metadata.dir | Should -Be 'rtl' + $plan.Metadata.translators[0].name | Should -Be "[Parisa Translator$([char]0x200E)]{dir=ltr}" + $plan.Metadata.labels.translators | Should -Be 'مترجمان' + $plan.Metadata.title | Should -Be 'راهنمای نمونه' + @($plan.Includes|Where-Object Part -eq 'rtl').Count | Should -Be 1 + $plan.Fingerprints.Path | Should -Contain 'site/i18n/fa.yaml' + } + It 'uses the most specific template for each part and places parts around the body' { + Write-Fixture "$pdf/cover.tex" 'site cover $title$' + Write-Fixture "$guidePdf/cover.fa.tex" 'guide persian cover' + $en=Get-GuidePdfPlan $workspace $policy $guide.id $edition.id en 'pdf/guide.en.pdf' + ($en.Includes|Where-Object Part -eq cover).Path | Should -Be (Join-Path $workspace "$pdf/cover.tex") + $fa=Get-GuidePdfPlan $workspace $policy $guide.id $edition.id fa 'pdf/guide.fa.pdf' + ($fa.Includes|Where-Object Part -eq cover).Path | Should -Be (Join-Path $workspace "$guidePdf/cover.fa.tex") + @($en.Includes|ForEach-Object {"$($_.Placement):$($_.Part)"}) | Should -Be @('header:style','header:page-header','header:page-footer','header:filter:callouts','before:cover','before:licence','before:body-start','after:back') + Write-Fixture "$editionPdf/pdf.yaml" "parts: [body]`n" + @((Get-GuidePdfPlan $workspace $policy $guide.id $edition.id en 'pdf/guide.en.pdf').Includes|Where-Object Placement -ne header).Count | Should -Be 0 + } + It 'replaces a platform filter by name and adds site filters with their preamble' { + Write-Fixture "$pdf/filters/callouts.lua" '-- site callouts' + Write-Fixture "$guidePdf/filters/glossary.lua" '-- glossary' + Write-Fixture "$guidePdf/filters/glossary.tex" '% glossary preamble' + $plan=Get-GuidePdfPlan $workspace $policy $guide.id $edition.id en 'pdf/guide.en.pdf' + $filters=@(for($i=0;$i -lt $plan.Arguments.Count;$i++){if($plan.Arguments[$i] -eq '--lua-filter'){$plan.Arguments[$i+1]}}) + $filters | Should -Contain (Join-Path $workspace "$pdf/filters/callouts.lua") + $filters | Should -Contain (Join-Path $workspace "$guidePdf/filters/glossary.lua") + @($filters|Where-Object {$_ -like '*hugo-images.lua'}).Count | Should -Be 1 + @($plan.Includes|Where-Object Part -eq 'filter:callouts').Count | Should -Be 0 -Because 'the site callouts filter has no companion preamble' + ($plan.Includes|Where-Object Part -eq 'filter:glossary').Path | Should -Be (Join-Path $workspace "$guidePdf/filters/glossary.tex") + } + It 'refuses unknown settings, misplaced downloads and PDF keys in front matter' { + Write-Fixture "$pdf/pdf.yaml" "mainfont: X`ncolour: red`n" + { Get-GuidePdfPlan $workspace $policy $guide.id $edition.id en 'pdf/guide.en.pdf' } | Should -Throw "*Unknown PDF setting 'colour'*" + Write-Fixture "$pdf/pdf.yaml" "downloads:`n - path: pdf/x.pdf`n" + { Get-GuidePdfPlan $workspace $policy $guide.id $edition.id en 'pdf/guide.en.pdf' } | Should -Throw '*edition folder*' + Write-Fixture "$pdf/pdf.yaml" "mainfont: X`n" + Write-Fixture "$content/index.md" "---`ntitle: Example`nmainfont: Old`n---`nBody" + { Get-GuidePdfPlan $workspace $policy $guide.id $edition.id en 'pdf/guide.en.pdf' } | Should -Throw '*no longer read*' + } + It 'reports declared downloads and invalid settings for discovery and Prepare' { + $declared=@(Get-GuidePdfDeclaredDownloads -SourceDirectory (Join-Path $workspace 'site') -GuideId $guide.id -EditionPath $edition.path) + $declared.Count | Should -Be 1 + $declared[0].Path | Should -Be 'pdf/guide.en.pdf' + $declared[0].Handling | Should -Be 'generated' + Write-Fixture "$pdf/unknown-guide/pdf.yaml" "mainfont: X`n" + Write-Fixture "$guidePdf/pdf.yaml" "downloads: []`n" + $findings=@(InModuleScope OpenGuidePlatform.PowerShell.Core -Parameters @{Workspace=$workspace;Policy=$policy} {param($Workspace,$Policy) Get-GuidePdfSettingFindings $Workspace $Policy}) + @($findings|Where-Object Code -eq PDF_SETTINGS_INVALID).Count | Should -Be 2 + @($findings|Where-Object Code -eq PDF_LABEL_MISSING).Subject | Should -Be 'site/i18n/fa' + } +} +Describe 'Rendering template parts' { + BeforeEach { + $policy=Get-Content -Raw (Join-Path $root 'tests/Contracts/fixtures/single-guide.site-policy.json')|ConvertFrom-Json -AsHashtable + $policy.protectedPaths=@();$policy.guides[0].protectSource=$false + $guide=$policy.guides[0];$edition=$guide.editions[0] + $edition.translations[0].downloads=@(@{path='pdf/guide.pdf';handling='generated'}) + $workspace=Join-Path $TestDrive ([guid]::NewGuid().ToString('N')) + Write-Fixture "$($guide.contentRoot)/$($edition.path)/index.md" "---`ntitle: Example`n---`nBody" + Mock Get-GuidePdfToolchain -ModuleName OpenGuidePlatform.PowerShell.Core { @([pscustomobject]@{Tool='pandoc';Available=$true},[pscustomobject]@{Tool='xelatex';Available=$true}) } + Mock Get-Command -ModuleName OpenGuidePlatform.PowerShell.Core -ParameterFilter { $Name -eq 'fc-list' } { $null } + $script:calls=[Collections.Generic.List[object]]::new() + Mock Invoke-GuidePandoc -ModuleName OpenGuidePlatform.PowerShell.Core { param($Arguments) $script:calls.Add(@($Arguments));[IO.File]::WriteAllText($Arguments[-1],'%PDF-rendered');0 } + } + It 'renders each template part with the metadata before the main run' { + $result=New-GuidePdf $workspace $policy $guide.id $edition.id en 'pdf/guide.pdf' + $result.Status | Should -Be created + $plan=Get-GuidePdfPlan $workspace $policy $guide.id $edition.id en 'pdf/guide.pdf' + $templates=@($plan.Includes|Where-Object Template) + $script:calls.Count | Should -Be ($templates.Count+1) + foreach($call in $script:calls[0..($templates.Count-1)]){ $call | Should -Contain '--template';$call | Should -Contain '--metadata-file' } + $main=$script:calls[-1] + $main | Should -Contain '--metadata-file' + @($main|Where-Object {$_ -in @('--include-in-header','--include-before-body','--include-after-body')}).Count | Should -Be $plan.Includes.Count + @(Get-ChildItem (Join-Path $workspace "$($guide.contentRoot)/$($edition.path)/pdf") -Force).Count | Should -Be 1 -Because 'staging is removed' + } +} diff --git a/tests/Core/HugoGuideRendering.Tests.ps1 b/tests/Core/HugoGuideRendering.Tests.ps1 index 69ac9726..f868f89e 100644 --- a/tests/Core/HugoGuideRendering.Tests.ps1 +++ b/tests/Core/HugoGuideRendering.Tests.ps1 @@ -11,7 +11,7 @@ BeforeAll { Copy-Item "$module/layouts/index.html" "$fixture/themes/guides/layouts/index.html" Copy-Item "$module/layouts/guide/details.html" "$fixture/layouts/guide/details.html" [IO.File]::WriteAllText("$fixture/layouts/baseof.html",'{{ block "main" . }}{{ end }}') - [IO.File]::WriteAllText("$fixture/layouts/guide/probe.html",'{{ define "main" }}{{ partial "components/guide/guide-creators.html" . }}{{ partial "components/versions/version-card.html" (dict "page" . "itemType" "latest") }}{{ end }}') + [IO.File]::WriteAllText("$fixture/layouts/guide/probe.html",'{{ define "main" }}{{ partial "components/guide/guide-creators.html" . }}{{ partial "components/guide/guide-translators.html" . }}{{ partial "components/versions/version-card.html" (dict "page" . "itemType" "latest") }}{{ end }}') [IO.File]::WriteAllText("$fixture/hugo.yaml",@' baseURL: https://fixture.example/ theme: guides @@ -32,12 +32,17 @@ languages: role: creator founder: true weight: 1 + localizedNames: + fa: سازنده آزمایشی - name: Fixture Contributor gravatarHash: fixture-hash role: contributor founder: true weight: 2 '@) + # Translation teams: the data key keeps the content language's case (es-ES) + # while Hugo reports the page language in lower case (es-es). + [IO.File]::WriteAllText("$fixture/data/contributions/guide.es-ES.yml","- name: Fixture Traductora`n role: translator`n weight: 2`n- name: Fixture Revisora`n role: reviewer`n weight: 1`n") [IO.File]::WriteAllText("$fixture/content/guide/_index.md","---`ntitle: Fixture guide`ntype: guide`nlayout: details`n---`nGuide overview.") foreach($language in @('en','fa','fr','ja','min','es-ES','pt-BR')){ [IO.File]::WriteAllText("$fixture/content/guide/latest/index.$($language.ToLowerInvariant()).md","---`ntitle: Fixture guide $language`ntype: guide`nlayout: probe`n---`nThis is a complete guide body with enough words to represent an online translation in the catalogue.") @@ -82,6 +87,18 @@ Describe 'Guide contributor rendering' { } } } +Describe 'Translator and localized name rendering' { + It 'renders the translation team from the guide language data file' { + $spanish=[IO.File]::ReadAllText("$fixture/public/es-es/guide/latest/index.html") + $spanish | Should -Match 'Fixture Traductora' + $spanish.IndexOf('Fixture Revisora') | Should -BeLessThan $spanish.IndexOf('Fixture Traductora') -Because 'records are ordered by weight' + [IO.File]::ReadAllText("$fixture/public/guide/latest/index.html") | Should -Not -Match 'Fixture Traductora' + } + It 'uses localizedNames for the page language only' { + [IO.File]::ReadAllText("$fixture/public/fa/guide/latest/index.html") | Should -Match 'سازنده آزمایشی' + [IO.File]::ReadAllText("$fixture/public/fr/guide/latest/index.html") | Should -Match 'Fixture Creator' + } +} Describe 'Translation PDF resource selection' { It 'selects each language PDF rather than a shared untagged English resource' { foreach($language in @('en','fa','fr','ja','min','pt-br')){ From e058971501b8cf948f2dfcb4e3ca960d3c3072c5 Mon Sep 17 00:00:00 2001 From: Martin Hinshelwood Date: Wed, 23 Sep 2026 16:20:38 +0100 Subject: [PATCH 2/4] Keep data-file order for contributors with equal weights PDF covers broke weight ties alphabetically while the website keeps the data file's order; both now list equal-weight records in file order. Co-Authored-By: Claude Opus 5.5 --- .../ContributorManagement/Get-GuideCredits.ps1 | 7 +++++-- tests/Core/GuideCredits.Tests.ps1 | 2 +- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/Get-GuideCredits.ps1 b/system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/Get-GuideCredits.ps1 index bbf7d6af..3670bcc9 100644 --- a/system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/Get-GuideCredits.ps1 +++ b/system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/Get-GuideCredits.ps1 @@ -60,13 +60,16 @@ function ConvertTo-GuideCredit { function Select-GuideCredits { param([object[]]$Records,[string]$EditionId,[string[]]$Roles,[string]$Language) + # Order by weight; equal weights keep the data file's order, as the website does. + $position=0 $selected=@(foreach($record in $Records){ + $position++ if($record -isnot [Collections.IDictionary]){continue} if([string]$record['role'] -notin $Roles){continue} if(@($record['contributions']|ForEach-Object {[string]$_}) -notcontains $EditionId){continue} - [pscustomobject]@{Weight=$(if($null -ne $record['weight']){[double]$record['weight']}else{100});Name=[string]$record['name'];Record=$record} + [pscustomobject]@{Weight=$(if($null -ne $record['weight']){[double]$record['weight']}else{100});Position=$position;Record=$record} }) - @($selected|Sort-Object Weight,Name|ForEach-Object {ConvertTo-GuideCredit $_.Record $Language}) + @($selected|Sort-Object Weight,Position|ForEach-Object {ConvertTo-GuideCredit $_.Record $Language}) } function Get-GuideCredits { diff --git a/tests/Core/GuideCredits.Tests.ps1 b/tests/Core/GuideCredits.Tests.ps1 index d05ea1b6..43d8795d 100644 --- a/tests/Core/GuideCredits.Tests.ps1 +++ b/tests/Core/GuideCredits.Tests.ps1 @@ -51,7 +51,7 @@ Describe 'Contributor records and credits' { It 'omits translators for the source language and honours selected roles' { $credits=Get-GuideCredits $workspace $policy example $editionId en -ContributorRoles @('reviewer','involved') -TranslatorRoles @('translator','reviewer') @($credits.Authors|ForEach-Object {$_.name}) | Should -Be @('Adam Creator','Zoe Creator') - @($credits.Contributors|ForEach-Object {$_.name}) | Should -Be @('Ivy Involved','Rita Reviewer') + @($credits.Contributors|ForEach-Object {$_.name}) | Should -Be @('Rita Reviewer','Ivy Involved') -Because 'equal weights keep the data file order' @($credits.Translators).Count | Should -Be 0 } It 'creates and updates a translation team file' { From e2df48ef6c0f6921140c72fb8e9b8c7fe281d940 Mon Sep 17 00:00:00 2001 From: Martin Hinshelwood Date: Wed, 23 Sep 2026 16:45:58 +0100 Subject: [PATCH 3/4] Report missing fonts with sources; fix right-to-left PDF rendering Fonts: pdf.yaml gains fontSources (font name -> where to get it). The plan records which settings file chose each font; New-GuidePdf checks every font before rendering and lists all missing ones with that file and the source. Test-GuidePdfFonts reports font status for every generated PDF of a site. Right-to-left: use babel bidi=bidi-r (the default XeTeX mode loses colour changes), add the rtl-latin filter that marks Latin runs and Latin-only paragraphs as English so their order survives, and mark cover values, including editions and dates, the same way. Co-Authored-By: Claude Opus 5.5 --- .../guide-pdf-and-contributors.md | 3 + examples/reference-guide-site/pdf/pdf.ja.yaml | 3 + .../skills/guide.genpdfs/SKILL.md | 2 +- .../OpenGuidePlatform.PowerShell.Core.psd1 | 2 +- .../PdfPublishing/Get-GuidePdfPlan.ps1 | 70 +++++++++++++++-- .../PdfPublishing/Resolve-GuidePdfRecipe.ps1 | 19 +++-- .../templates/filters/rtl-latin.lua | 77 +++++++++++++++++++ .../README.md | 2 + tests/Core/GuidePdfRecipe.Tests.ps1 | 36 ++++++++- 9 files changed, 197 insertions(+), 17 deletions(-) create mode 100644 system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/filters/rtl-latin.lua diff --git a/docs/architecture/guide-pdf-and-contributors.md b/docs/architecture/guide-pdf-and-contributors.md index 752dc1b4..04bac50b 100644 --- a/docs/architecture/guide-pdf-and-contributors.md +++ b/docs/architecture/guide-pdf-and-contributors.md @@ -311,4 +311,7 @@ Differences from the original draft, found while implementing and checking real - Added the fixed `body-start.tex` and `rtl.tex` includes (section 4.3) and left-to-right wrapping of Latin text in right-to-left covers and headers; the running header mirrors for right-to-left documents. - D4: translation reviewers are not a separate cover group. They can be listed with translators through `cover.translatorRoles`; the website still shows the whole translation team. - Contributor warnings apply only to sites that keep `data/contributions`, so sites without contributor data are not asked for it. +- Missing fonts are reported together, each with the settings file that chose it and the `fontSources` entry saying where to get it; `Test-GuidePdfFonts` reports this for a whole site before generating. +- Right-to-left PDFs use babel `bidi=bidi-r` (the default XeTeX mode loses colour changes) and the `rtl-latin` filter, which marks Latin runs and Latin-only paragraphs as English; cover values use the same marking, including editions and dates. +- Contributors with equal weights keep the data file order, as on the website. - Core exposes `Get-GuideCredits` (resolved credits) and `Get-GuidePdfDeclaredDownloads` (used by discovery). Discovery records `wrapper.languageDirections`, added to the site-policy schema. diff --git a/examples/reference-guide-site/pdf/pdf.ja.yaml b/examples/reference-guide-site/pdf/pdf.ja.yaml index 7d2cd4b5..130558e7 100644 --- a/examples/reference-guide-site/pdf/pdf.ja.yaml +++ b/examples/reference-guide-site/pdf/pdf.ja.yaml @@ -3,3 +3,6 @@ mainfont: Noto Serif JP sansfont: Noto Sans JP monofont: Noto Sans JP CJKmainfont: Noto Serif JP +fontSources: + Noto Serif JP: https://github.com/notofonts/noto-cjk/releases/tag/Serif2.003 + Noto Sans JP: https://github.com/notofonts/noto-cjk/releases/tag/Sans2.004 diff --git a/system/OpenGuidePlatform.Agents.Integration/skills/guide.genpdfs/SKILL.md b/system/OpenGuidePlatform.Agents.Integration/skills/guide.genpdfs/SKILL.md index 3c03ecf1..ecce6859 100644 --- a/system/OpenGuidePlatform.Agents.Integration/skills/guide.genpdfs/SKILL.md +++ b/system/OpenGuidePlatform.Agents.Integration/skills/guide.genpdfs/SKILL.md @@ -7,7 +7,7 @@ Read [Core usage](../USAGE.md). Select guide, edition, language and the exact do The recipe is committed configuration, never per-run choices. Settings, templates and filters are layered: platform defaults, then `/pdf/`, `/pdf//` and `/pdf///`, with `.` variants (`pdf.fa.yaml`, `cover.ja.tex`) at any level. `pdf.yaml` keys merge; `cover.tex`, `licence.tex`, `back.tex`, `page-header.tex`, `page-footer.tex` and `style.tex` are Pandoc templates replaced by the most specific file; `filters/.lua` replaces a same-named filter and may have a companion `filters/.tex` preamble. Cover credits come from contributor data (see guide.contributions) and labels from the site i18n `pdf_*` ids. Fonts and direction never come from front matter; Japanese needs `CJKmainfont`. -Use `Get-GuidePdfPlan` to inspect source, destination, resolved recipe files, settings, cover metadata, arguments, fonts and fingerprints. Use `Get-GuidePdfToolchain` for diagnostics, then `New-GuidePdf` with the same selections. Change the look by editing the site's PDF configuration in a reviewed change, not by passing options. Do not silently substitute fonts or install packages. The command passes the filename/default language to Pandoc metadata and never needs lang in Hugo front matter. +Use `Get-GuidePdfPlan` to inspect source, destination, resolved recipe files, settings, cover metadata, arguments, fonts and fingerprints. Use `Test-GuidePdfFonts` to see every required font, whether it is installed and where to get it (record sources under `fontSources` in `pdf.yaml`), and `Get-GuidePdfToolchain` for diagnostics, then `New-GuidePdf` with the same selections. Change the look by editing the site's PDF configuration in a reviewed change, not by passing options. Do not silently substitute fonts or install packages. The command passes the filename/default language to Pandoc metadata and never needs lang in Hugo front matter. For an authorized replacement, pass the reviewed existing PDF SHA-256 as ExpectedOutputSha256 to New-GuidePdf. A stale hash requires fresh review, not deleting the old file or blindly refreshing the hash. Failed generation preserves the previous PDF. Test-GuidePdfCache accepts the current plan, prior receipt and observed toolchain. Reuse requires an EnvironmentSha256 covering approved fonts, TeX packages and indirect resources; without that evidence it refuses reuse. Never invent this digest or use timestamps as proof of freshness. Cooperative locks do not prevent other editors ignoring them. diff --git a/system/OpenGuidePlatform.PowerShell.Core/OpenGuidePlatform.PowerShell.Core.psd1 b/system/OpenGuidePlatform.PowerShell.Core/OpenGuidePlatform.PowerShell.Core.psd1 index 623a230a..207501ad 100644 --- a/system/OpenGuidePlatform.PowerShell.Core/OpenGuidePlatform.PowerShell.Core.psd1 +++ b/system/OpenGuidePlatform.PowerShell.Core/OpenGuidePlatform.PowerShell.Core.psd1 @@ -4,7 +4,7 @@ GUID='67db96a0-183a-452a-a09a-494526b6cf60' Author='OpenGuidePlatform contributors' PowerShellVersion='7.4' - FunctionsToExport=@('Get-GuideTranslationWork','New-GuideTranslation','Test-GuideTranslation','Set-GuideTranslation','Get-GuideContent','Set-GuideContent','Read-GuideDocument','Get-GuideLegacyAliasTargets','Test-GuideLegacyAliases','Get-GuideForbiddenPaths','Save-GuidePdfReceipt','Get-GuidePdfReceipts','Resolve-GuideWorkspacePath','Get-GuideLanguage','Test-GuideWritePolicy','Get-GuideTranslationState','Get-GuidePolicyFinding','Test-GuidePublicationPolicy','Import-GuidePolicy','Get-GuideInventory','New-GuideTranslationScaffold','Set-GuideWrapperTranslation','Get-GuideGravatar','New-GuideEdition','New-GuideContributions','Update-GuideContributions','Get-GuideCredits','Get-GuidePdfDeclaredDownloads','Get-GuidePdfPlan','Get-GuidePdfToolchain','New-GuidePdf','Test-GuidePdfCache','Get-GuideWrapperStatus','Get-GuideAssessment','Get-GuideDownloadRequirements','Test-GuideDownloadPublication') + FunctionsToExport=@('Get-GuideTranslationWork','New-GuideTranslation','Test-GuideTranslation','Set-GuideTranslation','Get-GuideContent','Set-GuideContent','Read-GuideDocument','Get-GuideLegacyAliasTargets','Test-GuideLegacyAliases','Get-GuideForbiddenPaths','Save-GuidePdfReceipt','Get-GuidePdfReceipts','Resolve-GuideWorkspacePath','Get-GuideLanguage','Test-GuideWritePolicy','Get-GuideTranslationState','Get-GuidePolicyFinding','Test-GuidePublicationPolicy','Import-GuidePolicy','Get-GuideInventory','New-GuideTranslationScaffold','Set-GuideWrapperTranslation','Get-GuideGravatar','New-GuideEdition','New-GuideContributions','Update-GuideContributions','Get-GuideCredits','Get-GuidePdfDeclaredDownloads','Get-GuidePdfPlan','Get-GuidePdfToolchain','Test-GuidePdfFonts','New-GuidePdf','Test-GuidePdfCache','Get-GuideWrapperStatus','Get-GuideAssessment','Get-GuideDownloadRequirements','Test-GuideDownloadPublication') CmdletsToExport=@() VariablesToExport=@() AliasesToExport=@() diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Get-GuidePdfPlan.ps1 b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Get-GuidePdfPlan.ps1 index ed2ffd05..1d39f6e9 100644 --- a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Get-GuidePdfPlan.ps1 +++ b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Get-GuidePdfPlan.ps1 @@ -71,6 +71,9 @@ function Get-GuidePdfPlan { if ($direction -eq 'rtl') { foreach($key in @('title','short_title','tagline','based_on','licence','watermark')){ if($metadata.Contains($key)){ $metadata[$key]=Format-GuidePdfText $metadata[$key] $true } } + foreach($key in @('edition','date')){ if($metadata.Contains($key)){ $metadata[$key]=Format-GuidePdfText $metadata[$key] $true -Numeric } } + # babel's default XeTeX bidi mode loses colour changes in right-to-left text; bidi-r keeps them. + $metadata.babeloptions=@('bidi=bidi-r','provide=*') foreach($key in @($metadata.labels.Keys)){ $metadata.labels[$key]=Format-GuidePdfText $metadata.labels[$key] $true } foreach($credit in @($metadata.authors)+@($metadata.contributors)+@($metadata.translators)){ $credit.name=Format-GuidePdfText $credit.name $true } } @@ -106,6 +109,12 @@ function Get-GuidePdfPlan { $fonts=[ordered]@{} foreach($key in $script:GuidePdfFontKeys){ if(-not [string]::IsNullOrWhiteSpace([string]$settings[$key])){ $fonts[$key]=[string]$settings[$key] } } + # Each required font with the settings file that chose it and, when recorded, where to get it. + $sources=if($settings['fontSources'] -is [Collections.IDictionary]){$settings['fontSources']}else{@{}} + $fontRequirements=@(foreach($key in $fonts.Keys){ + $source=$null; foreach($name in $sources.Keys){ if($name -ieq $fonts[$key]){ $source=[string]$sources[$name] } } + [pscustomobject]@{Key=$key;Font=$fonts[$key];SetBy=$(if($recipe.FontOrigins.ContainsKey($key)){$recipe.FontOrigins[$key]}else{'platform/pdf.yaml'});Source=$source} + }) $workspaceFiles=@(@("$($selection.RelativePath)/$filename")+$resources+@($credits.Files)+@($labels.Files)|Select-Object -Unique) $fingerprints=@(foreach($path in $workspaceFiles){ $full=Resolve-GuideWorkspacePath $WorkspaceRoot $path @@ -116,7 +125,7 @@ function Get-GuidePdfPlan { $metadataJson=$metadata|ConvertTo-Json -Depth 20 -Compress [pscustomobject]@{ WorkspaceRoot=[IO.Path]::GetFullPath($WorkspaceRoot);Guide=$GuideId;Edition=$EditionId;Language=$resolvedLanguage;Input=$inputPath;Output=$output;RelativeOutput=$relative - Arguments=$arguments;Includes=@($includes.ToArray());Metadata=$metadata;Settings=$settings;Fonts=$fonts;Recipe=@($recipe.Files|Select-Object Level,Kind,@{n='Path';e={if($_.Relative){$_.Relative}else{"platform/$([IO.Path]::GetRelativePath((Get-GuidePdfPlatformRoot),$_.Path).Replace('\','/'))"}}}) + Arguments=$arguments;Includes=@($includes.ToArray());Metadata=$metadata;Settings=$settings;Fonts=$fonts;FontRequirements=$fontRequirements;Recipe=@($recipe.Files|Select-Object Level,Kind,@{n='Path';e={if($_.Relative){$_.Relative}else{"platform/$([IO.Path]::GetRelativePath((Get-GuidePdfPlatformRoot),$_.Path).Replace('\','/'))"}}}) Fingerprints=$fingerprints MetadataSha256=[Convert]::ToHexString([Security.Cryptography.SHA256]::HashData([Text.Encoding]::UTF8.GetBytes($metadataJson))).ToLowerInvariant() PlatformSha256=[Convert]::ToHexString([Security.Cryptography.SHA256]::HashData([Text.Encoding]::UTF8.GetBytes($platformEvidence))).ToLowerInvariant() @@ -142,13 +151,9 @@ function New-GuidePdf { if ($ExpectedOutputSha256 -and (-not $replacing -or (Get-FileHash -LiteralPath $plan.Output).Hash -ne $ExpectedOutputSha256)) { throw 'PDF changed since review or is missing.' } $toolchain=@(Get-GuidePdfToolchain) if (@($toolchain | Where-Object { $_.Tool -in @('pandoc','xelatex') -and -not $_.Available }).Count) { throw 'PDF generation requires Pandoc and XeLaTeX. Other Core commands do not.' } - $fontCommand=Get-Command fc-list -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1 - if($plan.Fonts.Count -and $null -eq $fontCommand){throw 'Font diagnostics require fc-list for explicitly selected fonts.'} - if($fontCommand) { - $families=@(& $fontCommand.Source --format '%{family}\n') - if($LASTEXITCODE -ne 0){throw 'Font enumeration failed.'} - $available=@($families | ForEach-Object { $_ -split ',' } | ForEach-Object { $_.Trim() }) - foreach($font in $plan.Fonts.Values){if($font -notin $available){throw "Font is not installed: $font. Install it or change the font in the site's pdf settings; no fonts are installed or substituted automatically."}} + if(@($plan.FontRequirements).Count){ + $missing=@(Get-GuidePdfMissingFonts $plan.FontRequirements) + if($missing.Count){ throw (Format-GuidePdfMissingFonts $missing "$($plan.RelativeOutput)") } } if ($PSCmdlet.ShouldProcess($plan.Output,'Generate a guide PDF with explicit language metadata')) { [IO.Directory]::CreateDirectory([IO.Path]::GetDirectoryName($plan.Output))|Out-Null @@ -206,6 +211,55 @@ function New-GuidePdf { } } +function Get-GuideInstalledFontFamilies { + # Font families visible to XeTeX's fontconfig. $null when fc-list is unavailable. + $command=Get-Command fc-list -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1 + if($null -eq $command){ return $null } + $families=@(& $command.Source --format '%{family}\n') + if($LASTEXITCODE -ne 0){ throw 'Font enumeration with fc-list failed.' } + ,@($families | ForEach-Object { $_ -split ',' } | ForEach-Object { $_.Trim() } | Where-Object { $_ } | Sort-Object -Unique) +} + +function Get-GuidePdfMissingFonts { + param([object[]]$Requirements) + $installed=Get-GuideInstalledFontFamilies + if($null -eq $installed){ throw 'Checking fonts needs fc-list, which ships with the TeX distribution (MiKTeX or TeX Live). Install it and run again.' } + @($Requirements|Where-Object { $installed -inotcontains $_.Font }) +} + +function Format-GuidePdfMissingFonts { + param([object[]]$Missing,[string]$Subject) + $lines=foreach($group in $Missing|Group-Object Font){ + $first=$group.Group[0] + $uses=(@($group.Group|ForEach-Object Key|Select-Object -Unique) -join ', ') + $where=if($first.Source){"Get it from $($first.Source)"}else{"No source is recorded; add it under fontSources in $($first.SetBy)"} + " - $($group.Name) ($uses, set in $($first.SetBy)). $where" + } + "Missing fonts for $($Subject): +$($lines -join " +") +Install them and run again. Fonts are never installed or substituted automatically." +} + +function Test-GuidePdfFonts { + <# + Reports every font the site's generated PDFs need and whether it is installed, + with the settings file that chose it and where to get it. + #> + [CmdletBinding()] + param([Parameter(Mandatory)][string]$WorkspaceRoot,[Parameter(Mandatory)][System.Collections.IDictionary]$Policy) + $installed=Get-GuideInstalledFontFamilies + foreach($guide in $Policy.guides){ foreach($edition in $guide.editions){ foreach($translation in $edition.translations){ + foreach($download in @($translation.downloads|Where-Object { $_.handling -eq 'generated' })){ + try{ $plan=Get-GuidePdfPlan -WorkspaceRoot $WorkspaceRoot -Policy $Policy -GuideId $guide.id -EditionId $edition.id -Language $translation.language -DownloadPath $download.path } + catch{ [pscustomobject]@{Pdf="$($guide.contentRoot)/$($edition.path)/$($download.path)";Language=$translation.language;Key=$null;Font=$null;SetBy=$null;Source=$null;Installed=$null;Problem=$_.Exception.Message}; continue } + foreach($requirement in $plan.FontRequirements){ + [pscustomobject]@{Pdf=$plan.RelativeOutput;Language=$plan.Language;Key=$requirement.Key;Font=$requirement.Font;SetBy=$requirement.SetBy;Source=$requirement.Source;Installed=$(if($null -eq $installed){$null}else{$installed -icontains $requirement.Font});Problem=$null} + } + } + }}} +} + function Invoke-GuidePandoc { param([string[]]$Arguments) & pandoc @Arguments | Out-Host diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Resolve-GuidePdfRecipe.ps1 b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Resolve-GuidePdfRecipe.ps1 index 4ddd4ee5..3166965e 100644 --- a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Resolve-GuidePdfRecipe.ps1 +++ b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/Resolve-GuidePdfRecipe.ps1 @@ -1,5 +1,5 @@ $script:GuidePdfFontKeys=@('mainfont','sansfont','monofont','CJKmainfont','CJKsansfont','CJKmonofont') -$script:GuidePdfSettingKeys=@('mainfont','sansfont','monofont','CJKmainfont','CJKsansfont','CJKmonofont','papersize','geometry','fontsize','toc','tocDepth','watermark','licence','parts','cover','downloads') +$script:GuidePdfSettingKeys=@('mainfont','sansfont','monofont','CJKmainfont','CJKsansfont','CJKmonofont','papersize','geometry','fontsize','toc','tocDepth','watermark','licence','parts','cover','fontSources','downloads') $script:GuidePdfCoverKeys=@('tagline','contributorRoles','translatorRoles') $script:GuidePdfParts=@('cover','licence','body','back') $script:GuidePdfTemplates=[ordered]@{style='header';'page-header'='header';'page-footer'='header';cover='before';licence='before';back='after'} @@ -39,6 +39,10 @@ function Test-GuidePdfSettings { if($Settings.cover -isnot [Collections.IDictionary]){'cover must be a mapping.'} else{foreach($key in $Settings.cover.Keys){if($key -cnotin $script:GuidePdfCoverKeys){"Unknown cover setting '$key'."}}} } + if($Settings.Contains('fontSources')){ + if($Settings.fontSources -isnot [Collections.IDictionary]){'fontSources must map font names to where to get them.'} + else{foreach($font in $Settings.fontSources.Keys){if([string]::IsNullOrWhiteSpace([string]$Settings.fontSources[$font])){"fontSources for '$font' is empty."}}} + } if($Settings.Contains('parts')){ $parts=@($Settings.parts) foreach($part in $parts){if($part -cnotin $script:GuidePdfParts){"Unknown part '$part'. Use: $($script:GuidePdfParts -join ', ')."}} @@ -78,7 +82,7 @@ function Merge-GuidePdfSettings { param([Collections.IDictionary]$Target,[Collections.IDictionary]$Source) foreach($key in $Source.Keys){ if($key -ceq 'downloads'){continue} - if($key -ceq 'cover' -and $Target[$key] -is [Collections.IDictionary] -and $Source[$key] -is [Collections.IDictionary]){ + if($key -cin @('cover','fontSources') -and $Target[$key] -is [Collections.IDictionary] -and $Source[$key] -is [Collections.IDictionary]){ foreach($inner in $Source[$key].Keys){$Target[$key][$inner]=$Source[$key][$inner]} }elseif($Source[$key] -is [Collections.IDictionary]){ $copy=[ordered]@{};foreach($inner in $Source[$key].Keys){$copy[$inner]=$Source[$key][$inner]};$Target[$key]=$copy @@ -99,6 +103,7 @@ function Resolve-GuidePdfRecipe { $files=[Collections.Generic.List[object]]::new() function Use($level,$path,$kind){$files.Add([pscustomobject]@{Level=$level.Name;Kind=$kind;Path=$path;Relative=$(if($level.Relative){"$($level.Relative)/$([IO.Path]::GetRelativePath($level.Path,$path).Replace('\','/'))"}else{$null})})} $download=$null + $origins=@{} foreach($level in $levels){ foreach($name in @('pdf.yaml',"pdf.$Language.yaml")){ $path=Join-Path $level.Path $name @@ -106,6 +111,7 @@ function Resolve-GuidePdfRecipe { $display=if($level.Relative){"$($level.Relative)/$name"}else{"platform/$name"} $values=Read-GuidePdfSettingsFile $path $level.Name $display Merge-GuidePdfSettings $settings $values + foreach($key in $script:GuidePdfFontKeys){ if($values.Contains($key)){ $origins[$key]=$display } } if($level.Name -eq 'edition' -and $values.Contains('downloads')){ $declared=@($values.downloads|Where-Object {[string]$_.path -ceq $DownloadPath}) if($declared.Count){$download=$declared[-1]} @@ -133,7 +139,7 @@ function Resolve-GuidePdfRecipe { } foreach($filter in $filters.Values){Use $filter.Level $filter.Lua filter;if($filter.Header){Use $filter.Level $filter.Header filter-header}} $resources=@($levels[($levels.Count-1)..0]|ForEach-Object {Join-Path $_.Path 'images'}|Where-Object {[IO.Directory]::Exists($_)}) - [pscustomobject]@{Settings=$settings;Templates=$templates;Filters=@($filters.Values|Sort-Object Name);ResourcePaths=$resources;Files=@($files.ToArray());Download=$download} + [pscustomobject]@{Settings=$settings;FontOrigins=$origins;Templates=$templates;Filters=@($filters.Values|Sort-Object Name);ResourcePaths=$resources;Files=@($files.ToArray());Download=$download} } function Get-GuidePdfLabels { @@ -214,10 +220,11 @@ function Format-GuidePdfText { # Metadata strings are read as Markdown. In a right-to-left document, text # without any RTL characters is wrapped in an LTR span so bidi keeps Latin # word order (Pandoc writes \LR{...}). - param([string]$Text,[bool]$RightToLeft) - if(-not $RightToLeft -or [string]::IsNullOrWhiteSpace($Text) -or $Text -match '[֐-ࣿיִ-﷿ﹰ-]' -or $Text -notmatch '\p{L}'){return $Text} + param([string]$Text,[bool]$RightToLeft,[switch]$Numeric) + # -Numeric also wraps letterless values such as editions and dates ("2025.7"). + if(-not $RightToLeft -or [string]::IsNullOrWhiteSpace($Text) -or $Text -match '[\u0590-\u08FF\uFB1D-\uFDFF\uFE70-\uFEFF]' -or ($Text -notmatch '\p{L}' -and -not $Numeric)){return $Text} # The trailing LEFT-TO-RIGHT MARK keeps closing punctuation with the Latin run. - '['+($Text -replace '([\\\[\]])','\$1')+[char]0x200E+']{dir=ltr}' + '['+($Text -replace '([\\\[\]])','\$1')+[char]0x200E+']{lang=en}' } function ConvertTo-GuideLatexPath { diff --git a/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/filters/rtl-latin.lua b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/filters/rtl-latin.lua new file mode 100644 index 00000000..a564b532 --- /dev/null +++ b/system/OpenGuidePlatform.PowerShell.Core/PdfPublishing/templates/filters/rtl-latin.lua @@ -0,0 +1,77 @@ +-- Keep Latin text in its own order inside right-to-left PDFs. +-- XeTeX's right-to-left handling does not reorder runs of Latin words, so +-- "(Knowledge Work)" inside Persian text would print as "Work) (Knowledge". +-- In documents whose metadata sets dir: rtl, this filter marks each run of +-- Latin text as English (Pandoc writes \foreignlanguage{english}{...}) and +-- each paragraph with no right-to-left letters as an English block. +-- Other documents are returned unchanged. + +local rtl_pattern = "[\216-\219]" -- UTF-8 lead bytes of U+0600..U+06FF (Arabic script) +local rtl_extra = {"\239\173", "\239\174", "\239\175", "\239\176", "\239\177", "\239\178", "\239\179", "\239\180", "\239\181", "\239\182", "\239\183", "\239\185", "\239\186", "\239\187"} + +local function has_rtl(text) + if text:find(rtl_pattern) then return true end + -- Hebrew (U+0590..U+05FF) and Arabic presentation forms (U+FB50..U+FEFF) + if text:find("\214[\144-\191]") or text:find("\215") then return true end + for _, prefix in ipairs(rtl_extra) do + if text:find(prefix, 1, true) then return true end + end + return false +end + +local function has_latin(text) + return text:find("[A-Za-z]") ~= nil +end + +local function classify(inline) + if inline.t == "Space" or inline.t == "SoftBreak" or inline.t == "LineBreak" then return "N" end + local text = pandoc.utils.stringify(inline) + if has_rtl(text) then return "R" end + if has_latin(text) then return "L" end + return "N" +end + +local function mark_latin_runs(inlines) + local result = pandoc.List() + local i, n = 1, #inlines + while i <= n do + if classify(inlines[i]) == "L" then + -- Extend over Latin items and the neutral items between them. + local last = i + local j = i + 1 + while j <= n do + local kind = classify(inlines[j]) + if kind == "R" then break end + if kind == "L" then last = j end + j = j + 1 + end + local run = pandoc.List() + for k = i, last do run:insert(inlines[k]) end + result:insert(pandoc.Span(run, pandoc.Attr("", {}, {lang = "en"}))) + i = last + 1 + else + result:insert(inlines[i]) + i = i + 1 + end + end + return result +end + +local function latin_only(block) + local text = pandoc.utils.stringify(block) + return has_latin(text) and not has_rtl(text) +end + +function Pandoc(doc) + if pandoc.utils.stringify(doc.meta.dir or "") ~= "rtl" then return nil end + -- Only the body: metadata (babel options, cover values) must stay untouched. + local blocks = doc.blocks:walk({ + Para = function(el) + if latin_only(el) then return pandoc.Div({el}, pandoc.Attr("", {}, {lang = "en"})) end + return nil + end, + }) + -- Nested marks (an English span inside an English block) are harmless. + blocks = blocks:walk({Inlines = mark_latin_runs}) + return pandoc.Pandoc(blocks, doc.meta) +end diff --git a/system/OpenGuidePlatform.PowerShell.Core/README.md b/system/OpenGuidePlatform.PowerShell.Core/README.md index 6241349c..fea1318e 100644 --- a/system/OpenGuidePlatform.PowerShell.Core/README.md +++ b/system/OpenGuidePlatform.PowerShell.Core/README.md @@ -29,6 +29,8 @@ PDF language comes from the filename suffix or declared source language and is p `cover.tex`, `licence.tex`, `back.tex`, `page-header.tex`, `page-footer.tex` and `style.tex` are Pandoc templates (write a literal `$` as `$$`); the most specific file, including a `..tex` variant, replaces the default. `filters/.lua` accumulate across levels, a same-named file replacing a less specific one, and an optional `filters/.tex` is included in the preamble. The platform ships a Hugo image-path filter and a callouts filter for `> [!NOTE]` blocks. Templates receive `title`, `short_title`, `date`, `edition`, `guide`, `authors`, `contributors`, `translators` (each with `name`, `role`, optional `url`), `labels` (from the site i18n ids `pdf_authors_label`, `pdf_contributors_label`, `pdf_translators_label`, `pdf_edition_label`, `pdf_based_on_label` and `pdf_callout_*`, with English defaults), `tagline`, `based_on` (from `forked_from`), `logo` (`content//images/-logo.png`), `licence`, `watermark` and, for right-to-left languages, `dir`. Direction comes from the Hugo language `direction` (or `languageDirection`). Pandoc's own title block is suppressed; the cover replaces it. Japanese and other CJK text needs `CJKmainfont`. +Fonts are never installed or substituted. `fontSources` in any `pdf.yaml` maps a font name to where to get it (a URL or a short note); `Test-GuidePdfFonts -WorkspaceRoot ... -Policy ...` lists every font the site's generated PDFs need, whether it is installed, the settings file that chose it and its source. `New-GuidePdf` checks all fonts first and reports every missing one with the same details. For right-to-left languages the platform switches babel to `bidi=bidi-r` (the default XeTeX mode loses colour changes) and the `rtl-latin` filter marks Latin runs and Latin-only paragraphs as English so their word and digit order survive; cover values are marked the same way. + This module enforces the supplied policy, not the authenticity of that policy. GuideSite packages distribute these commands through installation and Update. Independent enforcement requires the AgentControls evaluator to be configured with an external trusted baseline; installing skills does not configure that enforcement. ## Correct an existing guide diff --git a/tests/Core/GuidePdfRecipe.Tests.ps1 b/tests/Core/GuidePdfRecipe.Tests.ps1 index ffdaccb0..f4651190 100644 --- a/tests/Core/GuidePdfRecipe.Tests.ps1 +++ b/tests/Core/GuidePdfRecipe.Tests.ps1 @@ -47,6 +47,7 @@ Describe 'Layered PDF recipe' { $plan.Metadata.licence | Should -Be 'CC BY-SA 4.0' $plan.Metadata.labels.authors | Should -Be 'Authors' $plan.Metadata.Contains('dir') | Should -BeFalse + $plan.Metadata.Contains('babeloptions') | Should -BeFalse $plan.Arguments | Should -Contain 'title=' $plan.Arguments | Should -Contain 'lang=en' $plan.Fingerprints.Path | Should -Contain "site/data/contributions/$($guide.id).yml" @@ -55,10 +56,13 @@ Describe 'Layered PDF recipe' { Write-Fixture 'site/i18n/fa.yaml' "- id: pdf_translators_label`n translation: مترجمان`n" $plan=Get-GuidePdfPlan $workspace $policy $guide.id $edition.id fa 'pdf/guide.fa.pdf' $plan.Metadata.dir | Should -Be 'rtl' - $plan.Metadata.translators[0].name | Should -Be "[Parisa Translator$([char]0x200E)]{dir=ltr}" + $plan.Metadata.translators[0].name | Should -Be "[Parisa Translator$([char]0x200E)]{lang=en}" $plan.Metadata.labels.translators | Should -Be 'مترجمان' $plan.Metadata.title | Should -Be 'راهنمای نمونه' @($plan.Includes|Where-Object Part -eq 'rtl').Count | Should -Be 1 + $plan.Metadata.edition | Should -BeLike '*2024.8*{lang=en}' -Because 'digits and dots keep their order in right-to-left text' + $plan.Metadata.babeloptions | Should -Contain 'bidi=bidi-r' -Because 'the default XeTeX bidi mode loses colour changes' + @(for($i=0;$i -lt $plan.Arguments.Count;$i++){if($plan.Arguments[$i] -eq '--lua-filter'){[IO.Path]::GetFileName($plan.Arguments[$i+1])}}) | Should -Contain 'rtl-latin.lua' $plan.Fingerprints.Path | Should -Contain 'site/i18n/fa.yaml' } It 'uses the most specific template for each part and places parts around the body' { @@ -131,3 +135,33 @@ Describe 'Rendering template parts' { @(Get-ChildItem (Join-Path $workspace "$($guide.contentRoot)/$($edition.path)/pdf") -Force).Count | Should -Be 1 -Because 'staging is removed' } } +Describe 'Missing font reporting' { + BeforeEach { + $policy=Get-Content -Raw (Join-Path $root 'tests/Contracts/fixtures/single-guide.site-policy.json')|ConvertFrom-Json -AsHashtable + $policy.protectedPaths=@();$policy.guides[0].protectSource=$false + $guide=$policy.guides[0];$edition=$guide.editions[0] + $edition.translations=@(@{language='en';intent='web';downloads=@(@{path='pdf/guide.en.pdf';handling='generated'})},@{language='ja';intent='web';downloads=@(@{path='pdf/guide.ja.pdf';handling='generated'})}) + $workspace=Join-Path $TestDrive ([guid]::NewGuid().ToString('N')) + Write-Fixture "$($guide.contentRoot)/$($edition.path)/index.md" "---`ntitle: Example`n---`nBody" + Write-Fixture "$($guide.contentRoot)/$($edition.path)/index.ja.md" "---`ntitle: 例`n---`n本文" + Write-Fixture 'site/pdf/pdf.yaml' "mainfont: Installed Serif`nsansfont: Absent Sans`nfontSources:`n Absent Sans: https://fonts.example/absent-sans`n" + Write-Fixture 'site/pdf/pdf.ja.yaml' "mainfont: Absent JP`nCJKmainfont: Absent JP`n" + Mock Get-GuidePdfToolchain -ModuleName OpenGuidePlatform.PowerShell.Core { @([pscustomobject]@{Tool='pandoc';Available=$true},[pscustomobject]@{Tool='xelatex';Available=$true}) } + Mock Get-GuideInstalledFontFamilies -ModuleName OpenGuidePlatform.PowerShell.Core { ,@('Installed Serif') } + Mock Invoke-GuidePandoc -ModuleName OpenGuidePlatform.PowerShell.Core { 0 } + } + It 'lists every missing font with where it was set and where to get it' { + $message=$null + try { New-GuidePdf $workspace $policy $guide.id $edition.id ja 'pdf/guide.ja.pdf' } catch { $message=$_.Exception.Message } + $message | Should -Match 'Missing fonts for .*guide\.ja\.pdf' + $message | Should -Match 'Absent JP \(mainfont, CJKmainfont, set in site/pdf/pdf\.ja\.yaml\)\. No source is recorded' + $message | Should -Match 'Absent Sans \(sansfont, set in site/pdf/pdf\.yaml\)\. Get it from https://fonts\.example/absent-sans' + $message | Should -Not -Match 'Installed Serif' + Should -Invoke Invoke-GuidePandoc -ModuleName OpenGuidePlatform.PowerShell.Core -Times 0 + } + It 'reports font status for every generated PDF' { + $report=@(Test-GuidePdfFonts $workspace $policy) + @($report|Where-Object { $_.Installed -eq $false }|ForEach-Object Font|Sort-Object -Unique) | Should -Be @('Absent JP','Absent Sans') + ($report|Where-Object { $_.Pdf -like '*guide.en.pdf' -and $_.Key -eq 'mainfont' }).Installed | Should -BeTrue + } +} From 1ef1a467b6ad70e89db97f259d535f49edf6be32 Mon Sep 17 00:00:00 2001 From: Martin Hinshelwood Date: Wed, 23 Sep 2026 16:52:03 +0100 Subject: [PATCH 4/4] Warn, not block, on a translation team file without its translation The packaged contributor workflow deletes and re-creates a translation; its team file must remain valid meanwhile. An unknown guide still blocks. Co-Authored-By: Claude Opus 5.5 --- .../Assessment/Get-GuideAssessment.ps1 | 2 +- .../ContributorManagement/Get-GuideCredits.ps1 | 3 ++- tests/Core/GuideCredits.Tests.ps1 | 3 ++- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/system/OpenGuidePlatform.PowerShell.Core/Assessment/Get-GuideAssessment.ps1 b/system/OpenGuidePlatform.PowerShell.Core/Assessment/Get-GuideAssessment.ps1 index dddd8acd..d39f8f2d 100644 --- a/system/OpenGuidePlatform.PowerShell.Core/Assessment/Get-GuideAssessment.ps1 +++ b/system/OpenGuidePlatform.PowerShell.Core/Assessment/Get-GuideAssessment.ps1 @@ -62,7 +62,7 @@ function Get-GuideAssessment { [ordered]@{id=$guide.id;editions=$editions} }) # Contributor records and PDF configuration are site-wide source conventions. - $conventionScopes=@{CONTRIBUTOR_FILE_UNKNOWN='guide';CONTRIBUTOR_FILE_AMBIGUOUS='guide';CONTRIBUTOR_RECORD_INVALID='guide';CONTRIBUTOR_EDITION_UNKNOWN='guide';CREATORS_MISSING='edition';TRANSLATORS_MISSING='translation';PDF_SETTINGS_INVALID='download';PDF_LABEL_MISSING='wrapper'} + $conventionScopes=@{CONTRIBUTOR_FILE_UNKNOWN='guide';CONTRIBUTOR_FILE_UNUSED='guide';CONTRIBUTOR_FILE_AMBIGUOUS='guide';CONTRIBUTOR_RECORD_INVALID='guide';CONTRIBUTOR_EDITION_UNKNOWN='guide';CREATORS_MISSING='edition';TRANSLATORS_MISSING='translation';PDF_SETTINGS_INVALID='download';PDF_LABEL_MISSING='wrapper'} try { foreach($finding in @(Get-GuideContributorFindings $WorkspaceRoot $Policy)+@(Get-GuidePdfSettingFindings $WorkspaceRoot $Policy)){ Add-Finding $finding.Code $conventionScopes[$finding.Code] $finding.Subject $finding.Message $finding.Remediation $finding.Severity diff --git a/system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/Get-GuideCredits.ps1 b/system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/Get-GuideCredits.ps1 index 3670bcc9..54d2dca9 100644 --- a/system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/Get-GuideCredits.ps1 +++ b/system/OpenGuidePlatform.PowerShell.Core/ContributorManagement/Get-GuideCredits.ps1 @@ -117,7 +117,8 @@ function Get-GuideContributorFindings { $editionIds=@($guide.editions|ForEach-Object {[string]$_.id}) if($file.Language){ $declared=@($guide.editions|ForEach-Object {$edition=$_;$_.translations|Where-Object {$_.language -ine $edition.sourceLanguage}|ForEach-Object {$_.language}}) - if($declared -inotcontains $file.Language){Add CONTRIBUTOR_FILE_UNKNOWN $file.Relative "No edition of $($file.GuideId) declares a $($file.Language) translation." 'Remove the file or add the translation it describes.';continue} + # A translation may be missing while it is being (re)created; its team file is kept. + if($declared -inotcontains $file.Language){Add CONTRIBUTOR_FILE_UNUSED $file.Relative "No edition of $($file.GuideId) has a $($file.Language) translation yet." 'Keep the file while the translation is in progress; otherwise remove it.' warning;continue} } try{$records=@(Read-GuideContributionFile $file.Path)}catch{Add CONTRIBUTOR_RECORD_INVALID $file.Relative $_.Exception.Message 'Correct the YAML so the file is a list of contributor records.';continue} $roles=if($file.Language){$script:GuideTranslationRoles}else{$script:GuideContributorRoles} diff --git a/tests/Core/GuideCredits.Tests.ps1 b/tests/Core/GuideCredits.Tests.ps1 index 43d8795d..c01d50a3 100644 --- a/tests/Core/GuideCredits.Tests.ps1 +++ b/tests/Core/GuideCredits.Tests.ps1 @@ -75,7 +75,8 @@ Describe 'Contributor records and credits' { $codes=@(Find-ContributorIssues $workspace $policy|ForEach-Object Code) $codes | Should -Contain CONTRIBUTOR_RECORD_INVALID $codes | Should -Contain CONTRIBUTOR_EDITION_UNKNOWN - @($codes|Where-Object {$_ -eq 'CONTRIBUTOR_FILE_UNKNOWN'}).Count | Should -Be 2 + @($codes|Where-Object {$_ -eq 'CONTRIBUTOR_FILE_UNKNOWN'}).Count | Should -Be 1 -Because 'an unknown guide is an error' + (Find-ContributorIssues $workspace $policy|Where-Object Code -eq CONTRIBUTOR_FILE_UNUSED).Severity | Should -Be warning -Because 'a translation team may exist before or while its translation does' } It 'warns about missing creators and translators only when the site keeps contributor data' { Remove-Item (Join-Path $workspace "$data/example.fa.yml")