Parameter Files — Text
Parameter Files — XML | AppendPDF Pro & AppendPDF | Stamp Files - AppendPDF Pro
Overview
We will be using the sample parameter file, paramsletter.txt, in the samples directory as an example throughout this chapter. The default location for AppendPDF on Windows is C:\Appligent\AppendPDF\ and AppendPDF Pro is located in C:\Appligent\AppendPro. On other platforms, it will be wherever you installed it. The paramsletter.txt example, (AppendPDF Pro only), contains most of the features described in this chapter for the purpose of explanation and examples.
Note: AppendPDF does not have all the capabilities that are shown in the examples. Parameters that are specific to AppendPDF Pro will be followed by the notation: (AppendPDF Pro only).
What is a Parameter file?
To run AppendPDF Pro or AppendPDF you will need a parameter file. A text parameter file is a simple text file that contains the instructions AppendPDF Pro or AppendPDF uses to build your new document. Sample parameter files are included with the AppendPDF Pro and AppendPDF installation and are located in the samples directory.
A parameter file includes:
- The name and directory path of the new, appended PDF file
- Source file information is a list of the documents to be used for appending, including page ranges and Table of Contents (TOC) entries (AppendPDF Pro only)
- Cover page information includes the cover page file and the stamp file for the cover page (AppendPDF Pro only)
- Table of Contents information includes the TOC file, style information, and the stamp file for the TOC (AppendPDF Pro only)
- Document Info is Title, Author, Subject, Keywords which are viewable within Adobe Acrobat and Acrobat Reader
- Extras specify additional information such as how the document should open and a stamp file for the body of the document (AppendPDF Pro only)
Important! We will continue to support existing text parameter files. However, new features will only be available using XML files.
Building a Parameter File
New file name
The first line of the parameter file is the name of the new PDF file — the output file that will be created by AppendPDF or AppendPDF Pro. For example:
paramsletter.pdf
It is likely that you will be appending files that do not reside in the directory that holds AppendPDF or AppendPDF Pro. To avoid losing track of where your files are being written, we recommend that you include the full pathname for each file that you use. For example:
C:\MyDir\WorkFiles\paramsletter.pdf
The Source Files Block — Text — (required)
Following the first line of the parameter file is the list of input or source files that AppendPDF Pro or AppendPDF will use to create the new document. Before beginning the list you must enter the keyword begin_source and at the end of the list insert the keyword end_source. Files will be appended in the order that they appear in the source files list. After each filename are commas and page numbers; this is the notation that AppendPDF Pro and AppendPDF uses for specifying pages and page ranges. Specifying pages is discussed in detail below.
This is an example source file block:
begin_source
Sample1.pdf
Sample2.pdf,1,2
Sample3.pdf,1,1
Sample3.pdf,3,3
Sample4.pdf,2,4
end_source
It is important to make sure that none of your source files have names with commas in them. Since AppendPDF Pro and AppendPDF uses commas for describing page ranges, it will try to interpret any comma it sees as being a part of page information. Each parameter file can have only one source files block. Extra source blocks will be ignored.
Specifying page ranges in your source files block
In AppendPDF and AppendPDF Pro page ranges are delimited by commas. In the source files block shown above, each file has a range of pages specified. The different ways for specifying which pages you want to use are described below. When specifying pages do not insert spaces between file names and commas, or commas and numbers.
- If no pages are specified with a file, all pages from that file will be appended to the new document. For example:
Sample1.pdf
- To specify a single page to append from a file, after the file name add a comma, the page number to be appended, another comma and the same page number. This indicates that the beginning and ending page are the same, as in Sample3.pdf below:
Sample3.pdf,1,1
- To specify a range of pages place a comma after the file name, the number of the first page in the range, another comma, and the last page number of the range. The following example of Sample4.pdf specifies the range of pages 2 through 4:
Sample4.pdf,2,4
- To specify multiple, non-contiguous pages from a single document, multiple entries need to be made in the parameter file. Below, see that Sample3.pdf is listed twice, once to add page 1 and a second time to add page 3:
Sample3.pdf,1,1
Sample3.pdf,3,3
Note: This is the only way to avoid appending page 2 for this file.
- To specify all pages from a specific page in a document, list the starting page only. Appending will start from this page and go to the end of the document. The sample below will append pages 2 through the end of Sample3.pdf:
Sample3.pdf,2
- To specify that only the last page of a document be appended, use the special notation -1 as shown with Sample2.pdf below:
Sample2.pdf,-1
Note: The -1 notation for last page can be used with page ranges. As shown in the example below, the second through the last page of sample4.pdf will be appended:
sample4.pdf,2,-1
Note: If you will be including a Table of Contents, you must explicitly specify what pages in the document are to be appended — even if all pages of a document are to be used. The TOC will not recognize any files that are listed without a page range.
The Cover Block — Text — (optional)
Important! This section applies to AppendPDF Pro only. AppendPDF does not have the capability to create a Cover Page.
A cover page is a PDF document that is appended at the beginning of the final appended output. There are two approaches to cover pages:
- Supply your own ready-made cover page
- Supply a document and specify a stamp file that AppendPDF Pro will use to stamp information onto the page
Cover pages are allowed to be more than one page. Cover pages should not contain any bookmarks. AppendPDF Pro adds its own bookmark for the cover page.
Cover Page
To supply a ready-made PDF document for the cover page named lettersample.pdf, add the following information to your parameter file:
begin_coverpage
CoverPage (./samples/pdfs/lettersample.pdf)
end_coverpage
The name of the document that will be the cover page needs to be entered in parentheses after the keyword CoverPage. The Cover Page block of the parameter file must begin with begin_coverpage and end with end_coverpage.
There must be at least one space between the CoverPage keyword and the name of the cover page filename in parentheses. We recommend that you always use the full path to the PDF document used as the cover page.
Stamped Cover Page
Using a stamp file with your cover page will provide more flexibility in design. See Stamp Files to learn how to create a stamp file that will place custom text, watermarks, or page numbers on your cover page. When your stamp file is ready, include the file with the full path, in your cover page block, along with the name of the document to be used for the cover page:
begin_coverpage
CoverPage (./samples/pdfs/lettersample.pdf)
StampFile (./samples/stampfiles/letterstamp.txt)
end_coverpage
Your cover page will be stamped with information you specified in CoverStamp.txt.
The Table of Contents Block — Text — (optional)
Important! This section applies to AppendPDF Pro only. AppendPDF does not have the capability to create a Table of Contents.
The optional Table of Contents (or TOC) works similarly to the Cover Page. The user provides a blank PDF document to be used for the Table of Contents. AppendPDF Pro uses this to write the chapter headings and page numbers. The TOC block in the parameter file can specify a stamp file as in the Cover Page block. The user is able to specify how information is printed on the Table of Contents page(s): in what font, size, position and color. All text entered by AppendPDF Pro on the Table of Contents page is linked to the respective pages in the new PDF document.
The document used for the Table of Contents page must be a single-page document. If the Table of Contents needs to run on to a second or more pages, a copy will be made of the first page to accommodate the additional listings. Do not have any bookmarks in the document you use for your Table of Contents. AppendPDF Pro applies its own bookmark for these pages.
A sample Table of Contents block looks like this:
begin_TOC
TOCPage (./samples/pdfs/toc.pdf)
StampFile (./samples/stampfiles/tocstamp.txt)
BookMarkText (TOC Page)
HeaderHeight (100)
FooterHeight (240)
LeftMargin (20)
RightMargin (20)
FontName (Helvetica)
FontSize (14)
ColorSpace (DeviceRGB)
Red (0)
Blue (44)
Green (87)
LineSpace (3)
Leader (.)
PageColumnWidth (40)
end_TOC
Parameter Descriptions
TOCPage (required)
TOCPage must be specified or no Table of Contents will be generated. You should supply the full path to the PDF file you wish to use for the TOC page. The file name must be enclosed in parenthesis.
StampFile (optional)
If you would like to stamp additional information such as a watermark, copyright etc. on your Table of Contents, you may use the stamp file for this. Always use the full path to the StampFile. The stamp file name must be enclosed in parenthesis.
Note: The StampFile listed in the TOC block does not control any options for the TOC entries. These must be included in the TOC block of the parameter file.
The rest of the TOC block closely resembles the construction of a stamp item as you’ll see in the section on Stamp Files. The following sections will explain the remaining components of the TOC block.
HeaderHeight, FooterHeight, LeftMargin and RightMargin (optional)
HeaderHeight, FooterHeight, LeftMargin and RightMargin are values given in points that you can use to position your Table of Contents listing to appear as you want. AppendPDF Pro will use a default of 72 points (1 inch) if the margin parameters are omitted. The unit for the margins is points; use the conversion of 72 points to the inch to determine how you would like your margins to appear.
FontName and FontSize (optional)
FontName and FontSize are optional parameters. If you do not include these your Table of Contents will be done in the default font, Times-Roman, and the default size of 14 pt.
The FontName is the name of a Base 14 font (sometimes called a system font). With any font that you use, make sure that you enter the name of the font properly, with the correct spelling, hyphenation and capitalization. The Base 14 fonts are as follows:
| • Courier | • Helvetica | • Times-Roman | • Symbol |
| • Courier-Bold | • Helvetica-Bold | • Times-Bold | • ZapfDingbats |
| • Courier-Oblique | • Helvetica-Oblique | • Time-Italic | |
| • Courier-BoldOblique | • Helvetica-BoldOblique | • Times-BoldItalic |
FontFile (optional)
If you would like to use a font other than a Base 14 font, it is possible to use an additional parameter, FontFile, to add a PostScript Type 1 font. To use one of these fonts you will need to give the font’s name in FontName and the location of the font’s .pfb file in FontFile.
Fonts consist of two files: one with a .pfm extension and one with a .pfb extension. Both of these files need to be in the same directory for AppendPDF Pro to access the font properly but only the .pfb file is listed in the parameter file. The PostScript name of the font will need to be entered in FontName. More information on fonts and font files is presented in the section on Stamp Files, Font Specifications.
If there is a conflict between FontName and FontFile, the information in FontFile overrides that in FontName.
Note: You cannot use TrueType or OpenType fonts with AppendPDF Pro. If you use a font other than a Base 14 font, it must be a PostScript Type 1 font.
ColorSpace (optional)
ColorSpace should be either DeviceGray or DeviceRGB. Use DeviceRGB if you will be using color values and DeviceGray if you will be using a shade of gray. DeviceGray works in conjunction with the Color keyword and DeviceRGB works in conjunction with the Red, Green and Blue keywords.
In AppendPDF Pro, you can specify the color of the TOC text by setting the Red, Green and Blue values, allowing you to use virtually any color you like. See the section on Stamp Files, Stamp Color for more details on choosing colors.
Color (optional)
If you choose ColorSpace to be DeviceGray, use the Color keyword to specify the shade of gray to be used. Color is measured as a percentage of white within black — a value between 0 and 100 where 0 is black and 100 is white. A Color of 95, therefore would be a very light gray, and a Color of 15 would be a dark gray.
ColorSpace is an optional parameter. If you omit it, TOC entries will be written in black (DeviceGray and Color of 0).
Red, Green and Blue (required with ColorSpace - DeviceRGB)
Red, Green and Blue can each be any value from 0 to 255, depending on how much of each color you need to create your desired color. More on colors can be found in the section on Stamp Files, Stamp Color.
LineSpace (optional)
LineSpace allows you to make some modification to the space that appears between each entry on the Table of Contents page. If you do not use the LineSpace parameter, AppendPDF Pro will use the default of 3. LineSpace can be any number as long as it is an integer. The number corresponds to the number of carriage returns between entries.
Leader (optional)
Leader will place a leading character (a dot, for example) from the end of the text of the Table of Contents entry to the page number for that entry. A Leader will help your reader join the TOC entry to its page number. The most common leader character is a dot (.), but you are free to use any other ASCII character (+, *, -, _, etc.)
Note: If a Leader is not specified, long TOC entries will wrap to a new line. Consider this when choosing LineSpace or TOC entries may overlap each other. If a Leader is specified, lines will not wrap in the TOC entries and long lines will be truncated.
PageColumnWidth (optional)
PageColumnWidth specifies the width of the column for page numbers in the TOC listing. The width is defined in points and can be modified to increase or decrease the space between the page numbers and the leader characters. If PageColumnWidth is not used, a width of 72 points is used as the default. Make sure the column is set wide enough to enclose the largest page number a TOC entry will have, however, for aesthetic reasons we suggest not using columns larger than 75 points.
How to Change a Source Files Block to Make a Table of Contents
If you will be including a Table of Contents with your appended file you need to specify both the first and last page to be used in the document, then add a TOC entry at the end of each line in your source files block. This will be the heading used on the TOC page. For instance:
begin_source
sample1.pdf,1,-1,(sample document 1)
sample2.pdf,1,-1,(sample document 2)
sample3.pdf,1,-1,(sample document 3)
sample4.pdf,1,-1,(sample document 4)
end_source
The above example is a source files block that will make entries in a Table of Contents if there is a TOC block in the parameter file. The text in parentheses will be used on the TOC page. There should be no spaces between items on the source files block line. It is fine to have spaces within the TOC entry text, as shown above.
After the page numbers are specified, insert another comma to separate page numbers from the TOC entry text, then add the text in parentheses. With the block specified as shown in the example above, the result will look something like this:
sample document 1
sample document 2
sample document 3
sample document 4
You may vary the appearance by choosing different fonts, point sizes, leaders, colors and line spacings.
All of the entries will be active links to their respective pages.
Note: When using TOC entries in your source files block, take care with how you use the -1 notation to indicate “last page.” In a plain source files block (without TOC entries) it is possible to enter sample1.pdf,-1 and the last page will be appended. In the TOC entry the notation must be modified slightly and -1 must be added twice (a source file must always have the beginning and end pages specified when a TOC entry is to be used):
sample1.pdf,-1,-1,(A "last page" TOC entry)
Inserting All Pages in a Document and Making a TOC Entry
The pages of a document must be clearly stated for the Table of Contents to recognize it and add it to the Table of Contents page. If you would like all pages from your document to be in the appended document you will need to tell AppendPDF Pro to insert all pages from page 1 to the last page:
sample1.pdf,1,-1,(All pages appended)
If you know that the particular document has 50 pages you could tell AppendPDF Pro to insert pages 1 to 50, that will also append all the pages of the document:
filename.pdf,1,50,(All pages appended)
Example of a Finished Table of Contents Page
The figure below explains the Table of Contents page layout options.
The Document Information Block — Text — (optional)
Within Adobe Acrobat there is a feature to view information about a file by choosing Document Properties from the File menu. With AppendPDF Pro and AppendPDF it is possible to populate certain fields of the Document Info with the parameter file. A sample of a Document Properties dialog screen from Acrobat is shown below.
Document Info screen
Below is a Document Info screen in Acrobat for a Sample PDF, also called Document Properties.
Title, Author, Subject, and Keywords are fields in the Document Info screen as shown in the figure above. These are the fields that can be modified by AppendPDF Pro and AppendPDF. Enter values in the parameter file as you would like to see them appear when you call up the Document Properties in Acrobat. The fields Title, Subject and Author refer to information specific to that document. Keywords (this is Acrobat’s Keywords, not to be confused with the many other references to keywords in this manual) are usually simple words used for sorting and grouping (December, ProjectX, personal, etc.) and are useful for those who will be indexing their documents with Acrobat Catalog and would like to improve searching efficiency. More about indexing can be found in the Acrobat Guide or the Reader Guide if you don’t have the full version of Acrobat. (Either guide can be found under the Help menu of its respective application.)
To specify document information in a parameter file, list the name of the field followed by its value in parentheses. Before beginning this section the keyword begin_info must be added to the parameter file. At the end of the list close the section with the end_info keyword:
begin_info
Title (AppendPDF Pro Test)
Subject (testing AppendPDF Pro with sample files)
Author (Appligent, Inc.)
Keywords (testing AppendPDF Pro sample files)
end_info
There is no set number of tabs or spaces that need to appear between the field name and the value in parentheses, as long as there is at least one tab or space. Also, if you do not want to include a Document Info field (for example, if you want Title and Subject, but not Author and Keywords) make sure that keyword is not listed in the Document Info block. Items listed with empty parentheses will cause AppendPDF or AppendPDF Pro to fail.
Make sure that all Document Info keywords (Title, Subject, Author, Keywords) are spelled correctly or AppendPDF and AppendPDF Pro will treat them as custom strings. Custom strings are discussed in the next section.
Optional Custom Information to Add within Document Info
AppendPDF and AppendPDF Pro support two custom field types: strings and dates. These can be added within the Document Info block of the AppendPDF or AppendPDF Pro parameter file which saves them in the keywords section of the Document Properties. The keywords can then be indexed with Acrobat Catalog.
The name of a custom string can be anything you want. Give it any name that will have meaning to you and/or be easy for you to remember. For example:
String1 (This file created by AppendPDF Pro)
or
ExtraText (AppendPDF Pro document)
Custom dates need to conform to the format D:YYYYMMDDHHMMSS. Acrobat Catalog allows dates to be searched using boolean operators. You can tell Catalog to find, for example, invoices whose date is greater than 1999 and less than 2000. A custom date in the Document Info block of the parameter file can be entered as:
DocDate (D:20070714235659)
This example indicates a date of 14 July 2007 with a time of 23:56:59.
The Extras Block — Text — (optional)
The Extras block is used to apply stamps to the body of an appended document. You can add a watermark, company logo, page numbers etc. Extras stamps will not be applied to Cover or Table of Contents pages. One stamp file can be used in the Extras block. There is no limit to the number of stamp items in the file. Stamp Files provides full instructions for creating stamp files.
Cover pages, Table of Contents pages, and appended pages each use an independent stamp file. Stamps listed in the Extras block are to be applied solely to the appended pages of the output PDF and will not affect the cover or TOC pages.
The Extras block in your parameter file is constructed as follows:
begin_extras
StampFile (./samples/stampfiles/ExtraStamps.txt)
end_extras
As with the other parts of the parameter file (except for the Source Files Block) make sure there is at least one space or tab separating the keyword StampFile from the value in parentheses. The extras block must begin with begin_extras and end with end_extras.
Putting It All Together — Text
Adding Comments
Comments in your parameter file are lines of text that you don’t want to be read by AppendPDF Pro or AppendPDF. They can be either notes to yourself or descriptions of what something does or is used for, which can be useful if others will be accessing the file. Additionally, comments can be used for testing or debugging. You may want to prevent a file from being used in the source list, instead of deleting and retyping the name of the file you can simply “comment it out”. Comments start with the hash or number symbol: # and must be placed at the beginning of a line:
#This is a comment in my parameter file.
The following is an incorrect comment:
begin_source #beginning of the file list
Note: AppendPDF Pro or AppendPDF reads the first line of a parameter file as the name to call the new, appended document. Therefore, if a comment is on the first line of a parameter file and is not preceded by a #, AppendPDF Pro or AppendPDF will think it is the name for the output file. There will be no error messages generated during processing and the output file name will be the text of the comment and it will be written to the AppendPDF Pro or AppendPDF directory. The file will not have a .pdf extension. Remember the # before all comments.
Complete Parameter File Example
Now that we have gone through all of the pieces of a parameter file, we show one in its entirety. This example is almost the same as the sample paramscomplete.txt parameter file that comes with your copy of AppendPDF Pro. The example below uses all the parameter options.
Note: AppendPDF does not support all of the options in this example, however there are two example files located in the Samples directory where you installed AppendPDF. They are parameters.txt and tutorial.txt.
#Complete Parameter file for use with AppendPDF Pro with a cover letter
#Name for the new, appended file
./samples/paramsletter.pdf
#List of files and pages for appending with text for Table of Contents
begin_source
./samples/pdfs/sample1.pdf,1,-1,(sample document 1)
./samples/pdfs/sample2.pdf,1,-1,(sample document 2)
./samples/pdfs/sample3.pdf,1,-1,(sample document 3)
./samples/pdfs/sample4.pdf,1,-1,(sample document 4)
end_source
#Cover page block
begin_coverpage
CoverPage (./samples/pdfs/lettersample.pdf)
StampFile (./samples/stampfiles/letterstamp.txt)
end_coverpage
#Table of Contents block
begin_TOC
TOCPage (./samples/pdfs/toc.pdf)
StampFile (./samples/stampfiles/tocstamp.txt)
BookMarkText (TOC Page)
HeaderHeight (100)
FooterHeight (240)
LeftMargin (20)
RightMargin (20)
FontName (Helvetica)
FontSize (14)
ColorSpace (DeviceRGB)
Red (0)
Blue (44)
Green (87)
LineSpace (3)
Leader (.)
PageColumnWidth (40)
end_TOC
#document info block
begin_info
Title (AppendPDF Pro Test)
Subject (testing AppendPDF Pro with sample files)
Author (Appligent, Inc.)
Keywords (testing AppendPDF Pro sample files)
ExtraText (AppendPDF Pro document)
DocDate (D:20000714235659)
end_info
#Extras block for Stamp Files
begin_extras
Open_Mode (ShowBookmarks)
View_Mode (FitPage)
end_extras
#End of parameter file
The parameter file is a text document which requires the new file name and the list of documents to append. The document information is optional. The Cover page, TOC, and Extras blocks are also optional and used only with AppendPDF Pro.
When this example file is run with AppendPDF Pro, the user will get an output file called appendprocomplete.pdf that contains all of the pages listed in the Source files block of the parameter file.
When File > Document Properties or File > Properties is selected in Acrobat, the Title, Subject, Author, and Keywords fields will be populated with the information as shown in the Document Info block of the sample parameter file. A custom string and date have been added for searching with Acrobat Catalog.
The pages of the appended documents (not the cover or the table of contents) will be stamped by the stamp file listed in the Extras block.
Parameter Files — XML | AppendPDF Pro & AppendPDF | Stamp Files - AppendPDF Pro