Cover sheet: a stroke-weight ladder, so a user sees how thin is thin (§ 8.8)

The cover already makes the one thing outside our control visible — a print
driver scaling — with a 50 mm square and a 100 mm rule. This adds the other
thing a definition cannot show on screen: how a given stroke weight actually
renders on the user's own printer or e-ink panel. A fixed ladder of short lines
from 0.1 to 1.0 pt, each labelled, sits between the rule and the summary.

On a device each label also carries the pixel width — 0.15pt · 0.48px at 229 dpi
— which ties the ladder to the media check (§ 12.1): that check says a hairline
is too thin, the ladder shows how thin, and the pixel figure says why. On paper
there is no pixel figure, because a format's assumed_dpi is a yardstick and not
a resolution (§ 8.3.1). The weights are fixed numbers, a yardstick like the
square and the rule, not a setting.

The samples are shorter than the 100 mm rule, so they add no width constraint
the rule has not. They do add height: the ladder is kept to seven weights so the
cover still fits an A6 page (the imposition test's format), never scaled to fit —
if it does not fit, the run is refused, exactly as before (§ 8.2).

Verified on real cover sheets read back, on A4 paper and on the reMarkable Paper
Pro. Spec § 8.8 gains the ladder as the cover's second figure.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: DocAtPrompt

ctrlgrid/cover.py

@@ -1,4 +1,4 @@
-"""The cover sheet (§ 8.8) — a calibration figure and a settings summary.
+"""The cover sheet (§ 8.8) — calibration figures, a weight ladder, a summary.
 
 It is one extra first page and it is unlike every other page in three ways, all
 of them from § 8.8: it is **not counted** in the numbering, it carries **no
@@ -41,6 +41,13 @@
 RULE_LENGTH = 100_000
 TICK = 3_000
 
+#: A fixed ladder of stroke weights (§ 8.8), fine at the thin end where a stroke
+#: can round to nothing on a coarse device (§ 12.1). A yardstick like the square
+#: and the rule — fixed numbers, not settings the user picks.
+WEIGHTS_PT = (0.1, 0.15, 0.2, 0.3, 0.5, 0.7, 1.0)
+SAMPLE_LENGTH = 45_000  # shorter than the 100 mm rule, so it adds no width bound
+PT_TO_MM = 25.4 / 72
+
 TITLE_SIZE = 4_233  # 12pt
 BODY_SIZE = 3_175  # 9pt
 #: The summary shrinks rather than overflowing, but only so far: below this it
@@ -99,6 +106,9 @@ def cover_marks(document: Document, *, q: WriterQuery) -> list[Mark]:
     marks += _rule(left, cursor, q=q)
     cursor -= TICK + _text_height(q, size=BODY_SIZE) + GAP // 2
 
+    cursor -= GAP
+    cursor = _weight_ladder(marks, left, cursor, device=document.device, q=q)
+
     cursor -= GAP
     cursor = _summary_block(marks, document, left, cursor, width=right - left, q=q)
 
@@ -243,6 +253,59 @@ def _rule(left: Um, top: Um, *, q: WriterQuery) -> list[Mark]:
     ]
 
 
+# ------------------------------------------------------------- the weight ladder
+
+
+def _weight_ladder(
+    marks: list[Mark], left: Um, top: Um, *, device: object, q: WriterQuery
+) -> Um:
+    """Sample lines at rising weights, each labelled (§ 8.8).
+
+    So a user can see on their own printer or e-ink screen what a given stroke
+    actually looks like: the media check (§ 12.1) says a hairline is too thin,
+    this shows *how* thin. On a device each label also carries the pixel width,
+    which ties the warning to the thing it warns about; on paper it does not,
+    because a format's `assumed_dpi` is a yardstick, not a resolution (§ 8.3.1).
+
+    The lines are shorter than the 100 mm rule, so they never add a width
+    constraint the rule has not already imposed.
+    """
+    cursor = _line_of_text(
+        marks, "line weights — how each renders on this medium",
+        left, top, size=BODY_SIZE, family="sans", q=q,
+    )
+    labels = [_weight_label(weight, device) for weight in WEIGHTS_PT]
+    label_width = max(q.text_width(label, family="mono", size=BODY_SIZE) for label in labels)
+    line_x = left + label_width + GAP
+    ascent, descent = q.text_metrics(family="mono", size=BODY_SIZE)
+    for weight, label in zip(WEIGHTS_PT, labels, strict=True):
+        baseline = cursor - ascent
+        marks.append(
+            Text(pos=Point(left, baseline), content=label, size=BODY_SIZE,
+                 family="mono", layer=Layer.PATTERN)
+        )
+        middle = baseline + ascent // 3  # the sample sits at the label's optical middle
+        marks.append(
+            Segment(
+                start=Point(line_x, middle),
+                end=Point(line_x + SAMPLE_LENGTH, middle),
+                weight=weight * PT_TO_MM,
+                layer=Layer.PATTERN,
+            )
+        )
+        cursor = baseline - descent
+    return cursor
+
+
+def _weight_label(weight: float, device: object) -> str:
+    """`0.15pt` on paper; `0.15pt  0.48px` on a device (§ 12.1)."""
+    text = f"{weight}pt"
+    density = getattr(device, "density", None)
+    if density is not None:
+        text += f"  {weight * density / 72:.2f}px"
+    return text
+
+
 # ------------------------------------------------------------------ the summary
 
 

pflichtenheft-vorlagengenerator.md

@@ -1356,15 +1356,25 @@ kein Fehler, sondern der Normalfall — deshalb:
 
 ### 8.8 Deckblatt
 
