Technischer Artikel

Deklaratives PDF-Layout in Delphi mit getaggter Ausgabe

Ein Absatz, der unten auf Seite 4 beginnt und oben auf Seite 5 endet, ist für die lesende Person ein einzelner Absatz. In einem getaggten PDF lebt er in zwei Content-Streams, und jede Seite nummeriert ihre Marked-Content-Sequenzen für sich, sodass der Strukturbaum ein einziges P-Element braucht, dessen /K-Array etwa auf MCID 7 auf Seite 4 und MCID 3 auf Seite 5 zeigt. Zeichnet man die Seiten mit Koordinatencode und settelt das Tagging hinterher an, zeigt der Tag-Baum in einem Accessibility-Checker typischerweise zwei Absätze, wo einer war, dazu einen Satz von Spaltentiteln, der in den Daten jeder fortgesetzten Tabelle wiederholt wird

Der Koordinatenansatz hat eine zweite Kostenart, die früher zuschlägt. Die erste Version eines Berichts funktioniert. Dann wächst eine Kundenadresse auf drei Zeilen, eine lokalisierte Überschrift bricht um, eine Tabelle gewinnt vierzig Zeilen, und jede y-Position unterhalb dieses Punkts ist falsch. Seitenumbruch-Prüfungen landen verstreut in der Geschäftslogik, und Code, der nur je nach x und y kannte, weiß nicht, wo ein Absatz beginnt, wenn die Barrierefreiheits-Anforderung zwei Jahre später auftaucht

Einen HotPDF-Layoutbaum in Delphi aufbauen

HotPDF beantwortet beide Probleme mit einem deklarativen Layoutbaum in der Unit HPDFLayoutDOM. Ein THPDFDOMDocument hält Abschnitte; jeder THPDFDOMSection hat eine Seitengröße, Ränder, einen optionalen Header und Footer und einen Body-Stapel, in den man Text, Überschriften, Abstandshalter, Listen, Bilder, Container und Tabellen legt. Nichts im Baum trägt eine y-Koordinate. THPDFDOMRenderer vermisst den Baum, entscheidet die Seitenumbrüche, zeichnet Header und Footer auf jeder Seite und schreibt, weil GenerateStructure standardmäßig True ist, den Strukturbaum gleich mit

Der Besitz im Baum ist strikt. Das Dokument besitzt seine Abschnitte, ein Abschnitt besitzt seinen Body, Header und Footer, und Stapel, Container und Tabellen besitzen ihre Kinder, daher übergibt Section.Body.Add(Table) die Tabelle endgültig. Eine Komponente, die an zwei Eltern hinge, würde unter unterschiedlichen Einschränkungen zweimal vermessen und beim Abbau zweimal freigegeben. Wiederkehrende Teile wie ein Unterschriftenblock kommen deshalb aus Clone, aus SetHeaderClone / SetFooterClone oder aus einer bei RegisterComponent registrierten Factory, womit jeder CreateComponent('signature')-Aufruf eine frische Instanz zurückgibt

Eigentumsbaum eines deklarativen HotPDF-Layoutdokuments, in dem Abschnitte, Kopf- und Fußzeilen und Tabellenzeilen jeweils genau einen Eigentümer haben
Jeder Knoten im Layoutbaum hat genau einen Besitzer, daher liefern Helfer frische Instanzen statt geteilter Referenzen zurück, und wiederkehrende Ausstattung kommt aus einer registrierten Factory als neue Komponente bei jedem Aufruf
uses
  SysUtils, HPDFDoc, HPDFLayoutDOM;

type
  TAssetRow = record                    // eigener Datentyp
    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 hoch, 36 pt Ränder als Vorgabe
    Section.MarginLeft := 56;
    Section.MarginRight := 56;
    Section.Style.FontName := 'Helvetica';
    Section.Style.FontSize := 10;
    Section.Style.LineHeight := 13;
    Section.Body.Style.Spacing := 6;    // Abstand zwischen Body-Kindern
    Section.Footer := THPDFDOMText.Create('Plant maintenance - internal');

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

    Table := THPDFDOMTable.Create('assets');  // RepeatHeaders ist standardmäßig True
    Table.AddColumn(3);                 // Gewichtungen, keine Breiten in Punkt
    Table.AddColumn(1);
    Table.AddColumn(1);
    Row := Table.AddRow(18, True);      // Kopfzeilen müssen zuerst kommen
    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);            // der Body besitzt die Tabelle ab hier
    Result := Doc;
  except
    Doc.Free;
    raise;
  end;
end;

