Form2PDF 4 - User's Guide

What's new?

New features in Form2PDF include:

Acknowledgements

FreeType

Form2PDF uses code from The FreeType Project, http://www.freetype.org.

OpenSSL

Form2PDF includes cryptographic software written by Eric Young (eay@cryptsoft.com)

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.

Top »

Getting started

Download

Download the Form2PDF you want from the URL below:
http://www.form2pdf.se/download.html

Installing Form2PDF

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
sh ./INSTALL

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.

License

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.

Top »

Configuring Form2PDF

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".

Top »

Creating PDF

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

Standard fonts:

Using external TrueType fonts

To use an external TrueType font, follow these steps:

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 support

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.

More information about PDF/A can be found here:
http://www.digitalpreservation.gov/formats/fdd/fdd000125.shtml

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:

Some text
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).

Top »

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.

Top »

Document security

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):

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.

Top »

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 user@example.com --sender sender@example.com \
   test.txt test.pdf

Address formats

Addresses can be in one of two forms. First, the normal, address-only, "user@host.domain" notation, and second the "Full Name <user@host.domain>" 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 user@example.com --sender sender@example.com \
  --subject "Invoice 12340" invoice.txt invoice.pdf

Multiple recipients

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 sender@example.com --mailto user1@example.com \
  --mailto user2@example.com --cc user3@example.com --cc user4@example.com \
  --bcc user5@example.com --bcc user6@example.com mydocument.doc test.pdf

SMTP authentication

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 user@example.com --sender sender@example.com \
  --smtphost smtp.example.com --smtpuser myuser1 --smtppassword secret \
  test.txt test.pdf

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".

Parameter "--mailonly"

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.

Example:

form2pdf --mailonly --mailto user@example.com --sender sender@example.com \
  mydocument.doc

Parameter "--noinline"

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.

Example:

form2pdf --mailonly --mailto user@example.com --receiptto sender@example.com \
  --sender sender@example.com mydocument.doc

Top »

Logging

Using syslog

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.

Top »

Troubleshooting

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
Trying 127.0.0.1...
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
quit
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.

Performance

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.

Top »

Overview | FAQ | Order | Download | Legal and privacy | Sitemap
© Copyright 2018 Infoflex Connect AB