Chapter 8. Creating Tables of Contents and Other Lists

CONTENTS

Chapter 8. Creating Tables of Contents and Other Lists

•  Lists, Lists, and More Lists
•  Looking Inside: How FrameMaker Creates a Table of Contents
•  Creating a Table of Contents
•  Making Changes to an Existing Table of Contents
•  Working with Static Text
•  Adding Prefixes to Page Numbering
•  Using Hypertext Links
•  Using Run-In Heading Formats in a Table of Contents
•  Ways to Work with a TOC Template
•  Using Cross-References
•  Other Helpful Lists
•  Summary

Open any book or magazine and take a look at the table of contents. The table of contents is the key to what's inside. It maps out an organized list of topics or chapters and the pages on which they start. Two factors define a table of contents: contents and aesthetics.

Many other types of lists serve as guides to what's inside documents. Lists of figures and tables organize figure or table titles and the pages on which they start. Lists that include markers, alphabetized paragraphs, and referenced items in documents are lists that FrameMaker uniquely enables you to create.

Do you remember that eleventh-hour project that had you creating a table of contents, list of figures, and list of tables by hand? If so, you'll appreciate letting FrameMaker do that grunt work for you.

This chapter provides you with the information you need to understand the architecture behind tables of contents and other lists, how to set these up for the first time, change them at any time, and solve some of the problems that you might run into. You also explore how various FrameMaker parts work together to produce these lists and what you need to do to make it all work.

Lists, Lists, and More Lists

Note

For more information on indexes, see Chapter 9.

This chapter focuses mainly on tables of contents. However, the same principles apply to other types of lists that you might want to create in FrameMaker. In Table 8.1, some of the available lists are reviewed, such as what they are used for and the suffix that is automatically added to the filename.

Table 8.1. Generated Lists Available in FrameMaker

List Name	Description	Suffix Tag
Table of Contents	Used for a list of headings displayed in order of occurrence in source documents.	TOC
List of Figures	Used to list figure titles or captions in order of occurrence in source documents.	LOF
List of Tables	Used to list table titles in order of occurrence in source documents.	LOT
List of Paragraphs	Used to list text of specified paragraphs in order of occurrence in source documents.	LOP
List of Paragraphs (Alphabetical)	Used to list text of specified paragraphs in alphabetical order.	APL
List of Markers	Used to list a variety of marker entries that have been inserted in source documents. The actual text contained in each marker is displayed in the list, in order of occurrence in the source document.	LOM
List of Markers (Alphabetical)	Used to list a variety of markers that have been inserted in source documents. The actual text contained in each marker is displayed in the list in alphabetical order.	AML
List of References	Used to list special information in source documents, such as conditional tags, external cross-references, unresolved cross-references, fonts, text insets, unresolved text insets, imported graphic and Macintosh publishers. The selected information is listed in order of occurrence in the document.	LOR

Looking Inside: How FrameMaker Creates a Table of Contents

You might have heard the term generated files. That's exactly what tables of contents are in FrameMaker. FrameMaker generates, or creates, the table of contents based on some parameters, or rules, that you set up.

The table of contents does not exist until FrameMaker brings it into being the first time. FrameMaker gathers information from source documents and inserts this information in a separate file the table of contents file. Once the file exists, you can decide what other elements you want to include and format the look of your table of contents.

When the information in the document changes, simply update the table of contents and FrameMaker obtains the new information from the source document and replaces the old information. Before you get started with some real-world examples and how-to's, you must review the features you'll be working with to either create a table of contents for the first time, or edit existing tables of contents' templates. These include the following:

• Determining what's included in the table of contents

• Learning how a table of contents is structured

• Understanding how a table of contents looks

Determining What's Included in the Table of Contents

The information you want to include in a table of contents is determined by paragraph tags. Because each paragraph in a document is tagged with a particular paragraph tag, you simply select the paragraph tags that contain the source information you want to include in the table of contents. For example, if you want to include chapter headings in a table of contents, and chapter headings are tagged with the paragraph tag ChapterTitle, you must select ChapterTitle for inclusion in the table of contents. When the table of contents is created, FrameMaker obtains the content of each paragraph tagged with ChapterTitle from source documents and inserts the text into the table of contents list.

Note

Paragraph tags are listed whether or not they are actually used in each document.

You use the Set Up Table of Contents window to select the paragraph tags that you want to include, as shown in Figure 8.1. Access this window by selecting Special > Table of Contents when you have a document file open, or by selecting Add > Table of Contents when you have a book file open. Table 8.2 describes each Set Up Table of Contents setting.

Figure 8.1. The Set Up Table of Contents window.

Table 8.2. Setting Up the Table of Contents

Setting	Description
Suffix	Denotes the file type. This should not be mistaken for a filename extension. Using the table of contents example, the suffix TOC becomes part of the filename, as in FilenameTOC.fm. By default, TOC is added to the filename, but you can change the name of the suffix before you click the Set button.
Add File	Appears on the menu only if you add a table of contents from within a book file. You can select whether the table of contents will be added before or after a particular file in the book list.
Include Paragraphs Tagged	Moves paragraph tags to this list when you want to include their content in the table of contents.
Don't Include	Displays a list of all paragraph tags contained in the source document. If you are in a book file, this list includes paragraph tags from all the document files in the book. Move paragraph tags between lists by double-clicking on the paragraph tag, or by clicking one time, then clicking on the left or right arrow. Move all paragraph tags from one list to another by holding down Shift and clicking on the left or right arrow.
Create Hypertext Links	Check this box to link each item in the table of contents list to the source information. Then, with hypertext enabled, you can jump from each list item to it's source information with a single click.

How a Table of Contents Is Structured

