Article technique

Repli de police automatique pour CJK et emoji en Delphi

Un jeu de modèles de factures en Arial imprime « Invoice for » puis plus rien. L'appel de texte a renvoyé 1, le fichier validé, et l'extraction de texte est revenue écourtée de dix caractères : chaque caractère Han de 北京示例科技有限公司 avait disparu, parce qu'Arial n'en possède aucun. Le repli de police automatique dans PDF Library for Delphi est actif par défaut et puise ces caractères dans les polices installées, AddFontFallback définit votre propre ordre de recherche, et une politique de glyphes manquants avec rapport JSON traite ce qu'aucune police ne peut dessiner

La partie silencieuse est ce qui rend cela coûteux. Un PDF avec un blanc là où un nom de partie devrait être passe tous les contrôles structurels, s'ouvre dans tous les visionneurs, et se fait remarquer par le client plutôt que par votre suite de tests

Pourquoi un texte non pris en charge disparaît-il au lieu de déclencher une erreur ?

Le PDF n'a aucune notion d'une police qui refuserait un caractère, donc un glyphe manquant n'est pas une erreur au niveau du fichier. Une police simple associe des codes d'un octet à des noms de glyphes via un encodage ; une police composite associe des codes à des CIDs via une CMap, puis à des indices de glyphes. Demandez à une police quelque chose qu'elle ne contient pas et vous atterrissez sur l'indice de glyphe zéro, .notdef, que l'ISO 32000-1 §9.7.6.3 traite comme l'issue standard des caractères non définis. La plupart des polices dessinent .notdef comme rien du tout. D'autres dessinent une case vide

Dans les deux cas, le flux de contenu est bien formé et la page se rend. Rien dans la spécification ne demande à un producteur de vérifier la couverture avant d'écrire un opérateur de texte, donc un générateur qui saute la vérification produit un fichier conforme qui a silencieusement perdu du contenu. C'est pourquoi repli et rapport vont ensemble. Résoudre ce qui peut l'être est la moitié du travail ; vous dire le reste est l'autre moitié, et à notre avis la plus importante pour tout ce qui porte un nom ou un montant

Activer la chaîne de repli dans PDF Library for Delphi

Le repli n'entre en jeu que quand la police sélectionnée manque réellement d'un caractère de la chaîne, donc un texte purement latin garde son chemin normal et ne coûte rien de plus. Une nouvelle instance de TPDFlib a déjà le repli automatique activé, si bien que le code de dessin n'a besoin d'aucun appel supplémentaire :

var
  Lib: TPDFlib;
begin
  Lib := TPDFlib.Create;
  try
    // Le repli automatique est actif par défaut : emoji, kana, Hangul,
    // les Han et les symboles sont cherchés dans une table de candidats intégrée
    Lib.SetMissingGlyphPolicy(PDF_MISSING_GLYPH_REPORT);

    Lib.AddTrueTypeFont('Arial', 2);   // 2 = incorporer en sous-ensemble
    Lib.SetTextSize(11);
    Lib.DrawText(72, 720, 'Invoice for 北京示例科技有限公司');
    Lib.DrawText(72, 700, 'Delivery status: on time ✅');

    Lib.SaveToFile('invoice.pdf');
  finally
    Lib.Free;
  end;
end;

Avec le repli automatique actif, la bibliothèque choisit les candidats selon l'écriture de chaque caractère non résolu. La table est fixe et orientée Windows : les emoji et pictogrammes essaient Segoe UI Emoji, puis Segoe UI Symbol, puis Arial Unicode MS ; les kana essaient Yu Gothic en premier ; le hangul essaie Malgun Gothic en premier ; le bloc Han unifié essaie Microsoft YaHei, puis Microsoft JhengHei, Yu Gothic, Malgun Gothic et SimSun ; les symboles mathématiques et techniques vont à Segoe UI Symbol et Cambria Math. Tout le reste tombe sur une large liste qui commence par Nirmala UI et Segoe UI