Zwei Vorgaben in diesem Listing sind Stolperfallen. LineHeight löst sich zu 12 Punkten auf, sofern kein Style in der Kette ihn setzt, egal was FontSize sagt, also bekommt eine 18-pt-Überschrift ohne eigenes LineHeight 12-pt-Zeilen und überlappt die nächste. Und eine Tabellenzeile ist genau so hoch wie die Höhe, die an AddRow übergeben wird: Zelltext kommt auf eine Zeile heraus, also bemessen Sie die Zeilen für die Schrift, die Sie gewählt haben

Render öffnet und schließt das Dokument selbst

THPDFDOMRenderer.Render(Doc, Pdf) ruft BeginDoc am Ziel auf, rendert jeden Abschnitt und ruft EndDoc, bevor es zurückkehrt. Wickeln Sie es nicht in ein eigenes BeginDoc / EndDoc-Paar ein. Alles, was vor dem Dokumentstart gesetzt sein muss, kommt zuerst auf die THotPDF-Instanz: FileName, Title und, wenn die Ausgabe PDF/UA beanspruchen soll, PDFUACompliance. Bei eingeschalteter Strukturgenerierung schaltet Render außerdem EnableTaggedPDF ein und kopiert Doc.Language nach Pdf.Lang, falls man es leer gelassen hat

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;        // aktiviert auch die Prüfung des Figuren-Alt-Texts
    // Kein BeginDoc / EndDoc hier: Render öffnet und schließt das Dokument
    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;

Protokollieren Sie den Statistikdatensatz bei jedem Lauf, denn er zeigt Vorlagen-Regressionen, die nie eine Exception auslösen. Ein springender SplitCount nach einer Vorlagenänderung bedeutet meist, dass eine Komponente nun höher misst als der Platz, in den sie früher passte. Ein schleichend wachsender MaximumContinuationDepth zeigt auf eine Komponente, deren Split zu wenig Inhalt pro Seite weiterreicht. ArtifactCount umfasst Seitenköpfe und -füße, dekorative Rahmen wie den voreingestellten 0,5-pt-Rahmen der Tabelle und wiederholte Kopfzeilen; vergleichen Sie ihn also zwischen Läufen derselben Vorlage statt gegen ein handgerechnetes Ziel

Wie paginiert eine lange Tabelle, ohne sich auf jeder Seite selbst zu kopieren?

Der Renderer splittet nur, was über die Seitengrenze hinausragt. Die naive Art, einen Baum zu paginieren, besteht darin, alles zu klonen, was nicht passte, und die Kopie auf die nächste Seite zu tragen; bei einer Tabelle mit 10.000 Zeilen klont das die verbleibenden Zeilen einmal pro Seite und macht aus einem linearen Job einen quadratischen. HotPDF geht die Body-Kinder nach Index durch und klont niemals einen ganzen Abschnitt oder Body. Ein verschachtelter Stapel oder Container, der eine Seitengrenze kreuzt, bekommt nur seinen betroffenen Teilbaum geklont, und die beiden schwergewichtigen Blatttypen tragen einen Cursor statt einer Kopie

Ein fortgesetzter Absatz ist eine Referenz auf den Originaltext plus den Zeichenbereich, den er noch schuldet, und er nutzt die Zeilenumbrüche wieder, die bereits für diese Breite berechnet wurden. Eine fortgesetzte Tabelle ist eine Referenz auf die Originaltabelle plus die Scheibe von Zeilen, die noch zu platzieren sind. Ein Absatz mit 300 Zeilen kostet gleich viel, ob er einmal oder fünfmal umbricht

Balkendiagramm: quadratische Paginierungskosten durch Klonen ganzer Teilbäume gegenüber flachen linearen Kosten durch schmale Seitengrenz-Splits in HotPDF
Den ganzen unplatzierten Teilbaum auf jeder überlappenden Seite zu klonen macht aus zusätzlichen Zeilen quadratische Arbeit, während ein schmaler Schnitt langen Text einen Zeichenbereichs-Cursor und Tabellen einen Zeilenscheiben-Cursor tragen lässt

Die Platzierung selbst läuft über die öffentliche Routine THotPDF.PlaceLayoutElement. Sie vermisst das Element gegen die verbleibende Body-Höhe, zeichnet es ganz, wenn es passt, und fordert sonst ein Split, vermisst die platzierte Hälfte erneut, zeichnet sie und gibt den Rest als Overflow-Objekt zurück, das der Renderer auf eine frische Seite trägt. Measure darf niemals etwas zeichnen; es kann für eine Platzierung mehrfach laufen. Der DOM-Renderer setzt Seitenrahmenelemente, Abstände zwischen Kindern und Entscheidungen über neue Seiten oben auf diese Routine