The way in which source information is arranged or put together in a table of contents is determined by a structure that's located on the TOC reference page of the table of contents file. The structure on the TOC reference page contains Building Blocks that represent various parts of the source information. For example, you might want to include the chapter number and title, but not the page number. A Building Block represents the chapter number, one for the title and another for the page number. You can use Building Blocks in any order or not at all to determine what parts of source information are inserted and displayed in the table of contents list. Building Blocks can also be combined with text or character tags for even more control over the appearance of information.

Table 8.3 shows a simple example of how Building Blocks represent various parts of the source information.

Table 8.3. Example of Building Block Representatives

Building Blocks	<$chapnum>	<$paratext>	<$pagenum>
How This is Displayed	9	Travel Made Easy	149

If you have worked with Building Blocks in other FrameMaker features, you know that usually a list of Building Blocks is provided from which you can select. That is not the case with Building Blocks that are used to create the structure of lists in generated files, such as the table of contents. It's a good idea to keep a list of Building Blocks handy while you work on these types of lists.

How a Table of Contents Looks

After you determine the source information that's included (by selecting a paragraph tag) and how the information is structured (through Building Blocks), the final step is to format the look of the information. The first time a table of contents or another list is created, it is quite plain-looking and uses the default FrameMaker format. You can format the information using the Paragraph Tag Designer just as you would any other paragraphs in a document.

You might notice that after the table of contents is created, some new paragraph tags are added to the Paragraph Catalog. Each of these new paragraph tag names have something in common: a TOC suffix. For example, if you select the ChapterTitle paragraph tag to be included in your table of contents, the paragraph tag ChapterTitleTOC is included in the table of contents' Paragraph Catalog.

As a result, text in the table of contents list with a paragraph tag that includes the TOC suffix is replaced every time you update the table of contents. If you change the name of the paragraph tag, this feature doesn't work.

Issues to Keep in Mind Before You Create the TOC

Before you dive into creating a table of contents (whether for a single file or a book), here are three issues to keep in mind that can cause problems in resulting tables of contents or other lists:

• Be consistent with paragraph tagging. Paragraph tags are used to determine what is included in the table of contents. That said, say that you have first-level subheadings in your document tagged with Heading1. Then you decide to vary the format slightly and tag some of the first-level subheadings with Heading1a; well, now you have to keep track of two paragraph tags for one heading level. As a result, although it's the same heading level, in the table of contents, you will have to configure two separate paragraph tags to achieve one outcome.

• Soft returns. Stay away from soft returns in paragraphs that are included as source information in the table of contents. Basically, all the source information is included, meaning that the soft return is also included. If you have many soft returns in source paragraphs, these will be included in the table of contents and you must manually delete these. After performing such great work, when you update the table of contents, all your work will be replaced and you will have to start over.

• Empty paragraph lines. This is a big no-no in FrameMaker for a few reasons. Say that you have empty paragraph lines that are tagged with Heading1, and Heading1 is included in the table of contents source information. When you create or update the table of contents, you end up with many blank lines. FrameMaker is just following orders, obtaining information from the source document that is tagged with Heading1. It does not care whether or not "real" information is contained in the paragraph. It's really looking for any occurrence of that paragraph tag. So, if it's empty, it's empty. You get the idea.

Creating a Table of Contents

Now that you have some background information about tables of contents, get started by creating a table of contents for the first time. In this section, you go through the steps to determine what's included, how the information is structured, and how to format the look. In addition, you discover how to make changes at any time to existing tables of contents. Although these exercises address working with creating a table of contents based on one source document file, the process is almost exactly the same as working with a book file. The differences are included as sidenotes where appropriate.

Determining What's Included

Before you start this step, it's a good idea to get organized about the information that you plan to include in the table of contents. For example, you might want to include chapter headings and first- and second-level subheadings. Take a look inside the source document and make a note of the paragraph tags applied to the source information. After you know the paragraph tag names of the source information that you want to include in the table of contents, you can get started.

For this exercise, suppose that you want to include ChapterTitle, H1, and H2 paragraph tags in the table of contents. These paragraph tags contain the chapter heading, and the first- and second-level subheadings. Each of these includes an autonumber and is displayed like this in the source document:

Chapter 3 The Essential Guide to Running

3.1 The Language of Running

3.2 Understanding Pace

3.2.1 When to Walk

3.2.2 When to Jog

Begin with the document containing the source information open, and follow these steps:

Book Note

From a Book File window, select Add > Table of Contents to reach the Table of Contents window.

1. Select Special > Table of Contents.

   The Stand-alone Table of Contents message appears. This reminder from FrameMaker tells you that you are not currently in a book file, but that option is available.

2. Click Yes.

   The Set Up Table of Contents window appears.

3. Double-click on ChapterTitle on the Don't Include side. ChapterTitle moves to the Include Paragraphs Tagged: list on the left. The result: The ChapterTitle source information is included in the table of contents list.

4. Double-click on H1 and then H2 on the Don't Include side (see Figure 8.2).

   Figure 8.2. You can move between lists in the Set Up Table of Contents window.

   

   H1 and H2 move to the Include Paragraphs Tagged: list on the left. As a result, both H1 and H2 source information will be included in the table of contents list.

Tip

To move all paragraph tag names from one list to another at the same time, press Shift and either the left or right arrow in the window.

5. Click on the Set button.

   The Set Up Table of Contents window closes, and a new file is created and displayed. The filename is the same as the document filename that was open and active when you set up the table of contents. The filename includes the TOC suffix, as in filenameTOC.fm. The new table of contents file contains a list of the source information that you included in the setup. The table of contents looks plain (see Figure 8.3) and might not include all the parts of the source information, such as the autonumber. Adding that is discussed next.

   Figure 8.3. The newly created table of contents before formatting occurs.

   

