Parameter Files — XML

Introduction to AppendPDF and AppendPDF Pro | AppendPDF Pro & AppendPDF | Parameter Files — Text

Overview

We will be using the sample parameter file paramsletter.xml in the samples directory as an example throughout this chapter. The default location for AppendPDF Pro on Windows is C:\Appligent\AppendPro\ and AppendPDF is located in C:\Appligent\AppendPDF. On other platforms, it will be wherever you installed it. The paramsletter.xml AppendPDF Pro example 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 (Comparing AppendPDF Products provides an overview of the differences). Information that is specific to AppendPDF Pro will be followed by the notation: (AppendPDF Pro only). 

What is a Parameter File?

AppendPDF and AppendPDF Pro require a parameter file to specify how you want to build a new document. This chapter explains XML parameter files and Parameter Files — Text describes text parameter files:

• XML — the parameter files using XML to code parameter specifications.
• Plain text — the text parameter files used by earlier releases of AppendPDF Pro and AppendPDF. These are supported to maintain backward compatibility with existing workflows. New features will only be available using XML files.

An XML parameter file is a text file containing the XML markup that specifies how AppendPDF Pro or AppendPDF will build your new document. You can specify the name of the output file, list the files to be included in the appended document and set many other options to establish how you want the final document to look when it is opened by the end user.

The parameter file includes:

• <outputpdf> — Output File is the name (including directory path) of the new, appended file.
• <sourcepdfs> — Source Files are the documents to be used for appending, including page ranges and Table of Contents entries.
• <TOC> — Table of Contents information includes the table of contents file, alternate bookmark text, and the stamp file for the table of contents (AppendPDF Pro only).
• <coverpage> — Cover page information includes the cover page file to be used and the stamp file for the cover page (AppendPDF Pro only).
• <docinfo> — Document information is Title, Author, Subject, Keywords, and custom fields. These are viewable within Adobe Acrobat and Acrobat Reader.
• <extras> — Extras specify additional information such as how the document should open or a stamp file for the body of the document.

Building a Parameter File

Elements and structure

We use XML to describe the parameters that AppendPDF Pro and AppendPDF uses to append documents together. As we describe XML elements, there are two sections:

1. A tree view of the elements, which describes the elements and shows how they are related.
2. Examples of XML code for each element.

Content of an element table

An element table contains the following information:

• Element — The element tag.
• R — Whether the element is required (✔) or optional (blank). If the child of an optional element is marked required, it is only required if the parent is used.
• Content — what information the element contains, i.e., what it specifies. Note that an element can either contain data, or be empty. If it is empty, nothing else is needed.

Note: Empty element tags can be entered using the beginning and end tags together or by using a simpler tag placing the slash “/” after the tag name as shown below:
<tag></tag>
or
<tag/>

The element tree structure

All of the tables in the XML Parameter chapters that describe the structure of elements use notations and indents to indicate specific things about individual elements:

• The element tree structure shows the topmost element as being expanded with child elements below.
• The Level column indicates what level from the top parent element described in the table, the current child element resides.
• The notation "+" indicates the element is collapsed and is a parent which contains child elements within its structure.
• Indents are used to assist in understanding the structure levels of the elements in the table.
• When there are elements that come before the current element in the <appendparam> structure, and they are not being shown, there will be a ⇔ symbol before the element tag name in the table.
• Some parent elements contain several options. When only one of the options can be used at a time the word "OR" will appear before the element tag name in the table.

XML Parameter File Details

The XML parameter file contains content and design information for the document that will be built by AppendPDF Pro or AppendPDF. The following sections describe in detail how to build parameter files in XML format.

The Top Level Element — XML

The element <appendparam> specifies that this is an AppendPDF Pro or AppendPDF parameter file. It has one attribute, version, which should be 1.0. The table below describes the attributes of the element <appendparam>. 

Content of the <appendparam> Element

XML Code Sample

<appendparam version="1.0">
     Insert parameter specifications here
</appendparam>

The Output File — XML

The element <outputpdf> specifies the output file for the appended document. The following table lists all the elements and their attributes along with the tree view.

The table below describes the elements specifying <outputpdf>.

Contents of the <outputpdf> Element

XML Code Sample

To specify an output file, outputfile.pdf, insert the code:

<appendparam version="1.0">
   <outputpdf>
      <file>
         /fullpath/outputfile.pdf
      </file>
   </outputpdf>
<!-- . Indicates skipped sections -->
<!-- . -->
<!-- . -->
</appendparam>

File

Specifies the path and filename of the output, appended PDF file.

The Source Files — XML

The element <sourcepdfs> specifies the input files, page ranges, and Table of Contents entry text for the appended document. You can specify more than one input file. To specify multiple page ranges from one file, specify an inputpdf, using the same file, for each page range.

The table below describes the elements specifying <sourcepdfs>.

Contents of the <sourcepdfs> Element

XML Code Sample

Specifying an input file.

<appendparam version="1.0">
 <!-- .  Indicates skipped sections--> 
 <!-- . -->
 <!-- . -->
   <sourcepdfs>
      <inputpdf>
         <file>
            /fullpath/input1.pdf
         </file>
         <startpage>
            3
         </startpage>
         <endpage>
            10
         </endpage>
         <TOCEntry>
            Input File 1
         </TOCEntry>
      </inputpdf>
   </sourcepdfs>
<!-- . -->
<!-- . -->
<!-- . -->
</appendparam>

Elements for <sourcepdfs>
inputpdf

Specifies the details of an input file.

You can specify more than one file by including multiple sets of <inputpdf> tags.

file

Specifies the path and filename of an input PDF file.

