Technisch artikel

Declaratieve PDF-lay-out in Delphi met getagde uitvoer

Een alinea die onderaan pagina 4 begint en bovenaan pagina 5 eindigt, is voor de lezer één alinea. In een getagde PDF leeft ze in twee content streams, en elke pagina nummert zijn marked-content-sequences op eigen houtje, dus de structuurboom heeft één P-element nodig waarvan de /K-array bijvoorbeeld naar MCID 7 op pagina 4 en MCID 3 op pagina 5 wijst. Teken de pagina's met coördinaatcode en plak het taggen er achteraf op, en de tag-boom in een accessibility checker toont typisch twee alinea's waar er één was, plus een set kolomtitels die in de data van elke voortgezette tabel wordt herhaald

De coördinaataanpak heeft nog een tweede prijs, en die komt eerder. De eerste versie van een rapport werkt. Dan groeit een klantadres naar drie regels, breekt een gelokaliseerde kop om, krijgt een tabel veertig rijen erbij, en klopt elke y-positie daaronder niet meer. Paginabreuk-controles belanden verspreid door de bedrijfslogica, en code die alleen maar x en y kende, heeft geen idee waar een alinea begint zodra de toegankelijkheidseis er twee jaar later aankomt

Een HotPDF-layoutboom bouwen in Delphi

HotPDF lost beide problemen op met een declaratieve layoutboom in de unit HPDFLayoutDOM. Een THPDFDOMDocument bevat secties; elke THPDFDOMSection heeft een paginaformaat, marges, een optionele header en footer en een Body-stack waar je tekst, koppen, spacers, lijsten, afbeeldingen, containers en tabellen aan toevoegt. Niets in de boom draagt een y-coördinaat. THPDFDOMRenderer meet de boom, bepaalt de paginabreuken, tekent header en footer op elke pagina en schrijft — omdat GenerateStructure standaard op True staat — onderweg de structuurboom weg

Het eigendom in de boom is strikt. Het document bezit zijn secties, een sectie bezit zijn body, header en footer, en stacks, containers en tabellen bezitten hun kinderen, dus Section.Body.Add(Table) draagt de tabel definitief over. Een component die aan twee ouders hangt, zou tweemaal worden gemeten onder verschillende beperkingen en tweemaal worden vrijgegeven bij de afbraak. Herhaalde onderdelen zoals een handtekeningblok komen daarom uit Clone, uit SetHeaderClone / SetFooterClone of uit een factory die bij RegisterComponent is geregistreerd, waarna elke CreateComponent('signature')-aanroep een verse instantie teruggeeft

Eigendomsboom van een declaratief HotPDF-layoutdocument waarin secties, kop- en voetteksten en tabelrijen elk exact één eigenaar hebben
Elk knooppunt in de layoutboom heeft precies één eigenaar, dus helpers geven verse instanties terug in plaats van gedeelde verwijzingen, en herhaald meubilair komt van een geregistreerde factory als een nieuwe component bij elke aanroep
uses
  SysUtils, HPDFDoc, HPDFLayoutDOM;

type
  TAssetRow = record                    // je eigen datatype
    Name, ServiceDate, Status: WideString;
  end;

function BuildMaintenanceReport(const Assets: array of TAssetRow): THPDFDOMDocument;
var
  Doc: THPDFDOMDocument;
  Section: THPDFDOMSection;
  Heading: THPDFDOMText;
  Table: THPDFDOMTable;
  Row: THPDFDOMTableRow;
  I: Integer;
begin
  Doc := THPDFDOMDocument.Create;       // GenerateStructure = True, Language = 'en-US'
  try
    Section := Doc.AddSection;          // A4 staand, standaard 36 pt marges
    Section.MarginLeft := 56;
    Section.MarginRight := 56;
    Section.Style.FontName := 'Helvetica';
    Section.Style.FontSize := 10;
    Section.Style.LineHeight := 13;
    Section.Body.Style.Spacing := 6;    // tussenruimte tussen body-kinderen
    Section.Footer := THPDFDOMText.Create('Plant maintenance - internal');

    Heading := Section.Body.AddHeading('Annual maintenance report', 1);
    Heading.Style.FontSize := 18;
    Heading.Style.LineHeight := 22;     // LineHeight volgt FontSize niet
    Section.Body.AddText('Every asset inspected during the reporting ' +
      'period is listed below, grouped by site.');

    Table := THPDFDOMTable.Create('assets');  // RepeatHeaders staat standaard op True
    Table.AddColumn(3);                 // gewichten, geen breedtes in punten
    Table.AddColumn(1);
    Table.AddColumn(1);
    Row := Table.AddRow(18, True);      // headerrijen moeten eerst komen
    Row[0].Text := 'Asset';
    Row[1].Text := 'Last service';
    Row[2].Text := 'Status';
    for I := 0 to High(Assets) do
    begin
      Row := Table.AddRow(16);
      Row[0].Text := Assets[I].Name;
      Row[1].Text := Assets[I].ServiceDate;
      Row[2].Text := Assets[I].Status;
    end;
    Section.Body.Add(Table);            // de body bezit de tabel vanaf hier
    Result := Doc;
  except
    Doc.Free;
    raise;
  end;
