pod2pdf

Converts POD to PDF format

Download

Usage 

pod2pdf [options] filename.pod >filename.pdf
perldoc -u <Module::Name> | pod2pdf [options] >filename.pdf

Options

pod2pdf accepts the following command-line options:

  • --version
    Prints version number and exits
  • --output-file
    Specifies the filename for the output PDF file. If this option is not set, pod2pdf will output to STDOUT.
  • --header | --noheader
    Prints a header consististing of the document title, and optionally the timestamp of the source file and an image icon at the top of each page. This option is enabled by default, use --noheader to disable.
  • --footer | --nofooter
    Adds page numbers to the bottom of each page. This is enabled by default, use --nofooter to disable.
  • --title
    Sets the title to be included in the page header. If unspecified, the title will default to the name of the file which is being converted, or to 'STDIN' if pod2pdf is processing from standard input.
  • --footer-text
    Specifies an additional text string to be included in the page footer.
  • --icon
    Path to an image file which will be included as part of the header in the top left of each page. Image files must be in a format supported by PDF::API2 (JPEG, PNG, GIF, TIFF, or PNM).
  • --icon-scale
    Scaling value for the icon image - default is 0.25
  • --timestamp
    Boolean option - if set, the timestamp of the file to be converted will be included in the page header. This option is turned off by default.
  • --margins
  • --left-margin
  • --right-margin
  • --top-margin
  • --bottom-margin
    Specifies the non-printable area of the page. The --margins option will set all margins to the same value, however individual margins may be altered with the appropriate options. Values must be given in points. The default value for the left and right margins is 48 points (0.75"), for the top and bottom margins the default value is 60 points.
  • --page-height
    Page height in points. Default is 842 (A4).
  • --page-width
    Page with in points. Default is 595 (A4).
  • --page-size
    Sets the page size to one of the 'standard' paper formats, e.g. "A4" or "Letter". Requires the module Paper::Specs to be installed.
  • --page-orientation
    Sets the page orientation, acceptable values are 'portrait' or 'landscape'. Overrides the --page-height and --page-width options, i.e. the option set --page-height=300 --page-width=100 --page-orientation=landscape will set the page height to 100 points and the width to 300 points to force landscape format.

Config / settings files

Sets of command-line options may be saved into configuration files.

A configuration file contains options in the same format as used by pod2pdf 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, create a file mycompany.conf containing the following: 

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

Then invoke pod2pdf as: 

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

If you create a config file called pod2pdf.conf and place this in the same directory as the pod2pdf script, it will be loaded as the default configuration.

Supported features

The following POD tags can be used: 

=head1
=head2
=head3
=head4
=over
=over number
=item
=item *
=item number
=item text
=back

Pod formatting commands B<>, C<>, E<>, F<>, I<>, L<>, S<>, X<>, and Z<> are supported. These can be used in text blocks or in the text field of =item tags. In =head blocks, all formatting commands may be used, but the heading font will remain fixed, i.e. B<>, I<>, and C<> will have no effect.

Formatting commands may be nested, e.g. B<I<bold_italic>> or C<$object-E<gt>method>.

Verbatim blocks will be displayed in Courier font.

Pod extensions

In addition to the commands listed above, pod2pdf.pl supports the following extensions to the Pod syntax:

  • =ff command
    Creates a page break in the output PDF file
  • O<> formatting code
    Inserts an object into the PDF file - supported formats are PNG, JPEG, and PNM.

These are described fully in perlpodextensions.pdf

Unsupported features

  • S<> formatting command does not prevent line breaks

Dependencies

Requires the following modules:

To use inline images (the O<> formatting code) and header icons, the modules File::Type and Image::Size are required.

To enable the "--page-size" option, the Paper::Specs module must be installed.