Parameter Files — XML

AppendPDF & AppendPDF Pro User Guide

In this chapter...

...we will go through what you need to know about building XML parameter files for use with AppendPDF Pro and AppendPDF.

• What is a parameter file? — provides a brief overview of parameter files in general and XML parameter files in particular.
• Building a parameter file — lists in detail all of the sections of a parameter file and describes how to build each part.
• Putting It All Together — describes how to put all the sections together for both a simple parameter file and a complex one that uses all the options.

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\, (AppendPDF Pro only), and AppendPDF is located in C:\Appligent\AppendPDF. On other platforms, it will be wherever you installed it.  The paramsletter.xml AppendPDF Pro 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.  XML code that is specific to AppendPDF Pro will be distinguished with green text followed by a notation: (AppendPDF Pro only).

For more information about XML and the notation we use in this chapter, refer to Introduction to XML.

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 —  parameter files using XML to code parameter specifications.
• Plain text —  the text parameter files used by previous 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:

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

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 three sections:

1. A tree view of the elements, which describes the elements and shows how they are related.
2. The DTD entity, for advanced users.
3. The XML code itself.

We provide DTD definitions for elements and examples of XML code for each of the elements.

The following sections describe in detail how to build parameter files in XML format.

The XML parameter file contains content and design information for the document that will be built by AppendPDF Pro or AppendPDF.   The following are sections that are explained in detail:

Content of an element
The tree structure
The output file
The source files
Table of Contents (AppendPDF Pro only)
Table of Contents — page layout (AppendPDF Pro only)
Table of Contents — colorspace (AppendPDF Pro only)
Table of contents — style (AppendPDF Pro only)
Coverpage (AppendPDF Pro only)
Document information
Extras
Putting It All Together

Content of an element

An element contains the following information:

• Element — The element tag.
• R — Whether the element is required (X) or optional (blank). If the child of an optional element is marked required, it is only required if the parent is used.
• C — The cardinality of the element as expressed in the DTD. The cardinality is defined as the number of elements in a given set.
• 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 table below describes the meaning of cardinality of elements.

Cardinality of elements

The tree structure

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

• The element tree structure shows the top most 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 that 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 be before the element tag name in the table..

The top level element <appendparam>

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 of <appendparam>. 

Content of the <appendparam> element

DTD Elements

<!ELEMENT appendparam (outputpdf, sourcepdfs, (coverpage | TOC | docinfo | extras)*)>
<!ATTLIST appendparam version NMTOKEN "1.0">

XML Code Sample

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

Specifying the output file <outputpdf>

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.

Note: For clarity, the following examples may not use full path names. We recommend that you use full path names for all files.

The table below describes the Elements specifying <outputpdf>.

Contents of the <outputpdf> element

DTD Elements

