Article technique

Exporter un PDF en Markdown et DOCX depuis Delphi

Un demi-point décide de tout. Dans un rapport avec un corps de texte à 10 points, un titre de section composé en gras à 11 points se convertit en Markdown comme un paragraphe ordinaire, tandis qu'une légende de couverture à 12 points, en graisse normale, revient en ### Quarterly figures. Cela paraît à l'envers jusqu'à ce qu'on se rappelle ce qu'une page PDF stocke réellement : des glyphes à des coordonnées, un nom de police et une taille. Rien sur la page ne dit "titre". Chaque titre qu'émet un convertisseur est une conjecture bâtie sur ces trois faits, et la conjecture a des seuils

Pourquoi une page PDF n'a pas de paragraphes à exporter

Une page PDF contient des opérateurs d'affichage de texte, pas des paragraphes. Chaque opérateur place une suite de glyphes à une position, dans l'ordre où l'application productrice est arrivée à les émettre, et ISO 32000-1 n'impose au producteur aucune obligation de dire que deux suites appartiennent à la même phrase, et encore moins au même élément de liste ou à la même cellule de tableau. Le format décrit une page imprimée exactement, et il y parvient en jetant la structure qui a produit la page

Chaque convertisseur doit donc rebâtir ce que le générateur a jeté. Les lignes viennent des lignes de base partagées et de l'espacement vertical. Les fins de paragraphe viennent des changements d'espacement et d'indentation. Une liste est une suite de blocs qui commencent par une puce ou un motif de numéro. Un tableau est une grille de blocs de texte dont les bords s'alignent en travers des lignes et des colonnes. Sur les documents qui suivent les habitudes typographiques ordinaires, cela marche bien ; sur une brochure composée pour l'effet visuel, cela a très peu à quoi se raccrocher

Diagramme PDF Library for Delphi du pipeline d'inférence qui transforme les suites de glyphes PDF brutes en lignes groupées, paragraphes, titres, listes et tableaux exportés en Markdown ou DOCX
Chaque titre, liste et tableau de l'export est inféré de l'espacement, des polices et des bords alignés parce que le format PDF lui-même n'en enregistre aucun

Les PDF balisés sont la grande exception. Quand un document porte un arbre de structure, les rôles de paragraphe, de titre, de liste et de tableau sont enregistrés par le producteur au lieu d'être devinés ensuite, et voilà pourquoi le travail décrit dans la structure d'accessibilité des PDF balisés paie aussi en qualité de conversion. Si vous maîtrisez le producteur, baliser la sortie est la chose la moins chère que vous puissiez faire pour qui devra la convertir plus tard

D'où viennent les niveaux de titres

PDF Library for Delphi décide des niveaux de titres de deux façons, selon l'entrée. Sur une page balisée, un bloc dont le rôle de structure est H1 à H6 garde ce niveau, et H ou Title devient niveau 1. Sur une page non balisée, l'export retombe sur la taille de police relativement au corps de texte de la page, et il ne considère que les paragraphes d'une seule ligne de 200 caractères au plus

La règle de taille demande à la fois un ratio et un écart absolu, mesurés contre la taille dominante du corps :

Sortie MarkdownPlus grand texte de la ligneAvec un corps à 10 pt
#au moins 1,6 fois la taille du corps et au moins 4 pt de plus16 pt et plus
##au moins 1,35 fois et au moins 2,5 pt de plus13,5 pt et plus
###au moins 1,15 fois et au moins 1,25 pt de plus11,5 pt et plus

Cela explique l'exemple d'ouverture. Un titre en gras à 11 points sur du texte à 10 points manque le troisième palier d'un demi-point, et la graisse ne joue aucun rôle dans le niveau. La légende de couverture à 12 points le franchit. L'écart absolu existe pour les petites tailles de corps : sur du texte de note à 6 points, un ratio seul promouvrait une ligne à 7 points en titre, et l'exigence supplémentaire de 1,25 pt empêche cela