end;

Twee defaults in die listing vangen mensen. LineHeight komt op 12 punten uit tenzij een stijl in de keten hem zet, wat FontSize ook zegt, dus een kop van 18 pt zonder eigen LineHeight krijgt regels van 12 pt en overlapt de volgende. En een tabelrij is precies zo hoog als de hoogte die aan AddRow wordt doorgegeven: celtekst gaat op één regel naar buiten, dus dimensioneer rijen voor het font dat je koos

Render opent en sluit het document zelf

THPDFDOMRenderer.Render(Doc, Pdf) roept BeginDoc aan op het doel, rendert elke sectie en roept EndDoc aan voordat hij terugkeert. Wikkel het niet in een eigen BeginDoc / EndDoc-paar. Alles wat moet staan voordat het document begint, zet je eerst op de THotPDF-instantie: FileName, Title en, als de uitvoer PDF/UA mag claimen, PDFUACompliance. Met structuurgeneratie aan schakelt Render ook EnableTaggedPDF in en kopieert Doc.Language naar Pdf.Lang als je dat leeg liet

var
  Doc: THPDFDOMDocument;
  Pdf: THotPDF;
  Renderer: THPDFDOMRenderer;
  Stats: THPDFDOMRenderStatistics;
begin
  Doc := BuildMaintenanceReport(Assets);
  Pdf := THotPDF.Create(nil);
  Renderer := THPDFDOMRenderer.Create;
  try
    Pdf.FileName := 'maintenance-report.pdf';
    Pdf.Title := 'Annual maintenance report';
    Pdf.PDFUACompliance := True;        // zet ook de alt-tekstcontrole voor figuren aan
    // hier geen BeginDoc / EndDoc: Render opent en sluit het document
    Stats := Renderer.Render(Doc, Pdf);

    Writeln(Format('%d page(s), %d placement(s), %d split(s)',
      [Stats.PageCount, Stats.PlacementCount, Stats.SplitCount]));
    Writeln(Format('structure elements=%d marked content=%d artifacts=%d',
      [Stats.StructureElementCount, Stats.MarkedContentCount,
       Stats.ArtifactCount]));
    Writeln(Format('header draws=%d footer draws=%d deepest chain=%d',
      [Stats.HeaderDrawCount, Stats.FooterDrawCount,
       Stats.MaximumContinuationDepth]));
  finally
    Renderer.Free;
    Doc.Free;
    Pdf.Free;
  end;
end;

Log het statistiekenrecord bij elke run, want het laat sjabloonregressies zien die nooit een exception veroorzaken. Een SplitCount die na een sjabloonwijziging opspringt, betekent meestal dat een component nu hoger meet dan de ruimte waar hij vroeger in paste. Een langzaam oplopende MaximumContinuationDepth wijst op een component waarvan Split per pagina te weinig content verplaatst. ArtifactCount dekt paginaheaders en -footers, decoratieve randen zoals het standaard 0,5 pt-kader van de tabel en herhaalde headerrijen, dus vergelijk hem tussen runs van hetzelfde sjabloon in plaats van tegen handmatig berekende doelen

Hoe pagineert een lange tabel zonder zichzelf op elke pagina te kopiëren?

De renderer splitst alleen wat over de paginagrens heen ligt. De naïeve manier om een boom te pagineren is alles wat niet paste te klonen en de kopie naar de volgende pagina over te brengen; bij een tabel met 10.000 rijen kloont dat de resterende rijen eenmaal per pagina en verandert het lineaire werk in kwadratisch werk. HotPDF doorloopt de body-kinderen op index en kloont nooit een hele sectie of body. Een geneste stack of container die een paginagrens overschrijdt, krijgt alleen zijn betrokken subboom gekloond, en de twee zware bladtypen dragen een cursor in plaats van een kopie