startpage, endpage

Specifies the start page and end page of a range of pages to extract and append to the output document. The example above will extract pages 3 through 10 of the input document.

Specifying page ranges

The following notes apply to specifying page ranges:

TOCEntry — AppendPDF Pro only

Specifies the text to use in the Table of Contents to identify this range of pages. <TOCEntry> is only used if you include a TOC page, see Table of Contents — XML. If you want to append an <inputpdf> without an entry in the Table of Contents, use an empty <TOCEntry> tag as shown below:

<TOCEntry/>

Note: If you are using a TOC page and do not include a <TOCEntry> element for an <inputpdf>, the Title in the Document Properties of the input file will be used as the TOC entry. If the file does not have a Title set, the file name of the <inputpdf> will be used.  

Examples

For clarity, the following examples use truncated path names. We recommend that you use full path names for all files. The following examples are from the sample files included with AppendPDF Pro.

Including the entire file

To include the entire file, do not specify a page range:

<sourcepdfs>
   <inputpdf>
      <file>
         ./samples/pdfs/sample1.pdf
      </file>
   </inputpdf>
</sourcepdfs>

 To explicitly specify all pages in a file and a TOC entry

<sourcepdfs>
   <inputpdf>
      <file>
         ./samples/pdfs/sample1.pdf
      </file>
      <startpage>
         1
      </startpage>
      <endpage>
         -1
      </endpage>
      <TOCEntry>
         sample document 1
      </TOCEntry>
   </inputpdf>
</sourcepdfs>

Other examples

The following additional examples use a generic example file.

Including one page of a file

To include only page 7 of a file:

<sourcepdfs>
   <inputpdf>
      <file>
         ./samples/example.pdf
      </file>
      <startpage>
         7
      </startpage>
      <endpage>
         7
      </endpage>
      <TOCEntry>
         example document, page 7
      </TOCEntry>
   </inputpdf>
</sourcepdfs>

Including a range to the end of the file

To include from page 7 to the end of the file:

<sourcepdfs>
   <inputpdf>
      <file>
         ./samples/example.pdf
      </file>
      <startpage>
         7
      </startpage>
      <endpage>
         -1
      </endpage>
      <TOCEntry>
         example document, page 7 to end
      </TOCEntry>
   </inputpdf>
</sourcepdfs>

Including the last page only

To specify the last page when you are not sure what number it will be:

<sourcepdfs>
   <inputpdf>
      <file>
         ./samples/example.pdf
      </file>
      <startpage>
         -1
      </startpage>
      <endpage>
         -1
      </endpage>
      <TOCEntry>
         example document, last page
      </TOCEntry>
   </inputpdf>
</sourcepdfs>

Table of Contents — XML

Important! This section applies to AppendPDF Pro only. AppendPDF does not have the capability to create a Table of Contents.

The element <TOC> specifies the Table of Contents for the output document. The <TOC> element contains the following elements:

Setup Information for the <TOC>

The setup information specifies:

The table below describes the Elements for specifying setup information for <TOC>.

Contents of the <TOC> Element

XML Code Sample

<appendparam version="1.0">
 <!-- . Indicates skipped sections -->
 <!-- . -->
 <!-- . -->
   <TOC>
      <file>
         /fullpath/TOC.pdf
      </file>
      <bookmarktext>
         Alternate bookmark text
      </bookmarktext>
      <stampfile>
         /fullpath/stamptoc.txt
      </stampfile>
 <!-- . -->
 <!-- . -->
 <!-- . -->
   </TOC>
 <!-- . -->
 <!-- . -->
 <!-- . -->
</appendparam>

Elements for setup information of <TOC>

file

Specifies the path and filename of a PDF file to be used for the Table of Contents.    AppendPDF Pro will only use the first page of the Table of Contents file. It will add additional copies of the first page as needed.

The file used for the Table of Contents page should not contain any bookmarks. AppendPDF Pro adds its own bookmark. 

bookmarktext

Specifies alternate text to appear in the bookmark pane identifying the Table of Contents. The default is “Table of Contents” but you can call it anything you want.

stampfile

Specifies the path and filename of a stamp file specifically for the Table of Contents. Can be used to stamp company information and page numbers, for example, onto Table of Contents pages. Refer to Stamp Files, for more information about stamp files.

Note: Table of Contents pages, Cover pages, and body pages each use an independent stamp file. A <stampfile> listed in the <TOC> section is applied only to the TOC pages and will not affect the cover or the body pages of the output PDF.

Usage notes for the Setup Information elements of <TOC>

Example

Specifying alternate bookmark text and a stampfile:

<TOC>
   <file>
      /fullpath/TOC.pdf
   </file>
   <stampfile>
      /fullpath/tocstamp.txt
   </stampfile>
   <bookmarktext>
      TOC Page
   </bookmarktext>
 <!-- . Indicates skipped sections -->
 <!-- . -->
 <!-- . -->
</TOC> 

TOC Page Layout Elements — XML

Important! This section applies to AppendPDF Pro only. AppendPDF does not have the capability to create a Table of Contents.

The page layout options specify:

• The <pagebox> is a set of page boundaries that AppendPDF Pro uses when stamping and placing information.
• Header and footer height is measured from the top and bottom margins within the <pagebox>.
• The left and right margins within the <pagebox>.
• The page column width is the width of the column that holds the page numbers.

See the following table for detailed information on the structure of the <TOC> layout.

Contents of the <TOC> Page Layout Element

