Mapsoft TOCBuilder
Version 1.5

Introduction

The TOCBuilder tool allows you to create a Table of Contents for a document. Each entry within the Table of Contents can show the appropriate page for that entry, (as in a traditional Table of Contents for a printed document). In addition each entry within the Table of Contents is also linked to the actual heading within the document to which that entry relates. Selecting that link from within the Table of Contents will cause the focus in the document to jump to the relevant text. The Table of Contents is thus a powerful tool for navigating around your document.

The Table of Contents can be hierarchical, with sub-sections being indented below higher level sections, or it can be flattened with all entries appearing at the same level. Using options within the TOCBuilder you control the positioning and appearance of all the entries within a Table of Contents.

        TOCBuilder uses bookmarks found within a document to generate the Table of Contents.

The bookmarks used by TOCBuilder to generate a Table of Contents can have been created directly within Acrobat, or they can have been created by using the Mapsoft BookMarker tool which is available for purchase from the Mapsoft website: www.mapsoft.com. BookMarker creates list of bookmarks from the headings found within a document. Typically, most large documents are organised by chapter, section and sub-section, and BookMarker uses these different heading levels to create a hierarchical set of bookmarks.

If the original bookmarks within a document are hierarchical, then the resulting Table of Contents will be hierarchical too. In a hierarchy subordinate items are indented to the right. Each different heading level within the Table of Contents will correspond to one of the hierarchical levels within the bookmark list. Thus, TOCBuilder will create a level 1 Table of Contents entry for each level 1 bookmark found within the document. It will create a level 2 Table of Contents entry for each level 2 bookmark and so on. Options you specify to the TOCBuilder tool control the appearance and positioning of each different heading level within the generated Table of Contents.

The number of levels to which the Table of Contents can be nested depends on the level to which the bookmarks have been nested. For example, if bookmarks are nested to four levels then you can set up to four different levels of entries in a Table of Contents.

The following diagram shows a sample Table of Contents created using the TOCBuilder tool. This particular example shows a hierarchical Table of Contents which is nested to three levels.

If the bookmarks are all at the same level, the resulting Table of Contents will be flattened, and all the entries within it will appear at the same level. The following diagram illustrates this.

This diagram shows the same Table of Contents as in the first diagram, but here the Contents list has a flat structure as the original bookmarks were all at the same level, while the first example has a hierarchical structure reflecting the fact that the original bookmarks were also hierarchical.

The Table of Contents is inserted back into the original (current) document. By default this is inserted after the first page in the document but you can specify exactly where you want it to be inserted.

Using the TOCBuilder Tool

Before using the TOCBuilder you must ensure the document for which you wish to create a Table of Contents contains bookmarks. If it does not you will receive an error message when you attempt to run TOCBuilder and you will not be able to proceed until you have first created bookmarks for that file.

To create a table of contents for a single document:

1.      Open the document for which you wish to create a Table of Contents.

2.      Check the document contains bookmarks. If it does not then you must create them before using the TOCBuilder. You can use the BookMarker tool to do so if you wish. See the BookMarker chapter for details.

3.      Select Plug-Ins > Mapsoft >TOCBuilder ... from the Acrobat main menu.

4.The Mapsoft TOCBuilder dialog box now appears.

5.      Select the Template File radio button and then enter the name of the template file on which the new Table of Contents pages should be based. Alternatively, click the Blank Page radio button to base the new pages on a page found within the current document. (You can specify the appropriate page number of the page on which the new Table of Contents pages should be based.)

6.      In the Units field, select the units of measurement that you wish to use when specifying information for your Table of Contents entries. This controls the units of measurement that will be used in fields such as the Page Margins. By default, these are calculated in Inches, but you can choose Centimetres or Points instead from the drop down list in the Units field.

7.      Next, set the margins you require for the Table of Contents pages in the Page Margins group of fields. You may wish to set these to be the same as the page margins used throughout the rest of the document, so that when the new Table of Contents pages are inserted they appear consistent with existing pages within the document.

You can also specify a margin to be used at the top of the first page of the new Table of Contents page should you want that page to have a different top margin than subsequent pages within the Table of Contents. This would accommodate a template which had more space in subsequent pages than the first.

8.      Now, make entries into the Contents Title group of fields. Options here allow you to specify the text to be used for the Table of Contents heading, together with its positioning and appearance on the page:

• Type the heading you wish to be used for your Table of Contents into the Text field. For example, Table of Contents or simply Contents.
• Select the font in which you wish this heading to appear in the completed Table of Contents. Choose from the available fonts shown in the drop-down list in the Font field.
• Next select the font size using the drop-down list in the Size field.
• Now specify the colour in the Colour field. Click on this field to display a Colour dialog box from where you can make your selection. See the Customised Colours section below for full details on selecting colours.
• Specify the position on the page at which you wish the Table of Contents title to appear, by setting the X (horizontal) and Y (vertical) co-ordinates in the Top and Left fields respectively. These co-ordinates refer to the position of the text in relation to the top left of the page.
• Specify the right margin to be used for the Table of Contents title into the Right Margin field.

