Form2PDF 4 - User's Guide
- What's new?
- Getting started
- Configuring Form2PDF
- Creating PDF
- Document security
- Mailer (SMTP client)
New features in Form2PDF include:
- TLS and SSL support
- Limited HTML/XML support
- Limited PCL command support
- Support for PDF/A (long-term preservation)
- External TrueType fonts can be used
- Unicode support
Form2PDF uses code from The FreeType Project, http://www.freetype.org.
Form2PDF includes cryptographic software written by Eric Young (firstname.lastname@example.org)
Form2PDF includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org)
BitStream Vera fonts
Form2PDF includes fonts based on the BitStream Vera fonts subject to the copyright below.
Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. Bitstream Vera is a trademark of Bitstream, Inc.
Download the Form2PDF you want from the URL below:
Download the compressed tar archive binary, for example form2pdf30-solaris-full.tar.gz.
Uncompress it with gzip and extract it.gzip -d form2pdf40-33432-linux-32bit-full.tar.gz
tar xvf form2pdf40-33432-linux-32bit-full.tar
A new directory form2pdf-dist will be created. Change directory and run the installation script.cd form2pdf-dist
Check the file README for additional information and instructions.
Optionally add a license key (if you have purchased one) to the file /etc/form2pdf/form2pdf.cfg using the text editor of your choice.
Without a license key Form2PDF will run in "demo" mode. In "demo" mode it is fully functional except for random lines in the created output being replaced by a demo message.
License keys are locked to the hostid of the server where Form2PDF will be used. The hostid is a unique hardware id and if the software is moved from one server to another a new license key is needed.
The hostid can be displayed by running "form2pdf --showhostid".
A license key which removes the demo message for commercial operation can be purchased at the following URL, http://www.form2pdf.se/buy.html.
The form2pdf binary takes numerous arguments which can be specified on the command-line or in the configuration file, /etc/form2pdf/form2pdf.cfg.
In order to display the available command-line parameters run "form2pdf --help".
Run "form2pdf --help" to list available command-line options.
Converting a text file
In its simplest form we only need to supply the name of an input text file and the output PDF file to convert from text to PDF. Several input files can be specified, each file will begin on a new page.
Example:form2pdf first.txt first.pdf
Controlling page layout
Page dimensions are set using the "--pagewidth" and "--pageheight" parameters. The default values are 595 and 842 pixels respectively. This corresponds to an A4 page at 72 dpi. For US Letter 612 (width) and 792 (height) would be used.
Margins are set using "--marginleft" and "--margintop", linespacing and lines per page using "--linespacing" and "--linesperpage".
Example:form2pdf --pagewidth 612 --pageheight 792 letter.txt letter.pdf
Adding a background image
A background image (or template) can be added to each page using the parameter "--bgimage". The background image must be in PNG (Portable Network Graphics) format. Most graphics software such as SmartDraw, Macromedia Fireworks and CorelDraw can save images in PNG format.
In order for Form2PDF to perform well the images should not be unnecessarily large and the pixel depth should be kept as low as possible.
The image will be scaled to the page size regardless of the actual image size. It is therefore important that the image has the same proportions as the page, otherwise it will be distorted. Default page size is 842 x 595 pixels (A4, 72 dpi).
Example:form2pdf --bgimage bg.png test.txt test.pdf
Changing the font and font size
The default font used is Courier which is a font with fixed spacing. The font used can be changed to any of the fonts which are "built-in" and always available in PDF readers.
It is also possible to change the size (default: 9pt) of the font by using parameter "--fontsize".
Example:form2pdf --fontsize 12 --fontname Times-Roman test.txt test.pdf
- Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique
- Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique
- Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic
- Symbol, ZapfDingbats
Using external TrueType fonts
To use an external TrueType font, follow these steps:
- Copy the font file to /etc/form2pdf/fonts, or use --fontdir dirname to load the file from another directory. If you want to use fonts from several directories, make a new directory and make symbolic links to the them. Form2PDF will follow these links, and find the entire set of fonts.
- Run "form2pdf --showfonts", to show the available fonts.
- Add "--fontname FontName" to the command line, where FontName is taken from the field after the slash in the font list.
Adding to existing PDF
Convert first page:form2pdf first.txt first.pdf
Convert rest of pages adding them after first page:form2pdf first.pdf contents.txt output.pdf
Controlling PDF document information
It is possible to change PDF document information using the parameters below.
Example:form2pdf --pdftitle "Invoice 12340" --pdfsubject "This is an invoice" \
--pdfauthor "Bill, Sample Company Inc" --pdfkeywords "Invoice, Bill" \
--pdfproducer "ERP App 3.0" invoice.txt invoice.pdf
PDF/A is a constrained form of PDF version 1.4 intended to be suitable for long-term preservation of documents. This PDF version contains a number of restrictions and additions. Using the "--pdfa" parameter will cause Form2PDF to generate a PDF/A compliant document.
One of the most important changes is that the fonts used will be embedded in the file.
Generate PDF/A compliant document.
PDF Description, for the PDF/A Metadata
PDF Creator, for the PDF/A Metadata
PDF Language, for the PDF/A Metadata
More information about PDF/A can be found here:
Using PCL commands
Using PCL commands it is possible to control the layout and font use in a document in more detail. PCL stands for Printer Control Language and is one of the standards used to control printouts to laser printers.
All PCL commands start with the ESC character (0x1B) followed by one of the commands below. The character "#" below should be replaced by a numeric value.
%A : leave hpgl mode (see "%B")
%B : enter hpgl mode, making form2pdf ignore everything up to the "leave" command
E : reset
(s#B: primary stroke weight, 0=normal, >2 gives bold
(s#H: primary pitch, chars/inch
(s#P: 0 gives fixed spaced font Courier, and 1 gives proportional Helvetica
(s#S: primary style upright, 0=normal, 1=italics/oblique
(s#T: primary typeface, 3 gives Courier, 4, 4148 and 16602 gives Helvetica, 5 and 4101 gives Times-Roman, and anything else gives the current default font
(s#V: primary font size, also changes the linespacing
&a#L: left margin (characters, hard coded as fontsize * 2 / 3)
&d@ : underline off (ignored)
&f#S: cursor pos, 0=push, 1=pop, ignoring all movement when level>0
&l#A: paper size, 1=executive, 2=letter, 3=legal, 26=A4
&l#D: line spacing in lines/inch
&l#E: margin top, in lines
&l#F: lines per page
&l#H: paper tray (ignored)
&l#L: skip perforation (ignored)
&l#O: page orientation, 0=portrait, 1=landscape
&k#S: font size, 0=10, 1=12, 2=16 (default 12)
&l#Z: margin top, in 1/720 inch
*c : graphics commands, ignored
*v : print patterns, ignored
*p#X: move horizontal, absolute or relative, in 1/300 inch
*p#Y: move vertical, absolute or relative, in 1/300 inch
Hypertext links / XML tags
It is possible to use HTML-style tags in order to define hypertext links within a document and to generate a document outline. This requires the use of the parameter "--xml".
Example:form2pdf --xml testwithlinks.txt output.pdf
where "testwithlinks.txt" could look something like this:
To visit our website <a href="http://www.example.com">click here</a>.
Links can be surrounded by a border (frame) controlled by the parameters "--linkframe" and "--linkwidth". The linkframe parameter takes an argument specifying the style of the frame: s=solid, d=dashed, b=beveled, i=inset, u=underline. The default value is "s" for "solid".
Using the tags h1, h2, h3, h4 it is possible to add sections to the document outline (bookmarks).
Unicode and input maps
The input data is by default considered to be in ISO-8859-1 (Latin-1). There are several options to override this.
Use --ucs2 or --ucs2be if the input file is in UCS2, big endian.
Use --ucs2le for UCS2, little endian. The UCS2 escape codes U+FFFE to force little endian and U+FEFF to for big endian, is respected. The endianness is reset at the beginning of each file.
Use --utf8 for UTF-8.
For even more flexible input handling, use --inputmap mapfile. The mapfile should reside in the directory given by --mapdir, by default /etc/form2pdf/maps.
In the "mapfile", each line should have two fields, separated by a tab. In the first column comes the character to map from as a hex value, for example '=A3'. In the second column comes the unicode character to map to, in standard unicode notation. In ISO-8859-2, the character A3 maps to 'U+0141'.
Provided in the distribution are maps for ISO-8859-1 to ISO-8859-15, and Microsoft Windows Codepage 1252.
Normally the content of a PDF document is not encrypted. By locking the document using an "owner" password the contents is encrypted and the operations a user is allowed to perform on the document can be restricted.
Two different type of password can be used to protect a document. The "owner" password can be used to create a "read-only" document which cannot be modified by a user. It is also possible to assign a "user" password which will have the effect that it is not possible to even open and read the document without entering the password.
Example (set both owner and user password):form2pdf -userpassword secret -ownerpassword verysecret test.txt test.pdf
By specifying a PDF protect mask (parameter "--pdfprotectmask") the owner of the document can specify which operations on the document will be denied, the default being modification of the contents.
Bits in protect mask (setting a bit denies the corresponding operation):
- 4 - Printing
- 8 - Modiy contents
- 16 - Copy text and graphics from document
- 32 - Add or modify text annotations and form fields
Example (set both owner password and deny printing or modifying of document, 4+8):form2pdf -userpassword secret -ownerpassword verysecret \
--pdfprotectmask 12 test.txt test.pdf
Changing encryption key length
The encryption key length can be set between 40 bits (weak) and 128 bits (strong) by using the command line option "--keylength". If a key length larger than 40 bits it will force the PDF version to 1.4 or higher.
Mailer (SMTP client)
Form2PDF includes an SMTP client which can be used for sending the resulting PDF documents (or in fact any file) as e-mail with document(s) being attachments.
Example:form2pdf --mailto email@example.com --sender firstname.lastname@example.org \
Addresses can be in one of two forms. First, the normal, address-only, "email@example.com" notation, and second the "Full Name <firstname.lastname@example.org>" notation. Either form can be used for both the --mailto, --cc, and --bcc options.
Subject and headers
You can specify the e-mail subject using the parameter "--subject". Also it is possible to add other custom header lines by adding those to a separate file and then use the "--headerfile" parameter.
Example:form2pdf --mailto email@example.com --sender firstname.lastname@example.org \
--subject "Invoice 12340" invoice.txt invoice.pdf
In order to send e-mail to multiple recipients Form2PDF supports use of one or more "--mailto" parameters and optionally use of "--cc" (carbon copy) and "--bcc" (blind carbon copy) parameters. Each recipient specified by the use of these parameters will receive a copy of the e-mail. In the e-mail headers there will be one corresponding To:, Cc: and Bcc line for each entry.
Example:form2pdf --sender email@example.com --mailto firstname.lastname@example.org \
--mailto email@example.com --cc firstname.lastname@example.org --cc email@example.com \
--bcc firstname.lastname@example.org --bcc email@example.com mydocument.doc test.pdf
Some SMTP servers requires the client to authenticate before allowing e-mails to be sent. This is supported by Form2PDF via the "--smtpuser" and "--smtppassword" parameters.
Authentication is only done if both the username and password is set.
If the server allows the LOGIN method, that is used. As a second choice, PLAIN is used. If neither method is supported, authentication isn't used.
Example:form2pdf --mailto firstname.lastname@example.org --sender email@example.com \
--smtphost smtp.example.com --smtpuser myuser1 --smtppassword secret \
SMTP and encryption (TLS/STARTTLS or SSL/smtps)
In order to connect to a SMTP server supporting TLS (STARTTLS) use parameter "--tls". For SSL/smtps use "--smtps".
When using the "--mailonly" parameter no conversion is performed and form2pdf acts as a stand-alone SMTP client which can be used to send any kinds of attachments (text, documents, images etc) as e-mail from the command-line.
form2pdf --mailonly --mailto firstname.lastname@example.org --sender email@example.com \
By default, files ending with .txt, .gif, .jpg and .png are sent with the disposition parameter set to "inline", and all others as "attachment". To send all files as attachments, use the parameter --noinline.
Delivery receipts / notifications
To get a delivery receipt when the user has opened the mail, use the parameter "--receiptto". Please note that not all e-mail clients support delivery receipts and if they do the user can usually suppress sending of the receipt.
form2pdf --mailonly --mailto firstname.lastname@example.org --receiptto
--sender email@example.com mydocument.doc
When the "--syslogfacility" option is specified syslog is used to log messages. The parameter can be "local0" through to "local7" or "user" (default) for the corresponding syslog facility. The syslog daemon, syslogd, may ne to be configured through syslog.conf and refreshed in order for log messages to be written to the intended destination.
Running in debug mode
It is possible to run form2pdf in debug mode by adding the parameter "--debug" or "--debug2" (more logging) to the command-line.
Example:form2pdf --debug2 test.txt test.pdf
Problem sending e-mail
Sending e-mail from Form2PDF requires you have access to a SMTP server to which Form2PDF can connect and send the e-mail via SMTP. The SMTP server can either be local, such as sendmail running on the same server as Form2PDF, or remote such as a SMTP server at your ISP.
By default Form2PDF tries to connect to localhost on port 25, the standard TCP port for SMTP. You may need to change this depending on your environment. One easy way to find out whether the SMTP server is reachable is to telnet to the SMTP host and port you specify. You should get a response from the SMTP server.
Sample session:[root@lina i386]# telnet localhost 25
Connected to localhost.
Escape character is '^]'.
220 lina.example.com Sendmail 8.11.6/8.11.0; Tue, 6 Dec 2005 16:24:47 +0100
221 2.0.0 lina.example.com closing connection
Connection closed by foreign host.
If you get a "connection refused" or similar error message then there is no SMTP server available on the specified host and port.
If it takes long (several seconds) to convert files into PDF when using a background image it may very well be the image handling that steals most of the time. Try to convert without the background image and compare the time.
If you run form2pdf with parameter "--debug2" you will see a couple of lines similar to these:image_load: Color type is 6, bit depth = 8, pixel depth = 32
Add file `test.txt'
image_print: Storing image with width 2096 and height 2620
This file in uncompressed format is about 5 megapixel where each pixel uses 32 bits (4 bytes), while in PNG compressed format the file was about 170 kb.
So, make sure that you do not use much larger images than needed. For example, a black and white image does not need a pixel depth of 32 bits.