Article technique

Mise en page PDF déclarative dans Delphi avec sortie balisée

Un paragraphe qui commence en bas de la page 4 et se termine en haut de la page 5 reste un seul paragraphe pour le lecteur. Dans un PDF balisé, il vit dans deux flux de contenus, et chaque page numérote ses séquences de contenu marqué pour son propre compte, si bien que l'arbre de structure a besoin d'un unique élément P dont le tableau /K pointe, par exemple, vers le MCID 7 de la page 4 et le MCID 3 de la page 5. Dessinez vos pages avec du code de coordonnées et ajoutez le balisage après coup, et l'arbre de balises d'un vérificateur d'accessibilité affichera généralement deux paragraphes là où il n'y en avait qu'un, sans compter une série de titres de colonnes répétés dans les données de chaque tableau poursuivi

L'approche par coordonnées a un second coût, qui se manifeste plus tôt. La première version d'un rapport fonctionne. Puis une adresse client s'étale sur trois lignes, un titre localisé passe sur plusieurs lignes, un tableau gagne quarante lignes, et toute position y en aval devient fausse. Les vérifications de saut de page finissent éparpillées dans la logique métier, et un code qui n'a jamais connu que x et y ne sait pas où commence un paragraphe lorsque l'exigence d'accessibilité se présente deux ans plus tard

Construire un arbre de mise en page HotPDF en Delphi

HotPDF répond à ces deux problèmes avec un arbre de mise en page déclaratif hébergé dans l'unité HPDFLayoutDOM. Un THPDFDOMDocument contient des sections ; chaque THPDFDOMSection définit un format de page, des marges, un en-tête et un pied de page optionnels, et une pile Body dans laquelle vous ajoutez texte, titres, espacements, listes, images, conteneurs et tableaux. Rien dans l'arbre ne porte de coordonnée y. THPDFDOMRenderer mesure l'arbre, décide des sauts de page, dessine l'en-tête et le pied de chaque page et, comme GenerateStructure vaut True par défaut, écrit l'arbre de structure au fil du dessin

La propriété dans l'arbre est stricte. Le document possède ses sections, une section possède son corps, son en-tête et son pied de page, et les piles, conteneurs et tableaux possèdent leurs enfants ; Section.Body.Add(Table) confie donc le tableau définitivement. Un composant rattaché à deux parents serait mesuré deux fois sous des contraintes différentes et libéré deux fois au démontage. Les éléments répétés comme un bloc de signature proviennent donc de Clone, de SetHeaderClone / SetFooterClone, ou d'une fabrique enregistrée avec RegisterComponent, après quoi chaque appel à CreateComponent('signature') renvoie une instance fraîche

Arbre de possession d'un document de mise en page déclaratif HotPDF où sections, en-têtes, pieds et lignes de tableau ont chacun exactement un propriétaire
Chaque nœud de l'arbre de mise en page a exactement un propriétaire, si bien que les fonctions d'aide retournent des instances neuves au lieu de références partagées, et le mobilier répété provient d'une fabrique enregistrée comme un nouveau composant à chaque appel
uses
  SysUtils, HPDFDoc, HPDFLayoutDOM;

type
  TAssetRow = record                    // votre propre type de données
    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 portrait, marges de 36 pt par défaut
    Section.MarginLeft := 56;
    Section.MarginRight := 56;
    Section.Style.FontName := 'Helvetica';
    Section.Style.FontSize := 10;
    Section.Style.LineHeight := 13;
    Section.Body.Style.Spacing := 6;    // écart entre les enfants du corps
    Section.Footer := THPDFDOMText.Create('Plant maintenance - internal');

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

    Table := THPDFDOMTable.Create('assets');  // RepeatHeaders vaut True par défaut
    Table.AddColumn(3);                 // pondérations, pas des largeurs en points
    Table.AddColumn(1);
    Table.AddColumn(1);
    Row := Table.AddRow(18, True);      // les lignes d'en-tête doivent venir en premier
    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);            // le corps possède le tableau à partir d'ici
    Result := Doc;
  except
    Doc.Free;
    raise;
  end;
