a2pdf - converts ASCII text to PDF format, with optional line/page numbering and Perl syntax highlighting


 a2pdf [options] [filename]


a2pdf recognises the following command line options:


Displays usage message and exits.


Displays full documentation and exits.


Prints the version number and exits

--output-file | -o

Specifies the filename for the PDF file. If this option is not set, a2pdf will output to STDOUT.


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 a2pdf is processing from standard input.


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.


Path to an image file which will be included as part of the header in the top left of each page.

Image files may be in any format supported by PDF::API2.


Scaling value for icon images, default is 0.25.

--header | --noheader | --notitle

Prints a header consististing of the page title, and optionally the timestamp and an image icon at the top of each page. This option is enabled by default, use --notitle or --noheader to disable.

Adds the current page number to the bottom of each page. This is enabled by default, use --nofooter or --nopage-numbers to disable.

--line-numbers | --noline-numbers

By default, line numbers will be included in the output PDF file. To disable this behaviour, use the --noline-numbers option.

--perl-syntax | --noperl-syntax

Enables or disables (default is enabled) Perl syntax highlighting. This feature requires that the Perl::Tidy module is installed.


Page width and height in points. Default page size is 595 x 842 (A4).


Sets the page size to one of the 'standard' paper formats, e.g. "A4" or "Letter". Requires the module Paper::Specs to be installed.


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.


Specifies the non-printable area of the page. The --margin 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, and for the top and bottom margins is 60 points.


Sets the font to use for the PDF file - currently this must be one of the PDF core fonts. The default font face is Courier.


Font size in points, default value is 10.


Line spacing in points, default value is the font size + 2.


By default, any formfeed characters in the input stream will be processed and will act as expected, i.e. a new page will be started in the output PDF file. This can be disabled with the --noformfeed option which will cause all formfeed characters to be ignored.


Location of a settings file (described below).

Options may be given in any format recognised by the Getopt::Long Perl module, e.g. --name=value or --name value. Option names may be abbreviated to their shortest unique value.

If the input filename is not given, then a2pdf will expect to receive input from STDIN.

Config / settings files

Options to a2pdf may be stored in settings files. These have the same format as the command line options with the exception that the '--' chharacters preceding the option name are optional.

A single option may be contained on each line of the settings file, e.g.


At startup, a2pdf looks for a default settings file named a2pdf.conf in the current directory, the user's home directory, and the directory containing the a2pdf script.

Settings will cascade as follows;

 Default 'a2pdf.conf' settings file              -->
 Settings file specified by '--settings' option  -->
 Options given on the command line

i.e. options on the command line will always take precedence.


a2pdf requires the PDF::API2 Perl module (tested with PDF::API2 version 0.3r77).

Perl syntax highlighting requires the Perl::Tidy module (tested with Perl::Tidy version 20031021).

To include images in the page header, the modules File::Type and Image::Size must be installed.

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


  • If the Perl syntax highlighting feature is used and the input Perl code uses source filter modules, then depending on the changes made by the source filter the syntax highlighting may not be performed correctly.


a2pdf homepage -

pod2pdf -


Perl::Tidy -


Written by Jon Allen (JJ), <> /


Copyright (C) 2004 Jon Allen (JJ)

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.