Convert POD to PDF

A reader, print workflow, or document-management system may require PDF instead of Perl's POD source format. Converting POD to HTML first preserves headings, lists, code examples, and links more reliably than treating the source as plain text.

What the POD format is

POD means Plain Old Documentation, Perl's lightweight markup language for documenting programs and modules. It commonly appears in standalone .pod files and inside .pm or .pl files. Directives such as =head1, =over, =item, and =cut define headings, lists, and the boundary between documentation and Perl code.

Perl distributions, CPAN packages, Perl source repositories, Unix manual-source workflows, and developer-documentation archives use POD. A POD file is source markup rather than a page-layout document, so its final appearance depends on the renderer.

What the PDF format is

PDF is a page-oriented document format that can preserve pagination, fonts, images, links, metadata, and print settings across operating systems. It is suitable for printing, email attachments, archival copies, document-management systems, and devices without Perl or a POD renderer.

PDF is harder to edit structurally than POD. Keep the original .pod, .pm, or .pl file as the editable source after creating the PDF.

How to convert POD to PDF locally

Generate HTML with pod2html

1. Install Perl. Linux and macOS often include it; on Windows, Strawberry Perl provides Perl and the standard POD utilities.
2. Open a terminal in the directory containing the source file and run:

pod2html --outfile=manual.html manual.pod

The same command can read a Perl module or script containing POD:

pod2html --outfile=manual.html Module.pm

Only the POD documentation is rendered; Perl code outside POD sections is not executed or converted into formatted source.

Print the HTML as PDF

1. Open manual.html in Chrome, Chromium, Microsoft Edge, or Firefox.
2. Choose Print, select Save as PDF or Microsoft Print to PDF, choose the paper size and margins, and save the output as manual.pdf.
3. Enable background graphics only when the stylesheet uses backgrounds. Review headers, footers, page breaks, links, code indentation, and the final page count.

Automate browser PDF output

Chrome or Chromium can create the PDF without opening a print dialog:

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

Replace chromium with google-chrome or the executable name installed on the system. Use an absolute file:// URL; relative paths can fail in headless browser commands.

Control layout with CSS

For headings, code blocks, and page margins, supply a stylesheet while generating the HTML:

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

Print CSS can define page margins and reduce awkward code-block splits:

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

The browser's print settings still control paper size, headers, footers, scaling, and background rendering. A local stylesheet or image referenced by a relative path must remain available when the HTML is opened.

Online conversion options

Direct .pod-to-PDF support is uncommon because the .pod extension can identify unrelated file types and many conversion services do not include a Perl POD parser. For a non-confidential file, generate manual.html locally with pod2html, then submit the HTML to a reputable HTML-to-PDF service such as CloudConvert if local browser conversion is unavailable.

Confirm that the service accepts HTML and preserves linked CSS, images, Unicode, and hyperlinks before relying on its output. Do not upload proprietary source code or private documentation unless the provider's retention, transfer, and deletion terms are acceptable; remove uploaded files after conversion when the service allows it.

Quality and compatibility checks

pod2html interprets POD semantics but does not reproduce terminal output, Unix man-page formatting, or custom Perl-renderer styles exactly. Unsupported formatting directives may be ignored, and links to local files, installed modules, or generated man pages may not work in the PDF.

Inspect nested lists, verbatim code indentation, escaped characters, Unicode symbols, hyperlinks, tables, images, and page breaks. Empty boxes usually indicate a missing glyph; use a Unicode-capable font in the browser or CSS. Very long code blocks may still split across pages despite break-inside: avoid, because browsers cannot always keep an oversized block on one page.