Element	Level	Pro	R	Content
<appendparam> version="1.0"	Top		✔	Topmost element, contains entire parameter spec
⇔  <TOC>	2	Pro		Table of contents information
⇔  <pagebox>	3	Pro		Specifies page box
OR  <artbox>	4	Pro		Empty: page box is art box
OR  <bleedbox>	4	Pro		Empty: page box is bleed box
OR  <cropbox>	4	Pro		Empty: page box is crop box [default]
OR  <mediabox>	4	Pro		Empty: page box is media box
OR  <trimbox>	4	Pro		Empty: page box is trim box
<headerheight>	3	Pro		Text: Specifies header height* [72 pt]
<footerheight>	3	Pro		Text: Specifies footer height* [72 pt]
<leftmargin>	3	Pro		Text: Specifies left margin* [72 pt]
<rightmargin>	3	Pro		Text: Specifies right margin* [72 pt]
<pagecolumnwidth>	3	Pro		Text: Specifies page column width* [72 pt]

     * Refer to the Table of Contents: Page layout options explained illustration below for more explanation of these measurements.

XML Code Sample

<appendparam version="1.0">
  <!-- . Indicates skipped sections -->
  <!-- . -->
  <TOC>
    <!-- . -->
    <!-- . -->
    <pagebox>
      <!-- Choose only one of the 5 options -->
      <artbox />
      <bleedbox />
      <cropbox />
      <mediabox />
      <trimbox />
      <!-- End of options -->
    </pagebox>
    <headerheight>84</headerheight>
    <footerheight>60</footerheight>
    <rightmargin>72</rightmargin>
    <leftmargin>72</leftmargin>
    <pagecolumnwidth>60</pagecolumnwidth>
    <!-- . -->
    <!-- . -->
  </TOC>
  <!-- . -->
  <!-- . -->
</appendparam>

 

Table of Contents: Page layout options explained

Elements for <TOC> page layout

pagebox

Specifies the boundaries that AppendPDF Pro measures from to determine where to place TOC elements.

artbox

Empty element that tells AppendPDF Pro to use the art box as the page box. The art box defines the extent of the page’s meaningful content as intended by the page’s creator.

bleedbox

Empty element that tells AppendPDF Pro to use the bleed box as the page box. The bleed box defines the region where the contents of the page should be clipped when creating output in a production environment. This may include any extra “bleed area” needed to accommodate the physical limitations of cutting, folding, and trimming equipment.

cropbox

Empty element that tells AppendPDF Pro to use the crop box as the page box. The crop box defines the region to which the contents of the page are to be clipped (cropped) when displayed or printed.

mediabox

Empty element that tells AppendPDF Pro to use the media box as the page box. The media box defines the maximum imageable area of the physical medium on which the page is to be printed.

trimbox

Empty element that tells AppendPDF Pro to use the trim box as the page box. The trim box defines the intended dimensions of the finished page after trimming.

Usage notes for <pagebox>

The default is <cropbox>, which will be appropriate for most applications. If the PDF has a crop box set, this will ensure that none of the TOC information you specify will fall outside the viewable area. The most common exception to this is to specify <mediabox>. The other options may be applicable if you have a complex publishing process.

headerheight

Specifies the distance, in points, from the top of the page box to the start of the Table of Contents entries. Default is 72 points (1 inch).

footerheight

Specifies the distance, in points, from the bottom of the page box to the end of the Table of Contents entries. Default is 72 points (1 inch).

leftmargin

Specifies the left margin, in points. Default is 72 points (1 inch).

rightmargin

Specifies the right margin, in points. Default is 72 points (1 inch).

pagecolumnwidth

Specifies the width of the column that holds the TOC page numbers. Default is 72 points (1 inch). You can use <pagecolumnwidth> to tighten or loosen up the space between the page numbers and the leader. See leader for more information.

Example

Refer to Table of Contents: Page layout options explained above, for an illustration example of the page layout options.

To specify some common settings:

• Default page box.
• One-quarter inch left and right margins. 
  
• 1.4 inch header to leave room for company logo.
• 3 1/3 inch footer to leave room to stamp company address.
• Approximately one-half inch page column width to hold up to 3 digits.

Insert the following code:

<TOC>
 <!-- . Indicates skipped sections -->
 <!-- . -->
 <!-- . -->
   <headerheight>
      100
   </headerheight>
   <footerheight>
      240
   </footerheight>
   <leftmargin>
      18
   </leftmargin>
   <rightmargin>
      18
   </rightmargin>
   <pagecolumnwidth>
      40
   </pagecolumnwidth>
 <!-- . -->
 <!-- . -->
 <!-- . -->
</TOC>

TOC Color Space — XML

Important! This section applies to AppendPDF Pro only. AppendPDF does not have the capability to create a Table of Contents.

The <colorspace> option specifies whether the text for the Table of Contents is grayscale or RGB color:

• Grayscale is the gray level specified.
• RGB color is the Red, Green and Blue levels specified to create a color.

The table below describes the elements for the TOC <colorspace>. 

Contents of the <colorspace> Element

Element	Level	Pro	R	Content
<appendparam> version="1.0"	Top		✔	Topmost element, contains entire parameter spec
⇔   <TOC>	2	Pro		Table of contents information
⇔  <colorspace>	3	Pro		Specifies the color space for the TOC
<devicegray>	4	Pro		Sets to grayscale
<color>	5	Pro	✔	Grayscale level (0–100)
OR
⇔  <colorspace>	3	Pro		Specifies the color space for the TOC
<devicergb>	4	Pro		Sets to RGB color
<red>	5	Pro	✔	Red level (0–255)
<green>	5	Pro	✔	Green level (0–255)
<blue>	5	Pro	✔	Blue level (0–255)

XML Code Sample