Les polices que vous enregistrez avec AddFontFallback sont essayées avant cette table intégrée, dans l'ordre où vous les avez ajoutées. SetAutomaticFontFallback(0) éteint seulement la table intégrée : la chaîne explicite reste active, c'est le réglage à choisir quand vous voulez que la sortie utilise vos polices approuvées et rien d'autre. AddFontFallback ignore un nom déjà présent dans la liste et renvoie sa position à base 1, et ClearFontFallbacks, RemoveFontFallback et GetFontFallbackCount vous laissent reconstruire la chaîne entre deux documents

Le piège de l'unification Han : qui gagne les caractères partagés ?

Le chinois, le japonais et le coréen partagent la plupart des idéographes Han d'Unicode, mais chaque locale attend des formes de lettres différentes pour beaucoup d'entre eux. Le point de code de 直 ou 骨 est le même dans une adresse de Tokyo et une de Pékin ; la forme qu'un lecteur natif attend ne l'est pas. Une chaîne de repli ne répond qu'à « quelle police installée a un glyphe pour ce point de code », et toute police CJK en a un, donc la police qui vient en premier gagne tous les caractères partagés

La table automatique met Microsoft YaHei en premier pour les Han. C'est correct pour le chinois simplifié et faux pour le japonais. Une adresse japonaise sur cette facture sort avec des kana dessinés par Yu Gothic (les kana envoient la recherche vers la police japonaise en premier) et des kanji dessinés par YaHei avec des formes chinoises, le tout sur une seule ligne. Rien ne manque, le rapport reste vide, et un lecteur japonais voit immédiatement que quelque chose cloche

Notre recommandation est d'arrêter de compter sur l'ordre automatique pour les Han et de construire la chaîne explicite à partir de la locale du document. Vous la connaissez déjà en général, via la fiche client ou la langue du modèle :

procedure ConfigureFallback(Lib: TPDFlib; const Locale: string);
begin
  Lib.ClearFontFallbacks;
  if Locale = 'ja' then
  begin
    Lib.AddFontFallback('Yu Gothic');
    Lib.AddFontFallback('Meiryo');
  end
  else if (Locale = 'zh-TW') or (Locale = 'zh-HK') then
    Lib.AddFontFallback('Microsoft JhengHei')
  else if Locale = 'ko' then
    Lib.AddFontFallback('Malgun Gothic')
  else
    Lib.AddFontFallback('Microsoft YaHei');
  // Emoji, symboles et toute écriture non couverte ci-dessus passent
  // quand même par les candidats intégrés ; passez 0 ici pour l'interdire
  Lib.SetAutomaticFontFallback(1);
end;

Appelez-la une fois par document, avant le premier DrawText. L'ordre à l'intérieur de la liste explicite compte de la même façon : la première police qui couvre un caractère gagne, donc une police pan-Unicode comme Arial Unicode MS a sa place à la fin, si tant est qu'elle y soit. Mettez-la en premier et elle dessinera presque tout, et les polices spécifiques à une écriture que vous avez choisies avec soin ne seront jamais consultées

Le repli fonctionne sur des clusters entiers

PDF Library for Delphi décide du repli par cluster de graphèmes, si bien qu'un cluster est toujours dessiné par une seule police. Une syllabe devanagari, un emoji avec un modificateur de teint, une lettre de base avec des signes combinants : chacun forme une unité unique à l'écran, et les décisions de façonnage en son sein viennent des tables d'une police en particulier. La moitié d'un cluster en Arial et l'autre moitié en police de secours mettrait sur la page un glyphe techniquement présent et visiblement cassé, ce qui est sans doute pire qu'un blanc

La police sélectionnée façonne d'abord la chaîne. Seuls les clusters revenus en glyphe zéro partent chercher une autre police, et les clusters voisins qui se résolvent vers la même police sont dessinés ensemble comme un seul passage, si bien qu'un nom chinois de dix caractères devient un seul passage YaHei plutôt que dix changements de police séparés. L'ordre de droite à gauche est préservé lui aussi : un passage de repli à l'intérieur d'un texte arabe ou hébreu reste là où l'algorithme bidirectionnel l'a mis. La même mécanique de façonnage pilote l'écriture verticale pour le japonais et le chinois

