Convertir POD en PDF

Un lecteur, un flux d’impression ou un système de gestion documentaire peut nécessiter un PDF au lieu du format source POD de Perl. Convertir d’abord le POD en HTML préserve plus fiablement les titres, les listes, les exemples de code et les liens que de traiter la source comme du texte brut.

Qu’est-ce que le format POD ?

POD signifie Plain Old Documentation, le langage de balisage léger de Perl utilisé pour documenter les programmes et les modules. Il apparaît couramment dans des fichiers .pod autonomes ainsi qu’à l’intérieur de fichiers .pm ou .pl. Des directives telles que =head1, =over, =item et =cut définissent les titres, les listes et la séparation entre la documentation et le code Perl.

Les distributions Perl, les paquets CPAN, les dépôts de code source Perl, les flux de travail liés aux sources des manuels Unix et les archives de documentation destinées aux développeurs utilisent le POD. Un fichier POD est un balisage source plutôt qu’un document mis en page : son apparence finale dépend donc du moteur de rendu.

Qu’est-ce que le format PDF ?

PDF est un format de document orienté page qui peut préserver la pagination, les polices, les images, les liens, les métadonnées et les paramètres d’impression sur différents systèmes d’exploitation. Il convient à l’impression, aux pièces jointes d’e-mails, aux copies d’archivage, aux systèmes de gestion documentaire et aux appareils dépourvus de Perl ou d’un moteur de rendu POD.

Le PDF est plus difficile à modifier structurellement que le POD. Conservez le fichier .pod, .pm ou .pl d’origine comme source modifiable après avoir créé le PDF.

Comment convertir localement un POD en PDF

Générer du HTML avec pod2html

1. Installez Perl. Linux et macOS l’incluent souvent ; sous Windows, Strawberry Perl fournit Perl et les utilitaires POD standard.
2. Ouvrez un terminal dans le répertoire contenant le fichier source et exécutez :

pod2html --outfile=manual.html manual.pod

La même commande peut lire un module ou un script Perl contenant du POD :

pod2html --outfile=manual.html Module.pm

Seule la documentation POD est rendue ; le code Perl situé en dehors des sections POD n’est ni exécuté ni converti en code source mis en forme.

Imprimer le HTML au format PDF

1. Ouvrez manual.html dans Chrome, Chromium, Microsoft Edge ou Firefox.
2. Choisissez Print, sélectionnez Save as PDF ou Microsoft Print to PDF, choisissez le format de papier et les marges, puis enregistrez le résultat sous manual.pdf.
3. Activez les graphiques d’arrière-plan uniquement lorsque la feuille de style utilise des arrière-plans. Vérifiez les en-têtes, les pieds de page, les sauts de page, les liens, l’indentation du code et le nombre final de pages.

Automatiser la génération du PDF par le navigateur

Chrome ou Chromium peut créer le PDF sans ouvrir de boîte de dialogue d’impression :

chromium --headless --disable-gpu --print-to-pdf=manual.pdf file:///absolute/path/manual.html

Remplacez chromium par google-chrome ou par le nom de l’exécutable installé sur le système. Utilisez une URL file:// absolue ; les chemins relatifs peuvent échouer dans les commandes de navigateur sans interface graphique.

Contrôler la mise en page avec CSS

Pour les titres, les blocs de code et les marges de page, fournissez une feuille de style lors de la génération du HTML :

pod2html --css=manual.css --title="Manual" --outfile=manual.html manual.pod

Le CSS d’impression peut définir les marges de page et réduire les coupures inappropriées des blocs de code :

@page { margin: 20mm; } pre { break-inside: avoid; }

Les paramètres d’impression du navigateur contrôlent toujours le format de papier, les en-têtes, les pieds de page, la mise à l’échelle et le rendu de l’arrière-plan. Une feuille de style locale ou une image référencée par un chemin relatif doit rester disponible lorsque le HTML est ouvert.

Options de conversion en ligne

La prise en charge directe de .pod vers PDF est peu courante, car l’extension .pod peut identifier des types de fichiers sans rapport et de nombreux services de conversion n’intègrent pas d’analyseur Perl POD. Pour un fichier non confidentiel, générez localement manual.html avec pod2html, puis envoyez le HTML à un service HTML vers PDF réputé tel que CloudConvert si la conversion locale par navigateur n’est pas disponible.

Vérifiez que le service accepte le HTML et préserve les CSS liés, les images, l’Unicode et les liens hypertexte avant de vous fier à son résultat. N’envoyez pas de code source propriétaire ni de documentation privée, sauf si les conditions de conservation, de transfert et de suppression du fournisseur sont acceptables ; supprimez les fichiers téléversés après la conversion lorsque le service le permet.

Vérifications de qualité et de compatibilité

pod2html interprète la sémantique du POD, mais ne reproduit pas exactement la sortie du terminal, la mise en forme des pages de manuel Unix ou les styles personnalisés des moteurs de rendu Perl. Les directives de mise en forme non prises en charge peuvent être ignorées, et les liens vers des fichiers locaux, des modules installés ou des pages de manuel générées peuvent ne pas fonctionner dans le PDF.

Inspectez les listes imbriquées, l’indentation du code verbatim, les caractères échappés, les symboles Unicode, les liens hypertexte, les tableaux, les images et les sauts de page. Des cases vides indiquent généralement un glyphe manquant ; utilisez une police compatible avec l’Unicode dans le navigateur ou le CSS. Les blocs de code très longs peuvent tout de même être répartis sur plusieurs pages malgré break-inside: avoid, car les navigateurs ne peuvent pas toujours conserver un bloc trop volumineux sur une seule page.