Ontwerp: paginaopmaak per document laten meereizen (front matter) #1511
Labels
No labels
accepted
bug
declined
docs
duplicate
enhancement
good first issue
in-progress
needs-info
privacy
security
triage
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
LibreKAT/Ocideck#1511
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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:
.mdheeft geen pagina's — dat is de winst van het formaat, niet een gebrek.Voorgestelde richting (ontwerp eerst, dan pas code):
.mddat je mailt raakt zijn sidecar kwijt, en opmaak die stil wegvalt is erger dan opmaak die niet meereist.ocideck_page_…), nietpage:/margins:— die botsen met handgeschreven Hugo/Jekyll-sleutels.theme:-sleutel (FILE_FORMAT.md §14.5): opt-in, byte-chirurgisch, alleen op verzoek geschreven, nooit automatisch. Zelfde volgorde-resolver: afdwingen → document → instellingen.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.
Ontwerpvoorstel: paginaopmaak per document
Uitgangspunt van de bewaker: maat en marges mogen app-breed blijven (een
.mdheeft 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
ocideck_page_sizedraagt exactPageSizeSpec.id(A4,A4L,B5,C6L).ocideck_page_marginsdraagt exactPageMargins.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
.mddat 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
effectiveDocumentStyleNamedat voor de stijl doet:Een document zonder deze sleutels gedraagt zich exact als vandaag.
Schrijfgedrag: dezelfde regels als
theme:.mdzonder front matter.marp: true; deze sleutels slepen nooitmarp:/paginate:mee.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.dartbewaart 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.
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:, geenocideck:.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). Eenocideck_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
Pandoc voert dit uit. Wie het
.mdnaar 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 doorPageMargins.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,3als bestandsinhoud. De bewaker wees op een echte val: die volgorde is boven,onder,links,rechts, terwijlcssMarginin 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: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 eenH1is 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
kOwnedFrontMatterKeys/kRetiredFrontMatterKeysinfront_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..mdwordt 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..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.theme:die heeft: zetten en terug naar "mijn standaard" geeft de exacte oorspronkelijke bytes, inclusief het geval waarin het blok daarmee leeg wordt.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.
navdraagt nu pagina, document én dia #1524Gemerged in #1525, volgens ontwerp v2.
Twee dingen uit het ontwerp zijn bewust niet meegebouwd en verdienen een eigen issue als ze gewenst zijn:
---vóór elkeH1), het alternatief dat de bewaker aandroeg voor een vierde privé-sleutel. De instellingdocumentChapterPageBreakblijft dus voorlopig app-breed en reist niet mee..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 viamake translate-docsbijgetrokken te worden.