end;

Deux valeurs par défaut de ce listing piègent du monde. LineHeight vaut 12 points tant qu'aucun style de la chaîne ne le définit, quel que soit le FontSize ; un titre de 18 pt sans LineHeight propre se retrouve donc avec des lignes de 12 pt et chevauche le suivant. Et une ligne de tableau fait exactement la hauteur passée à AddRow : le texte d'une cellule tient sur une seule ligne, dimensionnez donc vos lignes pour la police choisie

Render ouvre et ferme le document lui-même

THPDFDOMRenderer.Render(Doc, Pdf) appelle BeginDoc sur la cible, rend chaque section, puis appelle EndDoc avant de revenir. Ne l'encadrez pas de votre propre paire BeginDoc / EndDoc. Tout ce qui doit être réglé avant le début du document se règle d'abord sur l'instance THotPDF : FileName, Title, et PDFUACompliance si la sortie doit revendiquer PDF/UA. Quand la génération de structure est active, Render active aussi EnableTaggedPDF et recopie Doc.Language dans Pdf.Lang si vous l'avez laissé vide

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;        // active aussi la vérification du texte alternatif des figures
    // Pas de BeginDoc / EndDoc ici : Render ouvre et ferme le 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;

Journalisez l'enregistrement de statistiques à chaque exécution, car il révèle des régressions de gabarit qui ne lèvent jamais d'exception. Un SplitCount qui bondit après un changement de gabarit signifie généralement qu'un composant se mesure désormais plus haut que l'espace qu'il occupait auparavant. Un MaximumContinuationDepth qui grimpe progressivement désigne un composant dont le Split déplace trop peu de contenu par page. ArtifactCount couvre les en-têtes et pieds de page, les bordures décoratives comme le cadre de 0,5 pt par défaut des tableaux et les lignes d'en-tête répétées ; comparez-le donc entre des exécutions du même gabarit plutôt qu'à une cible calculée à la main

Comment un long tableau se pagine-t-il sans se copier à chaque page ?

Le moteur de rendu ne scinde que ce qui chevauche la limite de page. La façon naïve de paginer un arbre consiste à cloner ce qui n'a pas tenu et à reporter la copie sur la page suivante ; pour un tableau de 10 000 lignes, cela clone les lignes restantes à chaque page et transforme un travail linéaire en travail quadratique. HotPDF parcourt les enfants du corps par index et ne clone jamais une section ou un corps entier. Une pile ou un conteneur imbriqué qui franchit une limite de page ne voit que son sous-arbre affecté cloné, et les deux types de feuilles lourdes portent un curseur plutôt qu'une copie

Un paragraphe poursuivi est une référence au texte d'origine accompagnée de la plage de caractères encore due, et il réutilise les sauts de ligne déjà calculés pour cette largeur. Un tableau poursuivi est une référence au tableau d'origine accompagnée de la tranche de lignes restant à placer. Un paragraphe de 300 lignes coûte la même chose qu'il se coupe une fois ou cinq fois

Histogramme contrastant le coût de pagination quadratique du clonage de sous-arbres entiers avec le coût linéaire plat des coupures étroites aux frontières de pages dans HotPDF
Cloner tout le sous-arbre non placé à chaque page à cheval transforme les lignes supplémentaires en travail quadratique, tandis qu'une scission étroite laisse le texte long porter un curseur de plage de caractères et les tables porter un curseur de tranche de lignes

Le placement lui-même passe par la méthode publique THotPDF.PlaceLayoutElement. Elle mesure l'élément par rapport à la hauteur de corps restante, le dessine en entier s'il tient, lui demande sinon de se Split, mesure à nouveau la moitié placée, la dessine, et renvoie le reste sous forme d'objet de débordement que le moteur de rendu transporte vers une page neuve. Measure ne doit jamais rien dessiner ; elle peut être appelée plusieurs fois pour un même placement. Le moteur du DOM ajoute par-dessus cette routine les éléments récurrents de page, l'espacement entre enfants et les décisions de nouvelle page

