NAME¶
pod2pdf - converts Pod to PDF format
DESCRIPTION¶
pod2pdf converts documents written in Perl's POD (Plain Old Documentation)
format to PDF files.
Usage¶
pod2pdf [options] input.pod >output.pdf
If no input filename is specified, pod2pdf will read from STDIN, 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 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.
POD ENTENSIONS¶
As well as 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.
SEE ALSO¶
The pod2pdf homepage: <
http://perl.jonallen.info/projects/pod2pdf>
For more information 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
<
http://www.perlfoundation.org/legal/licenses/artistic-2_0.html>.