Ontwerp: paginaopmaak per document laten meereizen (front matter) #1511

Closed
opened 2026-08-17 09:41:24 +00:00 by brenno · 3 comments
Owner

Paginamaat, marges en drukkersafloop staan in AppSettings (app-breed, SharedPreferences). Hetzelfde .md-bestand pagineert bij een ander dus anders en exporteert op een ander formaat.

De bewaker (bij PR #1505) noemt de huidige keuze verdedigbaar als standaard, maar niet als enige plek:

  • Maat en marges mogen app-breed blijven. Een .md heeft geen pagina's — dat is de winst van het formaat, niet een gebrek.
  • De afloop is geen voorkeur maar een eigenschap van dít drukwerk. Wie hem één keer aanzet voor een folder, exporteert daarna stilzwijgend elke brief op 216×303 mm. (Deels verzacht: de afloop staat sinds #1505 in de paginamaat-indicator in beeld en de instellingentekst waarschuwt ervoor.)
  • Het tweede bezwaar is navolgbaarheid: nergens staat met welke instellingen een verstuurde PDF is gemaakt.

Voorgestelde richting (ontwerp eerst, dan pas code):

  • Front matter, niet een sidecar: een .md dat je mailt raakt zijn sidecar kwijt, en opmaak die stil wegvalt is erger dan opmaak die niet meereist.
  • Eén sleutel met prefix (ocideck_page_…), niet page:/margins: — die botsen met handgeschreven Hugo/Jekyll-sleutels.
  • Zelfde regels als de bestaande theme:-sleutel (FILE_FORMAT.md §14.5): opt-in, byte-chirurgisch, alleen op verzoek geschreven, nooit automatisch. Zelfde volgorde-resolver: afdwingen → document → instellingen.
  • §14.5 zegt nu letterlijk dat theme: de enige sleutel is die het documentpad ooit schrijft. Een tweede sleutel is dus een formaatwijziging, en die vraagt hier eerst een afgetoetst ontwerp.

Dit issue is het ontwerp, niet de bouw. Uitkomst: een voorstel dat langs de bewaker en de formaatregels is geweest, met de round-trip-garantie expliciet nagelopen.

Paginamaat, marges en drukkersafloop staan in `AppSettings` (app-breed, SharedPreferences). Hetzelfde `.md`-bestand pagineert bij een ander dus anders en exporteert op een ander formaat. De bewaker (bij PR #1505) noemt de huidige keuze verdedigbaar als *standaard*, maar niet als enige plek: - **Maat en marges** mogen app-breed blijven. Een `.md` heeft geen pagina's — dat is de winst van het formaat, niet een gebrek. - **De afloop is geen voorkeur maar een eigenschap van dít drukwerk.** Wie hem één keer aanzet voor een folder, exporteert daarna stilzwijgend elke brief op 216×303 mm. (Deels verzacht: de afloop staat sinds #1505 in de paginamaat-indicator in beeld en de instellingentekst waarschuwt ervoor.) - Het tweede bezwaar is **navolgbaarheid**: nergens staat met welke instellingen een verstuurde PDF is gemaakt. **Voorgestelde richting (ontwerp eerst, dan pas code):** - Front matter, niet een sidecar: een `.md` dat je mailt raakt zijn sidecar kwijt, en opmaak die stil wegvalt is erger dan opmaak die niet meereist. - Eén sleutel met prefix (`ocideck_page_…`), niet `page:`/`margins:` — die botsen met handgeschreven Hugo/Jekyll-sleutels. - Zelfde regels als de bestaande `theme:`-sleutel (FILE_FORMAT.md §14.5): opt-in, byte-chirurgisch, alleen op verzoek geschreven, nooit automatisch. Zelfde volgorde-resolver: afdwingen → document → instellingen. - §14.5 zegt nu letterlijk dat `theme:` de **enige** sleutel is die het documentpad ooit schrijft. Een tweede sleutel is dus een formaatwijziging, en die vraagt hier eerst een afgetoetst ontwerp. **Dit issue is het ontwerp**, niet de bouw. Uitkomst: een voorstel dat langs de bewaker en de formaatregels is geweest, met de round-trip-garantie expliciet nagelopen.
Author
Owner

Ontwerpvoorstel: paginaopmaak per document

Uitgangspunt van de bewaker: maat en marges mogen app-breed blijven (een .md heeft geen pagina's — dat is de winst van het formaat), maar de afloop is een eigenschap van dít drukwerk, en navolgbaarheid vraagt dat een verstuurde PDF reproduceerbaar is. Dit voorstel maakt paginaopmaak optioneel per document, met de app-instelling als standaard.

De sleutels: twee, en ze bestaan al

---
theme: LibreKAT
ocideck_page_size: A4
ocideck_page_margins: 25,25,20,20,3
---
  • ocideck_page_size draagt exact PageSizeSpec.id (A4, A4L, B5, C6L).
  • ocideck_page_margins draagt exact PageMargins.id — boven,onder,links,rechts, met de afloop als optioneel vijfde veld. Dat is dezelfde string die nu al in de instellingen wordt bewaard.

Geen nieuw serialisatieformaat dus, en geen tweede plek waar de betekenis van die getallen wordt vastgelegd: één codec, twee afnemers. De prefix ocideck_ is verplicht — page:/margins: zouden botsen met handgeschreven Hugo/Jekyll-sleutels.

Waarom front matter en geen sidecar: een .md dat je mailt raakt zijn sidecar kwijt. Opmaak die stil wegvalt is erger dan opmaak die niet meereist. Sidecars zijn hier voor inhoud (ink, grafiekdata), niet voor twee regels.

Volgorde van gelden

Afdwingen → document → instelling, precies zoals effectiveDocumentStyleName dat voor de stijl doet:

  1. een afgedwongen huisstijl-paginamaat, als die ooit komt (nu niet gebouwd);
  2. de sleutels in dit document;
  3. de app-instelling.

Een document zonder deze sleutels gedraagt zich exact als vandaag.

Schrijfgedrag: dezelfde regels als theme:

  • Opt-in en alleen op verzoek. Niets wordt automatisch geschreven; wie nooit "geldt voor dit document" kiest, houdt een .md zonder front matter.
  • Byte-chirurgisch. Zetten en weer wissen levert de oorspronkelijke bytes op. Handgeschreven sleutels blijven verbatim staan; alleen deze twee regels worden aangeraakt. Was het blok verder leeg, dan verdwijnt het hele blok.
  • Geen herkenningsmarkering. Herkenning blijft de afwezigheid van marp: true; deze sleutels slepen nooit marp:/paginate: mee.
  • Een onbekende waarde is geen fout. Een onleesbare maat valt terug op de instelling, zoals een ontbrekend stijlprofiel dat ook doet.
  • Reist niet mee op conversie. Een document dat een presentatie wordt, laat ze vallen — net als theme:.

Bediening

De paginamaat-indicator in de hoek van de visuele stand wordt aanklikbaar: "geldt voor dit document" naast "mijn standaard". Dat is de plek waar je de maat toch al ziet staan, en het maakt zichtbaar wélke van de twee geldt. In de instellingen blijft staan wat de standaard is voor nieuwe documenten.

Open punt: hoort de hoofdstukafbreking er ook bij?

AppSettings.documentChapterPageBreak ("nieuw hoofdstuk op een nieuwe pagina") bepaalt óók de pagina-indeling, en werkt door in HTML-print en LaTeX (§14.6). Reist die niet mee, dan pagineren twee machines het document nog steeds verschillend — dan is het probleem maar half opgelost. Argument tegen: het is een derde sleutel in andermans bestand.

Mijn voorkeur is meenemen, als ocideck_page_chapter_break: true, en alleen schrijven wanneer hij afwijkt van de standaard (false). Graag een oordeel hierop.

Wat dit kost aan uitwisselbaarheid

Een vreemde lezer ziet twee onbekende YAML-sleutels en negeert ze; Jekyll, Hugo en Obsidian houden ze staan als paginavariabelen. front_matter_merge.dart bewaart ze al. De bestaande belofte in FILE_FORMAT.md §14.3 (byte-getrouwe round-trip) blijft staan, en §14.5 moet worden bijgewerkt: theme: is dan niet langer de enige sleutel die het documentpad schrijft. Dat is de eigenlijke formaatwijziging waarvoor dit ontwerp er is.

Wat er níet in zit

Geen paginanummers, kop- of voetteksten in het bestand: die komen uit het stijlprofiel en horen daar. Geen afdwingbare huisstijl-paginamaat in deze ronde. Geen automatische migratie — bestaande documenten blijven ongewijzigd.

## Ontwerpvoorstel: paginaopmaak per document Uitgangspunt van de bewaker: maat en marges mogen app-breed blijven (een `.md` heeft geen pagina's — dat is de winst van het formaat), maar de **afloop** is een eigenschap van dít drukwerk, en **navolgbaarheid** vraagt dat een verstuurde PDF reproduceerbaar is. Dit voorstel maakt paginaopmaak *optioneel* per document, met de app-instelling als standaard. ### De sleutels: twee, en ze bestaan al ``` --- theme: LibreKAT ocideck_page_size: A4 ocideck_page_margins: 25,25,20,20,3 --- ``` - `ocideck_page_size` draagt exact `PageSizeSpec.id` (`A4`, `A4L`, `B5`, `C6L`). - `ocideck_page_margins` draagt exact `PageMargins.id` — boven,onder,links,rechts, met de afloop als optioneel vijfde veld. Dat is dezelfde string die nu al in de instellingen wordt bewaard. Geen nieuw serialisatieformaat dus, en geen tweede plek waar de betekenis van die getallen wordt vastgelegd: één codec, twee afnemers. De prefix `ocideck_` is verplicht — `page:`/`margins:` zouden botsen met handgeschreven Hugo/Jekyll-sleutels. **Waarom front matter en geen sidecar:** een `.md` dat je mailt raakt zijn sidecar kwijt. Opmaak die stil wegvalt is erger dan opmaak die niet meereist. Sidecars zijn hier voor inhoud (ink, grafiekdata), niet voor twee regels. ### Volgorde van gelden Afdwingen → document → instelling, precies zoals `effectiveDocumentStyleName` dat voor de stijl doet: 1. een afgedwongen huisstijl-paginamaat, als die ooit komt (nu niet gebouwd); 2. de sleutels in dit document; 3. de app-instelling. Een document zonder deze sleutels gedraagt zich exact als vandaag. ### Schrijfgedrag: dezelfde regels als `theme:` - **Opt-in en alleen op verzoek.** Niets wordt automatisch geschreven; wie nooit "geldt voor dit document" kiest, houdt een `.md` zonder front matter. - **Byte-chirurgisch.** Zetten en weer wissen levert de oorspronkelijke bytes op. Handgeschreven sleutels blijven verbatim staan; alleen deze twee regels worden aangeraakt. Was het blok verder leeg, dan verdwijnt het hele blok. - **Geen herkenningsmarkering.** Herkenning blijft de *afwezigheid* van `marp: true`; deze sleutels slepen nooit `marp:`/`paginate:` mee. - **Een onbekende waarde is geen fout.** Een onleesbare maat valt terug op de instelling, zoals een ontbrekend stijlprofiel dat ook doet. - **Reist niet mee op conversie.** Een document dat een presentatie wordt, laat ze vallen — net als `theme:`. ### Bediening De paginamaat-indicator in de hoek van de visuele stand wordt aanklikbaar: *"geldt voor dit document"* naast *"mijn standaard"*. Dat is de plek waar je de maat toch al ziet staan, en het maakt zichtbaar wélke van de twee geldt. In de instellingen blijft staan wat de standaard is voor nieuwe documenten. ### Open punt: hoort de hoofdstukafbreking er ook bij? `AppSettings.documentChapterPageBreak` ("nieuw hoofdstuk op een nieuwe pagina") bepaalt óók de pagina-indeling, en werkt door in HTML-print en LaTeX (§14.6). Reist die niet mee, dan pagineren twee machines het document nog steeds verschillend — dan is het probleem maar half opgelost. Argument tegen: het is een derde sleutel in andermans bestand. Mijn voorkeur is meenemen, als `ocideck_page_chapter_break: true`, en alleen schrijven wanneer hij afwijkt van de standaard (`false`). Graag een oordeel hierop. ### Wat dit kost aan uitwisselbaarheid Een vreemde lezer ziet twee onbekende YAML-sleutels en negeert ze; Jekyll, Hugo en Obsidian houden ze staan als paginavariabelen. `front_matter_merge.dart` bewaart ze al. De bestaande belofte in FILE_FORMAT.md §14.3 (byte-getrouwe round-trip) blijft staan, en §14.5 moet worden bijgewerkt: `theme:` is dan niet langer de enige sleutel die het documentpad schrijft. Dat is de eigenlijke formaatwijziging waarvoor dit ontwerp er is. ### Wat er níet in zit Geen paginanummers, kop- of voetteksten in het bestand: die komen uit het stijlprofiel en horen daar. Geen afdwingbare huisstijl-paginamaat in deze ronde. Geen automatische migratie — bestaande documenten blijven ongewijzigd.
Author
Owner

Ontwerp v2 — na de bewaker

Het eerste voorstel is geblokkeerd, en terecht. Ik neem alle vijf de punten over. Wat wegvalt en wat ervoor in de plaats komt:

Weg: de ocideck_-sleutels

§14.1 zegt letterlijk dat OciDeck geen eigen sleutels toevoegt — geen kind:, geen ocideck:. theme: was daar geen uitzondering op: die sleutel kennen pandoc, Obsidian en GitHub al, en dat is precies de reden dat hij daar mág staan (lib/utils/document_front_matter.dart). Een ocideck_page_size: heeft die rechtvaardiging niet en zou informatie meesturen die alleen binnen OciDeck betekenis heeft.

In plaats daarvan: vocabulaire die elders écht wordt uitgevoerd

---
theme: LibreKAT
papersize: a4
geometry: top=25mm,bottom=25mm,left=20mm,right=20mm
---

Pandoc voert dit uit. Wie het .md naar zijn eigen pandoc voert — de uitgang die DOCUMENT_MODE.md zelf aanwijst — krijgt dezelfde pagina, zonder OciDeck. Dat is uitwisselbaarheid in plaats van bytes die meereizen zonder betekenis.

De geometry-string wordt al letterlijk geproduceerd door PageMargins.latexMargin; de LaTeX-export schrijft hem vandaag al zo. Eén bron, twee afnemers — maar nu in een vorm die zichzelf uitlegt.

Daarmee vervalt ook 25,25,20,20,3 als bestandsinhoud. De bewaker wees op een echte val: die volgorde is boven,onder,links,rechts, terwijl cssMargin in dezelfde klasse de CSS-volgorde boven,rechts,onder,links schrijft. Wie de regel als CSS-achtig leest, wisselt onder en rechts om en drukt stil een verkeerde tekstspiegel af — geldige getallen, geen foutmelding. En het zesveldsformaat met de dode snijtekens-vlag zou als wrat in een publiek formaat belanden.

De afloop: als echte maten, niet als vlag

Een drukkersafloop heeft geen pandoc-vocabulaire. Hij komt daarom in dezelfde geometry-sleutel als expliciete maten — precies wat onze eigen LaTeX-export al doet:

geometry: paperwidth=216mm,paperheight=303mm,top=28mm,bottom=28mm,left=23mm,right=23mm

De prijs is eerlijk te benoemen: het bestand draagt de effectieve maat, niet de abstractie "A4 plus 3 mm". Bij inlezen leidt OciDeck dat terug af — is de papiermaat een ISO-maat plus tweemaal hetzelfde getal, dan toont hij "A4 + 3 mm afloop"; anders een vrije maat. Die afleiding is een gemak in de interface, geen betekenis in het bestand.

Hoofdstukafbreking: geen sleutel maar gewone Markdown

Het antwoord op mijn eigen open vraag, en beter dan wat ik voorstelde. §14.6 kent al de juiste vorm: een --- vóór een H1 is een pagina-einde dat élke lezer honoreert. Dus geen vierde privé-sleutel, maar een eenmalige bewerking van de body: "hoofdstukafbrekingen in dit document toepassen" zet ----regels neer. Zichtbaar, door de gebruiker terug te draaien, en het reist naar pandoc, GitHub en de printer van de ontvanger.

Wat er verder bij hoort voordat dit mag landen

  • Een eigendomsregister voor documentsleutels, zoals het deckpad dat heeft (kOwnedFrontMatterKeys/kRetiredFrontMatterKeys in front_matter_merge.dart), inclusief terugtrekroute. Zonder dat is er geen pad om een sleutel ooit nog uit bestaande bestanden te krijgen — de uitgang moet net zo makkelijk zijn als de ingang.
  • §14.7 herschrijven mét koerswijzigingsnotitie. Die paragraaf stelt vandaag als bewuste keuze vast dat er niets naar het .md wordt geschreven en dat het vel niet meereist. Dat terugdraaien mag, maar niet stilzwijgend: er hoort een zichtbare "we hebben ons bedacht, en hierom" bij. Idem §14.1 en §14.5.
  • De geprojecteerde .md-export moet de sleutels meenemen (§14.4). Doet hij dat niet, dan drukt de ontvanger het alsnog op zíjn vel af — precies de storing die dit moest verhelpen.
  • Round-trip-toets zoals theme: die heeft: zetten en terug naar "mijn standaard" geeft de exacte oorspronkelijke bytes, inclusief het geval waarin het blok daarmee leeg wordt.
  • De bediening langs gebruiksgemak. De bewaker merkte terecht op dat een te makkelijke knop sleutels schrijft in bestanden die de gebruiker niet wilde wijzigen.

Wat blijft staan

Volgorde van gelden (afdwingen → document → instelling), opt-in en alleen op verzoek schrijven, byte-chirurgisch, geen herkenningsmarkering, en een onleesbare waarde valt terug op de instelling in plaats van te falen.

## Ontwerp v2 — na de bewaker Het eerste voorstel is geblokkeerd, en terecht. Ik neem alle vijf de punten over. Wat wegvalt en wat ervoor in de plaats komt: ### Weg: de `ocideck_`-sleutels §14.1 zegt letterlijk dat OciDeck **geen eigen sleutels** toevoegt — geen `kind:`, geen `ocideck:`. `theme:` was daar geen uitzondering op: die sleutel kennen pandoc, Obsidian en GitHub al, en dat is precies de reden dat hij daar mág staan (`lib/utils/document_front_matter.dart`). Een `ocideck_page_size:` heeft die rechtvaardiging niet en zou informatie meesturen die alleen binnen OciDeck betekenis heeft. ### In plaats daarvan: vocabulaire die elders écht wordt uitgevoerd ``` --- theme: LibreKAT papersize: a4 geometry: top=25mm,bottom=25mm,left=20mm,right=20mm --- ``` Pandoc voert dit uit. Wie het `.md` naar zijn eigen pandoc voert — de uitgang die DOCUMENT_MODE.md zelf aanwijst — krijgt dezelfde pagina, zonder OciDeck. Dat is uitwisselbaarheid in plaats van bytes die meereizen zonder betekenis. De `geometry`-string wordt al letterlijk geproduceerd door `PageMargins.latexMargin`; de LaTeX-export schrijft hem vandaag al zo. Eén bron, twee afnemers — maar nu in een vorm die zichzelf uitlegt. Daarmee vervalt ook `25,25,20,20,3` als bestandsinhoud. De bewaker wees op een echte val: die volgorde is boven,onder,links,rechts, terwijl `cssMargin` in dezelfde klasse de CSS-volgorde boven,rechts,onder,links schrijft. Wie de regel als CSS-achtig leest, wisselt onder en rechts om en drukt stil een verkeerde tekstspiegel af — geldige getallen, geen foutmelding. En het zesveldsformaat met de dode snijtekens-vlag zou als wrat in een publiek formaat belanden. ### De afloop: als echte maten, niet als vlag Een drukkersafloop heeft geen pandoc-vocabulaire. Hij komt daarom in dezelfde `geometry`-sleutel als expliciete maten — precies wat onze eigen LaTeX-export al doet: ``` geometry: paperwidth=216mm,paperheight=303mm,top=28mm,bottom=28mm,left=23mm,right=23mm ``` De prijs is eerlijk te benoemen: het bestand draagt de *effectieve* maat, niet de abstractie "A4 plus 3 mm". Bij inlezen leidt OciDeck dat terug af — is de papiermaat een ISO-maat plus tweemaal hetzelfde getal, dan toont hij "A4 + 3 mm afloop"; anders een vrije maat. Die afleiding is een gemak in de interface, geen betekenis in het bestand. ### Hoofdstukafbreking: geen sleutel maar gewone Markdown Het antwoord op mijn eigen open vraag, en beter dan wat ik voorstelde. §14.6 kent al de juiste vorm: een `---` vóór een `H1` is een pagina-einde dat *élke* lezer honoreert. Dus geen vierde privé-sleutel, maar een eenmalige bewerking van de body: "hoofdstukafbrekingen in dit document toepassen" zet `---`-regels neer. Zichtbaar, door de gebruiker terug te draaien, en het reist naar pandoc, GitHub en de printer van de ontvanger. ### Wat er verder bij hoort voordat dit mag landen - **Een eigendomsregister voor documentsleutels**, zoals het deckpad dat heeft (`kOwnedFrontMatterKeys`/`kRetiredFrontMatterKeys` in `front_matter_merge.dart`), inclusief terugtrekroute. Zonder dat is er geen pad om een sleutel ooit nog uit bestaande bestanden te krijgen — de uitgang moet net zo makkelijk zijn als de ingang. - **§14.7 herschrijven mét koerswijzigingsnotitie.** Die paragraaf stelt vandaag als bewuste keuze vast dat er niets naar het `.md` wordt geschreven en dat het vel niet meereist. Dat terugdraaien mag, maar niet stilzwijgend: er hoort een zichtbare "we hebben ons bedacht, en hierom" bij. Idem §14.1 en §14.5. - **De geprojecteerde `.md`-export moet de sleutels meenemen** (§14.4). Doet hij dat niet, dan drukt de ontvanger het alsnog op zíjn vel af — precies de storing die dit moest verhelpen. - **Round-trip-toets zoals `theme:` die heeft**: zetten en terug naar "mijn standaard" geeft de exacte oorspronkelijke bytes, inclusief het geval waarin het blok daarmee leeg wordt. - **De bediening langs gebruiksgemak.** De bewaker merkte terecht op dat een te makkelijke knop sleutels schrijft in bestanden die de gebruiker niet wilde wijzigen. ### Wat blijft staan Volgorde van gelden (afdwingen → document → instelling), opt-in en alleen op verzoek schrijven, byte-chirurgisch, geen herkenningsmarkering, en een onleesbare waarde valt terug op de instelling in plaats van te falen.
Author
Owner

Gemerged in #1525, volgens ontwerp v2.

Twee dingen uit het ontwerp zijn bewust niet meegebouwd en verdienen een eigen issue als ze gewenst zijn:

  • Hoofdstukafbrekingen als bewerking van de body (--- vóór elke H1), het alternatief dat de bewaker aandroeg voor een vierde privé-sleutel. De instelling documentChapterPageBreak blijft dus voorlopig app-breed en reist niet mee.
  • De geprojecteerde .md-export neemt de sleutels nog niet mee (§14.4). Zonder dat drukt een ontvanger het alsnog op zijn eigen vel af.

De .nl.md-vertalingen van FILE_FORMAT, USER_GUIDE en GLOSSARY lopen achter en horen via make translate-docs bijgetrokken te worden.

Gemerged in #1525, volgens ontwerp v2. Twee dingen uit het ontwerp zijn bewust **niet** meegebouwd en verdienen een eigen issue als ze gewenst zijn: - **Hoofdstukafbrekingen als bewerking van de body** (`---` vóór elke `H1`), het alternatief dat de bewaker aandroeg voor een vierde privé-sleutel. De instelling `documentChapterPageBreak` blijft dus voorlopig app-breed en reist niet mee. - **De geprojecteerde `.md`-export** neemt de sleutels nog niet mee (§14.4). Zonder dat drukt een ontvanger het alsnog op zijn eigen vel af. De `.nl.md`-vertalingen van FILE_FORMAT, USER_GUIDE en GLOSSARY lopen achter en horen via `make translate-docs` bijgetrokken te worden.
Sign in to join this conversation.
No milestone
No project
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#1511
No description provided.