-`--cover` erzeugt **eine zusätzliche erste Seite**, die zwei Dinge trägt:
+`--cover` erzeugt **eine zusätzliche erste Seite**, die drei Dinge trägt:
 
 **1. Kalibrierquadrat.** Ein beschriftetes Quadrat von exakt 50 mm Kantenlänge
 und eine 100-mm-Strecke, beide mit Sollmaß beschriftet. Der Nutzer legt ein
 Lineal an; stimmt das Maß nicht, hat der Druckertreiber skaliert. Das ist die
 einzig mögliche Antwort auf ein Problem außerhalb unserer Kontrolle (§ 8.2):
 Wir können die Skalierung nicht verhindern, aber sichtbar machen.
 
-**2. Einstellungszusammenfassung.** Generator, Format, Ränder, Basiswerte,
+**2. Strichstärken-Leiter.** Kurze waagerechte Linien in einer festen,
+aufsteigenden Folge von Strichstärken (0,1 bis 1,0 pt), jede beschriftet. So
+sieht der Nutzer auf seinem *eigenen* Drucker oder E-Ink-Gerät, wie eine
+gegebene Stärke wirklich aussieht — die Medienprüfung (§ 12.1) sagt nur, *dass*
+eine Haarlinie zu dünn ist, die Leiter zeigt, *wie* dünn. Ist ein Gerät aktiv,
+trägt jede Beschriftung zusätzlich die Pixelbreite (`0,15pt · 0,48px`) und
+verbindet die Warnung mit dem, wovor sie warnt. Auf Papier nicht, weil ein
+`assumed_dpi` ein Maßstab und keine Auflösung ist (§ 8.3.1). Feste Zahlen wie
+Quadrat und Lineal, kein einstellbarer Wert.
+
+**3. Einstellungszusammenfassung.** Generator, Format, Ränder, Basiswerte,
 Zyklen, effektive Periode in Marken und Millimetern, Einrastmodus,
 Werkzeugversion und Name bzw. Prüfsumme der zugrunde liegenden Def. Damit ist
 ein gelungenes Blatt Jahre später reproduzierbar, ohne dass jemand die Def

tests/test_cover.py

@@ -17,7 +17,15 @@
 
 import pytest
 
-from ctrlgrid.cover import RULE_LENGTH, SQUARE_SIDE, cover_marks, summary
+from ctrlgrid.cover import (
+    PT_TO_MM,
+    RULE_LENGTH,
+    SAMPLE_LENGTH,
+    SQUARE_SIDE,
+    WEIGHTS_PT,
+    cover_marks,
+    summary,
+)
 from ctrlgrid.errors import DefinitionError
 from ctrlgrid.loader import loads
 from ctrlgrid.marks import Layer, Polygon, Segment, Text
@@ -103,6 +111,49 @@ def test_it_is_ticked_at_both_ends(self) -> None:
         assert abs(verticals[0].start.x - verticals[1].start.x) == RULE_LENGTH
 
 
+class TestLineWeightLadder:
+    """§ 8.8: a user sees how a stroke weight actually renders on their medium."""
+
+    def _samples(self, doc):
+        return [
+            m
+            for m in marks(doc)
+            if isinstance(m, Segment)
+            and m.start.y == m.end.y
+            and abs(m.end.x - m.start.x) == SAMPLE_LENGTH
+        ]
+
+    def test_it_samples_every_fixed_weight(self) -> None:
+        samples = self._samples(document())
+        assert len(samples) == len(WEIGHTS_PT)
+        got = sorted(round(s.weight, 6) for s in samples)
+        want = sorted(round(w * PT_TO_MM, 6) for w in WEIGHTS_PT)
+        assert got == want
+
+    def test_each_sample_is_labelled_in_points(self) -> None:
+        texts = " ".join(m.content for m in marks(document()) if isinstance(m, Text))
+        assert "0.15pt" in texts and "0.5pt" in texts
+
+    def test_on_paper_there_is_no_pixel_figure(self) -> None:
+        # A format's assumed_dpi is a yardstick, not a resolution (§ 8.3.1), so
+        # a pixel width on paper would be a made-up number.
+        texts = " ".join(m.content for m in marks(document()) if isinstance(m, Text))
+        assert "px" not in texts
+
+    def test_on_a_device_each_weight_carries_its_pixel_width(self) -> None:
+        # § 12.1 warns that a hairline is too thin; here the user sees how thin,
+        # in the device's own pixels. 0.15pt at 229 dpi is 0.48 px.
+        doc = loads(
+            "version: 1\n"
+            "page:\n  device: remarkable-paper-pro\n"
+            "generator: lines\n"
+            "families:\n  - direction: horizontal\n    base_spacing: 10mm\n",
+            source="test",
+        )
+        texts = " ".join(m.content for m in marks(doc) if isinstance(m, Text))
+        assert "px" in texts and "0.48px" in texts
+
+
 class TestSummary:
     """§ 8.8: enough to reproduce a sheet that worked, years later."""
 
@@ -237,8 +288,9 @@ def test_it_carries_no_pattern(self, tmp_path: Path) -> None:
         path = tmp_path / "cover.pdf"
         build(document(blocks="pages:\n  cover: true\n"), PdfWriter(path))
         horizontals = [line for line in pdfread.lines_um(path, 0) if line.is_horizontal]
-        # Only the calibration rule, never a grid.
-        assert len(horizontals) == 1
+        # The calibration figures only — the 100 mm rule and the weight ladder —
+        # never the generator's grid (which would be dozens of full-width lines).
+        assert len(horizontals) == 1 + len(WEIGHTS_PT)
 
     def test_the_square_measures_fifty_millimetres_in_the_finished_pdf(
         self, tmp_path: Path