The first example uses <devicegray>, setting <colorspace> to <devicegray> and <color> to 50, which will create medium gray text in the Table of Contents.

<appendparam version="1.0">
 <!-- . Indicates skipped sections -->
 <!-- . -->
 <!-- . -->
   <TOC>
   <!-- . -->
   <!-- . -->
   <!-- . -->
      <colorspace>
         <devicegray>      
            <color>
               50
            </color>
         </devicegray>
      </colorspace>
   <!-- . -->
   <!-- . -->
   <!-- . -->
   </TOC>
<!-- . -->
<!-- . -->
<!-- . -->
</appendparam>

 

The second example uses <devicergb>, setting <colorspace> to <devicergb> and using the values of <red> 51, <green> 153, and <blue> 51, which will create medium green text in the Table of Contents.

<appendparam version="1.0">
 <!-- . Indicates skipped sections -->
 <!-- . -->
 <!-- . -->
   <TOC>
   <!-- . -->
   <!-- . -->
   <!-- . -->
      <colorspace>
         <devicergb>
            <red>
               51
            </red>
            <green>
               153
            </green>
            <blue>
               51
            </blue>
         </devicergb>
      </colorspace>
   <!-- . -->
   <!-- . -->
   <!-- . -->
   </TOC>
<!-- . -->
<!-- . -->
<!-- . -->
</appendparam>

Elements for <colorspace>

devicegray

Specifies the Table of Content entries to be grayscale.

color (required for <devicegray>)

Specifies the gray level of the TOC entries using values from 0 through 100.  The <color> value is a percentage of white, such that:

• 0 is black
• 50 is medium gray
• 100 is white

devicergb

Specifies the Table of Content entries to be in RGB color.

red (required for <devicergb>)

Specifies the red level of the TOC entries using values from 0 through 255.

green (required for <devicergb>)

Specifies the green level of the TOC entries using values from 0 through 255.

blue (required for <devicergb>)

Specifies the blue level of the TOC entries using values from 0 through 255.

Usage notes for <red>, <green>, and <blue>

If the color space is <devicergb>, then <red>, <green>, and <blue> specify the levels of each color from 0–255, such that:

Red	Green	Blue	Result
0	0	0	Black
255	0	0	Red
0	255	0	Green
0	0	255	Blue
255	255	255	White
128	128	128	Gray

16 million colors are possible with this system. You can get help choosing RGB values from graphic design software or several internet sites (for example, www.visibone.com/colorlab).

Note that red=128, green=128, and blue=128 makes gray. You can duplicate any gray color in RGB with an appropriate choice of equal red, green, and blue values. 

XML Code Samples

To specify dark gray TOC entries:

   <TOC>
   <!-- . -->
   <!-- . -->
   <!-- . -->
      <colorspace>
         <devicegray>
             <color>
                25
             </color>
         </devicegray>
      </colorspace>
   <!-- . -->
   <!-- . -->
   <!-- . -->
   </TOC>

 

The following, used in the sample parameter file, paramsletter.xml, results in dark green:

   <TOC>
   <!-- . -->
   <!-- . -->
   <!-- . -->
      <colorspace>
         <devicergb>
            <red>
               0
            </red>
            <green>
               87
            </green>
            <blue>
               44
            </blue>
         </devicergb>
      </colorspace>
   <!-- . -->
   <!-- . -->
   <!-- . -->
   </TOC>

TOC Style Elements — XML

Important! This section applies to AppendPDF Pro only. AppendPDF does not have the capability to create a Table of Contents.

The style options specify text style and layout of the text in the TOC. You can specify:

• Font file is the path and name of the PostScript Type 1 font.
• Font name is the name of the font.
• Font size is the size of the font in points.
• The leader character is the character from the end of the TOC entry text to the page number.
• The line spacing.

The table below describes the elements of <TOC> style.

Contents of the <TOC> Style Element

Element	Level	Pro	R	Content
<appendparam> version="1.0"	Top		✔	Topmost element, contains entire parameter spec
⇔   <TOC>	2	Pro		Table of contents information
⇔  <fontfile>	3	Pro		Text: Name and path of the font file. This is required when specifying a PostScript Type 1 font.
<fontname>	3	Pro		Text: Name of the font [Times-Roman]
<fontsize>	3	Pro		Text: Size of the font [14]
<leader>	3	Pro		Text: Character of the leader
<linespace>	3	Pro		Text: Specify the line spacing [3]
<appendblanklines>	3	Pro		Empty: Adds additional blank lines after TOC entry — defaults to [3] unless <linespace> is set differently

XML Code Sample

<appendparam version="1.0">
 <!-- . Indicates skipped sections -->
 <!-- . -->
 <!-- . -->
   <TOC>
   <!-- . -->
   <!-- . -->
   <!-- . -->
      <fontfile>
         /fullpath/HVL_____.pfb
      </fontfile>
      <fontname>
         Helvetica-Light
      </fontname>
      <fontsize>
         12
      </fontsize>
      <leader>
         .
      </leader>
      <linespace>
         4
      </linespace>
      <appendblanklines/>
   <!-- . -->
   <!-- . -->
   <!-- . -->
   </TOC>

 

Elements for <TOC> style

fontfile

Specifies the name and path of the font file. This is required when specifying a PostScript Type 1 font.

If you specify a PostScript Type 1 font, you must supply the font name (<fontname>), and the path and name of the font file:

• Type 1 fonts use two files, a .pfb and a .pfm file. Both files need to be in the same directory, but you specify the .pfb file for <fontfile>.
• If there is a conflict between font name and font file, the information in the font file overrides the font name.

fontname

Specifies the name of the font for the TOC text. The default is Times-Roman.

