docs(bestandsformaat): §8 is eindelijk het overzicht dat het beloofde te zijn #1580

Merged

brenno merged 1 commit from docs/markers-documenteren into main

2026-08-19 13:06:52 +00:00

brenno commented

2026-08-19 13:00:06 +00:00

Owner

ocideck_list_style, ocideck_checklist_progress, ocideck_continue_numbering, ocideck_continue_split, ocideck_image_zoom, ocideck_title_image_overlay, ocideck_table_num_cols, ocideck_gantt_scale, ocideck_gantt_sections, ocideck_ms_review, ocideck_page, ocideck_media_redacted.

Twee die geen invuloefening waren

ocideck_page staat binnen het sprekersnotitieblok, niet ernaast — en dat botst met het blok waar hij in zit. Ik heb dat niet geredeneerd maar gedraaid (een wegwerptest die een deck met notities op twee pagina's serialiseert). Op schijf staat er:

<!--
<!-- ocideck_page:1 --\>
eerste

<!-- ocideck_page:2 --\>
tweede
-->

Die --\> is de escape die voorkomt dat de notitie zichzelf halverwege sluit. Dat verzin je niet uit de broncode.

ocideck_media_redacted staat nooit in een bewaard bestand, alleen in een export: hij geeft de HTML-renderer een vlak om te tekenen waar een weggeredigeerd beeld zat, want anders ziet de ontvanger een gat terwijl de tekst wél zwarte blokken toont. De schrijver hangt aan forExport én aan de vlag. Die grens hoort in het formaat, anders gaat iemand hem in een bron zoeken.

De overige tien zijn bediening: lijststijl, voortgangsbalk, doortellende nummering, de gedeelde tekstschaal van een splitsrun, paneelzoom, titeloverlay, numerieke tabelkolommen en de twee gantt-schakelaars.

De poort ertegen

Een toets in docs_enum_counts_test.dart scant lib/ op de commentaarvorm  en eist dat elke gevonden marker in FILE_FORMAT staat. Bewust op de vorm en niet op de naam: ocideck_staging en ocideck_git_sandbox zijn mapnamen van tijdelijke directories en horen niet in een bestandsformaat.

Rood geproefd door één tabelrij te verwijderen — de toets viel om — en daarna hersteld uit een kopie, niet met git, want er stond ongecommit werk in dezelfde boom.

Getoetst

make check volledig groen (hele suite, dekkingsvloer, per-bestand-vloer).
make check-secrets en make sast gedraaid.
Nederlands meevertaald in dezelfde wijziging, wat de poort uit #1576 nu ook afdwingt.

Wat hierna nog open staat

#1569 (voetnootplaatsing die niet meereist in het geprojecteerde .md). Verder is de documentkant van het bestandsformaat nu compleet: front matter, documentsecties §14.1–14.11, de profielvelden in §3.2 en de commentaartabel in §8 — en alle vier gedekt door een poort.

Sluit het laatste gat uit de reeks van vandaag (#1568, #1573, #1576): §8 noemt zichzelf een overzicht van de HTML-commentaren die OciDeck schrijft, en was er geen. Twaalf markers stonden nergens in het bestandsformaat. `ocideck_list_style`, `ocideck_checklist_progress`, `ocideck_continue_numbering`, `ocideck_continue_split`, `ocideck_image_zoom`, `ocideck_title_image_overlay`, `ocideck_table_num_cols`, `ocideck_gantt_scale`, `ocideck_gantt_sections`, `ocideck_ms_review`, `ocideck_page`, `ocideck_media_redacted`. ## Twee die geen invuloefening waren **`ocideck_page` staat binnen het sprekersnotitieblok**, niet ernaast — en dat botst met het blok waar hij in zit. Ik heb dat niet geredeneerd maar gedraaid (een wegwerptest die een deck met notities op twee pagina's serialiseert). Op schijf staat er: ```  ``` Die `--\>` is de escape die voorkomt dat de notitie zichzelf halverwege sluit. Dat verzin je niet uit de broncode. **`ocideck_media_redacted` staat nooit in een bewaard bestand**, alleen in een export: hij geeft de HTML-renderer een vlak om te tekenen waar een weggeredigeerd beeld zat, want anders ziet de ontvanger een gat terwijl de tekst wél zwarte blokken toont. De schrijver hangt aan `forExport` én aan de vlag. Die grens hoort in het formaat, anders gaat iemand hem in een bron zoeken. De overige tien zijn bediening: lijststijl, voortgangsbalk, doortellende nummering, de gedeelde tekstschaal van een splitsrun, paneelzoom, titeloverlay, numerieke tabelkolommen en de twee gantt-schakelaars. ## De poort ertegen Een toets in `docs_enum_counts_test.dart` scant `lib/` op de commentaarvorm `` en eist dat elke gevonden marker in FILE_FORMAT staat. Bewust op de *vorm* en niet op de naam: `ocideck_staging` en `ocideck_git_sandbox` zijn mapnamen van tijdelijke directories en horen niet in een bestandsformaat. Rood geproefd door één tabelrij te verwijderen — de toets viel om — en daarna hersteld uit een kopie, niet met git, want er stond ongecommit werk in dezelfde boom. ## Getoetst - `make check` volledig groen (hele suite, dekkingsvloer, per-bestand-vloer). - `make check-secrets` en `make sast` gedraaid. - Nederlands meevertaald in dezelfde wijziging, wat de poort uit #1576 nu ook afdwingt. ## Wat hierna nog open staat `#1569` (voetnootplaatsing die niet meereist in het geprojecteerde `.md`). Verder is de documentkant van het bestandsformaat nu compleet: front matter, documentsecties §14.1–14.11, de profielvelden in §3.2 en de commentaartabel in §8 — en alle vier gedekt door een poort.

brenno added 1 commit

2026-08-19 13:00:07 +00:00

docs(bestandsformaat): §8 is eindelijk het overzicht dat het beloofde te zijn

scans / scans (pull_request) Successful in 2m55s

Details

static-gate / static-gate (pull_request) Successful in 6m9s

Details

1c5389b094

Twaalf HTML-commentaren die OciDeck zelf in een `.md` schrijft, stonden nergens
in het bestandsformaat. Ze verdwenen niet met een knal — ze kwamen met een
functie mee en niemand liep de tabel na, precies zoals bij de
inhoudsopgavemarker (#1568). §8 noemt zichzelf een overzicht en was er geen.

Twee ervan zijn contra-intuïtief genoeg om apart te noemen:

- `ocideck_page` staat *binnen* het sprekersnotitieblok, niet ernaast, en zijn
  eigen afsluiting is daar geëscapet tot `--\>` — anders sluit de notitie
  zichzelf halverwege. Dat is niet uit de code te redeneren; ik heb het
  geserialiseerd en op de uitvoer gekeken.
- `ocideck_media_redacted` staat nooit in een bewaard bestand, alleen in een
  export. Hij geeft de HTML-renderer een vlak om te tekenen waar een
  weggeredigeerd beeld zat, want anders ziet de ontvanger een gat terwijl de
  tekst wél zwarte blokken toont. Die grens hoort in het formaat, anders zoekt
  iemand hem in een bron.

De rest is bediening: lijststijl, voortgangsbalk, doortellende nummering,
splitsrun-schaal, paneelzoom, titeloverlay, numerieke tabelkolommen en de twee
gantt-schakelaars.

Een nieuwe toets scant `lib/` op de commentaarvorm `<!-- ocideck_… -->` en eist
dat elke gevonden marker in FILE_FORMAT staat. Bewust op de vorm en niet op de
naam: `ocideck_staging` en `ocideck_git_sandbox` zijn mapnamen en horen hier
niet. Rood geproefd door één rij te verwijderen; daarna hersteld uit een kopie.

Nederlands is meevertaald in dezelfde wijziging, zoals de poort uit #1576 nu
afdwingt.

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

brenno merged commit 534d88fdd0 into main

2026-08-19 13:06:52 +00:00

brenno referenced this pull request from a commit

2026-08-19 13:06:53 +00:00

docs(bestandsformaat): 8 is eindelijk het overzicht dat het beloofde te zijn (#1580)