docs(bestandsformaat): §14.11 aangevuld en vertaald #1573

Merged

brenno merged 1 commit from docs/tijdlijn-sectie-aanvullen into main

2026-08-19 10:20:15 +00:00

brenno commented

2026-08-19 10:12:23 +00:00

Owner

Opvolger van #1571, en de uitwerking van de drie punten uit mijn reactie daar.

Vooraf, want dat hoort erbij: §14.11 kwám in dezelfde PR als de functie. Dat is precies de volgorde die deze repo wil. Wat er ontbrak zijn drie dingen die pas opvallen als je de sectie naast §14.9 en §14.10 legt.

1. Het rijtje per oppervlak

§14.9 (voetnoten) en §14.10 (inhoudsopgave) sluiten allebei af met wat elke uitvoer met de bytes doet. Dat is wat iemand in het bestandsformaat komt halen: mijn tabel staat er, wat gebeurt ermee als ik exporteer. Alle vier nagerekend tegen de gemergede code, niet tegen het ontwerp:

Het geprojecteerde .md houdt marker én tabel byte voor byte (op na wat OciWacht in de cellen redigeert). document_export_privacy_test legt dat al vast met expect(out, contains('\n| Tijd |')) — de belofte stond dus in een test maar niet in het formaat.
De HTML-export rendert de rijen als tijdlijnlijst; elk item draagt break-inside: avoid, zodat afdrukken geen gebeurtenis doormidden knipt op een velgrens.
De LaTeX-export schrijft \begin{description} en geen tabular; een derde kolom komt achter de gebeurtenis als Kop: waarde. Daarom doet de kopnaam ertoe voor de lezer en niet voor OciDeck — dat is een nuttiger formulering van "header names have no prescribed meaning" dan die zin alleen.
De bewerker en Pagina's tonen de tijdlijn; in de visuele modus reizen marker en tabel als één embed, dus er kan geen marker zonder tabel achterblijven.

2. Herkenning, zo precies als de code hem leest

"immediately preceded by this exact marker" was aan beide kanten onnauwkeurig. TimelineTableSyntax matcht ^\s*\s*$, dus witruimte eromheen mag en een ingesprongen marker telt gewoon mee. Maar de schrijfwijze binnen het commentaar is wél streng:  en  zijn gewone HTML-commentaren. Beide helften staan er nu, met waarom die strengheid er is: het houdt tegen dat een toevallig commentaar stilletjes iemands tabel omvormt.

3. `FILE_FORMAT.nl.md`