Warum kann eine einzelne Kopfzeile den gesamten Render anhalten?

Wiederholte Tabellenköpfe tragen zwei Regeln, und beide existieren, damit ein Bericht keine Seiten ohne Daten erzeugt. Kopfzeilen müssen den ersten Lauf von Zeilen bilden: AddRow(Height, True) nach einer Body-Zeile löst EInvalidOpException mit „Table header rows must precede body rows“ aus. Und der erste Split einer Tabelle muss jede Kopfzeile plus mindestens eine Body-Zeile unterbringen. Eine Tabelle, die den Kopf am Fuß einer Seite stranden ließe, rückt stattdessen auf die nächste Seite

Die zweite Regel hat eine harte Kante. Passen die Kopfzeilen plus eine Body-Zeile nicht einmal auf eine leere Seite, gibt es keine Seite, auf der die Tabelle beginnen könnte, und Render wirft „Layout component ... cannot fit an empty body page“ mit dem Komponentenpfad, etwa Sections[0]/Body/Items[2]/assets. Das ist das Verhalten, das man haben will. Eine Layout-Engine, die weiter Seiten hinzufügt in der Hoffnung, die nächste wäre geräumiger, macht aus einem überdimensionierten Kopf eine festplattenfüllende Schleife

Benutzerdefinierte Komponenten bekommen denselben Schutz. Man leitet THPDFDOMComponent ab, implementiert Clone, Measure, Draw und Split, und der Renderer zählt, wie viele Fortsetzungen jedes Body-Kind erzeugt. Oberhalb von THPDFDOMRenderer.MaximumContinuationDepth (standardmäßig 100.000) stoppt das Rendern mit „exceeded the continuation depth limit“. Ein Split, der immer einen gleichwertigen Rest zurückgibt und daher keinen Fortschritt macht, scheitert mit einem Komponentenpfad, statt zu laufen, bis die Festplatte voll ist

Auf Fortsetzungsseiten werden die Kopfzeilen erneut gezeichnet, innerhalb einer /Artifact-Marked-Content-Sequenz, und der Strukturbaum behält das ursprüngliche TR genau einmal. Die Textextraktion fügt daher keine doppelte Kopfzeile zwischen Datenzeilen ein, und Assistenztechnik verkündet die Spaltentitel nicht erneut mitten in der Tabelle. Jede Kopfzelle ist als TH mit einem /Scope /Column-Attribut getaggt

Ein logischer Absatz, mehrere Seitenfragmente

Ein geteilter Absatz bleibt ein P-Strukturelement. Jedes sichtbare Fragment öffnet eine neue Marked-Content-Sequenz auf seiner eigenen Seite, und HotPDF hängt ein Marked-Content-Referenzwörterbuch, << /Type /MCR /Pg page /MCID n >>, an das /K-Array dieses Elements an und registriert die MCID im ParentTree-Eintrag der Seite mit Rückverweis auf dasselbe Element. Das ist die Anordnung, die ISO 32000-1 §14.7.4 für Inhaltselemente beschreibt, die sich über Seiten verteilen, und sie ist der Grund, warum eine Tag-Baum-Ansicht einen Absatz zeigt, wo die Seiten zwei Stücke zeigen

Semantische Identität ist der Grund, warum Fortsetzungskopien sich anders verhalten als eigene Klone. Ein Clone-Aufruf bedeutet „neuen logischen Inhalt“, und das Ergebnis bekommt beim Zeichnen ein neues Strukturelement. Die Kopien, die während der Paginierung entstehen, erben die Identität der Komponente, die sie fortsetzen, sodass ein über drei Seiten geteilter Stapel weiterhin ein Div liefert und eine über zwei Seiten geteilte Liste weiterhin ein L. Seitenköpfe und -füße nehmen einen anderen Weg: Sie werden auf jeder Seite als /Artifact << /Type /Pagination /Subtype /Header >> (oder /Footer) verpackt und betreten den Strukturbaum nie

HotPDF-Diagramm: ein getaggter Absatz bleibt ein einzelnes PDF-Strukturelement, während seine zwei Seitenfragmente separate Marked-Content-Identifikatoren tragen und eine neu gezeichnete Kopfzeile als Artefakt getaggt wird
Fragmente eines Absatzes teilen sich ein einziges Strukturelement über die Pg- und MCID-Paare, die in seinem K-Array gesammelt sind, und die auf Fortsetzungsseiten neu gezeichnete Kopfzeile fährt als Artefakt statt als Inhalt mit