Book Note

Using a book file, the filename can be the same as the book filename and include the TOC suffix.

Establishing the Structure

As you can see in Figure 8.3, the first time a table of contents is created, it might not contain all the parts of the source information that you want to include in the list. For example, the autonumber of each source item in the list is not currently included. The look of the list is not aesthetically pleasing either, but that'll be fixed in the next exercise.

In this section, you discover how to include the autonumber of source paragraphs in the table of contents, as well as how a tab is used to move the page number to the right side of the column.

Viewing the Current Structure

Take a look at and understand the structure behind the current table of contents list before you attempt to fix it:

1. Select View > Reference Page.

   The first reference page appears.

2. Select View > Go To Page. Then select TOC from the drop-down menu (see Figure 8.4) and click on the Go button.

   Figure 8.4. The Go To reference page window.

   

   The reference page that contains the Building Block structure for the table of contents appears.

3. Click one time in each line of the Building Block structure (see Figure 8.5). You can see that the first line represents the H2TOC paragraph tag, the second line represents H1TOC, and the last line represents ChapterTitleTOC. The first Building Block, <$paratext>, represents the text part of the paragraph tag's source information. The <$pagenum> represents the page number where the source information is located. These are the default Building Blocks that FrameMaker inserts the first time you create a table of contents.

   Figure 8.5. The initial Building Block structure.

   

Back to Basics

Paragraph tag names appear in the status bar on the lower left of the screen.

Adding the Autonumber Building Block to the Chapter Heading

Next, add the autonumber to the chapter heading that appears in the table of contents list:

1. Click one time right before the <$paratext> Building Block for ChapterTitleTOC.

   The insertion cursor is inserted right before the <$paratext> Building Block. Note that, in this example, ChapterTitleTOC Building Blocks are last in the list on the TOC reference page.

Back to Basics

To be on the safe side, save the table of contents files after each series of steps is completed.

2. Type <$paranum>.

   <$paranum> is inserted right before <$paratext>. <$paranum> represents the autonumber part of the ChapterTitle paragraph's source information. The next time the table of contents is regenerated from the source information file, the autonumber of source information paragraphs tagged with ChapterTitle will be included in the table of contents along with the title text and page number.

   Alternatively, you can use <$chapnum> rather than <$paranum>. The result looks like <$chapnum><$paratext>. <$chapnum> is used for the chapter number of any given file and, therefore, displays the chapter number when it's included in the table of contents structure. If you decide to use this method, type the word "Chapter" before the <$chapnum> Building Block if you want the word "Chapter" included in the table of contents list (i.e., Chapter 3 The Essential Guide to Running).

3. Select View > Body Pages.

   The table of contents body page appears. Nothing on this page has changed as a result of the change you made to the reference page structure. This is normal and exactly what should happen.

Back to Basics

The TOC must be regenerated to realize changes to the structure.

4. Use the Window menu to make the source document file active.

   The document containing the source information is the active file.

5. Select Special > Table of Contents.

   The Stand-alone Table of Contents message appears. This reminder from FrameMaker tells you that you are not currently in a book file but that option is available.

   Click Yes.

   The Set Up Table of Contents window appears.

Book Note

From a Book File window, select Edit > Update Book.

6. Click on the Set button.

   You set up the table of contents paragraph tag source information in the last exercise. You do not have to perform this step again, unless you are making a change to the original settings.

   The Set Up Table of Contents window closes and the existing table of contents file displays with the updated text. The autonumber of the ChapterTitle source information is included in the list (see Figure 8.6. ) It won't look very appealing at this stage of the process. The other items in the list look the same as they did.

   Figure 8.6. The results after you add the chapter heading number Building Block.

   

Back to Basics

If a manual tab was included in the chapter title text, it's also included in the TOC.

Adding Remaining Autonumber and Tab Building Blocks

Now that you have seen how to get the autonumber of the chapter heading to appear in the table of contents, it's time to add the autonumber to both the H1, and H2 subheadings. In addition, you need to add a tab in between the autonumber and the text, and then the text and the page number for ChapterTitle, H1, and H2. If not, the various parts of the displayed information run into each other.

Back to Basics

If the source paragraphs contain manual tabs, these are included in the table of contents list.

1. Select View > Reference Page.

   The reference page appears.

2. Select View > Go To Page. Then select TOC from the drop-down menu and click on the Go button.

   The reference page that contains the Building Block structure for the table of contents appears.

3. Click one time right before the <$paratext> Building Block for H2TOC.

   The insertion cursor is inserted right before the <$paratext> Building Block. The Building Blocks for H2TOC are displayed first in the list.

4. Type <$paranum>.

   <$paranum> is inserted right before <$paratext>. <$paranum> represents the autonumber part of the H1 paragraph's source information. As a result, the next time the table of contents is updated with new source information, the autonumber of source information tagged with H2 will be included in the table of contents.

5. Click one time in between the angle brackets of <$paranum> and <$paratext>.

   The insertion cursor is inserted in between <$paranum> and <$paratext>. You are preparing to add another Building Block.

6. Type \t.

   This Building Block must be inserted in between <$paranum> and <$paratext>. \t is a Building Block that represents a tab. As a result, a tab will be included in between the autonumber and the text of H2 source information.

Tip

Alternatively, you can press the Tab key.

7. Type \t in between <$paratext> and <$pagenum>.

   \t is inserted in between <$paratext> and <$paranum>. As a result, a tab is included in between the text and the page number of H2 source information in the table of contents.

8. Repeat Steps 3 through 7 for H1TOC.

   The resulting changes look like Table 8.4. You are now ready to regenerate the table of contents.