Die is de versie die in de app wordt getoond, en had §14.11 niet. translate-docs-check merkt dat niet op — die poort toetst of een variant bestaat en geregistreerd is, niet of hij bij is. Zo kon §14.9 er eerder helemaal uit blijven met alles groen (#1568). De Nederlandse sectie is er nu, inclusief de aanvullingen hierboven.

Getoetst

make check-static groen.
flutter test op docs_enum_counts_test.dart, docs_anchor_links_test.dart, doc_link_test.dart — 35 toetsen groen, inclusief de ankercontrole over de nieuwe verwijzingen.
Geen lib/-wijziging: alleen documentatie en de changelog.

Wat dit niet oplost

Er is nog steeds geen poort die zegt "een ### 14.x in de Engelse bron hoort een tegenhanger te hebben in .nl.md". Die zou dit geval hebben gevangen én het vorige. Ik heb hem niet in deze PR gestopt omdat het een aparte afweging is; hij staat als voorstel bij de indiener.

Opvolger van #1571, en de uitwerking van de drie punten uit [mijn reactie daar](https://pawprint.vigilis.online/LibreKAT/Ocideck/pulls/1571#issuecomment-10256). Vooraf, want dat hoort erbij: §14.11 kwám in dezelfde PR als de functie. Dat is precies de volgorde die deze repo wil. Wat er ontbrak zijn drie dingen die pas opvallen als je de sectie naast §14.9 en §14.10 legt. ## 1. Het rijtje per oppervlak §14.9 (voetnoten) en §14.10 (inhoudsopgave) sluiten allebei af met wat elke uitvoer met de bytes doet. Dat is wat iemand in het bestandsformaat komt halen: mijn tabel staat er, wat gebeurt ermee als ik exporteer. Alle vier nagerekend tegen de gemergede code, niet tegen het ontwerp: - Het **geprojecteerde `.md`** houdt marker én tabel byte voor byte (op na wat OciWacht in de cellen redigeert). `document_export_privacy_test` legt dat al vast met `expect(out, contains('\n| Tijd |'))` — de belofte stond dus in een test maar niet in het formaat. - De **HTML-export** rendert de rijen als tijdlijnlijst; elk item draagt `break-inside: avoid`, zodat afdrukken geen gebeurtenis doormidden knipt op een velgrens. - De **LaTeX-export** schrijft `\begin{description}` en geen `tabular`; een derde kolom komt achter de gebeurtenis als `Kop: waarde`. Daarom doet de kopnaam ertoe voor de lezer en niet voor OciDeck — dat is een nuttiger formulering van "header names have no prescribed meaning" dan die zin alleen. - De **bewerker en Pagina's** tonen de tijdlijn; in de visuele modus reizen marker en tabel als één embed, dus er kan geen marker zonder tabel achterblijven. ## 2. Herkenning, zo precies als de code hem leest "immediately preceded by this exact marker" was aan beide kanten onnauwkeurig. `TimelineTableSyntax` matcht `^\s*\s*$`, dus witruimte eromheen mag en een ingesprongen marker telt gewoon mee. Maar de schrijfwijze *binnen* het commentaar is wél streng: `` en `` zijn gewone HTML-commentaren. Beide helften staan er nu, met waarom die strengheid er is: het houdt tegen dat een toevallig commentaar stilletjes iemands tabel omvormt. ## 3. `FILE_FORMAT.nl.md` Die is de versie die in de app wordt getoond, en had §14.11 niet. `translate-docs-check` merkt dat niet op — die poort toetst of een variant bestaat en geregistreerd is, niet of hij bij is. Zo kon §14.9 er eerder helemaal uit blijven met alles groen (#1568). De Nederlandse sectie is er nu, inclusief de aanvullingen hierboven. ## Getoetst - `make check-static` groen. - `flutter test` op `docs_enum_counts_test.dart`, `docs_anchor_links_test.dart`, `doc_link_test.dart` — 35 toetsen groen, inclusief de ankercontrole over de nieuwe verwijzingen. - Geen `lib/`-wijziging: alleen documentatie en de changelog. ## Wat dit niet oplost Er is nog steeds geen poort die zegt "een `### 14.x` in de Engelse bron hoort een tegenhanger te hebben in `.nl.md`". Die zou dit geval hebben gevangen én het vorige. Ik heb hem niet in deze PR gestopt omdat het een aparte afweging is; hij staat als voorstel bij de indiener.

brenno added 1 commit

2026-08-19 10:12:24 +00:00

docs(bestandsformaat): §14.11 aangevuld en vertaald

scans / scans (pull_request) Successful in 3m5s

Details

static-gate / static-gate (pull_request) Successful in 7m28s

Details

2eda478427

De tijdlijnsectie kwam met de functie mee (#1571) — netjes, in dezelfde PR —
maar alleen in het Engels en zonder het rijtje dat §14.9 en §14.10 wél hebben:
wat elk oppervlak met deze bytes doet op de weg naar buiten. Dat is nu juist
wat een lezer van het bestandsformaat komt halen.

Aangevuld, alle vier nagerekend tegen de gemergede code:
- het geprojecteerde `.md` houdt marker én tabel byte voor byte (vastgelegd in
  `document_export_privacy_test`);
- de HTML-export maakt er een tijdlijnlijst van waarvan elk item
  `break-inside: avoid` draagt, zodat afdrukken geen gebeurtenis doormidden knipt;
- de LaTeX-export schrijft een `description`-lijst in plaats van een `tabular`,
  met een derde kolom als `Kop: waarde`;
- in de visuele modus reizen marker en tabel als één embed.

Rechtgezet: "this exact marker" was aan beide kanten onnauwkeurig. Witruimte om
de marker heen mag (`^\s*<!-- timeline -->\s*$`), de schrijfwijze erbinnen niet —
`<!--timeline-->` en `<!-- Timeline -->` zijn gewoon commentaar. Dezelfde nuance
staat sinds #1568 bij `<!-- toc -->`.

En de Nederlandse variant heeft de sectie nu ook. Dat is de versie die in de app
wordt getoond, en `translate-docs-check` toetst alleen of hij bestaat en
geregistreerd is — niet of hij bij is.

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

brenno merged commit bccf097303 into main

2026-08-19 10:20:15 +00:00

brenno referenced this pull request from a commit

2026-08-19 10:20:16 +00:00

docs(bestandsformaat): 14.11 aangevuld en vertaald (#1573)

brenno referenced this pull request from a commit

2026-08-19 10:52:59 +00:00

feat(poort): translate-docs-check toetst of een vertaling bíj is, niet alleen dat hij bestaat

brenno referenced this pull request

2026-08-19 10:53:31 +00:00

feat(poort): een vertaalde gids moet bíj zijn, niet alleen bestaan #1576

brenno referenced this pull request