Converti POD in PDF

Un lettore, un flusso di lavoro di stampa o un sistema di gestione dei documenti potrebbe richiedere PDF invece del formato sorgente POD di Perl. Convertire prima POD in HTML preserva in modo più affidabile intestazioni, elenchi, esempi di codice e collegamenti rispetto al trattamento del sorgente come testo normale.

Che cos'è il formato POD

POD significa Plain Old Documentation, il linguaggio di markup leggero di Perl per documentare programmi e moduli. Viene comunemente utilizzato in file .pod autonomi e all'interno di file .pm o .pl. Direttive come =head1, =over, =item e =cut definiscono intestazioni, elenchi e il confine tra documentazione e codice Perl.

Le distribuzioni Perl, i pacchetti CPAN, i repository del codice sorgente Perl, i flussi di lavoro per i sorgenti dei manuali Unix e gli archivi della documentazione per sviluppatori utilizzano POD. Un file POD è markup sorgente, non un documento con layout di pagina, quindi il suo aspetto finale dipende dal renderer.

Che cos'è il formato PDF

PDF è un formato di documento orientato alle pagine che può preservare impaginazione, caratteri, immagini, collegamenti, metadati e impostazioni di stampa tra diversi sistemi operativi. È adatto alla stampa, agli allegati email, alle copie archiviate, ai sistemi di gestione dei documenti e ai dispositivi privi di Perl o di un renderer POD.

PDF è più difficile da modificare strutturalmente rispetto a POD. Conservare il file .pod, .pm o .pl originale come sorgente modificabile dopo aver creato il PDF.

Come convertire POD in PDF localmente

Generare HTML con pod2html

1. Installare Perl. Linux e macOS spesso lo includono; in Windows, Strawberry Perl fornisce Perl e le utilità POD standard.
2. Aprire un terminale nella directory contenente il file sorgente ed eseguire:

pod2html --outfile=manual.html manual.pod

Lo stesso comando può leggere un modulo o uno script Perl contenente POD:

pod2html --outfile=manual.html Module.pm

Viene eseguita la conversione solo della documentazione POD; il codice Perl al di fuori delle sezioni POD non viene eseguito né convertito in codice sorgente formattato.

Stampare l'HTML come PDF

1. Aprire manual.html in Chrome, Chromium, Microsoft Edge o Firefox.
2. Scegliere Print, selezionare Salva come PDF o Microsoft Print to PDF, scegliere il formato della carta e i margini, quindi salvare l'output come manual.pdf.
3. Abilitare la grafica di sfondo solo quando il foglio di stile utilizza sfondi. Controllare intestazioni, piè di pagina, interruzioni di pagina, collegamenti, rientri del codice e numero finale di pagine.

Automatizzare l'output PDF del browser

Chrome o Chromium possono creare il PDF senza aprire una finestra di dialogo di stampa:

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

Sostituire chromium con google-chrome o con il nome dell'eseguibile installato nel sistema. Utilizzare un URL assoluto file://; i percorsi relativi possono non funzionare nei comandi del browser headless.

Controllare il layout con CSS

Per le intestazioni, i blocchi di codice e i margini di pagina, fornire un foglio di stile durante la generazione dell'HTML:

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

Il CSS di stampa può definire i margini di pagina e ridurre le interruzioni indesiderate dei blocchi di codice:

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

Le impostazioni di stampa del browser continuano a controllare il formato della carta, le intestazioni, i piè di pagina, il ridimensionamento e il rendering dello sfondo. Un foglio di stile locale o un'immagine referenziata tramite un percorso relativo deve rimanere disponibile quando si apre l'HTML.

Opzioni di conversione online

Il supporto diretto da .pod a PDF è poco comune perché l'estensione .pod può identificare tipi di file non correlati e molti servizi di conversione non includono un parser per Perl POD. Per un file non riservato, generare localmente manual.html con pod2html, quindi inviare l'HTML a un servizio affidabile di conversione da HTML a PDF, come CloudConvert, se la conversione tramite browser locale non è disponibile.

Verificare che il servizio accetti HTML e conservi CSS collegati, immagini, Unicode e collegamenti ipertestuali prima di fare affidamento sul suo output. Non caricare codice sorgente proprietario o documentazione privata a meno che i termini del provider relativi a conservazione, trasferimento ed eliminazione siano accettabili; rimuovere i file caricati dopo la conversione quando il servizio lo consente.

Controlli di qualità e compatibilità

pod2html interpreta la semantica POD, ma non riproduce esattamente l'output del terminale, la formattazione delle pagine man Unix o gli stili personalizzati dei renderer Perl. Le direttive di formattazione non supportate potrebbero essere ignorate e i collegamenti a file locali, moduli installati o pagine man generate potrebbero non funzionare nel PDF.

Controllare gli elenchi annidati, i rientri del codice in formato verbatim, i caratteri con escape, i simboli Unicode, i collegamenti ipertestuali, le tabelle, le immagini e le interruzioni di pagina. I riquadri vuoti indicano solitamente un glifo mancante; utilizzare un carattere compatibile con Unicode nel browser o nel CSS. I blocchi di codice molto lunghi potrebbero comunque essere suddivisi tra più pagine nonostante break-inside: avoid, perché i browser non riescono sempre a mantenere un blocco troppo grande su una sola pagina.