Table 8.4. The Completed Building Blocks for a Table of Contents

H2TOC	<$paranum>\t<$paratext>\t<$pagenum>
H1TOC	<$paranum>\t<$paratext>\t<$pagenum>
ChapterTitleTOC	<$paranum>\t<$paratext>\t<$pagenum>

After you regenerate the table of contents, you can see the changes that you incorporated into the Building Block structure on the reference page. Figure 8.7 shows the result. Notice the numbers are now included and you can see the tab symbols. No position for the tabs to move to exists yet.

Figure 8.7. The result after you add Building Blocks to the TOC format structure.

If you do not regenerate the table of contents, you won't see these changes incorporated in the table of contents list.

Formatting the Look

So far in this section, the pieces to the table-of-contents puzzle are slowly coming together. You selected the paragraph tag source information to include in the table of contents, as well as defined the parts of each paragraph that you want to include, such as the autonumber, text, and page number. The final step: Make it all look aesthetically pleasing.

In this exercise, you format the look of the current table of contents by using the Paragraph Designer. After you complete this step, the next time you regenerate the table of contents, the information will flow nicely into the new format and you won't have to do all this work again, unless you plan to make purposeful changes to any aspect of the table of contents.

Back to Basics

You can click Update All in the Paragraph Designer after you make changes to each property.

You'll make changes to the Basic properties of the Paragraph Designer to create the indents, spacing, and tabs that are necessary to make the table of contents look organized. Note that, although default font changes are not included in this exercise, you must make those changes in your document, if appropriate.

First, start on the body page of the table of contents with the insertion cursor in the first line of text. In this exercise, the first line of text is tagged with ChapterTitleTOC.

1. Select Format > Paragraphs > Designer.

   The Paragraph Designer for ChapterTitleTOC appears.

2. In Basic Properties, change the settings as shown in Figure 8.8.

   Figure 8.8. The Basic properties for ChapterTitleTOC.

   

   The new settings are incorporated in all paragraphs tagged with ChapterTitleTOC. Don't forget to add the two tab stops for the two tabs currently incorporated in the paragraph. If you don't add the tab stops, the tabs won't have a position from which to move. A leader tab is included for the second tab position. This is the tab between the text and the page number. You don't have to choose a leader tab. This is just one way of displaying a page number in a table of contents.

Next, place the insertion cursor in the second line of text. In this exercise, the second line of text is tagged with H1TOC.

1. Select Format > Paragraphs > Designer.

   The Paragraph Designer for H1TOC appears.

2. In Basic Properties, change the settings as shown in Figure 8.9.

   Figure 8.9. The Basic properties for H1TOC.

   

   The new settings are incorporated in all paragraphs tagged with H1TOC. The settings you use in your document might not be the same as these. This is just one idea of Basic Property settings for list items in the table of contents.

3. Select Format > Paragraphs > Designer.

   The Paragraph Designer for H2TOC appears.

4. In Basic properties, change the settings as shown in Figure 8.10.

   Figure 8.10. The Basic properties for H2TOC.

   

   The new settings are incorporated in all paragraphs tagged with H2TOC.

After you finish making the appropriate changes to the three paragraph tags in the table of contents, regenerate the table of contents. Each time you regenerate the table of contents, the current information in the list is deleted and replaced with the updated information, even if none of the source information actually changed.

The result after formatting will look something like what's shown in Figure 8.11.

Figure 8.11. Alas! The result of formatting the table of contents information.

Other Types of Formatting

After a table of contents or other type of list is created, the file is essentially just like any other FrameMaker file in terms of understanding how to format the look of the information contained therein. You've seen that once the table of contents is created, you can simply make changes to the paragraph tags used for the table of contents list to change the look.You affect these changes by using properties that are controlled by the Paragraph Designer for each paragraph tag.

You might decide to make other changes to the file, such as page size, column width, height or placement, headers and footers, or page numbering. Although I don't review these methods here, it's worth mentioning that you can easily make these types of changes in exactly the same way you would make those changes to any FrameMaker file.

Making Changes to an Existing Table of Contents

After you have a table of contents in place, you might decide to make changes to include source information or the structure of source information once it's included. For example, suppose that you originally selected ChapterTitle, H1, and H2 as the source information to be included in the table of contents. Later, you might decide to keep those, but add H3 (third-level subheadings). You decide to make a change to the part of source information that's included for ChapterTitle. For instance, in the current example for ChapterTitleTOC, the structure of the source information includes the autonumber, text, and page number. Say that you decide to exclude the page number from the ChapterTitleTOC. After these changes are made and the table of contents is updated, it might look something like this:

    Chapter 3 The Definitive Guide to Running
             3.1 The Language of Running 1
             3.2 Understanding Pace 2
                  3.2.1 When to Walk2
                  3.2.2 When to Jog2
                  3.2.3 Break Out and Run2
                        3.2.3.1 First Time Out - What to Watch For3
 

In this section, you discover how to make these types of changes to existing tables of contents. After you understand these concepts, applying them to other types of lists is not different from the techniques you use for the table of contents. For a brief overview of other lists, skip to the section, "Other Helpful Lists" on page 260.

Adding New Source Information

Using the current example, you can make one small change to what's included in the table of contents. Currently, the ChapterTitle, H1, and H2 are included. In this exercise, you add H3. Here's how to do it from the source document window:

Book Note

From a Book File window, you can click on table of contents list, then select Edit > Set Up Table of Contents.

1. Select Special > Table of Contents.

   The Stand-alone Table of Contents message appears. This reminder from FrameMaker tells you that you are not currently in a book file but that option is available.

2. Click Yes.

   The Set Up Table of Contents window appears.

