LibreKAT/Ocideck
LibreKAT/Ocideck
Watch
4
0
Fork
You've already forked Ocideck
 1
Code Issues Pull requests Projects Releases 21 Packages Activity Actions

docs(bestandsformaat): de documentkant van FILE_FORMAT weer gelijk met de code #1568

Merged
brenno merged 4 commits from docs/bestandsformaat-documentkant into main 2026-08-19 08:54:00 +00:00
Conversation 0 Commits 4 Files changed 4 +547 -76
brenno commented 2026-08-19 08:49:04 +00:00
Owner
Copy link

Waarom

De documentmodus is sinds 6 augustus flink gegroeid — voetnoten, paginaopmaak in
het bestand, snijtekens, hoofdstukafbrekingen, een inhoudsopgave, een
tabelhuisstijl — en FILE_FORMAT.md is niet overal meegegaan. Op vier punten
stond er iets dat door de code was ingehaald, en één constructie stond er
helemaal niet in.

Wat erin zit

Nieuw — §14.10, de inhoudsopgave. De marker <!-- toc --> is naast --- de
enige constructie die OciDeck zelf in de body van een document schrijft, en hij
stond nergens in het bestandsformaat (wel in SOURCE_MAP en de gebruikersgids).
De sectie zegt wat er op schijf staat (alleen de marker, nooit de lijst),
waarom, en welk dialect elke uitvoer eraan geeft.

Rechtgezet, met de correctie op de record in plaats van stil herschreven:

§ stond er klopt
14.4 twee uitvoervormen, geen PDF-route vier (md/html/tex/ocideck); de LaTeX-route is juist de PDF mét afloop
14.7 "crop marks are not emitted by any output path", geen instelling de LaTeX-export zet ze, bij een afloop, via documentCropMarks
14.5 drie eigen sleutels; terugtrekroute "declared, not yet built" vier sinds reference-location:; de generieke schrijver ruimt teruggetrokken sleutels op
14.8 een "known gap" rond liggend/afloop dezelfde dag al gedicht (_inferPaper, documentCarriesPageSetup)