There are two types of fonts AppendPDF Pro can use:

• One of the Base 14 fonts
• A PostScript Type 1 font

The names of the Base 14 fonts are:

	• Courier		• Helvetica		• Times-Roman		• Symbol
	• Courier-Bold		• Helvetica-Bold		• Times-Bold		• ZapfDingbats
	• Courier-Oblique		• Helvetica-Oblique		• Time-Italic
	• Courier-BoldOblique		• Helvetica-BoldOblique		• Times-BoldItalic

If you use a PostScript Type 1 font, specify the PostScript name of the font. Refer to the font user documentation for the exact spelling of the font name.

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.

fontsize

Specifies the size of the font for the TOC text.  Fractional point sizes are supported  (14.5) The default is 14 points.

leader

Specifies the leader character used in the space from the end of the text to the page number.  

Usage note for <leader>

• If you do not specify a leader, long TOC entries will wrap to a new line. Consider this when choosing <linespace> or TOC entries may overlap each other.
• If you have long lines that may wrap, do not specify a leader. Long lines may be truncated with a leader specified.
• You can use <pagecolumnwidth> to tighten or loosen up the space between the page numbers and the leader. See pagecolumnwidth for more information. 

linespace

Specifies the line spacing of the TOC text. The default is 3 lines.  

Line spacing is specified as:

• 0 = bookmarks are created, but no TOC text is applied to the TOC page.
• 1 = single spacing
• 2 = double spacing
• 3 = triple spacing, and so on...

The default value is 3. Refer to the Usage note for <leader> above for more information.

appendblanklines

Adds blank lines after the last line of the TOC entry, using the value of <linespace>. Without <appendblanklines> set, AppendPDF Pro counts line spaces from the first line of the TOC entry.

For example: When <appendblanklines> is set, if a TOC entry is 3 lines, the line space count will begin after the third line; if the TOC entry is 2 lines, the line space count will begin after the second line of that entry. If <appendblanklines> is not set, the line space count always begins with the first TOC line. See the example below for an illustration.

<appendblanklines> is not set in the parameter file:

<appendblanklines> is set in the parameter file:

Use this option to control the spacing between page numbers: — <linespace> is set to 3 (default). — <appendblanklines> option is not set. — The line count starts at the first line of the TOC entry; the spacing between page numbers (first TOC lines) is consistent.

Use this option to control the spacing between TOC entries: — <linespace> is set to 3 (default). — <appendblanklines> option is set. — There are 3 lines added between each TOC entry; the line spacing between entries is consistent.

 

Examples

Specifying style

To specify the style as shown in the table above. 

      <fontname>
         Times-Roman
      </fontname>
      <fontsize>
         14
      </fontsize>
      <leader>
         .
      </leader>
      <linespace>
         3
      </linespace>

 

To specify the Type 1 Font News Gothic: 

      <fontfile>
         /fullpath/NewsGot.pfb
      </fontfile>
      <fontname>
         NewsGothic
      </fontname>
      <fontsize>
         10
      </fontsize>
      <leader>
         -
      </leader>
      <linespace>
         2
      </linespace>

The Cover Page — XML

Important! This section applies to AppendPDF Pro only. AppendPDF does not have the capability to create a cover page.

The element <coverpage> specifies a cover page to use on the appended document.  You can specify:

• A file to use as the cover page.
• A stampfile for applying stamps to the cover page.

The table below describes the elements of <coverpage>.

Contents of the <coverpage> Element

Element	Level	Pro	R	Content
<appendparam> version="1.0"	Top		✔	Topmost element, contains entire parameter spec
⇔   <coverpage>	2	Pro		Cover page information
<file>	3	Pro	✔	Text: Specifies name and path of the cover page file
<stampfile>	3	Pro		Text: Name and path of the stampfile to use

XML Code Sample

<appendparam version="1.0">
 <!-- . Indicates skipped sections -->
 <!-- . -->
 <!-- . -->
   <coverpage>
      <file>
         /fullpath/coverpage.pdf
      </file>
      <stampfile>
         /fullpath/stampcover.txt
      </stampfile>
   </coverpage>
 <!-- . -->
 <!-- . -->
 <!-- . -->
 </appendparam>

Elements for <coverpage>

file

Specifies the path and file name of a PDF file to be the cover page. A cover page file can be more than one page. The cover pages should not contain any bookmarks. AppendPDF Pro adds its own bookmark for the cover page.    

stampfile

Specifies the path and file name of a stamp file specifically for the cover page. Stamp files can be used to define stamps for customized company information for the cover page. Refer to Stamp Files for more information about stamp files.

Note: Cover pages, Table of Contents pages, and body pages each use an independent stamp file. A <stampfile> listed in the <coverpage> section is applied only to the cover pages and will not affect the TOC or the body pages of the output PDF.

Example

Specifying a cover page and a stamp file

For clarity, the following example does not use full path names. We recommend that you use full path names for all files.

<appendparam version="1.0">
 <!-- . Indicates skipped sections -->
 <!-- . -->
 <!-- . -->
   <coverpage>
      <file>
         ./samples/pdfs/lettersample.pdf
      </file>
      <stampfile>
         ./samples/stampfiles/letterstamp.txt
      </stampfile>
   </coverpage>
 <!-- . -->
 <!-- . -->
 <!-- . -->
 </appendparam>

Document Information — XML

The element <docinfo> specifies values for fields Acrobat uses in its document information feature. You can specify values for the following information fields: 

• Title
• Subject
• Author
• Keywords
• Custom

The table below describes the elements of <docinfo>.

Contents of the <docinfo> Element

