Un importateur d'annotations FDF peut renvoyer le nombre d'entrées qu'il a analysées sans en ajouter une seule au document : chaque entrée comptée, chaque entrée perdue. TPDFlib.ImportAnnotationsFromFDFString de losLab PDF Library lit les clés dans n'importe quel ordre, analyse /Rect correctement et indépendamment de la locale, et renvoie le nombre d'annotations réellement ajoutées, tandis que l'exportateur correspondant écrit le vrai /Rect de l'annotation, si bien qu'un export, un import et un second export produisent un FDF identique octet pour octet. Le reste de cette note explique comment un offset de départ erroné produit un échec silencieux parfait, quels trois autres pièges s'y cachent, et comment vérifier un import vous-même au lieu de faire confiance à une valeur de retour
Le scénario est banal. Un relecteur annote un contrat, les commentaires voyagent dans un fichier FDF (Acrobat dit Export Comments), et votre service Delphi les fusionne dans une copie propre par un appel d'import FDF. L'appel renvoie 7, le journal dit « 7 commentaires importés », le travail passe au vert, et le PDF de sortie n'a aucun commentaire. Rien n'a levé, rien n'a prévenu, et le nombre avait l'air plausible car c'était le vrai compte d'entrées du fichier. C'est la pire forme qu'un bug puisse prendre : une fonction dont le seul signal de succès est un compteur calculé indépendamment du travail qu'il prétend rapporter
Pourquoi un import FDF peut annoncer succès sans rien ajouter ?
Parce qu'un lecteur de noms peut commencer au mauvais endroit, et qu'un compteur peut vivre hors du code qui fait le travail. Un chercheur de clé qui renvoie la position immédiatement après /Subtype atterrit sur le blanc avant la valeur. Un ReadName qui démarre à cet espace et s'arrête au premier caractère blanc s'arrête avant d'avoir rien lu, donc chaque subtype revient vide. Un assistant tel que AddAnnotationToPage qui refuse de construire une annotation sans subtype fait le bon choix défensif isolément, mais si c'est une procedure sans valeur de retour et que le Inc(Result) de l'appelant se trouve en dehors, les deux gardes ensemble convertissent « rien n'a marché » en « tout a marché ». Le bon lecteur de noms saute le blanc, exige le / initial d'un objet name PDF, et s'arrête à tout délimiteur, y compris [, ( et ), donc /Subtype/Text et /Subtype /Text donnent tous les deux Text ; c'est ainsi que losLab PDF Library lit les noms
La valeur de retour mérite aussi un soin au-delà. Un importateur qui incrémente pour chaque dictionnaire bien formé du tableau /Annots sur-compte quand une entrée a un /Page en base 0 hors plage ou un /Subtype manquant, deux cas qui sont sautés. Dans losLab PDF Library, ImportAnnotationsFromFDFString et ImportAnnotationsFromFDF renvoient le nombre d'annotations réellement ajoutées, comme l'import XFDF : l'assistant FDF AddAnnotationToPage renvoie un Boolean et le compteur ne bouge qu'en cas de succès. Mesurer le document reste le test le plus fort, car il tient quel que soit le code qui a produit le nombre, donc le croquis ci-dessous compare AnnotationCount sur chaque page avant et après l'import
function TotalAnnotations(Lib: TPDFlib): Integer;
var
Page, Saved: Integer;
begin
Result := 0;
Saved := Lib.SelectedPage;
for Page := 1 to Lib.PageCount do
if Lib.SelectPage(Page) = 1 then
Inc(Result, Lib.AnnotationCount); // par page sélectionnée, widgets compris
Lib.SelectPage(Saved);
end;
var
Lib: TPDFlib;
Before, Reported, Added: Integer;
begin
Lib := TPDFlib.Create;
try
Lib.LoadFromFile('contract.pdf', '');
Before := TotalAnnotations(Lib);
Reported := Lib.ImportAnnotationsFromFDF('review-comments.fdf');
Added := TotalAnnotations(Lib) - Before;
if Added <> Reported then // égal depuis la v3.539.40
Writeln(Format('Importer reported %d, %d landed on a page', [Reported, Added]));
Lib.SaveToFile('contract-reviewed.pdf');
finally
Lib.Free;
end;
end;
Trois autres pièges derrière le premier
Réparer le subtype seul expose trois pièges de plus dans le même genre d'analyseur, chacun invisible tant qu'aucune annotation n'atteint une page. D'abord, un ReadNumber qui reçoit sa position en paramètre valeur relit le même endroit quatre fois quand on l'appelle pour les quatre nombres du /Rect de suite, et s'il ne saute pas le [ ouvrant, en pratique il ne lit rien du tout. Ensuite, un FindKey qui partage un curseur avançant entre toutes les recherches dépend de l'ordre des clés. Un exportateur peut écrire /Subtype, /Rect, /Page, /Contents, /T, /Subj pendant que l'importateur cherche dans l'ordre /Subtype, /Contents, /T, /Subj, /Page, /Rect ; une fois le curseur passé /Contents, la recherche de /Page et /Rect court au-delà de l'entrée courante et ne trouve rien ou prend les clés de l'annotation suivante, si bien que l'importateur ne peut même pas lire la sortie de son propre exportateur. Troisièmement, les nombres analysés par une routine qui suit le séparateur décimal du système, telle que PLStrToFloat, cassent sur les machines à locale virgule. L'ISO 32000-1 §12.7.7 définit le FDF comme syntaxe d'objets PDF, et les clés de dictionnaire en PDF sont sans ordre (§7.3.7), donc tout analyseur FDF qui suppose un ordre de clés est faux par construction, quel que soit l'outil qui a produit le fichier
losLab PDF Library borne d'abord chaque entrée. FindDictEnd marche depuis le << ouvrant jusqu'à son >> apparié, en suivant les dictionnaires imbriqués et en sautant les corps de chaînes littérales avec leurs échappements par antislash, donc un >> dans un commentaire tel que (see section >> 4) ne peut pas terminer l'entrée trop tôt. Chaque recherche de clé démarre alors au début de l'entrée et est limitée à sa fin, ce qui rend l'ordre des clés sans importance et empêche une annotation d'emprunter le /Page d'une autre. La correspondance de clé accepte aussi un délimiteur directement après le nom, car /Contents(Hi) est aussi valide que /Contents (Hi), tandis que la règle de frontière de mot empêche /Subj de prendre le début de /Subtype et /T de prendre /Type. ReadNumber reçoit sa position en paramètre var, saute le blanc et le [, et analyse avec PLTryStrToFloatInvariant, qui échoue doucement sur un token malformé au lieu de lever. Si l'un des quatre nombres du rectangle échoue, les quatre retombent à zéro plutôt que de produire un rectangle à moitié lu
Pourquoi des allers-retours FDF peuvent-ils décaler chaque annotation de sa propre hauteur ?
Parce qu'il est facile d'écrire un rectangle dans le mauvais modèle de coordonnées. Le /Rect d'une annotation est [llx lly urx ury] dans l'espace utilisateur par défaut (ISO 32000-1 §12.5.2, rectangles définis en §7.9.5), et le FDF transporte le même tableau. GetAnnotRectEx, lui, rapporte Left, Top, Width et Height dans les coordonnées de dessin de la bibliothèque, l'espace que contrôle SetOrigin. Un exportateur qui sérialise cela en [L T L+W T+H] remet à l'importateur quatre valeurs qui, réécrites verbatim en rectangle PDF, posent le bord supérieur là où appartient le coin inférieur gauche, si bien que chaque aller-retour monte l'annotation de sa propre hauteur. L'exportateur de losLab PDF Library copie les nombres /Rect propres à l'annotation, trois décimales, séparateur point, sans exposant, et ne retombe sur le rectangle calculé que si le tableau stocké est absent ou pas quatre nombres
Un test d'aller-retour digne d'être copié affirme sur le document et sur un second export, pas sur la valeur de retour de l'importateur. Notez le compte attendu de 2 : AddNoteAnnotation crée une annotation Text plus sa Popup, et les deux voyagent. Le test fait aussi tourner l'export et l'import sous un séparateur décimal virgule, et c'est là que vit l'autre moitié de cette histoire
var
Source, Target: TPDFlib;
FDF: AnsiString;
OldSep: Char;
begin
Source := TPDFlib.Create;
Target := TPDFlib.Create;
try
Source.NewPages(1); // deux pages désormais
Source.SelectPage(2);
Source.AddNoteAnnotation(50.5, 60.25, 0, 80, 80, 120, 60,
'Reviewer', 'Check this', 0.25, 0.5, 0.75, 0);
Target.NewPages(1);
OldSep := FormatSettings.DecimalSeparator;
FormatSettings.DecimalSeparator := ','; // simule un bureau allemand ou français
try
FDF := Source.ExportAnnotationsToFDFString; // écrit toujours /Rect [50.5 ...
Target.ImportAnnotationsFromFDFString(FDF);
finally
FormatSettings.DecimalSeparator := OldSep;
end;
Target.SelectPage(2);
Assert(Target.AnnotationCount = 2); // la note et sa popup
Assert(Target.GetAnnotType(1) = 'Text');
Assert(Target.ExportAnnotationsToFDFString = Source.ExportAnnotationsToFDFString);
finally
Target.Free;
Source.Free;
end;
end;
Le chemin FDF est construit autour du dictionnaire central de l'annotation. L'importateur reconstruit chaque entrée avec /Type, /Subtype, /Rect, /Contents, /T et /Subj, et l'exportateur laisse les annotations Widget aux méthodes de données de formulaire, où appartiennent les champs. Avant de compter sur le FDF pour les couleurs, drapeaux, style de bordure, liens de popup ou flux d'apparence, consultez la carte plus large de quelles données voyagent par quelle méthode dans la vue d'ensemble de l'échange de données de formulaire FDF, XFDF et XFA, et si vous devez inspecter ce qui est réellement arrivé, les lecteurs par index tels que GetAnnotType, GetAnnotTitle et GetAnnotContentsEx sont couverts dans l'introspection des signets, annotations et actions
Comment lire des fichiers FDF et XFDF à décimales virgule ?
Pour le FDF la réponse est sans ambiguïté : une virgule n'est pas un délimiteur dans la syntaxe PDF, donc un token de nombre qui contient exactement une virgule et aucun point ne peut être qu'un décimal écrit sur une machine à locale virgule. De tels fichiers existent, par exemple /Rect [10,500 20,250 40,750 60,125] d'un exportateur qui a formaté les nombres avec la locale du système, et ReadNumber transforme cette virgule unique en point avant l'analyse. Un token à deux virgules, ou avec virgule et point, est rejeté plutôt que deviné. Le lecteur ne consomme pas la notation exponentielle non plus, ce qui colle à l'ISO 32000-1 §7.3.3 : les nombres PDF ne l'utilisent jamais
Le XFDF est plus difficile, car dans les attributs XML la virgule est le séparateur. Le XFDF standard (ISO 19444-1) écrit rect="50.5,80.25,70.75,100.125" et dashes="4,2", tandis qu'un writer dépendant de la locale sur un système à virgule produit rect="50,500 80,250 70,750 100,125" et opacity="0,600". losLab PDF Library lit et écrit les nombres XFDF de façon invariante dans les deux sens, et reconnaît la forme historique via XFDFNormalizeLegacyDecimals seulement quand l'attribut se découpe sur les blancs en exactement le nombre attendu de tokens (quatre pour rect, un pour opacity et width) et que chaque token a la forme chiffres-virgule-chiffres. Un rect standard ne correspond jamais : c'est soit un token à trois virgules, soit des tokens qui finissent par une virgule. dashes est délibérément laissé de côté, car 4,2 peut être deux longueurs de tiret ou un historique 4.2, et aucune règle ne peut les distinguer
const
// Clés dans un autre ordre que l'exporteur, plus décimales à virgule d'un vieil export
LegacyFDF: AnsiString = '%FDF-1.2'#10'1 0 obj'#10'<< /FDF << /Annots ['#10 +
'<< /Rect [10,500 20,250 40,750 60,125] /Page 0 /Contents (First) ' +
'/Subtype /Text /T (Alpha) /Type /Annot >>'#10 +
'] >> >>'#10'endobj'#10'trailer'#10'<< /Root 1 0 R >>'#10'%%EOF'#10;
var
Lib: TPDFlib;
begin
Lib := TPDFlib.Create; // un document neuf a une page
try
Lib.ImportAnnotationsFromFDFString(LegacyFDF);
Assert(Lib.AnnotationCount = 1);
Assert(Lib.GetAnnotTitle(1) = 'Alpha');
// Réexporté en XFDF à décimales point : rect="10.500 20.250 40.750 60.125"
Writeln(Lib.ExportAnnotationsToXFDFString);
finally
Lib.Free;
end;
end;
Que doit réellement affirmer un test d'import d'annotations ?
Un test d'import utile affirme sur l'état du document cible, jamais seulement sur ce que l'importateur dit de lui-même ; dans la panne du zéro silencieux, la valeur de retour est justement le seul nombre qui reste intact. Trois assertions attrapent chaque piège décrit ici : le compte d'annotations sur la page attendue, un champ relu via GetAnnotType ou GetAnnotContentsEx, et un second export comparé octet pour octet au premier. La même discipline vaut pour toute API qui réécrit la structure d'un document en masse, y compris la consolidation de champs décrite dans la fusion des champs de formulaire dupliqués : contrôlez l'arbre résultant, pas un total renvoyé. Les méthodes d'annotations FDF et XFDF, avec leurs variantes fichier et chaîne, livrent dans la losLab PDF Library for Delphi et C++Builder