pod2pdf (1)

Leading comments

Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man1/pod2pdf.1p".)

NAME

pod2pdf - converts Pod to PDF format

DESCRIPTION

pod2pdf converts documents written in Perl's (Plain Old Documentation) format to files.

Usage

 pod2pdf [options] input.pod >output.pdf

If no input filename is specified, pod2pdf will read from

e.g.

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

Options

pod2pdf accepts the following command-line options:

--output-file

Sets the output filename for the generated

PDF

file. By default pod2pdf will output to

STDOUT.

--page-size

Sets the page size to be used in the

PDF

file, can be set to any of the standard paper sizes (A4, A5, Letter, etc). Defaults to A4.

--page-orientation

Controls if pages are produces in landscape or portrait format. Defaults to 'portrait'.

--page-width, --page-height

Sets the width and height of the generated pages in points (for using non-standard paper sizes).

--left-margin, --right-margin, --top-margin, --bottom-margin

Allows each of the page margins (top, bottom, left, and right) to be individually set in points.

--margins

Sets all page margins to the same size (specified in points).

--header, --noheader

Controls if a header (containing the page title, and optional timestamp and icon) will be included on each page. Defaults to on, so use "--noheader" to disable.

--title

Sets the page title (defaults to the input filename).

--timestamp

Boolean option - if set, includes the 'last modified' timestamp of the input file in 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 if a footer (containg the current page number and optional text string) will be included on each page. By default the footer will be included, so use "--nofooter" to disable.

--footer-text

Sets an optional footer text string that will be included in the bottom left corner of each page.

--outlines

Adds outlines (bookmarks) to pdf according to headings (=head1, =head2, ...).

--version

Prints version number and exits.

Configuration 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

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.

POD ENTENSIONS

As well as the standard commands (see perlpodspec), pod2pdf supports the following extensions to the 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.

SEE ALSO

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

For more information about

read the perlpod manpage or see the page on the Perl 5 Wiki (<www.perlfoundation.org/perl5/index.cgi?pod>).

COPYRIGHT and LICENSE

Copyright (C) 2007 Jon Allen () <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 <www.perlfoundation.org/legal/licenses/artistic-2_0.html>.