PDF Library for Delphi : diagramme de la chaîne de repli : une série de clusters CJK sans la police primaire Arial est dessinée par Microsoft YaHei comme première police de repli couvrante, et les clusters non couverts suivent la politique de rapport ou d'abandon
Cette exécution de cluster passe de la police principale à la première police de repli couvrante, et seules les polices réellement utilisées sont incorporées. Les clusters qu'aucune police ne peut dessiner suivent la politique des glyphes manquants : signaler et continuer, ou abandonner avec l'erreur 521

Un glyphe manquant doit-il arrêter le document ?

Cela dépend de ce à quoi le document sert, et PDF Library for Delphi vous laisse choisir avec SetMissingGlyphPolicy. PDF_MISSING_GLYPH_REPORT est la valeur par défaut : l'opération de texte va au bout, les caractères qu'aucune police ne peut dessiner sont retirés de la sortie, et chacun est enregistré. PDF_MISSING_GLYPH_ABORT rejette toute l'opération de texte avant que quoi que ce soit soit écrit sur la page, DrawText renvoie 0, et le code d'erreur est 521 (PDFLIB_ERROR_MISSING_GLYPH)

Pour des rapports internes en lot, prenez la politique de rapport et journalisez les manques ; un rapport légèrement incomplet aujourd'hui vaut mieux qu'aucun rapport. Pour les contrats, factures, certificats et tout ce qui porte le nom d'une personne ou d'une société, prenez l'interruption. Un caractère abandonné dans le nom d'une partie est un défaut que vous voulez trouver dans votre propre chaîne, et comme l'interruption arrive avant l'écriture, aucune ligne à moitié dessinée ne subsiste sur la page

var
  Lib: TPDFlib;
  Err: Integer;
  Report: WideString;
begin
  Lib := TPDFlib.Create;
  try
    Lib.SetMissingGlyphPolicy(PDF_MISSING_GLYPH_ABORT);
    Lib.AddTrueTypeFont('Arial', 2);
    Lib.SetTextSize(11);

    if Lib.DrawText(72, 660, CustomerName) <> 1 then
    begin
      Err := Lib.LastErrorCode;   // la lire la remet aussi à 0
      if Err = PDFLIB_ERROR_MISSING_GLYPH then
      begin
        Report := Lib.GetMissingGlyphReportJSON;
        // {"valid":false,"policy":1,"eventCount":1,"events":[
        //   {"sequence":1,"documentIndex":0,"page":1,"utf16Index":3,
        //    "codePoint":983041,"unicode":"U+F0001",
        //    "fontName":...,"fontType":...,"operation":"DrawText"}]}
        EscalateToOperator(Report);
      end;
    end;
  finally
    Lib.Free;
  end;
end;

Notez la variable locale. LastErrorCode s'efface quand on le lit, donc un code qui vérifie Lib.LastErrorCode = 0 à un endroit puis journalise Lib.LastErrorCode ailleurs journalisera 0. Lisez-le une fois, gardez la valeur

Chaque événement du rapport porte la page, l'indice UTF-16 dans la chaîne, le point de code en décimal et sous forme U+XXXX, la police sélectionnée, son type et l'appel d'API qui a rencontré le problème. Avec cela, un ticket de support nomme le caractère exact au lieu de décrire un symptôme. Le drapeau valid ne vaut true que si aucun événement n'a été enregistré, ce qui en fait un garde pas cher dans un traitement par lots

La bibliothèque garde les 256 événements les plus récents et abandonne les plus anciens, si bien qu'un document plein de texte non rendable ne peut pas transformer le diagnostic en problème de mémoire. Les événements s'accumulent d'un document à l'autre sur la même instance de TPDFlib ; appelez ClearMissingGlyphReport avant chaque document si vous voulez un rapport par fichier, ou servez-vous du champ documentIndex pour les distinguer

Interrompre sur les lettres, tolérer la décoration

Une politique unique pour tout le document est parfois trop brutale. Une étiquette d'expédition peut porter un emoji décoratif à côté du nom du destinataire, et vous préférez perdre l'emoji plutôt que de rejeter l'étiquette. L'événement OnMissingGlyph se déclenche pour chaque caractère qu'aucune police de la chaîne n'a pu dessiner, reçoit la politique comme action par défaut, et peut la contourner point de code par point de code :

