Using FDFMerge Lite Or FDFMerge
In this chapter...
...we detail the range of FDFMerge Lite and FDFMerge functions and provide practical examples. Information that is specific to FDFMerge is followed by the notation: (FDFMerge only).
- Using Command-Line Options describes the different option flags available with FDFMerge Lite and FDFMerge.
- Examples of Merging FDF files and PDF Forms presents several examples of running FDFMerge Lite and FDFMerge and guides you through the procedure of merging an FDF file with a PDF form to create a PDF document.
Example Command-Line Syntax
Listed below is an example of a simple command line for calling FDFMerge Lite or FDFMerge:
$ fdfmergeliteapp [options] -o out.pdf input.pdf input.fdf
$ fdfmergeapp [options] -o out.pdf input.pdf input.fdf
Note: Do not call the fdfmergelite or fdfmerge script from another script or application. Call fdfmergeliteapp or fdfmergeapp directly, as shown in the first example above.
Using Command-Line Options
The table below shows both general and specific command-line options for FDFMerge Lite and FDFMerge. The following sections detail the use of these options.
FDFMerge Lite & FDFMerge options — summary
| Type | Option | Parameter | Description |
|---|---|---|---|
| Specific | -x | Input is an XFDF file, not an FDF file. | |
| -s | Replace all fields with stamps. | ||
| -reverse | Make FDF file come first followed by multiple PDF files. | ||
| -norebuild | Don't rebuild appearances. | ||
| -f | <FormInfo.txt> | Field information file for partial field replacement (FDFMerge only). | |
| -cmds | <CommandFile.txt> | Process multiple commands and files. Compatible with -l, -p, -r, -h or -help and -n. |
|
| General | -l | <logFile> | Write progress information or errors to log file. |
| -p | Display progress messages to console or screen. | ||
| -n | Do not write anything to the console or screen. | ||
| -r | <RegNum> | Pass registration number to FDFMerge Lite or FDFMerge. | |
| -v | Display version information. | ||
| -h or -help |
Display usage information. | ||
| -i | Save using an incremental save. | ||
| -w | Linearize the file upon save. | ||
| -optimize | Optimize the output file to try to reduce file size | ||
| -iso32000 | Set file for ISO 32000 compliance (PDF 1.7) | ||
| -o | <outFile.pdf> | Save output to a new file or directory |
General options — detailed
Refer to General options — detailed for details on the general options.
Specific options — detailed
-x — Input is an XFDF file (required)
Specifies that the input data file is an XFDF file, which is an XML version of an FDF file. Required if using an XFDF input file instead of an FDF file.
-s — Replace all fields with stamps (optional)
Flattens a form, changing active form fields into static text or images. For more information about how this works, see To merge and flatten, or to merge and not flatten.
-reverse — Make FDF file come first followed by multiple PDF input files (optional)
Processes multiple PDF forms with a single FDF file. An output directory must be used with -reverse. FDFMerge Lite and FDFMerge normally require the PDF form before the FDF file on the command line. However, when running multiple forms with the same FDF file, the FDF file must appear before the PDF form on the command line. For example, the following command:
$ fdfmergelite [options] -o ./merged -reverse fdf_filename.fdf pdf_filename1.pdf pdf_filename2.pdf...pdf_filename3.pdf
$ fdfmerge [options] -o ./merged -reverse fdf_filename.fdf pdf_filename1.pdf pdf_filename2.pdf...pdf_filename3.pdf
Merges the same form information into each PDF file, and writes the new files to the ./merged directory using the same PDF filename as the input PDF form file. Required when running multiple PDFs.
Note: FDFMerge Lite or FDFMerge will not create a directory, so be sure the directory for the output files exists.
-norebuild — Don't rebuild appearances (optional)
Specifies that Acrobat, rather than FDFMerge Lite or FDFMerge builds the form appearances for an output PDF form. Use this option when merging text fields containing formats or calculations to have Acrobat keep the formatting.
Note: The -norebuild flag will be ignored if used with the -s flag.
-f <FormInfo.txt> — Field information file for field customization (optional) — FDFMerge only
Specifies that a FormInfo file be used for flattening, customizing form fields, or stamping them with JPEG, TIF or PDF images.
More information on merging and flattening form fields can be found below in To merge and flatten, or to merge and not flatten. For information on available parameters and how to put together a FormInfo file, see FormInfo Files.
Note: All form fields described in the FormInfo file are flattened in the output PDF document, whether or not the -s option (described below) is used.
To merge and flatten, or to merge and not flatten, and the FormInfo file — FDFMerge only
The results of using the -s option can vary if you also specify a FormInfo file. See flattening variations in the table below describes the different scenarios (see FormInfo Files).
Flattening variations
| -s | -f FormInfo file | Result |
|---|---|---|
| ✔ | All fields are flattened, and the original file formatting is retained. | |
| ✔ | Only those form fields specified in the FormInfo file are flattened. Fields that are not specified remain active. (FDFMerge only) |
|
| ✔ | ✔ | All fields are flattened and formatted according to FormInfo file specifications, if available. Fields without customization information in the FormInfo file maintain their original formatting. (FDFMerge only) |
Note: See Notes on JavaScript and Formatting Fields for detailed information on formatting fields in the FDF file that will be flattened.
-cmds <CommandFile.txt> — Allows you to process a collection of files at one time
To process multiple commands quickly and efficiently, use the -cmds <filename> option. The file specified by -cmds, the commands file, should contain one or more single line commands. Each command is just like an ordinary FDF Merge Lite or FDFMerge command-line without the executable name. The commands file does not support wildcards in filenames. The following is an example of command-line syntax when running with -cmds:
$ fdfmergeliteapp -p -l logfile.txt -cmds CommandFile.txt
$ fdfmergeapp -p -l logfile.txt -cmds CommandFile.txt
CommandFile.txt contains a list of commands for FDFMerge to process. An example of a CommandFile.txt file:
-p -optimize -f /appligent/fdfmerge/samples/testfiles/testfile1.txt -o /appligent/fdfmerge/samples/testfiles/outfile1.pdf /appligent/fdfmerge/samples/testfiles/testfile.pdf /appligent/fdfmerge/samples/testfiles/testfile.fdf
-p -x -o /appligent/fdfmerge/samples/testfiles/outfile2.pdf /appligent/fdfmerge/samples/testfiles/testfile.pdf /appligent/fdfmerge/samples/testfiles/testfile.xfdf
-p -w -x
-f /appligent/fdfmerge/samples/healthform/healthform3.txt -o /appligent/fdfmerge/samples/healthform/outfiles3.pdf /appligent/fdfmerge/samples/healthform/healthform.pdf /appligent/fdfmerge/samples/healthform/healthform.xfdf
Examples of Merging FDF Files and PDF Forms
You're ready to start merging FDF data files and PDF forms. Before you begin, remember these important points about FDFMerge Lite and FDFMerge:
For FDFMerge Lite or FDFMerge to run successfully, the PDF form file name must precede the FDF data file name on the command line unless you are running with the -reverse option.
- The order in which options are listed on the command line is not important. However, any file names associated with an option must immediately follow that option.
- The proper directory paths must be given for the fdfmergelite or fdfmerge executable and all of the files that you use.
- To prevent overwriting your original PDF file, save your output to a new file using the -o <outfile.pdf> option.
For your first merge of FDF data files and PDF forms, try using the samples included with the installation of FDFMerge Lite or FDFMerge in the samples\testfiles directory.
Basic merging data and forms on UNIX
- Make sure you're in the directory you want to be in; the examples below assume you are in the directory where FDFMerge Lite or FDFMerge is installed.
- Using the sample files try:
$ ./fdfmergelite -p -o ./samples/testfiles/out_testfile.pdf
./samples/testfiles/testfile.pdf ./samples/testfiles/testfile.fdf
$ ./fdfmerge -p -o ./samples/testfiles/out_testfile.pdf
./samples/testfiles/testfile.pdf ./samples/testfiles/testfile.fdf
In this example the -p flag shows progress, and the -o flag specifies an output file to prevent overwriting the input PDF file.
- When you press Return the following progress messages appear on your screen:
Processing : ./samples/testfiles/testfile.pdf
Open : ./samples/testfiles/testfile.fdf
Close : ./samples/testfiles/testfile.fdf
Done : ./samples/testfiles/out_testfile.pdf
fdfmerge completed successfully.
Note: If you run FDFMerge Lite or FDFMerge without -p and no errors occur, nothing is written to the screen.
- Open out_testfile.pdf to see the completed form.
Basic merging data and forms on Windows
If you are not familiar with using the command line, refer to Command Line Introduction - FDFMerge & FDFMerge Lite.
- Click the Start button.
- Go to Programs > Accessories and select Command Prompt.
- Make sure you're in the directory you want to be in; the examples below assume you are in the directory where FDFMerge Lite or FDFMerge is installed.
- Using the sample files try:
>fdfmergelite -p -o .\samples\testfiles\out_testfile.pdf .\samples\testfiles\testfile.pdf .\samples\testfiles\testfile.fdf
>fdfmerge -p -o .\samples\testfiles\out_testfile.pdf .\samples\testfiles\testfile.pdf .\samples\testfiles\testfile.fdf
In this example the -p flag shows progress, and the -o flag specifies an output file to prevent overwriting the input PDF file.
- When you press enter the following progress messages appear on your screen:
Processing : .\samples\testfiles\testfile.pdf
Open : .\samples\testfiles\testfile.fdf
Close : .\samples\testfiles\testfile.fdf
Done : .\samples\testfiles\out_testfile.pdf
fdfmerge completed successfully.
Note: If you run FDFMerge Lite or FDFMerge without -p and no errors occur, nothing is written to the screen.
- Open out_testfile.pdf to see the completed form.
More merging examples for UNIX and Windows
In the previous sections the resulting out_testfile.pdf file was a filled-in form with active form fields. Here we give a few more examples, using command-line options and FormInfo files for form flattening (or stamping).
The examples are shown in the UNIX format, which is only slightly different from the DOS format on Windows in that directories are separated by a forward-slash ( / ) in UNIX, rather than the backslash ( \ ) in Windows/DOS.
Merging data and forms with the sample FormInfo file — FDFMerge only
$ ./fdfmerge -p -o ./samples/testfiles/out_testfile.pdf -f ./samples/testfiles/testfile1.txt
./samples/testfiles/testfile.pdf ./samples/testfiles/testfile.fdf
The out_testfile.pdf file is a new form with text attributes as specified in testfile1.txt. Some form fields remain active while the fields specified in testfile1.txt are flattened.
Merging data and forms with form flattening
$ ./fdfmergelite -p -s -o ./samples/testfiles/out_testfile.pdf ./samples/testfiles/testfile.pdf ./samples/testfiles/testfile.fdf
$ ./fdfmerge -p -s -o ./samples/testfiles/out_testfile.pdf ./samples/testfiles/testfile.pdf ./samples/testfiles/testfile.fdf
The out_testfile.pdf file is a new PDF document with no active form fields; the text is stamped into the document as it appears in testfile.pdf.
Merging data and forms with FormInfo and form flattening — FDFMerge only
$ ./fdfmerge -p -o ./samples/testfiles/out_testfile.pdf -s -f ./samples/testfiles/testfile1.txt ./samples/testfiles/testfile.pdf ./samples/testfiles/testfile.fdf
The out_testfile.pdf file is a new PDF document with no active form fields; the text is stamped into the document as specified in testfile1.txt.
Merging data and forms using several options
$ ./fdfmergelite -p -l logfile.txt -o ./samples/testfiles/out_testfile.pdf -s ./samples/testfiles/testfile.pdf ./samples/testfiles/testfile.fdf
$ ./fdfmerge -p -l logfile.txt -o ./samples/testfiles/out_testfile.pdf -s -f ./samples/testfiles/testfile1.txt
./samples/testfiles/testfile.pdf ./samples/testfiles/testfile.fdf
All of the progress messages are written to logfile.txt. The out_testfile.pdf file is a new PDF document with no active form fields. The text is stamped into the document by FDFMerge Lite. FDFMerge stamps the data into the form fields and fields specified in testfile1.txt have their attributes changed to what is set in this file.