Een voortgezette alinea is een verwijzing naar de oorspronkelijke tekst plus het tekenbereik dat ze nog verschuldigd is, en ze hergebruikt de regeleinden die voor die breedte al zijn berekend. Een voortgezette tabel is een verwijzing naar de oorspronkelijke tabel plus het rijbereik dat nog geplaatst moet worden. Een alinea van 300 regels kost evenveel of ze eenmaal of vijfmaal breekt

Staafdiagram dat kwadratische pagineringskosten uit het klonen van hele subbomen afzet tegen vlakke lineaire kosten uit nauwe paginagrensplitsingen in HotPDF
De hele ongeplaatste subboom klonen op elke overschrijdende pagina maakt van extra rijen kwadratisch werk, terwijl een smalle split lange tekst een cursor over een tekenbereik geeft en tabellen een cursor over een rijbereik

De plaatsing zelf verloopt via de publieke routine THotPDF.PlaceLayoutElement. Ze meet het element tegen de resterende bodyhoogte, tekent het in één keer als het past, en anders vraagt ze een Split, meet het geplaatste deel opnieuw, tekent dat en geeft de rest terug als overflow-object dat de renderer naar een frisse pagina meeneemt. Measure mag nooit iets tekenen; voor één plaatsing kan hij meerdere keren draaien. De DOM-renderer zet paginaonderdelen, tussenruimte tussen kinderen en nieuwe-paginabeslissingen bovenop die routine

Waarom kan één headerrij de hele render stoppen?

Herhaalde tabelheaders dragen twee regels, en beide bestaan om te voorkomen dat een rapport pagina's zonder data produceert. Headerrijen moeten de eerste aaneengesloten reeks rijen vormen: AddRow(Height, True) na een body-rij geeft EInvalidOpException met "Table header rows must precede body rows". En de eerste splitsing van een tabel moet elke headerrij plus ten minste één body-rij bevatten. Een tabel die de header onderaan een pagina zou achterlaten, gaat naar de volgende pagina

De tweede regel heeft een harde rand. Passen de headerrijen plus één body-rij zelfs op een lege pagina niet, dan is er geen pagina waar de tabel kan beginnen, en geeft Render "Layout component ... cannot fit an empty body page" met het componentpad, bijvoorbeeld Sections[0]/Body/Items[2]/assets. Dat is het gedrag dat je wilt hebben. Een layout-engine die maar blijft pagina's toevoegen in de hoop dat de volgende ruimer wordt, zou één te grote header veranderen in een lus die de schijf vult

Custom components krijgen dezelfde bescherming. Subclass THPDFDOMComponent, implementeer Clone, Measure, Draw en Split, en de renderer telt hoeveel voortzettingen elk body-kind produceert. Boven THPDFDOMRenderer.MaximumContinuationDepth (standaard 100.000) stopt de render met "exceeded the continuation depth limit". Een Split die telkens een equivalente staart teruggeeft en dus nooit voortgang boekt, faalt met een componentpad in plaats van door te draaien tot de schijf vol is

Op vervolgpagina's worden de headerrijen opnieuw getekend binnen een /Artifact-marked-content-sequence, en de structuurboom houdt de oorspronkelijke TR precies één keer bij. Tekstextractie voegt daarom geen dubbele headerrij tussen datarijen in, en assistieve technologie kondigt de kolomtitels niet opnieuw aan midden in de tabel. Elke headercel is getagd als TH met een /Scope /Column-attribuut

Eén logische alinea, meerdere paginafragmenten

Een gesplitste alinea blijft één P-structuurelement. Elk zichtbaar fragment opent een nieuwe marked-content-sequence op zijn eigen pagina, en HotPDF voegt een marked-content-reference-dictionary, << /Type /MCR /Pg page /MCID n >>, toe aan de /K-array van dat element en registreert de MCID in de ParentTree-entry van de pagina die terugwijst naar hetzelfde element. Dat is de opzet die ISO 32000-1 §14.7.4 beschrijft voor content items die over pagina's zijn verspreid, en het is wat een tag-boomweergave één alinea laat zien waar de pagina's twee stukken tonen

Semantische identiteit is de reden waarom voortzettingskopieën zich anders gedragen dan je eigen klonen. Clone aanroepen betekent "nieuwe logische inhoud", en het resultaat krijgt een nieuw structuurelement zodra het wordt getekend. De kopieën die tijdens de paginering ontstaan, erven de identiteit van het component dat ze voortzetten, dus een stack die over drie pagina's is gesplitst levert nog steeds één Div op, en een lijst die over twee pagina's is gesplitst nog steeds één L. Paginaheaders en -footers nemen een andere route: ze worden op elke pagina verpakt als /Artifact << /Type /Pagination /Subtype /Header >> (of /Footer) en komen nooit in de structuurboom