type
  TGlyphGate = class
    procedure MissingGlyph(Sender: TObject; CodePoint: Cardinal;
      UTF16Index, Page: Integer; const FontName, Operation: WideString;
      var Action: Integer);
  end;

procedure TGlyphGate.MissingGlyph(Sender: TObject; CodePoint: Cardinal;
  UTF16Index, Page: Integer; const FontName, Operation: WideString;
  var Action: Integer);
begin
  // Les pictogrammes et les dingbats sont de la décoration : les abandonner et les enregistrer
  if ((CodePoint >= $1F000) and (CodePoint <= $1FAFF)) or
     ((CodePoint >= $2600) and (CodePoint <= $27BF)) then
    Action := PDF_MISSING_GLYPH_REPORT
  else
    Action := PDF_MISSING_GLYPH_ABORT;   // lettres et chiffres ne doivent pas disparaître
end;

// Câblage
Gate := TGlyphGate.Create;
Lib.OnMissingGlyph := Gate.MissingGlyph;

L'événement s'exécute après que le repli a eu sa chance, donc il ne voit que les caractères réellement irrésolubles sur cette machine. Chacun d'eux atterrit quand même dans le rapport JSON, quelle que soit l'action choisie par le gestionnaire

Mesurer, incorporer et déployer

GetTextWidth passe par les mêmes décisions de repli cluster par cluster que DrawText. Cela paraît évident, et c'est pourtant exactement là que les couches de repli maison se trompent : elles rapiècent l'appel de dessin, laissent la mesure sur la police principale, et chaque total aligné à droite et chaque colonne de tableau se retrouve calculé à partir de largeurs qui ne correspondent pas à ce qui finit sur la page. Ici, une chaîne mesurée avant le dessin occupe la largeur à laquelle elle a été mesurée, passages en repli inclus, et c'est ce qui rend raisonnable de laisser le repli actif partout plutôt que seulement dans les modèles que vous avez audités à la main

Une conséquence sous la politique d'interruption : quand la mesure tombe sur un caractère irrésoluble, GetTextWidth renvoie 0 et positionne l'erreur 521. Un code de mise en page qui divise par une largeur ou s'en sert pour dimensionner une cellule devrait vérifier cela avant d'utiliser le nombre

Les polices de repli ne sont incorporées que si elles dessinent quelque chose. Une police de la chaîne qui n'a jamais résolu de cluster n'ajoute rien au fichier, et une police qui l'a fait est incorporée comme sous-ensemble des glyphes qu'elle a dessinés. Un document avec un caractère chinois parmi 5 000 caractères latins transporte un seul glyphe Han, pas une police CJK de plusieurs mégaoctets ; l'optimisation de la taille des fichiers et le sous-ensemblage de polices couvre la construction de ce sous-ensemble. C'est pourquoi une longue chaîne couvrant chaque locale que vous servez est peu coûteuse à configurer, et chaque PDF ne paie que pour ce qu'il a utilisé. Les fichiers produits ailleurs qui référencent des polices qu'ils n'ont jamais incorporées demandent une autre réparation, décrite dans l'incorporation de polices manquantes dans un PDF existant

La réserve de déploiement est facile à manquer. Le repli se résout par rapport aux polices installées sur la machine qui exécute votre code, et une station de développement avec une installation Office complète en a bien plus qu'une image serveur allégée ou un conteneur. Si Yu Gothic ou Microsoft YaHei n'y est pas, la chaîne n'a rien vers quoi se replier. Faites tourner un document avec un nom Han, un nom hangul et un emoji sur le serveur cible et lisez le rapport JSON : un tableau events vide là-bas vous en dit plus que n'importe quel test sur votre propre bureau. Livrez les polices dont vous dépendez, et vérifiez que leurs licences autorisent l'incorporation

La même chaîne de repli, la même politique de glyphes manquants et le même rapport sont exposés dans les éditions DLL et ActiveX, si bien que des appelants C#, C++ ou scripts les configurent avec les mêmes appels. La documentation de référence et les téléchargements sont sur la page produit PDF Library for Delphi