3. Double-click on H3 in the Don't Include list.

   H3 moves to the Include Paragraphs Tagged: list on the left. As a result, the H3 source information is included in the table of contents list. Paragraph tags ChapterTitle, H1, and H2 are already included in the list because of the previous setup of the table of contents. You are simply adding one new item.

4. Click Set.

   The Set Up Table of Contents window closes and the existing table of contents file appears with updated source information. The information that was previously set up looks nicely formatted, but the new information looks plain, as you can see in Figure 8.12. The new information displays as "First Time Out - What to Watch For 2." You haven't yet made any changes to the structure or to the look of the new source information.

   Figure 8.12. The resulting table of contents after you add the new source information.

   

Changing the Structure

Now that you added new information, you must make changes to the structure on the TOC reference page to incorporate the pieces of the source information that are currently missing.

In addition, you must change another existing piece of information: ChapterTitleTOC. You must delete that page number Building Block. In this exercise, you add the missing Building Blocks to the new H3 source information and delete a Building Block from the ChapterTitle source information.

Earlier, you learned how to make changes to the structure behind the table of contents source information in steps. First, you made changes to the ChapterTitleTOC, then you went back and made changes to the H1 and H2. Although this works well for teaching purposes, it makes more sense to incorporate all your changes at one time, whenever possible, when on the reference page.

Begin on the TOC reference page of the table of contents. Notice that a line of Building Blocks was added. If you click one time anywhere on that line, you can see in the status bar that the paragraph tag is H3TOC, the information you added in the last exercise:

1. Click one time right before the <$paratext> Building Block for H3TOC.

   The insertion cursor is inserted right before the <$paratext> Building Block.

2. Type <$paranum>.

   <$paranum> is inserted right before <$paratext>. <$paranum> represents the autonumber part of the H3 paragraph's source information. As a result, the next time you update the table of contents, the autonumber of this particular source paragraph will be included in the table of contents.

3. Type \t in between both <$paranum> and <$paratext>, then <$paratext> and <$pagenum>.

   \t is inserted in each location. \t represents a tab. The result is that a tab is included in between both the autonumber and the text, and the text and the page number. You might not want a tab included. If you do not, hit the space bar to include a space instead.

4. Delete \t <$pagenum>, the last two Building Blocks of the ChapterTitleTOC.

   ChapterTitleTOC now contains the structure <$paranum>\t<$paratext>. This results in only the autonumber and the text of the source information being included in the table of contents. The tab and the page number aren't included.

Update the table of contents in order to view the changes you made to the Building Blocks on the reference page of the table of contents.

In addition, you need to use the Paragraph Designer to format the new paragraph tag, H3TOC, to make it fit with the look of the other source information contained in the table of contents list.

Working with Static Text

Each time you regenerate a list or index, the information is replaced with the current text from source documents. In a table of contents, each paragraph of text that's replaced has a paragraph tag applied that includes the TOC suffix in its name. In an index, replaced text has a paragraph tag applied that includes the IX suffix in its name. The text is replaced regardless of whether the source information has actually changed or not.

If you want to include a title in a list or index that won't change every time you update the table of contents, you must tag it with a paragraph tag that does not have a TOC (for table of contents) or IX (for index) suffix. Text that remains fixed in the document each time you update a generated file is also called static text.

You should be aware of one catch: If you include static text within list or index information, that static text will remain unchanged in the file after updating, but it will appear just before the first entry in the list or index. Look at Figure 8.13. The top graphic shows text added within table of contents entries, and the bottom graphic shows what happens to that static text after the table of contents is updated. Although the text remains unchanged, its location moves.

Figure 8.13. What happens to static text in a table of contents.

Static text works well for a title because a title usually starts at the top of a page, before the first entry, but does not work well in other positions.

Be aware that, if you name a paragraph tag in a generated list something like TitleTOC and apply it to text, FrameMaker discards it when you update the list. FrameMaker replaces all paragraphs that have the TOC suffix in its tag name. In this case, there is no source information to replace it.

Adding Prefixes to Page Numbering

You can configure tables of contents in many ways. These are usually driven by your current corporate style or the manner that you choose to organize documents. For example, sometimes document pages are numbered from 1 through n, beginning to end regardless of the specific chapter numbers that head up each chapter or document file. The previous examples of tables of contents lists are suitable for documents with page numbers 1 through n.

What if your documents use chapter-based page numbering? In other words, each page number depends on the chapter number heading of each chapter or document file. In this instance, Chapter 3 page numbers would display as 3-1, 3-2, 3-3 3-49, 3-50, and so on. If this is the case, you want the table of contents, or other lists you plan, to reflect the chapter-based page numbering, or the page numbers would fail to make sense.

Another time to use a prefix along with a page number is when text needs to precede the page number. Let's explore an idea of why you would do this: Say you produced a software manual that consists of both a user and reference guide. If you have these bound into one great manual with a single table of contents, the user might get confused as to what chapters make up the user guide or reference guide content. One way to solve this is to have the page numbers for the user guide read UG-1, UG-2, UG-3 , while the reference guide pages can be referred to as RG-1, RG-2, RG-3 .

You might have other ideas on why you would use a text-based prefix for page numbering in documents. This section explores how to add prefixes to page numbering in tables of contents, whether they're numerical or textual.

Chapter-Based Page Numbering

You must consider two features when you incorporate chapter-based numbering into table of contents page numbers:

• The Document Number Property for Chapter in the individual file(s) that are used as source information for the table of contents.

• Redefining the Building Block structure on the TOC reference page of the table of contents.

Take a look at how these two features work together to get you the result for which you are looking. For this example, suppose that you're creating a table of contents for a book file that contains many document files, and each page is numbered according to chapter-based numbering.