Pourquoi une seule ligne d'en-tête peut-elle arrêter tout le rendu ?

Les lignes d'en-tête répétées obéissent à deux règles, et toutes deux existent pour éviter qu'un rapport produise des pages sans données. Les lignes d'en-tête doivent former la première série de lignes : un AddRow(Height, True) après une ligne de corps lève une EInvalidOpException avec « Table header rows must precede body rows ». Et la première scission d'un tableau doit faire tenir toutes les lignes d'en-tête plus au moins une ligne de corps. Un tableau qui laisserait son en-tête abandonné au bas d'une page passe plutôt à la page suivante

La seconde règle a un bord dur. Si les lignes d'en-tête plus une ligne de corps ne tiennent même pas sur une page vide, il n'existe aucune page où le tableau puisse commencer, et Render lève « Layout component ... cannot fit an empty body page » avec le chemin du composant, par exemple Sections[0]/Body/Items[2]/assets. C'est le comportement qu'on veut. Un moteur de mise en page qui continuerait d'ajouter des pages en espérant que la prochaine serait plus spacieuse transformerait un en-tête trop grand en boucle qui remplit le disque

Les composants personnalisés bénéficient de la même protection. Dérivez THPDFDOMComponent, implémentez Clone, Measure, Draw et Split, et le moteur de rendu compte combien de continuations chaque enfant du corps produit. Au-delà de THPDFDOMRenderer.MaximumContinuationDepth (100 000 par défaut), le rendu s'arrête avec « exceeded the continuation depth limit ». Un Split qui renvoie indéfiniment une queue équivalente, donc ne progresse jamais, échoue avec un chemin de composant au lieu de tourner jusqu'à remplir le disque

Sur les pages de continuation, les lignes d'en-tête sont redessinées à l'intérieur d'une séquence de contenu marqué /Artifact, et l'arbre de structure ne conserve le TR d'origine qu'une seule fois. L'extraction de texte n'insère donc pas de ligne d'en-tête en double entre les lignes de données, et les technologies d'assistance n'annoncent pas une seconde fois les titres de colonnes au milieu du tableau. Chaque cellule d'en-tête est balisée TH avec un attribut /Scope /Column

Un paragraphe logique, plusieurs fragments de page

Un paragraphe scindé reste un unique élément de structure P. Chaque fragment visible ouvre sa propre séquence de contenu marqué sur sa page, et HotPDF ajoute un dictionnaire de référence de contenu marqué, << /Type /MCR /Pg page /MCID n >>, au tableau /K de cet élément et enregistre le MCID dans l'entrée ParentTree de la page, qui pointe en retour vers le même élément. C'est l'agencement que décrit la norme ISO 32000-1 §14.7.4 pour des éléments de contenu répartis sur plusieurs pages, et c'est ce qui permet à une vue de l'arbre de balises d'afficher un seul paragraphe là où les pages en montrent deux morceaux

L'identité sémantique explique pourquoi les copies de continuation se comportent différemment de vos propres clones. Appeler Clone signifie « nouveau contenu logique », et le résultat reçoit un nouvel élément de structure quand il est dessiné. Les copies créées pendant la pagination héritent de l'identité du composant qu'elles prolongent, si bien qu'une pile répartie sur trois pages produit toujours un seul Div, et une liste répartie sur deux un seul L. Les en-têtes et pieds de page empruntent une autre voie : ils sont enveloppés en /Artifact << /Type /Pagination /Subtype /Header >> (ou /Footer) sur chaque page et n'entrent jamais dans l'arbre de structure

Diagramme HotPDF d'un paragraphe balisé conservé comme unique élément de structure PDF tandis que ses deux fragments de page portent des identifiants de contenu marqué distincts et qu'un en-tête redessiné est balisé comme artifact
Les fragments d'un même paragraphe partagent un seul élément de structure via les paires Pg et MCID collectées dans son tableau K, et l'en-tête redessiné sur les pages de suite voyage en artefact plutôt qu'en contenu

