docs: breng de documentatie terug in overeenstemming met de code #1870

Merged

brenno merged 1 commit from docs/actualiseren-2026-08-30 into main

2026-08-30 19:23:45 +00:00

brenno commented

2026-08-30 12:55:43 +00:00

Owner

Wat dit is

De documentatie nagelopen tegen wat de app doet, en de dertien plekken waar die twee uiteen waren gelopen gecorrigeerd. Elke bewering is tegen de code getoetst; elke correctie draagt de datum in de tekst zelf, zoals de huisregel in FAQ.md en MIGRATION_GUIDE.md.

De drie die een lezer echt op het verkeerde been zetten

Waar	Stond er	Klopt
`USER_GUIDE` § Exporting a document	vier formaten (md, HTML, PDF, LaTeX)	zes — ePub en ODT ontbraken
`USER_GUIDE` § Exporting	PDF, PPTX, LaTeX, HTML, pakket	ODP ontbrak (#1769, sinds 2026-08-24 in de dialoog)
`USER_GUIDE` § Crop to fit	klik Bijsnijden; de dialoog "never rewrites the image file"	de knop heet Afbeelding aanpassen in alle vijf de editors, en draaien herschrijft het bestand op schijf wél

Die eerste is de vervelendste in zijn tweede helft: ePub stond alléén in USER_GUIDE.nl.md — de gegenereerde variant. De eerstvolgende make translate-docs had die tekst gewist, en een Engelse lezer wist er sowieso niets van. Een nieuw formaat hoort eerst in de Engelse bron.

De derde is de enige met een gedragskant: _writeRotatedBytes() in image_crop_dialog.dart schrijft de geroteerde pixels naar het bronbestand zodra je Klaar indrukt. Bij een afbeelding die meerdere decks delen verandert dat de foto overal. De alinea zegt dat nu, plus dat Annuleren niet schrijft en dat draaien niet wordt aangeboden voor bundled assets en URL's. Het gedrag zelf verandert deze PR niet — dat staat als los punt uit.

De rest

KNOWN_LIMITATIONS: "Exporting a document does not work on the web build" — opgelost in #1720 op 2026-08-22; het komt nu als browser-download. Kop en alinea herschreven, met de geschiedenis erbij.
KNOWN_LIMITATIONS + README + FAQ: laatste release 0.1.1 (2026-07-27) → 0.4.10 (2026-08-25, geverifieerd tegen de releaselijst op de forge: 12 assets, alle vier de platformen).
KNOWN_LIMITATIONS: ~71.500 vertalingen → ~107.800 (geteld 2026-08-30). En de "ongeveer vijftig veldlabels die hun Nederlandse brontekst tonen" is niet meer waar: EditorField doet l10n.d(widget.label), en app_localizations_test.dart laat de build vallen als zo'n bronsleutel in een taal ontbreekt.
ARCHITECTURE § Module layout: collab/, xmpp/ en meetings/ ontbraken — samen ~12.000 regels, dus samenwerken en bellen bestonden niet op deze kaart. De services/-lijst noemde negen van de vierentwintig submappen, waaronder een parts/ die niet meer bestaat; de zes exportmappen, de importer, de twee engines en de netwerkwacht ontbraken. Ook in het lagen-diagram opgenomen.
CHECKS: "every one of the 24 slide types" → de golden-lus loopt over SlideType.values (nu 32), dus het aantal is weg in plaats van opgehoogd. "627 files" → de reikwijdte (lib/, tool/, test/, samen 2.211 bestanden). uncoveredBaseline 84 → 92, met teldatum.
LICENSE_COMPLIANCE: 199 → 226 SBOM-componenten, BSD-3-Clause 127 → 141, MIT 50 → 59, OFL 5 → 6; en "five fonts" noemde er vier (Roboto Mono ontbrak sinds #1784).
PERFORMANCE_GUIDE: de tellingen van 19-07 waren in zes weken ongeveer verdubbeld (545 → 1.143 bestanden).
API_DOCUMENTATION: ExportFormat is { pdf, pptx, html } → { pdf, pptx, odp, html, latex }.
README (root): exportlijsten, "thirteen chart types" → veertien plus acht statistische met de module aan, en vier ontbrekende toplaag-mappen in de project-layout.
docs/README: KNOWN_LIMITATIONS.md en SECURITY_REVIEW_APT.md stonden niet in de index — de eerste is in de app gebundeld, vertaald en vanaf vier pagina's aangehaald.
USER_GUIDE + SHORTCUTS: de toetsen +/- zoomen een Mermaid-diagram tijdens het presenteren (presenter_keys.dart). Stonden nergens, en het is de enige van de vier zoomroutes die zonder aanwijsapparaat werkt.
USER_GUIDE.nl.md: een regel begon met #672 en rendert daardoor als kop in de documentatielezer. Ook: "zes statistische types" → acht (chartTypeRequiresProcesverbetering noemt er acht, en de sectie verderop zei dat al).

Waar een getal met de codebase meegroeit, is het gedateerd of vervangen door de reikwijdte.

Bewaker

Documentatie-only: raakt formaat, opslag noch een afhankelijkheid. Wél publieke beloftes — en dat is precies waarde 4 (beloftes in de interface en de documentatie zijn toetsbaar) die ze terugbrengt naar wat de code doet. Geen waardenbotsing af te wegen. De ene plek waar dit iets over het product zegt in plaats van over de tekst — destructief roteren tegenover waarde 3 — is als los punt uitgezet in plaats van hier meegenomen.

Toetsing

make check-static — groen
make check-registrations — groen (63 tests)
93 documentatietests groen: docs_claims_match_code, docs_enum_counts, doc_link, docs_anchor_links, doc_translation, docs_registration, callout_documentation
dart run tool/translate_docs.dart --check en tool/check_translated_mermaid.dart apart nagelopen

Geen regressietest bij deze wijziging: er is geen gedragsverandering om te bewaken. Wat wél mechaniseerbaar was, wordt al door de bestaande poorten gedekt — en één correctie kwam er zelfs uit voort: docs_claims_match_code viel op mijn eerste formulering "31 non-Dutch languages" omdat die poort elke N languages naast een vertaalwoord tegen AppLocalizations.languageNames houdt. Terecht; de zin is herschreven naar 32 met de bron erbij.

## Wat dit is De documentatie nagelopen tegen wat de app doet, en de dertien plekken waar die twee uiteen waren gelopen gecorrigeerd. Elke bewering is tegen de code getoetst; elke correctie draagt de datum in de tekst zelf, zoals de huisregel in `FAQ.md` en `MIGRATION_GUIDE.md`. ## De drie die een lezer echt op het verkeerde been zetten | Waar | Stond er | Klopt | |---|---|---| | `USER_GUIDE` § Exporting a document | vier formaten (md, HTML, PDF, LaTeX) | zes — **ePub** en **ODT** ontbraken | | `USER_GUIDE` § Exporting | PDF, PPTX, LaTeX, HTML, pakket | **ODP** ontbrak (#1769, sinds 2026-08-24 in de dialoog) | | `USER_GUIDE` § Crop to fit | klik **Bijsnijden**; de dialoog "never rewrites the image file" | de knop heet **Afbeelding aanpassen** in alle vijf de editors, en **draaien herschrijft het bestand op schijf wél** | Die eerste is de vervelendste in zijn tweede helft: ePub stond alléén in `USER_GUIDE.nl.md` — de **gegenereerde** variant. De eerstvolgende `make translate-docs` had die tekst gewist, en een Engelse lezer wist er sowieso niets van. Een nieuw formaat hoort eerst in de Engelse bron. De derde is de enige met een gedragskant: `_writeRotatedBytes()` in `image_crop_dialog.dart` schrijft de geroteerde pixels naar het bronbestand zodra je **Klaar** indrukt. Bij een afbeelding die meerdere decks delen verandert dat de foto overal. De alinea zegt dat nu, plus dat **Annuleren** niet schrijft en dat draaien niet wordt aangeboden voor bundled assets en URL's. *Het gedrag zelf verandert deze PR niet* — dat staat als los punt uit. ## De rest - `KNOWN_LIMITATIONS`: "Exporting a document does not work on the web build" — opgelost in #1720 op 2026-08-22; het komt nu als browser-download. Kop en alinea herschreven, met de geschiedenis erbij. - `KNOWN_LIMITATIONS` + `README` + `FAQ`: laatste release `0.1.1` (2026-07-27) → `0.4.10` (2026-08-25, geverifieerd tegen de releaselijst op de forge: 12 assets, alle vier de platformen). - `KNOWN_LIMITATIONS`: ~71.500 vertalingen → ~107.800 (geteld 2026-08-30). En de "ongeveer vijftig veldlabels die hun Nederlandse brontekst tonen" is niet meer waar: `EditorField` doet `l10n.d(widget.label)`, en `app_localizations_test.dart` laat de build vallen als zo'n bronsleutel in een taal ontbreekt. - `ARCHITECTURE` § Module layout: `collab/`, `xmpp/` en `meetings/` ontbraken — samen ~12.000 regels, dus samenwerken en bellen bestonden niet op deze kaart. De `services/`-lijst noemde negen van de vierentwintig submappen, waaronder een `parts/` die niet meer bestaat; de zes exportmappen, de importer, de twee engines en de netwerkwacht ontbraken. Ook in het lagen-diagram opgenomen. - `CHECKS`: "every one of the 24 slide types" → de golden-lus loopt over `SlideType.values` (nu 32), dus het aantal is weg in plaats van opgehoogd. "627 files" → de reikwijdte (`lib/`, `tool/`, `test/`, samen 2.211 bestanden). `uncoveredBaseline` 84 → 92, met teldatum. - `LICENSE_COMPLIANCE`: 199 → 226 SBOM-componenten, BSD-3-Clause 127 → 141, MIT 50 → 59, OFL 5 → 6; en "five fonts" noemde er vier (Roboto Mono ontbrak sinds #1784). - `PERFORMANCE_GUIDE`: de tellingen van 19-07 waren in zes weken ongeveer verdubbeld (545 → 1.143 bestanden). - `API_DOCUMENTATION`: `ExportFormat is { pdf, pptx, html }` → `{ pdf, pptx, odp, html, latex }`. - `README` (root): exportlijsten, "thirteen chart types" → veertien plus acht statistische met de module aan, en vier ontbrekende toplaag-mappen in de project-layout. - `docs/README`: `KNOWN_LIMITATIONS.md` en `SECURITY_REVIEW_APT.md` stonden niet in de index — de eerste is in de app gebundeld, vertaald en vanaf vier pagina's aangehaald. - `USER_GUIDE` + `SHORTCUTS`: de toetsen `+`/`-` zoomen een Mermaid-diagram tijdens het presenteren (`presenter_keys.dart`). Stonden nergens, en het is de enige van de vier zoomroutes die zonder aanwijsapparaat werkt. - `USER_GUIDE.nl.md`: een regel begon met `#672` en rendert daardoor als kop in de documentatielezer. Ook: "zes statistische types" → acht (`chartTypeRequiresProcesverbetering` noemt er acht, en de sectie verderop zei dat al). Waar een getal met de codebase meegroeit, is het gedateerd of vervangen door de reikwijdte. ## Bewaker Documentatie-only: raakt formaat, opslag noch een afhankelijkheid. Wél publieke beloftes — en dat is precies waarde 4 (*beloftes in de interface en de documentatie zijn toetsbaar*) die ze terugbrengt naar wat de code doet. Geen waardenbotsing af te wegen. De ene plek waar dit iets over het *product* zegt in plaats van over de tekst — destructief roteren tegenover waarde 3 — is als los punt uitgezet in plaats van hier meegenomen. ## Toetsing - `make check-static` — groen - `make check-registrations` — groen (63 tests) - 93 documentatietests groen: `docs_claims_match_code`, `docs_enum_counts`, `doc_link`, `docs_anchor_links`, `doc_translation`, `docs_registration`, `callout_documentation` - `dart run tool/translate_docs.dart --check` en `tool/check_translated_mermaid.dart` apart nagelopen Geen regressietest bij deze wijziging: er is geen gedragsverandering om te bewaken. Wat wél mechaniseerbaar was, wordt al door de bestaande poorten gedekt — en één correctie kwam er zelfs uit voort: `docs_claims_match_code` viel op mijn eerste formulering "31 non-Dutch languages" omdat die poort elke *N languages* naast een vertaalwoord tegen `AppLocalizations.languageNames` houdt. Terecht; de zin is herschreven naar 32 met de bron erbij.

brenno added 1 commit

2026-08-30 12:55:44 +00:00

docs: breng de documentatie terug in overeenstemming met de code

scans / scans (pull_request) Successful in 2m31s

Details

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

Details

abf3f3d2d8

Dertien beweringen in docs/ en README.md die niet meer klopten, elk tegen
de code getoetst en gedateerd gecorrigeerd in de tekst zelf (huisregel uit
FAQ.md/MIGRATION_GUIDE.md).

De drie die een lezer echt op het verkeerde been zetten:

- USER_GUIDE noemde vier documentexportformaten terwijl de dialoog er zes
  aanbiedt. ePub stond alléén in USER_GUIDE.nl.md — de *gegenereerde*
  variant — waar de eerstvolgende `make translate-docs` hem had gewist;
  ODT stond nergens. Beide nu in de Engelse bron, ODT ook in het
  Nederlands.
- De deck-exportlijst sprong van PPTX meteen door naar LaTeX; ODP (#1769,
  sinds 2026-08-24 in de dialoog) ontbrak.
- De alinea over bijsnijden stuurde de lezer naar een knop **Bijsnijden**
  die in geen van de vijf editors zo heet (het is "Afbeelding aanpassen"),
  en beloofde dat de dialoog "never rewrites the image file" — terwijl de
  draaiknoppen ernaast het bestand op schijf herschrijven zodra je op
  Klaar drukt. Die alinea zegt nu wat er wél gebeurt, en voor welke
  afbeeldingen draaien niet wordt aangeboden.

Verder: KNOWN_LIMITATIONS beweerde nog dat documentexport niet werkt op
web (opgelost in #1720, 2026-08-22 — het komt nu als browser-download) en
noemde `0.1.1` als laatste release waar het `0.4.10` is (idem in README en
FAQ); het vertaalaantal stond op 71.500 tegen ~107.800 nu, en de "vijftig
Nederlandse veldlabels" die het noemde lopen allang door `l10n.d()`.
ARCHITECTURE miste `collab/`, `xmpp/` en `meetings/` — samen zo'n 12.000
regels — plus vijftien `services/`-submappen, en noemde een `parts/` die
niet meer bestaat. CHECKS sprak van 24 slidetypes waar de golden-lus over
`SlideType.values` (32) loopt en van "627 files" waar er 2.211 staan.
LICENSE_COMPLIANCE telde 199 SBOM-componenten tegen 226, en "vijf fonts"
terwijl het er vier noemde (Roboto Mono ontbrak sinds #1784).
PERFORMANCE_GUIDE droeg de tellingen van 19-07 die sindsdien verdubbeld
zijn. De docs-index liet KNOWN_LIMITATIONS en SECURITY_REVIEW_APT weg. De
toetsenbordzoom `+`/`-` op een Mermaid-dia stond nergens — de enige van de
vier zoomroutes die zonder aanwijsapparaat werkt. En een regel in de
Nederlandse gids begon met `#672`, wat in de documentatielezer als kop
rendert.

Waar een getal met de codebase meegroeit is het gedateerd of vervangen
door de reikwijdte: de golden-lus loopt over `SlideType.values`, dus daar
hoort geen aantal naast.

Bewaker-toets: documentatie-only, raakt formaat noch opslag noch een
afhankelijkheid. Wel publieke beloftes — en dit is precies waarde 4
(beloftes zijn toetsbaar) die ze terugbrengt naar wat de code doet. Geen
waardenbotsing. Dat draaien het bronbestand herschrijft is als los punt
uitgezet; deze PR beschrijft het gedrag, verandert het niet.

Poort: make check-static groen, make check-registrations groen, en de
93 documentatietests (docs_claims_match_code, docs_enum_counts, doc_link,
docs_anchor_links, doc_translation, docs_registration,
callout_documentation) groen. translate_docs --check en
check_translated_mermaid apart nagelopen.

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

brenno merged commit 3bfcd3a67a into main

2026-08-30 19:23:45 +00:00

brenno referenced this pull request from a commit

2026-08-30 19:23:47 +00:00

docs: breng de documentatie terug in overeenstemming met de code (#1870)

brenno referenced this pull request

2026-08-30 20:03:45 +00:00

ux(bijsnijden): draaien waarschuwt vooraf dat het het bestand herschrijft #1872