Working with Chapter Numbering Properties

Although it makes sense to use <$chapnum> in autonumber formats of paragraphs in document files, you can still use this method if you have not used <$chapnum> in autonumber formats. Regardless, you need to go to each individual document file and set the chapter number. The chapter number for each individual file is set up in the Format > Document > Numbering > Chapter. This setting only corresponds to <$chapnum> and does not affect other placeholder autonumbering that you might have used (such as <n> or <n+>).

Back to Basics

Book file settings override settings for individual files.

After you display the Numbering properties for Chapter, you can either set the chapter number to a specific number, or if you are working with a book file, you can set the chapter number to "Continue Numbering from Previous File in Book." If you choose the second selection, the chapter numbers update only after you update the book file.

Setting Up TOC Reference Page Building Blocks

After you set up the Chapter Numbering properties for each individual file, go to the table of contents reference page and add a new Building Block to each line of Building Block structure.

Previously, we saw how the Building Blocks

<$paranum>\t<$paratext>\t<$pagenum>

produced the following:

3.1 The Language of Running 1

3.2 Understanding Pace 2

Now add <$chapnum> - just before the <$pagenum> Building Block. <$chapnum> represents the chapter number that you assigned in Chapter Numbering properties for each individual file. (Consider using the dash to separate the chapter number from the page number.)

Back to Basics

You must update the table of contents to see the results from Building Block changes.

Now you see that these Building Blocks

<$paranum>\t<$paratext>\t<$chapnum>-<$pagenum>

produce this result:

3.1 The Language of Running 3-1

3.2 Understanding Pace 3-2

Text as Prefix

You might require a text prefix for page numbers rather than a number, as discussed in the last section. Using the example of a software manual that consists of both user and reference guides with page numbers designated as UG-1 for the user guide and RG-1 for the reference guide, take a look at how it's done.

For text prefixes, you must consider two features that work hand in hand to get you the results you want:

• The Document Number Property for volume in individual files that are used as source information.

• Redefining the Building Blocks structure on the reference page of the table of contents.

Setting Up the Text Prefix

First, you must adjust the Numbering properties for Volume for each document file. The <$volnum> variable that we'll be using, corresponds to the Volume Numbering properties. From a source document file, follow these steps:

1. Select Format > Document > Numbering. Click the Volume tab.

   The Numbering properties for Volume appears.

2. Use the Format drop-down menu and select Text.

   Text is selected from the drop-down menu and indicates that text will be used to define the Volume variable rather than a number.

3. Type "UG" in the Volume # text field.

   UG is inserted in the Volume # text field. UG is the new definition of the <$volnum> variable. As a result, wherever <$volnum> is used in appropriate places for this file, UG is displayed.

For document files using a different prefix, repeat the previous exercise for each of those files and type the text you want to use in the Volume # text field.

If you are working in a book file, you can set the volume number to "Continue Numbering from Previous File in Book"rather than type the text for individual files.

Redefining the TOC Building Block Structure

After you set up the volume number to text in each document file, the next step is to add the <$volnum> Building Block to the table of contents structure on the reference page.

Previously, you saw how the Building Blocks

<$paranum>\t<$paratext>\t<$pagenum>

produced the following:

3.1 The Language of Running 1

3.2 Understanding Pace 2

Now add <$volnum> - right before the <$pagenum> Building Block. <$volnum> represents the volume number that you assigned in Volume Numbering properties for each individual file. Consider using the dash to separate the chapter number from the page number.

Now you see that the following Building Block structure:

<$paranum>\t<$paratext>\t<$volnum>-<$pagenum>

produces this result:

3.1 The Language of Running UG-1

3.2 Understanding Pace UG-2

Using Hypertext Links

If you have used an online help system of any kind or surfed around on the World Wide Web, you're already familiar with hypertext links. A link on a web page to a URL is essentially the same thing as a hypertext link. You can click on a link on a web page that takes you to a new URL. In an online help system, you can click on an information topic and you are taken to another screen with information about that topic.

Hypertext links are helpful to link information in documents and get you to that information quickly. How does this relate to tables of contents or other lists in FrameMaker? Suppose that you created a table of contents for a 400-page book that you are reviewing in final production.

If you look through the table of contents and see errors, you might want to debug the list items that contain the errors, regardless of what the errors are. In this case, you would have to figure out which document files to open that contain the source information, open those files, and go to that page number. If you used hypertext links in the table of contents, you could simply click on that list item and travel to the exact location of the source information.

If you plan to use documents for distribution as online documents, hypertext links enable users to click on an item in the table of contents and jump directly to the source information. Using hypertext links can greatly enhance a user's experience with online documents, as well as make it easier to debug source information.

Creating Hypertext Links

You might have noticed that, when you first created a table of contents, right below the list of displayed paragraph tags, a check box for Create Hypertext Links exists. If you check this box, the next time you update the table of contents, hypertext links will be included in the list. Figure 8.14 shows what hypertext links look like with text symbols turned on.

Figure 8.14. Hypertext link markers.

Hypertext links in FrameMaker are displayed as markers with text symbols turned on. With text symbols turned off, the markers are still there you just cannot see them.

Executing Hypertext Links

After you include hypertext links in a document, they're easy to use. In a FrameMaker document file, press the Ctrl and Alt keys at the same time and move the cursor over hyperlinked text. The arrow cursor becomes a hand cursor. Continue to press the Ctrl and Alt keys at the same time and move the cursor over non-hyperlinked text; the cursor remains an arrow. In the table of contents, click a hypertext link (indicated by the hand cursor), and the source information to which that hypertext link refers is displayed.

