/index.md: omit
```
-versus ours:
-
-```html
-Configuration
+- A directory key keeps its three modes (§5). `omit` drops the section without a title or a note (D14).
+ The first implementation (P8) left both; the imprint names the online edition as the complete
+ reference instead.
+- A page key accepts `omit` only; any other mode fails the build. The page is dropped without a note.
+- Dropping the index page of a section keeps its other pages, under a heading with the section's
+ navigation title - the shape Release Notes already has (§3).
+- **Scope of the first edition (decided 2026-09-16, backlog P26):** it is a user guide, so the parts an
+ administrator or a developer needs are omitted whole - E `deploy-and-configure/` (34 pages) and
+ G `develop/` (89 pages). The narrower `develop/cmem-client-api/` key goes with it, because keys do not
+ nest. A reference from a printed page into an omitted part is not lost: it becomes a web address in its
+ part's endnote list (D15), pointing at the online edition.
+- Keys do not nest: a key inside a directory that another key shortens fails the build.
+- A key that matches no page in `nav.yml` fails the build, as today.
+- A link to a dropped page prints the page's online address in a footnote, like any link that leaves
+ the book (R4). Within a section that `list` or `omit` shortens, it prints as text, as today.
+
+#### Parts of a page: the class `print-exclude` (D13)
+
+One class, spelled the way the element takes it:
+
+````markdown
+??? example print-exclude "INSERT query"
+
+ ```sql
+ INSERT INTO product(...) VALUES ...
+ ```
+
+```{ .sql .print-exclude }
+SELECT ...
```
-Now that §1-§8 generate those anchors, every one of these links has a valid destination.
-The anchors exist; nothing points at them.
-
-### Approach: template override, *not* post-build injection
-
-`zensical/templates/partials/tags.html` is **byte-identical to Material 9.7.7's**. It
-already contains the branch that produces a link:
-
-```jinja
-{% if tag.url %}
- {{ tag.name }}
-{% else %}
- {{ tag.name }}
-{% endif %}
-```
-
-The template is not the problem - `tag.url` is simply never populated, because Zensical has
-no listing index to point at. So the fix is to compute the URL in an override rather than
-depend on `tag.url`, exactly as `overrides/partials/tabs-item.html` does for tab icons.
-
-This is strictly better than extending `render_tag_listings.py`:
-
-| | template override | post-build injection |
-| :-- | :-- | :-- |
-| Works in `task serve` | **yes** | no (see §6) |
-| Extra build step | none | another pass over 531 pages |
-| Removal when #38 lands | delete one file | more code to unpick |
-
-### Verified feasible
-
-A spike produced output byte-identical to production's, then was reverted. MiniJinja
-supports the three filters needed (`url`, `lower`, `replace`):
-
-```jinja
-{% set anchor = "tags/" | url ~ "#tag:" ~ (tag.name | lower | replace(" ", "-")) %}
-{{- tag.name -}}
+A paragraph the print edition leaves out.
+{ .print-exclude }
+
+
+
+Several blocks - also inside a list item, a content tab or an admonition.
+
+
+````
+
+- The print edition removes every element with the class from a page's article, before ids, links and
+ headings are processed. The class has no effect on the site and the screen PDF.
+- A heading inside a removed part leaves the numbering and the contents. Links to it print as text, the
+ rule for any link without a target.
+- The build logs how many parts it removed per page, so a marker that no longer matches shows.
+- A note takes the place of a removed part (D14): *This print edition leaves out a part of this page.
+ The online edition has the full details:* followed by the page's online address, with the anchor of
+ the heading the part belongs to. Consecutive removed parts share one note.
+- In the Snowflake tutorial the class goes on the SQL code block, as `{ .sql .print-exclude }` on its
+ opening fence: exactly lines 92-1094 are removed. The `??? example "INSERT query"` block around it keeps
+ its title and holds the note.
+- A generated page cannot carry the class: its generator has to emit it, or a path rule drops the page.
+- The name follows the edition. The site does not style the class; a later `@media print` rule could
+ use it for printing from the browser.
+
+### Implementation outline
+
+- **Rules:** `load_section_rules` accepts `.md` keys, rejects any mode but `omit` for them and rejects
+ nested keys.
+- **Page `omit`:** `apply_section_rules` drops the page's entry. For an index page it inserts a heading
+ entry with the navigation title, which `NavEntry.title` already carries.
+- **Parts:** in the print edition, `page_article` replaces the `.print-exclude` elements with the note -
+ one per run of consecutive parts - and counts them.
+- **`omit` for directories:** no title and no note any more. `test_omit_drops_the_pages_and_leaves_a_heading_with_a_note`
+ and `test_merge_renders_an_omitted_section_as_its_title_and_a_note` change with it.
+- **Tests:** `tests/test_build_pdf_print.py` gets page keys, the mode check, nesting, a dropped index
+ page, and the removal with its note and online address in the print edition only.
+- **Documentation:** the `sections` comment in `print.yml`, and for authors a line in
+ `.claude/docs-guidelines/repo-conventions.md` on the class, including that generated pages cannot
+ carry it.
+- **Effort:** small to medium; backlog P18.
+
+## 11. Review of the first print build
+
+**Status:** findings of the pull request review, 2026-09-15, decided the same day as D15-D18 (§4).
+P19-P24 and P13 are implemented; P15 keeps 42 images to replace or accept.
+
+| Finding | Today | Proposal | Backlog |
+| :-- | :-- | :-- | :-- |
+| A left-hand page's footer should read `Part A: Build` | `A Build` (R1) | the part label the part band prints | P19 |
+| Web addresses belong at the end of the document | a footnote for each link out of the book (R4) | endnotes, listed at the end of each part (D15) | P20 |
+| The author order should follow the printed content | commits to the whole repository (§3) | commits to the printed pages (D16) | P21 |
+| Facing cards in a two-column grid should be equally high | each card as high as its text | one height per row | P22 |
+| The operator reference should print descriptions and parameters | overview tables, `list` mode (§5) | one compact entry per operator, replacing the overview tables (D17) | P23 |
+| PDF/X-4 and CMYK | specified, not built (§7) | unchanged; done, with transparency rendered to images first | P13 |
+| Low-resolution images mostly lack `width` in the Markdown | an image without `width` prints at its declared density | widths written into the sources so every image prints at 150 ppi or better (D18, revised 2026-09-16); done, and P15 with it | P24, then P15 |
+
+### Footer: the part label
+
+R1 names the part beside the page number of a left-hand page as `A Build`. The part band already prints
+`Part A: Build`, while the contents and the bookmarks print `A Build`. The left-hand footer follows the
+band: `1234 Part A: Build`. The contents, the bookmarks and the right-hand footer stay as they are.
+
+### Web addresses as endnotes (D15)
+
+Today every link out of the book prints its address in a footnote on the same page (R4). Decided:
+
+- A link out of the book prints its text and a superscript number.
+- The numbers run within a part and start again at 1 in the next one. An address cited more than once in
+ a part keeps its first number there.
+- A list "Web addresses", on a new page under an unnumbered heading, closes each part that cites any. It
+ holds each number, its address and the pages that cite it, for example
+ `17 https://github.com/eccenca/cmemc (pp. 412, 530)`.
+- The list is laid out without link annotations, like the contents (P9). Footnotes link marker and entry
+ internally, which Typst cannot switch off, and PDF/X output wants no annotation at all (§7).
+- Links within the book keep their page reference.
+
+Numbering in a `context` rule over every link costs layout passes; measure the compile time and watch
+for Typst's warning that the layout did not converge.
+
+### Author order from the printed content (D16)
+
+Today `tools/pdf/authors.yml` counts a contributor's commits to the whole repository, from the GitHub
+contributors API. Tooling, generated references and content the print edition leaves out weigh as much
+as the printed pages. The repository has 1,633 commits, 1,292 of them touching `docs/`. Decided:
+
+- The printed files: the pages the print edition prints after the section rules (§5, §10), and the
+ images in their directories.
+- The commits: `git log --no-merges` for those files, following renames. A commit counts once, however
+ many printed files it touches.
+- The account of each commit: `author.login` from the GitHub commits API, which maps a commit's e-mail
+ to a GitHub account - one request per 100 commits, about 17.
+- The existing rules stay: no anonymous commits, bots or agents; `authors.exclude`; names from
+ `authors.names` or the profile.
+- `authors.yml` records these counts. The imprint reads "most commits to the printed pages first".
+
+Commits to generated pages credit whoever ran the generator, so they do not count.
+
+### Cards of equal height
+
+`cards()` sets `card()` blocks in two columns, each as high as its text, so facing cards end at
+different heights. Plan: lay the grid out row by row, measure both cards of a row at the column
+width, and give both the taller height. A card alone in the last row keeps its own height. The rounded
+frame and `breakable: false` stay. The screen PDF uses the same grid and changes with it.
+
+### The operator reference in a compact format (D17)
+
+A.3 prints as `list` (§5): the overview pages with their `Name | Description` tables, while the 389
+operator pages are dropped. The review asks for the operators themselves, with their descriptions and
+parameters but without examples. In the print edition the operator entries replace the overview tables.
+The format below was decided as proposed (D17).
+
+All 389 operators share one structure. `tools/templates/plugin.md` generates their pages, and the
+generator dumps the same data to `data/plugins.json`, which is tracked and was last regenerated together
+with the pages on 2026-09-02. Much of the structure is sparse (measured 2026-09-15):
+
+| Part | Measured |
+| :-- | :-- |
+| parameters | 1,040 in all; 59 operators have none, 316 have no advanced ones. Median per operator: 4 for custom workflow tasks (at most 24), 3 for datasets, 1 for distance measures and transformers, 0 for aggregators |
+| defaults | 431 parameters have none; 8 are multi-line, 4 structured |
+| parameter descriptions | 27 are empty |
+| sub-parameters | 21 |
+| descriptions | median 263 characters; 154 under 200, 43 over 2,000 |
+| examples | on 91 operators, 19 % of the documentation text |
+| related plugins | on 81 operators |
+| Python plugins | 71 |
+
+A generated page spends a heading and three bullets on every parameter (`ID`, `Datatype`,
+`Default Value`). It writes `None` both for a missing default and for an empty advanced section, and
+repeats the Python plugin note on every Python operator.
+
+#### Structure
+
+- **Chapters:** each operator type keeps its chapter and its introduction, A.3.1 Aggregators to A.3.5
+ Transformers. The chapter's operator entries replace its overview table.
+- **Order:** operators follow in alphabetical order, as in the overview tables. The transformer category
+ becomes a field of the entry instead of a level of headings. So every operator sits at the same level,
+ A.3.x.y, and the part contents list them with their pages.
+- **Introduction:** the introduction of A.3 says once what an entry shows, that the examples are part of
+ the online edition, and what a Python plugin needs.
+
+#### An entry
+
+```text
+A.3.5.42 Constant transformer · Value · constant
+
+Generates a constant value.
+
+Parameter Type Default Description
+Value text – The constant value to be generated
+value
```
-`| url` resolves `tags/` relative to the current page, so it survives mike's versioned
-prefixes without special handling.
-
-### Open questions
-
-1. **Slug duplication.** The template computes the slug in MiniJinja; `render_tag_listings.
- tag_slug()` computes it in Python. They must agree or every link dangles. Accept the
- duplication with a comment in both places, or have the renderer assert that each anchor
- it emits is reachable? **Recommend: assert** - it is a cheap required check and the
- failure mode is otherwise silent.
-
-2. **Tags with no listing section.** A tag carried *only* by the listing page itself
- produces no section (self-exclusion, §3), so its chip would link to a dead anchor. Does
- not occur today. **Recommend: cover it with the check in Q1** rather than special-casing.
-
-3. **`hide: tags` pages.** The existing template already honours it; the override must keep
- that branch. No decision needed, just do not drop it.
+- **Heading:** the operator's title, numbered, kept together with what follows.
+- **Field line:** the operator type, the transformer category, the plugin ID in monospace, `Python plugin`
+ where it applies, and a distance measure's range. It is small, grey and one line long.
+- **Description:** the rendered description from the site page, without its `## Examples` section and
+ without the Python plugin note. Its own second-level headings, such as `## Characteristics`, print as
+ run-in labels, not as numbered sections.
+- **Parameters:** one table per operator, in the plugin's order. The columns are Parameter (the title, and
+ the ID in monospace below it), Type, Default and Description. Advanced parameters follow in the same
+ table after a row labelled `Advanced`; a sub-parameter follows its parameter as `parent.child`.
+- **Related:** one line, for example `Related: Merge (p. 214), Zip (p. 230)`.
+
+Sparse data prints as nothing:
+
+- An operator without parameters has no table, and one without advanced parameters no `Advanced` row.
+- A parameter without a default shows `–`; a password never shows one.
+- A multi-line or structured default shows `see below`, and a code block follows the table.
+- An operator without related plugins has no `Related` line, and an empty parameter description leaves
+ its cell empty.
+
+The data types print in one vocabulary:
+
+| Data type | Printed |
+| :-- | :-- |
+| `string`, `multiline string` | text |
+| `int`, `Long` | integer |
+| `double` | number |
+| `boolean` | boolean |
+| `char` | character |
+| `enumeration` | choice |
+| `password` | password |
+| `resource` | file |
+| `scheme:string` | URI - to confirm |
+| `traversable[string]` | list of text |
+| `stringmap` | map |
+| `code-sparql` | SPARQL |
+
+#### Data source
+
+The build takes the structure and the parameters from `data/plugins.json` and only the description from
+the rendered site page. The JSON tells a missing default apart from the text `None`, and it carries the
+types, the advanced flags and the sub-parameters that the page shows only as bullets. The build fails when
+an operator page and the JSON disagree - an operator without an entry, or an entry without a page - so a
+regeneration that updated only one of them shows.
+
+#### Budget
+
+A rough count - 95 characters per line of description, one row per parameter and more for a long
+description, four lines for heading and field line - gives about 180 pages for the 389 entries. The part
+contents add about 8 pages. The book would grow from 666 to about 860 pages; the operator pages in full
+took about 458 (§5). BoD takes 1,200 pages on 80 g and 1,050 on 90 g (D5). Measured after P23: A.3 takes 213 pages and the
+book 870.
+
+The site and the generator stay as they are. The same format could later serve the site as well; that is
+not part of this proposal.
+
+### PDF/X-4 and CMYK
+
+Unchanged: the optional normalization pass (§7, D11), backlog P13. The review confirms that it is
+needed.
+
+### Image widths in the sources (D18)
+
+Typst prints an image without `width` at the pixel density it declares, 72 dpi when it declares none,
+and never wider than the column. On 2026-09-15 the printed pages that are not generated hold 500 raster
+images, 352 of them without `width`. The declared densities: none on 231, 144 dpi on 180 (Retina
+captures on macOS), 120 dpi on 80, 96 dpi on 8, 192 dpi on 1. 43 images print below 150 ppi, 37 of them
+without `width`.
+
+Decided as D18 on 2026-09-15 from the capture density, and **revised on 2026-09-16** once the report of
+P15 showed what each image actually prints at. The rule is the printed density: `dec-tool image-widths`,
+with `--fix`, narrows every raster image that prints below 150 ppi in pages that are not generated.
+
+- **Width:** the pixel width divided by the 6.3 inches of the text column and by the 150 ppi target,
+ rounded **down to a whole percent**, with one further step down where the rounding of the density would
+ leave it short. The width a page declares cancels out of `declared × density ÷ target`, so the pixels
+ alone decide it.
+- **Measured at** the width the page declares, quoted or not; an image without one fills the column and
+ counts as 100 %.
+- **Scope:** raster images only. SVGs, remote images, fenced code and images already at 150 ppi or more
+ stay as they are, as do generated pages.
+- **No floor:** an image whose pixels only support a thumbnail gets the thumbnail; the two smallest are
+ 14 % and 21 %, each a snippet of a dialog.
+- **Check:** `task check` runs it as `check:images`, so a new screenshot is caught before it is built.
+
+The same percentage serves the site and the PDF: on paper the image prints at 150 ppi or better, and the
+site shows it at the share of the article it fills on the page. This closes P15 - `--fix` wrote 47 widths
+into 21 pages and the report is empty - rather than replacing screenshots. The superseded rule, natural
+width from the capture scale rounded to 5 %, left 42 images below the target.
+
+### Decisions
+
+Decided on 2026-09-15 as D15-D18, recorded in §4: web addresses in a list at the end of each part (D15),
+the author order from commits to the printed pages (D16), the compact operator reference as proposed
+(D17), and screenshot widths against the full page width (D18).
diff --git a/tests/test_build_pdf.py b/tests/test_build_pdf.py
index 639731c53..38eb1eb6d 100644
--- a/tests/test_build_pdf.py
+++ b/tests/test_build_pdf.py
@@ -24,6 +24,7 @@ def soup(markup: str) -> BeautifulSoup:
def test_section_opens_with_its_index_page():
+ # A page keeps its navigation title; an index page takes its section's.
nav = [
{"Build": [
{"Build": "build/index.md"},
@@ -32,10 +33,10 @@ def test_section_opens_with_its_index_page():
]},
]
assert nav_entries(nav) == [
- NavEntry(depth=0, md="build/index.md"),
- NavEntry(depth=1, md="build/rules/index.md"),
- NavEntry(depth=2, md="build/rules/linking.md"),
- NavEntry(depth=1, md="build/spark.md"),
+ NavEntry(depth=0, md="build/index.md", title="Build"),
+ NavEntry(depth=1, md="build/rules/index.md", title="Rules"),
+ NavEntry(depth=2, md="build/rules/linking.md", title="Linking"),
+ NavEntry(depth=1, md="build/spark.md", title="Spark"),
]
@@ -50,13 +51,13 @@ def test_section_without_index_page_gets_a_heading():
assert nav_entries(nav) == [
NavEntry(depth=0, title="Release Notes"),
NavEntry(depth=1, title="2026"),
- NavEntry(depth=2, md="release-notes/2026/corporate-memory-26-2/index.md"),
+ NavEntry(depth=2, md="release-notes/2026/corporate-memory-26-2/index.md", title="v26.2.1"),
]
def test_page_listed_twice_appears_once_and_links_are_skipped():
nav = [{"A": ["a/index.md", {"Again": "a/index.md"}, {"Site": "https://example.org/"}]}]
- assert nav_entries(nav) == [NavEntry(depth=0, md="a/index.md")]
+ assert nav_entries(nav) == [NavEntry(depth=0, md="a/index.md", title="A")]
def test_merge_breaks_chapters_adds_section_headings_and_drops_web_chrome(tmp_path):
@@ -73,7 +74,7 @@ def test_merge_breaks_chapters_adds_section_headings_and_drops_web_chrome(tmp_pa
NavEntry(depth=1, md="release-notes/v1/index.md"),
NavEntry(depth=1, md="release-notes/v2/index.md"),
]
- doc, missing = merge_pages(entries, site, "https://example.org/latest/")
+ doc, missing, _ = merge_pages(entries, site, "https://example.org/latest/")
assert missing == ["release-notes/v2/index.md"]
assert str(doc.body) == (
'Release Notes
'
@@ -91,7 +92,7 @@ def test_part_cover_is_the_title_then_the_diagram_the_page_shows_above_it(tmp_pa
'Build
Intro
'
'