NAME
Pdf.pm -- A POD to PDF translator
SYNOPSIS
All systems:
pod2pdf([options])
Also from the shell prompt in conjunction with the script "pod2pdf" (see "scripts/pod2pdf"):
$ pod2pdf [options] <file>
DESCRIPTION
pod2pdf
translates single POD
(Perl Plain Old Documentation) files and translates them to PDF
(Adobe Portable Document Format) files. Future extensions to this program may permit translation of multiple POD
files into a single book. At this stage the emphasis is on simplicity and ease of use. The output PDF
file takes the name of the input file with the suffix .pdf
.
PDF Outlines
are created at three levels corresponding to =head1
, =head2
and =item
. The outline
headings are reproduced as a Table of Contents
page. Long =item
strings are curtailed to a length which will fit reasonably in the space available on the page. When the PDF
document is viewed on screen, the outlines
(sometimes known as Bookmarks
) provide links to the appropriate page. When the document is printed the ToC
provides the same facility.
Links of the form xyz.pm and links to named destinations are not implemented since it is rarely possible to resolve the link except in the limited instance of links to named destinations in the document itself. Links to URL
addresses (including http, ftp and mailto) are active however and call the resident default browser. How that responds to the call will depend to some extent on the type of browser and the environment in which it finds itself.
The POD
specification perlpod.pod
allows blocks of text to be enclosed by =begin
and =end
markers. The block-type my be indicated by a string after =begin
(for example =begin html
would indicate an HTML
block) of which roff, man, latex, tex and html are recognised entities. Specification perlpod.pod
goes on to say that "A formatter that can utilize that format will use the section, otherwise it will be completely ignored." This seems to defeat the object of the documentation since quite different output might be expected according to which translator was used. It is doubtful if that would necessarily be the author's intention.
This translator, Pdf.pm
, in all cases reproduces the section enclosed by a =begin/=end
pair (or any paragraph following =for
which is similarly defined in perlpod.pod
) but in a special color so as to give a visual warning to the reader that special meaning might attach to the block of text.
The primary objective is to produce a translation of a POD
file of good typographical quality which can be printed on any printer (particularly low-cost non-PostScript ink-jet printers) in any environment. In this connection it must be recognised that some authors use POD
mark-up more intelligently and to better effect than others. Not infrequently mistakes in formatting (frequently the absence of a blank line to end a block) result in files which do not translate properly on some or all translators. PDF
files provide the very useful ability to quickly screen the translation for visual checking before the file is despatched to the printer.
OPTIONS
In the interests of simplicity and ease of use the number of options has been kept to a minimum. However an option to set paper size remains an unavoidable necessity untill such time as the world can agree on one standard. Only A4 and USLetter are preprogrammed, other custom sizes will require an edit to the Pdf.pm
code.
Options are implemented using Getopt::Long
using the syntax --[key]=
as indicated below. The order in which options are entered is immaterial.
- Paper size
-
The default paper size is A4 (which may be re-editied to a custom size):
my $x_size = 595; # default page width (pixels) my $y_size = 842; # default page height (pixels)
The option:
--paper=usletter
sets the North American standard size:
my $x_size = 612; # US letter page width (pixels) my $y_size = 792; # US letter page height (pixels)
The program will accept any (reasonable) paper size.
- Error reporting
-
Limited error reporting to STDERR may be turned on by setting
$verbose
:--verbose=1 # progress reports --verbose=2 # more extensive progress reports about links
- Input filename
-
The input file name may be entered in various ways on most sytems. It may be included as an option, or as a string argument to
pod2pdf
, or as an item in@ARGV
or finally, as a command line entry on systems which support command lines. As anoption
the syntax is:--podname=filename
- Duplex printing
-
The output is always "duplex" in the sense that the pages are "handed" with the page number (for example) at the bottom right (on odd pages) and the bottom left (on even pages). However not everyone possesses a duplex printer capable of automatically printing on both sides of the paper, but fortunately most if not all printers are capable of printing all the odd sides in one pass and all the even pages (on the reverse side of the paper) in a second pass, which achieves the same result. Even if that is either not possible or not worth the effort, and the whole document is printed single sided, the handing of the pages is no great drawback. There is really no compelling need for the complication of a switch to select simplex or duplex mode.
- Document name
-
Since the program is restricted to processing single
POD
files the input file name can be used as the output file name distinguished simply by adding the extension.pdf
to that name. If a file of that name already exists it will be overwritten without warning.
EXAMPLES
- Example 1 (all platforms)
-
use Pod::Pdf; push @ARGV, qw(--paper usletter --verbose 1); # alternatively "push @ARGV, qw(-paper usletter -verbose 1)" # but NB "push @ARGV, '--verbose 2'" will NOT work push @ARGV, 'podfilename'; pod2pdf(@ARGV);
- Example 2 (all platforms)
-
use Pod::Pdf; pod2pdf( '--paper=usletter', 'podfilename' );
- Example 3 (all platforms)
-
use Pod::Pdf; pod2pdf( '--paper=usletter', '--verbose=2', '--podfile=podfilename' );
- Example 4 (MacOS droplet)
-
use Pod::Pdf; unshift @ARGV, '--paper=usletter'; pod2pdf(@ARGV);
AUTHOR
Alan J. Fry
HISTORY
- Version 1.0 released 04 April 2000
- Version 1.1 released 18 April 2000
-
This version supports active URI links and features improved formatting.
For many helpful suggestions sincere thanks (in alphabetical order) to:
Stas Bekman <sbekman@stason.org>
Rob Carraretto <carraretto@telus.net>
M. Christian Hanson <chanson@banta-im.com>
Marcus Harnisch <harnisch@mikrom.de>
Johannes la PoutrŽ <jlpoutre@corp.nl.home.com>
Henrik Tougaard <ht000@foa.dk>
- Version 1.2 released 26 May 2000
-
This version has essentially the same functionality as version 1.1 but is reshaped into modular format. In reshaping the module grateful thanks are due to Axel Rose http://www.roeslein.de/axel/ whose suggestion to place the opening statements of the program into the subroutine
pod2pdf
has been adopted together with his proposals for exporting the function name. This arrangement bringsPdf.pm
more into line with the structure of other POD translators. His assistance in testing the module on a variety of platforms (MacOS, Linux and Windows) has been invaluable as has his advice on the structure of the interface and many fine details too numerous to mention individually.
VERSION
COPYRIGHT
11 POD Errors
The following errors were encountered while parsing the POD:
- Around line 1967:
'=item' outside of any '=over'
- Around line 2006:
You forgot a '=back' before '=head1'
- Around line 2042:
You forgot a '=back' before '=head1'
- Around line 2046:
'=item' outside of any '=over'
- Around line 2050:
You forgot a '=back' before '=head1'
- Around line 2052:
'=item' outside of any '=over'
- Around line 2070:
Non-ASCII character seen before =encoding in 'PoutrŽ'. Assuming CP1252
- Around line 2080:
You forgot a '=back' before '=head1'
- Around line 2082:
'=item' outside of any '=over'
- Around line 2084:
You forgot a '=back' before '=head1'
- Around line 2086:
'=item' outside of any '=over'
=over without closing =back