Element	Level	Pro	R	Content
<appendparam> version="1.0"	Top		✔	Topmost element, contains entire parameter spec
⇔   <docinfo>	2			Document Information
<infopair>	3		✔	Specifies a key-value pair
<key>	4		✔	Text: Information field name
<value>	4		✔	Text: Information field value

XML Code Sample

<appendparam version="1.0">
 <!-- . Indicates skipped sections -->
 <!-- . -->
 <!-- . -->
   <docinfo>
      <infopair>
         <key>
             Title
         </key>
         <value>
             Using AppendPDF Pro
         </value>
      </infopair>
   </docinfo>
 <!-- . -->
 <!-- . -->
 <!-- . -->
 </appendparam>

Elements for <docinfo>

infopair

Specifies a key-value pair as described below.

key

Specifies the Document Information field to set:

• Title
• Subject
• Author
• Keywords
• Custom

You can set a single key or any combination of keys.  

value

Specifies the value of the Document Information field specified by <key>.

Usage notes for the elements of <docinfo>

Custom fields

• Custom fields can be either strings or dates.  These fields will appear in the document information window within Acrobat, and can be searched using Adobe Catalog, or retrieved using Appligent’s APGetInfo utility. 
• A string can consist of any name and text value that would add meaningful meta data information to the document.
• A date must be of the format (D:YYYYMMDDHHmmSSOHH' mm'), where: 

YYYY is the year: required
MM is the month (01-12): optional/default = 01
DD is the day (01–X1): optional/default = 01  
HH is the hour (00–2X): optional/default = 00 
mm is the minute (00–59): optional/default = 00
SS is the second (00–59): optional/default = 00
O is the relationship of local time to Universal Time (UT): optional/default = unknown
      + means local time is later than UT
      - means local time is earlier than UT
      Z means local time is UT
HH' is the absolute value of the offset from UT in hours (00–2X)  
mm' is the absolute value of the offset from UT in minutes (00–59)

• Adobe Catalog can perform boolean searches on dates, for example, finding an invoice after 2006 but before 2008.

Example

 

   <docinfo>

    <infopair>
      <key>Author</key>
      <value>Appligent, Inc.</value>
    </infopair>

    <infopair>
      <key>Title</key>
      <value>AppendPDF Pro Test</value>
    </infopair>

    <infopair>
      <key>Subject</key>
      <value>testing AppendPDF Pro with sample files</value>
    </infopair>

    <infopair>
      <key>Keywords</key>
      <value>testing AppendPDF Pro sample files</value>
    </infopair>

    <infopair>
      <key>ExtraText</key>
      <value>AppendPDF Pro document</value>
    </infopair>

    <infopair>
      <key>DocDate</key>
      <value>D:200707142X2059+04’00’</value>
    </infopair>

  </docinfo>

Extras Elements — XML

The element <extras> specifies additional attributes you may want to define for the output file. You can specify:

• Open mode — whether Acrobat will show the navigation pane with bookmarks, thumbnails, or not at all.
• Bookmark mode — how bookmarks will be displayed in the Bookmark pane.
• View mode — the zoom level at which Acrobat opens the document.
• Open to page — the page number to which you want the document to open.
• Stamp file — a stamp file to stamp any optional text or images onto the body of the document.
• Display Mode — the display properties of the Acrobat window when a document is opened.
• Layout mode — The screen layout at which Acrobat will display the document.

The table below describes the elements of <extras>.

Contents of the <extras> Element

 

Element	Level	Pro	R	Content
<appendparam> version="1.0"	Top		✔	Topmost element, contains entire parameter spec
⇔  <extras>	2			Specifies how a document should open
<openmode>	3			Specifies navigation mode in which file should open
OR  <showbookmarks>	4			Empty: Specifies that bookmarks should show
OR  <showthumbnails>	4			Empty: Specifies that thumbnails should show
OR  <shownone>	4			Empty: Specifies only the document should show
OR  <fullscreen>	4			Empty: File opens in full screen mode
<opentopage>	3			Text: Specifies page at which the file should open
<stampfile>	3	Pro		Text: Name and path of stampfile to use
<viewmode>	3			Specifies the view that the file should open in
OR  <actualsize>	4			Empty: File opens actual size
OR  <fitheight>	4			Empty: File opens so window fits full height
OR  <fitpage>	4			Empty: File opens so window fits full page
OR  <fitvisible>	4			Empty: File opens so visible area fits the window
OR  <fitwidth>	4			Empty: File opens to fit full width of window
<bookmarkmode>	3			Specifies the initial state of bookmarks
OR  <openbookmarks>	4			Empty: Show all bookmarks
OR  <closebookmarks>	4			Empty: Collapse all bookmarks
OR  <openlevel>	4			Specifies number of bookmark levels shown
<layoutmode>	3			Specifies the initial display layout mode
OR  <single>	4			Empty: One page at a time
OR  <onecolumn>	4			Empty: Pages in a continuous vertical column
OR  <twocolleft>	4			Empty: Two pages side by side, first page left
OR  <twocolright>	4			Empty: Two pages side by side, first page right
<displaymode>	3			Specifies the initial window display mode
OR  <hidetoolbar>	4			Empty: File opens with tool bar hidden
OR  <hidemenubar>	4			Empty: File opens with menu bar hidden
OR  <hidewinui>	4			Empty: File opens without window controls
OR  <fitwin>	4			Empty: Window opens resized to fit the first page
OR  <centerwin>	4			Empty: Centers document window on screen
OR  <showtitle>	4			Empty: Displays document title on title bar

XML Code Sample