9.      Next, select the properties to be used for first level entries within the Table of Contents. Options within the Level group control the appearance of entries within the Table of Contents:

• First in the Font field, select the font that is to be used for the highest level Table of Contents entries (or all entries in a flat Table of Contents structure). For example, select Helvetica from the drop-down list available in this field.
• Type the size of that headings font into the Size field (in points), for example 10.
• Type the line spacing to be used between Table of Contents entries into the Line Spacing field (in points). If you enter a size and then go on to modify another level you will find that TOCBuilder sets a sensible line spacing automatically.
• Type in the amount by which this particular level of entry is to be indented from the left-hand margin in the Indent field. This is measured in the Units selected in step 6.
• Click the Colour button to display a Colour dialog box from where you can select the colour of the text to be used for Table of Contents entries of this particular level. See the Customised Colours section below for full details on selecting colours
• Ensure the Include Destination Page Numbering check box is checked (the default) if you want the Table of Content entries to include the page number of the actual content. In addition, ensure the Include Leaders check box is checked (the default) if you want the Table of Contents entries to include leading dots between the entry and its associated page number.

10.   If you want each Table of Content entry to be surrounded by a box (i.e. by a visible link) select the Line Width you require for those boxes from the Links field. You can choose if the line should be Thin, Medium or Thick. You can also select the colour of the line by clicking on the Colour field associated with the Links group. Clicking on this field displays a Colour dialog box from where you can make your selection. See the Customised Colours section below for full details on selecting colours

11.   Click Add Level to set this particular level of Table of Content entry.

12.   If creating a hierarchical Table of Contents, repeat steps 9 through 11 for each different heading level.

As you add each new level it will appear in the box to the right of the TOCBuilder dialog box. Each new level will be nested below the previously defined one, so demonstrating the hierarchy the Table of Contents will follow when it is created:

If you specify more levels than have been defined for bookmarks any extra levels will simply be ignored. For example, if you have three levels of bookmarks defined for a document, but you define five levels for the Table of Contents, the Contents list will only be nested to three levels when it is generated. If you wished to nest to more levels you would need to define additional bookmark levels first before running TOCBuilder.

You can remove a heading type from the Table of Contents list at any time simply by selecting the Level representing that heading type from the right-hand box in the TOCBuilder dialog box, and then clicking Remove Level. Any sub-levels will automatically be incremented by one level.

13.   Now, make entries into the TOC Numbering Options group of fields:

• Enter the page number of the page that is to appear immediately after the Table of Contents in the Page After TOC is Number field. The page number you should use here is that which would appear on the page after the insertion point if it were printed.
  
  It is also important to note that bookmarks referring to pages prior to the insertion point will be ignored and will not appear in the TOC.
• Specify the position in the document at which the Table of Contents is to be inserted in the Insert TOC at Page field. This can either before of after a specified page number.
• If your document is divided into chapters, optionally, click the Restart Page Numbering if you wish page numbering to re-start afresh for each individual chapter. The chapter headings are considered to be the level1 bookmarks.
  
  
• If you document is divided into chapters, optionally check the Show Chapter Numbering Starting At button and enter the number that should be used for the first chapter.
• Choose if you want to exclude any bookmarks that don't currently point to any pages by setting the Exclude Bookmarks that don't Point to Pages checkbox. (This is set on by default.)
• Click the Create ThumbNails for new pages check box if required.

14.   Optionally, enter a name in to the Configuration Name field and click its associated Save button to save your Table of Contents definition for later re-use with other files.

15.   Click OK to create the Table of Contents.

The Table of Contents will be inserted into the specified location in your document once it has been generated.

Saving a TOCBuilder Configuration

To save a particular TOCBuilder configuration for later re-use, simply enter a name for it into the Configuration Name field, then click the Save button. This makes configuration available for re-use in another session of TOCBuilder. It also makes it available for use with Automator, Mapsoft's unique automation tool which allows you to work with multiple files in batch mode.

Once saved, you can delete any existing TOCBuilder configurations you no longer require simply by selecting the appropriate one from the drop-down list in the Configuration Name field and then clicking the Delete button.

TOCBuilder Options

The following options can be set in the TOCBuilder dialog box:

