docs(design): het callout-formaat na de tweede review (#1801)

brenno commented

2026-08-27 13:20:28 +00:00

Owner

Verwerkt de tweede reviewronde op docs/design/IMAGE_CALLOUTS.md (issue #1801). Alle zeven punten zijn beantwoord; twee ervan veranderden een besluit in plaats van een formulering.

Twee besluiten die omgingen

De afgeleide overlay wordt niet meer opgeslagen (§2.3). Revisie 3 zette een positieregel per callout in het gegenereerde thema, zodat marp --theme-set de markeringen tóch tekende. Dat is een tweede kopie van een feit dat de front matter al vastlegt, en een handmatige bewerking van het .md kan die kopie stil laten liegen.
De meetlat stond op de verkeerde release (§10). v0.4.10 is op 25 augustus uitgebracht (niet-concept, 12 assets) en v0.4.9 kreeg nooit een release. De bewaarproef noemt daarom geen versie meer bij naam maar lost 'nieuwste uitgebrachte tag' op bij de poort, en is een uitvoerbare kruisversietoets in plaats van een weggegooide probe. De conclusie zelf houdt stand: de diff over de vier dragerpaden tussen v0.4.10 en main is leeg.

De waardenbotsing, opgeschreven (verplicht want dit raakt het bestandsformaat; bewaker gedraaid)

Uitwisselbaarheid tegen een rijke functie, en uitwisselbaarheid wint — dezelfde uitkomst als in §11, nu ook voor de opslagvorm. Een vreemd gereedschap dat niets tekent is eerlijk; een dat het verkeerde tekent niet, want de auteur kan het verschil niet zien. De prijs is benoemd: marp --theme-set toont voortaan de indeling, de tekst en (A), en geen markeringen. Wat dit besluit zou terugdraaien: een drager waarvan de afgeleide kopie niet kan verouderen, of waarvan het verouderd-zijn door het lezende gereedschap te zien is. CSS kan geen van beide.

Gemeten in plaats van beloofd

De geometrie was in revisie 3 alleen voor het gecentreerde cover-geval bewezen. Nu volledig (§4.1) en gemeten in headless Chrome (§4.2): 486 gevallen — 3 beeldverhoudingen × 3 slots × zoominvoer 0/100/140/400/−50/5000 × focaal 0/0,5/1 op beide assen × 8 doelen op elke hoek en randmidden plus een regio. Grootste afwijking 0,03 px.

Twee formuleringen die logisch klopten bleken fout, en staan nu als contract in het document:

CSS de contain-richting laten kiezen via max-width/max-height + aspect-ratio — tot 2144 px mis. De richting wordt bij generatie gekozen.
Zonder position: relative op de beelddoos vallen de markeringspercentages terug op de zoomdoos — 1184 px mis, terwijl de afbeelding zelf goed staat.

Bijvangst: een bestaand gebrek (§4.3)

Bij het meten van de zoomtak bleek dat elke zoom boven 100% hetzelfde beeld oplevert als 100%: Align versoepelt de grenzen maar houdt het slot als maximum, en SizedBox dwingt zijn maat daarbinnen af, dus de vergrote doos wordt teruggeknepen. Gemeten met flutter test op de exacte widgetketen, en het proefbeeld in de bijsnijddialoog knijpt op dezelfde manier — vandaar dat editor en dia het netjes met elkáár eens zijn. Dat krijgt een eigen issue en staat als voorwaarde vooraf naast #1803 in de werkvolgorde; zonder die reparatie zou de eerste surface die §4.1 getrouw uitvoert de markeringen ergens anders neerzetten dan Flutter.

De overige punten

§2.4 — één bewaarregel in plaats van twee die elkaar tegenspraken: ongeldige gegevens worden bewaard en gemeld, nooit stil naar een andere betekenis geklemd.
§2.5 — het geneste samenvoegcontract dat nodig wordt zodra v2 ocideck_callouts bezit: de bescherming die de oude lezer het blok laat behouden bestaat alleen omdat hij de sleutel niet bezit.
§2.6 — wanneer (A) een verwijzing is en wanneer gewoon proza, inclusief de geplakte dubbele bullet.
§2.1/§8 — de grammatica accepteerde ZZ terwijl het plafond 26 was; nu één letter.
§3.1 — de matrix van modus tegen doelsoort, met de dragende regel: een renderer mag geometrie versoberen, nooit verzinnen.
§12 — een toegankelijkheidscontract in plaats van alleen opgeslagen tekst; de beschrijving hoort bij de verwijzing, niet bij elk doel.
§6/§1 — rijke tekst is een grens, geen gat: de overgang wordt geblokkeerd in plaats van stil de callouts te laten vallen.

Poorten

make check-static (exit 0), make check-secrets (gitleaks + trufflehog, werkboom én historie), make sast (semgrep, 0 bevindingen), check-translated-mermaid, translate-docs-check, check-comment-language, check-audience-boundary — alle groen. De wijziging raakt geen Dart, dus de testsuite en de dekkingsvloer zijn niet aan de orde; docs/design/** is bewust ongebundeld en heeft geen registratie nodig.

Verwerkt de tweede reviewronde op `docs/design/IMAGE_CALLOUTS.md` (issue #1801). Alle zeven punten zijn beantwoord; twee ervan veranderden een besluit in plaats van een formulering. **Twee besluiten die omgingen** 1. **De afgeleide overlay wordt niet meer opgeslagen** (§2.3). Revisie 3 zette een positieregel per callout in het gegenereerde thema, zodat `marp --theme-set` de markeringen tóch tekende. Dat is een tweede kopie van een feit dat de front matter al vastlegt, en een handmatige bewerking van het `.md` kan die kopie stil laten liegen. 2. **De meetlat stond op de verkeerde release** (§10). `v0.4.10` is op 25 augustus uitgebracht (niet-concept, 12 assets) en `v0.4.9` kreeg nooit een release. De bewaarproef noemt daarom geen versie meer bij naam maar lost 'nieuwste uitgebrachte tag' op bij de poort, en is een uitvoerbare kruisversietoets in plaats van een weggegooide probe. De conclusie zelf houdt stand: de diff over de vier dragerpaden tussen `v0.4.10` en `main` is leeg. **De waardenbotsing, opgeschreven** (verplicht want dit raakt het bestandsformaat; bewaker gedraaid) Uitwisselbaarheid tegen een rijke functie, en uitwisselbaarheid wint — dezelfde uitkomst als in §11, nu ook voor de opslagvorm. Een vreemd gereedschap dat niets tekent is eerlijk; een dat het verkeerde tekent niet, want de auteur kan het verschil niet zien. De prijs is benoemd: `marp --theme-set` toont voortaan de indeling, de tekst en `(A)`, en geen markeringen. Wat dit besluit zou terugdraaien: een drager waarvan de afgeleide kopie niet kan verouderen, of waarvan het verouderd-zijn door het lezende gereedschap te zien is. CSS kan geen van beide. **Gemeten in plaats van beloofd** De geometrie was in revisie 3 alleen voor het gecentreerde cover-geval bewezen. Nu volledig (§4.1) en gemeten in headless Chrome (§4.2): 486 gevallen — 3 beeldverhoudingen × 3 slots × zoominvoer 0/100/140/400/−50/5000 × focaal 0/0,5/1 op beide assen × 8 doelen op elke hoek en randmidden plus een regio. Grootste afwijking **0,03 px**. Twee formuleringen die logisch klopten bleken fout, en staan nu als contract in het document: - CSS de contain-richting laten kiezen via `max-width`/`max-height` + `aspect-ratio` — tot **2144 px** mis. De richting wordt bij generatie gekozen. - Zonder `position: relative` op de beelddoos vallen de markeringspercentages terug op de zoomdoos — **1184 px** mis, terwijl de afbeelding zelf goed staat. **Bijvangst: een bestaand gebrek** (§4.3) Bij het meten van de zoomtak bleek dat **elke zoom boven 100% hetzelfde beeld oplevert als 100%**: `Align` versoepelt de grenzen maar houdt het slot als maximum, en `SizedBox` dwingt zijn maat daarbinnen af, dus de vergrote doos wordt teruggeknepen. Gemeten met `flutter test` op de exacte widgetketen, en het proefbeeld in de bijsnijddialoog knijpt op dezelfde manier — vandaar dat editor en dia het netjes met elkáár eens zijn. Dat krijgt een eigen issue en staat als voorwaarde vooraf naast #1803 in de werkvolgorde; zonder die reparatie zou de eerste surface die §4.1 getrouw uitvoert de markeringen ergens anders neerzetten dan Flutter. **De overige punten** - §2.4 — één bewaarregel in plaats van twee die elkaar tegenspraken: ongeldige gegevens worden bewaard en gemeld, nooit stil naar een andere betekenis geklemd. - §2.5 — het geneste samenvoegcontract dat nodig wordt zodra v2 `ocideck_callouts` bezit: de bescherming die de oude lezer het blok laat behouden bestaat alleen omdat hij de sleutel *niet* bezit. - §2.6 — wanneer `(A)` een verwijzing is en wanneer gewoon proza, inclusief de geplakte dubbele bullet. - §2.1/§8 — de grammatica accepteerde `ZZ` terwijl het plafond 26 was; nu één letter. - §3.1 — de matrix van modus tegen doelsoort, met de dragende regel: een renderer mag geometrie versoberen, nooit verzinnen. - §12 — een toegankelijkheidscontract in plaats van alleen opgeslagen tekst; de beschrijving hoort bij de verwijzing, niet bij elk doel. - §6/§1 — rijke tekst is een grens, geen gat: de overgang wordt geblokkeerd in plaats van stil de callouts te laten vallen. **Poorten** `make check-static` (exit 0), `make check-secrets` (gitleaks + trufflehog, werkboom én historie), `make sast` (semgrep, 0 bevindingen), `check-translated-mermaid`, `translate-docs-check`, `check-comment-language`, `check-audience-boundary` — alle groen. De wijziging raakt geen Dart, dus de testsuite en de dekkingsvloer zijn niet aan de orde; `docs/design/**` is bewust ongebundeld en heeft geen registratie nodig.

brenno added 1 commit

2026-08-27 13:20:29 +00:00

docs(design): het callout-formaat na de tweede review (#1801 )

scans / scans (pull_request) Has been cancelled

Details

static-gate / static-gate (pull_request) Has been cancelled

Details

be553b49cf

De reviewronde legde zeven punten neer; ze zijn allemaal verwerkt, en twee
ervan veranderden een besluit in plaats van een formulering.

Het zwaarste: de afgeleide overlay wordt niet meer opgeslagen. Revisie 3 zette
een positieregel per callout in het gegenereerde thema, zodat een vreemde
Marp-aanroep mét --theme-set de markeringen tóch tekende. Dat is een tweede
kopie van een feit dat de front matter al vastlegt, en een handmatige bewerking
van het .md kan die kopie stil laten liegen. Een vreemd gereedschap dat niets
tekent is eerlijk; een dat het verkeerde tekent niet.

Het tweede: de meetlat stond op de verkeerde release. v0.4.10 is op 25 augustus
uitgebracht en v0.4.9 kreeg nooit een release — de bewaarproef noemt daarom geen
versie meer bij naam maar lost 'nieuwste uitgebrachte tag' op bij de poort, en
draait als uitvoerbare kruisversietoets in plaats van als weggegooide probe.

Verder: één bewaarregel in plaats van twee die elkaar tegenspraken (ongeldige
gegevens worden bewaard en gemeld, nooit stilzwijgend naar een andere betekenis
geklemd), het geneste samenvoegcontract dat nodig wordt zodra v2 de sleutel
bezit, wanneer (A) een verwijzing is en wanneer gewoon proza, de matrix van
modus tegen doelsoort, en een toegankelijkheidscontract dat verder gaat dan het
opslaan van beschrijvende tekst.

De geometrie is niet langer beloofd maar gemeten: 486 gevallen in headless
Chrome, grootste afwijking 0,03 px. Twee formuleringen die logisch klopten
bleken fout — CSS de contain-richting laten kiezen (tot 2144 px mis) en de
ontbrekende position:relative (1184 px mis). Daarbij kwam een bestaand gebrek
boven water: inzoomen boven 100% doet niets, omdat Align+SizedBox de vergrote
doos terugknijpt tot het slot. Dat krijgt een eigen issue en staat als
voorwaarde vooraf in de werkvolgorde.

brenno added 1 commit

2026-08-27 13:22:51 +00:00

docs(design): scope de twee beelddoos-regels op hun ouder (#1801 )

scans / scans (pull_request) Has been cancelled

Details

static-gate / static-gate (pull_request) Has been cancelled

Details

e442bb4df1

Als één kale selector zou de zoomvariant met position:relative de
cover-variant met position:absolute overschrijven — en dan breekt precies
het geval dat helemaal geen zoomdoos heeft. Meteen ook opgeschreven wat
--iw/--ih/--fx/--fy/--z betekenen, want het fragment is bedoeld om
overgenomen te worden.

brenno added 2 commits

2026-08-27 13:25:24 +00:00

docs(design): haal de vervallen Marp-overlay uit het toegankelijkheidscontract (#1801 ) d8a606c883

§2.3 slaat niets afgeleids meer op, dus er is geen tweede HTML-oppervlak
naast de eigen export. En de aankondiging bij een stap kreeg de naam van de
aanroep die er al is, zodat de lezer hem kan opzoeken in plaats van te
moeten geloven dat hij bestaat.

docs(design): geen Marp-fragmentmarkering meer in het opgeslagen deck (#1801 )

scans / scans (pull_request) Successful in 4m36s

Details

static-gate / static-gate (pull_request) Has been cancelled

Details

2541ade0e5

De nieuwe regel uit 2.3 — niets afgeleids op schijf — gold nog niet voor
zichzelf: 7 liet de serialisatie naast 'reveal:' ook '*' schrijven. Dat is
dezelfde tweede kopie, met kleinere gevolgen maar hetzelfde gebrek, en een
regel met één handige uitzondering is geen regel. De verbeterroute staat
erbij: gaat '*' ooit verliesvrij door de rondgang, dan kan de markering de
drager worden en mag de front-matter-sleutel weg.

brenno added 1 commit

2026-08-27 13:42:46 +00:00

docs(design): de zoomvoorwaarde heeft een nummer (#1801 )

scans / scans (pull_request) Successful in 6m20s

Details

static-gate / static-gate (pull_request) Successful in 9m13s

Details

8f144acc27

De bevinding uit 4.3 staat nu als #1813 op de tracker; een verwijzing naar
"een eigen issue" zonder nummer is een belofte die niemand kan nalopen.

brenno merged commit 43f4c271c8 into main

2026-08-27 15:13:54 +00:00

brenno referenced this pull request from a commit

2026-08-27 15:13:54 +00:00

Merge pull request 'docs(design): het callout-formaat na de tweede review (#1801)' (#1806) from docs/1801-callout-ontwerp-v4 into main

brenno referenced this pull request

2026-08-27 15:14:07 +00:00

[Feature] Map with arrows #1801

brenno referenced this pull request

2026-08-27 16:06:56 +00:00

[Feature] Map with arrows #1801

brenno referenced this pull request

2026-08-28 09:45:26 +00:00

[Feature] Map with arrows #1801

Rows
Columns

docs(design): het callout-formaat na de tweede review (#1801) #1806