<appendparam version="1.0">
 <!-- . Indicates skipped sections -->
 <!-- . -->
 <!-- . -->
   <extras>
      <stampfile>
         /fullpath/stampfile.txt
      </stampfile>
      <opentopage>
         5
      </opentopage>
      <openmode>
 <!-- Choose only one of the 4 options -->
         <showbookmarks/>
         <showthumbnails/>
         <shownone/>
         <fullscreen/>
      </openmode>
      <bookmarkmode>
 <!-- Choose only one of the 3 options -->
         <openbookmarks/>
         <closebookmarks/>
         <openlevel/>
      </bookmarkmode>
      <viewmode>
 <!-- Choose only one of the 5 options -->
         <actualsize/>
         <fitheight/>
         <fitpage/>
         <fitvisible/>
         <fitwidth/>
      </viewmode>
      <layoutmode>
 <!-- Choose only one of the 4 options -->
         <single/>
         <onecolumn/>
         <twocolleft/>
         <twocolright/>
      </layoutmode>
      <displaymode>
 <!-- Choose one or more of the 6 options -->
         <hidetoolbar/>
         <hidemenubar/>
         <hidewinui/>
         <fitwin/>
         <centerwin/>
         <showtitle/>
      </displaymode>
   </extras>
</appendparam>

 

Elements of <extras>

opentopage

The page number at which to open the document. 

stampfile — AppendPDF Pro only

Specifies the path and filename of a stamp file for the appended document.   These stamps will not be added to the cover page or the Table of Contents. 

viewmode

Specifies the zoom level when the document opens.

actualsize

The document opens at actual size.

fitheight

The document opens so the full height of the page fits into the document window.

fitpage

The document opens so the full page fits into the document window.

fitvisible

The document opens so the visible area of the page fits into the document window.

fitwidth

The document opens so the full width of the page fits into the document window.

bookmarkmode

Specifies the initial state of the document’s bookmarks in the navigation pane. 

openbookmarks

Expands the bookmark list to show all bookmarks in the navigation pane when the document is opened.  

closebookmarks

Collapses the bookmark list to show only the top level bookmarks in the navigation pane when the document is opened.

openlevel

Expands the bookmark list through level n. For example, for n=3, all bookmarks up to and including the third level are shown. The fourth and higher level bookmarks are collapsed.

layoutmode

Specifies the display page layout when the document opens.

single

Displays one page at a time.

onecolumn

Arranges the pages in a continuous vertical column.

twocolleft

Arranges two pages side by side, the first page on the left.

twocolright

Arranges two pages side by side, the first page on the right.

displaymode

Specifies the window display mode when the document opens. You can specify more than one option.

hidetoolbar

Specifies that the Acrobat tool bar will not be displayed when the document opens.

hidemenubar

Specifies that the Acrobat menu bar will not be displayed when the document opens.

hidewinui

Specifies that the Acrobat window controls will not be displayed when the document opens.

fitwin

Resizes the document window to fit the first page when the document opens.

centerwin

Centers the document window on the screen when the document opens.

showtitle

Displays the document title, rather than the file name, on the title bar and the Windows menu.

Usage notes for the elements of <extras>

Cover pages, Table of Contents pages and body pages each use an independent stamp file. Stamps listed in the Extras section are applied only to the body pages, and will not affect the cover or the TOC pages of the output PDF.

Example

The example specifies using extrasstamp.txt as the stampfile; opentopage is page 7; viewmode as fit the full document width to the window; openmode set to show bookmarks and bookmarkmode displaying 3 levels of bookmarks. Displaymode will be set to center the window on screen and show the document title in the title bar.

   <extras>
      <stampfile>
         /fullpath/extrasstamp.txt
      </stampfile>
      <opentopage>
         7
      </opentopage>
      <viewmode>
         <fitwidth/>
      </viewmode>
      <openmode>
         <showbookmarks/>
      </openmode>
      <bookmarkmode>
         <openlevel>
            3
         </openlevel>
      </bookmarkmode>
      <displaymode>
         <centerwin/>
         <showtitle/>
      </displaymode>
   </extras

Putting It All Together — XML

Testing your Parameter Files

A parameter file test should be used to make sure the Table of Contents is formatted properly, and all of the documents are being appended in the way that you expect. You can use a parameter file with one or two page documents so you can quickly check results and make small adjustments to margins, colors, line spacing, leaders, etc. You can use a source files block that consists of more than one instance of the same one page file for a very simple test. For example:

<appendparam version="1.0">
 <!-- Output file -->
   <outputpdf>
      <file>
         /outputfilepath/output.pdf
      </file>
   </outputpdf>
 <!-- Begin source files -->
   <sourcepdfs>
 <!-- First input file -->
      <inputpdf>
        <file>
           /inputfilepath/Sample1.pdf
        </file>
 <!-- First TOC entry -->
        <TOCEntry>
           Sample A
        </TOCEntry>
        </inputpdf>
 <!-- Second input file -->
        <inputpdf>
          <file>
             /inputfilepath/Sample1.pdf
          </file>
 <!-- Second TOC entry -->
        <TOCEntry>
           Sample B
        </TOCEntry>
        </inputpdf>
 <!-- End of input files -->
   </sourcepdfs>
 <!-- End of source files -->
   <TOC>
     <file>
        /tocfilepath/TOC.pdf
     </file>
   </TOC>
</appendparam>

 

This will append two /inputfilepath/Sample1.pdf files, each with a different TOC entry, and save the file as /outputfilepath/output.pdf.

Paramsletter Example

The following puts together the examples we've been using throughout this section in the file, paramsletter.xml. For clarity, the following example does not use full path names. We recommend that you use full path names for all files.

 