TOC Pages	The file to be used as the template file when the Table of Contents pages are created. Choose from the following two options: Template File The PDF file which is to act as a template for the new Table of Contents pages when they are created. You can type the name (and path) of the appropriate file into this field, or alternatively use the Browse button to locate and then select it. This template file can consist of one or two pages. If two pages in length, the first page will be used as the template for the first page of the new Table of Contents, while the second page will be used as the template for subsequent pages. Blank Page The new Table of Contents will be based on a blank page
Units	The units of measurement to be used in calculating the positioning of the Table of Contents and the various entries within it. Choose from: Inches (the default) Centimetres Points
Contents Title	Allows you to specify the Text to be used as the heading for the new Table of Contents, together with various properties relating to its appearance: Text The actual text to be used as the Table of Contents heading, for example, Table of Contents or Contents. Font The font of the heading, for example Helvetica. For maximum flexibility, you can select any Acrobat base font (shown in red in this field) or Type 1 (TrueType) font (shown in black) that is available on your system. However, if you choose a font that you do not have the ability to embed in your final document, then the generation of your Table of Contents will fail Size The heading size, in points. Colour Allows you to specify the colour of the text to be used as your Table of Contents heading. See the section Colour Options below for details. Top The horizontal position (in the units specified in the Units field) at which the Table of Contents heading should be positioned on the page in relation to the top left hand edge of the page. Left The vertical position (in the units specified in the Units field) at which the Table of Contents heading should be positioned on the page in relation to the top left hand edge of the page. Right Margin The size of the Table of Contents headings right margin (in the units specified in the Units field).
Page Margins	Specifies the Top, Bottom, Left, Right and First Page Top margins to be used for the Table of Contents pages when they are generated. These are calculated in the units selected in the Units field.
Level	Allows you to set the properties relating to each bookmark level for which Table of Contents entries are to be created: Font The font of the heading, for example Helvetica. Size The heading size, in points. Line Spacing The line spacing to be used between Table of Contents entries, in points Indent The amount (in the measurement unit specified in the Units field) by which this type of entry is to be indented to the right of the left margin. Colour Allows you to specify the colour of the text to be used as your Table of Contents heading. See the section Colour Options below for details Include Destination Page Numbering Includes the appropriate page number against each entry in the Table of Contents showing the page within that document on which the text associated with that entry can be found. Include Leaders Includes leading dots between each Table of Contents entry and its associated page number.
Links	Includes visible links around Table of Contents entries. You can select if the border for the links should be of Thick, Thin or Medium width. You can also choose the colour for these borders. By default, a visible border is not shown around Table of Contents entries.
Add Level	Adds the current Table of Contents text entry definition as a new level
Remove Level	Removes the currently selected type of Table of Contents entry from the hierarchical list of entry levels, and automatically increments all sub-levels by one to ensure no gap is left in the hierarchy.
TOC Numbering Options	Allows you to set properties relating to page numbering associated with Table of Contents: Page After TOC is Number Allows you to specify the page number that is to appear on the first page following the Table of Contents. This allows you to overcome any mismatch that may exist between Acrobats internal page numbers (used in calculating Table of Contents entries) and the physical page numbers actually shown on the relevant pages. Insert TOC at Page Allows you to specify where in the document the Table of Contents is to be inserted once it has been generated. Choose from Before to insert the new Table of Contents before the specified Page or After to insert the new Table of Contents after the specified Page. Specify the actual page number of the page before/after which the Table of Contents is to be inserted in the associated Page field. This is the internal page number of the page as used by Acrobat, and may not necessarily match the actual page number. It is also important to note that bookmarks referring to pages before the insertion point are ignored in the building of the table of content pages. Restart Page Numbering For documents that are divided into chapters, checking this option allows page numbering to start afresh at the beginning of each individual chapter. Show Chapter Numbering Starting At For documents that are divided into chapters, checking this option allows the page number to include a chapter number element, for example 1-1. The chapter numbering element will commence from the number specified here. Chapter headings are considered to be level1 bookmarks. Exclude Bookmarks that don't Point to Pages When set, ignores any non-active action handlers when creating the table of contents. (This is set on by default.) Create Thumbnails for New Pages Check this checkbox for thumbnails to be created automatically for each page in the Table of Contents as it is generated. By default, this option is set off so thumbnails are not created
Name Configuration	Allows you to saves the current Table of Contents definitions for later re-use with other files or for use with the Automator plug-in. Enter a name for this definition into the Name Configuration field and then click the Save button. Existing Table of Contents definitions can be removed, by selecting them within the Name Configuration field and then clicking Remove.
OK	Commences the Table of Contents generation process.

Customised Colours

The TOCBuilder dialog box contains three Colour fields, one allowing you to set the colour of the Table of Contents heading, the other the colour of entries within the Table of Contents itself and the third allowing you to specify the colour of any links. All three fields operate in exactly the same way. Click once on any of the three fields to display the following Colour dialog box.



Select the basic colour of your choice by simply clicking once on the square representing that colour and then clicking OK to return to the TOCBuilder dialog box.

Alternatively, define your own customised colour. To do so, click once on one of the blank squares in the Custom Codes field and then click the Define Custom Codes. Make your selection in the additional dialog box that then displays, as in the example below.



Click Add to Custom Color to add your selection as a new customised colour. This will be available for re-selection the next time you enter this dialog box (from either Colour field).

Click OK to return to the TOCBuilder dialog box where the colour you just defined or selected will be shown in the appropriate Colour field as in the example below: