POD2PDF(1p)

💖 POD2PDF(1p) — the pod2pdf girlies' guide 💖

User Contributed Perl Documentation · pod2pdf(1p) · the tool that turns your Pod into a whole PDF, no cap

---

✨ NAME ✨

pod2pdf — bestie, it converts Pod to PDF format. that's it, that's the job 💅

---

🌸 DESCRIPTION 🌸

pod2pdf takes documents written in Perl's POD (Plain Old Documentation) format and turns them into PDF files. glow-up of the century honestly 🦋

📝 Usage

pod2pdf [options] input.pod >output.pdf

If you don't hand it an input filename, pod2pdf will just read from STDIN instead, like:

perldoc -u File::Find | pod2pdf [options] >File-Find.pdf

piping it straight in? iconic. 🌈

🎀 Options

pod2pdf accepts the following command-line options:

• --output-file — sets the output filename for the PDF it generates. by default pod2pdf outputs to STDOUT.
• --page-size — sets the page size used in the PDF file. you can set it to any of the standard paper sizes (A4, A5, Letter, etc). defaults to A4.
• --page-orientation — controls whether pages come out in landscape or portrait format. defaults to portrait.
• --page-width, --page-height — sets the width and height of the generated pages in points, for when you're using non-standard paper sizes.
• --left-margin, --right-margin, --top-margin, --bottom-margin — lets you set each of the page margins (top, bottom, left, and right) individually, in points.
• --margins — sets all the page margins to the same size (specified in points).
• --header, --noheader — controls whether a header gets included on each page (the header has the page title, plus optional timestamp and icon). defaults to on, so use --noheader to turn it off.
• --title — sets the page title. defaults to the input filename.
• --timestamp — boolean option. if you set it, the 'last modified' timestamp of the input file goes into the page header.
• --icon — filename of an icon to be displayed in the top left corner of each page.
• --icon-scale — scaling value for the header icon. defaults to 0.25.
• --footer, --nofooter — controls whether a footer gets included on each page (the footer has the current page number and optional text string). by default the footer is included, so use --nofooter to turn it off.
• --footer-text — sets an optional footer text string that gets included in the bottom left corner of each page.
• --outlines — adds outlines (bookmarks) to the pdf according to headings (=head1, =head2, ...).
• --version — prints the version number and exits. bye bestie 👋

🗂️ Configuration files

You can save whole sets of command-line options into configuration files. so organized of you. ✨

A configuration file holds options in the exact same format pod2pdf uses on the command line, with one option given on each line of the file, e.g.

--page-size A5
--page-orientation landscape

To use a config file, invoke pod2pdf with the option @/path/to/configfile.conf.

For example, if you wanted to always include a company logo, timestamp, and copyright notice in your PDF files, you'd create a file mycompany.conf containing the following:

--icon "/path/to/your/logo.png"
--footer-text "Copyright 2007 MyCompany Limited"
--timestamp

Then you invoke pod2pdf like:

pod2pdf @/path/to/mycompany.conf input.pod >output.pdf

And listen — if you create a config file called pod2pdf.conf and place it in the same directory as the pod2pdf script, it will be loaded as the default configuration. automatic. we love a default. 👑

---

🦋 POD ENTENSIONS 🦋

On top of the standard POD commands (see perlpodspec), pod2pdf supports the following extensions to the POD format:

• =ff — the =ff command inserts a page bread (form feed) into the document.
• O<...> — the O<...> formatting code inserts an external object (file) into the document. this is primarily intended for embedding images, e.g.

O</path/to/figure1.jpg>

to insert diagrams, etc into documentation.

pod2pdf supports the file types JPG, GIF, TIFF, PNG, and PNM for embedded objects. 💖

---

🌈 DEPENDENCIES 🌈

pod2pdf requires the following modules to be installed:

• PDF::API2
• Pod::Escapes
• Getopt::ArgvFile

Additionally, to use images, the modules File::Type and Image::Size must be installed, and to specify alternative page sizes the Paper::Specs module is required. (yes, that's a whole lotta modules. worth it tho. 💅)

---

⭐ SEE ALSO ⭐

The pod2pdf homepage: <http://perl.jonallen.info/projects/pod2pdf>

For more info about POD, read the perlpod manpage or see the POD page on the Perl 5 Wiki (<http://www.perlfoundation.org/perl5/index.cgi?pod>).

---

👑 COPYRIGHT and LICENSE 👑

Copyright (C) 2007 Jon Allen (JJ) <jj@jonallen.info>

This software is licensed under the terms of the Artistic License version 2.0.

For full license details, please read the file artistic-2_0.txt included with this distribution, or see <http://www.perlfoundation.org/legal/licenses/artistic-2_0.html>.

---

okay that's the whole page bestie, you're officially a pod2pdf expert 🎀✨

this page brought to you by perl v5.32.1, dated 2021-05-23 — mwah, xoxo, go make some PDFs 💖🦋🌸