Strukturregeln, die beim Rendern des Baums geprüft werden

Mit GenerateStructure an verweigert der Renderer Struktur, die eine PDF/UA-Validierung später zurückweisen würde. Die erste Überschrift muss H1 sein, und spätere Überschriften dürfen keine Ebene überspringen, sodass ein H3 direkt nach einem H1 „Semantic heading levels cannot skip an intermediate level“ wirft. LI braucht einen L-Elternknoten, Lbl und LBody brauchen ein LI, TR braucht eine Tabelle oder Zeilengruppe, und TH / TD brauchen ein TR. Wenn das Ziel PDFUACompliance gesetzt hat, wird auch ein Figure ohne Alternativtext zurückgewiesen. Jede Verletzung stoppt Render mit einer Exception

var
  List: THPDFDOMList;
  Bmp: TBitmap;                         // Vcl.Graphics
begin
  Section.Body.AddHeading('Findings', 2);     // H1 kam zuerst, H2 ist also legal

  List := THPDFDOMList.Create('Decimal');     // als L getaggt, 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 erzeugt LI, Lbl und LBody

  Bmp := TBitmap.Create;
  try
    Bmp.LoadFromFile('site-plan.bmp');
    // Das Bild kopiert die Grafik; leerer Alt-Text scheitert unter PDFUACompliance
    Section.Body.Add(THPDFDOMImage.Create(Bmp, 240, 160,
      'Site plan of plant 3 with the inspected pumps circled'));
  finally
    Bmp.Free;
  end;
end;

Die Prüfung während des Renderns ist der richtige Ort für diese Regeln. Das Timing ist der Grund. Ein Validator, der einen fehlenden Alternativtext meldet, nachdem die Datei geschrieben wurde, sagt einem, dass eine Charge von 10.000 Belegen neu erzeugt werden muss; eine Exception während Render nennt die Regel, die scheiterte, während der Datensatz, der sie erzeugte, noch im Gültigkeitsbereich liegt. Formale Konformitätsprüfung gehört weiterhin in die Pipeline, und weil die Objekte des Dokuments nach der Rückkehr von Render lesbar bleiben, kann sie sofort laufen. PDF/A-, PDF/X- und PDF/UA-Validierung behandelt diesen Schritt, und Strukturreihenfolge und Textextraktion zeigt, wie der Tag-Baum steuert, was Extraktionstools zurücklesen

Wann man besser von Hand zeichnet

Der Baum zeichnet auf dieselben THPDFPage-Objekte wie die direkte API. Weil Render das Dokument von BeginDoc bis EndDoc besitzt, gehört handplatzierte Grafik wie ein Unterschriftsbild in den Baum: Das Draw einer benutzerdefinierten Komponente erhält die Seite und ihre Grenzen und kann dort die gewöhnlichen Seitenmethoden aufrufen. Der Seitenabschluss bleibt bei AddPage und EndDoc, daher werden mit gesetztem ImmediateFlushLayout auf der THotPDF-Instanz fertige Seiten geschrieben, während das Rendern läuft, und der Renderer hält keine abgeschlossenen Seiten; der Speicher hängt dann an den offenen Fortsetzungen, den Schriftressourcen und dem Objektgraphen des Dokuments

Die DOM-Textkomponente bricht Zeilen nach einem geschätzten mittleren Vorschub von 0,55 × Schriftgröße pro Zeichen und gibt jeder Zeile das aufgelöste LineHeight. Das hält die Vermessung billig und auf jeder Maschine gleich, und für datengetriebene Berichte reicht es locker. Text mit breiten Glyphen, etwa Kapitälchen, fette Passagen oder CJK, kommt breiter heraus als geschätzt, also lassen Sie in diesen Spaltenbreiten Spielraum und testen Sie das Layout einmal mit dem längsten realen String. Gesetzte Seiten mit exakten Glyphenmetriken, mehreren Schriften in einer Zeile oder Blocksatz sind besser bei der direkten Text-API aufgehoben; Textausrichtung geht diesen Weg durch, und wenn nur die Tabellenpaginierung schmerzt, ist Tabellen in PDF erzeugen die kleinere Änderung

Der Layoutbaum, sein Renderer, das hier beschriebene Tagging und die direkte Zeichen-API liegen in einer Komponente für Delphi und C++Builder; Editionen und die vollständige Funktionsliste finden sich auf der HotPDF-Delphi-PDF-Komponentenseite