If you are in a View Only document, you do not have to use the Ctrl and Alt keys. Just place the cursor over any hypertext item in the list and the cursor turns into the hand cursor. Then just click on the item. You are taken to the exact location of the source information.

Back to Basics

To make a document view only, select File > Save As > View Only, or toggle View Only with Esc Flk.

Using Run-In Heading Formats in a Table of Contents

You might have seen run-in heads used in documents. With run-in heads, two separate paragraphs can appear on the same line together. Paragraphs appear above or below the previous or next paragraph when they are not run-in heads.

When does a situation come up that would necessitate the use of run-in heads for table of contents listings? Suppose that your source document files contain chapter headings that appear on two separate lines and, therefore, are tagged with two different paragraph tags. Here's how that would look in a document file:

Chapter 9

The Ultimate Travel Guide

Say that the first line is tagged with ChapNum and the second line is tagged with ChapTitle. With this scenario in mind, when you create a table of contents and select both ChapNum and ChapTitle (as well as other tagged paragraphs) to be included, you probably want the chapter number and title to appear on the same line, as is commonly done in a table of contents. However, the result might look something like this:

Chapter 9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

The Ultimate Travel Guide . . . . . . . . . . . . . . . . . 23

You then have to manually fix each line that contains the chapter number and title so they appear on the same line. The next time you update the table of contents, all your hard work is discarded and you're back at square one.

Note

You can click Update All after you make changes to properties within the Paragraph Designer.

That's where run-in heads come to the rescue. After you create the table of contents for the first time, you can perform some paragraph formatting for both ChapNumTOC and ChapTitleTOC so that next time and thereafter, each update of the table of contents can find the chapter number and title on the same line automatically. Here's how to do it:

1. Click one time in a paragraph tagged with ChapNumTOC.

   The insertion cursor is inserted in the paragraph. You can check the status bar to see the paragraph tag name.

2. Select Format > Paragraphs > Designer, Pagination Property.

   The Pagination Properties for ChapNumTOC appears.

3. Type a space in the Run-In Head Default Punctuation text field.

   Run-In Head is the selected format. The purpose of the space is to separate the chapter number from the chapter title. The space is an automatic part of the paragraph tag.

4. Select the Basic tab.

   The Basic Properties for ChapNumTOC appear.

5. Select ChapTextTOC from the Next Pgf Tag drop-down menu.

   Do this step to ensure that the paragraph following ChapNumTOC retains the correct formatting of ChapTextTOC. If a different tag is selected, such as Body, the source information from ChapTextTOC follows ChapNumTOC, but is reformatted with Body instead.

After you complete the Paragraph Designer formatting, you must make changes to the Building Block structure on the reference page of the table of contents. Because these two separate paragraphs now appear on the same line, you want to ensure that the page number Building Block <$pagenum> doesn't appear in between the chapter number and chapter text. The <$pagenum> Building Block should only appear in the paragraph containing the chapter text source information.

Ways to Work with a TOC Template

After you create and format a table of contents for the first time, you can use it over for other documents that use the same paragraph tag names. For example, if you are using a particular FrameMaker template for your documents, the next time you start a new book that uses the same templates for document files contained therein, you can also use the table of contents template to create the table of contents. So, all your hard work to create the table of contents template to begin with is put to good use and saves you time in the long run.

Three methods are explored to accomplish this task:

• Importing formats from a template

• Creating a named TOC file

• Including specifications in document files

All three methods work well and get you the results you need. You might want to determine which one you feel most comfortable using.

Importing Formats from a Template

This first method is fairly straightforward. Here's how it works. For this example, suppose that you start a new book file that includes document files using an existing FrameMaker template:

1. Create a new table of contents for the first time for the new book file. The resulting table of contents file appears plain and might not include all the parts of the source information that you require, such as the autonumber. Now open up the table of contents template that you or someone else created.

2. With the new table of contents file open, select File > Import > Formats. Select the name of the table of contents template from the Source Document drop-down list. Select all the items in the list and click Import.

   All the selected formats are imported from the document.

3. After you complete importing the formats from the table of contents template into the new table of contents, you must update the new table of contents before you see all the changes.

Creating a Named TOC File

Here's another method that you might like to use: Suppose that you created a new book file that contains several document files. All the files are contained in one directory on your computer or on a shared file server. Assume that the name of the book file is sunshine.book:

1. Find the table of contents template that you plan to use for the new book file. Make a copy of this template file and place it in the same directory as the new book file sunshine.book.

2. Change the name of the table of contents template file to the same name as the book file. In this example, you must change the name of the table of contents template to sunshineTOC.fm. Be sure not to change the TOC suffix, or this file won't be recognized as a table of contents file.

3. From the book file, select Add > Table of Contents.

   The Set Up Table of Contents window appears.

4. Select the paragraph tags that you want to include in the table of contents. Then update the book, and the table of contents is created using the existing template format.

Including TOC Specifications in Document Files

This method is more streamlined than the previous two methods, but again, you should use the method with which you feel most comfortable.

You can include the table of contents specifications in a document file that is stand-alone or included in a book file. In other words, if the Building Block structure on the TOC reference page is also part of a document file, when you create a table of contents the first time, that TOC reference page also is automatically included in the created table of contents. In this case, you wouldn't have to adjust the Building Blocks the first time the table of contents is created. You can also include the paragraph tags used in the table of contents in a document file. These are also included in the newly created table of contents, which again saves you from editing those formats.

Here's an easy way to do this:

1. Open the table of contents template and a document file that is included in the book file or stand alone.

2. From the active document file, select File > Import > Formats. Select the table of contents file name from the Source Document drop-down list.

3. Select Paragraph Formats and Reference Pages from the list of items to choose from and click Import.

   Only the paragraph formats and reference page format are imported from the source document.