Diagram van HotPDF met één getagde alinea die als één PDF-structuurelement blijft, terwijl zijn twee paginafragmenten aparte marked-content-identificatoren dragen en een hertekende kop als artefact wordt getagd
Fragmenten van één alinea delen één structuurelement via de Pg- en MCID-paren verzameld in zijn K-array, en de kop die op vervolgpagina's opnieuw wordt getekend reist mee als artifact in plaats van als content

Structuurregels die worden gecontroleerd terwijl de boom rendert

Met GenerateStructure aan weigert de renderer structuur die PDF/UA-validatie later zou afkeuren. De eerste kop moet H1 zijn en latere koppen mogen geen niveau overslaan, dus een H3 direct na een H1 geeft "Semantic heading levels cannot skip an intermediate level". LI heeft een L-ouder nodig, Lbl en LBody een LI, TR een tabel of rijgroep, en TH / TD een TR. Als op het doel PDFUACompliance staat, wordt ook een Figure zonder alternatieve tekst geweigerd. Elke overtreding stopt Render met een exception

var
  List: THPDFDOMList;
  Bmp: TBitmap;                         // Vcl.Graphics
begin
  Section.Body.AddHeading('Findings', 2);     // H1 kwam eerst, dus H2 is legaal

  List := THPDFDOMList.Create('Decimal');     // getagd als L, ListNumbering /Decimal
  List.AddItem('1.', 'Replace the intake filter on pump P-14');
  List.AddItem('2.', 'Re-torque the flange bolts on line 3');
  Section.Body.Add(List);                     // AddItem bouwt LI, Lbl en LBody

  Bmp := TBitmap.Create;
  try
    Bmp.LoadFromFile('site-plan.bmp');
    // de afbeelding kopieert de graphic; een lege alt-tekst faalt onder PDFUACompliance
    Section.Body.Add(THPDFDOMImage.Create(Bmp, 240, 160,
      'Site plan of plant 3 with the inspected pumps circled'));
  finally
    Bmp.Free;
  end;
end;

Controleren tijdens de render is de juiste plaats voor deze regels. Timing is de reden. Een validator die een ontbrekende alternatieve tekst pas meldt nadat het bestand is weggeschreven, vertelt je dat een batch van 10.000 stukken opnieuw moet worden gegenereerd; een exception tijdens Render benoemt de regel die faalde terwijl het record die veroorzaakte nog in scope is. Formele conformiteitscontrole hoort nog steeds in de pijplijn thuis, en omdat de objecten van het document na het terugkeren van Render leesbaar blijven, kan die meteen daarna draaien. PDF/A-, PDF/X- en PDF/UA-validatie behandelt die stap, en structuurvolgorde en tekstextractie laat zien hoe de tag-boom bepaalt wat extractietools teruglezen

Wanneer je beter met de hand blijft tekenen

De boom tekent op dezelfde THPDFPage-objecten als de directe API. Omdat Render het document van BeginDoc tot EndDoc in bezit heeft, hoort handmatig gepositioneerd werk zoals een handtekeningafbeelding binnen de boom: de Draw van een custom component krijgt de pagina en zijn grenzen mee en kan daar de gewone paginamethoden aanroepen. Het sluiten van pagina's blijft bij AddPage en EndDoc, dus met ImmediateFlushLayout op de THotPDF-instantie worden voltooide pagina's weggeschreven terwijl de render vordert en houdt de renderer geen voltooide pagina's vast; het geheugengebruik hangt dan nog alleen van openstaande voortzettingen, fontresources en de objectgraaf van het document af

De DOM-tekstcomponent breekt regels op basis van een geschatte gemiddelde tekenbreedte van 0,55 × fontgrootte en geeft elke regel de opgeloste LineHeight. Dat houdt meting goedkoop en op elke machine gelijk, en voor datagedreven rapporten is het meer dan genoeg. Tekst met brede glyphs, zoals hoofdletters, vette passages of CJK, komt breder uit de schatting, dus laat speling in die kolombreedtes en test de lay-out één keer met de langste echte string. Gescripte pagina's met exacte glyphmetrics, gemengde fonts binnen één regel of uitgevulde alinea's zijn beter af met de directe tekst-API; tekstuitvulling loopt dat pad door, en als alleen tabelpaginering pijn doet, is tabellen genereren in PDF de kleinere ingreep

De layoutboom, zijn renderer, het hier beschreven taggen en de directe teken-API worden samen in één component voor Delphi en C++Builder geleverd; edities en de volledige functielijst staan op de HotPDF Delphi PDF-componentpagina