Aangevuld: §14.6 beschrijft nu ook de bewerking die de hoofdstukeinden écht
in het bestand zet (#1545), §14.1/§14.3 noemen de voetnootsleutel, §14.4 kreeg de
twee ontbrekende bullets (de inhoudsopgave reist mee, de voetnootplaatsing niet),
en §3.2 somt de tien profielvelden op (checklist- en tabelhuisstijl) die bij het
landen nooit in de tabel kwamen.

Nederlands bij. FILE_FORMAT.nl.md is wat in de app wordt getoond en liep
drie secties achter: §14.9 ontbrak volledig, §14.4 miste het hele blok over wat
er bij export meereist, §14.8 miste de exportbullet. translate-docs-check ziet
dat niet — die poort toetst aanwezigheid en registratie, niet actualiteit.

Poorten tegen herhaling

Dit verval had geen knal: de velden en de sleutel kwamen met een functie mee en
niemand liep de tabel na. Twee nieuwe toetsen in docs_enum_counts_test.dart
houden het bij — elk veld van ThemeProfile en elke sleutel uit
kDocumentOwnedKeys moet in FILE_FORMAT staan. Beide zijn eerst rood gemaakt
tegen de onherstelde documentatie.

Bewaker

Wel gedaan, want dit raakt het bestandsformaat en publieke beloftes. De weging
zat op §14.10: mag de marker <!-- toc --> "geen eigen vocabulaire" heten
(§14.1)? Uitkomst: de syntaxis is niet van OciDeck, de betekenis wél — dus staat
er nu de zwakkere, ware bewering in plaats van de te makkelijke. Wat §14.1
verbiedt blijft overeind: geen sleutel met onze naam, geen lezer die iets moet
begrijpen, en wie vertrekt raakt hoogstens de gegenereerde lijst kwijt, die
elk inhoudsopgavegereedschap opnieuw maakt uit de koppen.

Getoetst

  • make check-static groen.
  • flutter test op docs_enum_counts_test.dart, docs_anchor_links_test.dart,
    doc_link_test.dart, docs_claims_match_code_test.dart groen (50 toetsen).
  • dart run tool/translate_docs.dart --check groen.
  • make check-secrets en make sast gedraaid.
  • Geen lib/-wijziging, dus geen dekkings- of gedragsgevolg.

Open eind, opgeschreven en niet weggewuifd

reference-location: reist niet mee in het geprojecteerde .md, terwijl het
volgens de redenering in §14.4 (een maat reist, een verwijzing niet) wél een maat
is. Dat staat nu zo in §14.4. Zal ik daar een issue voor aanmaken?

## Waarom De documentmodus is sinds 6 augustus flink gegroeid — voetnoten, paginaopmaak in het bestand, snijtekens, hoofdstukafbrekingen, een inhoudsopgave, een tabelhuisstijl — en `FILE_FORMAT.md` is niet overal meegegaan. Op vier punten stond er iets dat door de code was ingehaald, en één constructie stond er helemaal niet in. ## Wat erin zit **Nieuw — §14.10, de inhoudsopgave.** De marker `<!-- toc -->` is naast `---` de enige constructie die OciDeck zelf in de body van een document schrijft, en hij stond nergens in het bestandsformaat (wel in SOURCE_MAP en de gebruikersgids). De sectie zegt wat er op schijf staat (alleen de marker, nooit de lijst), waarom, en welk dialect elke uitvoer eraan geeft. **Rechtgezet, met de correctie op de record in plaats van stil herschreven:** | § | stond er | klopt | | --- | --- | --- | | 14.4 | twee uitvoervormen, geen PDF-route | vier (`md`/`html`/`tex`/`ocideck`); de LaTeX-route is juist de PDF mét afloop | | 14.7 | "crop marks are not emitted by any output path", geen instelling | de LaTeX-export zet ze, bij een afloop, via `documentCropMarks` | | 14.5 | drie eigen sleutels; terugtrekroute "declared, not yet built" | vier sinds `reference-location:`; de generieke schrijver ruimt teruggetrokken sleutels op | | 14.8 | een "known gap" rond liggend/afloop | dezelfde dag al gedicht (`_inferPaper`, `documentCarriesPageSetup`) | **Aangevuld:** §14.6 beschrijft nu ook de bewerking die de hoofdstukeinden écht in het bestand zet (#1545), §14.1/§14.3 noemen de voetnootsleutel, §14.4 kreeg de twee ontbrekende bullets (de inhoudsopgave reist mee, de voetnootplaatsing niet), en §3.2 somt de tien profielvelden op (checklist- en tabelhuisstijl) die bij het landen nooit in de tabel kwamen. **Nederlands bij.** `FILE_FORMAT.nl.md` is wat in de app wordt getoond en liep drie secties achter: §14.9 ontbrak volledig, §14.4 miste het hele blok over wat er bij export meereist, §14.8 miste de exportbullet. `translate-docs-check` ziet dat niet — die poort toetst aanwezigheid en registratie, niet actualiteit. ## Poorten tegen herhaling Dit verval had geen knal: de velden en de sleutel kwamen met een functie mee en niemand liep de tabel na. Twee nieuwe toetsen in `docs_enum_counts_test.dart` houden het bij — elk veld van `ThemeProfile` en elke sleutel uit `kDocumentOwnedKeys` moet in FILE_FORMAT staan. Beide zijn eerst rood gemaakt tegen de onherstelde documentatie. ## Bewaker Wel gedaan, want dit raakt het bestandsformaat en publieke beloftes. De weging zat op §14.10: mag de marker `<!-- toc -->` "geen eigen vocabulaire" heten (§14.1)? Uitkomst: de syntaxis is niet van OciDeck, de betekenis wél — dus staat er nu de zwakkere, ware bewering in plaats van de te makkelijke. Wat §14.1 verbiedt blijft overeind: geen sleutel met onze naam, geen lezer die iets moet begrijpen, en wie vertrekt raakt hoogstens de *gegenereerde* lijst kwijt, die elk inhoudsopgavegereedschap opnieuw maakt uit de koppen. ## Getoetst - `make check-static` groen. - `flutter test` op `docs_enum_counts_test.dart`, `docs_anchor_links_test.dart`, `doc_link_test.dart`, `docs_claims_match_code_test.dart` groen (50 toetsen). - `dart run tool/translate_docs.dart --check` groen. - `make check-secrets` en `make sast` gedraaid. - Geen `lib/`-wijziging, dus geen dekkings- of gedragsgevolg. ## Open eind, opgeschreven en niet weggewuifd `reference-location:` reist niet mee in het geprojecteerde `.md`, terwijl het volgens de redenering in §14.4 (een maat reist, een verwijzing niet) wél een maat is. Dat staat nu zo in §14.4. Zal ik daar een issue voor aanmaken? 
De documentmodus is sinds 6 augustus flink gegroeid en FILE_FORMAT liep op vier
punten achter — niet vaag, maar aantoonbaar onjuist voor wie het narekent.

Nieuw: §14.10 over de inhoudsopgave. De marker `<!-- toc -->` stond nergens in
het bestandsformaat, terwijl dat naast `---` de enige constructie is die OciDeck
zelf in de body van een document schrijft. De sectie zegt wat er op schijf staat
(alleen de marker, nooit de lijst), waarom (een opgeslagen inhoudsopgave is
verouderd zodra een kop verandert), en welk dialect elke uitvoer eraan geeft.
Ook de weging tegen §14.1 staat er scherp in plaats van weggewuifd: de syntaxis
is niet van OciDeck, de betekenis wél — en dat is de zwakkere, ware bewering.

Rechtgezet:
- §14.4 sprak van twee uitvoervormen en geen PDF-route; het zijn er vier
  (md/html/tex/ocideck) en de LaTeX-route is juist de weg naar een PDF mét
  afloop. De twee ontbrekende bullets over wat er meereist staan er nu ook bij:
  de inhoudsopgave wel, de voetnootplaatsing niet.
- §14.7 beweerde dat snijtekens door geen enkel pad worden geschreven en dat er
  geen instelling voor is. Sinds 17 augustus zet de LaTeX-export ze, bij een
  afloop, met `documentCropMarks`.
- §14.5 telde drie eigen sleutels en noemde de terugtrekroute "verklaard, nog
  niet gebouwd". Het zijn er vier sinds `reference-location:`, en de generieke
  schrijver ruimt teruggetrokken sleutels wél op.
- §14.8 hield een "bekend gat" overeind dat dezelfde dag al gedicht was: het
  formaat wordt ook uit expliciete `paperwidth`/`paperheight` gelezen.

Aangevuld: §14.6 beschrijft nu ook de bewerking die de hoofdstukeinden écht in
het bestand zet (#1545) — inclusief de setext-H2-val en de idempotentie —, §14.1
en §14.3 noemen de voetnootsleutel, en §3.2 somt de tien profielvelden op
(checklist- en tabelhuisstijl) die bij het landen nooit in de tabel kwamen.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
De tien profielvelden en de vierde front-matter-sleutel verdwenen niet met een
knal uit de documentatie — ze kwamen met een functie mee en niemand liep de
tabel na. Precies het soort verval waar een ratchet voor is.

De eerste poort leest de velden van `ThemeProfile` uit de bron (Dart kent geen
reflectie) en eist dat elk veld in FILE_FORMAT staat; de tweede doet hetzelfde
voor `kDocumentOwnedKeys`. Beide zijn eerst rood gemaakt tegen de onherstelde
documentatie.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
De Nederlandse variant is wat er in de app wordt getoond, en hij liep drie
secties achter: §14.9 (voetnoten) ontbrak volledig, §14.4 miste het hele blok
over wat er bij export meereist, en §14.8 miste de exportbullet. Daar bovenop nu
dezelfde correcties als in de Engelse bron, plus §14.10.

`translate-docs-check` ziet dit niet: die poort toetst of een variant bestaat en
geregistreerd is, niet of hij bij is. Zolang dat zo is, is bijwerken met de hand
de enige route — zoals bij #1543.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
docs(changelog): de bijgewerkte documentkant in het ontwikkellog
All checks were successful
scans / scans (pull_request) Successful in 1m49s
Details
static-gate / static-gate (pull_request) Successful in 4m30s
Details
63bfc6ad8d 
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
brenno merged commit 1644ae9589 into main 2026-08-19 08:54:00 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
accepted
Assessed and will be built

  
bug
Something is broken

  
declined
Assessed and will not be built

  
docs
Documentation only

  
duplicate
Already tracked elsewhere

  
enhancement
New feature or improvement request

  
good first issue
Small, self-contained, and a good place to start

  
in-progress
Someone is working on this right now. Do not start it in parallel.

  
needs-info
Waiting for the reporter

  
privacy
Personal data can leak. Handled before anything else.

  
security
A weakness someone could use. Handled before anything else.

  
triage
Awaiting assessment

No labels
accepted
bug
declined
docs
duplicate
enhancement
good first issue
in-progress
needs-info
privacy
security
triage
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
LibreKAT/Ocideck!1568
No description provided.