The Table of Contents Block

Introduction

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 names of the Base 14 fonts are:

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

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.

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.

ColorSpace is an optional parameter. If you omit it, TOC entries will be written in black (DeviceGray and Color of 0).

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.

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.

Table of Contents Page Layout Options explained