<appendparam version="1.0">

  <!-- Output File -->
  <outputpdf>
    <!-- Specify output file -->
    <file>./samples/paramsletter_xml.pdf</file>
  </outputpdf>
  
  <!-- Begin Source PDFs -->
  <sourcepdfs>
    <inputpdf>
      <!-- First input file -->
      <file>./samples/pdfs/sample1.pdf</file>
      <!-- Start at page 1 to end of the file -->
      <startpage>1</startpage>
      <endpage>-1</endpage>
      <!-- TOC entry for file 1 -->
      <TOCEntry>sample document 1</TOCEntry>
    </inputpdf>
    <inputpdf>
      <!-- Second input file -->
      <file>./samples/pdfs/sample2.pdf</file>
      <!-- Start at page 1 to end of the file -->
      <startpage>1</startpage>
      <endpage>-1</endpage>
      <!-- TOC entry for file 2 -->
      <TOCEntry>sample document 2</TOCEntry>
    </inputpdf>
    <inputpdf>
      <!-- Third input file -->
      <file>./samples/pdfs/sample3.pdf</file>
      <!-- Start at page 1 to end of the file -->
      <startpage>1</startpage>
      <endpage>-1</endpage>
      <!-- TOC entry for file 3 -->
      <TOCEntry>sample document 3</TOCEntry>
    </inputpdf>
    <inputpdf>
      <!-- Third input file -->
      <file>./samples/pdfs/sample4.pdf</file>
      <!-- Start at page 1 to end of the file -->
      <startpage>1</startpage>
      <endpage>-1</endpage>
      <!-- TOC entry for file 4 -->
      <TOCEntry>sample document 4</TOCEntry>
    </inputpdf>
  </sourcepdfs>
  <!-- End source PDFs -->
  
  <!-- Begin Cover Page Block -->
  <coverpage>
    <!-- Coverpage template -->
    <file>./samples/pdfs/lettersample.pdf</file>
    <!-- Stamp file for cover page -->
    <stampfile>./samples/stampfiles/letterstamp.txt</stampfile>
  </coverpage>
  <!-- End Cover Page Block -->
  
  <!-- Begin TOC Block -->
  <TOC>
    <!-- TOC template file -->
    <file>/samples/pdfs/toc.pdf</file>
    <!-- Stampfile for TOC -->
    <stampfile>./samples/stampfiles/tocstamp.txt</stampfile>
    <!-- Alternate bookmark text for TOC -->
    <bookmarktext>TOC Page</bookmarktext>
    <!-- 1.4 inches header down to beginning of TOC entries -->
    <headerheight>100</headerheight>
    <!-- 3 1/3 inches footer up to bottom of TOC entries -->
    <footerheight>240</footerheight>
    <!-- Left margin 1/4 inch -->
    <leftmargin>20</leftmargin>
    <!-- Right margin 1/4 inch -->
    <rightmargin>20</rightmargin>
    <!-- Helvetica font for TOC entries -->
    <fontname>Helvetica</fontname>
    <!-- Font size for TOC entries is 14 pt -->
    <fontsize>14</fontsize>
    <colorspace>
      <!-- Colorspace RGB -->
      <devicergb>
        <!-- RGB color is 0, 87, 44 - Dark Green -->
        <red>0</red>
        <green>87</green>
        <blue>44</blue>
      </devicergb>
    </colorspace>
    <!-- Triple spaced text -->
    <linespace>3</linespace>
    <!-- Add additional 3 lines after TOC entries -->
    <appendblanklines />
    <!-- Leader looks like this ......... -->
    <leader>.</leader>
    <!-- Width of column for TOC page numbers: about 1/2 inch -->
    <pagecolumnwidth>40</pagecolumnwidth>
  </TOC>
  <!-- End of the TOC -->
  
  <!-- Begin Info Block -->
  <docinfo>
    <!-- Specify Author as "Appligent, Inc" -->
    <infopair>
      <key>Author</key>
      <value>Appligent, Inc.</value>
    </infopair>
    <!-- Specify Title as "AppendPDF Pro Test" -->
    <infopair>
      <key>Title</key>
      <value>AppendPDF Pro Test</value>
    </infopair>
    <!-- Specify Subject as "testing AppendPDF Pro with sample files" -->
    <infopair>
      <key>Subject</key>
      <value>testing AppendPDF Pro with sample files</value>
    </infopair>
    <!-- Specify the following Keywords: testing AppendPDF Pro appending assembly -->
    <infopair>
      <key>Keywords</key>
      <value>testing AppendPDF Pro sample files</value>
    </infopair>
    <!-- Specify a custom info field of ExtraText as "AppendPDF Pro document" -->
    <infopair>
      <key>ExtraText</key>
      <value>AppendPDF Pro document</value>
    </infopair>
    <!-- Specify custom info field of DocDate -->
    <!-- as the date "July 14, 2007,11:20:56 pm" -->
    <!-- Local time 4 hours later than Universal time -->
    <infopair>
      <key>DocDate</key>
      <value>D:20000714235659</value>
    </infopair>
  </docinfo>
  <!-- End of Docinfo -->
  
  <!-- Begin Extras Block -->
  <extras>
  <!-- Zoom to fit the page when document is opened -->
    <viewmode>
      <fitpage />
    </viewmode>
    <!-- Show bookmarks in the navigation pane when the document is opened -->
    <openmode>
      <showbookmarks />
    </openmode>
  </extras>
  <!-- End of Extras information-->
  
</appendparam>
<!-- End of parameter file-->

Introduction to AppendPDF and AppendPDF Pro | AppendPDF Pro & AppendPDF | Parameter Files — Text