Des règles de structure vérifiées pendant le rendu de l'arbre

Avec GenerateStructure actif, le moteur de rendu refuse toute structure qu'une validation PDF/UA rejetterait plus tard. Le premier titre doit être H1 et les titres suivants ne peuvent pas sauter de niveau, si bien qu'un H3 juste après un H1 lève « Semantic heading levels cannot skip an intermediate level ». LI exige un parent L, Lbl et LBody exigent un LI, TR exige un tableau ou un groupe de lignes, et TH / TD exigent un TR. Quand la cible a PDFUACompliance défini, une Figure sans texte alternatif est rejetée elle aussi. Chaque violation arrête Render par une exception

var
  List: THPDFDOMList;
  Bmp: TBitmap;                         // Vcl.Graphics
begin
  Section.Body.AddHeading('Findings', 2);     // H1 est déjà là, donc H2 est légal

  List := THPDFDOMList.Create('Decimal');     // balisé 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 construit LI, Lbl et LBody

  Bmp := TBitmap.Create;
  try
    Bmp.LoadFromFile('site-plan.bmp');
    // L'image copie le graphique ; un texte alt vide échoue sous PDFUACompliance
    Section.Body.Add(THPDFDOMImage.Create(Bmp, 240, 160,
      'Site plan of plant 3 with the inspected pumps circled'));
  finally
    Bmp.Free;
  end;
end;

Vérifier pendant le rendu est la bonne place pour ces règles. La raison, c'est le moment. Un validateur qui signale un texte alternatif manquant une fois le fichier écrit vous apprend qu'un lot de 10 000 relevés doit être régénéré ; une exception pendant Render nomme la règle en défaut alors que l'enregistrement qui l'a provoquée est encore dans la portée. La vérification formelle de conformité reste une étape du pipeline, et comme les objets du document restent lisibles après le retour de Render, elle peut tourner immédiatement. La validation PDF/A, PDF/X et PDF/UA couvre cette étape, et l'ordre de structure et l'extraction de texte montre comment l'arbre de balises pilote ce que les outils d'extraction lisent en retour

Quand continuer à dessiner à la main

L'arbre dessine sur les mêmes objets THPDFPage que l'API directe. Comme Render possède le document de BeginDoc à EndDoc, les visuels positionnés à la main, comme une image de signature, prennent place dans l'arbre : le Draw d'un composant personnalisé reçoit la page et ses limites et peut y appeler les méthodes ordinaires de la page. La fermeture des pages reste le fait d'AddPage et d'EndDoc ; avec ImmediateFlushLayout défini sur l'instance THotPDF, les pages terminées sont écrites au fil du rendu et le moteur ne retient aucune page achevée ; la mémoire dépend alors des continuations ouvertes, des ressources de polices et du graphe d'objets du document

Le composant de texte du DOM coupe les lignes à partir d'une avance moyenne estimée de 0,55 × la taille de police par caractère et donne à chaque ligne le LineHeight résolu. La mesure reste économique et identique sur toutes les machines, ce qui suffit largement aux rapports pilotés par les données. Un texte aux glyphes larges — tout en capitales, en gras ou en CJK — sort plus large que l'estimation ; laissez donc du jeu dans ces largeurs de colonnes et testez la mise en page une fois avec la plus longue chaîne réelle. Les pages typographiées avec des métriques de glyphes exactes, plusieurs polices dans une même ligne ou des paragraphes justifiés sont mieux servies par l'API de texte directe ; la justification de texte décrit cette voie, et si seule la pagination de tableaux vous fait souffrir, la génération de tableaux en PDF est le changement plus limité

L'arbre de mise en page, son moteur de rendu, le balisage décrit ici et l'API de dessin direct sont livrés dans un seul composant pour Delphi et C++Builder ; les éditions et la liste complète des fonctionnalités figurent sur la page du composant PDF Delphi HotPDF