Now, when you create the table of contents for the first time, it is formatted according to the table of contents information that currently resides on the reference page in the document file.

Using Cross-References

Previously, you reviewed creating a table of contents for a stand-alone document or many chapters in a book file. There are many other ways in which to use tables of contents in documents. For example, you might have a book comprised of many chapters with a master table of contents for the entire book, as well as a mini-table of contents for each individual chapter. This type of table of contents is commonly included in the first page of an individual document file.

You can accomplish this in a few ways. For example, one way is to create the master table of contents and copy and paste those entries for a particular chapter into that chapter file. If you plan to update your table of contents often, this method becomes time-consuming.

Another method is to create a separate table of contents for each individual file and then import that table of contents into its own source file as a text inset.

Although these methods work, they require many steps and maintenance each time the table of contents is regenerated.

Using cross-referencing to create a table of contents for individual files within a book works well to accomplish this task. After you set up the cross-reference format and source information, you can update the information as necessary. If you are working with a book file, the information updates each time you update the book file. Using this method, you would set up the cross-references for each file once and enjoy automated updates thereafter.

Back to Basics

Cross-references update automatically each time a file is opened or printed.

In the section "Building a Cross-Reference Table of Contents" on page 143 in Chapter 5, "Cross-References," you will find the techniques required to create a cross reference table of contents. If you need additional information on cross-referencing in general, you might want to start at the beginning of the chapter.

Other Helpful Lists

In this chapter, I concentrate primarily on creating and updating tables of contents' lists. Many other types of lists are available in FrameMaker. Keep in mind that, regardless of what type of list you want to create or make changes to, the techniques you learned about for tables of contents apply conceptually to any list you can create in FrameMaker.

This section looks at two other lists that you can create in FrameMaker:

• List of Figures

• List of References

The steps to create and configure each list are given in the following sections. You'll undoubtedly notice the similarity to the table of contents' list.

List of Figures

If you create documents that contain many figures, a list of figures is a good way to organize and display figure information. A list of figures may include the number, title, and page on which figures are located.

Here's an abbreviated version of the steps required to create a list of figures. For this example, assume that figure titles in the document are tagged with FigureTitle:

1. Select Special > List Of > Figures. Then move FigureTitle from the Don't Include list on the right side to Include Paragraphs Tagged on the left side (see Figure 8.15). FigureTitle is included in the Include Paragraphs Tagged list. Notice the LOF suffix, which indicates that the name of the file you are creating will automatically have the suffix LOF included in its name.

   Figure 8.15. The Set Up List of Figures window.

   

2. On reference page LOF of the newly created List of Figures, modify the Building Blocks to include the parts of source information required in your list.

   The current Building Blocks <$paratext><$pagenum> correspond to the figure title and page number. You might want to include the figure number. Do this by typing <$paranum> right before <$paratext>. You might want to include a tab before the page number. Do this by typing \t before the <$pagenum> Building Block. The result looks like this on a reference page: <$paranum> <$paratext> \t <$pagenum>.

3. On the body page, modify paragraph formats to include indentations, tabs, fonts, and other formatting features that you require in your list. Notice that each paragraph tag that you selected to be included as source information in the list of figures has the LOF suffix as part of the paragraph tag name. LOF matches the suffix that is also included in the list of figures filename. Paragraph tags with the LOF suffix work exactly like tags with a TOC suffix (tagged text will be replaced each time you update the list of figures).

Back to Basics

After the reference page and formatting changes, you must update the list of figures to see all the changes.

List of References

You might have heard the term importing graphics by reference. When graphics are imported by reference, the graphic doesn't reside in the document file, but outside the file. It's referenced by its location.

Many other types of information references exist in FrameMaker documents. These include condition tags, external cross-references, fonts, text insets, and unresolved cross-references. As you can see, you sometimes must keep track of tons of information in documents.

If you have hundreds of referenced imported graphics in documents files that were contained in a book file, it would be nice to list the actual name and location of each graphic, as well as where it appears in the document file. When using text insets in documents, you might want to keep track of the source material and its location in the FrameMaker documents.

A list of references is the perfect tool to keep track of and organize certain information that's referenced in FrameMaker documents. Here's a sample of what a list of references for imported graphics might look like:

image4/04image01.tif @ 150 dpi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

image4/04image02.tif @ 150 dpi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

image4/04image03.tif @ 150 dpi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

image4/04image04.tif @ 150 dpi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

As you can see, the name of the graphic that was imported by reference is included, as well as the path location to that graphic, the dpi information about that graphic when it was imported and the page number location in the FrameMaker document file.

To create a list of references, follow these steps:

1. Select Special > List Of > References from a single file, or Add > List Of > References from a book file.

   The Set Up List of References window appears, as shown in Figure 8.16.

   Figure 8.16. The Set Up List of References window.

   

2. Choose reference type items on the right side and move to the left side.

The resulting list of references file needs to be set up similarly to how you set up the table of contents. The Building Blocks you will work with are

<$referencename> <$pagenum>

<$referencename> refers to the items being referenced and <$pagenum> refers to the page number location in the document. If you selected more than one reference type to be included, each type of reference item included will have its own paragraph tag. For example, imported graphic references have the paragraph tag ImportedGraphicLOR, while External Cross-Refs eferences have the paragraph tag External Cross-RefsLOR. You can then format each of these paragraph tags accordingly.

Summary

After you create a table of contents or other lists the first time, and go through the steps required to include the information you need and format the look, it's easy to update the TOC later with the latest source information. Not only are generated lists used to map out the contents of certain information in documents for readers, but they are equally useful in keeping track of particular referenced information in documents that are handy to the author or production team.

CONTENTS