<!ELEMENT outputpdf (file)>
<!ELEMENT file (#PCDATA)>

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>

Element for <outputpdf>

File

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

Specifying the source files <sourcepdfs>

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

DTD Elements

<!ELEMENT sourcepdfs (inputpdf+)>
<!ELEMENT inputpdf (file, (startpage | endpage | TOCEntry)*>
<!ELEMENT file (#PCDATA)>
<!ELEMENT startpage (#PCDATA)>
<!ELEMENT endpage (#PCDATA)>
<!ELEMENT TOCEntry (#PCDATA) >

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 is for APPENDPDF PRO only -->
         <TOCEntry>
            Input File 1
         </TOCEntry>
      </inputpdf>
   </sourcepdfs>
<!-- . -->
<!-- . -->
<!-- . -->
</appendparam>

Elements for <sourcepdfs>

Inputpdf

Specifies the details of an input file.

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 X through 10 of the input document.

TOCEntry — AppendPDF Pro only

Specifies the text to use in the Table of Contents to identify this range of pages. The TOCEntry is only used if you include a TOC page, see Specifying the Table of Contents <TOC> (AppendPDF Pro only). 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 TOCEntry.  If the file does not have a Title set, the filename of the inputpdf will be used.

Usage notes for the elements of <sourcepdfs>

Specifying input files

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

Specifying page ranges

The following notes apply to specifying page ranges:

• If you do not specify a page range, the entire file will be appended.
• You can specify multiple page ranges by specifying the same file in multiple instances of <inputpdf>. For each instance, specify one of the required ranges in a <startpage> and <endpage> set.
• To specify one page, make the value of <startpage> and <endpage> the same.
• To specify from a particular page to the end, use only the <startpage> tag.
• You can specify the last page of a document using “-1”. This is especially helpful if the number of pages in a document may change.

Examples

For clarity, the following examples may not use full 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 is for APPENDPDF PRO only -->
      <TOCEntry>
         sample document 1
      </TOCEntry>
   </inputpdf>
</sourcepdfs>

Other options

The following options are not in the sample files, they are shown as further examples.

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 is for APPENDPDF PRO only -->
       <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 is for APPENDPDF PRO only -->
      <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 is for APPENDPDF PRO only -->
      <TOCEntry>
         example document, last page
      </TOCEntry>
   </inputpdf>
</sourcepdfs>

Specifying the Table of Contents <TOC> — AppendPDF Pro only

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

• Setup information — The PDF source file for the TOC, alternate bookmark text and optional stamp file to use on the TOC pages.
• Page layout — Page Box and margins.
• Colorspace — Grayscale or RGB color.
• Style — Font, text layout, and leader information.

Setup Information for the <TOC> — AppendPDF Pro only

The setup information specifies:

• The PDF file AppendPDF Pro uses for the TOC.
• Alternate bookmark text is used to identify the Table of Contents in the bookmark pane other than “Table of Contents.”
• A stamp file to stamp any optional text or images onto the TOC.

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

Contents of the <TOC> element — AppendPDF Pro only

DTD Elements

<!ELEMENT TOC (file, (bookmarktext | stampfile | pagebox | headerheight | footerheight |
leftmargin | rightmargin | pagecolumnwidth | colorspace | fontfile | fontname | fontsize | leader |
linespace | appendblanklines)*)>
<!ELEMENT file (#PCDATA)>
<!ELEMENT stampfile (#PCDATA)>
<!ELEMENT bookmarktext (#PCDATA)>

XML Code Sample

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

Elements for Setup Information of <TOC> — AppendPDF Pro only

file — AppendPDF Pro only

Specifies the path and filename of a PDF file to act as a template for the Table of Contents.

bookmarktext — AppendPDF Pro only

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 — AppendPDF Pro only

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.

Usage notes for the Setup Information elements of <TOC> — AppendPDF Pro only

• 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.
• All text entered onto the Table of Contents by AppendPDF Pro is linked to the respective pages in the new document.
• Table of Contents pages should not contain any bookmarks. AppendPDF Pro adds its own bookmarks.
• Cover pages, Table of Contents pages and body pages each use an independent stamp file. Stamps listed in the TOC section are applied only to the TOC pages.
• If the TOCEntry is blank in the parameter file, the title of the PDF file is used as the bookmark name. If a title is not set in the document, then the filename is used.

Examples — AppendPDF Pro only

Specifying alternate bookmark text and a stampfile

 <!-- TOC is for APPENDPDF PRO only -->
<TOC>
   <file>
      /fullpath/TOC.pdf
   </file>
   <stampfile>
      /fullpath/tocstamp.txt
   </stampfile>
   <bookmarktext>
      TOC Page
   </bookmarktext>
 <!-- . Indicates skipped sections -->
 <!-- . -->
 <!-- . -->
</TOC>

Specifying the Table of Contents <TOC> Page Layout — AppendPDF Pro only

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 — AppendPDF Pro only

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

DTD Elements

<!ELEMENT TOC (file, (bookmarktext | stampfile | pagebox | headerheight | footerheight |
leftmargin | rightmargin | pagecolumnwidth | colorspace | fontfile | fontname | fontsize | leader |
linespace | appendblanklines)*)>
<!ELEMENT pagebox (mediabox | cropbox | artbox | trimbox | bleedbox)>
<!ELEMENT mediabox EMPTY> <!ELEMENT cropbox EMPTY>
<!ELEMENT artbox EMPTY> <!ELEMENT trimbox EMPTY>
<!ELEMENT bleedbox EMPTY>
<!ELEMENT headerheight (#PCDATA)> <!ELEMENT footerheight (#PCDATA)>
<!ELEMENT leftmargin (#PCDATA)> <!ELEMENT rightmargin (#PCDATA)>
<!ELEMENT pagecolumnwidth (#PCDATA)>

XML Code Sample — AppendPDF Pro only

<appendparam version="1.0">
 <!-- . Indicates skipped sections -->
 <!-- . -->
 <!-- TOC is for APPENDPDF PRO only -->
   <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 (AppendPDF Pro only)

Elements for <TOC> Page Layout — AppendPDF Pro only

pagebox (AppendPDF Pro only)

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

artbox (AppendPDF Pro only)

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 (AppendPDF Pro only)

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 (AppendPDF Pro only)

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.

This is the default value.

mediabox (AppendPDF Pro only)

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 (AppendPDF Pro only)

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.

headerheight (AppendPDF Pro only)

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 (AppendPDF Pro only)

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 (AppendPDF Pro only)

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

rightmargin (AppendPDF Pro only)

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

pagecolumnwidth (AppendPDF Pro only)

Specifies the width of the column that holds the TOC page numbers. Default is 72 points (1 inch).

Usage notes for the elements of <TOC> Page Layout — AppendPDF Pro only

Specifying the page box — AppendPDF Pro only

The default is the <cropbox>, this 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.

Specifying margin — AppendPDF Pro only

The following notes apply to specifying margins:

• Margin distances are specified in points. There are 72 points per inch.
• <pagecolumnwidth> can be used to tighten or loosen up the space between the page numbers and the leader. See leader for more information.

Examples — AppendPDF Pro only

Refer to See Table of Contents: Page layout options explained , for more information about 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 is for APPENDPDF PRO only -->
<TOC>
 <!-- . Indicates skipped sections -->
 <!-- . -->
 <!-- . -->
   <headerheight>
      100
   </headerheight>
   <footerheight>
      240
   </footerheight>
   <leftmargin>
      18
   </leftmargin>
   <rightmargin>
      18
   </rightmargin>
   <pagecolumnwidth>
      40
   </pagecolumnwidth>
 <!-- . -->
 <!-- . -->
 <!-- . -->
</TOC>

Specifying the Table of Contents <TOC> Colorspace — AppendPDF Pro only

The colorspace option specifies whether the text for the TOC 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 <TOC> Colorspace.

Contents of the <TOC> Colorspace element — AppendPDF Pro only

DTD Elements

<!ELEMENT TOC (file, (bookmarktext | stampfile | pagebox | headerheight | footerheight |
leftmargin | rightmargin | pagecolumnwidth | colorspace | fontfile | fontname | fontsize | leader |
linespace | appendblanklines)*)>
<!ELEMENT colorspace (devicergb | devicegray)>
<!ELEMENT devicergb (red, green, blue)>
<!ELEMENT red (#PCDATA)>
<!ELEMENT green (#PCDATA)>
<!ELEMENT blue (#PCDATA)>
<!ELEMENT devicegray (color)>
<!ELEMENT color (#PCDATA)>

XML Code Sample — AppendPDF Pro only

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

<appendparam version="1.0">
 <!-- . Indicates skipped sections -->
 <!-- . -->
 <!-- . -->
  <!-- TOC is for APPENDPDF PRO only -->
   <TOC>
   <!-- . -->
   <!-- . -->
   <!-- . -->
      <colorspace>
         <devicegray>      
            <color>
               50
            <color>
         <devicegray>
      <colorspace>

The second example uses <devicergb>, setting the 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 is for APPENDPDF PRO only -->
   <TOC>
   <!-- . -->
   <!-- . -->
   <!-- . -->
      <colorspace>
         <devicergb>
            <red>
               51
            <red>
            <green>
               153
            </green>
            <blue>
               51
            </blue>
         <devicergb>
     <colorspace>

Elements for <TOC> Colorspace — AppendPDF Pro only

devicegray — AppendPDF Pro only

Specifies the Table of Content entries to be grayscale.

color (AppendPDF Pro only)

Specifies the gray level of the TOC entries. Grayscale level (0-100).

devicergb — AppendPDF Pro only

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

red AppendPDF Pro only)

Specifies the red level of the TOC entries. Red level (0-255).

green AppendPDF Pro only)

Specifies the green level of the TOC entries. Green level (0-255).

blue AppendPDF Pro only)

Specifies the blue level of the TOC entries. Blue level (0-255).

Usage notes for the elements of <TOC> Colorspace — AppendPDF Pro only

If the colorspace is <devicegray>, <color> specifies the percentage of white:

• 0 would be black.
• 50 would be medium gray.
• 100 would be white.

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

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 appropriate choice of equal values.

XML Code Samples — AppendPDF Pro only

To specify dark gray TOC entries:

 <!-- TOC is for APPENDPDF PRO only -->
   <TOC>
   <!-- . -->
   <!-- . -->
   <!-- . -->
      <colorspace>
         <devicegray>
             <color>
                25
             </color>
          </devicegray>
       </colorspace>
   <!-- . -->
   <!-- . -->
   <!-- . -->
   </TOC>

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

 <!-- TOC is for APPENDPDF PRO only -->
   <TOC>
   <!-- . -->
   <!-- . -->
   <!-- . -->
      <colorspace>
         <devicergb>
            <red>
               0
            </red>
            <green>
               87
            </green>
            <blue>
               44
            </blue>
         </devicergb>
      </colorspace>
   <!-- . -->
   <!-- . -->
   <!-- . -->
   </TOC>

Specifying the Table of Contents <TOC> Style — AppendPDF Pro only

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 — AppendPDF Pro only

DTD Elements

<!ELEMENT TOC (file, (bookmarktext | stampfile | pagebox | headerheight | footerheight |
leftmargin | rightmargin | pagecolumnwidth | colorspace | fontfile | fontname | fontsize | leader |
linespace | appendblanklines)*)>
<!ELEMENT fontfile (#PCDATA)>
<!ELEMENT fontname (#PCDATA)>
<!ELEMENT fontsize (#PCDATA)>
<!ELEMENT leader (#PCDATA)>
<!ELEMENT linespace (#PCDATA)>
<!ELEMENT appendblanklines EMPTY>

XML Code Sample — AppendPDF Pro only

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

Elements for <TOC> Style — AppendPDF Pro only

fontfile (AppendPDF Pro only)

Name and path of the font file.

fontname (AppendPDF Pro only)

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

fontsize (AppendPDF Pro only)

Specifies the size of the font. Default is 14.

leader (AppendPDF Pro only)

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

linespace (AppendPDF Pro only)

Specifies the line spacing of the TOC text. Default is 3.

appendblanklines (AppendPDF Pro only)

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

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

Usage notes for the elements of <TOC> Style — AppendPDF Pro only

Font name (AppendPDF Pro only)

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:

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.

Font file (AppendPDF Pro only)

If you specify a PostScript Type 1 font, you must supply the font name, 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.
• If there is a conflict between Font Name and Font File, the information in the font file overrides the font name.

Leader (AppendPDF Pro only)

The following notes apply to the 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.

Linespacing (AppendPDF Pro only)

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 Leader note above for more information.

Examples — AppendPDF Pro only

Specifying style (AppendPDF Pro only)

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>
         14
      </fontsize>
      <leader>
         .
      </leader>
      <linespace>
         3
      </linespace>

Specifying the Cover Page <coverpage> — AppendPDF Pro only

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 — AppendPDF Pro only

DTD Elements

<!ELEMENT coverpage (file, stampfile?)>
<!ELEMENT file (#PCDATA)>
<!ELEMENT stampfile (#PCDATA)>

XML Code Sample — AppendPDF Pro only

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

Elements for <coverpage> — AppendPDF Pro only

File (AppendPDF Pro only)

Specifies the path and filename of a PDF file to be the cover page.

Stampfile (AppendPDF Pro only)

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

Usage notes for the elements of <coverpage> — AppendPDF Pro only

• Cover page files can be more than one page.
• Cover pages should not contain any bookmarks. AppendPDF Pro adds its own bookmark for the cover page(s).
• Cover pages, Table of Contents pages and body pages each use an independent stamp file. Stamps listed in the Cover Page section are applied only to the cover pages, and will not affect the TOC or the body pages of the output PDF.

Example — AppendPDF Pro only

Specifying a cover page and a stamp file (AppendPDF Pro only)

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">
 <!-- coverpage is for APPENDPDF PRO only -->
 <!-- . Indicates skipped sections -->
 <!-- . -->
 <!-- . -->
   <coverpage>
      <file>
         ./samples/pdfs/lettersample.pdf
      </file>
      <stampfile>
         ./samples/stampfiles/letterstamp.txt
      </stampfile>
   </coverpage>
 <!-- . -->
 <!-- . -->
 <!-- . -->
 </appendparam>

Specifying Document Information <docinfo>

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

The table below describes the Elements of <docinfo>.

Contents of the <docinfo> element

DTD Elements

<!ELEMENT docinfo (infopair+)>
<!ELEMENT infopair (key, 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> Document Information fields 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.

Examples

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

Specifying Extras <extras>

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

DTD Elements

<!ELEMENT extras (stampfile | opentopage | openmode | viewmode | bookmarkmode | layoutmode | displaymode)*>

<!ELEMENT stampfile(#PCDATA)>

<!ELEMENT opentopage(#PCDATA)>

<!ELEMENT openmode (showbookmarks | showthumbnails | shownone | fullscreen)>
<!ELEMENT showbookmarks EMPTY> <!ELEMENT showthumbnails EMPTY>
<!ELEMENT shownone EMPTY><!ELEMENT fullscreen EMPTY>

<!ELEMENT viewmode (actualsize | fitheight | fitpage | fitvisible | fitwidth)>
<!ELEMENT actualsize EMPTY> <!ELEMENT fitheight EMPTY>
<!ELEMENT fitpage EMPTY> <!ELEMENT fitvisible EMPTY>
<!ELEMENT fitwidth EMPTY>

<!ELEMENT bookmarkmode (openbookmarks | closebookmarks | openlevel)>
<!ELEMENT openbookmarks EMPTY><!ELEMENT closebookmarks EMPTY>
<!ELEMENT openlevel(#PCDATA)>

<!ELEMENT layoutmode (single | onecolumn | twocolleft | twocolright)>
<!ELEMENT single EMPTY> <!ELEMENT onecolumn EMPTY>
<!ELEMENT twocolleft EMPTY> <!ELEMENT twocolright EMPTY>

<!ELEMENT displaymode (hidetoolbar | hidemenubar | hidewinui | fitwin | centerwin | showtitle)+>
<!ELEMENT hidetoolbar EMPTY> <!ELEMENT hidemenubar EMPTY>
<!ELEMENT hidewinui EMPTY> <!ELEMENT fitwin EMPTY>
<!ELEMENT centerwin EMPTY> <!ELEMENT showtitle EMPTY>

XML Code Sample

<appendparam version="1.0">
 <!-- . Indicates skipped sections -->
 <!-- . -->
 <!-- . -->
   <extras>
 <!-- stampfile is for AppendPDF Pro Only -->
      <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>

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.

opentopage

The page number at which to open the document.

viewmode

Specifies the zoom level when the document opens.

fitheight

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

fitpage

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

fitvisible

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

fitwidth

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

actualsize

The document opens at actual size.

bookmarkmode

Specifies the initial state of the document’s bookmarks in the navigation pane. This does not affect the visibility of the Bookmark 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=X, 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 tool bar will not be displayed when the document opens.

hidemenubar

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

hidewinui

Specifies that 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 filename, 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 is for AppendPDF Pro Only -->
      <stampfile>
         /fullpath/extrasstamp.txt
      </stampfile>
      <opentopage>
         7
      </opentopage>
      <viewmode>
         <fitwidth/>
      </viewmode>
      <openmode>
         <showbookmarks/>
      </openmode>
      <bookmarkmode>
         <openlevel>
            3
         </openlevel>
      </bookmarkmode>
      <displaymode>
         <centerwin/>
         <showtitle/>
      </displaymode>
   </extras>

Introduction to AppendPDF and AppendPDF Pro | Putting It All Together

• About You
  • Who are you?
  • What do you do?
  • What do you need?
  • What's been done?
  • Who uses ADS?
  • What do they say?
• Our Software
  • Document Production
  • Forms Processing
  • Document Control
  • PDF Management
  • Desktop Software
  • Redax
  • PDF/A Solutions
  • Free Evaluations
  • How to Buy
  • WebStore Login
• Our Services
  • Standard PDF Forms
  • Designer / XFA Forms
  • Document Automation
  • PDF Accessibility
  • Section 508 Compliance
  • Publication Scanning
  • CD & DVD-ROMs
  • Acrobat SDK Training
  • Custom Development
• Our Support
  • Technical Support
  • Product Documentation
  • FAQs
  • Sample Scripts
  • PDF Glossary
  • Contact Support
• Why Us?
  • Innovation
  • Expertise
  • PDF Standards
  • Cost Effectiveness
  • Customers
  • Testimonials
  • Case Studies
• About Us
  • Mission
  • History
  • Principals
  • Partners
  • Customers
  • News & Events
  • labs.appligent.com
  • Talking PDF (blog)
  • Contact Us
  • Site Index