Nous pensons que c'est le bon arbitrage. Le gras est bien trop courant à l'intérieur du corps de texte (phrases d'amorce, termes définis, totaux dans une ligne de synthèse) pour être un signal de titre fiable à lui seul, et un convertisseur qui promeut chaque ligne en gras produit un Markdown avec des douzaines de sections fantômes. Manquer quelques titres en gras uniquement coûte moins cher. Si vos documents s'appuient sur des titres en gras à la taille du corps, la correction fiable est en amont : balisez-les, ou montez la taille du titre d'un point et demi

Le gras et l'italique dans la sortie se lisent depuis le nom de police. Une suite dont le nom de police contient Bold, Black ou Demi devient **bold** ; Italic ou Oblique devient *italic*. Les producteurs qui sous-ensemblent les polices sous des noms opaques tels que F3, ou qui simulent le gras en vectorisant des glyphes normaux, ne donnent rien à lire à l'export, et ce texte arrive sans style

Export Markdown pour les pipelines de récupération

Le chemin Markdown est celui vers lequel se tourner quand la destination est un pipeline de texte : un site de documentation, un index de recherche, un corpus découpé pour un assistant. ExportPageMarkdown renvoie une page sous forme de WideString, ExportDocumentMarkdown renvoie une plage de pages, et SaveMarkdownToFile et SaveMarkdownToStream écrivent le même texte en UTF-8 sans marque d'ordre d'octets. L'absence de BOM est délibérée ; un certain nombre de générateurs de sites statiques et d'outils de diff le traitent comme du contenu

Diagramme PDF Library for Delphi de l'export Markdown où le masque d'options sélectionne les marqueurs de page, la détection de titres et la préservation des styles avant que toute la plage de pages ne soit bâtie et écrite une fois en UTF-8
Les options se combinent en masque de bits et le rédacteur émet de l'UTF-8 sans BOM, tandis que les marqueurs de page laissent à chaque fragment récupéré un numéro de page citable

Les options sont un masque de bits : PDF_MARKDOWN_INCLUDE_PAGE_MARKERS (1), PDF_MARKDOWN_DETECT_HEADINGS (2) et PDF_MARKDOWN_PRESERVE_STYLES (4), avec PDF_MARKDOWN_DEFAULT qui combine les trois. Un second réglage, à l'échelle du document, contrôle l'analyse elle-même : SetStructuredTextOptions prend les drapeaux PDF_STRUCTURED_*, et son défaut détecte les colonnes, détecte les en-têtes et pieds courants, et rassemble les tableaux qui continuent après un saut de page

uses
  SysUtils, PDFlibrary;

var
  Pdf: TPDFlib;
  Exported: Integer;
begin
  Pdf := TPDFlib.Create;
  try
    if Pdf.LoadFromFile('handbook.pdf', '') = 0 then
      raise Exception.Create('Cannot open handbook.pdf');

    // La détection des en-têtes et pieds courants est active par défaut ;
    // ajouter EXCLUDE_FURNITURE les retire aussi de la sortie
    Pdf.SetStructuredTextOptions(PDF_STRUCTURED_ADVANCED_DEFAULT or
      PDF_STRUCTURED_EXCLUDE_FURNITURE);

    // Marqueurs de page et titres, mais pas d'emphase ** et *
    Exported := Pdf.SaveMarkdownToFile('1-40',
      PDF_MARKDOWN_INCLUDE_PAGE_MARKERS or PDF_MARKDOWN_DETECT_HEADINGS,
      'handbook.md');
    if Exported = 0 then
      raise Exception.CreateFmt('Markdown export failed, error %d',
        [Pdf.LastErrorCode]);

    // JSON avec une entrée par page : readingSource vaut tagged, mixed,
    // geometric ou geometric-columns
    Writeln(Pdf.GetLastStructuredTextDiagnostics);
  finally
    Pdf.Free;
  end;
end;

Pour un corpus de récupération nous abandonnons PDF_MARKDOWN_PRESERVE_STYLES. L'emphase est appliquée suite par suite, si bien qu'une phrase en gras composée de plusieurs suites sort en **Net** **revenue**, ce qui se lit très bien à l'écran et ajoute du bruit à chaque embedding. Les marqueurs de page sont le cas inverse : gardez-les. Chaque marqueur est un commentaire HTML, <!-- page: 12 -->, invisible quand le Markdown est rendu et trivial à analyser quand vous découpez des fragments, si bien qu'un passage récupéré peut citer la page d'où il vient. Quand un tableau se prolonge depuis la page précédente, le marqueur de la nouvelle page est omis pour que la table à barres reste d'un seul tenant

Deux comportements piègent ceux qui exportent page par page dans une boucle. D'abord, les en-têtes courants sont reconnus par répétition : un paragraphe dans les 12 pour cent du haut ou du bas de la page compte comme mobilier quand un texte correspondant se trouve dans la même bande sur une autre page du même export, avec les chiffres normalisés pour que "Page 3 of 40" corresponde à "Page 4 of 40". Un appel mono-page n'a pas d'autre page à laquelle se comparer, si bien qu'un en-tête courant non balisé reste dans le texte. Ensuite, les images dans le Markdown sont intégrées en ligne comme des URIs data:, ce qui garde le fichier autonome et fait qu'une page avec une grande photographie peut ajouter des centaines de kilooctets de base64 au fichier. Si votre découpeur a une limite de taille, retirez les lignes commençant par ![PDF image avant de découper

Garder les drapeaux d'options Markdown et DOCX séparés

Les constantes Markdown et DOCX partagent les bits bas mais signifient des choses différentes. PDF_DOCX_INCLUDE_IMAGES vaut 1, la même valeur que PDF_MARKDOWN_INCLUDE_PAGE_MARKERS. Passez la constante DOCX à un appel Markdown et le compilateur est content, l'appel réussit, et vous obtenez des marqueurs de page. Seul un bit hors de la plage Markdown est rejeté :

var
  Md: WideString;
begin
  // Se compile et s'exécute : 1 est lu comme PDF_MARKDOWN_INCLUDE_PAGE_MARKERS
  Md := Pdf.ExportDocumentMarkdown('', PDF_DOCX_INCLUDE_IMAGES);

  // PDF_DOCX_PRESERVE_PAGE_BREAKS vaut 8, hors du masque Markdown :
  // Md revient vide et LastErrorCode vaut 113
  Md := Pdf.ExportDocumentMarkdown('', PDF_MARKDOWN_DEFAULT or
    PDF_DOCX_PRESERVE_PAGE_BREAKS);
  if (Md = '') and
     (Pdf.LastErrorCode = PDFLIB_ERROR_MARKDOWN_EXPORT_INVALID) then
    Writeln('Unknown Markdown option bit');
end;

Une chaîne vide est aussi un résultat légitime pour une page sans aucun texte, alors vérifiez LastErrorCode avant de traiter '' comme une erreur. Les échecs d'extraction rapportent 517 (PDFLIB_ERROR_MARKDOWN_EXPORT) ; les arguments mauvais, y compris une plage de pages qui ne résout aucune page, rapportent 113

DOCX sans Office sur la machine

SaveDOCXToFile et SaveDOCXToStream écrivent eux-mêmes le paquet WordprocessingML : le conteneur ZIP, les parties document, numérotation et relations, et les médias PNG. Rien n'appelle Word ni COM, si bien que la conversion tourne sur un serveur sans tête, sous un compte de service ou dans un conteneur, tous les endroits où l'automatisation Office est soit sans licence, soit instable, soit absente

uses
  Classes, SysUtils, PDFlibrary;

var
  Pdf: TPDFlib;
  Target: TFileStream;
  Written: Integer;
begin
  Pdf := TPDFlib.Create;
  try
    if Pdf.LoadFromFile('handbook.pdf', '') = 0 then
      raise Exception.Create('Cannot open handbook.pdf');
    Target := TFileStream.Create('handbook.docx', fmCreate);
    try
      Written := Pdf.SaveDOCXToStream('1-40',
        PDF_DOCX_INCLUDE_IMAGES or PDF_DOCX_DETECT_HEADINGS or
        PDF_DOCX_PRESERVE_STYLES or PDF_DOCX_PRESERVE_PAGE_BREAKS,
        Target);
    finally
      Target.Free;
    end;
    // Written égale le nombre de pages de la plage en cas de succès
    if Written <> 40 then
      raise Exception.CreateFmt('DOCX export stopped after %d pages, error %d',
        [Written, Pdf.LastErrorCode]);
  finally
    Pdf.Free;
  end;
end;

Les listes sont écrites avec les définitions de numérotation propres de Word plutôt que des préfixes "1." tapés au clavier, si bien qu'insérer un élément dans Word renumérote les autres. Les tableaux détectés deviennent de vrais tableaux Word avec des largeurs de colonnes prises des bords de colonnes mesurés et une ligne d'en-tête ombrée. Avec PDF_DOCX_PRESERVE_PAGE_BREAKS réglé, chaque page source commence sur une nouvelle page Word, sauf là où un tableau continue depuis la page précédente ; ce saut est abandonné pour que le tableau reste un seul tableau. Laissez le drapeau éteint quand les utilisateurs vont de toute façon refondre le texte, car un saut dur tous les 40 lignes les gêne

La valeur de retour est le nombre de pages écrites. Un export en flux qui renvoie moins de pages que demandé a échoué en chemin, et le flux contient un paquet incomplet, alors jetez-le plutôt que de le remettre à Word

Packaging DOCX déterministe

Deux conversions du même PDF avec les mêmes options produisent un fichier DOCX identique octet pour octet, si bien que vous pouvez hacher la sortie pour détecter un changement, comparer deux builds d'un document généré, et mettre en cache sans craindre qu'une entrée identique produise un artefact différent

Diagramme PDF Library for Delphi du packaging DOCX déterministe bâti entrée par entrée en Pascal pur à côté de l'automatisation Office dont les métadonnées intégrées décalent chaque conversion
Deux conversions identiques hachent à l'identique pour le diff et la mise en cache, une propriété que l'automatisation Office abandonne dès qu'elle intègre des horodatages frais

Deux choix font tenir cela. Chaque entrée ZIP porte la même date DOS figée, le 1er janvier 1980, au lieu de l'heure de l'exécution, et la partie propriétés de base n'a pas de dates de création ni de modification. Chaque entrée n'est compressée en Deflate brut que quand cela la rend réellement plus petite, si bien que les médias PNG, déjà compressés, sont stockés tels quels. Vous pouvez confirmer le premier point avec unzip -v handbook.docx : chaque ligne montre la même date

L'automatisation Office ne peut pas vous donner cela. Enregistrer via Word estampille l'heure courante dans les métadonnées du paquet et les en-têtes ZIP, si bien que le même document converti deux fois diffère de façons qui battent un hachage. Le même raisonnement est derrière les identifiants de fichier stables de les IDs PDF déterministes pour des builds reproductibles : une fois la sortie reproductible, la vérification devient une comparaison

Quelles entrées se convertissent bien, et lesquelles jamais

La qualité de conversion varie davantage avec l'entrée qu'avec le convertisseur, et cela vaut la peine de le dire à vos utilisateurs d'emblée. Les PDF balisés et les documents d'affaires proprement générés (factures, rapports, contrats) se convertissent bien : les titres atterrissent en titres, les tableaux survivent, les listes se renumérotent dans Word. Les mises en page académiques à deux colonnes passent dans le bon ordre de lecture quand la géométrie des colonnes est régulière, et les diagnostics rapporteront geometric-columns pour ces pages. Les tableaux qui se coupent entre pages sont ressemblés par inférence, alors contrôlez-les au coup par coup. Le matériel marketing très composé, où le texte est placé pour l'effet plutôt que dans l'ordre de lecture, ne laisse à aucun convertisseur grand-chose à récupérer ; attendez-vous à retoucher le résultat à la main

Les documents numérisés sont un cas à part. Une page qui est une grande image ne contient aucun objet de texte, si bien qu'il n'y a rien à exporter tant qu'une couche de texte n'existe pas, et faire tourner l'OCR est un prérequis pour les deux formats. Avant de vous engager dans un gros lot, échantillonnez une douzaine de fichiers représentatifs et énumérez ce que leurs pages contiennent, comme décrit dans la recherche de texte et l'énumération d'éléments de page ; une page avec des images et aucun run de texte vous en dira plus en une seconde que la lecture de la sortie convertie

Choisissez le format selon ce qui vient ensuite. Le Markdown convient aux machines et aux pipelines : les titres deviennent des limites de fragments, les tableaux restent lisibles en tables à barres, et les marqueurs de page donnent à chaque fragment une citation. Le DOCX convient aux gens qui doivent modifier le document, parce que ce qu'ils veulent en retour est un fichier éditable dans Word, avec de vraies listes et de vrais tableaux, et le texte seul ne leur donne pas cela

PDF Library for Delphi existe pour Delphi, C++Builder et Lazarus, avec des éditions DLL et ActiveX qui exposent les mêmes appels d'export Markdown et DOCX à C#, C++ et aux hôtes de script. La référence de chaque drapeau d'option et un téléchargement d'essai sont sur la page produit de PDF Library for Delphi