New Page 5

• | Table of Contents
 | EEn 777

FrameMaker 6: Beyond the Basics
By Lisa Jahred
Publisher | : New Riders Publishing
Pub Date | : August 14, 2001
ISBN | : 0-7357-1108-9
Pages | : 448
Slots | : 1

FrameMaker's complex functionality can cause problems for even the most advanced user. A simple fix to one problem might throw off multiple functions in your document, which costs you time and money and deters innovation. The key to your success with FrameMaker is to understand the program holistically. Targeted at the intermediate/advanced audience, FrameMaker 6: Beyond the Basics addresses problems professional documentation creators face every day.

Copyright

About the Author

About the Technical Editors

Acknowledgments

A Message from New Riders

Visit Our Web Site: www.newriders.com

Email Us from Our Web Site

Call Us or Fax Us

Technical Support for This Book

Introduction

Who This Book Is For

How This Book Is Organized

How to Use This Book

What's on the Web

Have Fun

Chapter 1. Planning and Organizing Strategies

Saving Time with Templates

File Management

Adding Graphics from Another Application

Summary

Chapter 2. Automatic Text, Tabs, Special Characters, and Graphics

Automatic Text

Automatic Tabs and Special Characters

Automatic Graphics

Creating Lists

Creating Note Text

User Variables in Document Pages

Summary

Chapter 3. Automatic Numbering

Some Background on Autonumbering

The Interrelated Parts of an Autonumber Format

Creating a Numbered List

Creating Numbering Based on Chapter Numbers

Creating Section-Based Numbering

A Note on Book File Numbering

Summary

Chapter 4. Headers and Footers

Practical Uses

The Home of Headers and Footers

What Headers and Footers Are Made Of

Starting with the Easy Stuff

Working with Fixed Headers and Footers That Rarely Change

Working with Varying Headers and Footers

Using Abbreviated Headings

Summary

Chapter 5. Cross-References

Typical Uses of Cross-References

Planning for Cross-References

How Cross-References Work

Understanding the Cross-Reference Window

Cross-Reference to a Subheading

Cross-Reference to a Numbered Figure

Cross-Referencing Other Document Files

Creative Cross-References

Cross-References and Conditional Text

Cross-Referencing in Book Files

Cross-References and PDF or View Only Files

Updating Cross-References

Unresolved Cross-References

Summary

Chapter 6. Table Survival Guide

Charting a Clear Course

Basic Table Elements

Working with the Table Designer

Working with Table Anchors

Table Catalog and Paragraph Tags

Changing Table Styles

Using Table Continuation or Table Sheet

Troubleshooting Heading and Footing Rows

Tables and Text

Table Row Controls

Tables for Figure and Caption Placement

Tables as a Solution for Caution Notes

Using Tables for Section Titles on Left and Right Pages

Summary

Chapter 7. Combining Documents into Books

Why Build a Book

Overview of a Book File

A Word About Planning

Organizing and Managing Book Files

Going Bookwide

How Numbering Works in a Book

Updating File Information

Solving Book File Errors

Summary

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

Chapter 9. Indexing

How Indexing Works

Indexing Decisions

Creating Index Entries

Changing Existing Index Entries

Creating an Index List

Adding Prefixes to Page Numbers

Working with Static Text

Working with an Index Template

Summary

Chapter 10. Two Versions Within One Document

The Benefits of Conditional Text

How Conditional Text Works

Conditional Text Window De-Mystified

Creating Reviewer-Commented Document

Combining Two Conditional Text Documents

Creating Two Versions Within One Document

Summary

Chapter 11. PDF and HTML

Planning Smooth Transitions to PDF and HTML

Converting Documents to PDF

Convert to HTML

Summary

Chapter 12. Converting Documents from Other Applications

Using Practical Methods

The Act of Converting Files

Cleaning Up the Mess

Resolving Formatting Issues

Changing Hard-Typed Numbers to Autonumbering

Changing Hard-Typed Bullets to Automatic Bullets

Table Solutions

Dealing with Graphic Irregularities

Cleaning Out the Catalogs

Summary

Chapter 13. Typical FrameMaker Headaches

Working with Inherited Templates

Understanding Format Overrides

Working with As Is Checkboxes

Fixing Unresolved Cross-References

Working with Missing Fonts

Solving Book File Errors

Adding Page Number Prefixes in Generated Files

Working with Multiple Page Number Styles in an Index

The Running Headers or Footers Appear Empty

The Table of Contents Contains Empty Lines

Freezing Pagination

Excluding the .fm Extension in a Filename Variable

Fixing Tables Imported from Microsoft Word

Including Running Headers or Footers Across Files

Summary

Glossary

Copyright

Copyright © 2002 by New Riders Publishing

All rights reserved. No part of this book shall be reproduced, stored in a retrieval system, or transmitted by any means—electronic, mechanical, photocopying, recording, or otherwise—without written permission from the publisher. No patent liability is assumed with respect to the use of the information contained herein. Although every precaution has been taken in the preparation of this book, the publisher and author(s) assume no responsibility for errors or omissions. Neither is any liability assumed for damages resulting from the use of the information contained herein.

Library of Congress Catalog Card Number: 00-111655

Printed in the United States of America

First Printing: August 2001

05 04 03 02 01 7 6 5 4 3 2 1

Interpretation of the printing code: The rightmost double-digit number is the year of the book's printing; the rightmost single-digit number is the number of the book's printing. For example, the printing code 01-1 shows that the first printing of the book occurred in 2002.

Trademarks

All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. New Riders Publishing cannot attest to the accuracy of this information. Use of a term in this book should not be regarded as affecting the validity of any trademark or service mark.

Warning and Disclaimer

Every effort has been made to make this book as complete and as accurate as possible, but no warranty of fitness is implied. The information provided is on an "as is" basis. The authors and the publisher shall have neither liability nor responsibility to any person or entity with respect to any loss or damages arising from the information contained in this book or from the use of the CD or programs accompanying it.

Credits

Publisher

David Dwyer

Associate Publisher

Al Valvano

Executive Editor

Steve Weiss

Product Marketing Manager

Kathy Malmloff

Managing Editor

Sarah Kearns

Acquisitions Editors

Chris Nelson

Leah Williams

Senior Development Editor

Lisa Thibault

Project Editor

Lisa Thibault

Copy Editor

Sheri Replin

Technical Editors

Brian Keith

George Ritsi

Cover Designer

Aren Howell

Interior Designer

Kim Scott

Compositors

Wil Cruz

Steve Gifford

Proofreaders

Sheri Replin

Jeannie Smith

Indexers

Cheryl Lenser

Christopher Morris

Dedication

For Jessica and Johvan

About the Author

Lisa Jahred is a trainer and consultant based in southern California. Lisa has been a FrameMaker power user since 1991 and is an Adobe Certified FrameMaker expert. She has developed and conducted numerous customized FrameMaker training classes, carried out multi-language publishing projects nationally and internationally, developed hundreds of FrameMaker templates for various companies, and created interior book designs and templates for technical and creative non-fiction titles.

In the early 1990s, Lisa worked closely with Frame Technology Corporation (the original developer of FrameMaker) to help establish the Los Angeles chapter of the FrameMaker User's Network.

Lisa received a B.S. in Quantitative Methods from California State University in the mid-1980s, enjoys world travel and a healthy lifestyle, and is deeply committed to her children.

About the Technical Editors

George Ritsi is the manager of the Technical Documentation department at Orthodyne Electronics, Inc. in Irvine, California. George introduced FrameMaker as the principle authoring program for creating user manuals and other technical documents at his company about six years ago. The books created by his department generally contain many chapters, are richly illustrated with engineering drawings and digital photographs, and contain many generated lists. He finds the features of FrameMaker to be ideal for his work. More recently, the books are being converted to CD-ROM, again utilizing FrameMaker's features. George has had more than 30 years' experience developing technical documents for a number of aerospace and defense companies. George has an MSME degree from the University of Southern California.

Brian C. Keith, of Los Angeles, California, was introduced to FrameMaker in 1988, was quickly converted, and has since transformed himself into a devout and devoted disciple of the "FrameMaker Way." He presided over the establishment of the Los Angeles chapter of the FrameMaker User's Network in the early 1990s and continues to promote FrameMaker as the paramount desktop-publishing application for the production of long documents. Brian garnered a B.A. in English, cum laude, and an M.S. in Mass Communication from Boston University almost two decades ago, and has so far collected more than 17 years of experience in the field of writing.

Acknowledgments

The creation of this book is the result of the efforts of many people, and I thank you all for making this book possible.

Thank you David Dwyer, New Riders publisher, for the great opportunity to write this book.

Chris Nelson, thanks for your participation in this book's earliest stages and numerous brainstorming sessions that helped to shape this book.

Thanks to Leah Williams, acquisition editor. It's been a great pleasure working with you. I could not have written this book without your invaluable guidance every step of the way.

Lisa Thibault, development and project editor, thanks for tending to each chapter and helping me stay organized with the structure of this book's content.

Thank you, Sheri Replin, for being a magnificent copyeditor.

Thanks to Brian Keith, technical editor and dear longtime friend, for reading every word of this book, providing constructive comments and all sorts of good advice—much of which made its way into this book.

George Ritsi, technical editor, thanks for a job well done, and your great suggestions for topics and other tidbits that also made their way into this book.

Thanks to everyone, especially Laura Thommen, who provided encouragement and support in my early FrameMaker days.

Thanks to my parents, Myra and Nick, and friends who are always supportive of my life pursuits; to my long-lost friend, Randee Joseph, for finding me again and filling my e-mail box with an endless supply of fun and reminiscing; and to Brittany Olive Jumanji, my loyal canine companion and her pal Zoe, who doesn't say much these days.

Most of all, thank you Jessica and Johvan, who have been and continue to be a great inspiration in my life.

A Message from New Riders

As the reader of this book, you are our most important critic and commentator. We value your opinion and want to know what we're doing right, what we could do better, in what areas you'd like to see us publish, and any other words of wisdom you're willing to pass our way.

As Executive Editor at New Riders, I welcome your comments. You can fax, email, or write me directly to let me know what you did or didn't like about this book—as well as what we can do to make our books better. When you write, please be sure to include this book's title, ISBN, and author, as well as your name and phone or fax number. I will carefully review your comments and share them with the authors and editors who worked on the book.

Please note that I cannot help you with technical problems related to the topic of this book, and that due to the high volume of email I receive, I might not be able to reply to every message. Thanks.

Email: steve.weiss@newriders.com
Mail: Steve Weiss
Executive Editor
New Riders Publishing
201 West 103rd Street
Indianapolis, IN 46290 USA

Visit Our Web Site: www.newriders.com

On our Web site, you'll find information about our other books, the authors we partner with, book updates and file downloads, promotions, discussion boards for online interaction with other users and with technology experts, and a calendar of trade shows and other professional events with which we'll be involved. We hope to see you around.

Email Us from Our Web Site

Go to www.newriders.com and click on the Contact Us link if you:

  • Have comments or questions about this book.

  • Want to report errors that you have found in this book.

  • Have a book proposal or are interested in writing for New Riders.

  • Would like us to send you one of our author kits.

  • Are an expert in a computer topic or technology and are interested in being a reviewer or technical editor.

  • Want to find a distributor for our titles in your area.

  • Are an educator/instructor who wants to preview New Riders books for classroom use. In the body/comments area, include your name, school, department, address, phone number, office days/hours, text currently in use, and enrollment in your department, along with your request for either desk/ examination copies or additional information.

Call Us or Fax Us

You can reach us toll-free at (800) 571-5840 + 0 (ask for New Riders). If outside the U.S., please call 1-317-581-3500 and ask for New Riders. If you prefer, you can fax us at 1-317-581-4663, Attention: New Riders.

Technical Support for This Book

Although we encourage entry-level users to get as much as they can out of our books, keep in mind that our books are written assuming a non-beginner level of user-knowledge of the technology. This assumption is reflected in the brevity and shorthand nature of some of the tutorials.

New Riders will continually work to create clearly written, thoroughly tested and reviewed technology books of the highest educational caliber and creative design. We value our customers more than anything—that's why we're in this business—but we cannot guarantee to each of the thousands of you who buy and use our books that we will be able to work individually with you through tutorials or content with which you may have questions. We urge readers who need help in working through exercises or other material in our books—and who need this assistance immediately—to use as many of the resources that our technology and technical communities can provide, especially the many online user groups and list servers available.

Introduction

Adobe FrameMaker is famous for its powerful document-publishing features and steep learning curve. Through many versions and improved features, FrameMaker has become an indispensable tool to users creating various types of documentation.

You've undoubtedly felt overwhelmed with FrameMaker at least once. That's why I wrote this book—to make FrameMaker more accessible to you without becoming overwhelmed.

More than 10 years ago, before tables were even included in the menu options, I found FrameMaker. It took about a minute for me to realize how FrameMaker could simplify the process of producing documentation. FrameMaker was a real lifesaver for me while I worked on the production side of large-scale multi-language documentation projects. Although FrameMaker's steep learning curve was painful at times, it was more painful to work in software programs that did not come close to containing the automated features that FrameMaker offered.

Combining my FrameMaker expertise with my computer-teaching skills allowed me to educate others on FrameMaker usage. The real rewards came in teaching users how to get the most out of this powerful software in their everyday documentation tasks. Writing my own user guides and training documents in FrameMaker naturally followed. It's been a pleasure to experience FrameMaker from many different angles.

FrameMaker remains my favorite publishing software program. I composed this book in FrameMaker 6. Unlike other books about FrameMaker, the book you hold in your hands is not a reference book. Because documentation tasks in FrameMaker require you to understand and combine multiple features, I was inspired me to create this task-oriented book. I present you with the principles, techniques, and tips to achieve tasks, as well as the corresponding pitfalls and challenges.

Who This Book Is For

This book is ideal for intermediate to advanced FrameMaker users. You should already be familiar with the basic fundamental operations and have completed, either through experience or training, the introductory levels of FrameMaker topics and commands. The exercises and examples are focused on the task at hand. For example, if we are working on autonumbers, we only work with the Numbering property of the Paragraph Designer. We don't need to waste time with how to create that particular paragraph tag or go into the basic or default font properties, because those are basic FrameMaker skills that you are already familiar with and unimportant to our task. It is my goal to present very focused lessons throughout the book.

This book is not geared towards novice FrameMaker users.

This book is of particular interest to experienced FrameMaker users who

  • Work in FrameMaker on a daily basis

  • Create technical documentation (such as software manuals, user guides, and so on)

  • Create documentation for print, PDF, or web sites

  • Convert files from Microsoft Word to FrameMaker consistently throughout the documentation process.

This book shows you how to optimize the advantages of FrameMaker to create documentation.

How This Book Is Organized

Each chapter contains comprehensive coverage of FrameMaker topics that surpass the basic fundamentals of the program. Inside each chapter, you find an overview and background information on topics, followed by examples to follow. You also find helpful sidebars that discuss topics such as basic commands, tips, and other noteworthy information.

The overall organization is as follows:

  • Chapter 1, "Planning and Organizing Strategies," includes a discussion on what you need to know before you embark on a FrameMaker project.

  • Chapter 2, "Automatic Text, Tabs, Special Characters, and Graphics," teaches you how to work with features to automate a variety of tasks, including combinations of text, tabs, special characters, and graphics.

  • Chapter 3, "Automatic Numbering," gets you acquainted with the concepts and techniques behind autonumbering and you learn the how-to's of constructing a variety of autonumber sequences.

  • Chapter 4, "Headers and Footers," covers the practical uses of headers and footers, what they're made of, and how they work together with FrameMaker's interrelated parts. You explore the concepts behind building, modifying, and using headers and footers to achieve complex tasks and understand some of the pitfalls and tricks in dealing with them.

  • Chapter 5, "Cross-References," explores the typical uses of cross-references and how they work, how to integrate cross-references in documents, and what to do when they misbehave.

  • Chapter 6, "Table Survival Guide," covers a few topics that go beyond table basics, such as header rows, titles, custom ruling and shading, figures within tables, and conversion between table and text.

  • Chapter 7, "Combining Documents into Books," teaches you the benefits of building book files, how to work with a variety of book commands, and how to understand automatic numbering and other automated features after a book file is created.

  • Chapter 8, "Creating Tables of Contents and Other Lists," explains the architecture behind tables of contents and other lists. You learn how to set up and edit lists, create prefix numbering, and solve everyday problems.

  • Chapter 9, "Indexing," helps you make FrameMaker's indexing features work for you. From creating a variety of index entries to controlling the format of the index, this chapter covers a variety of indexing techniques.

  • Chapter 10, "Two Versions Within One Document," focuses on the concepts behind conditional text, appropriate uses of conditional text, and how to create and implement conditional text in documents. You are also shown the pitfalls in working with conditional text along the way.

  • Chapter 11, "PDF and HTML," teaches you about the tools available in FrameMaker for converting documents to PDF and HTML and how your document's criteria fit for either.

  • Chapter 12, "Converting Documents from Other Applications," shows you the best practices to clean up converted Microsoft Word documents quickly and efficiently.

  • Chapter 13, "Typical FrameMaker Headaches," teaches you how to approach and solve some common problems that you might encounter while you work on document projects. This includes the dreaded Missing Fonts error, mysterious templates, and undocumented features.

  • The Glossary provides a list of specialized FrameMaker words and their definitions, along with quick tips.

How to Use This Book

I wrote this book from a Microsoft Windows perspective. As you know, FrameMaker is nearly identical on various computing platforms. Although the conventions used are Windows-based, the basic concepts and techniques discussed in this book can be used equally well by users of various platforms.

Each chapter is independent and stands on its own. Go directly to the chapters that contain topics that interest you, or use the comprehensive index to find the subject of which you are looking. Try out the techniques (presented in the examples) as you go along and analyze the results in your own documents.

The following table shows the various conventions used throughout the book.

Conventions Used in This Book

Convention Example | Description
Format > Document > Numbering | Select the Format menu, then Document in the Format menu list and Numbering from the Document submenu.
Control f | Press the Control Key and lowercase letter f at the same time.
Esc pz | Press and release the Escape key, then press the letter p and release, press the letter z and release.

What's on the Web

Learn even more on how to put FrameMaker's features to good use by visiting www.informIT.com, an online resource center for premium IT content, access to industry experts, training courses, and news. At InformIT, as well as at New Riders' Web site (www.newriders.com), you'll find Lisa Jahred's continuing series of articles on a variety of FrameMaker topics not covered in this book.

Have Fun

Have fun with all the features that FrameMaker has to offer; don't be afraid to experiment. The learning curve might be steep, but it's worth the effort. Getting acquainted with FrameMaker can sometimes be an adventure of discovery. It's an adventure because of the many paths to accomplishing tasks with all their twists and turns. It's also a discovery of the wonders of this software program.


Chapter 1

Chapter 1. Planning and Organizing Strategies

  • Saving Time with Templates
  • File Management
  • Adding Graphics from Another Application
  • Summary

If you planned on writing a technical document, you wouldn't just start writing it without an outline. If you were going on a long road trip, you wouldn't just jump into your car without a map or some prior knowledge of how to get from point A to point B. Whether you're writing, traveling, or doing a multitude of other activities, planning ahead is essential to the success of what you are trying to accomplish.

The same rule applies to working on Framemaker projects. The point of using a robust program like FrameMaker is to automate routine documentation tasks and, therefore, simplify the production process. Without some up-front planning, however, you'd be stuck later in the project frantically trying to correct problems that you could have avoided in the first place.

This chapter presents some things that you should think about before you start a FrameMaker project. I explore a plan to organize files by using templates to ensure consistency across documents, working with a group, and what you need to know about imported graphics. Keeping projects streamlined and organized is a good foundation for a successful project.

Saving Time with Templates

Templates save you time and provide the consistency that's necessary between documents. In a nutshell, a template consists of preset document formats and features that are used as a basis for other documents. Therefore, formats and features do not have to be re-created every time you begin a new document.

Working through a document's formatting and feature requirements in advance helps you to establish document-publishing standards that you need in order to create FrameMaker templates.

After you create document templates that you can work with, use the same template for each new document. For example, say that you're creating a book with 20 chapters. After you create a template for one chapter, you can use that template for each new chapter. This ensures you a consistent format throughout every chapter in the book.

Back to Basics

Use File > Import Formats to import new formatting information to one or more documents.

If you decide to make design changes to the book, you can incorporate those changes into one document file and import the new formatting information into other document files that use the same predefined formats.

Anatomy of a Template

If you dissected a typical FrameMaker template, you would end up with this list of features:

  • Page layouts

  • Paragraph formats

  • Character formats

  • Table formats

  • Color definitions

  • Document properties

  • Cross-reference formats

  • Variable definitions

  • Math definitions

  • Conditional text settings

Although you might not need each feature, keep them in mind while you plan and go through the decision-making process for your own FrameMaker templates.

Planning Templates

Taking the time to plan your FrameMaker templates is worthwhile. For starters, consider the overall ingredients of your publication before you delve into the details. For example, you might ask yourself the following questions:

  • Is there a table of contents or an index?

  • Will I need chapter and appendix templates, or just one or the other?

  • Does my document include a preface or a title page?

After you understand the ingredients that you want to include in your publication, the next step is to determine the document's design and plan the features that each ingredient includes. For example, a template for a title page probably won't include numbered paragraphs, but a chapter template would.

With your overall goals in mind, develop a list of features that you need for each ingredient that makes up your publication. You might ask yourself the following questions during this planning phase:

  • Is automatic numbering part of my document's overall features?

    If so, you must plan out what type of numbering schemes you want to produce in your documents. For example, will you plan for numbered lists that include numbers or alphabetic items? Are just the chapter headings numbered or is military numbering style preferred?

  • Will tables be included in my documents? Will they include rules? How about table titles?

  • Will running headers and footers be included? If so, of what are they comprised?

    For example, if running headers or footers include each chapter's title, you have to consider creating Running Header/Footer variables. If they include the document title, you should consider creating user variables.

  • Do you plan to use cross-references? If so, what types of cross-reference formats?

Note

Download FrameMaker template packs at http://www.adobe.com/products/framemaker/.

After you understand what features your FrameMaker templates need to include, you can create templates from scratch or use an existing FrameMaker template (available from Adobe) and modify it for your own use.

The Inner Workings of a Template

Every FrameMaker document file is also a template. A document file and a template are one and the same. Any FrameMaker file that you open can also be used as a template.

If you use a content-filled document as a template, a new, untitled document opens and includes the complete contents of the source document file. You must delete the contents of the new, untitled document at that time.

To use any document file as a template, follow these steps:

  1. Select File > New > Document.

    The New window appears.

  2. Navigate to the location on either your hard drive or file server and select the FrameMaker file that you want to use as a template. The filename is inserted into the Use Template field.

  3. Click New.

    A new, untitled document opens with the same formatting features of the FrameMaker file that you used as the template.

Test, Test, and Test Again

After you establish the features of your FrameMaker templates and incorporate these features into a document, testing your template before you begin writing is a smart idea. Try out the template with dummy text to test running headers and footers, numbered paragraphs, or any other features that you created. Each feature should work under any circumstance.

If you have the urge to forgo testing your templates, keep in mind that once most of the document is finished, it's more difficult to solve template problems. If you are revising an existing template, go through the same testing process. If problems occur and you import that problematic template into your existing documents, your problem increases tenfold.

Testing and focusing on the logistics of how the template should work must be your first priority when you create or revise templates.

Keeping Your Documents Consistent

Documents do not magically stay consistent, even when you use a slick template. If you're working on a document with your coworkers, everyone must participate in maintaining consistency across documents. For example, suppose that you are working on a FrameMaker project with six coworkers who are contributing to the documents as authors. Although you base each new document on a single FrameMaker template, at any given time, different people work on several documents in various stages. While every person works on a document, they might want to make a slight change to a paragraph tag, a cross-reference format, or some other feature. They might think, "It's just a small change; it's not a big deal." However, it quickly becomes a big deal after you compile the book, which is made up of all these documents. All the little changes that you or your coworkers incorporate makes it difficult to maintain the necessary consistency across documents.

Therefore, it's up to you to maintain some control within your workgroup over documents that are being worked on. The art of keeping documents consistent is up to each person in your workgroup. If someone sees an opportunity for formatting changes in a document, consider that the change be incorporated into the master template and then imported throughout each document in the book (or not at all).

Note

For more information on format overrides, see Chapter 13.

One result of making slight changes here and there to page layouts, and paragraph and tables formats is format overrides. Format overrides mean that a change was made to a particular format that no longer matches the original predefined format. Here's how that works: Say that you have a predefined paragraph tag, Body. Now, for just one paragraph that is tagged with Body, you make a change to one of the Basic properties and apply that change to the currently selected paragraph using the Apply To button. You see an asterisk next to the paragraph tag name in the formatting bar. This asterisk means that the format of this particular paragraph no longer matches the predefined format in the Paragraph Catalog. In addition, a format override message window appears the next time you make changes to that paragraph tag using the Update All button.

To ensure consistency across document files, avoid incorporating formatting overrides into your documents whenever possible.

File Management

If you filed memos and other papers into a file cabinet, you wouldn't just put them into any file folder. Usually, memos or other papers are filed in some alphabetical, numerical, or other order that you determine ahead of time.

In the same way, file management is an important aspect while you work with FrameMaker. This section explores the benefits of organizing your files.

Organizing Your Files

Before you start a new documentation project, plan a file-organization method and then stick with it. The easiest and most logical way to organize your files is in a hierarchical fashion.

For example, say that you create a folder called Project A (see Figure 1.1). The Project A folder houses all the FrameMaker document files that make up a book and subfolders that contain graphic files used throughout each document.

Figure 1.1. Creating folders helps you organize your files.

Putting all the ingredients of a documentation project into a single folder enables you to later move these files to a different location, if necessary. Putting everything into a single folder also ensures that you don't break cross-references and links between document files, referenced graphics, and text insets.

With hierarchical file organization, if you want to move your files to another location, you can easily copy or move the folder that contains all the files. If you use other organizational methods, you have to move all the folders that contain some piece of the project in order to make it work properly in another place. You need to understand more about file location paths to carry out that plan.

File Location Paths

Numerous alternatives exist for how you ultimately decide to organize the ingredients of your FrameMaker projects. Understanding how FrameMaker stores file locations might help you during this phase of the project plan.

If you are importing referenced graphics or text insets, FrameMaker uses relative pathnames (folders and files that are relative to, or within, the current folder). As long as you keep these graphics and text insets in the same relative location, FrameMaker can still find the files if you later move them. If you import a file that is located in a folder which is above or outside of the current folder, however, FrameMaker uses an absolute pathname (an explicit list of folders starting at the highest in the hierarchy).

With absolute pathnames, keeping the files in the same relative location no longer works if you move the files. The path must be exactly the same, which is not possible if you move the files. With that, you have to deal with broken links between document files and referenced graphics or text insets, and cross-reference links between files and book file path locations.

File-Naming Conventions

Although FrameMaker files transfer easily from one hardware or software platform to another, file-naming conventions do not. It's always a safe bet to come up with a nomenclature that can withstand the limitations of any hardware or software platform.

For example, suppose that you created a book file that includes document files and referenced graphics in a computing environment configured for long file-naming.

Say that you move that book file and its included components to a computing environment that is set up for eight-character filenames. In this case, you can expect filenames to become truncated. As a result, the book file does not work properly because it can no longer find the original filenames. In addition, when the filenames change (are truncated), FrameMaker can no longer find cross-referenced files and referenced graphics.

A good, solid file-naming convention is a valuable part of your overall project plan. After you decide on a naming convention, set FrameMaker's Compatibility Preferences, as shown in Figure 1.2 (to get to Compatibility Preferences, go to File > Preferences).

Figure 1.2. You can name your file so it's cross-platform.

Adding Graphics from Another Application

When you create documents in FrameMaker, you often use graphics from other applications, such as Adobe Photoshop, Illustrator, or another graphic program. You have some considerations in deciding what graphic file types work best for your project and whether to import by reference or copy graphics into a document. This section explores those considerations.

File Types

Although FrameMaker supports many graphic file types, you might want to investigate which of these work well for your project. You might ask yourself the question, "How do I plan to work on documents and what will my end product be?" Then find the common denominator that works for all occasions.

For example, if you work in a multi-platform environment, creating and importing graphics that can only be viewed in one computing environment is not always the best solution. Importing graphics at a lower resolution for displaying onscreen is not a good solution if you also intent to print the document.

During the planning phase, experiment with various graphic file types and resolutions and take them through the import, viewing, and printing or PDF process to determine which type provides the best results. Again, if you find this out late in the production process, resaving and reimporting all those graphics will not be fun, especially when you could have avoided it.

Understanding Copied and Referenced Graphics

You have the option to import graphic files by reference or by copying them into a document. Do some experimenting before you begin the actual project to decide which method works best for you. If you decide to change the method later in the production process, and you already incorporated numerous graphics into your documents, you must reimport each graphic.

You choose to import a graphic by reference or to copy the graphic into a document by selecting a radio button in the Import File dialog box, as shown in Figure 1.3. Keep in mind that the radio button that you selected the last time you imported a file becomes the default the next time you import a file.

Figure 1.3. This dialog box allows you to either import or copy a graphic into your document.

Let's review each method's advantages and disadvantages.

Copied Graphics

When you copy graphics into your FrameMaker documents from another application, they become part of your document's file size. This method works well for documents that do not have many graphics (and the graphics are small in size).

What happens to a typical document file after a graphic is copied into it? Suppose that you have a FrameMaker document file that is 35KB and a JPEG image that is 515KB. Now import that image into the document file by copying it. Save the document. The document size now grows by leaps and bounds to 6,596KB! And that's just after copying one graphic into the document. Imagine if you were to import 10 graphics of the same size. Your document file would become too large to easily manage.

Another disadvantage to importing graphics by copying is that if you need to make any changes to the graphic, you must make the change in the source application and reimport the graphic into the FrameMaker document.

Referenced Graphics

When you import graphics by reference into FrameMaker documents from another application, it does not become part of your document's file size. The graphic appears to be part of your document, but it is really referencing a file that's being stored outside of the document.

Given the same scenario from the previous section, what happens when the graphic is imported by reference instead of being copied into the document? With a FrameMaker file that is 35KB and a JPEG image that is 515KB, the FrameMaker document does not grow in size after the graphic is imported. It remains at 35KB (that is, if you did nothing else to the document).

Importing graphics by reference keeps your document's file sizes down and, therefore, makes them easier to manage. Another great advantage is that, if you want to make changes to the graphic, you can make the changes directly to the source application; the next time you view that graphic in FrameMaker, the graphic automatically reflects those changes.

Note

For more information on generating a list of references, see page 261.

A disadvantage to referenced graphics does exist, however. You must pay close attention to the file management of graphics that are being referenced in documents with respect to file location and naming. This is because the graphics are stored outside of the Framemaker document. That's where a list of references can help you. A list of references for imported graphics helps you keep track of referenced graphics for all your documents.

Working with a Group of Coworkers

If you plan to work with more than one person on a project, consider a plan as to how you intend to work together. Take a look at two tasks that you might want to work into your overall plan.

Locking Files When Working over a Network

Note

On a Macintosh, only one person can use a file at one time.

If you work in a Windows environment over a network, understanding file locking reduces confusion for those working on individual files. Say that you stored all the ingredients of a FrameMaker project on a central file server, and each document is to be worked on directly from that file server.

In this case, if more than one person works on a particular document, another person can open the same document, even though it's already in use, and make changes at the same time. This is where understanding how file locking works is important to the success of your project.

Back to Basics

To turn on file locking, select File > Preferences, and click Network File Locking.

You might have seen a file located in the same folder as your original file, named filename.fm.lck. If you have Networking File Locking turned on (see Figure 1.4), this file is automatically created each time you open a FrameMaker document, and it's erased when you close that same file.

Figure 1.4. The Network File Locking preferences.

If someone on the network has a particular file open and a second person opens that file, a dialog box appears. This dialog box provides information about the file, such as the document name, the name of who opened it, the date and time it was opened, and the computer on the network that opened it.

The second person has three choices after opening the file that is already in use:

  • Open for Viewing Only. View the file and not make changes

  • Open Copy for Editing. Create a copy of the file for editing

  • Reset File Lock and Open. Edit the file and reset the file locking

The Network File Locking feature really acts as a warning mechanism for multiple users of the same file over a network. You can always turn off this feature. Regardless of which you choose, decide beforehand how your workgroup should access document files.

Creating a Template Style Guide

Another useful item to have on-hand when you work with a group on document files is a template style guide. Then everyone working on the documents will know what paragraph tag names are used for particular elements in the documents, what table formats to use and when, and understand cross-reference formats or rules about character formatting.

Note

For more information on creating a template style guide, see Chapter 13, "Typical FrameMaker Headaches."

A template guide does not have to be elaborate. You can put together a simple two- to four-page document with each paragraph tag listed with an explanation of what it's used for. If you tag each explanation with the paragraph tag that is being defined, the user of the template has a better idea of what it looks like.

Include all facets of the template in a template style guide. This ensures consistent use of the template across documents.

Summary

Mapping out strategies for your FrameMaker projects is an involved process, but it's an important phase in the document plan that should not be overlooked. Having a plan in place before you start a project helps keep files organized, prevents file path connection failures, ensures the use of a file-naming scheme that works on any platform, and enables others who work on your project to create consistent results.

In this chapter, you discovered the importance of having a plan before integrating more advanced features into your documents. After you find a plan that works, stick with it and use it as a model for future FrameMaker projects.


Chapter 2

Chapter 2. Automatic Text, Tabs, Special Characters, and Graphics

  • Automatic Text
  • Automatic Tabs and Special Characters
  • Automatic Graphics
  • Creating Lists
  • Creating Note Text
  • User Variables in Document Pages
  • Summary

With so many words in the world, it's no wonder that our documents consist of numerous combinations of unique strings of sentences. Combine that text with graphics and formatting elements, such as tabs and bullets, and you're looking at a typical document.

Documents often contain considerable amounts of repetitive text: a few strings that are used over and over in the same manner. This is also true of tabs, special characters, and graphics. You've undoubtedly composed a bulleted list in a document by hand. You know that, for each item in the list, you must type a bullet (or maybe an asterisk or hyphen) and tab (or space) before the interesting part—the unique string of text—even starts. Multiply the number of keystrokes that you use to construct a single bulleted list by the number of bulleted lists that you typically see in a document, and you understand the importance of this chapter.

Repetitive tasks make great candidates for automating and delegating your extra work to the computer. By investing a little time and effort, you can have things automated the way you'd like them to be.

In this chapter, you learn how to work with FrameMaker features to automate various tasks, including combinations of text, tabs, special characters, and graphics. I review real-world examples, ranging from creating bullets and Note or Caution text or graphics, inserting repetitive text throughout your documents, to changing all occurrences of a word in an instant.

How you plan to use automatically inserted text, tabs, special characters, or graphics determines your path to creating these features. In the next sections, you get more acquainted with various methods of automating. This new acquaintance helps you understand how and when to combine different FrameMaker functions to achieve a given task in this category.

Automatic Text

Text can be automatically introduced into a FrameMaker document in two ways: in a paragraph tag or in a user variable. Each method is used in its own way and for its own purpose. The only common thread between them? Both methods are forms of automating text.

Automatic Text in a Paragraph Tag

Automatic text in a paragraph tag is part of the autonumber format of a paragraph tag. When the paragraph tag is applied to any paragraph in your document, the specified text automatically is inserted either at the beginning or end of that paragraph. You cannot edit or spell-check this text in body pages. Changes to this text can be made only in the Numbering property of the Paragraph Designer window. Good uses for this method include short headings, such as "Note" or "Caution", and chapter or figure headings that include the word "Chapter" or "Figure".

Automatic Text in a User Variable

A user variable is an element that consists of a name and a definition which contains text. You create user variables by using Special > Variable. After you create a user variable, you can insert it anywhere into the body of your document or in the master page's headers or footers. The content specified by the user variable's definition appears in the document wherever you insert the user variable. After it's inserted, user variables behave like blocks of text rather than separate characters. If you want to make changes, you have to make them to the definition of the user variable. After you make the changes, all occurrences of that user variable in the document changes instantly. Good uses for this method include a name or title that is used repetitively throughout a document. You can also use this effectively for a temporary name or title that will change later. Insert this name or title throughout the document now, and later change all occurrences instantly.

Automatic Tabs and Special Characters

You can use the Numbering property of the Paragraph Designer to insert tabs, special characters, numbers, and text automatically. Tabs and special characters can be used on their own or in combination with text. Good uses for this method include bullets, dashes, tabs, em dashes, spaces, and other types of symbols that are implemented by using special symbol fonts.

Automatic Graphics

You can implement graphics automatically within the body of your document. The home for such graphics is your document's reference pages. After you place a graphic in a reference frame on a reference page, that reference frame is available through the Advanced properties of the Paragraph Designer. Graphics can be displayed either just above or just below any paragraph within your document, but they can be made to look otherwise. Good uses for graphics within a reference frame include any type of line to be displayed above or below a paragraph or a graphic that's used in conjunction with repetivite items, such as Note or Caution text.

Creating Lists

Various types of lists are commonly used in documents. Lists are usually marked with round or square bullets, various types of dashes, or other symbols. (Numbers also mark a list, but this section focuses on text-based lists.)

Creating a Bulleted List

Note

See Chapter 3 for more information on numbered lists.

Bulleted lists are commonly used in documents to express a group of concepts that are of approximately equal importance and do not fall into a logical sequence. If the concepts do fall into a sequence, it's better to use a numbered list.

To set up a bulleted list in FrameMaker, make each item in the list into a paragraph and tag it with a paragraph tag that properly indents the item and puts the bullet symbol in front of it.

In the following exercise, you learn how to use paragraph formatting to create an item with an automatic round bullet and a tab, as well as how to put that tag into action.

Setting the Autonumber Format

Note

Click on Update All after each change to a Paragraph Designer property. This step is intentionally left out of the steps.

For this exercise, say that you started to create the paragraph tag Bullet in your document. After you include Bullet in the Paragraph Catalog, apply the Bullet tag to a paragraph on a body page of your document.

  1. Enter the Paragraph Designer by selecting Format > Paragraph > Designer. (You can also press Ctrl-M.)

    The Paragraph Designer properties for Bullet is displayed.

  2. Click on the Numbering tab.

    The Numbering properties for the Bullet paragraph tag is displayed.

  3. Click once on \b in the Building Blocks list. The Building Block \b is inserted in the Autonumber Format field. The \b represents a bullet.

  4. Click once on \t in the Building Blocks list. The Building Block \t is inserted in the Autonumber Format field after the \b. The \t represents a tab. The Paragraph Designer window appears, as shown in Figure 2.1.

    Figure 2.1. The Numbering properties for bullets and tabs.

Back to Basics

You can type \b or \t rather than select it from the list. These symbols work on any platform.

Setting the Tab Stop and Indentations

After you include a tab in the autonumber format of the Bullet paragraph tag, you must assign a tab stop to which that tab can move. If you do not assign a tab stop, the tab symbol will be present and it will appear onscreen if you have Text Symbols turned on, but the tab will not affect the location where the subsequent text is placed, as a tab should.

Back to Basics

FrameMaker uses absolute rather than relative tab stops. This means that the nth tab on a line moves to the nth tab stop.

You must also set up the proper indentations to create the hanging indent that is used for bulleted lists. A hanging indent paragraph is a paragraph where all the lines are indented except the first one. Hanging indents are typically used for bulleted and numbered lists. Follow these steps to create a hanging indent:

  1. Click the Basic tab in the Paragraph Designer.

    The Basic properties for Bullet is displayed.

  2. In the Indents pane, type 0 in the First field and .25" in the Left field.

    As a result, only the first paragraph line will begin at 0, flush with the left side of the column, and all the subsequent lines of text will be indented by .25" on the left side.

  3. In the Tab Stops pane, double-click on New Tab Stop.

    The Edit Tab Stop window appears.

  4. Type .25" in the New Position field and select Left under Alignment.

  5. After you finish, click Continue.

    You return to the Paragraph Designer Basic properties. "0.25" L" is displayed in the Tab Stops list, as shown in Figure 2.2. As a result, the beginning of the paragraph text is automatically indented .25" from the left margin and is then aligned with subsequent lines in the paragraph.

    Figure 2.2. Basic properties for bullets (indents and tab stops).
Putting It into Action

After you create the Bullet paragraph tag, using your newfound capability is easy. Just apply the Bullet paragraph tag to any paragraph in your document.

Your newly bulleted items appear, as shown in Figure 2.3. You can see the tab symbol indicated just after the bullet (notice that Text Symbols is on in this view). The resulting bullet is displayed in the Default Paragraph Font of the Bullet paragraph tag.

Figure 2.3. Here's an example of a bulleted list.

Making Square Bullets

When you create a bulleted list by using the \b Building Block, it creates a round bullet. Round bullets are the traditional shape, or the plain vanilla, of bullet styles. If you want to add some pizazz to your documents by using square bullets or an icon, read on.

You can use bullets that consist of special characters. The following instructions show you how to make them.

First, you need to determine the special font that you can use to display the bullet you want. For example, if you want to use a black square, you have to do the following:

  1. In the task bar, click on the Start button.

  2. Select Programs > Accessories > System Tools > Character Map.

    The Character Map window appears. In Windows, Character Map inserts special characters into documents.

  3. Use the Font drop-down list to select a special font, such as Wingdings.

    Characters available for the selected font are displayed.

  4. Click once on the character that you want to use in your document.

    After you click on a character from the display, the keystroke that represents that character is displayed in the lower-right corner of the window. Make a note of this character. In this example, the character that represents the black square symbol is n, as shown in Figure 2.4.

    Figure 2.4. Character mapping in Windows.

Note

Character Map might live elsewhere, depending on your Windows installation. On the Macintosh, select [image] menu > Key Caps.

Now you know which font family can display the bullet that you want to use in your document. However, you cannot simply specify a font name in a paragraph's Numbering properties. Instead, you first need to create a new character tag in FrameMaker that uses this font family, if you don't already have one available.

Say that you have a character format, SqBullet, already included in the Character Catalog, as shown in Figure 2.5. SqBullet uses the font Wingdings, which contains the square bullet, as you discovered in the previous steps.

Figure 2.5. The Character Designer window for the SqBullet tag.

Finally, you need to create the autonumber format for the square bullet in the Paragraph Designer by following these steps:

  1. Set up the tab and indents for the square-bulleted list item paragraph tag in the Basic properties tab of the Paragraph Designer.

    If you want to change all the round-bulleted lists into square-bulleted lists, just modify the existing Bulleted tag. Otherwise, create a new tag.

  2. Switch to the Numbering properties tab and type n in the Autonumber Format field.

    The letter n represents a square bullet in the Wingdings font family.

  3. Click once on \t in the Building Blocks list.

    The Building Block \t is inserted into the Autonumber Format field. This symbol represents a tab that will be displayed following the square bullet in the body of your document.

  4. Click once on SqBullet in the Character Format list, as shown in Figure 2.6.

    Figure 2.6. The Paragraph Designer autonumber format for SqBullet.

    The Building Block SqBullet is inserted into the Character Format field. As a result, the SqBullet tag is applied to the autonumber format. Typed text on the document page will be displayed in the Default Paragraph Font of this paragraph tag. The Character Format list displays only character tags that are already included in your document. If you do not have a SqBullet character tag, you must create it before it will show up in this list.

Using Dashes Instead of Bullets

Now that you understand how to create two different types of bulleted lists, creating a bulleted list that uses dashes instead of bullets should be easy for you. Lists with dashes sometimes represent subentries of one entry in of a bulleted list, although you might have other ideas on how you want to use dashed lists.

Back to Basics

After changing an autonumber format, remember to adjust Basic property indents and tabs accordingly.

You can choose from a variety of dashes to create your dashed list. Table 2.1 gives you a breakdown of how to implement dashes in the autonumber format of the Paragraph Designer, and how they are displayed in documents. Each example also includes a tab as part of the autonumber.

Table 2.1. Dashes in Autonumber Formats

Autonumber Format

How It Is Displayed

Description

-

This is a regular dash.

—

This is an em dash.

–

This is an en dash.

Creating Note Text

Note text is commonly used in documents to emphasize explanations that need to be brought to a reader's attention. Many creative ways exist that allow you to include notes in your documents. For example, you might have seen notes with a line above and below the entire note and the word "Note" in a bold or italic font.

Sometimes notes come in the form of cautions, warnings, and tips. You can use the techniques that you learn in this section to implement any one of these variations. Just substitute the word you want to use where the "Note" heading goes.

In this exercise, you create a note that looks like Figure 2.7. Through this process, you become familiar with a few FrameMaker commands, such as using the autonumber format for text with tabs, including character formats, and implementing and adjusting reference frames used for the lines above and below the note.

Figure 2.7. An example of a note.

Later in this section, you also see how to create a note by using a graphic instead of the word "Note." Without further ado, let's get started.

Adding the Word "Note" as Automatic Text

The first step to adding a note in your document is to create the autonumber format that automatically includes the word "Note" followed by a tab. You need to add a tab or some other kind of spacing to separate the word from the text that you plan to type in the accompanying note text. Automated text is part of the autonumber format of paragraph tags. Suppose that you have begun to create a paragraph tag called Note. This example begins in the Paragraph Designer on the Numbering tab for the Note paragraph tag:

  1. Type "NOTE:" in the Autonumber Format field.

    The word "NOTE:" is inserted into the Autonumber Format field. As a result, the word "NOTE:" is displayed in document pages each time the Note paragraph tag is assigned to a paragraph.

    This example is given in all caps to bring a reader's attention to the note. If you prefer, use small letters instead or a combination of both. If you want to use punctuation other than a colon, type the characters you prefer instead. Experimenting is the spice of life.

  2. Click once on \t in the Building Blocks list.

    The Building Block \t is inserted into the Autonumber Format field following the word "NOTE:". The \t does not yet have a tab stop in which to move, but the tab symbol appears after you apply this paragraph tag to a paragraph.

  3. Switch to Basic in the Paragraph Designer and create the necessary tab setting.

    Create a tab stop in the same way as you created the Bulleted paragraph tag earlier in this chapter. However, the tab position in this case must be far enough to the right to clear the word "NOTE:" and leave some space before the text begins.

  4. In the Indents pane, type 0 in the First: box. In the Left: box, type the same number that you used for the tab stop in step 2.

Back to Basics

Click Update All after you make changes to a Paragraph Designer property window and before you move to another property.

Adding Character Formatting to Your Note

Back to Basics

Character tags must exist in order to show up in the Character Format list in the Numbering Properties window.

The autonumber format is almost complete. The last thing you'll have to do in Numbering properties is set the character formatting to bold for the word "NOTE." Remember that in our example as seen in Figure 2.7, the word "NOTE:" is bold but the typed text is not. Because autonumber text is not editable on the body page, you must apply the character format using the Numbering properties.

Check the Character Catalog for a Bold character tag. If you do not have a Bold character tag, you must create one first. After you create one, continue with the Numbering properties:

  1. Switch to Numbering in the Paragraph Designer.

    Character formats in autonumbers are applied in the Paragraph Designer Numbering property.

  2. Click once on Bold in the Character Format list.

    The word "Bold" is inserted into the Character Format field. This means that the Bold character tag will be applied to only the autonumber format of any paragraph tagged with the Note paragraph tag.

The completed autonumber format looks like Figure 2.8.

Figure 2.8. The completed autonumber format for the note.

Adding Lines Above and Below Your Note

You're almost finished! With the autonumber format and basics out of the way, you can add a nice touch to the notes by including a single line above and below the text. These lines are sometimes known as rules.

In this section, you work with the Advanced properties of the Paragraph Designer, although the single line is actually stored on a reference page within a named reference frame. In this case, the single line already exists in the document because it's part of FrameMaker's default reference frames. To add rules to your notes, do the following:

  1. Click on the Advanced tab in the Paragraph Designer for Note.

    The Advanced properties for Note appears.

  2. Select Single Line from the Frame Above Pgf drop-down list.

    Single Line is selected. As a result, a single line is displayed above any paragraph tagged with Note.

  3. Select Single Line from the Below Pgf drop-down list, as shown in Figure 2.9.

    Figure 2.9. The Advanced property settings for the notes.

    Single Line is now selected; a single line is displayed below any paragraph tagged with Note.

Congratulations! You just created a handy note format to use in your documents.

Adjusting Lines Above and Below Text

Times might arise when you want to make an adjustment to the graphics within reference frames, whether they become part of the document through FrameMaker's default setting or you create them.

Take a look at the note you created in the previous sections. The single line above the note has more space between it and the text than the single line below (see Figure 2.10). Because the spacing is uneven, your document might look unprofessional.

Figure 2.10. Incorrect spacing in your notes gives your document an amateurish look.

Adjusting the spacing above and below the text using the Basic properties does not change the uneven amount of spacing between the text and each line. That change only adjusts the space above and below the lines because they are treated as part of the paragraph.

To adjust the spacing of the single lines, follow these steps:

  1. Select View > Reference Pages.

    The first reference page appears. You see a variety of lines (graphics) within the reference frames, accompanied by the names for each reference frame.

  2. Look at the reference frame that's labeled Single Line.

    Notice how the single line is aligned to the top of the reference frame (see Figure 2.11). This means that, when it's included as part of a paragraph tag, the amount of space between the line and the bottom of the reference frame will be also be included above or below paragraphs.

    Figure 2.11. The original single line reference frame.

  3. Click one time on the single line within the reference frame to select it.

    The single line is selected.

  4. Press Alt + down-arrow key to move the single line down toward the middle of the reference frame (see Figure 2.12).

    Figure 2.12. The adjusted single line reference frame.

    The single line is displayed horizontally in the middle of the reference frame.

  5. Select View > Body Pages.

    The body page of the document appears. Any existing paragraphs that use the single line reference frame adjusts on their own, as shown in Figure 2.13.

    Figure 2.13. The adjusted note has even spacing and a professional look.

Creating an Automatic Graphic Icon in Note Text

You might have noticed in the last section that when you include a graphic as part of a paragraph tag, the Paragraph Designer can put the graphic either above or below the text of the paragraph, but does nothing about putting the graphic to the left or right at the same height as the text. If you want to include a graphic icon as part of the paragraph tag, but have it appear to the left or right of text, you have to get more creative with the method in which you implement this into your documents.

In this section, you learn how to set up a graphic icon stored on the reference page to include as part of a paragraph tag. You are then presented with two methods to implement an automatic graphic that will be displayed to the left of text: The first method is implemented using side heads, and the second method uses a table.

Setting Up the Graphic Icon

In order for the graphic to automatically be included as part of the paragraph tag, you must create a new reference frame on the reference page and import the graphic you want to use for your note. Here's how to do it:

Back to Basics

Select Graphics > Tools to show the Graphic Toolbox.

  1. Select View > Reference Pages.

    The first reference page appears. As noted in the section, "Adding Lines Above and Below Your Note," several reference frames are already included on this page as part of FrameMaker's default settings.

  2. Select the Place a Graphic Frame tool from the Graphic toolbox, as shown in Figure 2.14.

    Figure 2.14. The Place a Graphic Frame tool in the Graphic toolbox.

    Draw a box-shaped reference frame on the left side of the reference page. The cursor changes to cross hairs. The box shape you draw is inserted on the reference page, and the Frame Name window appears.

  3. Type Note in the Frame Name text field, as shown in Figure 2.15. Click on the Set button when you finish.

    Figure 2.15. The Frame Name window.

    "Note" is inserted into the Frame Name text field as the name of this reference frame. Therefore, "Note" is displayed in the Advanced Properties drop-down lists for both Frame Above Pgf and Frame Below Pgf. The word "Note" is not inserted as a label on the reference page.

Tip

To change the frame name later, click once on the reference frame and select Graphics > Object properties.

  4. Click once on the reference frame to select it. Select File > Import > File and import the graphic that you want to use for the icon in your notes.

    The graphic you select is inserted into the reference frame. Arranging the graphic to the left or right within the reference frame affects its location when viewed on body pages. In Figure 2.16, the graphic icon is placed to the upper-right corner of the reference frame.

    Figure 2.16. The graphic icon for notes in its reference frame.

    The entire reference frame is displayed when the frame is included in a paragraph tag. After you incorporate the frame using one of the two methods described in the following paragraphs, you might have to adjust both the size of the reference frame and the position of the graphic within the frame (but not the position of the reference frame on the reference page) to get the graphic to look good on body pages.
Including a Graphic Icon in a Side Head

The following solution to implement a graphic icon into a note works well if you already use the side heads in your documents. If you do not, it's not worth the effort to include side heads because the graphic icon for the note would be the only element that needed a side head setup. Instead, use the procedure described in the next section, "Including a Graphic Icon Note as a Table," if you do not currently have side heads in your document.

Figure 2.17 shows the end result of following the upcoming step list. Borders and text symbols are on so that you can see exactly where things are.

Figure 2.17. An automatic graphic note icon in side head text.

First, you must modify the paragraph tag that will include the graphic icon for notes. In this example, the paragraph tag is called NoteIcon. The steps are as follows, beginning in the Paragraph Designer for NoteIcon:

  1. Click on the Advanced tab for NoteIcon.

    The Advanced Properties window appears.

  2. Select Note from the Below Pgf drop-down list.

    Note is selected in the Frame Below Pgf field. As a result, the reference frame note containing the graphic icon is included as part of this paragraph tag.

Next, you have to adjust the Pagination properties for this paragraph tag, which contain the side head setting:

  1. Click on the Pagination tab in the Paragraph Designer for NoteIcon.

    The Pagination Properties window appears.

  2. Select the Side Head radio button, and select Top Edge from the Alignment drop-down list, as shown in Figure 2.18.

    Figure 2.18. The Pagination properties for NoteIcon.

    With Side Head and Alignment: Top Edge selected, the top edge of the reference frame containing the note graphic icon will be displayed evenly with the top edge of the first line of text that appears in the normal column to the right.

Next, you need a paragraph tag (or NoteText) for the note text that appears to the right of the graphic:

  1. For this tag, select In Column in the Pagination properties in the Paragraph Designer.

  2. If you want some space below the note, you must set the amount of space in the Below Pgf field in the Space pane (in Basic properties).

To set a note with its icon, insert a NoteIcon paragraph into a body page on your document, followed by a NoteText paragraph. You might notice two problems:

  • First, a paragraph symbol above the note icon pushes the icon down so that it does not align with the top edge of the note text.

  • Second, if you used the Basic properties in the Paragraph Designer for the NoteText paragraph tag to specify spacing above the note text, that space doesn't appear.

Both of these problems can be solved in the Paragraph Designer for the NoteIcon paragraph tag. The reason these changes have to be made in the NoteIcon paragraph rather than the NoteText paragraph is that the NoteIcon paragraph appears first and its top edge alignment overrides all the spacing above the paragraph that follows it. Follow these steps:

  1. To solve the top alignment problem, select the Default Font properties and enter 1pt in the Size box.

    The font size will be set as small as possible (which can be 2.0 pt).

  2. Select the Basic tab and set Above Pgf in the Space pane to the desired value.

Notice that, although you can control the spacing above the note icon, you cannot control the spacing below the note icon. You can control only the spacing below the note text.

Including a Graphic Icon Note as a Table

If you are not using side heads in your document, you can easily include a graphic icon note by treating it like a table. After you have the reference frame and note text paragraph tags set up, insert a two-column, one-row table into your document. Apply the NoteIcon paragraph tag to the cell on the left and the NoteText paragraph tag to the cell on the right. (In this scenario, the NoteIcon paragraph tag should not be set up as a side head.) Then use the Table Designer to make adjustments to the table, including any lines or shading you might want.

Note

For more information on the use of tables, see Chapter 7.

One important thing to keep in mind when you include the graphic icon in a table cell is that you have to adjust the position of the graphic inside the reference frame. For example, Figure 2.19 shows the graphic inside a large reference frame and shows how this graphic is displayed in the table cell. Because the reference frame is so much larger than the graphic, there is much additional white space in the table—in both the left and the right cells. But if you make that table cell smaller, the graphic is cut off.

Figure 2.19. Before adjustment, the reference frame looks too close to its text.

In Figure 2.20, on the other hand, the reference frame has been adjusted to fit more closely to the graphic inside. As a result, no space appears around the graphic as it's displayed within the table cell, and the right cell is not excessively enlarged, either.

Figure 2.20. After adjustment, the reference frame looks just right.

You might have to adjust graphics within their reference frames differently in order to make them look pleasing to the eye.

User Variables in Document Pages

A user variable is an elegant way to insert text, such as a short phrase, in numerous places throughout your document and be able to change all of them at once later. User variables can be displayed in body pages and also in document headers and footers located on master pages.

Note

For more information on headers and footers, see Chapter 4.

Before you get started with the "how-to's" of user variables in document pages, you might be wondering how you might actually use this type of variable. Here's an example: Say that you are working on documentation for a newly developed software product. The formal name of the product, by which the consumers will know it, won't be determined for a couple of weeks, but you are writing the documentation now. What can you do when the software is mentioned by name throughout the documentation?

This situation can be easily handled with a user variable. You can create a user variable to represent the name of the software. Call the user variable something like ProductName. Define the ProductName user variable to be a temporary name for the product, which might be the company's internal code name for the product ("Stealth-X") or the customer and job ID ("C0123-2002-001"). Next, instead of typing that temporary name in each location where the software product is mentioned by name, simply insert the ProductName user variable. Later, when the real name of the product is formalized, you can instantly change the definition of ProductName, and each occurrence throughout the document will update automatically. What a time saver!

Back to Basics

If files are included in a book, update all the files which contain that user variable at one time by using book-wide commands.

Next, see how to create the user variable, insert it in text, and then edit and update it later.

Creating a User Variable

In this exercise, you discover how to create the user variable to represent the software name:

  1. Select Special > Variable.

    The Variable window appears.

  2. Click on Create Variable.

    The Edit User Variable window appears.

  3. Type ProductName in the Name field.

    ProductName is the name of this variable. The name is displayed in the Variable List window.

  4. Type Stealth-X in the Definition field, as shown in Figure 2.21.

    Figure 2.21. The name of "Stealth-X" software product as a user variable.

    This is the name that is displayed wherever this variable is inserted in the document.

  5. Click on Add > Done.

    The Variable window reappears. The new user variable name is added to the Variables list and is highlighted.

  6. Click on Done.

    You return to the document page.

Note

Click somewhere in the body of the document; otherwise, the Variable menu will not be available.

Inserting a Variable in Text

Now that you created the variable that contains the name of the software, it's time to insert the variable where it's needed in your document:

  1. Place the insertion cursor at a location where you want to insert the variable.

  2. Select Special > Variable.

    The Variable window appears.

  3. Click once on ProductName to select it.

    The user variable name is highlighted in the variable list. You can see its definition displayed below the list.

  4. Click on Insert.

    The user variable definition will be inserted at the insertion cursor location.

Tip

You can copy and paste the variable instead of selecting Special > Variable each time.

Whether you insert this user variable in a chapter heading or a body paragraph, it will take on the characteristics of whatever paragraph tag has been applied to that paragraph (see Figure 2.22).

Figure 2.22. The user variable inserted into the body page.

Editing and Changing the Definition

After the variable is inserted in various locations throughout the document, you can change the definition of that variable and update all occurrences at one time. In this example, here's what to do when you completed writing the software documentation and now have the formal name for the software. For example, use "Technomaniac" as the actual name that replaces the temporary name "Stealth-X":

  1. Double-click on Stealth-X in any location where it appears in the document, or select Special > Variable and select ProductName.

    The Variable window appears with the ProductName variable selected.

  2. Click on Edit Definition.

    The Edit User Variable window appears.

  3. Change the text in the Definition field to Technomaniac, as shown in Figure 2.23.

    Figure 2.23. Edit the definition of ProductName.

    After you finish, click on Done.

    The Variable window reappears. The new variable definition is displayed below the variable list, when ProductName is selected in the list.

    Click on Done, not Replace.

    As a result, all occurrences of this variable automatically update and display the new information. Do not click on Replace; that simply replaces the current selection, which is just an instance of the user variable in the first place, with the user variable.

Summary

Automatic text, tabs, special characters, and graphics are underrated features that add great value when it comes to productivity in producing documents. That value is the whole point of using FrameMaker in the first place: to enhance productivity through automating as many things as possible.

In this chapter, you explored some methods that implement automated text and bullets and you learned how to create note text or graphics for your documents. You also glimpsed at variables in the form of a user variable. All these tools are just a few of the powerful automation features in FrameMaker. Use them to your advantage and don't be afraid to experiment. You never know what innovative new tricks you might come up with.


Chapter 3

Chapter 3. Automatic Numbering

  • Some Background on Autonumbering
  • The Interrelated Parts of an Autonumber Format
  • Creating a Numbered List
  • Creating Numbering Based on Chapter Numbers
  • Creating Section-Based Numbering
  • A Note on Book File Numbering
  • Summary

From computers to time and musical beats to universal logic, numbers play a central part of what makes the human world go round. In documents, numbers give a fixed order to things, such as steps in an exercise or categorization of topics within topics. Such an ordered sequence is often necessary for successful organization and structure in documents of any kind.

When numbers are entered into documents manually, making changes to those numbered paragraphs can be a daunting task. Throughout the writing process, editing documents happens often. Each time something within an ordered sequence is moved or deleted, all items before and after the number must be manually renumbered to reflect the change. If you've had the "pleasure" of carrying out this manual task, you know that it can be cumbersome at best. Luckily for us, that's where FrameMaker's autonumbering feature comes in.

In documents, autonumbering does just what its name implies: It automatically numbers your paragraphs so you don't have to. After autonumbers are incorporated into documents, the task of manually renumbering any numbered paragraph is almost totally eliminated. Autonumbered paragraphs always adjust themselves as the document changes. We could almost say that autonumbering provides error-free numbering in documents. In the real world, however, mistakes happen, and we have to seek solutions for those mysterious numbering anomalies.

In this chapter, you acquaint yourself with the concepts and techniques behind autonumbering in FrameMaker. You are also presented with examples of how to construct a variety of autonumbering sequences for chapter heads, appendixes, subheads, figures, tables, and more.

Whether you are just starting to use autonumbering or you use a template, this chapter gives you the information you need to go behind the scenes in FrameMaker with confidence.

Some Background on Autonumbering

Before I discuss autonumbering with some real examples and how-to's, here's some background information on the subject. If you prefer to jump right into autonumber how-to's, skip to the section "Creating a Numbered List."

Back to Basics

Use Format > Paragraphs > Designer to access Paragraph Designer (or use the keyboard shortcut Control-M).

Numbering in FrameMaker is one of six sets of paragraph properties, which you can specify in the Paragraph Designer. After numbering is set up in the Paragraph Designer as part of a paragraph tag, you can simply put it into action by applying that paragraph tag to a particular paragraph within your document. The numbering automatically increases by 1 for each successive paragraph tagged with that same paragraph tag.

Number Series

Your documents might contain numbered headings, lists, figures, tables, equations, exercises, or other types of numbered items. Each numbered item can be implemented as a paragraph or set of paragraphs. Each type of numbered paragraph can either be numbered independently of other types of numbered paragraphs or have its numbers relate to other numbered paragraphs. In the world of FrameMaker, paragraphs with related numbering are known as a number series. Understanding what number series are all about will help you to create flawless autonumbering at the start and to cope with numbering problems that may crop up later.

Independent and Related Number Series

Here's how a number series works: Say that you have numbered tables and numbered figures in a document. The table numbers start with 1 and count up from there, and the figure numbers also start with 1 and count up from there. These two series are separate entities, so they should be numbered independently.

On the other hand, two number series might be related to each other—that is, they have everything to do with each other. For example, if the table and figure numbers were related, a table might appear first in a document called Table 1, followed by the first figure called Figure 2. You might have already experienced this type of numbering within your documents.

Series Labels

Series labels indicate whether the number series of two or more numbered paragraph tags are correlated or independent of each other. Series labels are specified in the Autonumber Format field of the Paragraph Designer and consist of a letter followed by a colon; for example, "F:" for figures. If two paragraph tags have the same series label in their Autonumber fields, their numbers belong to the same series. If not, their number series are independent of each other. Be careful with series labels because the letters are case-sensitive. For example, "F:" identifies a different series than "f:". If a paragraph tag has no series label, its number series is independent of any other autonumbered tag that does have a series label.

You get more clarity and hands-on experience with series labels as you carry out the exercises presented later in this chapter.

Defining Characteristics of a Number Series

Each number series that you include in your documents must have two specified characteristics: numbering style and starting number. You need to keep both of these features in mind when you create numbered paragraphs in your documents.

Numbering Style

FrameMaker offers five basic numbering styles from which you can choose:

  • n. Arabic numerals (1, 2, 3 ...)

  • A. Uppercase alphabetic (A, B, C ...)

  • a. Lowercase alphabetic (a, b, c ...)

  • R. Uppercase Roman numerals (I, II, III ...)

  • r. Lowercase Roman numerals (i, ii, iii ...)

The numbering style you choose to use for various number sequences in your documents is up to you. After you start to go through some of the exercises, you will get better acquainted with numbering styles. Experiment with the various numbering styles to get a feel for how this works. Don't limit yourself to the particular numbering style I work with in the exercises.

Starting Number

FrameMaker offers three possible ways to specify how the autonumber is to be calculated. The calculation is specified by a suffix after the letter that indicates the numbering style:

  • No suffix. Number is the same number as that of the previous item in the series.

  • +. Number is one greater than that of the previous item in the series.

  • =n (where n is a number). Number is equal to the nth number in the selected number style. (For example, "a=6" causes "f" to be displayed.)

You can start a numbering sequence with any number you choose. You don't need to do this often, but it is essential in certain circumstances. Say that you have several numbered lists in your document that must be numbered sequentially beginning with 1. If you have a numbered list on a page that contains six items numbered 1 through 6, and a different numbered list using the same paragraph tag on a later page, the first item in the later list would be automatically numbered 7. That makes a certain kind of sense, because this is autonumbering, but it isn't what you had in mind.

Fixing this problem is where the starting number comes in. For this type of list, you need two different paragraph tags. One paragraph tag (called, say, "NLfirst") will have a starting number of 1, whereas the other tag (called, say, "NLnext") will have a number that increases by 1. After you create these tags, apply the NLfirst paragraph tag, which has a starting number of 1, to the first item in each list. This resets the first item to number 1. Apply the NLnext tag to the subsequent items in the list, and they will be numbered correctly.

Series labels are also needed in this situation. You certainly want to relate these two paragraph tags to each other. Otherwise, it does you no good to have the NLfirst tag reset the starting number to 1, because the following NLnext tag would just pick up the numbering where it left off at the end of the previous list. Therefore, the NLfirst and the NLnext tag must have the same series label (for example, "N:"). Later in this chapter, I explore examples of numbered lists and how to create and use them in documents.

Including Text in Autonumbering

Autonumbering is not limited to numbers. You can use autonumber formats to insert text or symbols automatically in paragraphs. For example, you might want to include the word "Figure" along with the figure numbers, or the word "Chapter" with numbered chapter headings. These insertions are not numbers per se, but they can be set up as part of the autonumber format. Also, you can set up an "autonumber" format that doesn't include any numbers at all. Text in autonumbers make an appearance in some of the exercises presented later, but the focus of this chapter is the construction and use of numbers.

Note

For more information on using autonumber formats to insert text automatically, see Chapter 2.

The Interrelated Parts of an Autonumber Format

Now that you have some background information on autonumbers, you're ready to get started with a more in-depth look at the inner workings of numbering and the various parts that make up the whole series.

In this section, you explore the Numbering properties in the Paragraph Designer, their Building Blocks, and the Numbering properties of the document. The last of these groups relates to the document file, whereas the first two relate to individual paragraphs. Although actual autonumbering is defined in the Numbering properties of the Paragraph Designer, you can use other FrameMaker features that work hand-in-hand with autonumbering. It's important that you understand how FrameMaker's interrelated parts work together to produce the outcome that you are looking for.

Note

For more information on book files, see Chapter 8.

If you have not yet created numbering in FrameMaker, you might want to read through this section to gain some familiarity and come back to it later. If you have already created numbering in FrameMaker, this section might help clear up some things for you.

You also find out how particular settings work for numbered paragraphs within files included in a book. The next sections briefly discuss when and why to use certain numbering settings when files are included in a book.

Understanding the Numbering Properties Window

Back to Basics

Use Format > Paragraphs > Designer to access Paragraph Designer (or use the keyboard shortcut Control-M). Then click the Number tab.

You work with the Numbering properties to construct, troubleshoot, or edit autonumber formats. The Numbering properties window (see Figure 3.1) is a page of the Paragraph Designer and comprises the Autonumber Format field and the Building Blocks, Character Format, and Position lists.

Figure 3.1. The Numbering properties window in Paragraph Designer.

Here is a run-down of how each item contributes to autonumbers:

  • Autonumber Format

    Select the check box to indicate that there is an autonumber format for a particular paragraph tag. You can use the Autonumber Format field to insert the combination of series labels, Building Blocks, text, symbols, and tabs that make up the autonumber in documents. When autonumber information is present in this field, the check box is automatically checked when this window appears. It will be turned on automatically if you click in the Autonumber Format field. To eliminate autonumbering from a paragraph tag, uncheck the check box (by clicking it two times) at any time and update the paragraph tag. Doing so automatically clears the Autonumber Format field.

  • Building Blocks

    Building Blocks are counters or placeholders that you insert in the Autonumber Format field by selecting them from the Building Blocks list. Fifteen of the Building Blocks represent the different combinations of numbering style and starting number. In the document, these Building Blocks will be replaced by autonumbers computed and presented according to the selected starting number and numbering style. Two more Building Blocks, <$chapnum> and <$volnum>, can be applied when you want to display the chapter or volume number. The starting number and style for these particular Building Blocks cannot be set in the Paragraph Designer Numbering properties; instead, they must be set in the Document Numbering properties. Finally, the \b and \t Building Blocks insert a bullet and a tab, respectively.

  • Character Formats

    These are the character format tags that are included in the Character Catalog in your document. Use character formats to apply a character format to only the autonumber portion of a paragraph. That is, the character format will be applied to the autonumber of the paragraph, not to the text.

  • Position

    Use this to specify where numbering is displayed: at the beginning or at the end of a paragraph. Usually, numbering appears at the beginning of a paragraph. There are cases in which an autonumber at the end of the paragraph is useful, such as numbered displayed equations. Again, the choice is yours.

Understanding Building Blocks

Building Blocks are the key to autonumbering. They represent number counters, placeholders, styles, tabs or bullets, and chapter or volume numbers. They don't seem like numbers at all when they're inserted in the Autonumber Format field, but they reveal themselves as numbers on document pages.

You use Building Blocks in the Autonumber Format field to construct a model of the numbering scheme that you want to use in documents. Table 3.1 lists various building blocks and why they are used. This helps serve as a basis for understanding before you move through the exercises. The Building Blocks that begin with <r, <R, <a, and <A work exactly the same as Building Blocks beginning with <n. The only difference is that they display different numbering styles, as described in the earlier section "Numbering Style."

Table 3.1. Defining Building Blocks

Use this Building Block...

To Do the Following...

\b

Insert a bullet.

\t

Insert a tab.

<n>

Insert a number that keeps the same value as the number at this position in the format in the previous paragraph of this series. For example, if the previous autonumber with series label N: was N:<n+> and showed as 3 in the document, N:<n> will also be shown as 3.

<n+>

Insert a number that is one greater than the number at this position in the format in the previous paragraph of this series.

<n=1>

Set the value of the number at this position in the format, for reference by subsequent paragraphs in this series, to 1 (or whichever number follows the equal sign) and display that value.

<$volnum>

Display a volume number as specified for the document in the Numbering properties window.

<$chapnum>

Display a chapter number as specified for the document in the Numbering properties window.

< >

Keep the value of the number at this position in the format the same as in the previous paragraph of this series, but not display the value.

< =0>

Set the value of the number at this position in the format to zero for reference by subsequent paragraphs in this series, but not display the zero. This Building Block is not shown in the Building Blocks list. To use this, you have to type it.

Building Blocks might still seem like a foreign language to you. At this point, they probably are. But, after you see them in action, Building Blocks will make more sense, and you'll be an expert at them in no time.

Understanding Document Numbering Properties

If you want to use the Building Blocks <$chapnum> and <$volnum> to include the chapter and volume in an autonumber format, you need to set the value and style of these variables by using your document's Numbering properties for chapter or volume, as well as book settings. You also use document Numbering properties for paragraph when document files using counter or placeholder numbered paragraphs are included in a book.

Back to Basics

Use Format > Document > Numbering to view the Numbering Properties window for chapter, volume, and paragraph.

It's likely that you might use a combination of all these numbering sequences in documents. Here's an overview of Document Numbering properties. You might want to return to this section after you go through some of the exercises in this chapter to gain clarity on the subject or to help troubleshoot settings in existing templates.

Back to Basics

When using <$volnum>, the Document Numbering properties for volume work just like those for chapter.

Chapter

Click on the Chapter tab in the Numbering Properties window to access the Chapter settings for this document (see Figure 3.2). You need this property only when paragraph autonumber formats include the <$chapnum> Building Block. Table 3.2 shows the settings available in this window.

Figure 3.2. The Chapter tab allows you to access the chapter settings for your document.

Table 3.2. Chapter Settings for a Document

Setting

Description

Chapter #

Use this field to set the chapter number for this document file. For example, if you want a chapter to be 9, type 9 in this field. This field accepts numbers, not letters or Roman numerals. For example, if you want your chapter to be Appendix D, then type 4 in the Chapter # field.

Format

Use this property to set the number style. For example, if you use <$ chapnum> for appendixes and this file is to be Appendix D, select ALPHABETIC (N) from the Format drop-down list to set the number style to A, B, C, and so forth. If you want to use lowercase Roman numerals, select roman (xiv) from the drop-down list.

Continue Numbering From Previous File in Book

Select this radio button if the file is included in a book and you want the chapter number to be one more than that of the previous file in the book.

Use Same Number As Previous File

Select this radio button if the file is included in a book and you want the chapter number to be the same number as the previous file in the book. For example, if Chapter 3 is very large and you split Chapter 3 into two separate files, you would want the second file of Chapter 3 to use the same number as the first file of Chapter 3 and not increment by 1

Back to Basics

Each document file uses one page number style, and each number series can use a different number style.

You'll see more of the document Numbering properties for chapters when you create chapter number-based paragraph numbering later in this chapter in the section "Creating Numbering Based on Chapter Numbers."

Paragraphs

Click on the Paragraph tab in Numbering properties to access its settings (see Figure 3.3). You use this property only when document files are part of a book and contain paragraph autonumber formats that include the counter or placeholder Building Blocks, <n>, <n+>, and their counterparts in other numbering styles. If you used a combination of <$chapnum> and these placeholder Building Blocks, you must use the Numbering properties settings for both chapter and paragraph when including files in a book. You might not actually have to use these properties, but you should have a general understanding of how these settings work.

Figure 3.3. The Numbering properties window for Paragraph.

Note

Use this property only when document files are or have been included in a book.

  • Restart Paragraph Numbering

    Select this radio button to restart the numbering of all paragraphs that contain counter or p laceholder building blocks in a book. For example, if figure paragraphs have the autonumber format F:<n+> and the last figure paragraph in one document file in a book is numbered 4, the first figure paragraph in the next document file in that book will be number 1. Restarting paragraph numbering does not affect the <$chapnum> and <$volnum> Building Blocks that you use in an autonumber format.

  • Continue Numbering from Previous Paragraph in Book

    Select this radio button to increment the numbering of paragraphs that contain counter or placeholder Building Blocks continuously from one file to the next file in that book. For example, if figure paragraphs have the autonumber format F:<n+> and the last numbered figure paragraph in one document file is numbered 4, the first figure paragraph in the next document file in that book will be numbered 5. Continuing paragraph numbering does not affect the <$chapnum> or <$volnum> Building Blocks that you use in a an autonumber format.

Back to Basics

Book file settings override individual file settings.

Creating a Numbered List

Now that you have some background on autonumbering, it's time to dig in to some real-world examples.

You might want to include many numbering schemes in your documents, but you need to begin at the simplest level: the numbered list.

Numbered lists appear in documents in a variety of number styles: Arabic numbers, letters, Roman numerals, and they may be punctuated with periods, parentheses, or other special characters. The following exercises show you around the construction and use of numbers in lists. After you understand how to construct a numbered list, you will be able to use different number styles quickly and easily.

Restarting and Continuing a Number Series

Numbered lists of any type are often used more than once in a document. Each time a numbered list is used, the first item in the list begins with the number 1, and each subsequent item in the list increases in value by 1. For this to work correctly in FrameMaker, you must restart the first item in each list throughout your document to the number 1. If you do not reset the first item in each list to the number 1, all the numbered lists throughout your document will be numbered sequentially.

As I discussed in the earlier section "Starting Number," the way to reset the first item in each list to 1 is to create two separate paragraph tags with different autonumber formats to use for numbered lists. The first paragraph tag restarts the numbered list at number 1, and the second tag increases the number of subsequent tagged paragraphs by 1. For the following exercise, assume the two paragraph tags already exist in the document except for the number property. To keep it simple, I named the paragraph tags N1 to restart the list and N2 to increment by 1. It's a good idea to name these paragraph tags something that reminds you which one restarts a list or increments a list item.

Restarting the List at 1

Let's start in the Paragraph Designer on the Numbering property for N1, the paragraph tag that restarts the numbered list at 1:

Back to Basics

Click Update All in the Paragraph Designer after you make changes to the Numbering property.

  1. Type N: in the Autonumber Format field.

    N: is a series label; see the section "Series Labels" earlier in this chapter. This series label will be used for both N1 and N2 so that the numbers in N1 and N2 paragraphs relate to each other.

  2. Select <n=1> from the Building Blocks list.

    The Building Block <n=1> is inserted into the Autonumber Format field. This block sets the value of the number to 1 and displays the number as an Arabic numeral. You can also use this Building Block to set the value to any number. For example, <n=3> sets the number to 3 instead of 1.

  3. Type a period.

    A period is inserted into the Autonumber Format field. As a result, a period will be automatically displayed after the number in all the N1 paragraphs in the document. If you want to use a parenthesis or a dash instead, type that character in the Autonumber Format field.
Increasing Subsequent Items in the List by 1

Now it's time to move on to the autonumber format for N2, the paragraph tag that increments each item in the list by 1:

  1. Type N: in the Autonumber Format field.

    Using the series label N: for both N1 and N2 means that the N1 and N2 paragraph numbers will relate to each other. When N1 is applied to a paragraph, the number will be 1. If a paragraph tagged with N2 follows it, that paragraph is numbered 2.

  2. Select <n+> from the Building Blocks list.

    The Building Block <n+> is inserted into the Autonumber Format field. This block is a counter. It increases the value of the number by 1 and displays that value as an Arabic numeral.

  3. Type a period.

    A period is inserted in the Autonumber Format field. As a result, a period is automatically inserted after the number. If you want to use a parenthesis or a dash instead, type that character in the Autonumber Format field. Of course, you should use the same character as you did in the N1 tag.

Putting Your List into Action

Back to Basics

For N1 Basic properties, set Next Pgf Tag to N2.

Now that you created the paragraph tag autonumber formats necessary to make the numbered list work, it's time to put them into action. Type a few lines of text on your document page or just apply the tags to empty paragraph returns to test them out:

  1. Apply the N1 paragraph tag to the first item in the list.

    N1 is applied to the paragraph. The number 1 appears.

  2. Apply the N2 paragraph tag to the subsequent items in the list.

    N2 is applied to the subsequent paragraphs in that list. The numbers 2, 3, 4, and so on are displayed.

Using a Different Numbering Style

If you decide to use a numbering style other than Arabic numerals, just replace <n=1> and <n+> with one of the numbering style Building Blocks listed in Table 3.3.

Table 3.3. Numbering Style Building Blocks

Number Style

Building Blocks

Lowercase alphabetic (a, b, c, ...)

<a=1>, <a+>

Uppercase alphabetic (A, B, C, ...)

<A=1>, <A+>

Lowercase Roman numeral (i, ii, iii, ...)

<r=1>, <r+>

Uppercase Roman numeral (I, II, III, ...)

<R=1>, <R+>

Creating Numbering Based on Chapter Numbers

So far in this chapter, you encountered numbered paragraphs that are used specifically for a list. Let's kick it up a notch on the learning curve to chapter-based numbering.

You might already be familiar with chapter-based numbering in documents that you've written or read. The goal of chapter-based numbering is to number all subheadings, figures, and tables within each chapter, based on the chapter number. Chapter-based numbering systems make it easier for readers to find referenced figures, tables, and other elements, as you can see in Table 3.4.

Table 3.4. Examples of Chapter-Based Numbering

Heading Level

What It Looks Like

ChapterTitle

Chapter 1 Travel Through Europe

Subhead1

1.1 Getting Around

Subhead2

1.1.1 Trains

Subhead2

1.1.2 Cars

Figure

Figure 1-1

Table

Table 1-1

Each numbered element in Table 3.4 is a kind of paragraph, so it can be autonumbered just as the list items were. In contrast to the list items, however, each numbered paragraph shown in Table 3.4 under the chapter heading includes the same number of the chapter heading (in this case, 1). If the chapter number changes to 2, all the numbered paragraphs under the chapter heading changes accordingly and automatically, as illustrated in Table 3.5.

Table 3.5. The Effect of a Chapter Number Change on Chapter-Based Numbering

Heading Level

What It Looks Like

ChapterTitle

Chapter 2 Travel Through Europe

Subhead1

2.1 Getting Around

Subhead2

2.1.1 Trains

Subhead2

2.1.2 Cars

Figure

Figure 2-1

Table

Table 2-1

Note

See Chapters 4 and 5 for more information on using chapter numbers in headers, footers, and cross-references.

Another advantage to chapter-based numbering is that the chapter number is easily included not only in paragraph numbers, but also in headers and footers, cross-references, table of contents, page numbers, and indexes.

Chapter Heading

This section discusses how to create the chapter heading before it discusses Subhead1, Subhead2, figure, and table. For each exercise, begin with the Paragraph Designer and assume that the paragraph tag already exists, except for the autonumber format. In addition, the steps to update the paragraph tag have been intentionally left out, so don't forget to press Update All when you make changes to the Autonumber Format field.

Determining What Elements Are Included

It's a good idea to plan and write out beforehand what paragraph types you want to number and how you want those numbers to be displayed. This design stage cannot be emphasized enough. Look at how the numbering of each of the example paragraph types in Table 3.4 is related to the heading level—that is, the function that the paragraph is intended to perform. For example, Subhead2 is two levels below the chapter heading. It includes the chapter number, a second number that stays the same but increases with Subhead1, and a third number that counts or increases by 1, separated by periods. For ChapterTitle, the word "Chapter" is included and there is a space separating the numbered portion of the paragraph from the typed text. Likewise, in your own documents, you need to decide what types of paragraphs will be numbered and what's included.

Back to Basics

Text included as part of the autonumber is not spell-checked.

These are important things to know before you start working with autonumbers. As with everything else, however, you can always return to it later and make changes.

Creating the Autonumber

You might want to type some text on a body page and assign it the ChapterTitle paragraph tag before you get started. This gives you a good idea of what the autonumber will look like with typed text. Let's begin in the Paragraph Designer Numbering property:

Note

If you use <$chapnum> as a lone Building Block, the series label is not necessary because <$chapnum> is not a counter. Its value does not change within a file.

  1. Type "Chapter" in the Autonumber Format field.

    Chapter is inserted in the Autonumber Format field of the Chaptertitle paragraph tag. Chapter will be included as part of the autonumber and will be displayed in paragraphs tagged with Chaptertitle.

  2. Click once on <$chapnum> in the Building Blocks list.

    <$chapnum> is inserted in the Autonumber Format field. <$chapnum> represents the chapter number for this document file and will reveal itself as an actual number in paragraphs with its tag applied.

  3. Press the space bar.

    A space is inserted after the <$chapnum> building block (see Figure 3.4). A space is included in Chaptertitle paragraphs to separate the autonumber format from the typed text.

    Figure 3.4. The ChapterTitle Autonumber format.
Setting the Chapter Number and Style

Now that you created the autonumber, there are just two things left to do. First, set the Chapter number and then, set the numbering style. Here's how to do it:

Note

<$chapnum> does not increment by 1 within the same file, only across files.

  1. Select Format > Document > Numbering > Chapter.

    The Document Numbering properties window for Chapter appears.

Note

This action sets the chapter number for the entire file.

  2. Type 1 in the Chapter# field.

    1 is inserted in the Chapter# field. Your document's Numbering properties might already have the number 1 included. Experiment by typing a different number. This means that whatever number you type in this field becomes the chapter number for this document file, including the chapter heading you are creating.

  3. Select Numeric from the Format drop-down list (see Figure 3.5). After you finish, click on the Set button.

    Figure 3.5. The Document Numbering properties for chapter.

    Numeric is the default selection. This means that the chapter heading for this document file will be in numeric style (1, 2, 3, and so on). The changes take effect in the document the moment that you click on the Set button. Just for fun, select another numbering style to try it out.

Subhead1

Now that you created an autonumber for a ChapterTitle, move on to the next subhead level under the Chapter heading. Although you did not need to include a series label for the ChapterTitle autonumber, you must include one here. Subhead1 must relate to some other paragraph tags with autonumbering and be independent of others. Use the series label S: for Subhead1.

Back to Basics

Series labels are case-sensitive.

So far, we have

Chapter 1 Travel Through Europe

Now we will add Subhead1, which is displayed as

1.1, 1.2, ... .

Begin in the Paragraph Designer Number property for Subhead1:

  1. Type S: in the Autonumber Format field.

    S: is inserted into the Autonumber Format field. S: is the series label assigned to this paragraph tag. The series label either relates two or more number sequences or makes them unique from each other.

  2. Click once on <$chapnum> in the Building Blocks list. Type a period after <$chapnum>.

    The Building Block <$chapnum> is inserted in the Autonumber Format field followed by a period. As a result, the chapter number for this document file, whose number and style you assigned in the previous exercise, appears in the Subhead1 autonumber format. Regardless of how many times <$chapnum> is used in various autonumber formats, it's always displayed according to the settings in the document Numbering properties for Chapter.

  3. Click on <n+> in the Building Blocks list.

    The Building Block <n+> is inserted in the Autonumber Format field. This Building Block is a counter. As a result, for each paragraph tagged with Subhead1, the number in the second position only increases by 1.

Back to Basics

Type a hyphen instead of a period if you want the format to be 1-1, 1-2, and so on.

Table 3.6 shows the numbers that will be displayed in Subhead1 paragraphs on body pages as compared with the autonumber format. You can see that, on body pages, two numbers appear, separated by a period, just as the autonumber format contains two Building Blocks separated by a period. The number 1 in the first position in all the paragraphs on body pages corresponds to <$chapnum>, also in the first position, in the autonumber format. The number in the second position in the paragraphs on the body pages corresponds to <n+> in the second position of the autonumber format. Notice how the second-position number increases each time the paragraph tag is assigned to another subsequent paragraph, because the <n+> Building Block is a counter.

Table 3.6. Number Positions in Building Blocks

In Paragraph on Body Pages

Autonumber Format

1.1

S:<$chapnum>.<n+>

1.2

1.3

Subhead2

The next step in creating automated lists is to create the Subhead2 autonumber format.

So far, we have

Chapter 1 Travel Through Europe

1.1 Getting Around

Now add Subhead2. As you can see Table 3.7, Subhead2 paragraphs get three numbers, as follows:

1.1.1, 1.1.2, ...

The first-position number is based on the chapter number, and the third-position number counts on its own. The second-position number is always equal to the second-position number of the most recent Subhead 1. In other words, Subhead2 is related to Subhead1. You can achieve this result by giving the Subhead2 paragraph tags the same series label that was used for Subhead1.

Table 3.7. Heads and Subheads in a Chapter

Heading Level

What It Looks Like

Chaptertitle

Chapter 1 Travel Through Europe

Subhead1

1.1 Getting Around

Subhead2

1.1.1 Trains

Subhead2

1.1.2 Cars

Subhead1

1.2 Getting a Hotel

Subhead2

1.2.1 Use a Travel Agent

Begin in the Paragraph Designer Number property for Subhead1:

  1. Type S: in the Autonumber Format field.

    S: is inserted in the Autonumber Format field. S: is the series label that was assigned previously to the Subhead1 autonumber format. By inserting the same series label in Subhead2, you relate the two paragraph tags, Subhead1 and Subhead2, to each other by making them use the same number series.

  2. Click once on <$chapnum> in the Building Blocks list. Type a period after <$chapnum>.

    <$chapnum> is inserted in the Autonumber Format field followed by a period. <$chapnum> represents the chapter number for this document file. You have already assigned the chapter number and style in previous exercises.

  3. Click on <n> in the Building Block list.

    The Building Block <n> is inserted in the Autonumber Format field. The <n> block is a placeholder rather than a counter. As a result, the number that is displayed will be the same as the number that appears in the same position (the second position) in the last previous paragraph that uses the same number series; that is, the last previous Subhead2 or Subhead1. This number was incremented in the last previous Subhead1 paragraph.

  4. Click on <n+> in the Building Blocks list.

    <n+> is inserted in the Autonumber Format field. <n+> is a counter. The number increases by 1 based on the number in the same position in the last previous Subhead2.

Table 3.8 illustrates the position of numbers displayed on body pages with respect to the autonumber format.

Table 3.8. Number Positions in Building Blocks for Subhead1 and Subhead2

In Paragraph

Autonumber Format

Paragraph Tag

1.1

S:<$chapnum>.<n+>

Subhead1

1.1.1

S:<$chapnum>.<n>.<n+>

Subhead2

1.2

S:<$chapnum>.<n+>

Subhead1

1.3

S:<$chapnum>.<n+>

Subhead1

1.3.1

S:<$chapnum>.<n>.<n+>

Subhead2

Just for fun, change the series label of Subhead2 to s: to see what happens to the autonumbers. Table 3.9 illustrates the results of this error. By not having the same exact series label, Subhead1 and Subhead2 don't relate to each other. Therefore, the second position number of Subhead2 has no previous number to retain its value. When this happens, the number in that position displays as 0.

Table 3.9. A Mistaken Series Label for Subhead1 and Subhead2

In Paragraph

Autonumber Format

Paragraph Tag

1.1

S:<$chapnum>.<n+>

Subhead1

1.0.1

s:<$chapnum>.<n>.<n+>

Subhead2

1.2

S:<$chapnum>.<n+>

Subhead1

1.3

S:<$chapnum>.<n+>

Subhead1

1.0.2

s:<$chapnum>.<n>.<n+>

Subhead2

Taking a Test Drive

Before moving on, you should test the autonumber formats you created so far. Autonumber formats should adjust correctly on their own under any circumstances. A good way to test autonumber formats is to press the Enter key several times to create lines of empty paragraphs. Then apply the paragraph tags with the autonumber formats at random to make sure they work properly.

If you wait until you have a huge document in front of you, troubleshooting will be more difficult as you search through tons of pages to find the problem. This way, everything is right in front of you at one time.

Figure Autonumber Format

Now that you have created three autonumber formats, you should have a good idea of how to create the Figure autonumber format. Here's how figures will be displayed:

Figure 1-1, Figure 1-2, Figure 1-3 ...

The number 1, in the first position, is based on the chapter number, and the second position number is a counter. If the chapter number were 9, the figure number would begin with 9-1. Here's how you create the Figure autonumber format:

  1. Type F: in the Autonumber Format field.

    The series label F: is inserted into the Autonumber Format field. This series label differs from the series label used for both Subhead1 and Subhead2. As a result, the figure number series is independent of both Subhead1 and Subhead2.

  2. Type "Figure" in the Autonumber Format field, then press the space bar once.

    The word "Figure" is inserted in the Autonumber Format field followed by a space. As a result, "Figure" is included as part of the Autonumber format. The space is included to separate the word "Figure" from the figure number. If you don't add a space, the word "Figure" runs into the figure number.

  3. Click once on <$chapnum> in the Building Blocks list, then type a hyphen (-).

    The Building Block <$chapnum> is inserted in the Autonumber Format field, followed by a hyphen. <$chapnum> represents the chapter number for this document file, which you have already set in a previous exercise. The hyphen is included to separate the chapter number from the figure counter, as in 1-1, 1-2, and so on. If you want to use a decimal, type a period instead. The result is 1.1, 1.2, and so on.

  4. Click once on <n+> in the Building Blocks list, then type a space (see Figure 3.6).

    Figure 3.6. The Autonumber Format field for figure based on the chapter number.

    <n+> is inserted in the Autonumber Format field followed by a space. <n+> is a counter. As a result, each figure number increases by 1 in number position 2, based on the number in the same position in the previous figure caption.

After you finish, the Figure autonumber format will be based on the chapter number, as shown in Table 3.10.

Table 3.10. Number Positions in Building Blocks for Figure

In Paragraph

Autonumber Format

Paragraph Tag

Chapter 6 Getting Around the Airport

Chapter <$chapnum>

ChapterTitle

Figure 6-1 Heathrow Airport Map

F:<$chapnum>-<n+>

Figure

Figure 6-2 Charles DeGaulle Airport Map

F:<$chapnum>-<n+>

Figure

Chapter 7 Using the Underground

Chapter <$chapnum>

ChapterTitle

Figure 7-1 London Underground

F:<$chapnum>-<n+>

Figure

Figure 7-2 Paris Underground

F:<$chapnum>-<n+>

Figure

Table Autonumber Format

The Table autonumber format is the last format in this exercise that we work on. Now that you created the figure autonumber format, you should breeze through this one. Here's a hint: The table and figure autonumber series are independent of each other. Here's how tables will be displayed:

Table 1-1 , Table 1-2, Table 1-3 , ...

The number 1, in the first position, is based on the chapter number, and the second position number is a counter. If the chapter number is 5, the table number would begin with 5-1.

  1. Type T: in the Autonumber Format field.

    The series label T: is inserted in the Autonumber Format field. This series label differs from the series label used for Subhead1, Subhead2 and Figure. As a result, the table number series is independent of both subheading number series and the figure number series.

  2. Type Table in the Autonumber Format field, then press the space bar once.

    The word "Table" is inserted in the Autonumber field followed by a space. As a result, "Table" will be included as part of the Autonumber format. The space separates the word "Table" from the table number. If you don't add a space, the word "Table" runs into the table number.

  3. Click once on <$chapnum> in the Building Blocks list, then type a hyphen (-).

    The Building Block <$chapnum> is inserted in the Autonumber Format field, followed by a hyphen. <$chapnum> represents the chapter number for this document file, which you already set in a previous exercise. The hyphen separates the chapter number from the table counter, as in 5-1, 5-2, and so on. If you want to use a decimal, type a period instead. The result would be 5.1, 5.2, and so on.

  4. Click once on <n+> in the Building Blocks list, then type a space (see Figure 3.7).

    Figure 3.7. The Autonumber Format field for tables based on the chapter number.

    The Building Block <n+> is inserted in the Autonumber Format field followed by a space. <n+> is a counter. As a result, each table number increases by 1 in the second number position, based on the number in the same position in the previous table title.

After you finish, the table autonumber format will be based on the chapter number, as shown in Table 3.11.

Table 3.11. Number Positions in Building Blocks for Table

In Paragraph

Autonumber Format

Paragraph Tag

Chapter 6 Getting Around the Airport

Chapter <$chapnum>

ChapterTitle

Table 6-1 London Airport Phone Numbers

T:Table <$chapnum>-<n+>

Table

Table 6-2 Paris Airport Phone Numbers

T:Table <$chapnum>-<n+>

Table

Chapter 7 Using the Underground

Chapter <$chapnum>

ChapterTitle

Table 7-1 London Transport Contacts

T:Table <$chapnum>-<n+>

Table

Table 7-2 Paris Transport Contacts

T:Table <$chapnum>-<n+>

Table

Just for even more fun, change the series label of Table to F:, the same series label for Figure. They are now related to each other. Table 3.12 shows the error in numbering that results. This error is one sure-fire way to disrupt the numbering schemes in your document.

Table 3.12. A Mistaken Series Label for Table and Figure

In Paragraph

Autonumber Format

Paragraph Tag

Figure 3-1

F:Figure <$chapnum>-<n+>

Figure

Figure 3-2

F:Figure <$chapnum>-<n+>

Figure

Table 3-3

F:Table <$chapnum>-<n+>

Table

Figure 3-4

F:Figure <$chapnum>-<n+>

Figure

Creating Section-Based Numbering

Say that you are producing a book in which each chapter consists of several sections. Suppose also that each section has its own separate sequence of figures and tables. In this case, figures and tables would not be numbered just within each chapter, but within each section of that chapter. This type of numbering is substantially trickier than what you did so far in this chapter.

In the following example, you set up figure and table numbers based on a subsection heading level. You work with autonumber format building blocks that you have not yet used—specifically, < > and < =0>. You saw the definition for both these building blocks in Table 3.1.

To find out what section-based numbering really means, say that you have three levels of numbered headings in your document, along with figures and tables. Table 3.13 shows the paragraph tag names for these levels and what each should look like in text.

Table 3.13. Section-Based Numbering Example

Paragraph Tag

Paragraph Number in Text

Section1

Section 9

Section2

9.1

Section3

9.1.1

Figure

Figure 9.1-1

Table

Table 9.1-1

Section2

9.2

Section3

9.2.1

Figure

Figure 9.2-1

Table

Table 9.2-1

As you can see from Table 3.13, this document comprises three levels of section headings, whose numbers are related to each other. The numbers of the figures and tables consist of the Section2 heading number in the first two positions, followed by a counter in position 3. In other words, if the current Section2 is 9.2 and Section3 is 9.2.1, the figures are numbered 9.2-1, 9.2-2, 9.2-3, and so on, and the tables are numbered 9.2-1, 9.2-2, 9.2-3, and so on. Table and figure numbers reset themselves to start over again at 1 each time the Section2 number increases by 1. You can see this clearly when Section2 changes to 9.2.

It seems like the tables and figures are not numbered in the same sequence. Figure 9.2-1 is not followed by Table 9.2-2 . At first glance, you might guess that the figure and table tags belong to a different number series. On the other hand, if different series labels for these tags were used, they could not both be related to the series for Section2. You can't insert one series label for the sections and a second series label for the figure numbers because an autonumber format cannot contain more than one series label. Therefore, we must use a single series label for all five paragraph tags. The autonumber formats must be constructed in a way that produces the two apparently independent counters for figures and tables.

The answer to this problem? Provide positions for all the possible numbers in all the subheadings, but hide the numbers each tag doesn't use, without changing them. For example, in the figure tag, it's necessary to hide the table number without changing it. The < > and < =0> Building Blocks achieve these results.

Note that, for this numbering system to work, figures or tables must not be set between Section1 and Section2 headings. If every Section1 heading is immediately followed by a Section2 heading, such as "Introduction," you will be safe.

After you understand how to implement this numbering scheme, you can take what you learned and creatively apply it to other numbering schemes.

Section1

Section1 is the most important autonumber format to set up for this numbering scheme. It sets the stage for the other autonumber formats, which are ultimately based on it. I use H: as the series label, but you can choose any letter you want:

  1. Determine how many autonumber formats are related to each other.

    A total of five autonumber formats are related to each other, Section1, Section2, Section3, Figure, and Table. Therefore, five number positions must be accounted for in this autonumber format.

  2. Type H: in the Autonumber Format field for Section1.

    H: is inserted in the Autonumber field. H: is the series label that is used for all five paragraph tags to relate to each other.

    Note

    Using the chapter number in place of Section1 does not eliminate the problem of section-based numbering.

  3. Select <n+> from the Building Blocks list.

    The Building Block <n+> is inserted in the Autonumber field. <n+> is a counter. As a result, each time a paragraph is tagged with Section1, the number increases by 1.

    Note

    < =0> is not available in the Building Block list.

  4. Type < =0>< =0>< =0>< =0> in the Autonumber Format field.

    The Building Blocks < =0>< =0>< =0>< =0> is inserted in the Autonumber Format field. The Building Block < =0> resets a counter value to 0 and does not display it. As a result, at every Section1 paragraph in the document (where Section1 increases by 1), the values for the counters in the next four positions are reset to 0 and not displayed. This way, the numbering sequences below the first-level section head can begin again. These four number positions produce the autonumbers for the Section2, Section3, Figure, and Table paragraph tags. You have not constructed these yet, but they must be accounted for in the first-level tag.

You must break down the positions in the Section1 autonumber format. Each position represents one of the five paragraph tags that are included in this numbering scheme, as seen in Table 3.14.

Table 3.14. Section1 Autonumber Format

Series Label

Position 1

Position 2

Position 3

Position 4

Position 5

H:

<n+>

< =0>

< =0>

< =0>

< =0>

Section1

Section2

Section3

Figure

Table

Section2

To set up Section2, do the following:

  1. Type H: in the Autonumber Format field for Section2.

    H: is inserted in the Autonumber field. H: is the series label that is used for all five paragraph tags to relate them to each other.

  2. Select <n> from the Building Blocks list.

    The Building Block <n> is inserted in the Autonumber Format field. <n> is a placeholder. As a result, each time a paragraph is tagged with Section2, the number in the first position retains the same value as the previous number in the same position. In this case, that would be the Section1 number.

  3. Type a period.

    A period is inserted in the Autonumber Format field. As a result, a period appears in the Section2 paragraph between the number in position 1 (the first-level section heading number) and the number in position 2 (the second-level section heading number).

  4. Select <n+> from the Building Blocks list.

    The Building Block <n+> is inserted in the Autonumber Format field. <n+> is a counter. As a result, each time a paragraph is tagged with Section2, the number in position 2 increases by 1.

  5. Select < > from the Building Blocks list.

    The Building Block < > is inserted in the Autonumber Format field. < > keeps the value in position 3 the same as the previous value in the same position, but suppresses the display of this value.

  6. Type < =0>< =0> in the Autonumber Format field.

    The Building Blocks < =0>< =0> is inserted in the Autonumber Format field. < =0> resets values of number positions 4 and 5 to 0. As a result, each time Section2 appears in the document (at which point it increases by 1), the values in positions 4 and 5 reset to 0, and start over again. Positions 4 and 5 represent the figure and table numbers, which start over at 1 each time a Section2-tagged paragraph occurs.

Table 3.15 shows a breakdown of the building blocks at the different number positions in the Section2 autonumber format.

Table 3.15. Section2 Autonumber Format

Series Label

Position 1

Position 2

Position 3

Position 4

Position 5

H:

<n>

.<n+>

< >

< =0>

< =0>

Section1

Section2

Section3

Figure

Table

Section3

To set up Section3, follow these steps:

  1. Type H: in the Autonumber Format field for Section3.

    H: is inserted in the Autonumber Format Field. H: is the series label that is used for all five paragraph tags to relate to each other.

  2. Select <n> from the Building Blocks list.

    The Building Block <n> is inserted in the Autonumber Format field. <n> is a placeholder. As a result, each time a paragraph is tagged with Section3, the number in the first position retains the same value as the previous number in the same position. In this case, that's the Section1 number.

  3. Type a period.

    A period is inserted in the Autonumber Format field. As a result, a period appears in the Section3 paragraph between the number in position 1 (the first-level section heading number) and the number in position 2 (the second-level section heading number).

  4. Select <n> from the Building Blocks list.

    The Building Block <n> is inserted in the Autonumber Format field. <n> is a placeholder. As a result, each time a paragraph is tagged with Section3, the number in position 2 retains the same value as the previous number in the same position. In this case, that value is the Section2 number.

  5. Type a period.

    A period is inserted in the Autonumber Format field. As a result, a period appears in the Section3 paragraph between the number in position 2 (the second-level section heading number) and the number in position 3 (the third-level section heading number).

  6. Select <n+> from the Building Blocks list.

    The Building Block <n+> is inserted in the Autonumber Format field. <n+> is the only number position that is a counter for Section3.

  7. Type < >< > in the Autonumber Format field.

    The Building Blocks < >< > are inserted in the Autonumber Format field. These Building Blocks suppress the display of the values in number positions 4 and 5 and keep those values the same as the last previous values in those positions. In this example, positions 4 and 5 represent the figure and table numbers. The values of the figure and table numbers are retained so that they do not start over again at 0. The only time they should start over is at the next Section2 heading.

Table 3.16 shows the Building Blocks at the different positions in the Section3 autonumber format.

Table 3.16. Section3 Autonumber Format

Series Label

Position 1

Position 2

Position 3

Position 4

Position 5

H:

<n>

.<n>

.<n+>

< >

< >

Section1

Section2

Section3

Figure

Table

Figure

To set up a figure, follow these steps:

  1. Type H: in the Autonumber Format field for figure, then type the word "Figure" followed by a space.

    The characters "H:Figure" are inserted in the Autonumber Format field. H: is the series label that is used for all five paragraph tags to relate them to each other. The word "Figure" is included in the autonumber format. The space prevents the word "Figure" from colliding with the figure number.

  2. Select <n> from the Building Blocks list.

    The Building Block <n> is inserted in the Autonumber Format field. This building block is a placeholder. As a result, each time a paragraph is tagged with Figure, the number in the first position retains the same value as the previous number in this same position, which is the Section1 number.

  3. Type a period.

    A period is inserted in the Autonumber Format field. As a result, a period appears in the figure paragraph between the number in position 1 (the first-level section heading number) and the number in position 2 (the second-level section heading number).

  4. Select <n> from the Building Blocks list.

    The Building Block <n> is inserted in the Autonumber Format field. <n> is a placeholder. As a result, each time a paragraph is tagged with Figure, the number in position 1 retains the same value as the previous number in this same position, which is the Section2 heading number.

  5. Select < > from the Building Blocks list.

    The Building Block < > is inserted in the Autonumber Format field. < > keeps the value in position 3 the same as the previous value in this same position (that is, the Section3 number), but suppresses the display of this value. That is, the third-level section number is not displayed in figure captions.

  6. Type a hyphen.

    A hyphen is inserted in the Autonumber Format field. As a result, a hyphen appears between the number in position 2 (the second-level section heading number) and the number that is displayed in position 4 (the figure number).

  7. Select <n+> from the Building Blocks list.

    The Building Block <n+> is inserted in the Autonumber Format field. <n+> is a counter. As a result, each time a paragraph is tagged with Figure, the number in position 4 (the figure number) increases by 1.

  8. Select < > from the Building Blocks list.

    The Building Block < > is inserted in the Autonumber Format field. < > keeps the value of the number position 5 the same as the previous value in this same position (the last previous table number), but suppresses the display of this value.

Table 3.17 shows the Building Blocks in the various positions in the figure autonumber format and what paragraph tags they represent in this series.

Table 3.17. Figure Autonumber Format

Series Label

Text

Position 1

Position 2

Position 3

Position 4

Position 5

H:

Figure

<n>

.<n>

< >

-<n+>

< >

Section1

Section2

Section3

Figure

Table

Table

To set up a table, follow these steps:

  1. Type H: in the Autonumber Format field for Table, then type the word Table followed by a space.

    The characters "H:Table" is inserted in the Autonumber Format field. H: is the series label that is used for all five paragraph tags to relate them to each other. The word Table is included in the autonumber format, followed by a space to keep the word Table from colliding with the table number.

  2. Select <n> from the Building Blocks list.

    The Building Block <n> is inserted in the Autonumber Format field. <n> is a placeholder. As a result, each time a paragraph is tagged with Table, the number in position 1 keeps the same value as the previous number in this same position. In this case, that would be the Section1 number.

  3. Type a period.

    A period is inserted in the Autonumber Format field. As a result, a period appears in the table paragraph between the number in position 1 (the first-level section heading number) and the number in position 2 (the second-level section heading number).

  4. Select <n> from the Building Blocks list.

    The Building Block <n> is inserted in the Autonumber Format field. <n> is a placeholder that displays the last previous value of the counter in position 2 and leaves the value unchanged. In this case, that value is the Section2 number.

  5. Select < > from the Building Blocks list.

    The Building Block < > is inserted in the Autonumber Format field. < > keeps the value in number position 3 the same as the previous value in this same position (that is, the value at the last Section3 heading), but suppresses the display of this value. In other words, the third-level section heading number doesn't appear in the table title.

  6. Select < > from the Building Blocks list.

    The Building Block < > is inserted in the Autonumber Format field. < > keeps the value in position 4 the same as the previous value in this same position (in other words, the last figure number), but suppresses the display of this value.

  7. Type a hyphen.

    A hyphen is inserted in the Autonumber Format field. As a result, a hyphen appears between the number in position 2 (the second-level section heading number) and the number that is displayed in position 5 (the table number).

  8. Type <n+> in the Autonumber Format field.

    The Building Block <n+> is inserted in the Autonumber Format field. <n+> is a counter. As a result, at each paragraph tagged table, the number in position 5 in this number series increases by 1 and is displayed as the table number.

Table 3.18 shows the building blocks at the various positions in the table autonumber format and the paragraph tags they represent in this series.

Table 3.18. Table Autonumber Format

Series Label

Text

Position 1

Position 2

Position 3

Position 4

Position 5

H:

Table

<n>

.<n>

< >

< >

-<n+>

Section1

Section2

Section3

Figure

Table

A Note on Book File Numbering

Now that you have some autonumbering techniques under your belt, this is a good place to discuss book file settings for numbering. As mentioned earlier, you'll use document Numbering properties for volume, chapter, and paragraph to set up book file numbering. Although this chapter doesn't thoroughly cover volume numbering, you can take what you learned about chapter numbering and apply the same basic concepts.

If you used the <$chapnum> Building Block in autonumbering, use Format > Document > Numbering > Chapter to control the chapter number when the file is included in a book. This is true whether you use <$chapnum> as a Building Block by itself or along with any of the other available Building Blocks for autonumbers.

If you used any other autonumbering Building Blocks and your file is included in a book, use Format > Document > Numbering > Paragraph to control whether numbering restarts or continues from the previous file, as discussed in the section, "Paragraphs."

Here are some example results of settings for document Numbering properties. Say that you have used a combination of <$chapnum> and other Building Blocks in autonumbers. To make it easier, this example comprises only a chapter heading and one subheading. Table 3.19 shows the paragraph tag, its autonumber format, and how it's displayed in the document.

Table 3.19. Paragraph Tag and Autonumber Formats for Book File Example

Paragraph Tag

Autonumber Format

How It's Displayed

Chapter Head

Chapter <$chapnum>

Chapter 4

Subhead1

S:<$chapnum>.<n+>

4.1

Now, suppose that this file is part of a book and follows Chapter 3. The last subheading1 in Chapter 3 is 3.5. Let's set the document Numbering properties for chapter to Continue Numbering from Previous File in Book and set the Document Number Properties for Paragraph to Continue Numbering from Previous Paragraph in Book. The results are shown in Table 3.20.

Table 3.20. Resulting Numbering Using Book File Settings

Paragraph Tag

How It's Displayed

Autonumber Format

Chapter Head

Chapter 4

Chapter <$chapnum>

Subhead1

4.6

S:<$chapnum>.<n+>

Notice that the first occurrence of Subhead1 in Chapter 4 is 4.6. FrameMaker is following the instructions; that is, it's continuing the numbering from the previous paragraph in the book (3.5).

Back to Basics

Book file document numbering properties override document settings.

If you want Subhead1 to start with 4.1, you must set the Document Numbering properties for Paragraph to Restart Numbering. This doesn't affect the <$chapnum> or <$volnum> at all.

Because you're working with autonumber properties of chapters in a book, remember to go to your book file and select Edit > Update Book.

Summary

Congratulations! You learned about the various types of autonumbers and the logic behind them. You explored some background information, as well as the methods used for a numbered list, chapter-based numbering, and section-based numbering. You can put the logic you learned to good use by creating many more types of numbering in your documents.

Be serious about planning before you use autonumbering features because it is essential to creating autonumbering (for most FrameMaker tasks). After you create the numbering, testing it is crucial to determine whether the numbering works correctly given any documentation situation. Nevertheless, you can still have fun with it.


Chapter 4

Chapter 4. Headers and Footers

  • Practical Uses
  • The Home of Headers and Footers
  • What Headers and Footers Are Made Of
  • Starting with the Easy Stuff
  • Working with Fixed Headers and Footers That Rarely Change
  • Working with Varying Headers and Footers
  • Using Abbreviated Headings
  • Summary

You see them in books, magazines, manuals, and guides. Just about everything you read contains those useful bits of information that appear at the top and bottom of each page. Headers and footers, the great navigation tools of any document, provide information about where you are in a document and about the document itself.

You might be creating FrameMaker document headers and footers or simply modifying existing ones. You might just be the end user of a FrameMaker template with headers and footers already built in. Whatever your role, this chapter is for you.

This chapter covers the practical uses of headers and footers, what they're made of, and how they work together with FrameMaker's interrelated parts. This chapter also examines the specifics of building, modifying, and using headers and footers to achieve complex tasks. It finally describes some of the pitfalls and tricks in dealing with them.

You might have discovered that some header and footer types in FrameMaker can be complicated or confusing. By reading this chapter, you gain important inside information that enables you to implement these concepts into your everyday tasks with ease. You might even have some fun.

Practical Uses

Typically, headers and footers are displayed on every page throughout a document to facilitate navigation or provide other information about a document. Although you can display just about any type of text or graphics in headers and footers, you should keep every reader's task in focus as you decide what to include. The following helpful items are commonly placed in headers and footers:

  • Page number

  • Chapter number and title

  • Section number and title

  • Document title

  • Revision date or number

  • Company or author information

The Home of Headers and Footers

Although you can construct headers and footers in many different ways, there is only one location in which they reside.

Headers and footers only live on FrameMaker's master pages. Simply put, the job of a master page is to provide the page layout and any background information that you want to appear on each page. That background information includes headers and footers. As you create and work with headers and footers in FrameMaker documents, you will probably spend most of your time with the master pages.

Back to Basics

Use View > Master Pages to access headers and footers.

What Headers and Footers Are Made Of

The more you understand about what headers and footers are made of, and how they work within FrameMaker, the easier it is for you to accomplish tasks that utilize these features. It's important to take a quick tour of what's inside FrameMaker's headers and footers before moving on to more in-depth explanations and real-world examples.

Headers and footers can comprise any combination of hard-typed text, graphics, and FrameMaker variables. These elements are discussed in more detail in the following subsections.

Hard-Typed Text

A simple way to display information in headers or footers is just to type text directly into the header or footer of your document. However, this method neglects FrameMaker's powerful global-updating features. For example, if you type the document title in the header of several master pages in your document, and you need to make a change later, you have to edit all the occurrences of that document title on each master page.

Although this method does not work well for long, complicated documents, you should consider using it for short, one-page memos that use one master page. You can also use this method in parts of the header and footer that do not change, such as the word "Chapter" in "Chapter 3".

Graphics

Back to Basics

Graphics imported by reference update automatically based on the source graphic.

You can import or create graphics (such as a company logo) in headers and footers by using the same methods as in other parts of your document. If you place graphics into headers and footers, these graphics will be displayed on all body pages in your document that correspond to the particular master pages that contain the graphics. Again, keep in mind that, if you want to make a change, you must change each occurrence of the graphic on master pages.

Simple System Variables

FrameMaker provides system variables for use in headers and footers. System variables perform a variety of functions, and they update themselves based on information generated by the system. These type of system variables include the following:

  • Page number and page count

  • Current date, creation date, and revision date

  • Filename (short) and filename (long) (the full path)

Back to Basics

From a master page background text frame, use Format > Headers & Footers > Insert Page #.

These system variables are easy to include in a document.

Let's look at how a simple system variable, such as a page number, works. You can implement this clever feature in your document by viewing the master page and selecting the page number variable from a menu to insert it into the header or footer. When viewed on the master page, the page number has no fixed quantitative value and is represented by a pound sign (#). When viewed on body pages, the page number reveals its quantitative value, automatically incrementing by 1 from page to page.

That's all there is to it. Simple system variables are easy to use because you don't have to think about them that much. You can read more on this topic in the section "Starting with the Easy Stuff" on page 82.

Medium-Strength System Variables

FrameMaker user variables fall under the medium-strength variety. They require a bit more effort than simple variables. User variables enable you to define fixed headers and footers that don't change often. For example, you can create a user variable to contain a document title. Then insert that variable in the header area on several master pages used in your document. The document title will be displayed in the header, both on the body pages and the corresponding master pages.

Tip

Learn how to use Volume Numbers to perform a similar task in "Tricks with Volume Numbers" on page 88.

Now suppose that you decide to change the document title. In contrast to hard-typed text, when you change information stored in a user variable, you can simply change the variable definition in one place, and all occurrences of that variable update automatically—what a great time-saver.

For further exploration and some real-world examples of medium-strength variables, see the section "Working with Fixed Headers and Footers That Rarely Change" on page 84.

Industrial-Strength System Variables

FrameMaker provides more robust and powerful variables for use in headers and footers that vary from page to page in your document. Some of these include the following:

  • Chapter number and title

  • Subheading number and title

  • Dictionary-style headers

These industrial-strength variables are more complicated than the other varieties. To work correctly when viewed on document pages, they assume a value that relies on underlying detail elsewhere in the document. But what does that really mean?

These powerful variables are made up of "containers" that store references to particular paragraph tags. Information in paragraphs in your document that have the particular paragraph tags specified by the containers is automatically displayed in the header. Based on each occurrence of content with those paragraph tags, the header automatically changes from page to page.

If you can't wait to start using these powerful variables, skip to the section "Working with Varying Headers and Footers" on page 90. Otherwise, to learn more about using the simpler system variables, read the next section.

Starting with the Easy Stuff

Before getting into the ins and outs of the more-complicated headers and footers, some of the techniques that you can use for the simplest headers and footers, such as hard-typed text, graphics, and simple system variables, must be discussed.

You already know how to type text or import graphics in FrameMaker. These operations are done in the exact same way on the master pages in background text frames. The only difference is the location.

Before getting to that, an important "gotcha" must be mentioned. Have you ever typed in a header or footer text frame and seen a large chunk of your definition "disappear" as the text wraps around to a second line? If so, this just means that the text frame does not have enough room to contain that information. Just Control-click on the text frame, grab the bottom anchor, and make the text frame longer. The text reappears, and you can adjust your frame accordingly.

Simple system variables, such as page numbers, dates, and filenames, are just as easy to include in your document header as regular text. Use the following steps to insert any of these variables in a master page header or footer background text frame:

  1. Select Special > Variable.

    The Variable window appears.

  2. Click once on the desired variable from the scrolling list to select it; click on Insert.

    The selected variable is inserted in the header or footer background text frame. This information is displayed on all body pages that utilize this particular master page.

Back to Basics

Another method to insert variables in background text frames is to select Format > Headers & Footers.

Page Number Combos

Now that you know the basics of simple variables, you can now explore how to make page numbering more interesting. You can include the page count, the chapter number, or just a word such as "page" along with the page number by using simple methods that are not time-consuming.

Including the Page Number

You can easily include the page number in your document by following these steps:

  1. If you're presently looking at the body pages, select View > Master Pages. Click inside the header or footer frame in which you want to insert the page number.

  2. Include the page number, either through the Special menu by selecting Special > Variable > Current Page #, or through the Format menu by selecting Format > Headers & Footers > Insert Page #.

Back to Basics

Include the page number by using keyboard commands Alt-S v Home Enter or Alt-o h i, respectively.

As previously noted, the page number appears as only a pound sign "#" on the master pages but appears correctly on the body pages.

Including the Word "Page"

After you insert the page number variable in the header or footer background text frame, you can preface the number with the word "page", if you'd like. To do this, type the word Page followed by a space directly before the page number variable (see Figure 4.1). On a body page (say, page 9), this header is displayed as "Page 9".

Figure 4.1. You can easily add the word "Page" to your header or footer.

Including the Total Page Count

To include the total page count of your document in the header or footer, place the cursor after the page number variable, type a space followed by the word "of" and another space. Then insert the Page Count variable by selecting Special > Variable > Page Count (or by selecting Format > Headers & Footers > Insert Page Count). Notice that, unlike the page number variable, the page count variable reveals its quantitative value on master pages (see Figure 4.2). The reason for this difference is that the page count, unlike the page number, does not vary depending on where the user is in the document. On body pages, this header will display as "Page 9 of 23".

Figure 4.2. Including the total page count of your document in the header of footer.

Including the Chapter Number

If you use chapter-based page numbering, you might want to include the Chapter Number variable along with the page number in a header.

Back to Basics

You can set the chapter number by using Format > Document > Numbering > Chapter.

After you insert the page number variable in the header background text frame, you can add the Chapter Number variable by inserting the variable Chapter Number directly before the page number variable, followed by a hyphen (see Figure 4.3). Like the page count, the Chapter Number variable appears as a number on master pages. On a body page, such as page 9 in Chapter 2, this header will display as "2-9".

Figure 4.3. Adding the Chapter Number variable displays the chapter and the current page number in the header or footer.

Working with Fixed Headers and Footers That Rarely Change

If you plan to use headers or footers in your document that might change, but you don't need to change them often, user variables are the perfect solution. These variables fall under the category of medium-strength variables. You might have already had an encounter with these odd blocks of text and are not sure what to do with them, or you might just be getting ready to create one. Whatever the case, user variables save you time if you work with multiple-master page documents or if you are using one FrameMaker template for different documents.

The idea behind user variables is to create text that will be used in several locations of your document. Locations can include, but are not limited to, headers and footers. After a user variable is defined and inserted in several places, if you then change the user variable definition, all occurrences of that user variable automatically update to include and display the new information.

This is an excellent solution for document titles that are displayed in headers. When you use the same template for a new document set, just change the user variable to a new document title. That's it!

To get a better idea of how to work with user variables, you need to take a deeper look into them.

Planning for User Variables

A user variable consists of two major components, which you have to keep in mind when you plan for this type of variable:

  • The name of the variable. This name will show up in the list of variables in the Variable window. Appropriate names for user variables are helpful for others who might use the same template. For example, if you create a user variable to display a document title, "doctitle" is a good name because the name indicates its purpose.

  • The definition of the variable. This is what will actually be displayed in the header (or another location) in the document where user variables are inserted.

After you decide on the name and definition, you need to create a user variable. Unlike other types of variables, you do not have to be on a master page to create a user variable. You can use this variable in other places in your document, as well as in headers and footers; for this example, I focus on headers and footers.

Creating a User Variable

Let's create a user variable with the name "doctitle" for use in the document header. The definition of doctitle is "Technical Bulletin No. 1086", the name of the document.

Back to Basics

If the insertion cursor is not in the text, the Variable menu command is gray and inaccessible.

  1. Place your insertion cursor in the header text frame on a master page.

    This is where the document title is displayed.

  2. Select Special > Variable.

    The Variable window appears.

  3. Click on the Create Variable button.

    The Edit User Variable window appears.

  4. Type "doctitle" in the Name field.

    The name "doctitle" for this variable displays in the Variables list window after you finish creating the variable.

  5. Type "Technical Bulletin No. 1086" in the Definition field, as shown in Figure 4.4.

    Figure 4.4. The Edit User Variable Window.

    This is the actual information that is displayed in the header.

Back to Basics

Split user variables into two separate lines by inserting \h in the user variable definition. The code \h means "soft return."

  6. Click on Done.

    You return to the Variable window. Notice that the name of the variable you just created is displayed and highlighted in the Variables list, and the variable definition is displayed directly below the variable list (see Figure 4.5).

    Figure 4.5. The Variable Name and Definition is displayed.

  7. Click on Insert.

    The document title variable is inserted into the header.

Making Changes in a User Variable

After you have user variables in FrameMaker documents, making changes is relatively easy. You'll really appreciate this feature when you use the same template for another set of documents with a new document title.

Here's how it works: Suppose that you take an existing FrameMaker document with a user variable, doctitle, for the document title and use that document as the template for a new document with a new title. You can instantly change the document title name that's already been inserted as doctitle in one or more header or footer locations in two ways: either from a master page or a body page.

Changing a User Variable from a Master Page

To change a user variable from a master page, follow these steps:

  1. Double-click on the document title.

    The Variable window appears with the variable doctitle selected.

  2. Click on Edit Definition.

    The Edit User Variable window appears.

  3. Edit the text in the Definition field. After you finish, click on Done.

    You return to the Variable window. The new document title appears below the variable list when doctitle is selected in the list.

  4. Click on Done.

    All occurrences of this variable automatically update and display the new information. You do not have to click on Replace, because that simply replaces the current user variable with itself.
Changing a User Variable from a Body Page

You can change a user variable from a body page by following these steps:

  1. Select Special > Variable.

    The Variable window appears.

  2. Select doctitle from the Variables list. Click on Edit Definition.

    The Edit User Variable window appears.

  3. To complete this exercise, continue with Step 3 of the previous list to change a user variable from a master page.

Note

The insertion cursor must be in any text frame or some menu selections will not be accessible.

Tricks with Volume Numbers

Instead of a user variable, you can also use the volume number variable in FrameMaker to implement a fixed header or footer.

Typically, volume numbers in FrameMaker are used to create automatic multi-level numbering. This is especially handy when you work with book files. Then each file in the book can be specified either to have the same volume number as the file that precedes it in the book, or to have the next incremental number.

Note

For information on using a volume number in cross-references, see Chapter 5.

However, you can also use the volume number function to insert a document title or some other textual information that you want to display in the header or footer on each page of your document. (You cannot use this particular method if you plan to use the Volume Number function for an actual volume number in your FrameMaker documents.)

Setting Up Volume Number Text

Using the previous example in this section for a user variable, here's how to set up a volume number to use as header text:

  1. Select Format > Document > Numbering.

    The Numbering Properties window appears.

  2. Click on the Volume tab or select Volume from the drop-down list.

    The Volume numbering properties appears.

  3. From the Format drop-down list, select Text.

    This allows for text entry into the Volume # field. If you do not select Text from the format menu, you can still enter text in the Volume # field, but you get an error message when you click on the Set button.

  4. Type "Technical Bulletin No. 1086" in the Volume # text field. Click on the Set button after you finish.

    You have completed the setup of the text field for the Volume Number (see Figure 4.6). The volume number is not yet displayed in any header or footer.

    Figure 4.6. The Volume Numbering properties is switched to Text.

Now that you have set up the volume number to display text, you can now move on to inserting its special variable into the header of the document.

Inserting the Volume Number Variable

The following steps start on the master page, with the insertion cursor in the background text frame for the header:

  1. Select Special > Variable.

    The Variable window appears.

  2. Click one time on Volume Number in the variable list to select it.

    The variable for Volume Number displays directly below the Variables list, as shown in Figure 4.7.

    Figure 4.7. The Volume Number in the Variable list.

  3. Click on the Insert button.

    The Volume Number variable is inserted at the insertion cursor location. The text that you previously set up in the Numbering Properties for Volume # is displayed.

    To edit the text, follow the steps in the section "Setting Up Volume Number Text" on page 88.

The headers and footers that you learned about so far represent some powerful yet basic types in FrameMaker. Coming up next: some more complex types that are commonly used in real-world documents.

Working with Varying Headers and Footers

The power of varying headers and footers to work their magic within FrameMaker documents can be a source of lasting amazement.

Varying headers and footers do just what the name indicates. They vary, or change, from page to page in your document, based on page content. In FrameMaker, they are also known as Running H/F variables. When they are inserted into a master page, they appear to have no fixed value and are displayed according to their name. When viewed from body pages, they assume a value based on content in your document that is tagged with particular paragraph tags.

Here's a simple example: Say that your document must have a chapter title and you want to display that chapter title on each page in the header of your document. You can define the special Running H/F variable to refer to the chapter title in your document, and insert that variable in your document header. Then that header will always display the content as the chapter title of your document. If you edit the chapter title, the document header automatically changes based on the new information contained in the chapter title.

After Running H/F variables are set up in your document, you can focus on the real work of writing. (Remember the scary ol' days before features like this existed?)

This section looks at what makes Running H/F variables tick and how to create, edit, and maintain them. Throughout the exercises, you see how to avoid common problems, and you learn what to look for if you've already run into problems with existing Running H/F variables.

How Varying Headers and Footers Work

So far, you have seen that FrameMaker comes loaded with a vast array of variables to choose from, each one with its own function. Four of these have been specially designed for varying headers and footers. You might have seen them in the list of variables or viewed them on master pages of your document. They are formally known as

  • Running H/F 1

  • Running H/F 2

  • Running H/F 3

  • Running H/F 4

Back to Basics

Running H/F variables cannot be viewed in the Variables list from body pages and must be viewed from master pages.

Although most variables in FrameMaker have editable names, these variables do not. You cannot change the name of a Running H/F variable, but you can change its definition.

Earlier, in the section "Industrial-Strength System Variables" on page 81, you learned that Running H/F variables function as containers, which allows you to store references to particular paragraph tags that occur in your document.

Running H/F variables are inserted as background information on master pages and they don't reveal their content. When you view master pages, the variable name itself displays. For example, if you use the Running H/F 1 variable to construct your varying header, "Running H/F 1" is displayed on the master page, as seen in Figure 4.8.

Figure 4.8. The Running H/F variable on a master page.

When it's viewed from body pages, the variable reveals the actual content of the particular paragraph tag that is referenced in the variable. Figure 4.9 shows an example of a variable that references the chapter title paragraph tag and, therefore, displays its content in the document header.

Figure 4.9. An example of a Running H/F variable on a body page

The Paragraph Tag Connection

As previously mentioned, Running H/F variables are connected to paragraph tags. To illustrate, continue the example on how to include a chapter title in a header.

If you set up a specific paragraph tag, such as "Chapter Title", to contain the chapter title of your document, you can make the chapter title show up in a header (say, at the top of every left page) by setting up the Running H/F variable to store a reference to the Chapter Title paragraph tag.

After you set up a Running H/F variable to refer to paragraphs tagged Chapter Title and insert the Running H/F into a header on the master page, then, when you print the document or view body pages, the content of the most-recent paragraph tagged with the Chapter Title paragraph tag is displayed on each page where the selected header was placed.

What if more than one chapter title exists in a document (that is, more than one paragraph is tagged with Chapter Title)? In this case, the first chapter title remains in effect until the next occurrence of a paragraph tagged with Chapter Title. That next occurrence is in effect until another occurrence is found.

Some Things to Keep in Mind

Tip

If Running H/F variables are not working properly, check to make sure at least one paragraph is tagged with the referenced paragraph tag.

Whether you create, modify, or simply work with existing variables in headers or footers, this section is worth reading to avoid problems.

Because paragraph tags make Running H/F variables tick and are an integral part of how they function, you should be aware of a few things when you work with Running H/F variables. Now is a good time to review your document and note the following:

  • You need to type the names of paragraph tags when you introduce them into Running H/F variables. Therefore, make sure you know the exact spelling, including upper and lower case, of the paragraph tags you want to use in varying headers and footers. Running H/F variables do not work if the spelling is incorrect or if extra spaces are added to the paragraph tag name in the variable.

  • If the paragraph tags include autonumbering, be aware of how the autonumber is constructed. For example, if the autonumber includes text in the format, this text is included in the header along with the autonumber.

  • Avoid spaces when possible in paragraph tag names. This makes it easier to incorporate tags without errors, because extra spaces are sometimes difficult to detect in paragraph tag names.

  • Keep paragraph tag names short and simple. Running H/F variables have a length limitation of 255 characters. If you can choose whether the paragraph tag name for the first-level subheadings in your document will be H1 or HeadingOne, go with the short version. It saves you from potential problems later.

Tip

If empty paragraph returns are tagged with referenced paragraph tags, the headers and footers appear empty.

Whew! It sounds complicated. Try an example to clear up some of the mystique.

Creating a Simple Varying Header

Although I refer to "headers" in the following examples, in the real world you can use these concepts and exercises equally well for either headers or footers. It's up to you.

In this section, you are guided through the steps in working with a simple varying header, including planning, creating, editing, and adding autonumbers or character formatting.

Planning for Simple Varying Headers

In the first example, say that you have a FrameMaker document that includes a chapter title paragraph tag that is constructed to include the word "Chapter" followed by an automatic chapter number and typed title text. Table 4.1 illustrates the tag name, how content is displayed, and the paragraph tag autonumber format.

Table 4.1. Paragraph Tag Names for Chapter Title

Paragraph Tag Name

Description

Autonumber Format

ChapTitle

Chapter 2 The Great Unknown

C:Chapter <$chapnum>\t

Understanding the location and purpose of varying headers or footers is a good idea before creating them. Following is a description of each of these:

  • Location. Decide where information will be displayed—whether in the header or in the footer, and whether on the left page, the right page, or both. If you haven't done so already, set up master pages to include background text frames for the headers and the footers.

  • Purpose. Determine the purpose of your varying running header and how it will be displayed in the header of your document. For instance, will your header include the word "Chapter" and the chapter number, or just the chapter title?

Back to Basics

On master pages, use the Text Frame tool in the Graphic toolbox to create background text frames.

For this exercise, start with a simple running header that includes the chapter title only. Then, build on what you've learned and move on to include the word "Chapter" and the chapter number. Finally, you add character formatting.

Creating a Running H/F Variable

To create a Running H/F variable, go directly to the master page of the document and click inside the header of your document. This is the location where the Running H/F variable will be inserted.

When you work with variables on the master page, you must have the insertion cursor inside a background text frame. If your cursor is not in a background text frame, either you won't be able to select Variable from the Special menu or you are prompted that you cannot perform this function.

In this exercise, you create a new definition for a Running H/F variable. Here's how to do it, beginning with the insertion cursor inside the background text frame for a header:

  1. Select Variable from the Special menu.

    A list of variables appear. Some items in the list are included with FrameMaker's default variables, whereas others might have been defined by coworkers or past template creators.

  2. Select Running H/F 1.

    The definition of this variable is displayed directly below the list of variables, as shown in Figure 4.10. This helpful information provides an instant view of the current construction of that variable.

    Figure 4.10. Variable Window with Running H/F 1 Definition displayed.

  3. Click once on Edit Definition.

    The Edit System Variable window appears with the Definition text already selected. This window includes the Definition text field and a list of Building Blocks (see Figure 4.11). Building Blocks are the containers that define the information that is referenced and displayed in your running header.

    Figure 4.11. The Edit Variable Definition window.

  4. Delete the current information in the Definition text field.

    Delete that material so that you can start from scratch in this exercise.

Back to Basics

To delete text in the Definition text field, select the text and press the Backspace or Delete key.

  5. Click once on <$paratext[paratag]> in the Building Blocks list.

    The Building Block <$paratext[paratag]> is inserted in the Definition text field. In this Building Block name, "$paratext" means that the text is inserted from a selected paragraph in your document, and "paratag" is a placeholder for the actual tag of the paragraph that you want to reference.

  6. Select the word "paratag" in the Building Block you just inserted. Replace this word by typing ChapTitle.

    Don't delete any angle brackets < > or the dollar sign $. The Building Block now reads <$paratext[ChapTitle]>. This Building Block means that any paragraph tagged with ChapTitle is referenced in this running header. ChapTitle is the paragraph tag name for chapter titles in the example document, so the Building Block inserts the text of the chapter title.

Note

Running H/F variables do not work correctly if the referenced paragraph tag name is not exactly as it appears in the Paragraph Catalog.

  7. Click on the Edit button.

    You return to the Variable window. Notice that, in Figure 4.12, the variable you just edited is selected in the list, and its definition is displayed directly below it.

    Figure 4.12. The Variable window with Running H/F 1 selected.

  8. Click on Insert.

    The Running H/F 1 variable is inserted and displayed in the master page header of the document. As shown in Figure 4.13, the name of the variable is displayed and not the referenced information.

    Figure 4.13. The Running H/F variable is displayed on the master page.
Inserting the Running H/F Variable in Another Location

After you create a Running H/F variable to use in your document, you can insert it into any master page background text frame. You might want to do this if you plan to display the chapter title text on both the left and right headers in your document or if you use several other types of master pages.

Back to Basics

FrameMaker documents can contain up to 100 master pages.

Insert the Running H/F 1 that you just created into another master page in the document:

  1. Place the insertion cursor in the background text location on a different master page.

  2. Select Special > Variable.

    The Variable window appears with a scroll list of available variables.

  3. Click one time on Running H/F 1 in the Variables list.

    The definition of this variable is displayed directly below the list.

  4. Click on the Insert button.

    The Running H/F 1 variable is inserted and displayed in the new location.
Viewing and Testing a Running Header

Tip

Use Esc v Shift-b to go from a master page to a body page, and Esc v Shift-M to go from a body page to a master page.

Running H/F variables do not reveal themselves on master pages and are displayed with their actual name in that location. When creating or editing these type of variables, you will find yourself going back and forth between master and body pages to check whether they are working properly. That's to be expected.

In this example, you reference the ChapTitle paragraph tag in the document. Make sure that at least one paragraph in your document is tagged with this paragraph tag in order to test it. If not, the running header variable doesn't have text to reference and displays nothing.

  1. View the running header from a body page of your document. The header text should be identical to the chapter title text in your document. This does not include the chapter number or the word "Chapter".

    If your running header correctly displays the chapter title, save your file. In a subsequent exercise in this section, you add the word "Chapter" and the chapter number to the header.

  2. Edit the chapter title text by replacing the current chapter title with new information. Type whatever you want as replacement text.

    The running header automatically updates with the new information.

Tip

Use Window > Refresh if the information does not instantly update itself.

Editing a Running H/F Variable

Now that you know how to create a simple running header, editing the Running H/F variable definition is a breeze! For example, maybe you want subheading content to be displayed in the header rather than chapter-title content.

For this exercise, you replace the referenced paragraph tag, ChapTitle, with H1, the paragraph tag for level 1 subheading text.

Tip

Double-click on any variable for quick access to the Variable window.

  1. From the master page, double-click on Running H/F 1.

    Notice that it is a block of text rather than separate characters. The Variable window is displayed with Running H/F 1 already selected in the list of variables.

  2. Click on Edit Definition.

    The Edit System Variable window appears. Beware of your fast-typing fingers (and mouse fingers) on this one! The definition text is automatically selected when the window appears. If you hit any key, it's deleted. Likewise, if you click on the Building Blocks list, the Building Block on which you happen to click replaces the entire definition. If you make either mistake, you can recover it as long as you don't press Enter or click any button onscreen. Just click on Cancel or press Esc.

  3. Select ChapTitle in the variable definition. Replace this by typing H1 in its place.

    H1 is the name of the paragraph tag used for level 1 subheads. The Definition text field displays <$paratext[H1]>.

  4. Click on the Edit button.

    You return to the Variable window.

  5. Click on Done.

All occurrences of this variable in this document automatically update with the new information. This means that the most recently encountered level 1 subheading text and not the chapter title text is displayed in the header of each page.

Note

To test this header, make sure at least one paragraph in the document is tagged with H1.

Adding Autonumber Formats

So far, you created a running header that displays the chapter-title text. Take this exercise one step further and add the word "Chapter" and the chapter number to the header. Going back to the document that you saved earlier in Step 1 of the section "Viewing and Testing a Running Header" on page 97, which showed the chapter title, the current header reads

The Great Unknown

You want the resulting header to read

Chapter 2 The Great Unknown

  1. From the Master page, double-click on Running H/F 1.

    The Variable window appears with Running H/F 1 already selected in the list of variables.

  2. Click on Edit Definition.

    The Edit System Variable window appears. Leave the current definition as is. You need to include it in the new definition.

  3. Place the insertion cursor immediately before the current definition.

    This is where you add the new Building Block that will reference the autonumber format of the chapter title. Information that is added at the beginning of the definition is displayed at the beginning of the header when it's viewed from the body page.

  4. Click once on <$paranum[paratag]> in the Building Block list.

    The Building Block <$paranum[paratag]> is inserted in the Definition text field. Just as "$paratext" specifies a Building Block that incorporates the text of a paragraph, "$paranum" specifies a Building Block that refers to the autonumbering of a particular paragraph, including any text that is part of the autonumber format. As before, "paratag" is a placeholder that you will replace with the actual paragraph tag that you want to reference in your document.

  5. Select paratag. Replace this by typing ChapTitle.

    The Building Block now reads <$paranum[ChapTitle]><$paratext[ChapTitle]>, as seen in Figure 4.14. Any paragraph tagged with ChapTitle will be referenced in this running header for both the autonumber and text.

    Figure 4.14. The edited Building Block.

  6. Click on the Edit button.

    You will be returned to the Variable window. Notice that the variable you just edited is selected in the list, and its definition is displayed directly below the list.

  7. Click on Done.

    All occurrences of this Running H/F 1 variable update and are displayed in the header of the document.

Tip

If you cannot see all characters in the definition text field, use Ctrl-left or right arrow key to scroll left and right.

Switch to the body pages and check that the running header is working correctly. Look in the header. You see good news and bad news:

Chapter 2 The Great Unknown

The good news is that the header already includes the word "Chapter" because the autonumber format for the chapter number already contains the word "Chapter" (refer to Table 4.1).

Now the bad news: Notice that no space exists between the number 2 and the word "The" at the beginning of the chapter title.

Don't panic; everything can be fixed. Try some detective work to find out why this happened. Is the source of the problem in the paragraph content itself? No, because you do not want the chapter title to have a space in front of it. Therefore, you need to return to the Running H/F 1 variable to see what happened.

Tip

If referenced paragraph tag names are not identical in both Building Blocks, the heading will not read correctly (text with no autonumber or vice versa).

Switch back to the master page and double-click on the Running H/F 1 variable. Look at the definition displayed below theVariables list. The two Building Blocks have no space between them. That problem can easily be fixed. Click on Edit Definition, click in the definition between the two Building Blocks, and insert a space so that the definition reads as follows:

<$paranum[ChapTitle]> <$paratext[ChapTitle]>

Update this variable by clicking Edit and Done. The problem is fixed. Confirm this fact by switching to a body page.

Save the document. In a subsequent example, you'll add character formats to change the appearance of the header.

More on Autonumber Formats

You might not want the word "Chapter" included in your real-world document header. Perhaps your document design calls for just the chapter number itself and accompanying text.

The problem—which was an advantage with the word "Chapter"—is that paragraph tags are sometimes constructed with words such as "Chapter" as part of the autonumber format (refer to Table 3.1 on page 46).

You can work around this difficulty in FrameMaker in a few ways. First, you can see how it's done by using a different Building Block. Then you review achieving the same result by adding a system variable in the header along with Running H/F 1. Either way works—it's up to you.

Using Building Blocks with "only"

FrameMaker provides alternative Building Blocks that enable us to include just the autonumber itself in the header and exclude the word "Chapter" even if it is part of the autonumber format. The following steps begin with the Edit System Variable window for Running H/F 1:

  1. Select the Building Block <$paranum[ChapTitle]> and delete it.

    You replace this Building Block with a different one that includes the numeric part of the autonumber format only.

  2. Select <$paranumonly[paratag]> from the Building Blocks list.

    The Building Block <$paranumonly[paratag]> is inserted in the Definition text field immediately before <$paratext[ChapTitle]>. Whereas "$paranum" includes the entire autonumber format that is part of a tag, including any text that is built into the format, "paranumonly" incorporates only the autonumbers of the referenced paragraph tag and does not include any text that is part of that autonumber format.

  3. Select paratag. Replace this by typing ChapTitle.

    The definition now reads

    <$paranumonly[ChapTitle]> <$paratext[ChapTitle]>

    This definition is shown in Figure 4.15. This means that this running header contains the paragraph number only; no text is included in the autonumber format, and the text content of the most-recent paragraph tagged with ChapTitle. Don't forget to make sure a space exists between the Building Blocks.

    Figure 4.15. The Paranunonly Building Block in Running H/F 1 Definition.
Using the Chapter Number System Variable

You can combine the method of this section with that of the section "Starting with the Easy Stuff" on page 82 to get a header containing the chapter number and chapter title. As noted previously, the system variable Chapter Number can be set up to contain the chapter number. This system variable can be put into the header along with the Running H/F variables. The following steps begin on the master page:

Note

For this method to work, the chapter number must be set in Format > Document > Numbering.

  1. Click in the header background text frame immediately to the left of the Running H/F 1 variable.

    Do not click on the Running H/F 1 variable itself.

  2. Select Special > Variable > Chapter Number. Click on Insert.

    The Chapter Number variable is inserted directly in front of the Running H/F 1 variable. The chapter number appears as a number on the master page and from body pages.

  3. Type a space.

    This space is needed to separate the chapter number from the Running H/F 1 variable that contains the title.

  4. Double-click on Running H/F 1.

    The Variable window appears with Running H/F 1 selected in the list.

  5. Click on Edit Definition.

    The Edit System Variable window appears with the definition selected.

  6. Select <$paranum[ChapTitle]> and delete it.

    You do not need Building Block <$paranum[ChapTitle]> because the chapter number is displayed from the Chapter Number variable inserted in the header in Step 2. Make sure no spaces are around the remaining Building Block. The necessary space between the chapter number and the chapter title was inserted at Step 3.

Tip

Watch fast-typing fingers here or the entire definition will be deleted.

When you return to the master page header, the completed header should look like Figure 4.16.

Figure 4.16. The final result of the Chapter Number variable with Running H/F 1.

Adding Character Formatting

Now that you have a varying header, you need to make it look fancier by putting the chapter number in bold.

Headers and footers take on the default formatting of whatever paragraph tag is initially applied to that header or footer. For example, if your header has a paragraph tag Header, and that header is formatted as Times, 12 Regular, that is how the header is displayed throughout the document.

By now, you probably noticed that the Running H/F variable behaves like a block of text. Although you can apply a character tag to the entire variable, you cannot use Format > Characters to apply a character tag to just a portion of this block of text. However, you can go back inside the definition of this variable to apply a character tag to a portion of this header.

In the example, the header now looks like this:

Chapter 2 The Great Unknown

It's time to add bold character formatting to the chapter number (but not the title), so that the header looks like this:

Chapter 2 The Great Unknown

Before you get started, it's a good idea to check your FrameMaker Character Catalog for a Bold character tag. If you do not have the tag that you want to use in the header (in this case, Bold), you have to create one. After the correct character tag exists in your FrameMaker template, you can use the following steps, beginning with the Edit System Variable window, to apply that tag to part of the header:

Back to Basics

Use Format > Characters > Designer > Commands > New Format to create new character tags. (Ctrl-D is the shortcut to the Designer window.)

  1. With the insertion cursor immediately before the first Building Block of the definition, <$paranum[ChapTitle]>, select <Bold> from the Building Blocks list.

    The <Bold> Building Block is inserted. This means that all content in the header variable to the right of this Building Block is formatted in accordance with the properties of the Bold character tag.

  2. Place the insertion cursor after the right angle bracket of the <$paranum[ChapTitle]> Building Block. Select <Default ¶ Font> from the Building Block list.

    The <Default ¶ Font> Building Block is inserted. This means that all text to the right is reset back to the normal default font of the paragraph and it's not bold. If you do not reset the font back to its normal state, everything in the header to the right of the <bold> Building Block also becomes bold.

  3. Click on Edit and Done to complete the process.

    The running header displays with bold character formatting for the chapter autonumber and regular character formatting for the remainder of the header.

Displaying Multiple-Level Headings in a Varying Header or Footer

Previously, you worked with a simple varying running header that referenced one heading level in your document: the chapter title. In this section, you explore more-complex varying running headers that have the ability to display any one of several subheading levels. For the example, say that your document has three levels of numbered subheadings. The tag name, how the subheading is displayed in the document, and the construction of the autonumber format for each subheading paragraph tag are shown in Table 4.2.

Table 4.2. Paragraph Tag Names for Chapter and Subheadings

Paragraph Tag Name

Description

Autonumber Format

H1

2.1 A Territory Divided

C:<$chapnum>.<n+>

H2

2.1.1

C:<$chapnum>.<n>.<n+>

H3

2.1.1.1

C:<$chapnum>.<n>.<n>.<n+>

The objective is to display the content of any one of these subheadings, as it occurs in the document. Technically speaking, the first paragraph with one of the referenced paragraph tags on any given page is displayed in the header of the document on that page. On the next page where any one of the subheadings is found in the document, the header displays that information.

For example, if a paragraph tagged with H2 is the first H1, H2, or H3 that occurs on page 5 of the document, the header displays the content of the paragraph tagged with H2. If a paragraph tagged with H3 appears on page 5 first, that paragraph's content is displayed in the header.

Creating a Multiple-Level Varying Header

For a refresher on creating a simply varying running header, see the section "Creating a Running H/F Variable" on page 94. You begin these steps from the Edit System Variable window and focus just on the multiple paragraph tag information, as previously outlined in Table 4.2.

In the first example, you create a multiple varying header that references the subheading text of any one of three subheadings in the document (H1, H2, H3). This example does not include the autonumber format. I cover that later in this chapter.

Make sure that some paragraphs in your document are already tagged with H1, H2, and H3 paragraph tags. Then, when you test this header, you'll know if it's working correctly.

Back to Basics

If no paragraphs in the document are tagged with H1, H2, or H3, nothing shows up in the header.

To create a multiple-level varying header, follow these steps:

  1. Delete the current information in the Definition text field.

    You must do this to start with a clean slate for this exercise.

  2. Click once on <$paratext[paratag]> in the Building Blocks list.

    The Building Block <$paratext[paratag]> is inserted into the Definition text field. As you learned, "$paratext" means that only the text of referenced paragraphs in your document is displayed in the header, and "paratag" is a placeholder for the actual paragraph tag that you want to reference.

  3. Select paratag in the definition. Replace it by typing H1,H2,H3.

    The Building Block now reads <$paratext[H1,H2,H3]>. The commas are part of the definition and are used to separate multiple referenced paragraph tags. This means that any paragraph tagged with either H1, H2, or H3 can be referenced and displayed in the header of your document. On any page, FrameMaker displays the first paragraph found tagged with any of the three paragraph tags.

Although no necessary limit exists to the number of paragraph tags that you can include in a Building Block, there is a limit as to how many characters can fit in the Definition text field. The magic number is 255. If you want to include many levels of subheadings in headers and footers, it's a good idea to keep paragraph tag names short, so you don't exceed the character limit of the Definition text field.

Back to Basics

You can create or rename paragraph tags with Format > Paragraphs > Designer > Commands.

In the next example, you see how the Definition text field can get crowded.

Adding Autonumber Formats

Now that you have a header that references the text of multiple levels of subheadings in your document, try adding some autonumbers to the header. For this exercise, you edit the Running H/F that you worked with in the previous example. Start from the Edit System Variable window:

  1. Place the insertion cursor immediately before the current definition.

    This is where you add the new Building Block that references the autonumber format of the three subheading levels in the document. The autonumber format, in this case, doesn't include text (refer to Table 4.2. )

  2. Click once on <$paranum[paratag]> in the Building Blocks list.

    The Building Block <$paranum[paratag]> is inserted into the Definition text field. This block means that the autonumber of a paragraph whose tag you type in place of "paratag" appears in the heading.

  3. Select paratag. Replace this by typing H1,H2,H3.

    The commas are part of the definition. Be sure to include them between paragraph tag names. The Building Block now reads <$paranum[H1,H2,H3]> <$paratext[H1,H2,H3]>, as shown in Figure 4.17. Any paragraph tagged with either H1, H2, or H3 is referenced in this running header for both the autonumber and text.

    Figure 4.17. The result of editing the Building Block.

Tip

You might not see all characters in the Definition text field. Use Ctrl left or right arrow keys to scroll left and right.

Changing the Default Order of Running Headers

Whether you reference one paragraph tag in the header or several, the default order in which FrameMaker displays this referenced content in the header is the order in which it was found in the document. Using the example of multiple subheading levels, if three paragraphs on a page are tagged with any one of the three paragraph tags that are referenced in the header, the first one found on the page is displayed in that header.

In the real world, the default order might not work well for your document. If you prefer to have the last item found on a page displayed in the header, you can do this easily with one small change to the Running H/F building block. Just type a plus sign (+), followed by a comma (,) in front of the first referenced paragraph tag, as shown in Figure 4.18.

Figure 4.18. You can reverse the running headers' default order by typing a few keystrokes.

If you are referencing just one paragraph tag, the same method applies. For example, <$paratext[+,H1]> causes the text of the last level 1 subheading on a page to be displayed in the header.

For the example that shows the autonumber and text of any level 1, 2, or 3 subheading, make sure that if you make this small but powerful change to the <$paranum[H1,H2,H3]> Building Block, you also make the same change to the <$paratext[H1,H2,H3]> Building Block. If not, you end up with the autonumber from the last found item on a page, followed by the text of the first found item on a page.

Dictionary-Style Headers

Dictionary-style headers are the headers at the top of left pages that display the first-referenced content on those pages and the headers at the top of right pages that display the last-referenced information on those pages. Pretty clever.

These headers work great for dictionaries (obviously), glossaries, indexes, or other reference material that has an alphabetical, or some other, order to it. Readers can get a better grasp on where they are in documents laden with pages and pages of such reference material.

Setting up this type of header is no different from setting up varying headers. But, you must follow one critical procedure: On the left master page, set up a Running H/F variable (say, Running H/F1) to display referenced paragraph tags in the default order. Then set up a different variable (say, Running H/F 2) on the right master page exactly the same as the Running H/F 1, except that you must add the plus sign and comma (+,) before the first-referenced paragraph tag. Then, the right page header will show the last item on the page instead of the first.

Using Abbreviated Headings

Just when you thought you explored all FrameMaker's powerful header and footer features, one more slick feature dazzles and amazes you.

Previously, I focused on headers and footers that have the ability to display text from the content of documents automatically. Now, you explore headers and footers that can display text that is not really part of your document—specifically, text that is hidden from view to begin with and not intended for viewing in the body of the document at all. Why would you want to do this? That's a good question.

Suppose that the document header must contain the number and text of level 1 subheadings. If those level 1 subheadings are wordy, they probably won't fit into the space available for the header. So, you need to abbreviate the header in order to make it fit. Thankfully, FrameMaker provides a method to produce abbreviated headers and footers.

Back to Basics

When you work with markers, keep text symbols turned on or you will not see the markers.

Here's how it works: If you have subheadings (or other referenced paragraphs) that are too long to be displayed in the header of your document, use Header/Footer markers instead of <$paratext[paratag]> Building Blocks in your Running H/F variables. You have two markers to choose from: Header/Footer $1 and Header/ Footer $2. The markers, rather than the actual subheadings, contain the text that you want to be displayed in the header. The marker is placed in the text at the location of the intended reference paragraph.

Let's go through the steps necessary to achieve this task. In this example, you set up a header that uses a marker instead of subheading level 1. The marker text and not the subhead level 1 text is displayed in the header of the document.

Begin by inserting a marker:

  1. With your insertion cursor at the beginning of a long subheading text, select Special > Marker > Header/Footer $1.

    The Marker window appears.

  2. Type text in the Marker text field.

    This text is what you want to display in the document header instead of the content of the referenced paragraph tag (see Figure 4.19).

    Figure 4.19. You must type the marker text that will be displayed in the header.

Back to Basics

You can use Special > List Of > Markers to get a list of all marker text and associated page numbers.

  3. Click New Marker.

    The marker is inserted at the insertion cursor location.

Next, set up the running header to reference the marker text instead of subheading text. These steps begin and end at the Edit System Variable window:

  1. Select <$paratext[H1]> and delete it.

    Clear the existing header variable so that you can start anew.

  2. Select <$marker1> from the Building Blocks list.

    The Building Block <$marker1> is inserted in the Definition text field. The block <$marker1> corresponds to the marker Header/Footer $1, and <$marker2> corresponds to the marker Header/Footer $2.

If you decide to use this method to reference particular information, you cannot also use the referenced paragraph tag method. You must set a Header/Footer 1 marker for every level 1 subheading in the document. Otherwise, level 1 subheadings that do not have markers are not reflected in the headers.

Summary

This chapter was certainly a brainful! You learned that several ways exist not only to incorporate various headers and footers into FrameMaker documents, but to change the format as well.

These distinctive FrameMaker features add considerably to the part of the workload that you can shift to the computer. Of course, that's when everything is working properly. If it's not, this chapter gives you some ammunition to get in there and fix it.


Chapter 5

Chapter 5. Cross-References

  • Typical Uses of Cross-References
  • Planning for Cross-References
  • How Cross-References Work
  • Understanding the Cross-Reference Window
  • Cross-Reference to a Subheading
  • Cross-Reference to a Numbered Figure
  • Cross-Referencing Other Document Files
  • Creative Cross-References
  • Cross-References and Conditional Text
  • Cross-Referencing in Book Files
  • Cross-References and PDF or View Only Files
  • Updating Cross-References
  • Unresolved Cross-References
  • Summary

Often, a new piece of information that you encounter becomes meaningful or understandable only when it relates to some other item of information that you have already encountered. This is true whether you're reading from a book, browsing the Web, or listening to a CD.

As information receivers, people don't give much thought to cross-references. They are simply a part of life. As a writer, you must give cross-references more consideration. You need to manage the connections between items of information within documents actively.

In the old days when all documents were generated on paper, or even with simple text editors, keeping track of the "shadow map" or web of cross-reference relationships within documents was an overwhelming manual task. Whenever page numbers or content changed, the process of updating cross-references not only had a high-error rate, but it took an insane amount of time. FrameMaker makes it easy to include, update, and maintain cross-references in your documents. What used to take hours now takes seconds. Ahhh ... the wonder of technology.

This chapter explores the world of cross-references according to FrameMaker. You begin with typical uses and how they work before you move on to the finer detail of integrating cross-references into documents. I also review how to get those cross-references looking their best, what to do when they misbehave, and how to use them in creative ways.

Typical Uses of Cross-References

In the real world, cross-references refer readers to another location in the document that contains related information. For example, technical writing steps might refer readers to a figure that illustrates what the author is communicating. Or an overview of a topic might refer readers to a more-detailed discussion on the same topic somewhere else in the document.

Typically, cross-references are structured like this:

  • See Figure 2.3 on page 4

  • See Figure 2.3

  • Figure 2.3

  • See Chapter 9, "The Good Life," on page 70

  • Page 70, "The Good Life"

  • See Problem 6 in Section 7.3.

You can structure cross-references in your documents in many ways. How you structure cross-references in your documents is up to you. This chapter provides a solid foundation on which to build a variety of cross-references in your documents.

Planning for Cross-References

As the creator of cross-references, it's important that you present cross-references in a consistent manner throughout your documents. In the same way that each page of your document follows a consistent layout, consistency applies to cross-references for both appearance and structure. With consistent cross-references, your readers have an easier time recognizing cross-references in documents and navigating through pages.

Therefore, before you start cross-referencing, make a plan. Although FrameMaker's powerful cross-referencing tools make it easy to create and maintain cross-references, you must come up with a format that works well for your documents and decide what type of things you want to cross-reference. Your plan will consist of the following:

Note

See Chapter 3 for information about setting up numbering for sections, figures, and tables.

  • Make a list of the type of items that you plan to cross-reference—for example, chapters, sections, figures, tables, and pages.

  • Decide how you want to format cross-references to each of the selected elements. For example, if sections have both numbers and titles, do you want to refer to them by both number and title or by number only? How do you want to set off the title (for example, in quotation marks or in parentheses)? Do you want to use the word "See" or avoid it? Settle on a few (usually two or three) standard cross-reference formats for each type of element.

After you have a good idea of the type of cross-reference formats you plan to use in documents, put some example cross-references together and create all the formats you will need first. The next section discusses specifically about how cross-references work in the world of FrameMaker.

How Cross-References Work

Cross-references in FrameMaker are comprised of two parts: source and format. Regardless of how you want to structure your cross-references, understanding these two parts is essential to successful integration of cross-references in your real-world documents.

Source Information

The source of a cross-reference is the information that identifies what is being referenced. For example, if a cross-reference reads

See Chapter 9, "Ain't Life Grand," on page 77

the Chapter 9 heading is the source for that cross-reference. If a cross-reference reads

Figure 9.3 on page 7

the Figure 9.3 numbered title is the source for that cross-reference.

Source information is identified in FrameMaker by either paragraph tags or spot cross-reference markers.

Paragraph Tags

As you know, each paragraph in FrameMaker is identified with a paragraph tag. Therefore, paragraph tags are the most-commonly used way to indicate source information in cross-references. Most of the time, the information being referenced is a chapter title, subheading, or figure title, and usually consists of one or two lines.

Here is how paragraph tags work with cross-referencing: Say that chapter titles are tagged with the paragraph tag Chapter. If you want to use the chapter title as the source of your cross-reference, you would select the Chapter paragraph tag as the source type. Then a list is displayed with all paragraphs in the selected document that are tagged with Chapter. Next, choose which particular paragraph you want to use as the source text for the cross-reference.

Note that if you include the page number as part of cross-references, the page number is always that of the first page that contains the source information. If the cross-reference refers to a figure, the page that will show up in the reference will be the one on which the figure appears. If the cross-reference is to a chapter or section heading, the page will be the one on which the chapter or section title appears—regardless of how many pages the chapter or section spans.

Spot Cross-Reference Markers

Back to Basics

Page numbers in cross-references refer to the first page of source information.

If your sections are sufficiently short that the information to which you want to refer the reader at least begins on the first page of its section, a cross-reference to the paragraph tag for the section heading will direct the reader to the correct page. On the other hand, if the source information to which you want to refer is (or might be) located somewhere after the first page of a section that spans two or more pages, spot cross-referencing is another method that you can use.

Spot cross-references are indicated with a special cross-reference marker rather than a paragraph tag. You can insert a spot cross-reference marker at the exact location of the text you want to reference, such as the second page of the source section.Then the page number displayed in the cross-reference will be the correct page that contains the source information, rather than the first page of the section that contains the section head.

Cross-references to a logical unit in the document, such as a numbered section, are often preferred to those that only reference a page number. Therefore, cross-references should be to paragraph tags rather than to spot cross-reference markers wherever possible.

Formatting

After you determine what types of information items you want to cross-reference, the next step is to choose the formats in which you want that information to be displayed. To make that choice, you need to understand the possibilities that FrameMaker offers. For example, say that you want to cross-reference a numbered chapter title in the current document. On the document body page, the chapter title actually reads

Chapter 5 Ain't Life Grand

You might want the cross-reference to read

See Chapter 5, Ain't Life Grand , on page 9.

or

Chapter 5 on page 9, ...

or

(see " Ain't Life Grand")

or

see Chapter 5 (page 9)

The source information can supply an autonumber and title as well as a page number, but you don't have to display all these parts in the cross-reference.

How can these other elements be added, and how can you use FrameMaker to ensure that the cross-references are presented to the user in a consistent manner? That's where formats come in handy. Cross-reference formats are vitally important to the success of cross-references. Formats determine the structure of cross-references. Formats work behind-the-scenes to define how source information is displayed in the cross-reference.

Formats of cross-references are made up of character formatting, constant text, and various parts of the source information itself. For example, the format of the cross-reference

See Chapter 5 , Ain't Life Grand , on page 9.

comprises a combination of various parts of the source information (the chapter number, the chapter title, and page number) with text elements (the words "See Chapter" and "on page" as well as the period, commas, and spaces).

These various parts of source information are represented by building blocks in cross-reference formats. For example, the autonumber format of the source information paragraph, which yields the chapter number when the source paragraph is tagged Chapter, is represented by the Building Block <$paranum>.

You can see that a lot goes into the way cross-references are displayed within content. It's a good idea to decide how you want to display cross-references in documents before you set up cross-reference formats. This is explored in more detail a little later in this chapter.

Understanding the Cross-Reference Window

You will see a lot of the Cross-Reference window if you are working with cross-references in your documents. This is a good time to take a look at the Cross-Reference window and understand the behind-the-scenes elements within it.

As shown in Figure 5.1, the Cross-Reference window is divided into two panes: Source (top) and Reference (bottom). These panes correspond to the source and format categories discussed in the section "How Cross-References Work" on page 115.

Figure 5.1. The organization of the Cross-Reference window.

Source Pane

You use the Source pane of the Cross-Reference window to specify the source information (a paragraph or a spot cross-reference marker) for each cross-reference:

  • Document. Use this drop-down list to select the document containing the source information that you plan to cross-reference. Current, the document in which you are currently working, is the default selection. If you plan to reference a FrameMaker document file other than the current file, that file must be open in order for it to be displayed in the list.

  • Go to Source. Click on this button to go to the source information selected in the lists at the bottom of the Source pane. The Cross-Reference window closes, and the page with the source information appears. If the source information is part of a different document, that document will become active and the page with the source will be displayed. If the source document is closed, you will be prompted to open the source file.

  • Source Type. Choose either Paragraphs or Cross-Reference Markers from the list. Use Paragraphs when referencing actual paragraphs in a source document (such as chapter or section heads, or figures), and use Cross-Reference Markers for spot cross-referencing.

When Paragraphs is selected from the Source Type list, the two lists at the bottom of the Source pane are headed Paragraph Tags and Paragraphs:

  • Paragraph Tags. This is a list of available paragraph tags in the selected source document. Choose one tag from this list to display the paragraphs that have that tag in the right-hand list.

  • Paragraphs. This is a list of the paragraphs in the source document that are marked with the paragraph tag selected from the left-hand list. If you select a Paragraph Tag on the left and no Paragraph on the right, an error message appears.

Note

Source text for a cross-reference to a paragraph is a combination of both a selected Paragraph Tag and Paragraphs text, never just one or the other.

When Cross-Reference Markers is selected from the Source Type list, the two lists at the bottom of the Source panel are headed Marker Types and Cross-Reference Markers:

  • Marker Types. This is a list of the possible types of spot cross-reference markers in the source document. As a default, FrameMaker provides one spot cross-reference marker type, "Cross-Ref."

  • Cross-Reference Markers. This is a list of all the cross-reference markers of the type selected in the left-hand list that are in the source document. Just as a cross-reference to a paragraph requires that you select both a paragraph tag and a paragraph, a spot cross-reference requires you to select both a marker type and a cross-reference marker of that type.

Note

The source for a spot cross-reference is a combination of a selected Marker Type and a Cross-Reference Marker, never just one or the other.

Reference Pane

The Reference pane contains the following features:

  • Format. The current (most-recently selected) cross-reference format is displayed. The name of the selected format appears in the drop-down list window, and the definition of the format is displayed directly below the name. If other formats are available, use the list to display and select another format.

  • Edit Format. Use this to add, change, or delete the selected cross-reference format. Clicking this button brings up the Edit Cross-Reference Format window, described in the section, "Creating a New Format" on page 122.

  • Convert to Text. Cross-references are inserted in documents as blocks of non-editable text, which are updated automatically with changes in source information. If you want to convert a cross-reference to editable text, use this button. After it's converted, the cross-reference will no longer update automatically and will be just like other text in your document.

Note

See page 148 for more information about how and when cross-references are updated.

The Big Five: Built-In Cross-Reference Formats

FrameMaker provides five default cross-reference formats when a new FrameMaker document is started using File > New > Document > Use Blank Paper:

  • Heading & Page

  • Page

  • See Heading & Page

  • Table All

  • Table Number & Page

You might have seen these in the Special > Cross-Reference > Format list. These default cross-reference formats might be included in the FrameMaker template you are using. If so, they may or may not be useful to your document, depending on whether they have been customized. If they have not been customized for your document, you can either delete or ignore those formats that you don't plan to use.

Cross-Reference to a Subheading

Regardless of whether you want to work with cross-references to chapter headings, figure titles, or some other information in your document, these exercises provide you with the understanding necessary to get the job done.

First, I show you how to start out with a simple cross-reference to a tagged paragraph within the same document and build from there, adding more-complicated elements along the way.

For this section, assume that you have a document with numbered subheadings that are tagged with the paragraph tag H2. This second-level subheading comprises an autonumber format (consisting of the chapter number, a section number, and a subsection number) and title text. Table 5.1 shows the name, autonumber format, and display of the Subheading Level 2 paragraph tag. In this example, you also define a new cross-reference format, Subhead. Subhead will display the title of the cross-referenced subsection—that is, the text of the source information subheading paragraph.

Note

See Chapter 3 for more information about autonumber formats.

Table 5.1. Subheading Paragraph Tag Description

Paragraph Tag

Autonumber Format

Display

H2

C:<$chapnum>.<n>.<n+>

9.2.2 Working with Microsoft Word Text

First, I discuss creating a new cross-reference format in the next section, "Creating a New Format," and you will proceed to insert a cross-reference using that format in the section "Setting Up and Inserting a Cross-Reference;" then, in the sections, "Adding Autonumber Formats" through "Volume Numbers," enhancing an existing cross-reference format is discussed. In the real world, you can do these in any order that you want. For example, you can insert a cross-reference before you set up or edit a format, or vice versa.

Creating a New Format

As you read in the section "Formatting" on page 117, formats work behind-the-scenes to display cross-references correctly. This exercise guides you through the steps to create new formats that you might need in documents and also help you understand what's behind the formats you are currently using.

The first format you will create will display the text of the source information in the cross-reference. When a heading is chosen as the source, the cross-reference will contain the title of the section to which the heading belongs.

Here's how to do it:

  1. Select Special > Cross-Reference.

    The Cross-Reference window appears.

  2. Click on Edit Format.

    The Edit Cross-Reference Format window appears. You can use this window to create a new cross-reference format. You can also modify any existing format in the Edit Cross-Reference Format window; it does not matter what format was showing in the Format list in the Cross-Reference window.

The Edit Cross-Reference Format window comprises the following controls:

  • Name. This is the name of the format. This name shows up in the Format drop-down list in the Cross-Reference window. It's a good idea to give formats sensible names so that other people who use them have a clue about their purpose.

  • Definition. This is how the cross-reference is structured. The structure consists of a combination of text and various Building Blocks that represent source information.

  • Formats. This is a list of formats that are included in this document. You can click on any one format in the list to edit its name or definition, or delete it from the list.

  • Building Blocks. Building Blocks represent specific items of source information. For example, the Building Block <$pagenum> causes the page number of the source information to be displayed in the cross-reference, whereas <$paranum> means that the autonumber format of the source information will be displayed in the cross-reference. You can choose any combination of Building Blocks in format definitions.

Note

See Chapters 3 and 4 for more information on the Building Blocks used in autonumber formats and running headers and footers.

Using these controls, you can name and define a new format:

  1. Select the text in the Name field and press the Delete key.

    The current name is deleted from the Name field.

  2. Type Subhead in the Name field.

    Subhead is the name of the new format. This means that Subhead becomes one of the choices in the Format list in the Cross-Reference window.

  3. Select <$paratext> from the Building Block list.

    The Building Block <$paratext> is inserted into the Definition field. The <$paratext> block represents the text of the source information paragraph. If the cross-reference is to a heading, <$paratext> produces the title of the section to which the heading applies. Because <$paratext> is the only Building Block selected, only the text of the source information will be displayed in the cross-reference. Even if an autonumber format is included in the source information, it will not be displayed in this type of cross-reference format.

  4. Click on the Add button.

    The new format, Subhead, is added to the Formats list.

  5. Click on Done.

    You return to the Cross-Reference window. Subhead now displays in the Format list. You can set up and insert a cross-reference with the Subhead format.

Setting Up and Inserting a Cross-Reference

Back to Basics

Click in the paragraph and view the status bar for paragraph tag information.

Now that you defined a cross-reference format in the section "Creating a New Format" on page 122, it's time to figure out how to insert the cross-reference itself. First, place the insertion cursor in the exact location where you want the cross-reference to appear. It's a good idea to know the paragraph tag name of the source information beforehand. If you do not, you will wander through source information in the Cross-Reference window, and that can take some time. For example, if you want to create a cross-reference to a figure title, check the paragraph tag of the figure title before moving on.

To insert a cross-reference, follow these steps:

  1. Select Special > Cross-Reference.

    The Cross-Reference window appears.

  2. Select Current from the Document list in the Source pane.

    Current is the default selection. Use Current when you insert a cross-reference to source information within the same document file.

  3. Click on the Source Type button. Select Paragraph Tags from the Source Type pop-up menu.

    Paragraph Tags is the default selection. Use Paragraph Tags when referencing paragraphs (such as section headers) in a source document.

  4. Select H2 from the Paragraph Tag list on the left.

    H2 is the name of the tag for the type of paragraph (Subheading Level 2) to which you are creating a cross-reference. After the tag name is selected, all paragraphs in the current document that are tagged with H2 will be displayed in the Paragraphs list on the right side. Experiment by selecting different paragraph tags on the left to see what pops up on the right.

  5. Select "9.2.2 Working with Microsoft Word Text" from the Paragraphs list (see Figure 5.2).

    Figure 5.2. The selected paragraph tag and source paragraph.

    This paragraph is the source information that will be displayed in the cross-reference. If you choose a different paragraph in the list, that source information will be displayed in the cross-reference. Keep in mind that, even though an autonumber format is displayed in the Paragraphs source list as well as a title, it will not necessarily be displayed in the actual cross-reference. What is displayed in the cross-reference is determined by the format structure.

  6. Select Subhead from the Format list in the Reference pane.

    The definition of Subhead is displayed directly below its name. In the section, "Creating a New Format," you defined the new Subhead format to display only the text of the source information.

  7. Click Insert.

    The cross-reference is inserted at the insertion cursor. (Figure 5.3 has the cross-reference highlighted so you can see it better.)

    Figure 5.3. The cross-reference is inserted.

Back to Basics

Type a space on either side of the cross-reference once inserted within text.

Marker Awareness

After a cross-reference is inserted into your document, a marker is also inserted at the source paragraph, whether that source paragraph is in the current document or in a different document file. You will not see this marker being inserted. This action is transparent to you. Cross-reference markers are inserted at the beginning of source paragraphs and look just like other marker types in FrameMaker.

Back to Basics

You can turn on text symbols to see if markers are in the text. Just select View > Text Symbols.

Take a quick look at a cross-reference marker so you become more familiar with it. To view the marker in the source paragraph, either manually move to that page of the document or do the following:

Back to Basics

You can find markers by using Edit > Find/Change > Marker of Type > Cross Ref.

  1. Double-click on the cross-reference.

    The Cross-Reference window appears with the source information selected in the Paragraph Tags and Paragraphs lists. Note that the Source Text page number is displayed directly above the Paragraphs list.

  2. Click on Go to Source.

    The Cross-Reference window closes and the insertion cursor immediately goes to the source paragraph cross-reference marker.

Back to Basics

You can go directly to the source information by pressing Alt-Control-clicking the cross-reference.

Be careful not to delete cross-reference markers when you edit text in documents. If cross-reference markers are deleted, the cross-reference will not be able to find its source information, and an unresolved cross-reference error message will be displayed. For more information on solving unresolved cross-references, see the section "Unresolved Cross-References" on page 150.

Adding Autonumber Formats

Now that you know how to create a cross-reference format that displays the text of the source information, you can now move on to adding autonumbers into the mix.

You probably noticed that inserting a cross-reference is easy. The real work is in the formats, which determine what is displayed in the cross-reference.

If you have several cross-references throughout documents that use a particular format, and you decide to edit that format, the display of those cross-references will update based on the new format.

Go through these steps to add an autonumber to the existing Subhead cross-reference format, which was created to show only the title in the section, "Creating a New Format" on page 122.

Back to Basics

You can double-click any cross-reference to display the Cross-Reference window.

  1. Select Special > Cross-Reference.

    The Cross-Reference window appears.

  2. Click on Edit Format.

    The Edit Cross-Reference Format window appears with the Format Definition selected.

    Be careful of fast-typing fingers! It's easy to hit a key on the keyboard and delete the current definition.

    If Subhead is not the selected format, click one time on Subhead in the Formats list box. Its name and definition appears.

  3. With the insertion cursor placed before the current definition, click one time on <$paranum> in the Building Block list.

    The Building Block <$paranum> is inserted into the Definition field (see Figure 5.4). The <$paranum> block represents the autonumber format of the selected source paragraph. This means that the paragraph's autonumbering, whose format is defined in the Paragraph Designer numbering property, will be displayed in the cross-reference at the selected position.

    Figure 5.4. The Add Autonumber format to cross-reference.

  4. Type a space between the pointing brackets of the two Building Blocks.

    A space is inserted between the Building Blocks <$paranum> and <$paratext> in the Definition field. This means that a space will be included between the autonumber and text of the cross-reference display. If you do not type a space, the autonumber and the text will run together.

  5. Click on Change. Then click on Done.

    The change you just made is incorporated into this format.

  6. The Update Cross-References window appears (see Figure 5.5).

    Figure 5.5. The Update Cross-References window.

    Select Internal Cross-References. This means that cross-references to source information located in the current document will be updated.

    If cross-references with this format have source paragraphs in other document files, and those documents are presently open in FrameMaker, select References to All Open Documents to update the cross-references to those files.

    Select References to All Documents to update all cross-references, whether their source files are open or closed.

    Click on Update to update the selected cross-references.

  7. You return to the Cross-Reference window. You do not have to click on Replace because you are not replacing the current cross-reference; you have already updated the format for all cross-references that use this format. Click on Done to finish.

Adding the Page Number and Text

By now, you should have a good idea about the relationship between cross-reference formats and the way in which cross-references are displayed.

Take your understanding a step further and add a page number and typed text to the cross-reference format. The cross-reference that has been formatted, inserted, and modified previously, is displayed as

9.2.2 Working with Microsoft Word Text

Let's add the page number to this type of cross-reference:

9.2.2 Working with Microsoft Word Text on page 2

With a quick edit to the format, all cross-references that use this format will be updated with the new one automatically. This exercise begins with the Edit Cross-Reference Format window.

Tip

Type the word "See" and a space before the entire definition to include it in the cross-reference format.

  1. Select Subhead from the Format list.

    The definition of the Subhead format appears in the Definition field.

  2. Place the insertion cursor after the <$paratext> Building Block in the Definition box. Type the words "on page". The words "on page" are inserted in the Format Definition field, so that the words "on page" will appear after the source paragraph text (the subsection title) in cross-references that use this format.

  3. Select <$pagenum> from the Building Block list.

    The Building Block <$pagenum>, which represents the page number of the source information, is inserted into the Definition field. This means that the page number of the source information will appear in the cross-reference immediately after the words "on page".

  4. Make sure to insert a space in between the word "page" and the <$pagenum> Building Block. If you don't, the word "page" runs into the page number, and the cross-reference in the text will end with "page2."

  5. Click on Change and Done.

    You are taken to the Update Cross-References window. After you're there, select the desired set of references, then click on Update. All cross-references that use this format will be updated to use the new definition.

Adding a Dash of Style

Thus far, the format of the cross-reference that was formatted, inserted, and modified in the previous examples looks like this:

9.2.2 Working with Microsoft Word Text on page 2

The design of your documents might require that part—but not all—of the cross-reference be displayed with italic, bold, or some other character format.

By now, you know that the cross-reference itself is a single unit that can only be selected as such. You cannot use ordinary methods to insert characters into a cross-reference in text, nor can you use the B or I toolbar button to apply character formatting to a part of the cross-reference. That's where Character Format Building Blocks come in.

Back to Basics

You can create new character format tags with Format > Characters > Designer.

Character Format Building Blocks use existing character format tags. Before getting started with character format building blocks, its a good idea to check the Character Catalog in your FrameMaker document to see what character format tags are available. If the character format you plan to use is not already part of the catalog, you must first create a tag for it in the catalog. If it is not available in the Character Catalog, it will not be available in the list of Cross-Reference Formats Building Blocks.

For this example, you put the autonumber and text of the referenced information (the section number and title) into italics. FrameMaker provides the character tag Emphasis for italics. The remainder of the cross-reference will be the default font of the paragraph. The cross-reference will look like this:

9.2.2 Working with Microsoft Word Text on page 2

This exercise starts at the Edit Cross-Reference Format window:

  1. Select Subhead from the Format list.

    The format name "Subhead" appears in the Name field, and its definition appears in the Definition field.

  2. Place the insertion cursor at the beginning of the definition, and select <Emphasis> from the Building Block list.

    The Building Block <Emphasis> is inserted into the Definition. As a result of inserting this Building Block, all characters to the right of the <Emphasis> Building Block will be tagged with the Emphasis character tag and, therefore, will be formatted with italic.

  3. Place the insertion cursor before the word "on" and select <Default ¶ Font> from the Building Block list.

    The Building Block <Default ¶ Font> is inserted into the Definition. As a result, all characters to the right of <Default ¶ Font> are reset to the default font of the paragraph tag. If you do not reset to the default font, all the characters in the cross-reference will be italic, because of the <Emphasis> tag added in Step 2 of this exercise.

Back to Basics

The appearance of characters in Default Paragraph Font is determined by the paragraph tag properties.

Cross-Reference to a Numbered Figure

Just for fun and to get some practice, it's time to create a cross-reference to a numbered figure in your current document. Use the same principles as you did in the section "Cross-Reference to a Subheading on page 121, except that, this time, you'll combine all the steps into one exercise.

It's likely that in documents, you will create cross-references to a variety of source information and structure them in many different ways. For this exercise, you create a cross-reference format that's structured like this:

See Figure x.x Title on page x.

First, set up the cross-reference to a numbered figure. For this example, suppose that, in this document, the paragraph tag for figure titles is FigureTitle. Perform the following steps:

  1. With the insertion cursor at the cross-reference location, select Special > Cross-Reference.

    The Cross-Reference window appears.

  2. Select Current from the Source > Document drop-down menu.

    Current is the default selection. The current document is the location of the source information for this cross-reference.

  3. Select the name of the paragraph tag used for figure titles in the current document, FigureTitle, from the Paragraph Tags list.

    FigureTitle will be selected in the list. All paragraphs tagged with FigureTitle (which should all be figure titles) will be displayed in the Paragraphs list on the right side.

  4. Select Figure 3.1 Remove the Rear Cover from the Paragraphs list.

    The paragraph "Figure 3.1 Remove the Rear Cover" is selected from the list of paragraphs (see Figure 5.6). As a result, this figure paragraph will be the source information for this cross-reference. A cross-reference marker will be inserted in the figure paragraph after the cross-reference is inserted.

    Figure 5.6. Set up a cross-reference to a figure title.

Next, create a new format in which to display cross-references for figure titles:

  1. Click on Edit Format.

    The Edit Cross-Reference Format window appears. The current format selection, Heading & Page, is displayed in the Name box, and its definition appears in the Definition field. You might see a different format name displayed in your document.

  2. Click on Heading & Page in the Name box, select the whole name, and delete it. Type "See Figure".

    "See Figure" will be the name of the new cross-reference format. As a result, it is displayed in the Reference > Format drop-down list.

  3. Click on the Definition field, select the entire definition, and delete it.

    The Definition field becomes blank.

  4. Type in the Definition field and select Building Blocks from the Building Blocks list to create a new format structure: See <Emphasis><$paranum> <$paratext> on page <$pagenum>.

    The new definition is inserted into the Definition field.

  5. Click on the Add button and then click on Done.

    The new format is added to the list of formats, and you return to the Cross-Reference window (see Figure 5.7).

    Figure 5.7. The definition of the "see Figure" format.

  6. Click on Insert.

    The cross-reference is inserted at the cursor location, and it uses the new format structure; see Figure 5.8.

    Figure 5.8. The cross-reference to a figure is inserted into the document.

Back to Basics

Use \` and \' for left and right smart quotes.

Here are a few ideas for different format structures and the corresponding definitions.

Cross-Reference Display | Format Definition
see Figure 3.1 | see <$paranum>
Figure 3.1 Remove the Rear Cover | <$paranum> <$paratext>
see Figure 3.1 on page 8 | see <$paranum> on page <$pagenum>
see Figure 3.1 , "Remove the Read Cover", on page 8 | see <$paranum>, \`<$paratext>\' on page <$pagenum>

Cross-Referencing Other Document Files

So far, you explored cross-references within the same file. What if you want to create cross-references to other files in your documents? This task requires the same procedure as cross-referencing within the current document, except for one thing: When you create cross-references to FrameMaker files other than the current file, the file containing the source information must be open in order to select it from the Document list in the Source pane of the Cross-Reference window, as shown in Figure 5.9. If the file isn't open, it doesn't show up in the document list.

Figure 5.9. Select the file from the Source Document menu.

Tip

Remember to save all open files to which you have created cross-references, or the markers will not be saved in the source file.

The file containing the source information must be open because, when you create a cross-reference to that file, it gets modified automatically by having a cross-reference marker inserted.

After you select the file from the list (see Figure 5.9), the paragraph tags from that file are displayed in the Paragraphs list.

Creative Cross-References

Now that you learned some basic principles of cross-references, let's discuss a few creative ways to work with them. In this section, I cover working with chapter and volume numbers, including using the volume number as text, as well as using cross-references to build a table of contents and understand the preceding paragraph technique.

Chapter Numbers

If you are including chapter numbers as part of the page number, you can make a slight adjustment to cross-reference formats to include this information in cross-references that display page numbers.

Previously, you learned about the <$pagenum> Building Block, which represents the page number in cross-reference formats. This does not, however, represent your document page number correctly if your document's actual page numbers look like this:

3-1, 3-2, 3-3, 3-4, and so on

In that case, a cross-reference to source information on page 2 of Chapter 3 of your document would look like this:

See Figure 3.1 , Remove the Rear Cover, on page 3-2.

Starting from the Edit Cross-Reference Format window, here's how to make the change you need in the cross-reference format:

  1. Place the insertion cursor before <$pagenum> in the Definition field.

    The cursor position specifies the location where you will insert the Building Block for the chapter number.

  2. Select <$chapnum> from the Building Blocks list. Then type a hyphen.

    The Building Block "<$chapnum>-" is inserted in the definition. The Building Block <$chapnum> represents the chapter number of the source information document. The hyphen is just one method that you can use to format the chapter number and page number together (see Figure 5.10).

    Figure 5.10. Add the chapter number to the cross-reference format.

Back to Basics

You can set chapter numbers by selecting Format > Document > Numbering > Chapter.

Volume Numbers

Back to Basics

You can set volume numbers by selecting Format > Document > Numbering > Volume.

If you are using volume numbers in documents, you might want to refer the reader to the volume number, in addition to the chapter and page number of source information. Suppose that, in Volume I, you want to refer the reader to Figure 2-3 , in Volume II, Chapter 2.

Here are a couple of examples of using volume numbers in cross-references:

Cross-Reference Display | Format Definition
See Figure 2-3 in Volume II on page 2-14. | See <$paranum> in Volume <$volnum> on page <$chapnum>-<$pagenum>
Page 2-14 of Volume II shows Figure 2-3 | Page <$chapnum>-<$pagenum> of Volume <$volnum> shows <$paranum>
Using Text as a Volume Number

The volume number function in FrameMaker provides more than just the capability to add an autonumber to documents. You can also use this special function for text, such as a book name. Keep in mind that you can do this only if you are not already using the volume number as an actual number in documents.

Note

The Chapter Number function has the same text capability.

Why do this? Imagine that you have created two books for the same software tool, but one book is for beginners and the other book is for advanced users. You decide not to use a volume number, and use book titles instead. For this example, the software tool is named "Stock Market Analyzer" and the book titles are

  • Getting Started with Stock Market Analyzer

  • Advanced Stock Market Analyzer

In the beginner book, there will be cross-references to some of the advanced topics, and the advanced book will reference some beginner topics as reminders. For this exercise, you will start with the beginner book, Getting Started with Stock Market Analyzer. These steps begin with the book file, and the first chapter file in the book is selected.

Set the volume number to text:

  1. Select Format > Document > Numbering.

    The Numbering Properties window appears. Select the Volume tab, if it has not already been selected.

  2. Select Text from the Format drop-down list.

    Text appears in the Format box.

  3. Type "Getting Started with Stock Market Analyzer" in the Volume # text field.

  4. Click on the Set button (see Figure 5.11).

    Figure 5.11. Change the volume numbers to use text.

    The volume number is set to the text "Getting Started with Stock Market Analyzer" instead of to a number. This means that, any time the volume number Building Block or variable is used, that text will be inserted rather than a number.

  5. For each subsequent file in the book, open the file and use Format > Document > Numbering and select the Volume tab. Then, select the Use Same Number As Previous File radio button (see Figure 5.12).

    Figure 5.12. You can set up book files to use previously set volume numbers.

    All files in the book will be set up to use the text you entered in the first chapter instead of a volume number.

After you finish, open the second book, Advanced Stock Market Analyzer. Follow the same steps as in the first book to set the volume number of each file to the name Advanced Stock Market Analyzer.

Now you are ready to insert a cross-reference in the beginning document, Getting Started with Stock Market Analyzer, that refers to a topic in the advanced document.

First, set up the format to display the cross-reference as

See Figure 3.1 in Advanced Stock Market Analyzer on page 3.2

  1. From the Edit Cross-Reference Format window, clear the Name field and type a new format name, DocNameFigPage.

    DocNameFigPage appears in the Name field.

  2. Clear the Definition field and use text and building blocks to insert the new definition: See <$paranum> in <Emphasis><$volnum><Default ¶ Font> on page <$chapnum>.<$pagenum> (see Figure 5.13).

    Figure 5.13. Define the cross-reference format using volume number.

    The new definition is inserted into the Definition field. The Building Block <$paranum> represents the autonumber, <$chapnum> notes the chapter number, <$pagenum> represents the page number, and <$volnum> notes the text you previously defined in the volume number text field.

  3. Click on the Add button. Then click on Done.

    The new definition is added to the Format list. You return to the Cross-Reference window.

Now that you set up the format, it's time to insert the cross-reference:

Back to Basics

Document files must be open to show up in the Document drop-down list in the Source pane of the Cross-Reference window.

  1. Select the source document (techc.fm) from the Document drop-down menu.

    The source document appears in the Document box.

  2. Select FigureTitle from the Paragraph Tags list.

    FigureTitle is the paragraph tag used for figure titles in the source document. All paragraphs tagged FigureTitle are displayed in the Paragraphs list.

  3. Select Figure 3.1 Add Stock to Portfolio from the Paragraphs list (see Figure 5.14).

    Figure 5.14. You can set up a cross-reference to figures in other documents.

    The text "Figure 3.1 Add Stock to Portfolio" is selected in the list. This is the source information that is displayed in the cross-reference.

  4. Click on the Insert button.

    The cross-reference is inserted into the document and displays as

    See Figure 3.1 in Advanced Stock Market Analyzer on page 3.2

Note

See page 148 for more information on updating cross-references in documents.

If you decide to change the name of the advanced book, just change the name in the first file of the book and update the book file by opening the book file with File > Open and then selecting Edit > Update Book. All the subsequent files in the book will be updated based on the new name, because their volume numbers are set to Use Same Number as Previous File. Then open the book that contains the cross-references to the advanced book file, and update that book with Edit > Update Book. (The advanced book does not have to be open.) Each occurrence of the book name will change accordingly throughout each document file.

Using the Preceding-Paragraph Technique

Up to this point, you've been inserting cross-references that are directly linked to specific paragraphs as source information. In other words, each Building Block used in the definition represented some portion of the specific source information that you were linking to.

FrameMaker, however, provides a powerful, and often underrated, cross-reference tool that enables you to include information from a paragraph preceding the source paragraph in a cross-reference. Suppose you want to insert a cross-reference to Table 2.1 in your document, and you want readers to know that the table is within Section 2.4 (whose title happens to be "Solution for Correcting Junction Board"), regardless of where in Section 2.4 Table 2.1 actually resides. You want one cross-reference that reads

See Table 2.1 (in Section 2.4, Solution for Correcting Junction Board).

The preceding-paragraph technique enables you to insert the cross-reference, selecting just the table title as the source information. You will have to know the paragraph tag that is used for section headings. In this case, the paragraph tag is H1. You can set up the format to look for the last occurrence of an H1-tagged paragraph preceding the source information. It doesn't make a difference as to whether the last paragraph tagged H1 was 10 pages before or on the same page.

Starting with the Edit Cross-Reference Format window, do the following:

  1. Clear the Name field and type the new format name, Table and Section. "Table and Section" is the format name that is displayed in both the Formats list in the Edit Cross-Reference Format window and the Reference Formats drop-down list in the Reference pane of the Cross-Reference window.

  2. In the Definition field, type "See" followed by a space. Select <$paranum> from the Building Blocks list. Then type a space followed by "(in" with another space. Here, as has been the case until now, the Building Block <$paranum> represents the autonumber of the table title.

  3. Select <$paranum[paratag]> and <$paratext[paratag]> from the Building Blocks list. Put a comma and a space between these Building Blocks, and put the ). characters after the last block.

    The Building Blocks "<$paranum[paratag]>" and "<$paratext[paratag]>" are inserted into the Definition field. These blocks represent the autonumber and the text of the most-recent paragraph with the intended tag that precedes the source information. In these blocks, "paratag" is a placeholder for the paragraph tag that you want to reference, which contains the desired section number and title.

  4. Replace "paratag" with H1 in the two Building Blocks <$paranum[paratag]> and <$paratext[paratag]> (see Figure 5.15).

    Figure 5.15. You can set up a cross-reference format for preceding paragraphs.

    The definition should now read

    See <$paranum> (in <$paranum[H1]>, <$paratext[H1]>).

    As a result, the autonumber of the source information is displayed, followed by the autonumber and text of the last occurrence, before the source information, of a paragraph tagged H1.

  5. Click on the Add button. Then click on Done.

    Your new cross-reference format, "Table and Section," is added to the Format list. You return to the Cross-Reference window.

  6. After you return to the Cross-Reference window, set up the cross-reference to the desired table in the source document. Then click on Insert to insert the cross-reference.

Building a Cross-Reference Table of Contents

Say that you want to include a short table of contents at the start of each chapter in a book. Cross-references provide an excellent way to create this table. Figure 5.16 shows an example:

Figure 5.16. A sample cross-referenced table of contents.

You could also generate the table of contents for the book and copy/paste each subset into their appropriate chapters each time you update the files. It's up to you. Try out this method. You might find it to be a real timesaver in the long run.

Note

See Chapter 8 for more information on generating a table of contents for a book.

First, set up the cross-reference format. This exercise starts at the Edit Cross-Reference Format window:

  1. Clear the Name field and type the new format name TOC.

    The new name, TOC, is displayed in the Name field and in the Reference Format drop-down list in the Cross-Reference window.

  2. Type and select Building Blocks to insert <$paranum> <$paratext> \t <$pagenum> in the Definition field.

    The Building Block <$paranum> represents the autonumber of the source information, <$paratext> represents the text, \t (which you have to type) represents a tab, and <$pagenum> represents the page number.

  3. Click on Add and then Done.

    The new TOC format is added to the Formats list (see Figure 5.17). You are returned to the Cross-Reference window.

    Figure 5.17. The TOC cross-reference format definition.

Next, set up and insert the cross-references that will be part of your table of contents. Press Enter after each cross-reference is inserted. This action places each subsequent cross-reference on a new paragraph line.

Back to Basics

You can use Format > Paragraphs > Designer to create new tags.

After you finish, set up a new paragraph tag that includes one tab stop, right-aligned where you want to show the page number (see Figure 5.18). Apply the new tag to each line of the cross-reference table of contents.

Figure 5.18. The TOC cross-reference paragraph tag.

Cross-References and Conditional Text

If you use both conditional text and cross-references in your documents, this is a worthwhile section for you.

Suppose that you insert a cross-reference to a certain piece of source information, and suppose you also apply a condition tag to that same piece of information. Then suppose you hide that condition tag. You run into that annoying problem of unresolved cross-references. Why does this happen?

Note

See Chapter 10 for more information on using, tagging, showing, and hiding conditional text.

When text is hidden, FrameMaker treats it as if it were deleted. For example, if hidden text is part of a numbered list, the list renumbers automatically as if the hidden text were deleted. Likewise, if hidden text is part of a running header or footer variable, it will not show up in the header or footer because it is not currently in view. In the same way, a cross-reference will not be able to find its source after the source is hidden.

This issue can get very complicated if you use many condition tags and refer to source information in various files. If you come up with unresolved cross-references because of hidden text, you can always turn those problem conditions back on; but, you might defeat your original purpose of using conditional text: to show different versions of a document without confusing them. If you turn the conditions back on, you will not have one version only in view.

What is the solution? Here's one useful approach: For every cross-reference that uses hidden or conditional text as its source, tag the cross-reference too with the same condition. Then, when that condition tag is hidden, the cross-reference is hidden as well, and you can avoid the problem altogether.

Cross-Referencing in Book Files

Cross-references in files that are part of a book behave the same way as cross-references in files that are not part of a book.

As far as cross-references are concerned, the main advantage to working with book files is the way unresolved cross-references are handled. The good news is that FrameMaker generates an organized list of unresolved cross-references in book files, with clickable items that take you to the cross-reference with the problem. Each document that contains unresolved cross-references is listed, and that document name is followed by an indented list of the documents that are supposed to contain the unresolved source information (see Figure 5.19).

Figure 5.19. A list of unresolved cross-references in book files.

After you have a list of problem cross-references, see the section "Unresolved Cross-References" on page 150 to learn how to solve them.

Cross-References and PDF or View Only Files

Documents produced in FrameMaker are commonly exported as HTML, PDF, or FrameMaker View Only files so that users can read them and print them (but not edit them) without having FrameMaker installed on their systems. When exporting to these file types, FrameMaker can preserve cross-references as hypertext links that work in the programs the users will use to view the documents. This section deals specifically with PDF andView Only documents and how they work with cross-references as hypertext links.

View Only Documents

Back to Basics

To make View Only press Esc Flk or select File > Save As > View Only.

FrameMaker View Only files enable others to read and print (but not edit) documents created in FrameMaker. Users who do not have FrameMaker can use FrameViewer, which is available from Adobe.

If you plan to create View Only documents, you get an added bonus with cross-references. When cross-references are part of a FrameMaker document that you convert to a View Only file, they are automatically converted to hypertext links.

Here's how to use cross-references in a View Only file:

Back to Basics

To test a cross-reference in a file without locking the file, Control-Alt-click on the cross-reference.

  1. In a View Only file, place the insertion cursor over a cross-reference text area.

    The insertion cursor changes to a hand with a pointing finger (see Figure 5.20).

    Figure 5.20. In View Only files, the cursor changes to a hand when it hovers over a text area.

  2. Click one time over the cross-reference text area.

    The area becomes highlighted and FrameMaker jumps to the source information, whether it's in the current file or in a different file.

Note

When in the same location, cross-references take priority over hypertext commands

That's all there is to it!

PDF Documents

Portable Document Format, or PDF, is a common document distribution format that enables users with Adobe Acrobat or Acrobat Reader to view documents. Although PDF documents are not discussed in detail in this book, I do discuss how cross-references work in them.

Tip

Do not use the PDFWriter driver to create PDF documents. Instant hypertext links will not be activated using PDFWriter.

Just as with View Only documents, cross-references become instant hypertext links when FrameMaker documents are saved as PDF documents. These hypertext links make it easy for readers of your PDF documents to navigate.

Here's how to use cross-references in a PDF file:

  1. In a PDF file, place the insertion cursor over a cross-reference text area. The insertion cursor change to a hand with a pointing finger (see Figure 5.21). Click one time.

    Figure 5.21. The insertion cursor changes to a hand in PDF files when it hovers over a text area.

    Acrobat jumps to and displays the source information, whether it is in the current file or in a different file.

Tip

Keep the same file path when creating PDF files.

Keep the following information in mind when you create a PDF file: To preserve FrameMaker cross-references as Acrobat hypertext areas, you must create the PDF file by selecting File > Save As and file type PDF. If you create the PDF file by printing to PDFWriter, the cross-references are converted to text, and they do not link to their sources.

If sources of cross-references are other documents, those documents must also be in PDF format in order for the hypertext links to work. If they are not, you will get a message similar to Figure 5.22.

Figure 5.22. The error message that's displayed when the source file was not converted to PDF.

Updating Cross-References

Cross-references are automatically updated each time a document containing cross-references is opened. You can also force cross-references in documents to be updated at any time while working in FrameMaker document files. You can also suppress the automatic update when the file is opened. This section discusses how to force and suppress the updating of cross-references.

Forcing an Update

If you massively edited a document, cross-references will not automatically update themselves. You need to run the Update References operation that FrameMaker provides. If you don't update cross-references, they simply display the most-recently updated source information. However, you don't have to perform the update after every change; you can update all the cross-references at once when you are ready.

To update cross-references at any time, follow these steps:

  1. Select Edit > Update References.

    The Update References window appears.

  2. Click on the All Cross-References check box. Click Update.

    All cross-references in this document will be updated, whether the source information is located in the current document or in another document file.

If unresolved cross-references are in the document file, you will get an unresolved cross-reference error message. For more information on solving this tricky problem, skip to the section "Unresolved Cross-References" on page 150.

Suppressing Automatic Updates

Automatic updating of cross-references, each time a document is opened, is a valuable feature, but it can be time-consuming when that document contains many cross-references.

If your documents have only a few cross-references sprinkled about, you don't have to worry about this time factor. These will update quickly. If, on the other hand, you have a massive collection of cross-references in a document, opening the file can take some time, especially when the source information is in other documents.

How much time does the automatic update take? That depends on how many cross-references are in your document, how fast your computer is, and whether the source information is in the current file or another file. Each case is different.

All such delay problems can be solved with one quick FrameMaker command: Suppress Automatic Updating. With this feature, cross-references will not be updated automatically every time a file containing them is opened.

Here's how to do suppress the automatic updating of cross-references:

  1. Select Edit > Update References.

    The Update References window appears. This window is used for both the Suppression command and manual updating of cross-references.

  2. Click on the Commands button and select Suppress Automatic Updating.

    The Suppress Automatic Updating window appears.

  3. Click on the Suppress Automatic Updating of All Cross-References check box. Click on the Set button.

    This means that cross-references with both internal and external source information will not be updated while the document is opened.

Note

Internal cross-references and cross-references to open documents will continue to be automatically updated when a document is printed.

Unresolved Cross-References

If you have never come across the Fix Unresolved Cross-References window, consider yourself lucky. If you have, you know that trying to resolve these cross-references that have come undone for one reason or another can be a challenge.

This section explores the "why"s and investigates the ways to solve unresolved cross-references, as well as how to locate individual occurrences in document files.

There are a few reasons why cross-references come undone:

  • A cross-reference marker was deleted from the source information.

  • The source information is part of conditional text that is hidden.

  • The name of the source file has changed.

  • The location (path) of the source file has changed.

The Update Unresolved Cross-References Window

When you open a file with cross-references or update references some other way, and unresolved cross-references occur, you see the Update Unresolved Cross-References window. This is not an intuitive window, but it does serve a useful purpose: to show you which files contain source information that is no longer recognized by the current document's cross-references (for one reason or another). This window also points out how many total unresolved cross-references are contained in the current document, and how many of those are referenced in each of the individual source files.

You can resolve some, but not all, unresolved cross-references right from this window. If unresolved cross-references are caused by deleted cross-reference markers, you will not be able to use this window to resolve them. See the section "Finding Unresolved Cross-References and Their Sources" on page 155 for more information.

With that said, take a closer look at the Update Unresolved Cross-References window, shown in Figure 5.23, and see how it can work for you.

Figure 5.23. The Update Unresolved Cross-Reference window.

Back to Basics

If a file is closed and has unavailable fonts, open the file before you use the Update Unresolved Cross-References window.

Here is an example in which unresolved cross-references were introduced into a file in the following manner:

  • A directory called tech101 contained three files: techa.fm, techb.fm, and techc.fm.

  • The file techc.fm contained two cross-references: one to techb.fm and one to techa.fm. These cross-references worked fine.

  • The files were then saved and closed.

  • The name of techb.fm was changed to techbulb.fm.

  • The file techc.fm was moved outside the tech101 directory.

Here is how to use the Update Unresolved Cross-References window to fix the cross-reference problems that appear when techc.fm is reopened:

  1. Open a file (techc.fm, in this example) that contains unresolved cross-references (or use Edit > Update References).

    The Update Unresolved Cross-References window appears, as shown in Figure 5.23. The top portion of the window provides information about how many total unresolved cross-references are located in the file just opened; in this case, there are two total. Current is selected in the Files Named list. Look below the list to see there are no unresolved cross-references in the Current file. That is, none of the unresolved cross-references has a source within the current file.

  2. Click once on the second file in the list, techa.fm.

    There is one unresolved cross-reference to source file techa.fm, as displayed beneath the Files Named list (see Figure 5.24).

    Figure 5.24. The unresolved cross-reference information, per file

  3. Click once on the third file in the list, techb.fm.

    There is one unresolved cross-reference to source file techb.fm, as displayed beneath the Files Named list (see Figure 5.24).

Now that you determined which files contain the unresolved cross-reference source information, it's time to solve each one:

  1. Click on techa.fm in the Files Named list.

    This is the first file for which you will resolve cross-references. Why is the cross-reference to this file unresolved? Recall that both the current file (techc.fm) and techa.fm were in the tech101 directory when the cross-references were created. Now techc.fm has been moved outside the tech101 directory whereas techa.fm has not, so the cross-references in techc.fm can no longer find techa.fm.

  2. Using the file display in the bottom part (For Cross-References to Selected File, Look In:) of the Update Unresolved Cross-References window, navigate to the correct directory, tech101, and click once on the correct file, techa.fm (see Figure 5.25).

    Figure 5.25. The cross-references to file techa.fm are resolved.

  3. After you finish, click on the Open button. As a result, the Current file will now find its cross-references to this source document using the new path.

  4. Click on techb.fm in the Files Named list.

    This is the next file for which you will resolve cross-references. Recall that not only was the current file, techc.fm, moved outside the directory that contained the source file techb.fm; techb.fm itself was renamed to techbulb.fm. So the current file cannot find its cross-reference source.

  5. Navigate to the correct directory, tech101, and click once on the new correct filename, techbulb.fm (see Figure 5.26).

    Figure 5.26. You can resolve the cross-references to file techb.fm by clicking on the correct filename.

    After you finish, click on the Open button.

    The Current file will now find its cross-references to this source document by using the new path and the new filename.

As you can see, fixing unresolved cross-references for files that have changed locations, names, or both, is an easy task. After the previous steps for unresolved cross-references are completed, the Update Unresolved Cross-References window will look like the one shown in Figure 5.27. Notice that there are now no unresolved cross-references in the Current open file.

Figure 5.27. The result of resolving all the unresolved cross-references.

Finding Unresolved Cross-References and Their Sources

If you have used the Update Unresolved Cross-References window and have not been able to get the cross-references resolved with the standard methods described in the previous example, you might need to take more serious measures.

For example, if a cross-reference marker was deleted in one of the files, you will not be able to use the Update Unresolved Cross-References window to correct the resulting unresolved cross-references. In this case, you have to find individual occurrences of unresolved cross-references to see exactly what the problem is with both the cross-reference and its source information.

You can combine these two methods to locate specific unresolved cross-references and their sources in files.

First, generate a list of unresolved source information:

  1. Select Special > List Of > References.

    If you are working in an individual file rather than a book file, you first see a message window containing the question, "Do you want to create a standalone List of References for this file?" Click on the Yes button.

    The Set Up List of References window appears.

  2. Select Unresolved Cross-Refs from the Don't Include list and move to the Include References list.

    Unresolved Cross-Refs will be displayed in the Include References list.

  3. Click on the Set button.

    A list will be created in a separate List of References file, which will then be opened. This file is a FrameMaker file whose name is the same as that of your document plus suffix (LOR, by default). For example, the List of References for the techc.fm file discussed in the section, "The Update Unresolved Cross-References Window" on page 150 would be techcLOR.fm. For each unresolved cross-reference, the list will contain the filename, paragraph tag, source content, and page number (see Figure 5.28). This information makes it easier to locate the unresolved source information.

    Figure 5.28. The List of References (LOR).

Back to Basics

Double-click on Unresolved Cross-Refs to move that item to the Include References list. Or you can click one time and then click on the left arrow.

Second, you can use Find/Change to find the cross-references in the current file that lost the connection to the source information:

  1. Select Edit > Find/Change.

    The Find/Change window appears.

  2. Select Unresolved Cross-Reference from the Find drop-down menu. Click on Find.

    The first unresolved cross-reference is displayed in the Find text field and the cross-reference is selected (see Figure 5.29). Notice that the information displayed in the Find text field matches the information in the List of References, which was previously generated.

    Figure 5.29. You can find and change unresolved cross-references.

  3. Look in the List of References for each found unresolved cross-reference.

    Notice the first found cross-reference, H1:2.2 Revision B, is the first item in the LOR. The LOR provides the name of the source file (techb.fm) and page number information as well.

  4. Double-click the found unresolved cross-reference.

    The Cross-Reference window appears. Notice that the source type is Marker. The two lists in the Source pane are Marker Types and Cross-Reference Markers. Marker type is the default selection when you double-click on cross-references with lost connections to source information.

  5. Click on the Source Type button and select Paragraphs from the pop-up menu.

    Paragraphs are selected as the source type. All paragraph tags in the selected document file are displayed in the Paragraph Tags list.

  6. Select H1 from the Paragraph Tags list.

    Select H1 because H1 is the paragraph tag from the LOR that matches the unresolved cross-reference. All paragraphs tagged with H1 are displayed in the Paragraphs list on the right side.

  7. In the Paragraphs list, look for a paragraph that matches the source information in the LOR or otherwise appears to be the missing source.

    It turns out that there is a paragraph tagged H1 that begins "2.2 Revision B." This text matches the source shown in the LOR. Select that paragraph (as shown in Figure 5.30).

    Figure 5.30. Reconnect the lost cross-reference to its source.

Back to Basics

Select the correct format for this cross-reference from the Reference > Format drop-down list.

  8. Click on the Replace button.

    The unresolved cross-reference is replaced with the new cross-reference.

The foregoing example was easy to resolve, because there was a paragraph that matched the desired source information exactly. You may often need to do more detective work than was needed here to locate the material that should be the source.

Even when the exact source information is found, an unresolved cross-reference can often be a symptom of an underlying problem in the organization of your document. You should spend some thought on deciding what to do to solve the underlying problem so as to achieve the highest possible document quality.

If the source information is present, why is a cross-reference unresolved? Check to see whether the paragraph is conditional text that was hidden when FrameMaker attempted to update its references and is now shown again. You can find cross-references that have become unresolved because of hidden conditional text by the following procedure:

  1. Search for unresolved cross-references first without turning conditional text back on, and resolve the references you can resolve.

  2. Turn all conditional text back on.

    Search for unresolved cross-references again. If a source paragraph is found now that was not found at Step 1, it was lost by hiding the conditional text. To solve the underlying problem, set the same conditional tag on the cross-reference too, as described in "Cross-References and Conditional Text" on page 145.

Back to Basics

To turn all conditional text back on, select Special > Conditional Text. On the Conditional Text window, click on Show/Hide. On the Show/Hide Conditional Text window that appears, select Show All and click on Set.

Summary

Cross-references are not such a mystery once you understand what goes on behind the scenes. In this chapter, you learned a few techniques for creating cross-references as well as some creative ways in which to use them in professional documents. You also learned how to cope with the dreaded Unresolved Cross-Reference window.

After you set up cross-references, have some fun with defining and trying out various formats. If a format doesn't work out, just try a new one.


Chapter 6

Chapter 6. Table Survival Guide

  • Charting a Clear Course
  • Basic Table Elements
  • Working with the Table Designer
  • Working with Table Anchors
  • Table Catalog and Paragraph Tags
  • Changing Table Styles
  • Using Table Continuation or Table Sheet
  • Troubleshooting Heading and Footing Rows
  • Tables and Text
  • Table Row Controls
  • Tables for Figure and Caption Placement
  • Tables as a Solution for Caution Notes
  • Using Tables for Section Titles on Left and Right Pages
  • Summary

You've probably found many uses for tables in your real-world documents. As with other document elements, you've probably discovered that consistent-looking, nicely formatted tables work better than plain vanilla, ordinary ones. FrameMaker's powerful table tools offer a variety of ways to manipulate and format tables.

You can take your tables from ordinary to extraordinary by specifying a few table properties including width, height, size, number of cells, spacing, borders, and shading. You don't have to reinvent the wheel each time you want to use a particular table format—the ability to take advantage of previous work using the Table Catalog is just one of FrameMaker's many time savers.

This chapter covers a few topics that go beyond the basics of tables in FrameMaker. You've probably had a close encounter with some of these troublesome table tasks, which didn't quite fit with what you originally envisioned the task to be.

Although this chapter is not an introduction to tables, it does begin with a review of some basic table elements. Afterward, you'll delve into a wide range of table techniques and the challenges they typically present in everyday tasks. I'll discuss, in no particular order, header rows, titles, custom ruling and shading, figures in tables, and conversion between table and text.

Charting a Clear Course

It's important to take the time to understand a few basics and the way in which a variety of functions work together in FrameMaker to achieve one goal. For example, if you are working with a table, you are not just working with a table. You are also working with paragraph tags, anchored frames, variables, or autonumber formats. When things go wrong, it might not be just a faulty table that's the problem, but a combination of many not-otherwise-related elements.

Basic Table Elements

In general, tables are composed of cells set in columns and rows to form a rectangular shape. FrameMaker tables are a bit more involved. Let's review the basic table elements and how they work before moving on to more complicated matters.

FrameMaker tables are comprised of the following:

  • Anchor

  • Title

  • Table continuation and table sheet variables

  • Heading row

  • Body cells

  • Footing row

Although you have the option of using all or some of the parts that make up a table, one thing is certain: You will always have an anchor and at least one cell. Without these two elements, a table does not exist.

Figure 6.1 shows a basic table with all the elements that you'll be revisiting.

Figure 6.1. The basic elements of a table.

Anchors

Anchors are a fundamental and mandatory element of both tables and anchored frames in FrameMaker. Here's how anchors work in tables: When you insert a table in a document, it is anchored, or fixed, at the insertion location, usually at the end of the paragraph that precedes it. When you add or delete text from the document, the table automatically moves with the text to which it is anchored.

You'll notice that, when you select an anchor, the element to which it's anchored is also selected. For example, if you select a table anchor, the entire table is selected.

You can also anchor the table to an empty paragraph line. Text does not have to exist in the paragraph in order for the anchoring to work.

Back to Basics

Keep Text Symbols turned on so you can easily recognize anchors and other symbols in documents. To turn on Text Symbols, select View > Text Symbols.

Table Titles

Table titles are optional. FrameMaker does not require you to use a table title, but it's useful for identification purposes, and indispensable for the reader if there will be references to the table elsewhere in the document. You can insert a table title at the top or bottom of a table—it's up to you. The Table Designer enables you to include a title or not, as well as specify the spacing between the table title and the first row of the table.

Back to Basics

You can select Table > Table Designer for table options.

When tables span multiple pages, the title is displayed on each page of the table. You cannot edit the title text on subsequent pages—you can only edit the first page of the table.

Table Continuation and Table Sheet in Titles

FrameMaker provides two variables for you to use in tables: Table Continuation and Table Sheet. If any table in your document spans more than a single page, at least one of these variables might be for you.

Table Continuation

Back to Basics

You can select > Special > Variable > Table Continuation or Table Sheet to access table title variables.

Insert the Table Continuation variable in the Table Title area. As a result, on subsequent pages of the table, the Table Title area reads "Continued" after the table title. This variable does not reveal itself on the first page of the table and is displayed as a non-breaking space text symbol in that location. The Table Continuation variable is configurable, which means that you can change it to read "(Cont'd.)" or something else. You can also add character formatting. This variable is particularly useful for tables that do not exceed two pages in length.

Table Sheet

Insert the Table Sheet variable in the Table Title area. As a result, on the first and subsequent pages of the table, the table title area reads "(Sheet 1 of 2)", "(Sheet 2 of 2)", and so on. If the table is just one page, this variable does not reveal itself and is displayed as a non-breaking space text symbol instead. Use the Table Sheet variable for lengthy tables that span many pages so that your readers always know where they are in the table. If a reader wants to skip over the rest of the table, one "(Sheet 2 of 15)" is more helpful than 14 pages of "(Continued)."

Heading Rows

A heading row, the row of column titles that appears at the top of a table, is a marvelous thing. You usually apply a bold style or other text formatting to the text in a heading row to distinguish it from the text in the rest of the table. If the table extends beyond a single page, the heading rows are repeated on each page. You can edit the text in a heading row on the first page only. When you use Table > Insert Table, you can specify the number of heading rows, although you can add a heading at any time.

Body Rows

Body rows contain the main content of your table. They appear below the heading rows and above the footing rows (if you include them in your table).

Tip

You can add body rows by placing the cursor in a body cell, and pressing Ctrl+Enter.

Footing Rows

Footing row cells appear at the bottom of each table column. Similar to heading rows, footing rows repeat on subsequent pages of a multipage table, but you cannot edit them on subsequent pages—you can only edit the first page of the table. You can specify footing rows in the table configuration by using Table > Insert Table, although you can add them at any time.

Back to Basics

You can add footing rows by using Table > Add Rows or Columns > Add Rows > To Footing.

Working with the Table Designer

The purpose of the Table Designer is to define certain properties of tables and store these properties in a catalog. You can then access the table formats stored in this Table Catalog at any time. You can also make changes to an existing format stored in the Table Catalog to update the look of any tables that have previously been formatted with that style. Some distinct characteristics of Table properties are described in the following sections.

Properties That You Can Define in the Table Designer

Table Designer properties that can be defined are broken down into three categories. Each property has its own page in the Table Designer window:

  • Basic Properties. Use these properties to control alignment and spacing within cells and of tables themselves, define table title position and numbering direction within cells and table start positions.

  • Ruling Properties. Use these properties to control both borders around the outside of a table and lines between the rows and columns within a table.

  • Shading Properties. Use these properties to control the shading of all the rows and columns within a table.

Transparent Properties

You cannot define other properties in the Table Designer itself, yet they are part of the table format. Think of these properties as those that are transparent to the user, yet present in the Table Catalog formats. Specifically, they are formats that FrameMaker remembers from the table you originally used to create a table format. It's a good idea to keep these formats in mind when you create new and update existing table formats:

  • Table Title paragraph tag. The table format remembers the paragraph tag that was used in the title of a table when a format is created from the table. Whenever that particular table format is used to insert a table in a document, the table title is automatically formatted with whatever paragraph tag was present in the table when that table format was created.

  • Body Row paragraph tags. The table format remembers the paragraph tag that the first body row cells of the table had when you created the format. The next time you insert a table of this same format, all the body row cells automatically format with the paragraph tag that you used in the first body row cells when you originally created the table format.

  • Table and column width. The table format remembers the width of the table columns from the format you originally created. For example, if the first column was .5 inches and the other columns were 1 inch, the next time you insert this table format, the columns are exactly this size. The table width also remains the same if you use the same number of columns as when you originally created the table format.

Note

After you insert a new table, apply any paragraph tag you want to the table cell text.

As you can see, these properties are not obvious parts of the Table Designer, yet they are a big part of Table properties after they are created. Although you can change any of these properties after the table is inserted, you must be aware of these "transparent" properties to save you time later. In other words, creating table formats with the correct paragraph tag in the table title, or the correct column widths, saves you from adjusting these elements individually later.

Features That Cannot Be Part of a Table Format

Now that you've seen what properties can be part of table formats, it's time to look at other features that are never part of the table format, although I wish they could be!

  • Straddled cells. Cells in tables are often combined horizontally or vertically, or spanned, into a single cell, especially in complicated heading rows. These "straddled" cells cannot be part of a table format, but there is a good solution if you plan to use them throughout a document. Create the table format as close to the final table as possible, except for the straddled cells. Then straddle the cells as required by your document design. Finally, store the table, straddled cells and all, on a reference page. Use the reference page as a library from which to copy the table each time you want to use that particularly complicated format.

  • Table Continuation or Table Sheet. These special table variables must be inserted in the table title each time a new table is inserted into your documents. They cannot be part of the Table properties.

  • Graphics in tables. You've seen how certain paragraph tags are remembered in table formats. You might be wondering about graphics as well. Unfortunately, graphics cannot be remembered in table formats. You must import graphics into tables. For another method to include a graphic in tables automatically, see the section "Tables as a Solution for Caution Notes" on page 190.

Working with Table Anchors

As you saw earlier in the section "Basic Table Elements" on page 160, tables are always anchored to text. Table anchors are straightforward, but you might experience a couple of difficulties. First, I discuss how to get an accurate List of Tables when tables start at the top of pages; next, I review a commonly encountered pitfall with inserting text below a table.

Forcing a Table to Start at the Top of the Page

If you are using the first released version of FrameMaker 6.0, you might have struggled with tables that you have set to start at the top of the page from the Table Designer. Here's the symptom: If a page has two tables, one of which starts at the top of the page from the Table Designer, and you generate a List of Tables, the table at the top of the page is listed second in the List of Tables.

A good way around this is to anchor the table to an empty paragraph line that is set to start at the top of the page instead. You get the same result by a different method and avoid this annoying problem.

If you use this method, you might notice that the table is not exactly at the top of the page. That's because the empty paragraph takes up a whole line height. To solve that part, set the empty paragraph font size to 1 pt and the table space above to a negative number. That forces the table to the top of the page. When you generate the List of Tables, the tables appear in the correct order.

Inserting Text Below a Table

Have you ever inserted a table anchored to the end of a paragraph and then could not get the next paragraph to start under, or just past, the table? This annoyance happens because the table anchor is very close to the end-of-paragraph symbol. If you just place the insertion cursor at that location, the chances of getting it right between the anchor and the paragraph symbol are slim. So, when you hit the Enter key, the table keeps moving down.

Be patient and use the left and right arrow keys to get the insertion cursor in the correct place, which is right after the anchor and before the paragraph symbol. Then press the Enter key. As a result, a new paragraph line is ready for text input just below the table.

Table Catalog and Paragraph Tags

Tip

If you set the Title Position to No Title after you include text in the table title, that text is deleted.

Text in the Table Title area is similar to any other text in your document. You can apply any paragraph tag that you want to table title text. It's a good idea to apply a paragraph tag that has been set up for a table title.

You might have noticed, upon inserting a table with a title, that the title already has a paragraph tag applied. Often, this is a paragraph tag with an autonumber format that looks like Figure 6.2.

Figure 6.2. The Table Title paragraph tag is automatically inserted.

If this is not the paragraph tag that you want to have inserted automatically in the Table Title area each time you use this table format, here's a quick fix:

  1. Click in the Table Title area and apply a paragraph tag that you prefer in the Table Title area.

    The table title is formatted with the new paragraph tag, whether or not text is in the Table Title area. Consider typing some text in the table title so you can see how the formatted text looks.

  2. Click one time anywhere in the table.

    The insertion cursor is placed in either the Table Title area or a table cell. In order to use table commands, the insertion cursor must be placed in the table. If the insertion cursor is not in the table, you can still access some table menu items, such as Table Designer, but an error message is displayed if you attempt to make changes.

  3. Select Table > Table Designer.

    The Table Designer appears. The current table tag (for example, Format B) is displayed in the Table Tag name field.

  4. Click on Update All.

    The Table Designer properties for the table tag Format B updates. The Table Designer remembers the paragraph tag that you applied to the table title and makes it the default title paragraph tag for any tables that you create in the future using this format. (You cannot choose this option specifically in the Table Designer window.)

If other tables in your document are tagged with Format B, and they have the incorrect table title paragraph tag, updating the Table Designer doesn't change the paragraph tag of those already tagged tables. This method applies only to the current selection and future tables of this same format.

Changing Table Styles

After you determine the styles or formats of tables in your real-world documents, you can use these again, because they are stored and easily accessed from the Table Catalog. After tables have a particular table format assigned to them, you might decide to change the look of one or more tables in your documents.

Two typical tasks come to mind with regard to changing table styles:

  • Assigning a new table format to one or more tables that already have a particular table format assigned

  • Changing the look of a particular table format and updating all tables currently tagged with that format

This section explores changing the look of tables in documents. You learn the how-to's and what to do when tables just won't behave the way you expect.

Changing the Style of an Existing Table

With the Table Designer, you have the ability to change the current format of any table in a document. For example, suppose that you have a table assigned Format A and, therefore, takes on the look of Format A's Table properties. Assuming that you want to change the existing table to take on the properties of Format B, and Format B exists in the document, click anywhere in the table. Next, select Table > Table Designer. Chose Format B from the Table Tag list and click Apply To.

The selected table is now assigned Table Tag Format B. You do not have to select the entire table to assign the new table tag. If you have problems getting the table to take on the characteristics of the Table Tags properties, see the section "Tables That Won't Accept the Ruling or Shading Format Changes" on page 170.

Changing an Existing Table Style

Each table tag in the Table Catalog comprises several Table properties categorized by Basic, Ruling, and Shading. Within each of these categories, you can change several characteristics at any time. After any characteristic within a category is changed, you have the option of applying that change either to only the current table in which you are working, or to all the tables that are assigned the same table style tag.

For this example, suppose that your document contains several tables tagged either Format A or Format B. Format A table tag's Ruling properties produce the results shown in Figure 6.3: a line at the top of the header row, a double line between the header row and the first body row, a line under the bottom row, but no outside ruling line on the left and right sides of the table and no lines between columns or rows.

Figure 6.3. An example of table rules.

Now suppose that you want to add left and right outside lines and lines between columns to all the tables currently tagged Format A. Use the following steps to make a ruling style change and apply it to all the tables that are currently tagged Format A:

Tip

Windows users: You can right-click the mouse button to access the pop-up table menu.

  1. Click one time anywhere within a table already tagged with table tag Format A.

    The insertion cursor is inserted in the table. In order to use the Table menu, you must first click inside a table. If you do not, you can still access the Table Designer, but you cannot make any changes.

  2. Select Table > Table Designer.

    The Table Designer appears. Format A is displayed in the Table Tag field.

  3. Click on the Ruling tab or select Ruling from the Properties drop-down menu.

    The Ruling properties for Format A appear.

  4. Change the Ruling properties, as shown in Figure 6.4.

    Figure 6.4. The Table Designer Ruling properties.

    The new Ruling properties appear in the Ruling properties window. You have not updated any tables yet.

  5. Click on the Update All button.

    All tables that currently are assigned Table Tag Format A are updated to display the new ruling style.

Back to Basics

To change the selected table only and not store this change in the Table Catalog, click on Apply To Selection.

Tables That Won't Accept the Ruling or Shading Format Changes

In the example, all the tables assigned with Table Tag Format A are changed based on the new style change. However, you might run across a table or two that do not take on this new Ruling property change, even though it is tagged with Table Format A. If this has ever driven you crazy, you'll be pleased to know that a simple solution exists for these misbehaving tables.

Before I address the solutions, however, take a look at the reasons why a table might misbehave in the first place. First, if you import tables from other applications, such as Microsoft Word, into FrameMaker, even though you apply the correct table tag, the table might not take on the format or style of that table tag.

Second, if you inherit a FrameMaker document project from another person, someone might have used Custom Ruling & Shading on any or all parts of the tables in your documents. If this is the case, these tables will not reflect all the table format properties as you defined them in the Table Designer.

Take a deeper look inside this common problem and find out how to fix it.

Identifying the Problem

First, determine if a problem exists with a particular table's format:

Back to Basics

You can press Ctrl+ triple-click to select entire table.

  1. Select the entire table.

    The table is selected. Do not select the anchor for this method. Selecting the anchor selects the entire table, but FrameMaker doesn't recognize the separate table elements as selected.

  2. Select Table > Custom Ruling & Shading.

    The Custom Ruling & Shading window appears.

  3. Click on Show Current Settings.

    The Current Selection's Settings window appears. Figure 6.5 shows three typical scenarios that can occur:

    Figure 6.5. Checking the selected table settings.

  • All current settings are From Table. Changes to this table's format tag work fine (see 6.5).

  • None of the settings is From Table. As a result, updating this table's format tag has no effect on the table. As you can see, the other settings present are overriding the From Table setting. This table was imported from Microsoft Word (see 6.5).

  • This table has a mixture of settings. Some elements of the table use the table's format tag setting, whereas others have a particular setting that overrides the setting of the table tag. In this example the settings for Top, Bottom, and Left use From Table. However, Right uses the setting Medium that overrides the table format setting (see 6.5).

Note

See Chapter 12 for more information on Microsoft Word conversion.

Resetting Table Settings

If the problem is that some other setting is overriding the setting that you want to use from the table format tag, you reset the table settings back to the table tag format. Here's how to fix it:

  1. Select the entire table.

    The table is selected. In this method, do not select the anchor. Selecting the anchor selects the entire table, but FrameMaker doesn't recognize the separate table elements as selected.

  2. Select Table > Custom Ruling & Shading.

    The Custom Ruling & Shading window appears.

  3. Click the check box for Custom Cell Ruling. Select From Table in the Apply Ruling Style List. Check all items under To Selection.

    As a result, the Ruling setting from the table tag is applied to the entire table. The current setting for all selected items is overridden. If you do not check all the boxes, certain parts of the table are left out.

  4. Click the check box for Custom Cell Shading. Select From Table in both the Fill and Color drop-down menus (see Figure 6.6).

    Figure 6.6. You can use the Custom Ruling & Shading dialog box to reset table settings

    As a result, the Fill and Color cell shading from the table tag overrides any current settings (the settings you don't want).

  5. Click on Apply.

    The Custom Ruling & Shading setting is applied to the selected table. The selected table now takes on the formats of the table tag, with regard to ruling and shading.
Tables That Won't Accept Table Tag Cell Margin Changes

In the last exercise, the look of a table was determined by more than just the table tag format itself. Other FrameMaker commands have the ability to override some of the table format settings. This section takes a look at how table format tags work with paragraph tags.

If you believe that you changed and updated the Cell Margin settings for a particular table format tag but some tables do not accept this change, the Paragraph Designer probably has something to do with the problem. In the Table Designer, you can specify only Default Cell Margin settings for each table. These defaults can be overridden by the Table Cell properties of the Paragraph Designer for one table cell, a group of cells, or all the cells, depending on how the Paragraph Designer's Table Cell properties were applied. You won't know until you check into the situation.

If you have just one table cell that contains text that refuses to accept the new Default Cell Margin settings from the table tag, here's how to do it:

  1. Click one time in table cell text.

    The insertion cursor is inserted in the table cell's text.

  2. Select Format > Paragraphs > Designer.

    The Paragraph Designer window appears.

  3. Click the Table Cell tab or select Table Cell from the Properties drop-down menu.

    The Table Cell properties appears.

  4. View the Table Cell properties.

    If any of the Cell Margins settings has Custom selected, or has From Table Format, Plus: selected and a number other than zero, the Paragraph Designer table cell property is overriding the table tag Default Cell Margins setting for that margin.

  5. If Custom is selected, select From Table Format, Plus: from the drop-down list for the affected margin.

  6. If a number is in the field to the right of the drop-down list, change that number to zero.

  7. Click on either Apply to Selection to fix the currently selected cell or Update All to fix all table cells that have this paragraph tag applied.

Using Table Continuation or Table Sheet

If your document contains a table that spans two or more pages, your readers will have a much easier time navigating if they are notified whether the table page they are viewing belongs to the same table as the preceding page or to a new table. To communicate that information, you can use one of two variables: Table Continuation and Table Sheet, which were mentioned earlier in the section "Table Continuation and Table Sheet in Titles" on page 162.

Inserting Table Continuation or Table Sheet

To insert either the Table Continuation or Table Sheet variables, follow these steps:

  1. Click one time in the table title.

    The insertion cursor is inserted in the table title. If text is present in the table title, hit the space bar one time after the text. If you do not insert a space between the end of the text and the variable, the title runs into the variable text on subsequent pages of the table.

  2. Select Special > Variable.

    The Variable window appears.

  3. Select either Table Continuation or Table Sheet. Then click on the Insert button.

    The variable is inserted into the table title. If you choose Table Sheet and your table spans more than one page, "(Sheet 1 of 2)" is displayed on the first page of the table, and subsequent pages are numbered accordingly. If you choose Table Continuation, a non-breaking space is displayed in the title on the first page, and "Continued" is displayed on subsequent pages in the table title.

Changing Table Continuation Display

The default display for Table Continuation is "(Continued)". In other words, if your table spans multiple pages and you include this variable in the table title, on subsequent pages the table title reads "(Continued)" after the table title text. This may or may not be suitable for your documents. You might prefer a shortened version, such as "(Cont'd)" or maybe an italicized "Continued" works better for you.

Let's take a look at how to change the format of the word Continued. In this example, change the current default Table Continuation variable to read:

Cont'd

instead of

(Continued)

Back to Basics

Create new character formats with Format > Characters > Designer.

Notice that the change includes not only abbreviating but adding italics to the word "Cont'd". Before you get started, it's a good idea to check the Character Catalog in your FrameMaker document to see what character formats are available. If the character format you plan to use for italics is not already part of the Character Catalog, you must create it first and add it to the Character Catalog. If it is not available in the Character Catalog, it isn't available for use in formatting the Table Continuation.

The following steps show you how to make changes to the Table Continuation variable:

  1. Select Special > Variable.

    The Variable window appears.

  2. Click on Table Continuation to select it.

    The Table Continuation variable is selected and its current definition, "(Continued)", is displayed below the variable list.

  3. Click on Edit Definition.

    The Edit System Definition window appears.

  4. Select "(Continued)" in the Definition text field and delete it. Type "Cont'd" in its place.

    The word "Cont'd" is inserted in the Definition text field. As a result, "Cont'" is displayed on the second and subsequent pages when this variable is used in a table title.

  5. Place the insertion cursor just before the word Cont'd and click on <Emphasis> in the Building Blocks list.

    The Building Block <Emphasis> is inserted in the Definition text field, as shown in Figure 6.7. <Emphasis> represents the Emphasis character tag. As a result, all characters to the right of the <Emphasis> Building Block are formatted in italic.

    Figure 6.7. The Edit Table Continuation variable.

  6. Click on Edit.

    The Table Continuation variable is updated to reflect the new change. The Variable window appears again.

  7. Click on Done.

    The document page is displayed. All occurrences of the Table Continuation variable are updated to reflect the new change, and all future insertions of this variable will contain the new change.

Changing Table Sheet Display

The default display for Table Sheet is "(Sheet sheet number of total number of sheets)". For example, "(Sheet 2 of 4)" means that your reader is looking at the second page of a four-page table. That is, Table Sheet indicates both the current page of the table and the total number of pages included in the table. It's very handy.

As with the Table Continuation variable, you might want to alter the appearance of this a bit. Take a look at how to change it. In this example, you change the current default Table Sheet variable to read:

Sheet x of x

instead of

(Sheet x of x)

Here's how to do it:

Back to Basics

Character formats in variables are limited to those already part of the Character Catalog.

  1. Select Special > Variable.

    The Variable window appears.

  2. Click on Table Sheet to select it.

    The Table Sheet variable is selected and its current definition is displayed below the variable list.

  3. Click on Edit Definition.

    The Edit System Definition window appears.

  4. Place the insertion cursor just before the first character of the current definition, and click on <Emphasis> in the Building Blocks list.

    The Building Block <Emphasis> is inserted in the Definition text field. This Building Block represents the Emphasis character tag. As a result, all characters to the right of the <Emphasis> Building Block are transformed into italic.

  5. Delete the parentheses on either side of the current Table Sheet definition.

    The parentheses are deleted. The definition looks like Figure 6.8. The <$tblsheetnum> Building Block represents the current table page number, and <$tblsheetcount> represents the total number of pages included in the table.

    Figure 6.8. The Edit Table Sheet variable.

Tip

In the Definition field, Ctrl left or right arrow to jump around each block of the definition.

  6. Click on Edit.

    The Table Sheet variable is updated to reflect the new change. The Variable window is again displayed.

  7. Click on Done.

    The document page is again displayed. All occurrences of the Table Sheet variable are updated to reflect the new change and all future insertions of this variable will contain the new change.

You can insert either one of these variable into a table title to test them out. If the current table does not span several pages yet, place the insertion cursor inside a row and use Table > Add Rows or Columns to make the table span more than one page for testing purposes. Or, add a row and put a tall anchored frame inside one of its cells.

Back to Basics

With the insertion cursor in a row, press Ctrl+Enter to add rows.

Troubleshooting Heading and Footing Rows

This section explores some of the traits of header or footing rows and ways to troubleshoot both.

When It Looks Like a Heading But It's Not

Heading rows, as discussed in the section "Heading Rows" on page 162, are often indicated in documents with bold or some other type of specially formatted text. Often, however, a heading row might look like a heading row, but might in fact be a "pretender."

How do you know if the heading row is a "pretender"? If your heading rows are not repeating on subsequent pages of the table, then clearly, it's not a real heading row. The same is true of footing rows.

Adding Heading Rows

If you run into this heading row problem, don't panic, and certainly don't create an entirely new table and reenter all the data. Just add a heading row to the existing table by following these steps:

  1. Click anywhere in the table.

    The insertion cursor is inserted in the table.

  2. Select Table > Add Rows or Columns from the menu.

    The Add Rows or Columns window appears.

  3. Select To Heading from the Rows drop-down menu (see Figure 6.9). Click the Add button.

    Figure 6.9. Use the Add Rows or Columns dialog box to add a heading row.

    A real heading row is added to the current table. Type the heading text inside the cells of this row. These cells are repeated on each subsequent page of the table.

Tip

Heading rows in tables imported from programs such as Microsoft Word do not work as real heading rows. A real FrameMaker header row must be added to these tables manually.

Checking for Real Heading Rows

If your table spans just one page and you want to determine whether or not the heading row is real, here's how to do it:

Back to Basics

You can Ctrl-double-click in between two columns to select an entire row.

  1. Select the entire top row.

  2. Look in the status bar (see Figure 6.10).

    Figure 6.10. Check the status bar for the heading cell.

    It displays "Heading Cells" for real heading rows and "Body Cells" for ordinary body text rows.

  3. If the top row is not a real heading row, follow the steps in the previous exercise so that you don't run into problems later.

Footing Rows

Similarly, if you think a footing row is a footing row, but it's not repeating on subsequent pages, it's not a real footing row.

To add a footing row to a table at any time, follow the steps in the section "Adding Heading Rows" on page 178. Just select To Footing instead of To Heading from the Row(s) drop-down list.

If your table does not yet extend over one page, you can select the bottom row and look in the status bar to see whether it's a real footing row, just as you can for a heading row.

Tables and Text

It's important to understand that, like anything else in a document, tables are not an entity unto themselves. Tables work in conjunction with many other FrameMaker functions, as you have probably experienced in your day-to-day tasks and read about in this chapter. This section takes you through some of the challenges presented in working with text in table cells. For this purpose, I focus on text behavior in cells and converting tables to and from text.

Text in Cells

You might have noticed that when you insert a new table, the text in the title, heading, and body cells is automatically formatted with a particular paragraph tag. Read through the section "Transparent Properties" on page 164 for a more in-depth explanation of this concept. In the meantime, it's important to understand that whatever paragraph format is automatically set in table title, heading, and body cells, you can change these at any time by simply applying a new paragraph tag to one or more cells.

Text in cells is formatted with a combination of a paragraph tag and the Table Designer basic properties.

Here is a breakdown of how this works: The Table Designer Basic properties allow you to define the Default Cell Margins for each cell in a table. This setting is applied to the entire table. In other words, you cannot set this property for one or a particular set of cells. Default Cell Margins refers to the distance between the edge of the cell and the text. You can set default Cell Margins for top, bottom, left, and right. The actual table cell margins, however, are also determined on a cell by cell basis by the Paragraph Designer's Table Cell properties.The Paragraph Designer Table Cell properties overrides the default cell margin setting from the Table Designer. This feature was already encountered in the section "Tables That Won't Accept Table Tag Cell Margin Changes" on page 172, where you wanted to defeat overrides.

Take a look at a simple example in which you actually want to override the Table Designer's default cell margins. Imagine a table set up with all default cell margins at 2 pt. Now suppose that the table heading cells don't look good with this spacing (perhaps because they are set in a bolder font), so they need to have a bit more space; say, 4 pt on all sides. Here's how to put that space in to the table heading cell row:

Back to Basics

In the Paragraph Designer, you can also select Table Cell from the Properties drop-down menu.

  1. Select the heading cells of the table that you want to change.

    The heading cells is selected.

  2. Select Format > Paragraphs > Designer. Click on the Table Cell tab.

    The Paragraph Designer Table Cell properties window appears. CellHeading is displayed in the Paragraph Tag drop-down menu.

  3. In the Cell Margins pane, select From Table Format Plus: from the drop-down lists for Top, Bottom, Left, and Right.

    From Table Format Plus: is the default selection. When this selection is applied to text within a cell, the cell margin is the sum of the original setting from the Table Designer plus the additional amount of space set in this window. In this example, the Table Designer specifies 2 pt. You want the cell spacing to be 4 pt, so the additional amount of space required is 2 pt.

  4. Type 2.0 pt in each of the settings, as shown in Figure 6.11.

    Figure 6.11. The Paragraph Designer table cell settings.

Back to Basics

There's no need to type 2.0 pt in text fields. Type 2.

  5. Click Update All if you are updating all CellHeadings paragraphs, or click Apply To Selection if you want to update only the current selection.

    The selected CellHeading text is updated with the cell margin changes. The Paragraph Designer overrides the setting of the Table Designer, thus making the cell margins for the selected cell text 4 pt on all sides.

Converting Tables To and From Text

The ability to convert tables to and from text is handy, especially when you import text from other sources in tab- or space-delimited format. This feature saves you a lot of time copying and pasting individual bits of text into cells. Let's go over an example of how to use this feature, some of the pitfalls to be aware of, and how to fix them.

Begin by converting tabbed text to a table. After you understand this concept, you can also convert text separated by spaces or other characters.

When you have tabbed text in FrameMaker that is not formatted in any way, it looks something like Figure 6.12. Notice that, even with Text Symbols turned on, the tabs are difficult to see because they are buried in the text. The text itself is difficult to see. Each line of text represents a row of a table. Each string of text in between tabs represents a cell within a column. This example represents a table that contains four columns and three rows. To break this down further, the first row is a heading row, and the remaining two rows are body rows.

Figure 6.12. An example of tabbed text that's ready to be converted into a table.

It's time to begin the conversion. Suppose you want to convert the tabbed text into a Format B table:

  1. Select the tabbed text that you want to convert to a table.

    The tabbed text is selected. If you leave some text out of the selection, that text is not included in the new table.

  2. Select Table > Convert to Table.

    The Convert to Table window appears.

  3. Click one time on Format B, located in the Table Format list on the left side of the window.

    Table Format B is selected in the Table Format list. Format B is the table format to which the tabbed text is converted. After the text is in a table format, you can apply any existing table format or modify the format.

  4. In the Treat Each Paragraph As pane, select A Row with Cells Separated By > Tabs.

    Tabs are selected. As a result, each paragraph line of the tabbed text is treated as a row. Each string of text in between the tabs is treated as a cell within that row.

  5. Type 1 in the Heading Row text field. Do not check Leave Heading Rows Empty, as shown in Figure 6.13.

    Figure 6.13. The Convert to Table window settings.

  6. Click on Convert after you finish.

    The tabbed text is converted to the selected table according to the settings in the Convert to Table window. When Heading Row is 1 and Leave Heading Rows Empty is not checked, the first paragraph line of tabbed text becomes the heading row of the table. If Heading Row is 1 and Leave Heading Rows Empty is checked, the first paragraph line of tabbed text is a body row, and an empty heading row is included in the table. If you do not type any number in the Heading Rows text box, no heading row is included in the table.

That was fairly easy to do. That is the case when tabbed text is neat and organized from the onset. Now it's time to add some typical complications to this equation and see what happens. These complications can happen with text that is tabbed, spaced, and so on.

Extra Tabs

Tabbed text often has more than one consecutive tab between strings of text that are intended to be in adjacent cells. This problem is especially likely to occur when tabbed text is imported from other sources. Consecutive tabs are difficult to see in FrameMaker (even with Text Symbols turned on); they usually appear to the naked eye as a single tab. But if you convert problematic tabbed text to a table, you might see a result similar to Figure 6.14.

Figure 6.14. Sloppy tabbed text converted to a table.

Empty cells are between the intended text strings. As a result, the columns don't line up and the table contains so many extra columns that it runs off the page. Each empty cell represents an extra tab. You must be a detective of sorts and clean up the tabbed text before you start the conversion. Fortunately, with FrameMaker's powerful tools, this is a simple task:

  1. Select the tabbed text.

    The tabbed text is selected.

  2. Select Edit > Find/Change.

    The Find/Change window appears.

  3. Type \t\t in the Find > Text field. Type \t in the Change > To Text field.

    As a result, FrameMaker looks for pairs of consecutive tabs and replaces each of them with a single tab.

  4. Click Selection.

    As a result, FrameMaker searches through the selected tabbed text only and not other text in the document.

  5. Click on Find.

  6. When the first pair of tabs is found, click Change & Find (see Figure 6.15).

    Figure 6.15. The Find/Change dialog box for tabbed text cleanup.

  7. Continue to find and replace until no pairs of consecutive tabs are left.

After you complete the process of cleaning up the tabbed text that you want to convert to a table, you can use the technique discussed in the section "Converting Tables To and From Text" on page 181 to perform the conversion. Then the table is displayed nicely and neatly in columns and rows, without gaping cell holes.

Table Row Controls

The position of an entire table can be controlled from the Table Designer. Similarly, you can control one or more rows within a table, but by using other commands. Understanding these commands not only helps you to control table rows that you are currently working on but also helps you troubleshoot badly behaving tables. Two of the topics explored in this section are formats applied to rows and solving the mystery of disappearing text within rows.

Special Formats for Rows

When you need particular rows to start at the top of a page, to keep rows together with other rows, or to specify the row height instead of relying on the automatic row height, special row formats are the tool to use.

When you use these commands, click first in the row that you want to format. Then select Table > Row Format. The purpose of each of the settings in the Row Format window, as shown in Figure 6.16, are the following:

Figure 6.16. The Row Format window.

  • Height Limits. Use this property to impose limits on the height of a table row. For example, if the minimum is set to 2 inches, then regardless of how little text is included in the cell, the row will never be less than 2 inches high. If the maximum is set to 2 inches, the cells in that row will never grow larger than 2 inches, regardless of how much text is in the cell.

  • Start Row. Use this property to start a particular row at the top of a page or column. For example, if you have a table with five rows, and row 2 is set to start at the top of a page, the title, heading, and row 1 will appear on page 1, with the heading cells and row 2 starting at the top of page 2 followed by the remaining rows.

  • Keep With. Use this property when one or more rows should never be separated from one another. For example, you might have subheads within a table that must always stay with the row that follows.

Back to Basics

If you do not click in a table cell, Table > Row Format is not accessible.

Keep these commands in mind when you work on documents that you inherited from another person. If you have trouble with tables breaking in strange places, just click in the row and look in Row Format. Usually, that is the source of the difficulty.

Disappearing Text

Row height commands determine the minimum and maximum height of a row. Suppose that the row height maximum is set to 3 inches, but the cells in one row have so much text that you do not see all the text that is in each cell. In other words, the text is cut off at the point where the cell height reaches 3 inches. If you find yourself in this situation, don't panic; simply click on the problem row and select Table > Row Format. Change the height maximum to a large number, such as 14 inches, and the text reappears in the cell.

Tables for Figure and Caption Placement

When figures with captions must be inserted in documents, a common approach is to put each figure caption on a separate paragraph line with its own paragraph tag applied either above or below the anchored frame that contains the figure. Although this technique is a good method to use to insert figures and their captions, sometimes the captions can get separated from the figures. For example, you might have seen a figure caption on the page after the figure itself. This problem is easy to fix for a few figures, but when documents have more than a few figures, it can be time-consuming to fix all occurrences.

Consider using tables as a solution to keep figures and their captions together. The Table Designer also allows you to specify spacing above and below each table. Therefore, you can easily keep spacing consistent throughout the document for all figures with captions. You can configure the table in a variety of ways, depending on the intended look of your document. Two methods that work well are described in the following sections.

Putting Figure and Figure Caption in Tables

Let's see how to use a table to get your figures and their captions looking good and staying together. If you want to reserve table Format A for figures and you have a paragraph tag Caption for the captions, the following steps puts a figure caption below its figure.

Inserting a New Table

To insert a new table, follow these steps:

  1. Select Table > Insert Table.

    The Insert Table window appears.

  2. Select Format A.

  3. Set Columns to 1, and Body Rows to 1, and other items to 0.

  4. Click Insert.

    A table is inserted with one column and one body row. The table contains one cell, which is used to insert the figure. The Table Title area is used for the caption. (Heading and footing rows are not necessary for this exercise.)
Setting the Table Title Position

Next, use the Table Designer to determine the title position. The title position is where you will enter the figure caption:

  1. Select Table > Table Designer.

    The Table Designer appears.

  2. Select Below Table from the drop-down list in the Title Position pane.

    The table title, which contains the caption, is set below the table. Select Above Table from the drop-down list instead to have the captions appear above the figures.

  3. Click Update All after you finish.

    All tables tagged with Format A and the Table Catalog are updated with the title position change.
Setting the Ruling Properties

After you finish, set the Ruling properties for the table to display none. To do this, follow these steps:

  1. Click on the Ruling tab or select Ruling from the Properties drop-down menu.

    The Ruling properties for Format A appears.

  2. Set all ruling options to None.

  3. Click Update All when you finish.

    All tables tagged with Format A and the Table Catalog are updated with the ruling changes.
Inserting a Figure into a Table

Now that you have a table set up to use for a figure and its caption, it's time to insert the figure in the table. To do this, follow these steps:

  1. Place the insertion cursor in the table cell.

    The insertion cursor is inserted in the table cell.

  2. Select File > Import > File.

  3. Navigate to the figure you want to import into your document and select Import.

    The file you select is placed inside an anchored frame within the table cell.

  4. Click in the Table Title area and type the caption.

    The caption text is inserted in the table title. The text is formatted with the Table Title paragraph tag, because you haven't yet applied the Caption paragraph tag.

  5. Apply the Caption paragraph tag to the caption text.

    The Caption paragraph tag is applied to the caption text. The text takes on the paragraph properties of a figure caption however you specified them. Figure 6.17 shows the completed table with a figure and figure caption below.

    Figure 6.17. Figure in table with the caption below it.

Update the table Format A so that each time you insert table Format A, the Caption paragraph tag, rather than the Table Title paragraph tag, is automatically part of the table title area:

  1. Click anywhere in a Format A table that contains the Caption paragraph tag in its Table Title area.

    The insertion cursor is placed in the table. To use table commands, the insertion cursor must be inserted somewhere in the table.

  2. Select Table > Table Designer.

    The Table Designer window appears. The tag of the current table, Format A, is displayed in the Table Tag name field.

  3. Click on Update All.

    The Transparent properties for table tag Format A is updated to store Caption as the new default paragraph tag for the Table Title area.

Back to Basics

The default paragraph tag is not an option in the Table Designer window but rather a Transparent property. See the section "Transparent Properties" on page 164.

Figures with Side Captions

In the previous section, you saw how to create the table for a figure with its caption either above or below it. Often, however, books and other documents are designed to have captions set to the left or right of the figures, at least if the figures are narrow. This design often looks better and saves space. Let's look at a table configuration that sets the caption to the left or right of the figure. Many of the steps were reviewed in detail in the last exercise. Here are the key distinctive points in setting side titles:

  1. Insert a table with two columns and one body row.

  2. Resize the left column to the correct width for the caption.

  3. Type the caption text in the left column of the table and apply the Caption paragraph tag to the text.

  4. Import the figure into the right column cell of the table.

  5. In the Basic properties of the Table Designer, select No Title from the drop-down list in the Table Position pane.

    This kind of table has no title area. For a figure with a side caption, the title area of the table is unnecessary and takes up extra space.

  6. Update the Table Designer to use Caption as the new default paragraph tag in the left column each time you insert this table format. Figure 6.18 shows the completed table with a figure and figure caption to the left.

    Figure 6.18. A figure in a table with a side caption.

Tables as a Solution for Caution Notes

Note

See Chapter 2 for more information on inserting notes and cautions.

Tables are a great way to insert caution notes into documents. You can even include a graphic automatically. Figure 6.19 shows an example of a caution note.

Figure 6.19. A table used for caution notes.

Let's see how to create this type of table. After you finish, you should be able to come up with even more unique ways to create notes and cautions within your documents.

This exercise combines a variety of FrameMaker functions, including tables, paragraph tags, and reference frames on reference pages. Table formats cannot contain a graphic per se, but they can contain a paragraph tag, so you'll create a graphic to use as a frame above the paragraph tag used in the table automatically. All the steps necessary to create the new table, the referenced frame with graphic used in the paragraph tag, and the paragraph tag are described in the next sections.

Inserting and Resizing a New Table

First, insert and size the columns of a new table by following these steps:

  1. Use Table > Insert Table to insert a new table with two columns and one body row.

    A new table is inserted at the insertion cursor in the document with two columns and one body row. Because you are creating a new table format, it's irrelevant which table format you chose to insert for the new table. The table you inserted may or may not have a table title. That's fine for now; you fix this later.

  2. Click in the left cell and select Table > Resize Columns.

    The Resize Selected Columns window appears.

  3. Select the To Width radio button and set the width of the first column to .6 inches.

    The first column of the newly inserted table is .6 inches wide.

  4. Click in the right cell and use Table > Resize Columns to set the width of the second column to 3.4 inches.

    The second column of the newly inserted table is 3.4 inches wide. You can use any measurement. These measurements are simply a guide for this exercise.
Creating a New Table Tag

Next, you create the new table tag name based on the inserted table configuration:

Back to Basics

The insertion cursor must be inside a table in order to use the Table Designer.

  1. Select Table > Table Designer.

    The Table Designer window appears. The table format that was used when you first inserted this table is displayed in the Table Tag field.

  2. Type the new name Caution for the table in the Table Tag field.

    The new table tag name, "Caution", is displayed in the Table Tag field.

  3. Click Apply To Selection.

    The New Format window appears.

  4. Make sure that Store in Catalog and Apply to Selection are both checked; click Create.

    A new table format is created. Store in Catalog means that this new format is part of the Table Catalog. Apply to Selection means that this new format is applied to the currently selected table.

  5. Define properties for the new Caution table format, as shown in Figure 6.20.

    Figure 6.20. The Table design Properties for caution note.

Back to Basics

After you update each property category, click on Update All before you move to the next category.

Creating a Reference Frame

Now that the table is inserted and its table tag created, it's time to create the reference frame that will contain the graphic for use in the caution table.

  1. Select View > Reference Pages.

    The first reference page appears. Several reference frames are already on this page.

  2. Select the Place a Graphic Frame tool from the Graphics Toolbox. Draw a Graphic Frame on the first reference page. A frame is inserted on the first reference page. The Frame Name window appears.

  3. Type the name CautionGraphic in the Frame Name text field, and click on the Set button.

    CautionGraphic is the name of this reference frame. CautionGraphic is displayed in the Paragraph Designer Advanced Properties, in the Frame Above and Frame Below Paragraph drop-down menus.

  4. Click one time on the CautionGraphic reference frame to select it.

    The CautionGraphic reference frame appears selected. Note the selection anchors on all sides of the reference frame.

  5. Select File > Import File to import the graphic that you want to use for the caution image.

  6. Navigate to the correct file that contains your caution graphic and click on Import.

    The imported file is inserted in the CautionGraphic reference frame. You can now resize the graphic as desired within the reference frame.

Back to Basics

Use Graphics > Tools to show the graphics toolbox. You can see a tool's name by hovering the mouse pointer over an icon.

You're almost there! So far, you created the table and the reference frame that contains the graphic for use in the caution table. Next, set up the paragraph tag that will be part of this table's format.

Setting Up the Caution Paragraph Tag

For this part of the exercise, start with the insertion cursor in the first column cell of the new caution table, and do the following:

  1. Select Format > Paragraphs > Designer.

    The Paragraph Designer window appears.

  2. Type a new paragraph tag named Caution in the Paragraph Tag field.

Tip

You can press Ctrl+M to access the Paragraph Designer.

  3. Caution displays in the Paragraph Tag field. Click on Apply To Selection.

    The New Format window appears.

  4. Make sure that Store in Catalog and Apply To Selection are both checked, and click on Create.

    FrameMaker creates a new paragraph tag. Store in Catalog means that this new tag is part of the Paragraph Catalog. Apply To Selection means that this new tag is applied to the currently selected paragraph.

  5. Click on the Advanced tab.

    The Advanced properties window appears.

  6. Select CautionGraphic from the Frame Above Pgf drop-down menu and click Update All.

    The image inside the CautionGraphic reference frame located on the reference page is displayed in the table cell that contains the insertion cursor (see Figure 6.21).

    Figure 6.21. The Paragraph Designer Advanced Properties Frame Above Pgf.

Back to Basics

In the Paragraph Designer, you can select Advanced from the Properties drop-down menu.

  7. Adjust other properties of the Caution paragraph tag as desired, and click Update All when you're finished.

  8. Click in the right cell of the Caution table and create a new paragraph tag for text that's displayed in this part of the table.

Now that you completed all the parts required to create the Caution table, the final step is to incorporate all this into the Caution table format. Then, each time you insert a table using the table tag Caution, the Caution paragraph tag and its graphic will be automatically part of the left cell, and the right cell will contain the correct paragraph tag for the caution note text.

Reconfiguring the Caution Table Format

To reconfigure the Caution table format, follow these steps:

  1. Click anywhere in the Caution table.

    The insertion cursor is inserted in the table. To use table commands, the insertion cursor must be inserted somewhere inside the table.

  2. Select Table > Table Designer.

    The Table Designer window appears. The current table tag, Caution, is displayed in the Table Title name field.

  3. Click on Update All.

    The transparent properties for the table tag Caution is updated to store the new default paragraph tags for both the left and right column cells of this table.

Using Tables for Section Titles on Left and Right Pages

Another interesting trick that can be done with tables is to create Section Title paragraph tag placement on a page that automatically adjusts to left-hand and right-hand pages.

For example, you might want the section title to always appear on the page farthest from the binding. You could do this formatting by selecting Left or Right Alignment from the Basic tab of Paragraph Designer. However, the problem arises if you add text to the document that causes the Section paragraph tag to flow to the next page. Then the alignment would no longer be consistent with "side farthest from the binding." You can fix this problem by searching through the document and manually adjusting each Section paragraph tag alignment, or you can use tables and have FrameMaker do it automatically. Here's how:

  1. Create a one-cell table format. You can name it HeadingTable in the Table Catalog.

  2. In the Table Designer's Basic tab, click on the Alignment drop-down list and select Side Farther From Binding.

  3. Use the previous techniques to eliminate all rulings around the table.

  4. Insert the heading table where you want the section heading to appear.

  5. Put the cursor in the table and select the appropriate heading paragraph tag from the Paragraph Tag Catalog (H1, H2, and so on).

  6. Type the section heading text in the table.

  7. Go to Table > Resize Column and click on the button To Width of Selected Cell's Content. Click on Resize.

That's all there is to it. If text were added at this point in the document so that the heading would flow to the next page, the alignment would automatically shift to the other edge.

Summary

Inserting tables in FrameMaker documents is straightforward, but the quirks can get you every time. In this chapter, you learned how tables work together with other FrameMaker functions and how to approach some typical table problems that might arise.

When you work with and problem-solve tables, keep in mind the other FrameMaker functions that work hand in hand with tables and some of the rules of thumb that go along with them.


Chapter 7

Chapter 7. Combining Documents into Books

  • Why Build a Book
  • Overview of a Book File
  • A Word About Planning
  • Organizing and Managing Book Files
  • Going Bookwide
  • How Numbering Works in a Book
  • Updating File Information
  • Solving Book File Errors
  • Summary

Organizing and maintaining long documents is a necessary part of the documentation process. In the same way that chapters make up a book, smaller document files can make up one larger document. Small document files typically consist of chapters or sections, front matter such as title page and preface, table of contents, appendixes, and an index. FrameMaker's book features provide the capability required to combine the various files that make up a book. Regardless of how many files you want to include in a book, you'll appreciate being able to work in a single document window while viewing or making changes to the overall organization of the document files that make up the book.

FrameMaker's book features bring many productive tools to the table, such as the ability to produce a single table of contents or index based on the smaller set of documents files, as well as applying a variety of settings to some or all of the document files in the book at one time.

In this chapter, you discover the benefits of building book files in FrameMaker through examples such as creating a new book file, working with a variety of commands across some or all the files included in the book, understanding how numbering works, and updating numbering, cross-references, text insets, or generated files with up-to-date information.

Why Build a Book

The benefits of book building in FrameMaker all add up to making some tasks in the document production process an easier and more streamlined operation for you to perform. While you'll always work with document files individually to include content, apply formatting to paragraphs and customize other elements, book building provides the means to work with a collection of document files as one unit and implement an imposing array of features.

While you work with a FrameMaker book file, here are a few tasks that you can use to your advantage:

  • Open, close, save, and organize files from a central location

  • Apply various commands or settings to one or more files

  • Page through the entire book

  • Produce the table of contents or another list

  • Using Spelling Checker and Find/Change across all files

  • Specify Numbering Properties

  • Print or save to PDF

Working with FrameMaker book files does not require that you have a real book. In other words, you don't have to be working on a software manual or another multi-chapter document to use these powerful book features. For example, if you were working on a stand-alone document file (such as a 75-page report) that grew too large in size because of intensive graphics or tables, you could easily split that file into two smaller files and use FrameMaker's book features to work with the two files as one unit.

Book files are not just for "books" per se. They can be used for any document files that are part of a bigger picture that you want to treat as one unit for the purpose of managing or applying certain FrameMaker commands.

Overview of a Book File

Before getting started with book building, it's a good idea to understand some basics about a book file because you will be working with it most of the time while performing book functions. A book file is not like a document file; it's a file that simply contains a list of filenames that are included in the book. The book file holds the key to particular settings and organization information for each file included in the book, as well as the ability to perform certain commands such as Find/ Change and Spelling Checker for one or more files contained in the book.

Back to Basics

Book file settings override individual file settings.

After you create a book file and add some document files to the book, your Book File window might look similar to Figure 7.1.

Figure 7.1. Working with the Book File window.

As you can see, the files included in the book are listed in the Book File window. If you click once on any file in the list, the status area displays the page numbers that file comprises in relation to the entire book. That page number is also displayed in the current page numbering style for that particular document file. If you select more than one document file, the status area displays the full page range of the selected files. If certain files restart page numbering or differ in numbering style, the page numbers are displayed in sets (in their native style), separated by commas.

Back to Basics

You can select more than one document file from the Book File window by holding down the Ctrl key and clicking on the desired files.

You can quickly execute commonly used commands with the four icons located on the lower right of the window. Table 7.1 provides a description of each Book File window icon.

Table 7.1. Book Window Command Icons

Command

Icon

Description

Display Heading Text/Display Filenames

Toggle between the actual name of the file or the heading text of the first heading displayed in a document.

Update Book and Generate Lists and Indexes

This one command combines two separate operations. First, Update Book supplies numbering, referenced files, cross-references, page numbering, and page type with the most recent or correct information. Next, the Generate operation creates a variety of lists that you have included in the book file, such as table of contents, indexes, or other lists, and subsequently refreshes the source information included in each of those files.

Add File to Book

Use this to add one or more document files to the current book file.

Delete Selected File from Book

Use this to delete selected files from the book list. Be certain that you want to delete a file from the book before clicking on this button. You will not see a dialog window asking, "Do you really want to do this?" Keep in mind that when using this button, you are only deleting the file from the book list, and not the file itself.

A Word About Planning

Although a book file allows you to manage all the files included in a book from a single window, you should still keep those files organized on your hard drive. For example, if you have a book file, 10 document files, and 1 table of contents, keeping all those files (and any referenced files, such as figures) in one folder on your computer disk helps you to manage those components. This is especially true if you plan to move the files to another location at a later time, whether it be to a CD, network server, or some other location on your local computer. Imagine if you had 10 document files in 10 different folders on your hard drive and referenced figure files in yet another location. If you were to move the files, it wouldn't be easy to gather all the files from various locations and maintain the correct file path for the book file to locate each file. By keeping all the ingredients of your book in one location, the file path isn't broken, and moving one folder to another location ensures that the path to each file contained in the book remains intact.

Another consideration is the file-naming conventions that you need to use for document files. For example, suppose that you created FrameMaker files with long filenames and included those in a book file. Next, you moved the book file and its components to another computer that's not configured to read filenames with so many characters. The result: Each filename becomes truncated on the disk, and the book loses its connection to each file because the filenames no longer match the filename in the book file list.

With this in mind, use file-naming conventions that work on most computing platforms, regardless of how they are configured.

Organizing and Managing Book Files

Tip

Save the book file after you make any changes. The asterisk indicates that the file has not been saved since the last change.

A FrameMaker book is the glue that holds its components together and your best friend in organizing and managing a set of files. This section explores the features that contribute to the physical organizing and managing of files within a book, before moving on to understanding the details of particular settings for individual files contained therein.

Getting Started with a Book File

Every book in FrameMaker starts with a book file. If you are reading this chapter, you have probably either created or worked with a FrameMaker template to contain the content of your document and are ready to combine those documents into a book file. The first step in building a book is to create the book file. Whether or not you have another FrameMaker document open, here is how to create a book file:

  1. Select File > New > Book.

    A new, untitled Book window displays. If no documents are open when you create the book, the untitled Book window remains empty. If a document is open and active when you create the book, the message "Do you want to add the file, 'filename.fm', to the new book?" is displayed. If you select Yes, this file is automatically added to the book list. If you previously created a stand-alone table of contents for this document file, the table of contents is automatically added with the document file (without warning).

  2. From the Book window, select File > Save (or Save As.)

    The Save Book window appears. Navigate to the location on your hard drive where you want to save the book file. Usually, this is the same location where you plan to put all the components of your book.

  3. Type the new book name in the File Name text field. Click on Save.

    Be sure to maintain the .book extension. The new book file is saved in the location with the name that you type. The .book filename extension indicates that this is a book file. If you look at the file icon on your computer (see Figure 7.2), you notice that the book file icon is slightly different from a FrameMaker document file icon. Do not change the filename extension, as the book file can become unusable.

    Figure 7.2. The difference between a book and document file icon.

Adding Document Files to a Book

With the Book File window active, you can add the document files that you want to include in the book. From the Book File window, here's how to do it:

Tip

You can use this button on the Book window task bar to add files.

  1. Use the menu to select Add > Files.

    The Add Files to Book window appears.

  2. Use the file folder navigation tools located at the top of the window to navigate to the folder that contains the files you want to add to the book.

    The list of files contained in the folder appears.

  3. Click one time on a file to select it, Shift-click to select multiple consecutive files or Control-click to select multiple non-consecutive files (see Figure 7.3). Click the Add button.

    Figure 7.3. You can add files to the Book window.

Back to Basics

You do not have to open the files to add them to the book.

You are returned to the Book window and the files that you added are included in the book file list. If included files are contained in a folder other than the folder containing the book file, the full path to the file will be displayed.

Sometimes, it's easier to find the files that you want to include in the book on your computer desktop (using the File Folder window) and just drag the files into the Book window. Using this method is as good as using the Add File command. Before you drop files into the Book window, arrange the windows so that both the FrameMaker Book window and the File Folder window that contains the files are in plain sight.

The files that you added to the book list might or might not be in the correct order. You correct that a little later in this section by using the Rearrange command.

Adding Non-FrameMaker Files

You can add document files, such as a Microsoft Word file, to the book. After the file is added to the book list, just double-click its name to open the file in its native application. Of course, you must have that native application installed on your computer for that to work. Although non-FrameMaker files can be included in the book list, they are ignored during FrameMaker book file updates or applying of other settings, such as formatting or numbering options.

Adding a Table of Contents or Another List

As you have seen so far, adding document files to a book is simple. If you plan to add a table of contents or other lists such as a list of figures, tables, or an index, it requires more thought and planning on your part. Table of contents and other lists are generated files in FrameMaker. FrameMaker creates this type of file based on some parameters and rules that you set up. For example, after the file, such as a table of contents, is initially created, you can decide what elements of the source information you want to include and determine the format and page layout of the file.

This section discusses how the table of contents works in relation to the book file.

Note

To learn more on creating, setting up, and formatting table of contents and other lists, see Chapter 8, "Creating Tables of Contents and Other Lists."

To learn details on Index lists, see Chapter 9, "Indexing."

The first time that you add a table of contents to a book file, while the name of the file exists in the book list, the file itself doesn't exist on disk until you update/generate the book file at least once. In other words, if you add the table of contents to the book file list for the first time and attempt to open that file by double-clicking on its name in the list without first updating/generating the book file, you see the message "File named filenameTOC.fm does not exist."

Fortunately, after adding this special type of generated file, FrameMaker prompts you to update the book before continuing. Although I explore updating books in the section, "Updating File Information," take a brief look at this command in this section to see how everything works together when adding generated files, such as a table of contents.

This example begins from the Book File window:

  1. Select Add > Table of Contents.

    The Set Up Table of Contents window appears (see Figure 7.4).

    Figure 7.4. The Set Up Table of Contents window.

  2. Use the drop-down list next to Add File to position the file before or after the currently selected file in the book list.

    When the table of contents is added to the book file, the order is as you selected with the Add File drop-down list. Don't be concerned if you don't make the correct order selection at this time. You have the opportunity at any time to rearrange files in the book list and update the information in the book based on the new arrangement.

  3. Double-click paragraph tags in the Don't Include list that you want to be included in the table of contents (see Figure 7.4).

    The paragraph tags you select move to the Include Paragraphs Tagged list on the left. The result: The source information of the paragraph tags you selected are included in the table of contents.

  4. Click once on Hypertext Links.

    A check is included next to Create Hypertext Links. When the table of contents is created, hypertext links are included for each list item, which enables you to jump from the list item to the source information in one click. To learn more, see the section "Using Hypertext Links" on page 253 in Chapter 8.

  5. Click the Add button after you finish.

    The Update Book window appears (see Figure 7.5). When the table of contents or other list filename is included in the Generate list and Generate Table of Contents, Lists, and Indexes is checked, the table of contents is created the first time. If just one or the other condition is true, the table of contents won't be created. If so, and you try to open the table of contents file, you see the "File does not exist" message.

    Figure 7.5. The Update Book window.

  6. Click on the Update button.

    The table of contents is added to the book file. The filename automatically becomes the same as the book file, with a TOC suffix (such as filenameTOC.fm).

Rearranging Files

Order is important in a book file. For example, if you add three files to the book, when you update the book file, the page and paragraph numbering is applied to the new files according to the order they appear in the book list.

Regardless of the order in which you added the files to the book list, you can easily organize the list of files at any time during the book-building process. To rearrange your files, do the following:

  1. Click and hold once on the filename that you want to move.

  2. The filename is highlighted.

  3. While you hold down the mouse button, move the file to the correct location in the list (see Figure 7.6).

    Figure 7.6. You can rearrange files at any time during the production process.

  4. When you move the cursor arrow, you see a line indicating where you are moving the file, as well as a marque that indicates that you are moving the file.

  5. Release the mouse button.

    The file moves to the new location in the book list. You must update the book file to include the new organizational information throughout the files.

Deleting Files

You might have discovered a file that was added in error, or simply not needed in the book file. Here's how to delete any file from the book list:

  1. Click once on the filename to select it.

    The file is highlighted in the list.

  2. Select Edit > Delete File from Book.

    The selected file is deleted from the book list. Although this file no longer is included in the book list, it still exists as a file on disk. You have not deleted the file from the disk.

Tip

You can use the Delete icon as shown in the Book File window. Or, you can right-click on the file to display the floating menu.

Moving File Locations and Renaming Files

When you work with many files that make up a book, relocating or renaming of files can occur. This section reviews the do's and don'ts for moving and renaming files.

Moving Files

Among FrameMaker's many slick features, keeping track of file movement is not one of them. If you have a few files in a book and you move one of those files from its current folder location, the book file no longer is able to find that file because the original path is the only location that is stored in the book file.

Back to Basics

Cross-references to moved files will not work after the path to the source information is lost.

Figure 7.7 shows what a book file list looks like if the path to a single file is broken in any way. Notice the icon next to the filename, "walking.fm", changed to a generic question mark icon. That's a sign that the book can no longer locate a file for one reason or another. If you were to double-click on that file in the list to open it, the message shown in Figure 7.7 appears.

Figure 7.7. The Filename icon for files that cannot be found.

You can avoid the lost file problem if you move individual files from their original location to another by doing the following:

  1. Manually delete the original filename from the Book File window.

  2. Add the filename (in its new location) to the book file.
Renaming Files in the Book List

One of the best ways to rename files that are included in a book file is from the Book File window. Alternatively, you have the option of changing the filename from the file folder location or using Save As from the document's File menu. Changing the filename from the file folder produces the same result as moving the file location, which was previously discussed. If you use Save As, you have to delete the original filename from the Book window and add the new filename.

Instead, rename files from the Book File window. You'll enjoy the following advantages that are not produced when renaming files using the other discussed methods:

  • The filename is changed in both the book list and on computer disk (hard drive).

  • Cross-references, hypertext links, and text insets throughout each file included in the book update based on the new filename information.

To rename a file from the Book window, follow these steps:

  1. Click once on the filename that you want to rename.

    The filename is highlighted.

  2. Select Edit > Rename File.

    A marque appears around the filename that you selected in the list (see Figure 7.8).

    Figure 7.8. The Rename File from Book window.

  3. Type the new filename and then press Return or Enter (or click elsewhere in the list).

    An alert message appears that displays information about additional updates FrameMaker can perform behind-the-scenes based on the filename change. These changes include updating cross-references, hypertext links, and text insets to reflect the new filename, as well as the filename change to disk.

  4. Click OK.

    FrameMaker makes those changes displayed in the alert message.

Tip

Attention Windows users: You can right-click the mouse to get floating menu selection.

If you have a large number of files, cross-references, hypertext links, and text insets throughout the book, this operation might take a few minutes to update. Be patient while your computer does the work.

The Dreaded Error Message

One of the biggest problems you might run into while performing this operation is the alert message that begins with "Some book components can't be opened or can't be saved." This happens because FrameMaker internally opens each file contained in the book to introduce the changes that have been discussed. If one of those files has a problem, FrameMaker cannot internally open the file and, hence, the alert message appears. Here are a few reasons why this might happen:

  • Imported graphics or other reference files are missing (for any reason).

  • Fonts are unavailable for a particular file.

If this happens to you, don't dismay. First, open all the files in the book (or at least the files causing the problem). Rename that file from the book list. Because the files are already open, FrameMaker can then update each file without running into error messages. When you open each file individually, you can see any error messages and bypass them.

Renaming the Book File

As you fill up the Book File window with document files and generated files such as lists, you might decide to change the name of that book file to something more meaningful. Changing a filename is an effortless task that you have no doubt done numerous times for other files. Although it's also effortless to rename a book file, you must be aware of a few quirks.

The least problematic method to change the name of a book file is to first open the folder that contains the book file. Click the name of the book file to make it editable, type the new name, and press Enter or Return.

Here's a question: What happens if generated files are part of the book list, contain the default name (same name as the book file, such as runguide.book or runguideTOC.fm), and you use the Save As method to change the book's filename?

As you learned, when adding any type of generated file to a book, that file has the same name as the book file but a different suffix. For example, if your book file is named runguide.book, the table of contents is runguideTOC.fm, and a list of figures is called runguideLOF.fm.

Take a look at what happens if you use Save As to change the name of the book file, using the example of runguide.book. Suppose that you change the name to runningstart.book. Then the table of contents' name in the list automatically changes to runningstartTOC.fm. However, that has nothing to do with the original table of contents you created and saved to disk. Only the name in the list changes, just as if you added a new table of contents to the book file. In fact, if you double-click on this new filename, you see the "File does not exist" error message. If you end up in this situation, you need to import the formats from the table of contents that you previously created and saved to disk (if it has already been structured and formatted) in order for this new table of contents to look correct both in structure and format.

On the other hand, if you change the name of the table of contents to something other than the original default name of runguideTOC.fm, the name of that table of contents in the book list will not change when you use Save As to rename the book file to runningstart.book.

Take a look at how that would work. If you have runguide.book, and therefore runguideTOC.fm, first change the name of the table of contents to runTOC.fm from the Book window. Now rename the book file using Save As. The runTOC.fm remains as it is and you avoid the problem altogether.

Opening, Closing, Printing, and Saving Files

The Book File window is the place where you manage and organize your files. Therefore, the most efficient way to open, close, print, and save files included in your book is from the Book File window.

Take a quick look at the alternative. Suppose that you want to print each file included in the book. You could open each file individually from the disk and print each one. Although that works fine for a couple of files, it's an astronomical undertaking when you work with 20 or 30 files that comprise a book. Or, suppose that you want to open the first 10 files that make up the book. You could search for the filenames of those document files and open each one individually, or you could work from the Book window and accomplish the same task in less time.

The following options are performed with the book file:

  • Open. Double-clicking a single file in the Book window opens it. Alternatively, click once on the file and press Enter. To open all the files at once, hold down Shift and select File > Open All Files in Book. To open several, but not all the files, select the files that you want to open and press Enter.

  • Close or Save. With one or more files open, hold down Shift and select File > Close All Files in Book or Save All Files in Book. If you use this method to save your files, you get an added bonus in that the book file is also saved.

  • Print. Use one of two methods to print. From the Book list, select the files that you want to print, and then select File > Print Selected Files. Or, to print the book, Select File > Print Book.

Tip

From the book file list, Shift-click for multiple consecutive selections, and Control-click for multiple, non-consecutive selections.

Going Bookwide

After the document and generated files are collected in the Book window, you can experience this collection as one unit rather than individual parts. This is just one area where FrameMaker really distinguishes itself from the "other guys."

You'll appreciate harnessing this power to make large-scale changes, such as View or Format settings, to one or more selected files or perform a spell check and find/change to some or all files right from the Book window.

If you manage a large number of documents that comprise a book, paging through the book from the first page to the last, without having to physically open individual files, is just another feature that you can enjoy.

This section explores some of the tasks that you can perform to all the files and discover how to use these effectively for one or more selected files in the book. I don't go into detail on individual commands, such as Spelling Checker, but rather how to use the command with a book file. After you understand how to use these commands within a book file, you can transfer that knowledge to using any of the book-wide commands (although every one of these isn't reviewed).

Moving Around the Collective Document

Among the many tasks included in the document production process is checking and rechecking each page for content and formatting accuracy. After any number of files is included in the book list, you can page through the entire book from beginning to end just by using the Page Down key on your keyboard or the arrows located at the bottom of the FrameMaker document window. From the book file, here's what you can expect:

  1. Click once on the first file in the book list, and press Enter or Return (or double-click the filename).

    The first file opens.

  2. Use the arrows to page through to the end of the first-opened document. Browse the document using any method with which you are comfortable. When you get to the last page, use the Page Down key on your keyboard, or the Page Down arrow in the FrameMaker document window.

    If you began this exercise with files in the book closed, once you reach the last page, you are prompted to open the next document in the book list (see Figure 7.9).

    Figure 7.9. The Open Next File window.

    If the next document in the book list is already open, no message appears. The next page (which is the first page of the next document) is displayed.

  3. Click Yes to proceed to the next document in the book list (if that document was closed).

    The next document in the list opens. If there are any missing graphics or unresolved cross-references, you are prompted in the usual manner.

Find and Find/Change

If you want to perform a Find, or Find/Change, you have the option to search across selected files in a book, or the entire book. The files on which you plan to perform the Find/Change do not have to be open when you initiate this command:

  1. Select one or more files in the Book window.

    The selected files are highlighted.

  2. Select Edit > Find/Change.

    The Find/Change window appears.

  3. Select the Selection radio button next to Look In (see Figure 7.10).

    Figure 7.10. The Find/Change window for a book file.

    The Selection radio button is highlighted. The Find/Change is performed on the files that you have selected in the book list, whether it is one file or several. Each selected file opens, and you can use Find/Replace as you always do.

If you plan to use Find/Replace on all the files in the book, just select the Book radio button, which is located next to Look In. Regardless of how many files you select in the book file list, the search is conducted throughout the entire book, beginning with the first file.

Spelling Checker

Spell-checking all the files in a book is a breeze. Using the Spelling Checker as you normally would:

  1. Select one or more files in the Book window.

    The selected files are highlighted.

  2. Select Edit > Spelling Checker.

    The Spelling Checker window appears.

  3. Select the Selection radio button under Check (see Figure 7.11).

    Figure 7.11. The Spelling Checker window for selected files in a book.

    The Selection radio button is highlighted. The Spelling Checker is performed on the files that you selected in the book list, whether it's one file or several files. Use the Spelling Checker as you normally do for each file.

Tip

Alternatively, you can spell-check all the files in a book by selecting the Book radio button instead.

You get the benefits of spell-checking your book even when you're not initiating this command from the Book window. Suppose that you have a book file open in the background, and you have opened one of the document files in the list and are viewing the body pages of that document. If you decide to spell-check this file, you will see the option to check the Book, Document, or Current Page in the Spelling Checker window (see Figure 7.12), even though you are in an individual file that happens to part of the book that is currently open.

Figure 7.12. The Spelling Checker option for the entire book.

Changing the View Options

Among the many handy features for FrameMaker book files is the ability to change the View options for one or more files included in the book. Here's a simple example: Say that you are working in a book file that contains 20 files, all with text symbols turned off. Suppose that you want text symbols turned on in each of those files. You could open each file and make that change. But that's tedious, because there are so many files. To change your View options the easy way, follow these steps:

  1. Select the files in the book list that you want to change.

    The files are selected.

  2. Select View > Show Text Symbols.

    Text symbols are turned on for all the selected files in the list. If some of the selected files already have text symbols turned on, the text symbols remain on.

The next time you open each individual file, the text symbols are turned on.

Importing Document Formats

While in a book file, File > Import > Formats offers the opportunity to import formatting information from a FrameMaker template (or any FrameMaker file) to one or more files included

in the book. This is especially helpful if you decide to make formatting changes that must be introduced in each file in the book. You can make those changes to one FrameMaker file and import selected formats to all the files at once.

Use Import Formats as you always do to import one or more formatting selections:

  • Paragraph formats

  • Character formats

  • Page layouts

  • Table formats

  • Color definitions

  • Documents properties

  • Reference pages

  • Variables definitions

  • Cross-reference formats

  • Conditional text settings

  • Math definitions

Keep in mind that importing formatting information is not always a magic bullet. FrameMaker merges formatting information into each individual document that you select. If formatting information is the same (for example, a paragraph tag has the same exact name), that information overwrites current information. You might have to go into each file and correct any formatting faux pas that can happen during an Import Format.

It's time to examine the steps required to import formatting information to one or more files in your book:

  1. From the Book file, select only those files to which you want to import formatting information.

    The files are selected in the list. In this example, only walking.fm, jog.fm and run.fm are selected (see Figure 7.13). runguideTOC.fm isn't included in the import formats update.

    Figure 7.13. You can import formats to selected files in your book.

  2. Select File > Import > Formats.

    The Import Formats window appears.

  3. Select the source document from the Import from Document drop-down list.

    The source document is selected. This document contains the formats that you want to import into other files included in the book. The source document must be open in order to show up in the Import From Document drop-down list.

  4. Click a check box next to formatting information that you want to import into documents.

  5. Click Import.

    The selected formatting information imports into all the selected files in the book list.

Back to Basics

If a check mark appears next to an item that you do not want to import, just click once on that check box to clear the check mark.

Depending on how many, and how large each selected file is, this procedure can take a few seconds or a few minutes. During the import procedure, the status bar of the Book window offers a glimpse of the current update status.

How Numbering Works in a Book

To start the numbering discussion, you first need to understand one primary rule about numbering in book files: Numbering at the book level, that is, changing the settings of individual files from the Book window, always overrides numbering settings that were introduced in an individual file. With that said, it's time to delve in and unravel the mysteries of Numbering Properties at the book level.

Note

To learn more about creating and using automatic numbering in individual files, see Chapter 3.

Overview of Numbering Properties

Document numbering properties, whether at the individual or book level, are made of six components: volume, chapter, page, paragraph, footnote, and table footnote. Each of these components offers a subset of properties to control various settings unique to each component.

Back to Basics

From a book file, select Format > Document > Numbering to access Numbering Properties.

The following is a brief explanation of each of these. To learn more detail, see page 47.

Volume

Click on the Volume tab in the Numbering Properties window to access the Volume settings for a particular document. You need this property only when paragraph autonumber formats, headers or footers, cross-references, or page numbers include the <$volnum> Building Blocks.

Chapter

Click on the Chapter tab in the Numbering Properties window to access the chapter settings for a particular document. You need this property only when paragraph autonumber formats, headers or footers, cross-references, or page numbers include the <$chapnum> Building Blocks.

Page

Click on the Page tab in the Numbering Properties window to access its settings. Use this property to set the starting page number, page numbering style, or a particular document to continue page numbering based on the previous file.

Paragraphs

Click on the Paragraphs tab in Numbering Properties to access its settings. You use this property only when document files contain paragraph autonumber formats that include the placeholder or counter Building Blocks <n> and <n+>, and their counterparts in other numbering styles. If you use a combination of <$chapnum> and these placeholder Building Blocks, you must use the Numbering Properties settings for both Chapter and Paragraph.

Footnote

Click on the Footnote tab in Numbering Properties to change the numbering style of footnote, set a particular number, start over, continue numbering from the previous file, or read from the original file settings.

Table Footnote

Click on the Table Footnote tab in Numbering Properties to access the setting that enables you to either change the numbering format style (such as numeric, alphabetic, Roman, or custom) or read from the original file settings.

Book Level Numbering Example

Numbering settings at the book level provide information about how individual files relate to the file that came before it. For example, if a file is second in the book list, does the page numbering continue based on the previous file's last page, or does the page number start over again at page 1? If this same file has a chapter number, does the chapter number automatically increment based on the previous file chapter number, or does this chapter number begin with 1 or some other number? Consider these items when you set up files that are contained in a book.

After you have a book file in place, with included document and generated files, you can see the overall organization and flow of the files at once (see Figure 7.14). To illustrate how numbering works at the book level, you must explore the setup of these files in the Book window.

Figure 7.14. The overall organization of files in a book.

Take a look at your book file to determine a plan of attack. What do you want to happen, with regard to numbering, in these files? Using the example, review the plan illustrated in Figure 7.15 for how numbering should work in this book, with regard to chapter, paragraphs, and page numbers.

Figure 7.15. How numbering should work for files in a book.

Setting Up Each File in the Book

After you determine an overall plan, the next step is to set up various numbering settings for each file. The following sections break down this exercise by filename, and discuss each file's requirements and setup at the book level. To set up each file in the book, click once on the filename, then select Format > Document > Numbering.

titlepg.fm

titlepg.fm is the first file that appears in the book and contains the title page followed by a blank page. Because no page numbers appear on these pages, nor chapter or paragraph numbering, no specific setup is required for this file.

runguideTOC.fm

runguideTOC.fm is the second file that appears in the book and uses small Roman numeral page numbering. This file follows the title pages, which, although not numbered, take up two pages. Therefore, the table of contents begins on page iii, continuing where titlepg.fm left off. Figure 7.16 shows the Numbering properties for the table of contents.

Figure 7.16. The Numbering Properties for the table of contents.

walking.fm

walking.fm is the third file and the first chapter in the book. This file uses Arabic numerals, begins on page 1, and uses both the chapter number and paragraph numbering, both starting at 1. Therefore, you must set up the Chapter, Paragraph, and Page Numbering properties, as shown in Figure 7.17.

Figure 7.17. The Numbering Properties for the first chapter file.

jog.fm

jog.fm is the fourth file and the second chapter in the book. This file uses Arabic numerals, continues page numbering following the last page of the previous chapter, and uses both the chapter number and paragraph numbering. The chapter number increments from the chapter number in the previous file, while the paragraph numbering begins at 1.

Tip

If you use chapter-based page numbering—that is, each chapter starts the page numbering over at 1, as in 2-1, 2-2, 2-3—you would set the First Page # to 1.

Therefore, you must set up the Chapter (refers to 2), Paragraph (refers to the number 1 in subhead, figure, and table), and the Page Numbering properties (see Figure 7.18).

Figure 7.18. The Numbering Properties for the second chapter file.

run.fm

run.fm is the fifth file and the third chapter in the book. This file uses Arabic numerals, continues page numbering following the last page of the previous chapter, and uses both the chapter number and paragraph numbering. The chapter number increases by 1 based on the chapter number in the previous file, while the paragraph numbering begins at 1.

Therefore, you must set up the Chapter (refers to 3), Paragraph (refers to the number 1 in subhead, figure, and table captions) and the Page Number properties, as shown in Figure 7.19.

Figure 7.19. The Numbering properties for the third chapter file.

runguideIX.fm

runguideIX.fm is the sixth and last file that appears in the book. This file uses Arabic numerals and continues page numbering following the last page of the previous file. No chapter or paragraph numbering is used in this file. Figure 7.20 shows the Numbering properties for the index file.

Figure 7.20. The Numbering properties for the index file.

Tip

If the index has its own page numbering, such as small Roman numerals beginning with number i, you must set up the First Page # to 1 and the Format to Roman (xiv).

Updating File Information

So far in this chapter, you have seen that a book file brings together all the necessary ingredients that make up a book in FrameMaker. You discovered how to perform a wide range of commands on files from the Book window, and how to use Numbering Properties for individual files in relation to the book as a single unit.

Back to Basics

When you update book file information, individual files do not need to be open.

After all this work, the final step is for FrameMaker to scan all the files included in the book and update file information, such as numbering and cross-references, and create or refresh generated files, such as the table of contents or list of figures with the most recent information.

You can perform this update at any time. You don't have to wait until you have included all the files in the book. However, you might want to update the book information as you add each file to the book. Why is this a good idea? Have you noticed that, while you work on individual files that are not part of a book and include numbered chapters, that each file might begin with the number 1? This is a common occurrence if you have started with a new FrameMaker template that hasn't been updated as part of a book and, therefore, is numbered as Chapter 1.

You might also want to review an updated table of contents or another list as you work through the chapters in your book file. If you rearranged or changed the Numbering properties for any files, you need to update the book file in order to incorporate these changes throughout each file included in the book.

When you are ready to update the information, here's how to do it from the Book File window:

  1. Select Edit > Update Book.

    The Update Book window appears.

  2. Select items in the list that you want to update throughout the files included in the books (see Figure 7.21).

    Figure 7.21. The Update Book window.

    The selected items are the only information that are updated after you click the Update button. If you included generated files, such as the table of contents, index, or list of figures in the book list, these appear in either the Generate or Don't Generate list. If generated files show up on the Generate list and you checked Generate Table of Contents, Lists, and Indexes, these files are updated with the current information. If the filenames show up under the Generate list, and you do not check Generate Table of Contents, Lists, and Indexes, these files are not updated with the latest information.

    Tip

    Use the Update icon as shown in the Book File window.

  3. Click the Update button after you finish selecting the items in the Update Book window.

    The book file begins to update the selected information for the book components. This can take a few seconds or a few minutes, depending on the size of each file and the type of information that's being updated in each file. The status bar in the Book window provides information about each operation as it's performed.

Solving Book File Errors

Updating a book file is easy! The errors that can occur, however, require detective work on your part. If errors occur, you need to solve them in order for the information in each file to be properly updated with the latest information. Book file errors are a common occurrence.

A separate FrameMaker window is created with a list of each error that occurred during the book update. Figure 7.22 shows an example of a Book Error Log window. The information is presented in an organized fashion, with the date, name of the file in which the error occurred, a list of errors in each particular file, and hyperlinks to the file, or the error itself if the error is an unresolved cross-reference.

Figure 7.22. The Book Error Log window.

This section explores the types of errors that can occur during a book update. Here you can discover how to solve each type of error.

Couldn't Open File

If any particular file in the book list couldn't be opened, you see the Couldn't Open File message. As seen in Figure 7.23, the name of the file appears in the Book Error Log. Why does this happen? Here's a list of reasons:

Figure 7.23. The frustrating Couldn't Open File error message.

  • Unavailable fonts. If the file in question uses unavailable fonts, FrameMaker cannot open this file in order to perform the update. Solve this problem by opening the file first and solving the missing font problem. Then save and close the file. Or, open the file and leave it open during the update process if you want to solve the font problem another time.

  • Saved in older version of FrameMaker. You see this message if the problem file was saved in a version of FrameMaker other than the current version in which you are working. To solve this, open the file and save it in the current version of FrameMaker before you update the book file.

  • Unable to locate file. You are met with this message if any file has been moved and not added to the book file from the new location, or if a filename has been changed from a location other than the Book File window. To solve this, delete the old filename and add the file again with its new name and/or location.

Inconsistent Settings

A number of inconsistency settings can occur during the book update process. Suppose that the first file in the book list has all conditional text showing and the second file in the book has some conditional text hiding. Those different settings are inconsistent to FrameMaker.

Inconsistency messages mean that certain command settings in a particular file are different from those same command settings for the previous file in the book list. This error message doesn't disrupt the updating of information in files. Its purpose is to serve as a reminder to you that these settings might differ from file to file in your book. If you are not using conditional text in document files, but the settings are different from file to file, you are met with the inconsistency message. In other words, don't be fooled into thinking that because you are not using conditional text this ought not happen. It will happen, and you need to fix it.

Inconsistency settings relate to conditional text or color settings. The easiest way to solve this annoying problem is to make these settings the same for each file in the book. You can either change the file settings individually in each file or choose one file's settings and import the formats from that one file into all the files in the book.

After all the files have the same setting with respect to conditional text and color definitions, the message disappears.

Inconsistent Numbering Properties

If you see the Inconsistent Numbering Properties error message, it reminds you that the Numbering properties you set up while in an individual file are different from the Numbering Properties for that same file at the book level. This error message does not affect the update of information in the book. As you learned previously, book file settings override individual file settings.

If many files in your book contain inconsistent Numbering properties (book level versus individual file), you can leave this alone and just check the box on the error message window "Skip Remaining Inconsistent Numbering Properties Messages" (see Figure 7.24). For each subsequent file with this type of inconsistency, the message doesn't appear again.

Figure 7.24. The Inconsistent Numbering Properties message.

If you want to make each file consistent with its book-level setting, you must open each file and change the Numbering properties to match those of the book-level settings.

Unresolved Cross-References

You might meet the Unresolved Cross-References error message if cross-references in files are unresolved for any number of reasons. The Book Error Log window provides a list of each file that contains an unresolved cross-reference with hyperlinks to each one.

Unresolved cross-references can happen because of the following reasons:

  • A cross-reference marker was deleted from the source information.

  • The source information is part of conditional text that's hidden.

  • The name of the source file changed.

  • The location (path) of the source file changed.

You must solve unresolved cross-references in order to continue with book updating. Read "Unresolved Cross-References" on page 150 in Chapter 5 for details.

Summary

In this chapter, you learned about working with a collection of document files as one unit. FrameMaker gives you a powerful array of features to manage and organize files included in a book. You learned some techniques for adding and arranging files, as well as working with the files as a unit for commands such as Spelling Checker and Find/Change. Some special techniques included specifying number settings for individual files in the book in relation to each other, and creating a single table of contents or another list based on the collection of files.

If you plan to create book files, keeping the individual files organized on a computer disk is an important part of the project and should be determined first rather than last. This saves you time later.


Chapter 8

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.


Chapter 9

Chapter 9. Indexing

  • How Indexing Works
  • Indexing Decisions
  • Creating Index Entries
  • Changing Existing Index Entries
  • Creating an Index List
  • Adding Prefixes to Page Numbers
  • Working with Static Text
  • Working with an Index Template
  • Summary

Indexes have one chief purpose in documents: to provide the reader of a document with a systematic arrangement of key concepts and terms that enable the reader to locate specific information in that document. An index typically serves as a guide, extracting particular words or subjects from the document content and presenting that information in an alphabetized format, with page(s) on which each item is mentioned.

A good index can make or break a book. As the author, you might have the urge to index too many words or not enough. With multiple words referring to one concept and one word referring to multiple concepts, well, you can see how complicated indexing can get.

How you go about selecting key terms and concepts for indexing, as well as the formatting style used, is your choice. In this chapter, you discover how to make FrameMaker's indexing features work for you. You learn how to create a variety of index entries, as well as how to control the structure and format of the index list after it's created. You also learn how to solve some common mishaps along the way.

How Indexing Works

An index is a generated file, which is a term you're probably familiar with by now. An index file does not exist until FrameMaker generates, or creates, it based on information that you have designated throughout the contents of source documents to be extracted into the index list.

In this section, you examine these indexing features:

  • Selecting what's included in the index

  • How index entry information is structured

  • How index information looks

As this chapter proceeds, you will see how to use index markers to identify or input text that will appear in the index. In addition, you see how to use punctuation in index markers to determine subordinate levels of information, as well as alphabetical sort order.

After information—in the form of concepts, terms, and words—is extracted into the index, you can either use the default structure and format provided by FrameMaker to display this information, or you can enhance and build upon the default format.

One great advantage of generated files, like an index, is that when information such as page location or index entries change, you can update the index with new information from source documents, replacing the old information. After you determine the look and format of the index, updated source information flows into the format you already created so you don't have to re-create the wheel.

Selecting What's Included in the Index

Index markers are inserted throughout your document to identify the concepts, terms, and words that you want included in the index. If you were to create an index before even one index marker was placed in a document, that index would be created with no index entries.

Understanding Index Markers

FrameMaker offers a variety of marker types that each perform a specific job. Each marker in FrameMaker looks exactly the same after it's inserted into text. It's the assigned marker type and what's inside each marker that makes them unique from each other.

Back to Basics

To access the Marker window, select Special > Marker.

Select marker types from the pop-up list in the Marker window. You can use a predefined marker type, such as Index, or create a new one. Later in this chapter (in the section "Working with Multiple Page Number Styles" on page 294), I discuss how and why to create a custom marker type for indexing.

Here's how index markers work for index entries: The Index Marker window is like a container that holds the information that will be extracted into the index each time the index is generated. After the index marker exists, you cannot see or edit this information unless you look inside that particular index marker's window.

When information is extracted from each index marker, the page location accompanies this information in the index list, although the page location is not displayed inside the index marker.

Determining Marker Types for the Index

After you insert index markers into documents, the next step is to set up the index to extract the information from the marker type you selected for index entries. With so many different marker types available in FrameMaker, you must choose which of these you want to include in the index. This is done through the Set Up Index window, as shown in Figure 9.1. You are met with this window when adding an index file to a book file or creating a standard index from a single file.

Figure 9.1. The Set Up Standard Index window.

Back to Basics

To add an index file, select Special > Standard Index or Add > Standard Index from a book file.

For example, if you used the index marker type for index entries, you'll select Index as the marker type to include in the index. If you created a custom marker type, say Index2, and use Index2 for index entries, you must select Index2 as the marker type to include in the index.

You are not limited to one marker type selection. As you'll see later in this chapter (in the section "Working with Multiple Page Number Styles" on page 294), you might need to use both index and another marker, such as Index2, for index entries in documents. In this case, you must select both marker types to include in the index. Then FrameMaker extracts the information contained in both Index and Index2 markers for listing in the index.

Back to Basics

Marker types are listed whether or not they are actually used in each document.

Table 9.1 shows the Set Up Standard Index commands and a description of their usage.

Table 9.1. Set Up Standard Index Commands

Command

Description

Suffix

Denotes the file type and should not be mistaken for the filename extension. Using the index example, the suffix IX becomes part of the filename as in FilenameIX.fm. For a standard index, IX is the default suffix, although you can change it in this window before clicking the Set button.

Add File

This feature is activated when you add an index from within a book file. You can then select whether the index will be added before or after a particular file in the book list. You can always rearrange the order of files in a book later. To learn more about working with a book file, see Chapter 7.

Include Markers of Type

Moves the marker type to this list when you want to include its contents in the index list. For a standard index, Index is the marker type that you'll use to include index entries. If you create a new marker type for index entries in the marker window, then the new marker type will show up in this list and you can use that one in addition to an existing marker type.

Don't Include

Displays a list of all marker types included in the source document. If you are working with a book file, this list includes marker types from all the document files contained in the book.

Move marker types between lists by double-clicking on the marker type name or clicking once, then clicking on the left or right arrow. Move all tags at one time from one list to the other with Shift-click on arrow.

How Index Entry Information Is Structured

The way in which index entry information is arranged in the index list is determined by a structure that's located on the reference page of the index file. If you are not using a template, the first time an index is generated or created, FrameMaker's default structure come into effect. After the index is created, you can make changes to the index structure to fit your needs.

The index reference page contains Building Blocks that represent various parts of source information that are displayed in the index. For example, Table 9.2 shows the Building Blocks that represent the order in which index entries get sorted. In this example, which also happens to be the FrameMaker default, index entries that are symbols appear first, as indicated by the <$symbol> Building Block showing first. Symbols are followed by numeric entries, as indicated by the <$numerics> Building Block showing second. Alphabetic entries follow as indicated by the <$alphabetics> Building Block showing last in this order.

If you changed the order of those Building Blocks on the reference page, the next time you update the index, the entries in the index list are arranged according to the new order.

Table 9.2. Example of Building Blocks

Building Blocks

<$symbol> <$numerics> <$alphabetics>

What This Means

The order that index entries are sorted is symbols, numbers, alphabetics.

Change Building Blocks

<$alphabetics><$symbol> <$numerics>

Change the Sort Order to

The order that index entries are sorted now is alphabetics, symbols, numbers.

This is a simple example of how information in the index list gets its structure. Many more aspects of the index take their structure from the reference page. More real-world examples are explored later in this chapter.

How Index Information Looks

After you determine what index marker types are included and how information is structured, the final step is formatting the look of the information in the index list. The first time an index or other type of generated list is created, it's plain looking. The most important thing at this stage is to focus on the mechanics of the index list, making certain that it works properly and displays source information as you expect. If it does not, you need to go back to the reference page or index markers in documents and make the necessary adjustments.

When you are ready, format the index using the Paragraph Designer, just as you would any other paragraphs in documents. Notice that, after the index is created, some new paragraph tags are included in the Paragraph Catalog. Each has a special suffix, IX, added to the paragraph tag name, such as Level1IX. This suffix means that each time you update the index, any text tagged with a paragraph tag name ending in IX is replaced with new source information, regardless of whether or not the source information has changed since the last index update.

Each paragraph tag with the suffix IX corresponds to Building Blocks located on the reference page. For example, the paragraph tag

GroupTitlesIX

corresponds to these Building Blocks:

Symbols[\];Numerics[0];A;B;C;D;E;F;G;H;I;J;K;L;M;N;O;P;Q;R;S;T;U; V;W;X;Y;Z

located on the reference page. These Building Blocks represent the titles for each grouping that is displayed in the index list, as in symbols, numerics, and alphabetics. If you changed the GroupTitlesIX Paragraph Designer properties, the titles under which each index entry is grouped is displayed with the new Paragraph Designer formatting information.

Indexing Decisions

Before you create an index, you must make some decisions about how information in the index is formatted with respect to the following:

  • Capitalization of headings and subheadings

  • Number of subheading levels

  • Cross-references

  • Alphabetization

Every index entry that appears in the index is a result of marker text that you inserted throughout the document. The way that you choose to enter marker text in the Marker window determines how that index entry is displayed in the index. Therefore, some up-front planning and subsequent decisions save you from going back later to redo marker text that was input inconsistently.

This section discusses key decisions to keep in mind while you index. This is not a guide to the art of indexing, but rather a guide to how some decisions affect indexing as it relates to the world of FrameMaker. Although some examples of marker text are revealed in relation to how index entries are displayed in the index, step-by-step how-to exercises can be found in the section "Creating Index Entries" on page 272.

Capitalization of Headings and Subheadings

You can format headings and subheadings in an index in many ways, with respect to capitalization. Take a look at the three decision examples in Table 9.3. Notice how the marker text is exactly what's displayed in the index. Therefore, if you decide to input marker text in documents, say, using the first initial caps for all entries, and later decide you prefer the no initial capitalization, you have to change all previously entered marker text in order to get that result in the index.

Table 9.3. Heading and Subheading Capitalization Decisions

Decision

How This Looks in the Index

Marker Text

First Initial Cap of Heading

Color Definitions

color libraries 1

Color Definitions:color libraries

model 9

Color Definitions:model

No Initial Cap of Heading

color definitions

color libraries 1

color definitions:color libraries

model 9

color definitions:model

First Initial Cap of Heading and Subheading

Color Definitions

Color Libraries 1

Color Definitions:Color Libraries

Model 9

Color Definitions:Model

As you read through other index formatting decisions, keep in mind that the heading and subheading capitalization decisions hold true in all the other decisions as well. In other words, if you are deciding whether cross-reference index entries are sorted at the top or bottom of a subentry list, you still have to consider capitalization of words in that particular cross-reference index entry.

Subheading Levels

Indexes typically have either one or two subheading levels. As you can see in Table 9.4, the marker text for one subheading level is different from the marker text for two subheading levels. Therefore, if you decide after the fact to change the number of subheading levels in the index, you must do a bit of editing work in previously entered marker text.

Table 9.4. Number of Subheading Levels Decision

Decision

How This Looks in the Index

Marker Text

One Level of Subheadings

Color Definitions

color libraries 1

Color Definitions:color libraries

Pantone 3

Color Definitions:Pantone

Trumatch 4

Color Definitions:Trumatch

Two Levels of Sub-headings

Color Definitions

color libraries 1

Color Definitions:color libraries

Pantone 3

Color Definitions:color libraries:Pantone

Trumatch 4

Color Definitions:color libraries:Trumatch

Cross-References

You've seen cross-references in indexes many times. Cross-references are typically used to point out related terms to the reader. Usually, index cross-references appear in either the top or bottom of a subentry list and often are accompanied by the words "See also." To be consistent, you should decide whether cross-reference index entries always appear at the top of a subentry list or the bottom. As you can see in Table 9.5, the marker text for a cross-reference entry that appears at the top of the list is a little different from a cross-reference entry that appears at the bottom of the list.

Table 9.5. Cross-Reference Display Decisions

Decision

How This Looks in the Index

Marker Text

Cross-Reference First

Color Definitions

see also online color library

color libraries 1

Pantone 3

Color Definitions:see also online color library [Color Definitions:aaa]

Cross-Reference Last

Color Definitions

color libraries 1

Pantone 3

see also online color library

Color Definitions:see also online color library [Color Definitions:zzz]

Alphabetization

You have to make plenty of alphabetization decisions in an index, such as sorting word by word, letter-by-letter, sorting alphabetically after numerics, or vice versa. However, those types of decisions are not all implemented with index marker entries. Concentrate on alphabetization decisions that are implemented using index marker entries. Later in this chapter, sorting methods that are implemented from the reference page are explored in detail.

Table 9.6 shows a typical example of an alphabetizing decision. In this case, an asterisk is an index entry. You can have this index entry show up under the symbol heading, the alphabetized A heading, or both of these. As you can see, the marker text for each of these decisions is different.

Table 9.6. Alphabetization Decisions

Decision

How This Looks in the Index

Marker Text

Sort Symbol Entry Under Symbols

Symbols

* (asterisks) 9

* (asterisks)

Sort Symbol Entry Under Alphabetical

A

* (asterisks) 9

* (asterisks)[asterisks]

Sort Symbol Entry Under Symbols and Alphabetical

Symbols

* (asterisks) 9

A

* (asterisks) 9

* (asterisks)[*;asterisks]

Creating Index Entries

Now that you have an idea of how index marker entries work to produce an index in FrameMaker and some important decisions that you ought to plan for before starting, it's time to get started creating index entries.

Once you get acquainted with the various types of index entries that are available, you will feel right at home including them in documents. In this section, we explore the following:

  • Markers Understand the role of index markers in source documents.

  • Simple index entries Learn the methods for including index entries that don't require extra typing, easy ways to select text as an index entry, and the widely used method of typing text for index entries.

  • Multi-level index entries Learn how to include subentries under a first-level entry heading as well as how to avoid mistakes that are common to this method.

  • Complicated index entries Learn how you can enhance index entries by changing the sort order, including cross-references in index listings, suppressing or restoring page number references, and including page ranges in entries. In addition, you'll see how to reduce markers in source documents with multiple index entries and add character formatting to all or part of an index entry.

A Word About Markers

Back to Basics

You can select View > Text Symbols to display markers.

Index entries are contained in markers. Markers are inserted in various locations that you have determined throughout the document. Be aware of markers while you edit documents. If you accidentally delete a marker, index entries contained in that marker are also deleted and, therefore, not included the next time you update the index. It's a good idea to work with text symbols turned on while you edit so that you can see the markers and avoid deleting them.

Another marker annoyance: When you insert more than one marker at the same location, the markers appear as one because they are actually piled on top of each other. Try to avoid inserting multiple markers in the same location. Whenever possible, place multiple index entries inside one marker. For more information on this, see the section "Multiple Index Entries in One Marker" on page 281.

Simple Index Entries

FrameMaker provides the means to create index entries that are very simple to insert in documents. Depending on what you want to index, a simple entry might not even require typing. Now you explore how to input simple index entries and understand some sleight-of-hand consequences.

No Typing Required

The simplest index entry is the entry that doesn't require any typing. Use this index-entry method when there's a single word somewhere in the document that you want to show up in the index on its own. You can't use this method if you want an index entry to be listed as a subentry of a main entry.

To begin this exercise, find a word in your document that you want to have appear in the index:

  1. Place the insertion cursor just before the word that you want to have appear in the index.

    The cursor is inserted immediately to the left of the word.

  2. Select Special > Marker.

    The Marker window appears.

  3. Select Index from the Marker Type pop-up menu (see Figure 9.2).

    Figure 9.2. An example of a no-typing-required index entry.

    Index is the marker type used for this entry. The Marker Text field remains empty.

  4. Click on New Marker.

    An index marker is inserted to the left of the word.

Besides being simple, another benefit of using this index-entry method is if the word to the right of the marker changes, this new information will be automatically updated the next time the index is updated. If you were to type text in the Marker Text field and you wanted to change the word that appears in the index list, then you would have to go into that marker's text to make the change.

Selecting Text for a Marker

You can select text to use as marker text. Use this index-entry method when a word or series of words are together in the document that you want to have appear in the index list just as they are on the document's body page. This method saves you from typing the same information in the Marker Text field.

To begin this exercise, find a word or series of consecutive words in your document that you want to have appear in the index:

  1. Select the word or series of words that you want to have appear in the index.

    The selected text is highlighted.

  2. Select Special > Marker.

    The Marker window appears. The highlighted text is inserted in the Marker Text field.

  3. Select Index from the Marker Type pop-up menu (see Figure 9.3).

    Figure 9.3. The selected text as an index entry.

    Index is the marker type that's used for this marker. The Marker Text field contains the same text as the text you highlighted.

  4. Click on New Marker.

    An index marker is inserted to the left of the first word in the selection.

Tip

Make sure that the selected text does not include a marker of any type.

When you select text using this method, if the text on the document page changes, the index entry in the index does not change the next time the index is updated with new source information. The reason is that when you select the text on the page, which is subsequently captured in the Marker Text field, it's the same as if you typed in the Marker Text field. That marker text is not based on text to the right of it, as you saw previously in marker text that you don't have to type.

Inputting Marker Text

Often, you might find that a particular word in a document's body page does not capture the essence of the concept that needs to be included in the index. Therefore, the previous methods for creating an index entry will not suffice. In this case, and most of the time, you must type in the Marker Text field to include terms of any type in the index. You also use this method to input multi-level entries and control index entry locations in the index list.

Using the example, suppose that the word Alphabetization is not detailed enough information for an index. Suppose the phrase Alphabetization Decisions better describes the concept. You must type the concept term in the Marker Text field.

This method of inputting marker text is common, as you'll see in more-complicated index entries. When you type text to use as an index entry, make sure that you place your insertion cursor at the location where you want to refer the reader. This is where the marker is inserted and thus the page to which the reader is referred.

  1. Place the insertion cursor at the start of the paragraph where you want to refer the reader.

    The cursor is inserted at the beginning of the paragraph.

  2. Select Special > Marker.

    The Marker window appears.

  3. Select Index from the Marker Type drop-down menu.

    Index is the marker type used for this marker.

  4. Type Alphabetizing Decisions in the Marker Text field (see Figure 9.4).

    Figure 9.4. Typing marker text as an index entry.

    The typed text is inserted in the Marker Text field. This is exactly how the index entry appears in the index.

  5. Click New Marker.

    The marker is inserted at the cursor location. The next time you update the index, Alphabetization Decision will be one of the index entries.

Multi-Level Index Entries

Previously, you saw how to create simple index entries that produce a single entry that appears in the index at the first index level. This section looks at how to create multi-level index entries; that is, index entries that appear in the index as a subentry of a first-level entry.

For this example, suppose that you want two subentries or more to appear under one first-level heading in the index. The result might look something like this:

I

Index Entries

Multi-Level 8

Simple 6

Here are the steps required to create one subentry where Index Entries is the first level and the words Multi-Level and Simple are the subentries:

  1. Place the insertion cursor at the start of the first paragraph where you want to refer the reader.

    The cursor is inserted at the beginning of the paragraph.

  2. Select Special > Marker.

    The Marker window appears.

  3. Select Index from the Marker Type drop-down menu.

    Index is the marker type used for this marker.

  4. Type Index Entries:Simple in the Marker Text field.

    The typed text is inserted in the Marker Text field. Index Entries is the first-level heading that appears in the index. The colon (:) indicates a separate level in an index entry. Simple is the subentry that appears under the Index Entries heading.

  5. Click New Marker.

    The marker is inserted at the location. The next time you update the index, this multi-level entry will be included in the index, as shown in Figure 9.5.

    Figure 9.5. Typing multi-level entry marker text.
Creating Another Subentry Under the Same Heading

Typically, you'll have more than one subentry appearing under one first-level heading in an index. Following the example, add the next subentry so that it appears under the same heading:

Note

You can create a third-level entry by using a colon as the level separator—First Level: second level:third level.

First Level

second level

third level

  1. Place the insertion cursor at the start of the paragraph where you want to refer the reader.

    The cursor is inserted at the beginning of the paragraph.

  2. Select Special > Marker.

    The Marker window appears.

  3. Select Index from the Marker Type drop-down menu.

    Index is the marker type used for this marker.

  4. Type Index Entries:Multi-Level in the Marker Text field.

    The typed text is inserted in the Marker Text field. Index Entries is the first-level heading that appears in the document.

  5. Click New Marker.

    The marker is inserted at the location. The next time you update the index, the multi-level entry is included in the index, as shown in Figure 9.6.

    Figure 9.6. Typing multi-level entry marker text.
What Can Go Wrong?

What an excellent question. You must be careful when you insert marker text that refers more than one subentry to a single first-level heading. For example, if you put in an extra space or did not spell the first-level entry portion of the marker text (before the colon) exactly the same for all occurrences of subentries that will appear under that first-level heading, these are displayed as separate entries. Let's explore what will happen.

Suppose that, when you typed the marker text for the second entry, Multi-Level, you used lower-case letters for the words "index entries", rather than uppercase letters as you did for the first entry, Simple.

Figure 9.7 illustrates the marker text and the result. Multi-Level is a subentry but "index entries" is included in the index as a separate entry from Index Entries because the first letters of each word are lowercase.

Figure 9.7. Typing marker text as an index entry. Index

When adding multi-level entries as marker text, you must be careful about typing the characters in exactly the same way for each occurrence that appears under the same first-level heading.

When this type of inconsistency happens, you must go back into the marker text for that particular index entry and correct the problem. See the section "Changing Existing Index Entries" on page 287 to learn various ways to go back into a marker and change the existing marker text.

Complicated Index Entries

So far, you explored simple index entries that appear as a single-level entry in an index and multi-level index entries that appear as subentries under a first-level heading. This section explores various methods to enhance marker text with Building Blocks to control the form and location of index entries in the index list.

For example, you might want to control the sort order of particular index entries, or suppress page numbers and add character formatting.

Sort Order

Usually, index entries are sorted in a particular order. For example, indexes typically list symbols, then numbers followed by alphabetical terms. Therefore, if you list a numerical entry, that entry appears under the numerical headings. You might want to list a numerical entry under its alphabetical letter instead, as if it were spelled out.

Suppose the year 1900 is an index entry. Without any special controls in the marker text, this entry appears under numerics in the index. Use a special sorting Building Block and you can change how this number is sorted in the index to appear under the letter N instead, as shown in Table 9.7. Notice how you can control this entry to appear under both numerics and the letter N.

The control features are enclosed in the square brackets. Brackets indicate special sort orders for an entry. After you include brackets in marker text, the information inside the brackets is used for sorting and not the marker text itself. If you want index entries to appear under more than one sorting category, use a semicolon (;) in between sorting information, as shown in the last marker text example in Table 9.7.

Table 9.7. Sort Order of Individual Index Entries

Marker Text

Appearance in Index

1900

Numerics

1900 56

1900[Nineteen hundred]

N

1900 56

1900[1900;Nineteen hundred]

Numerics

1900 56

N

1900 56

Cross-References

You've seen cross-references in indexes many times. Cross-references are used to refer the reader to related information that appears elsewhere in the index. Typically, cross-references look like this:

C

Color Definitions

Pantone 3

Trumatch 5

See also online color library

When you insert cross-reference index entries, you must use the sort order Building Block, brackets ([]), in order to force that cross-reference entry to the top or bottom of a subentry list. If you do not do this, the index entry sorts just as everything else in the list and looks like this:

C

Color Definitions

Pantone 3

See also online color library

Trumatch 5

In addition, you are using another Building Block to suppress the page number of this entry.

Suppressing Page Numbers

To suppress a page number, use the Building Block before the marker text of the entry for which you want to suppress the page number.

Sort orders are specified in square brackets. Because this particular cross-reference entry is a subentry of Color Definitions, the sort order in between the square brackets must also include the words Color Definition; this is the first-level entry that you want the cross-reference sorted under (see Table 9.8). Sort order Building Blocks are always inserted at the end of marker text.

In this case, the zzz indicates that you want this entry to appear last in the list under Color Definitions. In the same way, aaa indicates that you want this entry to appear first in the list under Color Definitions.

You could use zz instead of zzz. However, if an entry in that same list begins with zzy, that entry beginning with zzy would appear last in the list instead.

Table 9.8. Suppressing Page Number Building Block in Index Entries

Marker Text

Appearance in Index

<$nopage>Color Definitions:see also online color library [Color Definitions:zzz]

C
Color Definitions
See also online color library
Pantone 3
Trumatch 5

<$nopage>Color Definitions:see also online color library [Color Definitions:aaa]

C

Color Definitions

See also online color library

Pantone 3

Trumatch 5

Multiple Index Entries in One Marker

You might wonder where exactly in a document an index marker, such as a cross-reference, is inserted. You could place this type of index marker anywhere because it has no page reference with it. Using the example, a more logical place for this type of index marker is combined with some other marker text that is also a subentry under Color Definitions.Thus, you reduce the number of markers by creating a single marker that includes multiple index entries.

Tip

Marker text is limited to 255 characters.

Regardless of what type of index entry you are creating, you can combine more than one index entry into one marker. You probably noticed that, with many index entries, a multitude of markers are inserted throughout text in documents. Combine index entries into one marker whenever possible to cut down on the number of markers in your documents.

Begin with the combination of cross-reference marker text and another subentry in that same first-level heading. The semicolon (;), as shown in Table 9.9, separates more than one entry, just as if you placed the marker text in another marker. In this example, the marker text is for the "Pantone" and "See also" subentries in the index.

Table 9.9. Multiple Index Entries in One Marker

Marker Text

Appearance in Index

Color Definitions:Pantone;Color Definitions:see also online color library [Color Definitions:zzz]

C
Color Definitions
Pantone 3
Trumatch 5
See also online color library

What happens if you combine three sets of marker text into one marker? Hopefully, you have input all the information correctly and it displays as it should in the index. Take a look at some of the anomalies that can happen if you do not.

Using the same example, suppose that you decide to add yet another marker text entry following the second marker text entry in that marker, as shown in Table 9.10. You would do this because perhaps another term or concept is in that same short paragraph that must be listed in the index.

Table 9.10. Multiple Index Entries and Page Number Suppression

Marker Text

Appearance in Index

Color Definitions:Pantone;Color Definitions: see also online color library [Color Definitions:zzz];Color Views:Defined

C
Color Definitions
Pantone 3
Trumatch 5
See also online color library
Color Views
Defined
Restoring Page Numbers

Notice that the index entry in Table 9.10, Defined, has no page number. Looking at the marker text, you see that the Building Block was used in the second index marker text. Therefore, all entries to the right have no page number when they're displayed in the index. In this case, you must use another Building Block to restore the page number for the next entry in the marker text.

The Building Block <$singlepage> restores the page number for multiple entries where the page suppression Building Block,, was used. Table 9.11 shows how to include the Building Block <$singlepage> to restore the page number for the Color Views:Defined index entry.

Table 9.11. Building Block to Restore a Page Number in Index Entries

Marker Text

Appearance in Index

Color Definitions:Pantone;Color Definitions: see also online color library [Color Definitions:zzz]; <$singlepage>Color Views:Defined

C
Color Definitions
Pantone 3
Trumatch 5
See also online color library
Color Views
Defined 3

If you want to avoid using both of these Building Blocks in one marker, consider placing marker text entries that use the Building Block last in the series of entries.

Typing Special Characters

Thus far, you have seen that index entries contain certain characters in the Building Blocks that are used to control certain aspects of the index entry. Specifically, these are colon, semicolon, square bracket, and angle bracket. What can you do if you need to include one of these special characters in the index entry? If you type a colon, you create a multi-level index entry. If you type a semicolon, you create another index entry.

To include any of these special characters in index entries, type a backslash (\). Because the backslash is used to indicate that the character that follows is part of the index entry and not a control Building Block, you also have to use a preceding backslash to include a backslash in an index entry.

Table 9.12 shows how to create a symbol index entry. In this example, the symbol index entry is the backslash (\) and is located on page 3. In order to create this entry, you must precede the backslash that you want to have appear in the index with a backslash to indicate that it's an entry and not a control character.

Table 9.12. Typing Special Characters

Marker Text

Appearance in Index

\\

Symbols

\ 3

Page Ranges in Entries

Another common technique used in indexes is to use page ranges. This is useful when index information spans more than one page in a document.This might look like

Color Definitions

Pantone 3-5

Trumatch 5

Note

To learn how to automatically include page range information, see Table 9.14 on page 292.

Page ranges in index markers are manually created. In other words, you have to insert an index marker at the beginning of the information and another at the end of the information. Each marker uses its own Building Block to indicate that marker text is either the beginning or ending of the page range. Here is how to create the index markers for a page range entry. For this example, suppose that the information for Pantone, under the Color Definitions heading, begins on page 3 and ends on page 5.

To create the first page of a page range, follow these steps:

  1. Place the insertion cursor at the start of the paragraph that begins the information that you want included in the page range.

    The cursor is inserted at the beginning of the paragraph.

  2. Select Special > Marker.

    The Marker window appears.

  3. Select Index from the Marker Type drop-down menu.

    Index is the marker type used for this marker.

  4. Type <$startrange>Color Definitions:Pantone in the Marker Text field. Then click New Marker.

    The typed text is inserted in the Marker Text field. <$startrange> is the Building Block that indicates the first page of the range for this index entry. Color Definitions:Pantone is a multi-level index entry. The second level in the entry, Pantone, contains the page range information.

To create the last page of a page range, follow these steps:

  1. Place the insertion cursor at the end of the paragraph that ends with the information that you want included in the page range.

    The cursor is inserted at the end of the paragraph.

  2. Select Special > Marker.

    The Marker window appears.

  3. Select Index from the Marker Type drop-down menu.

    Index is the marker type used for this marker.

  4. Type <$endrange>Color Definitions:Pantone in the Marker Text field. Then click New Marker.

    The typed text is inserted in the Marker Text field. <$endrange> is the Building Block that indicates the last page of the range for this index entry. Color Definitions:Pantone is the multi-level index entry that the page range information applies to. This entry must be identical in every way to the marker text that was input for the first page of the page range.

    The next time you update the index, this index entry will be included with its page range (see Figure 9.8).

    Figure 9.8. The start and end range marker text.

If the start and end range markers happen to fall on the same page, a page range isn't displayed in the index, but rather as a single page number.

If the information in the two markers does not exactly match with respect to upper- or lowercase, spaces, and spelling, you see question marks appear in the index list for that index entry. Here is what the error might look like:

Color Definitions

Pantone 3–??

Question marks in a page range index entry are a clear indication that marker text representing the start and end ranges do not match. You must go back into the marker text for both entries and fix the problem.

Adding Character Formats to Index Entries

Index entries are viewed or printed in the Paragraph Designer's default font as specified in the index file. If you apply a character format to index entry text in the index list, the next time you update the index file, all your hard work is deleted and replaced with new index entry information that does not contain the character formatting.

Therefore, if you want character formatting applied to particular text in index entries, you have to add this information in the index marker text so that each time the index file is updated, the character formatting that you want is also included.

Here is a good example of why you would use character formatting in index entries. Suppose that you have many cross-reference index entries in the index list. Typically, cross-reference index entries begin with the words See also and are commonly placed in italics to set this type of entry off from other index entries. Thus, a cross reference entry might look like this:

See also online color library

Back to Basics

To create new character tags, select Format > Characters > Designer, then Commands > New Format.

To use a character tag in an index marker, that character tag must already be part of your Character Catalog in the index file. If you plan to use an italic character tag for certain index entries, but do not yet have an italic character tag in the Character Catalog of the index file, you must create it first.

Suppose that you have an existing character tag, Emphasis, that specifies italics. Table 9.13 shows how to add it to specific text in an index entry.

Table 9.13. Including Character Formats in Markers

Marker Text

Appearance in Index

Color Definitions:<Emphasis>See also<Default Para Font> online color library

C
Color Definitions
Pantone 3-5
See also online color library

Notice that this index entry is a multi-level entry, with the cross-reference as subentry under Color Definitions. Therefore, the character tag Building Block is inserted in the definition after the first level (after the colon). Furthermore, if you specifically want just the words "see also" to be in italics, and the words "online color library" not in italics, you must reset the rest of the entry back to the default font of the paragraph. Use the <Default Para Font > Building Block to reset text back to the default font of the paragraph tag. If you do not, all text to the right remains in the applied character format.

Although a character format Building Block formats characters to the right, this is only true for the specific index entry that the character format precedes. In other words, if you have a multi-level entry, and the character format precedes the first part of that entry, the subentry (following the colon) or the next entry (following a semicolon) will not be in the character format.

Changing Existing Index Entries

There are a number of reasons why you might have to edit existing index entries. Perhaps there is an error in how a particular entry is displayed in the index list or you might want to simply change the entry.

Because each index entry is contained inside a marker, you must go inside each marker to change particular marker text index entries. For starters, turn on Text Symbols because you need to see the markers in a document.

Selecting Markers

Let's first explore a tedious method to edit an index entry, before moving on to a more stream-lined approach. You could locate an index marker by viewing markers in the document's body pages. Once found, select the index marker, then select Special > Marker from the menu. The marker text contained in the selected marker is displayed. Make your changes to the marker text, then click Edit Marker. The next time you update the index, the new information for that index entry will be included.

Although this method works for the occasional marker text edit, it does not work well when you have many index entries that you want to edit for any reason.

Using Hypertext Links

When you set up the index, you can turn on hypertext links to automatically be included in each index entry listing. With hypertext links present, you can jump from an index entry listing in the index file, to the index entry marker in the source document.

Each hypertext link in the index is a marker, as shown in Figure 9.9. To jump from a hypertext link to its source, hold down Control + Alt on your keyboard and click once on the index entry in the list. This is a quick and easy way to jump from the index entry to the source marker. You can select Special > Marker to display the marker text of the source marker.

Figure 9.9. Hypertext links in an index list.

Using Find/Change

FrameMaker's powerful Find/Change tool is an efficient method to move between markers in documents. Use this method when you want to look inside many markers in a document rather than the occasional marker, or if several markers are piled on each other. Before using Find/Change, select Special > Marker to display the Marker window. Move the Marker window to the left or right of your screen so it does not interfere with other windows. Now you can begin your search for index markers:

  1. Select Edit > Find/Change.

    The Find/Change window appears.

  2. Select Marker of Type from the Find drop-down menu.

    Marker of Type means that you will search for a particular type of marker rather than just any marker type.

  3. Type Index in the Find Text field to the right of the pop-up menu.

    By typing Index, this search is restricted to index markers only. If you search for another type of marker, you type the name of that marker in the text field. For example, if you create a custom marker called Index2, you can type Index2 in the Find Text field.

  4. Click Find.

    The first index marker is selected and its marker text is displayed in the Marker window, as shown in Figure 9.10.

    Figure 9.10. The Marker Text window and Find/Change.

If the marker text needs editing, make the appropriate changes to the marker text and click Edit Marker. Keep this window open. Then use Find/Change again to find the next index marker. The next time you update the index file, the new index entry information is displayed in the list. Therefore, if you want to test edits that you make to index entries, you must update the index each time you want to perform a test.

Creating an Index List

So far, you learned the process by which index entries are created. Now it's time to discover how to create the index file that will contain the index entries extracted from documents. You also learn how to customize the structure of index entry information and format the look.

Determining What's Included in the Index

Before you start this step, it's a good idea to know ahead of time what marker type you used in documents to create index entries. If you select an incorrect marker type for source information you want to include in the index, the index will have no entries.

For this exercise, suppose that you will include the marker type Index in the index list. Index is the marker type that contains the marker text of index entries that you want to appear in the index list.

Begin the example with a single document containing index markers. Although this exercise shows how to create an index for a single file, the sidebar notes contain steps from a book file:

Book Note

From a book file window, select Add > Standard Index.

  1. Select Special > Standard Index.

    The Standalone Standard Index message is displayed. 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 Standard Index window appears.

  3. Double-click on Index on the Don't Include side (see Figure 9.11).

    Figure 9.11. You can move between lists in the Set Up Standard Index window.

    Index moves to the Include Markers of Type: list on the left. The marker text of Index markers are included in the index list.

  4. Click on Create hyperlinks.

    Hyperlinks are included in each index entry after the index is created. Hyperlinks enable you to quickly jump from an index entry to its source index marker. For more information, see the section "Using Hypertext Links" on page 287.

  5. Click on the Set button.

    The Set Up Standard Index window closes and a new file is created and displayed. The filename is the same as the document filename that was the active file when you set up the index. The filename includes the IX suffix, as in filenameIX.fm. The new index file contains a list of the index entries of the marker type that you included in the setup. The index list has the default FrameMaker look and format.

Book Note

Using a book file, the filename is the same as the book filename and includes the IX suffix.

How to Structure and Format an Index

After you create an index list the first time, it might not be exactly the way you want it to look, or display the information in the way that you require. For example, the sort order for the information in the list might be ordered as symbols, numerics, and alphabetics. You might prefer alphabetic, symbols, numerics (or some other sorting order).

This section explores the basics of rearranging the sort order of information and making changes to category headings and page number separators.

Viewing the Current Structure

Take a look at and understand the structure behind the index 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 IX from the drop-down menu (see Figure 9.12) and click on the Go button.

    Figure 9.12. The Go to Reference Page window.

    The reference page that contains the Building Block structure for the index appears. You selected IX from the Go To Page drop-down menu because IX was the suffix used in the Index Set Up window when you created the index.

  3. View the Index Building Block structure. In the example shown in Figure 9.13, each line or paragraph contained in the reference IX page corresponds to either a paragraph tag or marker type.

    Figure 9.13. The initial Building Block structure.

Back to Basics

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

Any changes that you make to the structure contained on the IX reference page cannot be viewed on the index body pages until the index is updated from either the book file or the individual file (if you created a stand-alone index file).

Any formatting changes that you make to paragraph tags can be viewed immediately.

Making Changes to the Index Structure

After an index is created, you can change a number of controls that determine how information is displayed in the index. Keep in mind that after you introduce any change to the index structure on the reference page, you must update the index file in order to see these changes. In other words, if you make a change to the reference page index structure, and view the body page of your index, you won't see any change until you update the index file from either the book file or the single file that you used to create the index in the first place.

Table 9.14 provides information on how to introduce changes to the way information is structured in the index. All changes shown in Table 9.14 are made from the IX Reference page of the index.

Table 9.14. How to Make Changes to the Index

Control to Change

What Will Change?

1, 2-3

Refers to page number separator placeholders. Currently, commas will be used to separate individual page numbers for a single index entry, and dashes will be used for page range entries. To change, replace the comma or the dash with another character.

Symbols[\];Numerics[0]; A;B;C;D;E;F;G;H;I;J;K;L;M;N; O;P;Q;R;S;T;U;V;W;X;Y;Z

Determines how group titles are displayed in the index. To change to a range (X - Z), change these Building Blocks to X-Z[X]. The X-Z determines the title displayed on the index page, and the [X] determines the sort information.

<$symbols><$numerics><$alphabetics>

Determines the sort order. Change the sort order by rearranging the Building Blocks using cut and paste.

--–—

Determines characters to ignore. The default is hyphens, non-breaking hyphens, en dashes, and em dashes. To include additional characters to ignore, type those characters beginning at the end of the current line.

Determines sorting letter by letter or word by word (default). To change to letter by letter, type a space before the first character of the IgnoreChar paragraph.

<$pagenum>

Displays the page number reference for index entries. Click once in this line to view the paragraph tag name that is the same as the index marker type used in source documents. If you used the marker type "Index", the tag name is "IndexIX." If you used the marker type "Index2", the tag name is "Index2IX."

To generate automatic page ranges from markers of the same type in the index list, type < $autorange> before the <$pagenum> Building Block.

Adding Prefixes to Page Numbers

The default index structure works fine if you use page numbers throughout documents without a prefix. However, your documents might use chapter-based page numbering, in which case, you must make a slight change to the Building Block structure on the IX reference page. Just because you use chapter-based page numbering in documents does not mean that the generated index will automatically implement that same page numbering for index entries.

Chapter-based page numbering looks like this:

9-1, 9-2, 9-3 ... in Chapter 9 and

5-1, 5-2, 5-3 ... in Chapter 5, etc.

Begin this exercise to add a prefix to an index entry page number from the IX reference page of the Index list.

  1. Place the insertion cursor just before the Building Block <$pagenum>.

    The insertion cursor is inserted just before the left pointy bracket of the <$pagenum> Building Block. <$pagenum> represents the page number of each index entry.

  2. Type <$chapnum>-.

    <$chapnum> represents the chapter number for each document file containing the source marker text of the index. The dash (-) is the character used to separate the chapter number from the page number: 9-1, 9-2, and so on. You can type any character you want. For example, you might choose to use a decimal (.) 9.1, 9.2, and so on.

Back to Basics

You can select Format > Document > Numbering to set up chapter or volume numbers of individual document files.

The next time you update the index file from either the book file or the single file, the chapter prefix is added to the page number of each index entry.

If you want to use the Volume number instead, just replace <$ chapnum> with <$volnum> on the IX reference page, as in <$volnum>-<$pagenum>. Or, you can combine the volume, chapter numbers, and text to display in the index:

Vol. <$volnum>, <$chapnum>-<$pagenum>

look something like this:

Color Definitions

Pantone Vol. 2, 9-1

Now that you have an idea of how to incorporate a prefix into the index page number display, it's time to move on to the more complicated multiple page number style and page number prefixes.

Working with Multiple Page Number Styles

Suppose that you are working with a book file that includes a Preface page-numbered as i, ii, iii, and so on, chapters page-numbered as 5-1, 5-2, 5-3 (for Chapter 5) and appendixes page-numbered A-1, A-2, A-3, and so on.

In order to include the chapter prefix with the page number in the index, you use the method in the previous exercise. However, you run into a problem with page numbers of index entries extracted from the Preface. The Preface page numbers have no prefix. Therefore, if you use

<$chapnum>-<$pagenum>

to produce the page numbers in the index, the Preface page numbers would also look something like this:

9-i, 9-ii, 9-iii…

Even though you might not actually be using the chapter number anywhere in the Preface file, you cannot suppress this number from appearing in generated file if you use the <$chapnum> building block in a generated file. You must perform two exercises in order to have the index entry page numbers for the Preface show up as

i, ii, iii …

without the chapter number preceding the page numbers. But you will continue to have the chapter number precede the chapters and appendixes.This would look something like this in the index list:

I

Index Entries

Simple 9-6

Installing the Software ii

Creating a Custom Marker Type

The first step is to create a custom index marker type that you use for the Preface only. Then you can customize the page number display in the index for those entries separately from the other index entries that you will use the marker type Index for. Here's how to do it. Begin with the Preface file:

  1. Place the insertion cursor at the start of the source information where you want to refer the reader.

    The cursor is inserted at the source information.

  2. Select Special > Marker.

    The Marker window appears.

  3. Select Edit from the Marker Type drop-down menu.

    The Edit Custom Marker Type window appears.

  4. Type Index2 (or some other name) in the CustomMarkerText field.

    The new name for the custom index marker is displayed in the Text field.

  5. Click Add, then Done.

    The Marker window appears. The new custom marker type is selected in the menu.

  6. Type the marker text in the Marker Text field and select Edit Marker (see Figure 9.14).

    Figure 9.14. How to create a custom index marker.

    A new index marker is inserted at the cursor location. The marker is of type Index2.
Including a Custom Marker Type in the Index Set Up

Now that you created a new marker type, you have to use the new marker for all index entries in the Preface document file only. Next, learn how to add the new marker type to be included in the index the next time you update or create the index.

The following exercise is performed from a book file window:

  1. Click once on the Index file in the book list and select Edit > Set Up Standard Index. The Set Up Standard Index window appears. If you previously set up the index to include markers of type, Index, then Index is listed on the Include side of the list.

  2. Double-click on Index2 on the Don't Include list (see Figure 9.15). Index2 moves to the Include list, along with Index. You now have two different index marker types that are included the next time you update the index file.

    Figure 9.15. How to include the custom marker in the index setup.

  3. Click Set.

    The Update Book window appears.

  4. Click the Generate Table of Contents, Lists, and Indexes check box and move the file ending in IX to the Include list. Then select Update.

    The index file is updated and now includes the index entries that were inserted in the Preface file using the Index2 marker type.
Understanding Index2 Marker Type Controls in the Index File

After you create the custom marker type that's included in the setup of the index and updated the index file, you can format the index entry information using Index2 in the same way that you would format index entry information using Index.

Take a look at the IX reference page of the index. You notice that a new line with the Building Block <$pagenum> is added. Click one time in that Building Block and look in the status bar display (in the lower left of the document window). You see that it refers to Index2IX, the custom marker you created. The next line, which already existed in the index file, refers to IndexIX, the original index marker you used throughout the chapter and appendix files. This is illustrated in Figure 9.16.

Figure 9.16. Custom marker page number controls.

Therefore, because the <$pagenum> referring to Index2IX has no chapter number Building Block preceding it, all index entries that were created using Index2 marker type have no page number prefix.

Using Section Numbers Instead of Page Numbers

Just when you thought that there were no more of FrameMaker's fabulous features for referencing index entries, we explore yet another method to indicate where a reader might find the source information that is listed in the index.

If you are using military-style headings in documents—that is, numbered heading levels as in 9.1, 9.1.1, 9.1.1.1, and so forth, you also might require that index entries refer to the section number rather than a page number. If this is the case, you have to make a small change to the IX reference page.

Currently, the page number is indicated with each index entry, as you have seen in the last two exercises. Looking at the IX reference page, we see the Building Block <$pagenum>, which represents the page number for each index entry.

Replace the <$pagenum> Building Block with a combination of typed text and the <$paranumonly> Building Blocks to have index entries refer to a section number rather than a page number. This looks like

Section <$paranumonly>

on the IX Index page, and

Color Definitions

Pantone Section 9.1.2

Trumatch Section 9.2.1

in the Index list. If you want the "Section number" to be in italics to set it off from the entry itself, add a character format Building Block to the definition on the IX reference page. The character format must already be included in the Character Catalog of the index file in order for this to work. Suppose the character format Emphasis produces italics. Then

<Emphasis>Section <$paranumonly>

on the IX index page produces the following:

Color Definitions

Pantone Section 9.1.2

Trumatch Section 9.2.1

in the index list.

Working with Static Text

Note

For more information, see the section "Working with Static Text" in Chapter 8, "Creating Tables of Contents and Other Lists."

FrameMaker contributes greatly to the speed and efficiency with which you can create an index because you can update an index at any time with new information in source documents in just a few seconds, or minutes. The paragraph tags assigned to items in the index list contain the IX suffix. This suffix is automatically added to each index entry-level paragraph. This means that, each time you update the Index, FrameMaker replaces all the information in the list tagged with paragraph tags that contain the IX suffix.

If you want to include a title in the index that remains static each time you update the index list, you must tag it with a paragraph tag that does not have a IX suffix.

There is always a catch. In this case, if you include static text in between index list items, that static text remains in the file after it's updated, but will appear just before the start of the index list. It's no longer in the location where you originally inserted it.

Static text works well for a title because a title starts at the top of a page, before the index list begins. Static text doesn't work well for text in other locations.

Working with an Index Template

After you create and format an index file for the first time, you can use this file as a template for other documents and books that use the same index marker types. The methods I explore work similarly to the method used for a table of contents or another list.

Importing Formats from a Template

This first method is fairly straightforward. Assume that you have a nicely formatted index file that you used for another book. Now you plan to start a new document that utilizes the same document templates as the first book. The new book has a new name, as will each document file that you create, although you are using the same template.

Create a new index file for the first time for the new book file. The resulting index file has the default look and structure offered by FrameMaker. Now open up the index template that you or someone else previously created:

  1. Select File > Import > Formats from the New Index File window.

  2. Select the name of the index template from the Source Document drop-down list.

  3. Select all the items in the list and click Import.

After you complete importing the formats from the index template into the new index, you have to update the new index before you see all the changes.

Creating a Named IX File

Here is another method that you might like to use. Suppose that you created a new book file that contains several document files and all the files are contained in one directory on your computer. Further assume that the name of the book file is "runner.book":

  1. Find the index template that you plan to use for the new book file.

  2. Make a copy of this template file and place it in the same directory as the new book file "runner.book".

  3. Change the name of the copied index template file to the same name as the book file. In this example, you can change the name of the index template to runnerIX.fm. Be sure not to change the IX suffix, or this file isn't recognized as an index file.

  4. Select Add > Standard Index from the Book File window.

    The Set Up Standard Index window appears; select the marker types that you want to include in the index.

  5. Update the book file by selecting Edit > Update Book.

    The index is created in the new template format.

Including IX Specifications as Part of Document Files

Here is yet another method that is more streamlined than the previous two methods. Use the method that you feel most comfortable with.

You can include the index 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 IX reference page is also part of a document file, when you create an index the first time, that IX reference page is also automatically included in the created index list. Then you would not have to adjust the Building Blocks the first time the index is created. You can also include the paragraph tags used to format the index paragraphs in a document file. These will also be included in the index, which again saves you time from editing those formats.

Here's an easy way to do this:

  1. Open the index template and a document file that's included in the book file or stand-alone.

  2. From the document file, select File > Import > Formats.

  3. Select the index filename from the Source Document drop-down list.

  4. Select paragraph formats and reference pages from the list of items to choose from.

  5. Click Import.

Now when you create the index the first time, it is formatted according to the index information that currently resides in the document file.

Summary

FrameMaker's indexing features are semi-automatic, providing you with the tools you need to assign index entries in documents and display those entries in a systematic arrangement in an index list. It's really a three-step process, made up of index markers that enable you to include particular words, concepts, or phrases to be extracted from documents, a mechanism to include that source information in an index list, and finally, a variety of ways in which to structure and format the final resulting index list.

Although the initial setup requires time and planning, after your index is in place, you can update the index at any time with the latest source information.


Chapter 10

Chapter 10. Two Versions Within One Document

  • The Benefits of Conditional Text
  • How Conditional Text Works
  • Conditional Text Window De-Mystified
  • Creating Reviewer-Commented Document
  • Combining Two Conditional Text Documents
  • Creating Two Versions Within One Document
  • Summary

Remember the days when creating two versions of a document with only a few unique differences meant maintaining two separate document files? Have you thought there had to be a better way to route documents electronically, collect reviewer comments, and maintain the documents easily? FrameMaker's powerful array of conditional text features allows you to do just that.

Conditional text offers you something unique: the ability to easily create and maintain more than one version of a document contained within one document file. Each document version is distinctive from the other with the exception of common text, tables, figures, and other elements that are shared by all versions. This common information is referred to as unconditional text.

In this chapter, you learn the concepts behind conditional text, appropriate uses, and how to create and implement conditional text in your documentation projects. This chapter focuses on two varieties of conditional text documents:

  • Reviewer commented document: Planning, creating, applying, and working with condition tags and merging two conditional text documents.

  • Two unique versions of one document: Planning and working with conditional tags in more-complicated documents.

After you discover the various ways in which conditional text has an effect on your document, you will be better equipped to plan your FrameMaker documents or work more effectively within the provided template. It's likely that, after you finish this chapter, you'll find even more creative ways to utilize conditional text in your documents.

The Benefits of Conditional Text

Fortunately, the benefits of implementing conditional text into your documents make it easy for you to understand why you should use this feature in the first place:

  • Fewer errors: Imagine that you have two versions of a document that share some text, tables, and figures in addition to content that is unique to each document. Now, both documents are stored in two separate files. The nightmare begins when you start changing the information found in both documents. Maintaining the same information in two separate documents is a big headache and increases the likelihood that at least one document will contain errors, inaccuracies, and oversights.

  • Maintenance: It goes without saying that it is much more efficient to maintain one set of documents than two.

How Conditional Text Works

In this chapter, you learn how conditional text works with various document elements, including the following:

  • Text (that's obvious, isn't it?)

  • Entire tables and table rows

  • Anchored graphics

  • Cross-references

  • Footnotes

  • Markers

  • Variables

With careful planning, the first step to working with conditional text is creating condition tags. After that, you must apply these condition tags to text or other elements within your document.

Next, you have the ability to turn various combinations of conditions on or off. This allows you to view one version or another of your document, or all versions simultaneously.

Where Does Conditional Text Go When Hidden?

You might wonder what happens to text and other elements after they're hidden from view with conditional text. Everything is stored in a little marker, as shown in Figure 10.1.

Figure 10.1. When hidden, conditional text is stored in a handy text marker.

It's a good idea to work with text symbols turned on at all times when you work with conditional text. If not, you won't see the conditional text markers as you edit your document and might attempt to delete them by mistake. Fortunately, FrameMaker displays an alert message if you are about to delete conditional text and you have the option of doing so or not.

Back to Basics

Keep text symbols turned on so you can easily recognize the location of markers and other symbols. You can turn on text symbols by choosing View > Text Symbols.

Conditional text markers look exactly the same as other markers in FrameMaker, such as cross-reference or index markers. Looking at the marker itself, there's no way to tell the difference between various markers. To get more information about a marker type, select it, then select Special > Marker. The marker type is displayed in the Marker window.

Although you can't actually see what's contained in the marker, you can cut, copy, and paste the marker to another location or a separate FrameMaker document. When the condition is shown, everything contained in that marker remains intact. To top it off, the condition tag itself is also copied to the new document.

The Incredible Shrinking Document

If your document has a great deal of conditional text and you are viewing with one condition turned off, you'll notice that your document shrinks in page size. For example, your document might be 50 pages with all conditions in view and only 30 pages after you hide one or more conditions.

Back to Basics

To change the pagination settings, use Format > Page Layout > Pagination > Before Saving & Printing > Delete Empty Pages.

This is exactly what you would expect to happen. Don't be surprised if you are left with many blank pages just past the last page of content in your document.

You have to either manually delete these pages, or save yourself some time and change the pagination settings to automatically delete empty pages in the document. Then just save or print the document to delete all empty pages. Don't worry—after the hidden text is shown, the pages reappear on their own.

Conditional Text Window De-Mystified

Before you delve into creating an actual conditional text document, this is a good time to find out about the contents of the Conditional Text window (see Figure 10.2). Table 10.1 defines each feature shown in the Conditional Text window.

Figure 10.2. The Conditional Text window.

Table 10.1. Conditional Text Window Contents

Command

Description

Current Selection Is

Makes selected text either conditional (based on tags listed under In) or unconditional.

In

Move the condition tag that you want to apply to selected text to this list. The Current Selection automatically changes to Conditional. The result of this action? The selected text is conditional, based on the condition tag shown under the In list. Apply multiple conditions to selected text by moving more than one condition to the In list. See the section, "Multiple Condition Tags Applied to One Unit of Information," later in this chapter.

Not In

When no condition is applied to selected text, all existing condition tags reside in this list. When Tag A is applied to selected text, the remaining existing tags are displayed in this list, meaning that the selected text is not conditional in any of these tags.

As Is

If line 1 is tagged with Condition Tag A, line 2 is tagged with Condition Tag B, and line 3 is tagged Unconditional, and you select all three lines, the condition tags are displayed in the As Is list. This means that the items you selected all have different conditional properties.

Apply

Use this to apply conditional text settings in the window to selected text.

Edit Condition Tag

Use this to create new condition tags, delete or change the style indicators of existing condition tags.

Show/Hide

Use this to show or hide any combinations of conditions in the document. In addition, you can turn the condition indicators on or off, depending on how you want to view the conditional text.

Creating Reviewer-Commented Document

Here's a simple example of a conditional text document: In this scenario, consider that you have written a document to be reviewed by two experts. Each reviewer will provide comments on the content of your document. Your goal is to have both reviewers enter their comments into the same document so you can view both sets of comments and content together in context.

In this section, you are guided through the steps to conditional text: planning, creating tags, applying tags, and working with conditions.

Planning the Reviewer-Commented Document

As always, make a plan! Spending time to plan your attack always results in more efficient use of FrameMaker, not to mention your time.

First, determine how many reviewers will comment on your document. In this example, two reviewers will look over your document. Assign each reviewer his or her own condition tag. For example, Reviewer A will use condition tag A and Reviewer B will use condition tag B. Keep it simple.

Tip

If you plan to print conditional text in black and white, choose a style in addition to or rather than color for your condition tags.

After you determine the number of condition tags necessary, be creative in deciding the characteristics of each condition tag. The characteristics of each condition tag are known as condition indicators. When you view your document with conditional text visible, indicators make it easy to distinguish one condition from another and from common text. For example, condition tag A can be blue and underlined, while condition tag B can be red and overlined. Text with no condition applied has no special characteristics except for those from its paragraph tag. Use your imagination.

Next, provide clear instructions for your reviewers, including which condition tag to use and how to apply it to the text.

Then send the document to Reviewer A. After it's completed, pass it to Reviewer B. Later in this chapter, you learn how to solve the problem of merging documents with conditional text that were reviewed at the same time (each document with one reviewer condition).

Creating Condition Tags

So far, you determined that two condition tags are needed for this document. The two condition tags that you create will become part of that document's template properties.

Back to Basics

Every document in FrameMaker is, in essence, a template. If you plan to use the same condition tags in other documents, use File > Import > Formats to import the condition tags to other documents.

The first condition tag is A, styled with an underline and a blue color. (Keep in mind that this book you are reading is not in color, so the condition tags will not show any color in the figures.) The following steps show you how to create a condition tag:

  1. Select Special > Conditional Text.

    (You probably realize by now that the Special menu has all the really cool, but difficult functions.)

  2. Click on the Edit Condition Tag button.

    Don't be fooled by the word Edit. This is where you create a new condition tag.

  3. Type a tag name in the Tag Text field.

    The Tag Text field already contains a placeholder, ConditionName, as a reminder to type the actual condition name. For this example, type A in the Tag Text field.

  4. Select Underline from the Style drop-down menu and Blue from the Color drop-down menu.

    As shown in Figure 10.3, these are the condition indicators for condition tag A.

    Figure 10.3. You apply the condition indicators for condition tag A in the Edit Condition Tag window.

  5. After you finish, click on the Set button.

    You return to the Conditional Text window. You have not yet applied this condition tag to the text.

  6. Create condition tag B by following steps 2 through 5 and by using a different condition indicator.

Viewing and Deleting Condition Tags

After you create both condition tags, they are displayed in the Conditional Text dialog window. You might also see other condition tags that were part of the original document (see Figure 10.4). You can either leave those intact or delete them. To delete the tag, click one time on that tag in the list, then click on Edit Condition Tag. Use the Delete button in the Edit Condition Tag window.

Figure 10.4. Other tags appear in the Conditional Text window.

Back to Basics

When you view condition tags, you might see tags displayed in any one of the three lists, depending on the placement of your cursor. For example, if the cursor is in text tagged with A, A will appear in the In list.

Applying Condition Tags

Now that you created two condition tags, it's time to put them to good use. In this example, the reviewers will apply their assigned condition tags to their comments. First, let's work with Reviewer A.

Reviewer A must follow these steps to apply conditional text to his or her comment text:

  1. Select the text that you want to apply the condition to.

  2. Select Special > Conditional Text.

    You see a list of condition tags in the Not In list.

  3. Double-click on A in the Not In list, to move it to the In list.

    After you do this, you see the Current Selection radio button change from Unconditional to Conditional. This means that the selected text will be conditional in condition tag A.

Back to Basics

Alternatively, you can click once on A in the Not In list and click once on the arrow below the list to move it to the In list.

  4. Press Apply.

    After you finish, the status bar displays the condition tag within parentheses when the insertion cursor is in text containing the condition (see Figure 10.5).

    Figure 10.5. The status bar displays the condition tag in parentheses.

Back to Basics

The status bar is located in the lower left of the document window.

Reviewer A must continue to apply this same condition tag to all commentary. Reviewer B does the exact same thing, except uses condition tag B.

Working with Condition Tags

After Reviewers A and B have entered their comments into the same document and tagged them accordingly, it's time to view and/or print the document. In this section, you learn the many options you have to work with and what the result looks like. For each option, open the Conditional Text window and click on the Show/Hide button. The following steps begin with that window.

Viewing with Both Reviewers' Comments Visible and Identifiable

Click on the Show All button and check Show Condition Indicators, as shown in Figure 10.6. When all condition tags are showing, it doesn't matter which list the tag is in. The resulting conditional text can be viewed in the document with indicators turned on to identify one from the other. After you finish, click on the Set button.

Figure 10.6. The settings and display of conditional text that is visible and identifiable.

Viewing with Both Reviewers' Comments Visible but Not Identifiable

Click on the Show All button and uncheck Show Condition Indicators, as shown in Figure 10.7. As a result, text with a condition applied to it will be viewed in the document with indicators turned off; you will not be able to identify one from the other. After you finish, click on the Set button.

Figure 10.7. The settings and display of conditional text that's visible but not identifiable.

Note

Alternatively, you can view the document with only tag A or tag B visible and not distinguishable. To do this, turn off condition indicators.

View with Reviewer A's Comments Visible and Identifiable

To view only Reviewer A's comments, move all conditions except for A to the Hide list and check Show Condition Indicators, as shown in Figure 10.8. As a result, only text with condition tag A applied will be viewed in the document with indicators turned on to identify them from common text. In this example, other conditional text is hidden and represented by a marker in the text. After you finish, click on the Set button.

Figure 10.8. Only the settings and display of conditional tag A is visible and identifiable.

Viewing with Reviewer B's Comments Visible and Identifiable

To view only Reviewer B's comments, move all conditions except for B to the Hide list and check Condition Indicators, as shown in Figure 10.9. As a result, text with condition tag B applied will be viewed in the document with indicators turned on so it can be identified from the common text. After you finish, click on the Set button.

Figure 10.9. Only the settings and display of conditional tag B is visible and identifiable.

Combining Two Conditional Text Documents

Previously, I examined how to work with condition tags where Reviewers A and B input their comments into one document. In the real world, this might not always be the case. For instance, you might have sent each reviewer a separate document to input their comments. If that's the case, you will find yourself with two separate document files, each one containing one reviewer's comments.

Getting both reviewers' comments into the same document is another FrameMaker brain teaser. Here's one way to solve it.

Say that you have two FrameMaker documents. The first document (doc1.fm) contains content and Reviewer A's comments tagged with condition tag A. The second document (doc2.fm) contains the same content as the first document and Reviewer B's comments tagged with condition tag B. The goal is to merge these two documents with no duplications so that Reviewer A's and B's comments can be viewed in one document.

To accomplish this task, you must combine more than one FrameMaker feature. Combining various features often results in more efficient use of the program.

Using Document Compare

Usually, document compare is used to compare a new and older version of a document. Document compare produces a single document by combining both versions of it. In this example, you use document compare to create a composite document for the purpose of combining the conditional text from both documents into one.

  1. Open both documents. Make sure the conditional-reviewer text in each document is showing.

    This doesn't work if the reviewer conditional text is hidden. The active document should be doc1.fm.

  2. Select File > Utilities > Compare Documents. Select doc2.fm from the Older Document drop-down menu.

    As a result, you compare the active document, doc1.fm, to doc2.fm.

  3. Select Summary and Composite Documents.

    Based on this selection, you generate not only a new composite document, but a summary document as well. You can ignore the summary document after it's generated; you won't need it for this task.

  4. Click on the Options button. Select Mark Insertions With > Nothing.

    Do this to avoid more than one condition tag applied to text that is added from the compared document.

  5. Select Mark Deletions with Condition Tag: Deleted. Uncheck the two list items at the bottom of the window and click on Set.

    These two items have no effect on this task.

  6. When the Compare Documents window displays, click on Compare and let FrameMaker do its magic.

Back to Basics

A summary document is usually one-page long and contains a summary and revision list of each item compared.

After you finish, a composite and summary document is displayed. For this task, you are only concerned with the composite document. The composite document contains the common or identical information from both documents and the additions from both documents. In this case, the additions are the conditional text.

You might notice two characteristics in the composite document. First, some paragraphs with conditional text as part of that paragraph might show up twice in the composite document. Those duplicate paragraphs are tagged with the condition tag Delete. This may or may not be the case in your document.

Second, the conditional tag Delete is added to all condition tags from the Reviewer A document, which makes each occurrence of that conditional text tagged with A+Delete rather than just A.

In the next exercise, you discover how to clean up the composite document quickly.

Cleaning Up the Composite Document

It's time to fix the duplicates, strip the Delete tag from the A+Delete, and be left with just the original content and the Reviewer A and B conditional text. Here's how:

  1. Select Special > Conditional Text.

  2. Click one time on the Delete condition tag.

    The list where Delete appears depends on the placement of your insertion cursor.

  3. Click on Edit Condition Tag. With the Edit Condition Tag window displayed, click on Delete.

    The Delete Condition tag window appears.

  4. Select Delete the Text.

    This action deletes all text tagged only with the Delete tag and also deletes the tag itself, thereby removing it from the A+Deleted as well. Just A is left.

Creating Two Versions Within One Document

Now that you understand how to create a simple conditional text document, take it a step further. In this example, you learn how to work with conditional text in complex tasks, such as graphics, tables, cross-references, markers, variables, and books.

A good example of a complicated conditional text document is a user guide for a software product being written for both Macintosh and Windows platforms. Most content will be applicable to both platforms, and some will be applicable to only one or the other. Content typically includes text, graphics, tables, and various markers, as well as cross-references and variables.

Let's walk through the techniques and principles used to work with conditional text in complicated documents, as well as the pitfalls of using condition tags with various elements.

Planning the Two Version Document

Planning is your best friend for accomplishing tasks in FrameMaker. Planning ahead saves you headaches from complications that might occur down the road. Although you might already have a FrameMaker template to work with, consider how you will work with conditional text throughout your daily tasks.

When you plan this type of conditional document, consider the following:

  • Determine how many versions are required. In this case, two document versions are required, one for Macintosh and one for Windows. You might have more versions in projects you are working on. You might also want to include reviewer comments in addition to each unique version.

  • Determine how many condition tags you need. For this example, two condition tags are needed: Mac and Win. You might need more tags. For instance, if your software manual spans Macintosh, Windows, and Unix, you'll need three tags. Throw in any number of reviewer comments, and you could be looking at eight or nine tags.

  • Decide what type of elements can be conditional. This is important, especially when more than one writer is involved in the process. You might decide that text, graphics, and tables can be conditional and not markers or variables. Or, you might come up with some other combination. It's a good idea to let everyone on the project know what the rules are so you don't run into surprises later.

  • Determine the size of information chunks that can be conditional. For example, you might decide that entire paragraphs only can be conditional, not just one word. The effect of making just one word conditional without a space on either side results in extra spaces after the conditional text is hidden.

Applying and Working with Condition Tags

Previously, I covered how to create condition tags (see the previous section, "Creating Condition Tags"). You also learned the basics of applying a condition tag to text. This section covers the details of applying condition tags to text, such as spaces and other punctuation, and the results you can expect to encounter.

You also discover how to use multiple condition tags applied to a single unit, as well as how condition tags work with tables, graphics, cross-references, footnotes, markers, variables, and within books.

Condition Tags and Text

When you apply condition tags to text, you should consider a few matters before you go on a tagging expedition.

During the planning process, you might decide that applying condition tags to small chunks of information, such as one word, is perfectly acceptable for your project. If this is the case, you also have to tag either the space before or after that one word with the same condition tag; otherwise, you will run into spacing problems when that condition is hidden. For example, Figure 10.10 illustrates the result of hiding one tagged word without also tagging the space either before or after that word. You end up with the unacceptable two spaces instead of one.

Figure 10.10. The result of tagging one word without a surrounding space.

Tag the space either before or after the word to get the correct result in your conditional text document. Figure 10.11 shows the space after the word tagged.

Figure 10.11. The result of tagging one word with a surrounding space.

The same basic rule applies to various punctuation throughout your document. As a practical example, say that you are referring the user to a menu command shortcut, followed by a comma. For each version, you would have a different menu command, each with a condition tag applied. Decide whether the comma is part of that conditional text and whether the space before a word is part of that conditional text.

It's a good idea to tag as you go, rather than tag everything after you finish writing the document.

Multiple Condition Tags Applied to One Unit of Information

Back to Basics

Use Edit > Find/Change > Conditional Text to search for multiple conditions applied to one unit of information.

In the real world, you might have to apply more than one condition tag to one unit of information. For example, say that you are writing software documentation applicable to three hardware platforms: Macintosh, Windows, and Unix. There might be information that is common to both the Windows and Unix platforms, but not Macintosh. In this case, those bits of information would be tagged with both Windows and Unix condition tags. If you click in that bit of information, the status bar looks like Figure 10.12. This unit of information is displayed when one or both tags are showing.

Figure 10.12. The status bar shows multiple condition tags.

Condition Tags with Autonumbers or Automatic Running Headers/Footers

Applying condition tags to any paragraph containing an autonumber is no different than applying a condition tag to text. A good rule of thumb: Always grab the end-of-paragraph symbol when you apply condition tags to numbered paragraphs. If you do not, when that condition is hidden, the text is hidden and the autonumber continues to be displayed.

The effect of hiding a conditional autonumbered paragraph is exactly the same as if the information were deleted from the document. For example, if your document contains autonumbering and you delete any of those numbered paragraphs, everything in that numbering stream is automatically renumbered.

In the same way, if conditional text is applied to headers that are part of an automatic running header or footer, and that condition tag is hidden, headers or footers adjust based on the information that's now displayed on any given page in the document.

Condition Tags and Tables

Condition tags work well with either an entire table or any number of rows within a table. Condition tags cannot be applied to a single cell or a column, but they can be applied to any text that is contained in a table cell.

If you created cross-references to tables, see the section, "Condition Tags and Cross-References," later in this chapter.

Table Anchor Symbols

To apply a condition tag to an entire table, select the table's anchor, as shown in Figure 10.13.

Figure 10.13. To apply a condition tag to an entire table, you must select the table's anchor.

Although you can select the entire table by using Ctrl triple-click, FrameMaker recognizes this as a condition tag applied to table rows and not the table as a whole. The problem with this method is that, if you add rows later, they will not be conditional.

Be careful with tables anchored to the paragraph directly above them. If you manually select the table anchor together with the end of paragraph symbol from the paragraph above, then, when that condition is hidden, the next paragraph automatically moves up to join the above paragraph.

Back to Basics

Use Find/Change > Any Table to easily and swiftly select table anchor symbols.

Working with a Row

To work with one row in a table, select any row within a table (or consecutive rows) and apply a condition tag. With indicators turned on, a conditional row looks like Figure 10.14.

Figure 10.14. A table row wtih the condition indicator turned on.

Keep in mind that table rows break the rules; you will not see a marker in place of the row when a conditional row is hidden. If you are looking for the condition tag in the status area, expect to see it only if you select any number of entire cells within a conditional row that is showing, or the row itself. You will not see the condition tag in the status area if you simply click inside the cell.

Back to Basics

You can apply multiple condition tags to tables or rows.

Working with Table Text

Text contained within table cells works exactly as text outside a table cell. Select text within any table cell and apply a condition tag.When condition indicators are turned on and that condition is showing, you will see the text with its indicator style and color.

If you applied a condition tag to either an entire table or a row, you will not see a condition indicator specifically on text. Because text is a subset of the larger table or row, the condition indicators will be displayed on either one of those.

Condition Tags and Figures

In the real world, you can construct FrameMaker documents in many ways. For example, when incorporating figures into your FrameMaker documents, you might have a favorite method for accomplishing this task, or your company might have defined the procedure on how to do it. Here are a few of those methods and how they best work with condition tags.

Tip

Anchored frames contain graphics or text. Anchored symbols represent the location where the anchored frame or a table is anchored.

If you created cross-references to figure titles, see the section "Condition Tags and Cross-References" later in this chapter.

Figures and Figure Titles as Separate Paragraphs

This first example shows how to work with condition tags and figures with a numbered figure title below it in a separate paragraph. Figure 10.15 shows how this is structured. The figure is anchored to the paragraph directly above it. There is a paragraph directly below the anchored frame with the numbered figure title.

Figure 10.15. The structure of figure and figure title separate.

With this setup, apply a condition tag by first selecting the anchor symbol. The anchored frame is selected. Alternatively, you can click one time on the anchored frame itself to select it. Either way works. Apply the correct condition tag to the selected anchored frame.

Back to Basics

Use Format > Find/ Change > Anchored Frame to easily find and select anchor symbols.

Next, select the figure title, including the end of paragraph symbol, and apply the correct condition tag.

Here's what can happen if you do not include the end of paragraph symbol in the selection and application of the condition tag:

  • With an automatic number, the automatic number will remain when that condition is hidden.

  • With no automatic number, an empty paragraph line will remain in the document, which creates an unneeded space between paragraphs.

Selecting both the anchored frame and numbered figure title below it at the same time works, but if you grab the anchor symbol and the end of paragraph symbol next to it, you will run into other problems. The section "Table Anchor Symbols" found earlier in this chapter is worth reading to learn how to avoid this sort of problem.

Back to Basics

Use the Text Frame tool in the Graphic Toolbox to place text inside an anchored frame.

Figures and Figure Titles in an Anchored Frame Together

When the figure title in included within the anchored frame containing the figure, applying a condition tag is easy as pie. Figure 10.16 shows you how this is structured.

Figure 10.16. The setup of the figure and title together in an anchored frame.

Select either the anchor symbol or the frame itself. Then apply the condition tag. Everything inside the anchored frame is included in the condition tag.You won't see condition indicators on any text within the frame. These are a subset of the anchored frame, and condition indicators will only be displayed on its anchor symbol.

Figures and Figure Titles in a Table Together

This is a favorite method of putting figures in a document (see Figure 10.17). If you have a table tag set up to include one row and column (for example, one cell only) and a table title below it, you can place the figure in the cell and the figure title in the table title area. This works well because all the elements related to the figure are included within the table.

Figure 10.17. The setup of the figure and figure title together in a table.

See the section "Table Anchor Symbols" earlier in this chapter for more information on how condition tags work with tables.

Condition Tags and Cross-References

Cross-references and condition tags can be tricky in FrameMaker. Applying a condition tag to cross-reference sources is easy, but understanding the consequence is another matter. In your document, you probably have tables, figures, or headings that are sources of cross-references.

For every source cross-reference that you apply a condition tag to, you should also apply the same condition tag to the cross-reference itself. If not, you end up with unresolved cross-references when that particular condition is hidden.

To break down this concept, when a condition is hidden, FrameMaker treats this as if the information is deleted. In other words, the source cross-reference marker vanishes and, therefore, the cross-reference comes up unresolved. Of course, once that condition is showing, the cross-reference marker is back in its place and you will not have the problem.

Back to Basics

Use Edit > Find/Change > Marker of Type > Cross-Ref to easily find and select cross-reference markers.

Another FrameMaker "gotcha" is when a cross-reference marker is inserted at the beginning of a paragraph. Say that you applied a condition tag to only the first word of a chapter heading. Later, you decide to cross-reference the chapter heading from another location in your document. The cross-reference marker is automatically inserted directly in front of the first word of the chapter heading. This marker takes on the conditional characteristics of the first word.

Then, when that condition is hidden, the cross-reference comes up as unresolved. Be sure to go back and change that marker to unconditional.

Condition Tags and Footnotes

If footnotes in your conditional document are applicable to either one version or another, apply a condition tag to the footnote reference and not to the footnote itself. If the footnote reference is part of a paragraph or series of words that you applied a condition tag to, the footnote reference will be included.

Back to Basics

Footnote reference is the small number in the text that refers to a footnote.

If you apply the condition tag to the footnote text itself, just the text in the footnote will be conditional. The number preceding the footnote or the reference in the text will not be conditional.

Condition Tags and Markers

You can easily apply condition tags to markers throughout your document. You might already be familiar with many marker types, such as cross-reference and index markers.

Because cross-reference markers were covered in the section "Condition Tags and Cross-References" earlier in this chapter, this section focuses on index markers.

To apply condition tags to index markers, simply select the marker and apply the condition tag.

Back to Basics

If you have trouble selecting the marker, use Edit > Find/Change > Any Marker.

In your two-version document, you will be generating two separate indices, depending on which version of the document is currently in view. With condition tags applied and one version of the document in view, only those index entries that are unconditional and those tagged with the one version in view will be generated in the index. If index entries that are meant to be hidden show up in the index, you might have tagged these with an incorrect condition tag. This might also be the case if ranged index entries come up with question marks (??).

Condition Tags and Variables

Here's a good example of how and why to use condition tags with variables: Going back to the document example, say that when you view the Windows version of the software manual, the book title will read "Installation Guide for Windows." When you view the Macintosh version of the book, the book title will read "Installation Guide for Macintosh." Each book title is made up of a user variable inserted on the master page.

Here's one way to implement this concept into your conditional document:

  1. Create two user variables named MacTitle and WinTitle.

    The definition of each user variable is "Installation Guide for Macintosh" and "Installation Guide for Windows," respectively.

    After you finish, the user variables are displayed in the list of variables (see Figure 10.18).

    Figure 10.18. After you create the two user variables, they are displayed in the list of variables.

  2. Determine where you want the document title to show up in your document.

    In this example, the document title shows up on the left side of the left-page header, just after the page number.

  3. Go to the left master page of your document. Insert both user variables in the left side of the left page header.

    The variables are displayed right next to one another.

  4. Apply the correct condition tag to each user variable.

    With all conditions showing and indicators turned on, the left header of the document looks like Figure 10.19.

    Figure 10.19. The user variables on the left master page with condition tags applied.

When you view just the Macintosh version of your document, the Macintosh document title will be in view, with the Windows document title hidden, and vice versa.

Note

Click on a conditional variable on the master page and its condition will not be displayed in the status area.

Conditional Text in Book Files

Conditional text in files can be tricky to work with once those files are included in a book. This section discusses the conditional text challenges that come up in book-building tasks. It'd be surprising if you have not already run across at least one of these.

Back to Basics

Save all book files after book-wide commands. Select Shift > File > Save All Files in Book from the Book window

Book-Wide Settings

After you put your files together into a book file, book-wide command settings take precedence over the original individual file settings for the selected book files. This means that, if File A has condition Mac hidden and you use book-wide commands across the entire book to show all conditional text, File A's condition settings will change based on the book-wide conditional setting.

Inconsistency Messages

When you update a book file, you might come across a few interesting inconsistency messages:

  • Inconsistent Show/Hide Settings

  • Inconsistent Use Condition Indicators

  • Inconsistent Condition Indicator

Any one of these messages means that the file in question contains conditional text settings that differ from those in previous files in the book.

What can you do to solve this problem? Make the conditional settings in every file within that book exactly the same. Instead of going through the trouble of opening each individual file and checking its settings, you can change all the files at once.

Here's how to change all the files at one time:

  1. With your book file active, decide which document file's conditional setting you want to use.

  2. Open the file.

    This file becomes the source file from which the conditional setting will be imported to the remaining files in the book.

  3. From the Book window, select the files that you want to change.

  4. Use File > Import > Formats to import the conditional text settings from the source document to the remaining files in the book.

Back to Basics

Select files within the book window by shift-clicking to select consecutive files, Control-clicking to select non-consecutive files, or pressing Control-A to select all the files.

Unresolved Cross-References

After you update your book file, you might discover unresolved cross-references. This can happen if you turned off a condition to hide text and other elements, and a cross-reference refers to that hidden text. See the section "Condition Tags and Cross-References" earlier in this chapter for clarity on this common problem.

Summary

Conditional text is just one of the many features tucked inside FrameMaker's bag of tricks. Comprised of a manageable array of features, conditional text is ready to work for you.

Although you learned many combinations of working with conditional text, you will probably find even more combinations after you have the opportunity to play around with and try out its nifty features.


Chapter 11

Chapter 11. PDF and HTML

  • Planning Smooth Transitions to PDF and HTML
  • Converting Documents to PDF
  • Convert to HTML
  • Summary

For the last 2,000 years, paper has been a significant source for collecting and distributing an exponential amount of information. You either produced documents yourself or read others that were distributed using that age-old form. Although paper won't be disappearing anytime soon, faster and more efficient methods for the distribution of information via the World Wide Web have established themselves firmly in our everyday lives. These methods include Hypertext Markup Language (HTML) and Portable Document Format (PDF) by Adobe.

The appeal of both HTML and PDF is the ability to distribute information electronically to any computer host, regardless of hardware or software platform. This ability makes that information more accessible than ever before. Information receivers can decide for themselves whether to print that information on paper or not.

FrameMaker provides the ability to take documents that you might have originally planned for print, and convert them to a hypermedia format, such as HTML or PDF.

In this chapter, you learn what FrameMaker tools are available for converting FrameMaker documents to either PDF or HTML. To take advantage of these features, you should already be familiar with Adobe PDF, HTML, CSS, and various graphic formats, such as GIF, JPEG, and PNG.

Planning Smooth Transitions to PDF and HTML

When you begin a FrameMaker project, you should address the resulting media format possibilities and build these into your plan. Although you can use any FrameMaker document to create PDF and HTML documents, converting documents that map well to either format gives you more options. Understanding the limitations and issues associated with each of these media formats will provide a good base on which to build FrameMaker documents for easy conversion. This section explores each media format and how FrameMaker document formats relate to each media format.

Adobe PDF

Adobe PDF is a universal file format that can be shared across different computer platforms. PDF maintains the formatting information of the source document. In other words, a PDF file will look exactly the way you intended it to with regard to the page layout and formatting information of the source document. To view PDF files, end users must have either Adobe Acrobat or Acrobat Reader on their computers. PDF files can be viewed page by page in a Web browser or downloaded and viewed independently.

Depending on what version of Adobe Acrobat or Acrobat Reader an end user has, you can take advantage of many features. If you use version 4.0 or higher, here's what you can expect from a converted FrameMaker document:

  • You can include information about the document, such as the author name and keywords, for better identification.

  • You can specify particular paragraphs as bookmarks, which enables the reader to jump to a topic for quick navigation through the PDF file.

  • Cross-references and hypertext commands change to clickable hyperlinks.

  • The PDF file will look exactly as you intended from a layout perspective.

Converting to HTML

HTML is a subset of an even bigger language called SGML (Standard Generalized Markup Language). HTML describes the structure of document contents rather than the page layout and format. Through word processing and page layout programs, you use style sheets to indicate how you want the content in your document to look. When style sheets are applied to particular paragraphs, those paragraphs take on the formatting properties of that style sheet. That's an important distinction: HTML describes structure only, while style sheets describe page layout and formatting.

HTML uses tags to define elements in a document. Each tag provides information about what that element is, rather than how it looks. For example, with HTML tagging, you indicate that an element is a Level 1 heading, not that the element is formatted in a particular way. Don't be confused by new HTML techniques that allow you to apply formatting to HTML elements. HTML has been and continues to be a document-structure description language. Therefore, the most important thing to consider for HTML output is the breakdown of elements in your documents.

HTML Conversion Considerations

While you decide what media you will use to distribute your documents, keep a few guiding principles in mind to determine good candidates for conversion to HTML:

  • If you use multiple tagged flows, only the main text flow (tagged A) will be converted. Content contained in other text flows will not be converted.

  • Master page content, whether text or graphics, will not be converted.

  • The contents of anchored frames are converted to graphics, whether they are imported graphics or text input in FrameMaker. However, if GIF images have been both referenced and scaled in FrameMaker, you could lose these settings after conversion.

  • If you use a two-column layout, no existing HTML element easily produces a two-column HTML page.

  • If you used paragraph tag format overrides extensively, the resulting HTML will not be accurate with regard to converted elements.

If you find that your documents will not convert well to HTML, don't bother struggling through the refining of HTML documents unless you are well versed in HTML. PDF might be the best solution for you.

Converting Documents to PDF

When you convert FrameMaker files to PDF, you must be concerned with two major components of this task. First you have to determine how the source information is output to PDF with regard to document settings. Then you move on to create the PDF file based on those configurations.

After you have the PDF setting that you want, you have these three methods with which to perform the conversion to PDF:

  • Print to PDFWriter

  • Using Save-As

  • Manually Distilling

In this section, you find out how to set up files before converting to PDF and explore all three methods of conversion. Keep in mind that using PDFWriter is not recommended for use with FrameMaker. However, I review it briefly.

PDF Setup

If you are using a template for documents, including the PDF settings that you plan to use when you finally create PDF files is a good idea. If you have not decided on final PDF settings, you can always include them later by fixing the PDF settings of a single file and using the Import Formats command to import PDF settings to other FrameMaker files to which you want to apply the same settings.

Back to Basics

To import PDF settings to files, select File > Import > Formats > Document Properties.

PDF Setup helps you control how source information is output to PDF. I review these control features so that you get the most out of PDF conversions. To access PDF settings, select Format > Document > PDF Setup. The PDF Setup window appears, which is made up of four setup categories:

  • Bookmarks. Defines a hierarchy of quick links to jump to topics in the PDF document.

  • Structure. Enables a defined logical structure of elements to be included in PDF files.

  • Document Info. Allows you to include information about the document in the PDF file.

  • Links. Creates named destinations for all paragraphs in a document.

Bookmarks

Bookmarks are used as clickable navigation tools in PDF files, which makes it easier for readers to jump to various parts of the document. In the Bookmarks tab of PDF Setup, you can define the tagged paragraphs in the source document that you want to use as bookmarks in the PDF file. Using the example in Figure 11.1, the content of paragraphs in the document that are tagged with either ChapterTitle, H1, H2, and H3 will be displayed in the PDF file as a collapsible hierarchical list of clickable hyperlinks.

Figure 11.1. PDF setup for bookmarks and resulting bookmarks.

The Bookmark Level arrows directly under the Include Paragraph lists allow you to change the hierarchical level for display in the PDF file. To make changes to the level of any paragraph tag shown on the Include list, click one time on the tag name and click either the left or right arrow under the list.

After you decide which paragraph tags to include as bookmarks, be sure to check Generate PDF Bookmarks to activate this feature before you perform the conversion.

You also have the option of selecting Include Paragraph Tags in Bookmark Text. Selecting this inserts the name of the paragraph tag in front of each bookmark. For example, without this option, a bookmark whose source is tagged with H1 might be displayed like this:

The Runner's Workshop

With this option, the same bookmark looks like this:

H1 - The Runner's Workshop

If the paragraph tags in the source document have many characters, this is not a good option for you to use for final conversions to PDF. The bookmarks become crowded and difficult to view.

The final option in this pane is Articles: Thread by Text Frame or Thread by Column. This setting corresponds to the Articles feature in a PDF file and sets the reading order of articles. For example, suppose that your source document were in a two-column format. The logical reading order of that document would be to read the first column top to bottom, and then start at the second column and read from top to bottom. In this case, Thread by Column causes the insertion point to move in that reading order in the PDF file.

If your source document is a one-column format, Thread by Text Frame is the appropriate setting because the logical reading order would be text frame to text frame that corresponds to each page.

Structure

The Logical PDF Structure mechanism makes it easier to access content in PDF files. The structural information in a document is similar to HTML in that it is used to describe the structural content of a document rather than the page layout or format. The logical structure in PDF files is independent of formatting information, such as order or location of graphics.

Note

Visit http://access.adobe.com for the latest information about this technology.

One of the many uses for creating PDF Logical PDF Structure is to provide accessibility to the content of PDF files with assisted technology, such as screen readers. For example, a screen reader, which assists seeing-impaired users, cannot utilize visual formatting information to interpret the content. Screen readers rely on the underlying structure of a document to interpret its contents and navigate the information.

To include the Logical PDF Structure, click the Structure tab in the PDF Setup window (see Figure 11.2). Move paragraph tag names to the Include Paragraphs list, to indicate paragraphs that you want included in the PDF structure. Then, use the arrows located directly under that list to indicate the structure level. Enable this feature by clicking Generate PDF Logical Structure. If you do not plan to utilize this technology, do not select this feature.

Figure 11.2. The PDF setup for the Logical PDF Structure.

Document Info

Click the Document Info tab in PDF Setup to access its contents, as shown in Figure 11.3. The information that you enter in this window corresponds to the information that is displayed in the File > Document Info > General tab in the resulting PDF file.

Figure 11.3. The PDF setup for document info.

If you plan to distribute PDF documents, it's helpful to those reading it to provide information about the document.

If you decide to leave the Document Info pane of the PDF Setup empty, FrameMaker automatically includes information in some of the fields, such as:

  • Author. Includes username from computer-user information.

  • Title. Includes the filename.

The remaining fields are left blank.

Links

Click the Links tab in PDF Setup to access this option (see Figure 11.4). If you use this option, the resulting PDF files increase in size. For reduced file size, make sure this option is not selected. However, you should first understand why you would even use this option. Suppose that you included cross-references from File A to File B. Then, you converted each file to PDF. If you opened File A's PDF and clicked on a cross-reference to File B, the source File B opens to the source information because cross-references are activated hyperlinks in the PDF file. Now, say that you added more cross-references from File A to File B and you only converted the changed File A to PDF and planned to use the old PDF File B. Now, when you open File A's PDF and click on one of the newly introduced cross-references, you jump to the source file even though you did not reconvert that source file after the new cross-references were input into File A.

Figure 11.4. The Links tab in PDF Setup.

Optimizing Options

If you created documents in previous versions of FrameMaker (earlier than 6.0) and you want to take advantage of the Create Named Destinations feature included in the Links tab of the PDF Setup, you must optimize the file first.

FrameMaker offers two optimization features for this purpose. The first, Format > Document > Optimize PDF Size > Options, allows you to specify a variety of optimization settings. The second, Optimize Files, allows you to select the file in which you want to apply these optimization settings.

Print to PDFWriter

If you have an Acrobat PDFWriter printer driver installed on your computer, you have the ability to use it as the print driver to create a PDF file. PDFWriter is a non-PostScript driver and was designed for use with other applications with PostScript limitations. This method is not good to use with FrameMaker; you should use the Save-As or Distiller options instead, if available.

If you have experimented with PDFWriter, the resulting PDF file does not include any of the features included with the other PDF conversion methods, such as clickable links or bookmarks.

In brief, here's how to use PDFWriter to create a PDF from an open FrameMaker document:

  1. Select File > Print.

    The Print window appears.

  2. Click the Setup button for Printer.

    The Setup Printer window appears.

  3. Select PDFWriter from the Printer drop-down list and click OK.

    The PDFWriter printer is selected.

  4. Click the Print button.

    The Save As PDF window appears. You have the option to change the PDF filename or save location in each pane. If you select Prompt for Document Information, the PDFWriter Document Information window is displayed. Here, you can enter information about the document that will be accessible in the PDF file from File > Document Information > General.

Save-As PDF

With the Save-As PDF feature, the resulting PDF file includes clickable links and bookmarks. In general, PDF files are created as the result of a two-step process. First, the Acrobat Distiller PS Driver is used to create a PostScript file. Then Acrobat Distiller converts the PostScript file to PDF. The Save-As method combines these two steps into a single step to make things easier for you.

Before you start creating a PDF file, be sure to review the many options available to exercise control over how source information is output in the section "PDF Setup" earlier in this chapter. When you are ready to create a PDF file, first setup Acrobat Distiller as the default PostScript printer:

  1. Select File > Print Setup.

    The Print Set window appears.

  2. Select Acrobat Distiller from the Printer drop-down menu.

    Acrobat Distiller is displayed in the menu and is included in the information area directly under the menu.

  3. Click OK.

    An alert about the font information in the system changing is displayed.

  4. Click OK.

After you set Acrobat Distiller as the default printer, you can convert your single FrameMaker file or book file to PDF by following these steps:

  1. Select File > Save As.

    The Save As window appears.

  2. Navigate to the location in which you want to save the PDF file.

  3. Select PDF from the Save As Type drop-down menu.

  4. Replace the filename extension with pdf.

    Do not change the filename itself, just the extension. If the filename is running.fm, change it to running.pdf. If the filename is running.book, change it to running.pdf. If you do not change the filename extension to PDF, a prompt is displayed after clicking the Save button.

  5. Click Save.

    The PDF Setup window appears.

  6. If you are satisfied with the current settings, click the Set button to continue with the PDF conversion process. If you want to make a change to any PDF setting, make those changes and click the Set button to continue with the conversion process. During the conversion process, a PostScript file is created and Acrobat Distiller is called to complete the process.
Understanding Log Files

A log file is created each time a PDF file is created. The log file is named the same as the PDF, except it has a .log extension. For example, if a PDF file is named filename.pdf, the log file is filename.log. The function of the log file is simply to let you know that the process went well (or didn't go so well). Because log files clutter up your PDF destination directory, you might want to delete them.

Understanding Book Files and PDF Settings

Book files help you work with several included files as a single unit. Book file settings always override individual file settings. When you save a book file to PDF, the PDF Setup window appears. At the same time, all the files included in the book are selected. You must click on the Set button in the PDF Setup window to continue. Clicking on the Set button changes the PDF settings for all the selected files to the current setting in the PDF Setup window. If you click on Cancel, the PDF conversion does not continue.

Back to Basics

Select Format > Document > PDF Setup to access PDF settings from a book file window.

Files included in the book might have varying PDF settings. If you select all the files in the Book File window and view PDF Settings, the Settings window shows the setup from the first-selected file in the list only. This might lead you to believe that all the files included in the book file list have the same PDF settings. Be sure to select the correct setting and click the Set button to effect all the selected files included in the Book Window list.

Distilling to PDF

Previously, you saw how to create PDF files by using the Save As feature in FrameMaker, thereby combining the two steps of creating a PostScript file and distilling that file to PDF. You can also perform this manually to exercise even more control over the resulting PDF file.

Back to Basics

Adobe Acbrobat Distiller creates PDF documents from PostSript information contained in PostScript files.

If you plan to manually create PDF files, you need to understand how to use Acrobat Distiller's settings. Adobe provides an excellent guide to using Acrobat Distiller. Open Acrobat Distiller and select Help > Acrobat Guide to view or print the PDF file.

Take the time to test the settings in Acrobat Distiller to find the ones that work best for your PDF project. After you understand how to use Acrobat Distiller's settings, here are the steps to manually create a PDF file from FrameMaker.

First, set up Acrobat Distiller as the default PostScript printer:

  1. Select File > Print Setup.

    The Print Set window appears.

  2. Select Acrobat Distiller from the Printer drop-down menu.

    Acrobat Distiller is displayed in the menu and included in the information area directly under the menu.

  3. Click OK.

    An alert about the font information in the system changing appears.

  4. Click OK.

After you set Acrobat Distiller as the default printer, you are ready to print your single FrameMaker file or book file to a PostScript file. To do so, follow these steps:

  1. Select File > Print.

    The Print window appears.

  2. Click Print Only to File. Type the filename and path in the text box (see Figure 11.5).

    Figure 11.5. The Print to PostScript File window and the resulting file icon.

    The path and filename are included in the text box. The path means the place where the resulting PostScript file will be located. Do not change the name of the file. Only the extension should be different. For example, if the filename is filename.fm, the PostScript filename should be filename.ps.

  3. Select Generate Acrobat Data.

    PDF Setup is the same as Format > Document > PDF Setup. If you already changed the settings to suit your needs, you do not have to select PDF Setup again. If not, select it here to change any PDF setting.

    If you did not select Acrobat Distiller as the default printer, the Generate Acrobat Data feature isn't available to you.

  4. Click on the Print button.

    Depending on the size of the FrameMaker file, it might take a few seconds or minutes to create the PostScript version of the file.You can expect the size of the PostScript file to be large in size (see Figure 11.5).

After you create one or more PostScript files, you can distill these at any time into PDF. First, start the Acrobat Distiller program. Then follow these steps:

  1. Select File > Open from the Acrobat Distiller window.

    The Open PostScript File window appears (see Figure 11.6).

    Figure 11.6. The Acrobat Distiller Open PostScript File window.

  2. Navigate to the PostScript file that you created in the previous exercise.

  3. Select the PostScript file, then click Open.

    The Specify PDF Filename window is displayed, as shown in Figure 11.7. The filename displays in the File Name field with the PDF extension automatically included.

    Figure 11.7. The Acrobat Distiller Specify PDF File Name window.

  4. Click Save.

    Acrobat Distiller creates a PDF file from the PostScript file you selected. After you're finished, use Acrobat or Acrobat Reader to view or print the resulting PDF file.

Convert to HTML

FrameMaker includes both a built-in HTML conversion feature and a third-party HTML conversion program called WebWorks Publisher. This section focuses on FrameMaker's built-in HTML conversion features.

In its simplest form, converting a FrameMaker document to HTML is as easy as using File > Save As and choosing the HTML file type. However, there's more to the conversion. This section explores some features that you should be aware of before you start an HTML conversion.

It's a good idea to understand the language of HTML and get some experience with it. There are many resources available on the Internet and in bookstores. Here are some recommendations to help get you started:

  • Sams Publishing Teach Yourself Web Publishing with HTML 4 in 21 Days by Laura Lemay

  • HTML for the World Wide Web by Elizabeth Castro (Peachpit Press)

  • Inside HTML by Günter Born (New Riders Publishing)

  • http://www.w3.org: The World Wide Web Consortium

  • http://www.informit.com: Offers a wealth of information. It covers many IT topics, including HTML.

  • http://www.ncsa.uiuc.edu/General/Internet/WWW/HTMLPrimer.html: A beginner's guide to HTML by the NCSA (National Center for Supercomputing Applications)

How HTML Conversion Works

HTML describes the structure of a document rather than its format. FrameMaker's conversion feature works by mapping source paragraphs in the document to HTML elements that describe the document's structure. For example, in HTML, the <H1> tag contains content that is displayed on a Web page as a first-level heading element. In a FrameMaker document, paragraphs tagged with a first-level heading formatting tag would then correspond or map to the <H1> tag in HTML. If the FrameMaker document has bulleted lists, each paragraph included in the bulleted list would correspond to the <li> tag, which designates a list element. Here is a simple example of how this works: Figure 11.8 shows a simple document page in FrameMaker, its paragraph tags, and the resulting HTML and Web page.

Figure 11.8. A summary of how HTML mapping works.

With this in mind, you have to understand how FrameMaker maps paragraphs in documents to HTML elements. You use the HTML Setup feature in FrameMaker to map corresponding elements.

The HTML Setup feature is an easy-to-use window that contains all the paragraph, character, and cross-reference formats included in the document. The HTML Setup also contains a pre-arranged selection of HTML elements from which you can choose to map each FrameMaker format.

The information in the HTML Setup window corresponds to HTML mapping tables located on reference pages.Therefore, changes made in the HTML Setup window are also changed in mapping tables on reference pages.

Save As HTML

The first time you save a FrameMaker document as HTML, the HTML mapping tables are created or updated with formatting information from the document. This is a good way to get started with converting to HTML. After you create an HTML document, you get an idea of how your document is converting. Therefore, you have better information with which to make adjustments to how information is converted to HTML.

Keep in mind that HTML describes the structure of a document and not its formatting information. Features you expect from formatting-based software programs do not exist in HTML. For example, page breaks are not recognized when converting to HTML. When you convert a FrameMaker document to HTML, the content is converted into one HTML page. Suppose that you have a 10-page FrameMaker document that you save as HTML. The resulting HTML is contained in a single HTML file. When viewed with a Web browser, such as Microsoft Explorer or Netscape, the file appears as a lengthy Web page that you'll have to scroll through to see in it's entirety.

You can use the HTML Setup to split up your FrameMaker document into separate HTML files. For example, you might want a separate HTML file (and, therefore, a separate Web page) to be created each time a Heading2 element occurs.

Here's how to save a document as HTML from an open document window:

  1. Select File > Save As.

    The Save Document window appears.

  2. Select HTML from the Save As Type drop-down menu.

    The Save As Type changes to HTML.

  3. Change the filename suffix to "html" without changing the filename.

    The filename now reads filename.html. Be careful not to change the filename. If you change the filename, links from HTML page to HTML page do not work.

  4. Click on Save.

    An HTML and a set of CSS files are created. You can view the HTML in aWeb browser to see the result. You can also open the file in FrameMaker or any text or HTML editor to view the HTML that was created based on your document's HTML mapping information.

CSS File

You might notice that when you saved the FrameMaker document to HTML, not only was an HTML file created but a CSS file was also created. CSS means cascading style sheet. As discussed earlier, HTML is used for the structural formatting of a document. Cascading style sheets were developed by the World Wide Web Consortium (W3C) as a way to provide more formatting control over certain elements within HTML. For example, with cascading style sheets, you can define all the H1 headers in HTML to be displayed as blue, using the Helvetica font face. For each element in HTML, you can define a particular font size, face, or color.

Cascading style sheets were designed to save you time when applying formatting to HTML. With a style sheet, you can change one control line (for example, H1), and each occurrence of H1 in all the HTML pages that you create will reflect this change.

Although cascading style sheets offer many advantages, a disadvantage does exist. Not every browser supports CSS in the same way, and a user's individual Web browser settings might override the CSS settings of any HTML page.

Although cascading style sheets are not complicated, taking the time to learn how to use them is a must before you try to implement them. If you are interested in learning more about cascading style sheets, the following book recommendations provide good information on this topic:

  • Creative HTML Design.2 by Lynda Weinman and William Weinman (New Riders Publishing)

  • HTML 4 For the World Wide Web by Elizabeth Castro (Peachpit Press)

Working with HTML Mappings

FrameMaker maintains a list of HTML elements that correspond to the paragraph, character, and cross-reference formats in documents. After the HTML mapping tables are created with your document's formatting information, you can make adjustments to that mapping information. The easiest way to make adjustments to HTML mapping is to use the HTML Setup window.

Note

You can select File > Utilities > HTML Setup to access its settings.

Here's how the HTML Setup window works:

  • Map. Choose to Map paragraph formats, character formats, or cross-reference formats. For example, when you select Paragraph Formats, all the paragraph formats included in your document are available in the From drop-down menu.

  • From. Select the format that you want to map from into a FrameMaker document.

  • To. Select the HTML structural element to which you want to map.

Mapping Document Formats to HTML

The HTML Setup window allows you to modify HTML mappings. Here's how to use the HTML Setup window, as shown in Figure 11.9:

Figure 11.9. The HTML Setup window for paragraph mappings.

  1. Select the type of format you want to map (Paragraph Formats).

  2. Select the format in FrameMaker that you want to map from on the left side.

  3. Select a corresponding HTML element to map to on the right side.

It's important to understand HTML when you make adjustments to HTML mappings. Table 11.1 shows a brief overview of how FrameMaker's paragraph formats correspond to HTML elements.

Table 11.1. Paragraph Formats

Mapping Name

Corresponding HTML Element

Usage Description

Heading (Autolevel)

H1, H2, H3, H4, H5, H6

Six levels of headings for chapter titles or subheadings.

Paragraph

P

Body paragraphs.

Preformatted Text

PRE

Text that uses spaces to create indentations with fixed-width fonts such as Courier.

Address

ADDRESS

Set off with indentation or italics.

Block Quote

BLOCKQUOTE, GQ

Blocks of text set off by indentation.

List Item

LI

Items that are part of either a bulleted list or a numbered list.

List Item (Continued)

P

Paragraph following a list item that does not need a number, but is part of the list.

Data Term

DT

Glossary term.

Data Definition

DD

Definition of a data term.

Data Definition (Continued)

P

Paragraph following a data term.

Throw Away

None

Content that is not included in the conversion process.

In a similar fashion, character and cross-reference formats correspond to HTML elements. For more information on each mapping element, refer to either the FrameMaker Reference Manual or the Help menu.

Converting Graphics

Whether you import graphics by reference or copy them into your FrameMaker documents, as long as each of these is contained in an anchored frame, they can be converted to a format for use with your HTML pages. You can determine the format of these converted graphics from the HTML Setup window:

  1. Select File > Utilities > HTML Setup.

  2. Click Options.

    The HTML Options window appears.

  3. Select the graphic file format you want to use.

    Choose GIF for non-photographic images that are composed of fewer than 256 colors, JPEG for photographs that are composed of more than 256 colors, and PNG (public domain format) for non-photographic images that are composed of fewer than 256 colors. Keep in mind that PNG is a new format that is not widely used on theWorld Wide Web at this time.

After you convert a document to HTML, each graphic that was included in the document is saved to a separate file in the same folder as the HTML document, with a new name. For example, if you have 10 graphics in a converted document, the files are automatically named the same as the converted document and numbered sequentially. If you had selected GIF in the HTML Setup options, the resulting graphic filenames included with the converted HTML, filename.html, would be filename-1.gif, filename-2.gif, filename-3.gif .... The resulting dpi of each image file corresponds to FrameMaker's imported dpi scaling of each graphic.

Each graphic file then corresponds to an HTML tag (for example, <IMG SRC= "filename.gif">) in the HTML file that references the image file. After the files are converted, it's important to keep the filenames and location intact or the HTML will not work properly.

URL Links

In converted FrameMaker documents, you might want to include hyperlinks to your World Wide Web documents located somewhere on the Internet or on your local intranet. Web addresses are known as Uniform Resource Locators (URLs). You can add these links in FrameMaker documents, and after the document is saved as either HTML or PDF, the text becomes an active hyperlink.

Note

Before you get started, decide what text you want to become a link after the conversion is complete.

Here are the steps to creating links:

  1. Select the text that you want to become a hyperlink.

  2. Apply an existing character format to the text.

    Choose a character format from the Character Catalog, such as underline or bold.

  3. Click anywhere within the text where you just applied a character format.

  4. Select Special > Hypertext.

  5. Select Message Client from the Command drop-down menu.

    The word "message" appears in the Text field.

  6. Type "URL url_address" in the Text field.

    Do not delete the word "message." The Text field now reads something like this: message URL http://www.newriders.com.

  7. Click New Hypertext Marker.

    When the document converts to either PDF or HTML, clicking on the text to which you applied the character format displays the Web page at that URL.

Web Page Titles

Web page titles are displayed in the title bar of the Web browser window. Web page titles are automatically determined when converting FrameMaker documents to HTML by the first-level heading in that HTML page. For example, suppose that after conversion to HTML, the first-level HTML element tagged with <H1> is Learning to Run. The title of that Web page is "Learning to Run."

If you don't want to use the default title, you can make adjustments from the HTML reference page. After you make this adjustment, the next time you use Save As to create an HTML file, the new title will appear in the title bar of the Web browser.

To make adjustments to the default title, you must make a change to the HTML System Macro table located on the reference page of the source file. Here's an example of how to make this adjustment:

  1. Select View > Reference Pages.

    The first of many reference pages appears.

  2. Use the page-down arrows (or View > Go To) to display the HTML reference pages.

  3. Locate the System Macros Table, as shown in Figure 11.10.

    Figure 11.10. The HTML System Macro Default table.

    You see many HTML tables before you come across the System Macros Table.

  4. Replace the Building Block <$defaulttitle> of the StartoOfDoc Macro with the title you want to use (see Figure 11.11).

    Figure 11.11. The HTML System Macro with a changed title.

    <$defaulttitle> is a Building Block that automatically uses the first H1 heading in an HTML document as the title of that document. If the first-level heading changes and you Save As HTML, the title of that HTML document changes. After you make a change to the System Macro, you must change that macro each time you want to update the title.

Summary

PDF and HTML are widely used to deliver information through the Internet or CDs. Do some testing to decide which method works best for your FrameMaker documents before you delve into either format.

There is more to HTML conversion than what's been discussed in this chapter. You should have a good understanding of HTML before you undertake the HTML conversion task. Keep in mind that documents look different once they become Web pages; if that's not what you had in mind, PDF format might be for you.

Above all, whichever method you decide to use, stay consistent with FrameMaker formats. It makes the entire task much easier.


Chapter 12

Chapter 12. Converting Documents from Other Applications

  • Using Practical Methods
  • The Act of Converting Files
  • Cleaning Up the Mess
  • Resolving Formatting Issues
  • Changing Hard-Typed Numbers to Autonumbering
  • Changing Hard-Typed Bullets to Automatic Bullets
  • Table Solutions
  • Dealing with Graphic Irregularities
  • Cleaning Out the Catalogs
  • Summary

In the real world, you might have written documentation in any number of other popular applications, such as Microsoft Word, Adobe PageMaker, or QuarkXPress. Whether you are just getting ready to make the big switch or have already begun the process of converting documents from other applications to FrameMaker, this chapter is for you.

Technically speaking, converting documentation is as simple as opening a file from another application, such as Microsoft Word, from within FrameMaker. You can use either the File > Open or the File > Import > File menus. It's also as simple as cutting and pasting directly from a source application document, such as PageMaker, to FrameMaker. Sounds easy, right?

That part is easy! What's important to remember is that neither of these methods provide acceptable results. With a little work performed in an organized fashion, you can achieve the results you want and have your document looking great in no time.

This chapter is not really about converting documentation. It's about cleaning up document files after conversion from Microsoft Word, PageMaker, and QuarkXPress. Although there are many more applications that you might use to create documentation, these three applications are commonly used and, therefore, will be used as examples in this chapter.

Using Practical Methods

You can attack the document cleanup problem a couple of ways to achieve great results in your converted documents. First, you can go through your converted document page by page, fixing everything on each page along the way. Although this works, this method doesn't lend itself well to FrameMaker's powerful global features. Using the second method, which I call Assembly Line Style, you make passes through the document for each task you need to carry out until you completely clean up the document.

Assembly Line Style

Here's an overview of how Assembly Line Style works. Break down the document cleanup into particular tasks. Then perform each task from the first page to the last. When the first task is complete, return to the first page and start the second task, and so on. If you have a need for speed, this is the way to go.

This method works well for a number of reasons. First, while performing each repetitive task, it's easy to get a good pace going, which makes this a great timesaver. For example, if you use keyboard shortcuts, it's easier to do the same keyboard shortcut over and over than it is to switch to a different set of keyboard shortcuts. When you make the same changes over and over again, you can take advantage of FrameMaker's powerful global change functions, thereby shifting some of the more tedious tasks to the computer. Next, if you are looking for and fixing one type of formatting problem on each page, it's naturally easier to spot them when you keep an eye out for one type of problem. Finally, FrameMaker's powerful global features work well one task at a time. By starting with the largest common denominator, the most troublesome and widespread problems get completed first. You start to see the document shaping up quickly.

If you work with a coworker, you can split up the tasks. Suppose that you only do tasks A, B, and C, and you pass the document to your coworker to perform tasks D and E. Yet another idea to make the job go even faster.

The Act of Converting Files

Before you start converting documents from another application, it's a good idea to take a look at the source document to determine what elements and styles are used throughout:

  • Formatting styles (including paragraph and character)

  • Table formats

  • Imported graphics

  • Numbered lists

  • Bulleted lists

Write the pertinent information on a hard copy of the document and keep it handy.

Developing a Strategy for Converting Files

Consider converting your most recent documents that you plan to work with right away. With a solid conversion/cleanup plan, you get a better idea of how much time each set of documents takes. If you have a massive number of pages to convert, convert and clean up a couple of the most difficult documents first to determine your worst-case scenario.

Working with Microsoft Word Text

You will have less work to do if you have the exact names for paragraph tags in FrameMaker as the source style tags in Microsoft Word. For example, if the chapter heading in Microsoft Word is named Heading1 and the equivalent paragraph tag in FrameMaker is named Heading1, the tagging process is easier. If your Word style names don't match your FrameMaker paragraph tag names, don't worry. Read through the section "Working with Paragraph Formatting," later in this chapter, for details on how to perform this task nearly effortlessly.

Methods for Importing Files

There is always more than one way to do things in FrameMaker. Here are two methods to get your Microsoft Word document into FrameMaker.

Open the Word Document from Within FrameMaker

You can open Microsoft Word files directly in FrameMaker by using the File > Open menu. After you select the file that you want to open, FrameMaker displays a window with a list of available conversion filters. The appropriate Microsoft Word filter is automatically selected. If FrameMaker cannot figure out what file type you are attempting to open, go back to your Word document and save it as an RTF before trying again.

Be patient: It can take up to a couple of minutes to open the file, especially if it's large with many tables or graphics.

Back to Basics

Making changes to a paragraph property without applying it to the predefined format in the catalog is known as a format override. An asterisk (*) will be displayed next to the tag name in the status bar.

When you finish opening the Word document in FrameMaker, open the FrameMaker template that you plan to use and import all the formats into your new document.

Import into an Existing FrameMaker Document

You can open an existing FrameMaker document and import a Microsoft Word file by selecting Import > File from the File menu. If you choose this method, be sure to select Copy into Document. If you select Import by Reference, you will have a referenced text file, otherwise known as a text inset.

After FrameMaker converts the file, the Import Text Flow by Copy window is displayed (see Figure 12.1). Be sure to select the following:

Figure 12.1. The Import Text Flow by Copy window settings.

  • Body Page Flow under Flow to Import

  • Reformat Using Current Document's Formats

  • While Importing, remove Other Format Overrides

This ensures that, if Word styles have the same names, the FrameMaker style takes precedence and you won't have format overrides for any individual paragraph that has the same name.

Working with PageMaker or QuarkXPress

Although FrameMaker's filters support many standard file types, PageMaker and QuarkXPress are not among them. Don't despair. There are some options you can use as a workaround that I review in more detail.

Exporting Text from PageMaker and QuarkXPress

Use this option if your file fits either of the following criteria:

  • Text is contained within one big text block.

  • Styles were applied to the text throughout the document.

This is the perfect combination for exporting text to a Microsoft Word or RTF file. Styles are retained when text is exported, and all the text will be retrieved because it is contained within one big text block.

After you finish exporting text to Microsoft Word, read through the section "Working with Microsoft Word Text" earlier in this chapter. Keep in mind that any graphics that reside in the original files must be reimported into FrameMaker. It's a good idea to make note of the location of these graphic files.

Cutting and Pasting from PageMaker and QuarkXPress

Use this option if your file has text that is contained within many text blocks throughout the document.

Tip

Check your computer's memory to be certain that you can open these two applications at the same time.

Whether you used styles or not, if text is broken up into many text blocks within each document, exporting to a Microsoft Word or RTF file will be problematic. All those little chunks of text will be a nightmare to figure out.

The best way to convert this type of document is to open the source file in PageMaker or QuarkXPress and open the FrameMaker template you plan to use at the same time.

Go through the source file page by page, select all the text in a text block, and copy and paste that text into your FrameMaker template. This process is tedious, but everything will be intact and in the correct order. After you finish, apply FrameMaker formats to the text.

Cleaning Up the Mess

You might have already discovered that there is a significant amount of cleanup after conversion, despite the care taken to develop a slick, great-looking FrameMaker template. Whether you have already made this discovery or are about to embark on the adventure, this chapter guides you through key techniques to solve the most common problems with minimal headaches.

You've already noticed how messy the text and other elements look after opening or importing a Microsoft Word file into FrameMaker. Usually, this mess consists of empty paragraph returns, tab stops piled on top of each other, tables split, elements in the wrongs places, and paragraphs formatted incorrectly.

Begin your Assembly Line Style of clean up with the small stuff, like empty paragraph returns and tabs before starting paragraph formatting, tables, or graphics. For each task, start at the first page and work your way through the last page before you move on to the next task.

Empty Paragraph Returns

Back to Basics

Turn on Text Symbols from the View menu to see non-printing characters, such as empty paragraph returns.

Traditionally, users of Microsoft Word tend to hit the Enter key on the keyboard to skip lines between paragraphs rather than use the preferred FrameMaker method of a fixed amount of space before and after each paragraph. After importing your Word document into FrameMaker, you might see empty paragraph returns throughout the document. This gets you in trouble with FrameMaker, because FrameMaker uses paragraph tags with many other features, such as variables and generated files. Although you did not specifically apply a paragraph tag to an empty paragraph return, FrameMaker has already assigned one to it. Therefore, the first step in successful conversion is to get rid of all the empty paragraph tags in the entire document and rely on Space Above/ Below instead to determine spacing between paragraphs. FrameMaker's ultra-cool Find/ Change helps clean up this mess quickly:

  1. Select Find/Change from the Edit menu.

  2. Type \p\p in the Find text field.

    As a result, FrameMaker searches for two consecutive end-of-paragraph symbols: the paragraph symbol at the end of a paragraph that is needed, and the empty paragraph symbol on the next line.

  3. Type \p in the Change To text field.

    When two consecutive end-of-paragraph symbols are found, they are replaced with one end-of-paragraph symbol. The symbol that is not needed is deleted.

  4. Click on Find to find the first two end-of-paragraph returns (see Figure 12.2), then click on Change or Change & Find.

    Figure 12.2. The "before and after" shots of extra paragraph symbol deletion.

    Using Change All is not a good idea, in case anchored frames or tables are purposely anchored to empty paragraph symbols. You want to keep these intact.

Deleting Tab Piles

Microsoft Word uses relative tab stops. Simply put, users can press the Tab key more than once to move text along repeating tab stops. This results in many tab symbols piled on top of each other in your FrameMaker document. If you have ever tried this, you already know that it's almost impossible to select each tab symbol for deletion unless you want to work in 1,600% view. Find/Change comes to the rescue for deleting all those unnecessary tab symbols.

Back to Basics

FrameMaker uses absolute rather than relative tab stops. Therefore, the nth tab on a line moves to the nth tab stop.

You might want to perform this step after you resolve the formatting issues in the next section. Then you won't delete the "real" tab stops. When you are ready, follow these steps:

  1. Select Find/Change from the Edit menu.

  2. Type \t in the Find Text field.

    \t is the symbol for tabs. As a result, FrameMaker searches for tab stops.

  3. Make sure the Change to Text field is empty. If any text is in there, be sure to select the text and press the Backspace or Delete key on your keyboard.

  4. Click on Find, then click on Change & Find, if appropriate.

    FrameMaker selects and replaces each tab with absolutely nothing. To avoid deleting tabs that are necessary in the document, don't use the Change All option.

Resolving Formatting Issues

You should have made a couple of passes through your document by now. This next task can be a little tricky; even under the best conditions, you will likely have various formatting issues to resolve. Don't assume that, because Word styles are named the same as the FrameMaker tags, a problem won't occur.

The Paragraph Catalog now includes the Microsoft Word style names in addition to the FrameMaker paragraph tag names. If the names are identical, duplicates do not occur.

If the Microsoft Word document contained character style names that were used in the document, these are displayed in the FrameMaker Character Catalog in addition to the original character tag names in your FrameMaker template.

Don't be concerned yet about deleting the unwanted tags from the Paragraph and Character catalogs. You can fix this later.

Working with Character Formatting

Tip

You should fix character formatting before paragraph formatting. If font problems occur during conversion and paragraphs are formatted first, character formats can get lost.

Character formatting that came along with imported files fall into two categories: those with character format tags and those without. Assuming that the source Microsoft Word document had a named character style that was used throughout the document, these will appear in your FrameMaker character catalog. They are easy to fix through the Character Catalog.

Characters formatted without character tags are just as easy to fix with FrameMaker's powerful Find/Replace tool.

Character Formatting with Character Format Tags

Here is a good way to change imported character tags to character tags that are part of your FrameMaker template: Suppose that the character tag Bold is part of your FrameMaker template and the character tag Strong came along with the Word import. You don't want two character tags that are essentially the same thing. Here is the one-minute way to change all occurrences of the character tag from Strong to Bold:

Back to Basics

After you apply the Bold character format to text, the character tag Bold is displayed in the status bar.

  1. Using the Character Catalog, apply the character tag Bold to selected text.

  2. With the bold text selected, press Ctrl-D to display the Character Designer.

    Bold is displayed in the Character Tag name box.

  3. Select Commands > Global Update Options.

  4. Select Strong from the All Tagged drop-down menu (see Figure 12.3).

    Figure 12.3. You can easily update all characters tagged as Strong to Bold.

  5. Press Update and watch FrameMaker change all occurrences of Strong to Bold.

    After you finish, Strong continues to be displayed in the Character Catalog. You can delete this later.

Do this for all character tags that you need to change in your FrameMaker document. Next, learn how to easily apply character tags to styled text without a character tag.

Character Formatting Without Character Format Tags

Back to Basics

To check if styled text has a tag name associated with it, click anywhere within the styled text and look in the status area. If a character tag is not displayed, this is styled text only.

Your imported Word document might have lots of styled text (such as bold and italic) without a tag name associated with it. You have the option to leave these as they are. However, if you need to make a global change to styled text, character tags are the way to go.

First, assess how many variations of styled text are incorporated in the document and map out which FrameMaker character tag will be applied to each variation. For example, you might want to tag italic-styled text with the Emphasis character tag.

Back to Basics

Character Format refers only to the particular properties of characters, such as italic, bold, or CAPS, and may or may not be associated with a character tag.

Start with one variation of styled text and find the first occurrence. For this example, suppose that there is italic-styled text throughout your document with no character tag association. A character tag is in your FrameMaker template for italics, called Emphasis, that you want applied to all italic-styled text (see Figure 12.4).

Figure 12.4. The Emphasis character tag in the FrameMaker Character Catalog.

Here's how to do it:

  1. Find two occurrences of italic-styled text. Double-click one occurrence to select it. Apply the Character tag Emphasis to this one only.

  2. Move to the next occurrence of italic-styled text and double-click to select it.

  3. Select Find/Change from the Edit menu and choose Character Format (not the tag) from the Find drop-down menu.

    The character format of the selected text is displayed in the dialog window, as shown in Figure 12.5. Click Set.

    Figure 12.5. The character format of the selected text is displayed.

  4. When you return to the Find/Change window, the Text field next to the Find > Character Format drop-down menu is empty.

    Everything is going exactly as planned.

  5. Leave the Find/Change window for a moment and return to your document. Find the first occurrence of italic-styled text that you already applied the character tag Emphasis to in Step 1. Double-click to select it.

    You see the name Emphasis displayed in the status bar of your document window.

  6. Select Edit > Copy Special > Character Format.

  7. Return to the Find/Change window and select By Pasting from the Change drop-down menu (see Figure 12.6). Click one time in the text field to the right of the Change drop-down window; press Control V (which is a keyboard shortcut for Paste) on your keyboard.

    Figure 12.6. The Find/Change window for character format setup.

    Using the Edit > Paste menu does not work in the Find/Change window.

  8. Press Find and then press Change to find occurrences of italic-styled text and apply the character tag Emphasis.

    This is a good task for the Change All button.

Working with Paragraph Formatting

Paragraph tags that came along with imported files fall into four categories:

  • Those with the default Word Normal style applied to everything in the document

  • Those that have the same name as the FrameMaker tags with no format overrides

  • Those that have the same name as the FrameMaker tags with format overrides

  • Those that you no longer need and want to convert to an existing FrameMaker tag

Your converted text might fall into one of these categories or might be a combination of all four. In any case, you might want to have a printed hard copy of the original Word document handy for verification of paragraph styles that got completely obliterated during conversion to FrameMaker.

If your converted Word document has tables, the text within those tables needs to be included in your paragraph-formatting fixes. Don't worry about the table itself; you fix that in the next section.

Most Paragraphs Are Tagged with Word's Default Normal Style

The solution to this problem is the most work. Get a cup of coffee, and start on the first page. Have fun. If more than 90 percent of your document is tagged with Word's default Normal style or some other style, the easiest way to solve this is to select the entire document and apply the FrameMaker paragraph tag that is most widely used in your document. For example, if the FrameMaker tag Body is widely used, select it to apply it to everything in your document.

After you finish, go through your document one page at a time and apply the correct paragraph tags to everything that should not be tagged with Body.

Same Name as the FrameMaker Tags with No Format Overrides

You're in great shape! If Word's paragraph style names match the FrameMaker paragraph tag name and you encountered no format overrides, you don't need to fix those particular paragraph formats.

Same Name as the FrameMaker Tags with Format Overrides

First, review how you got the Word file into FrameMaker in the first place. If you used the import method, you should have had the Remove Other Format Overrides checked (refer to the section "Import into an Existing FrameMaker Document" on page 354). If you didn't check this, don't worry; you can correct this easily.

To get rid of the format overrides, open up the original FrameMaker template and import the formats to the current document. Be sure to check While Updating Remove > Other Formats/ Overrides. This clears up the format overrides in the document.

Changing Paragraph Format Tags

The method used to change imported paragraph tags to the tags in your FrameMaker template is similar to the method used to change the character tags. Say that the paragraph tag H1 is part of your FrameMaker template, and the equivalent paragraph tag Heading1 came with the Word import. You don't want two paragraph tags that are essentially the same thing. Here is an easy way to change all occurrences of the paragraph tag Heading1 to H1:

  1. Using the Paragraph Catalog, apply the paragraph tag H1 to a paragraph that you want to change.

  2. With the insertion point still in the paragraph, press Ctrl-M to display the Paragraph Designer.

    H1 is displayed in the Paragraph Tag name box.

  3. Select Commands > Global Update Options.

  4. Make sure that All Properties is selected. Select Heading1 from the All Tagged drop-down menu.

  5. Press Update.

    You encounter an alert message, "OK to change all Heading1 to H1". Click OK and watch FrameMaker change all occurrences of Heading1 to H1.

    After you finish, Heading1 is still displayed in the Paragraph Catalog. You delete this later.

Changing Hard-Typed Numbers to Autonumbering

You might encounter hard-typed numbers in your converted document rather than autonumbers. If autonumbering was used in Microsoft Word, the autonumbering stays intact once the document's in FrameMaker. You can simply apply the correct autonumbering paragraph tag in FrameMaker and it takes care of itself.

If not, you end up with hard-typed numbering along with the autonumber after you apply the correct FrameMaker paragraph tags (that contain autonumbering).

Winning Number Combinations

As usual, you can fix this annoying problem in many ways. You can manually delete all the hard-typed numbers and accompanying tabs or spaces, one at a time. Or, you can delete the hard-typed numbers in under a minute with Find/Change.

It's a good idea to start with double-digit numbers. If you begin your search with single-digit numbers, FrameMaker finds the second number of the double-digit number, and you will still be left with the first-place number of the double-digit number.

Here's how to do it:

  1. See the earlier section "Working with Paragraph Formatting," and apply the correct FrameMaker paragraph tags to all numbered paragraphs. The result looks like the result shown in Figure 12.7.

    Figure 12.7. The result of hard-typed numbers and autonumbering applied.

  2. Look at the individual paragraph. The first number is the autonumber and the second number is the hard-typed number, as evident by the ability to select it.

    The next goal? Discover what is included with the hard-typed number. In this example (see Figure 12.8), a double-digit number followed by a period and tab make up the winning combination. You need to know exactly what you're looking for in order to delete it easily.

    Figure 12.8. An example of a winning number combination.

  3. Select Find/Change from the Edit menu. In the Find drop-down menu, select Text. Type [1-9][0-9].\t in the text field. Just below that, select Use Wildcards.

    Breaking it down, in this case, wildcards allow you find any one of characters within the range inside the square brackets. The [1-9] searches for a number between 1 and 9, while the [0-9] searches for a number between 0 and 9. Both numbers are combined with a period followed by a tab symbol. The Find/Change window looks like Figure 12.9. In this example, the first occurrence is found. If you forget to check the Use Wildcards, this search does not work.

    Figure 12.9. The Find/Change window search example with the first occurrence found.

Tip

When you search for double-digit numbers, the wildcard [1-9][0-9] is necessary because the second digit in the combination might be a zero (such as 10, 20).

  4. Make sure that there are no text or spaces in the Change To text field; if so, that becomes the replacement text. After you find the first occurrence of a number combination, click on Change or Change & Find.

    The number combination is deleted. Continue changing the remaining hard-typed numbers in your document. This search is conducive to using Change All.

Single-Digit Numbers

The previous example discusses double-digit numbers. After you complete searching and replacing double-digit numbers, begin your search for single-digit numbers.

For single-digit numbers that include a period and tab symbol, type [1-9].\t in the Find/ Change Text field, as illustrated in Figure 12.10.

Figure 12.10. Start your search for single-digit nmbers.

More Winning Numbering Combinations

A typical numbering combination to search for has already been discussed. The combination that you actually search for will differ from document to document, based on the source document text. These are not limited to numbered lists. You can encounter numbered headings with the same problem. Table 12.1 lists other combinations that can be present in your document and the wildcards to search with.

Table 12.1. Number Combinations Used in a Wildcard Search

Combination in Document

What to Type in Find/Change

1.0 space

[1-9].[0-9](hit space bar one time)

1.1.1tab

[1-9].[0-9].[0-9]\t

1)tab

[1-9])\t

1. space

[1-9].(hit space bar one time)

11)space tab

[1-9][0-9] \t

Changing Hard-Typed Bullets to Automatic Bullets

This one will be easy if you already fixed the hard-typed numbers. Hard-typed bullets might end up in your converted document rather than automatic bullets. Go ahead and apply the correct FrameMaker paragraph tags (that contain automatic bullets).

Another gotcha to look out for in bullets is funny-looking or odd characters that come along with the import. For example, if special symbols were used to create bullets in Word, when these are displayed in FrameMaker, they might look something like Figure 12.11 (or some other character).

Figure 12.11. Those funny-looking characters that try to replace bullets.

The example used in this section focuses on regular-looking bullets that were hard-typed. If funny-looking or odd characters came over instead, just substitute those as you work through the example.

After you apply the correct FrameMaker paragraph tag with automatic bullets to a paragraph with hard-typed bullets, the result might look something like what's shown in Figure 12.12.

Figure 12.12. The automatic bullet and hard-typed bullet together.

It's a bit messy, but it's basically made up of the automatic bullet and tab, followed by the hard-typed bullet and manual tab. The manual tab symbol has no tab position to move to, so it just sits there practically on top of the first character in the sentence (with no purpose). Understand what yours is made up of before you do the grand find and replace. Here's how to wipe out the hard-typed bullets and tabs quickly:

  1. See the earlier section "Working with Paragraph Formatting," and apply the correct FrameMaker paragraph tags to all bulleted paragraphs.

  2. Looking at the individual paragraph, the first bullet and tab are automatic and the second bullet is hard-typed, as is evident by the ability to select it. The goal now is to discover what's included with the hard-typed number. In Figure 12.13, you can easily see that a tab symbol follows the bullet. You need to know exactly what you are looking for in order to delete it easily.

    Figure 12.13. What's included in the hard-typed bullets.

  3. Select Find/Change from the Edit menu. In the Find drop-down menu, select Text. The best way to conduct this search is to copy and paste one of the hard-typed bullets into the Find Text field. Although the bullet might look correct in the document, it might actually be some type of odd character that won't reveal itself until it's copied into Find/Change. For this example, the first occurrence has been found, as seen in Figure 12.14.

    Figure 12.14. The first occurance of hard-typed bullet found with Find/ Change.

Tip

When pasting into the Find Text field, use Ctrl-V. The Edit > Paste will not work.

  4. Make sure that no text or spaces are in the Change To text field, or those will become the replacement text. After you find the first occurrence of a hard-typed bullet, click on Change or Change & Find. This is a good search in which to use Change All.

Use this method to search for hard-typed dashes or other characters that you are replacing with automatic characters.

Table Solutions

Tables are fun in FrameMaker because of its powerful table functions. These functions make it easier to fix tables imported from Word. When tables come over from Word, a number of things can, and will, go wrong. For example, you'll notice that although you have applied a FrameMaker table tag to an imported Word table, the table still does not take on the characteristics of the applied table tag format. No, you are not doing anything wrong; this is completely normal.

Next, if the Word tables had heading rows, these will not be recognized as such in FrameMaker. Finally, tables might also split into pieces of rows. Don't panic, because everything can be fixed.

Applying Table Format

When you import or open Word files in FrameMaker, all the imported tables are automatically tagged with Format A. If Format A doesn't exist in your FrameMaker template (you might have deleted it at some point), it reappears in the document but is not included in the Table Tag Catalog list. You must click anywhere in the table, press Ctrl-T to display the Table Designer, and view Format A in the Table Tag drop-down menu.

This is good news! Every table will have a table tag associated with it, thus making this task easier.

Remember the Assembly Line Style? Use this method as you go through the table-reformatting process. In other words, one table task at a time from the first page to the last page.

The first task is to change the table tags from Format A to another table tag. (If you want to use Format A, skip this step.) Here's how to do it:

  1. Determine which table tag will be used most of the time in your document.

  2. Click one time inside the first table you come upon. Press Ctrl-T to display the Table Designer. Format A is displayed in the Table Tag drop-down list but still is not stored in the official Table Catalog. You must add it to the catalog temporarily. Press Apply to Selection and add it to the Table Catalog.

  3. With the insertion point still inside the table, select the table tag you plan to use most of the time in your document, and press Apply to Selection.

  4. Select Commands > Global Update Options.

  5. Make sure that All Properties is selected. Select Format A from the All Tagged drop-down menu.

  6. Press Update and watch FrameMaker change all occurrences of Format A to Format X. After you finish, Format A is still displayed in the Paragraph Catalog. Feel free to delete Format A.

After you finish changing all the table tags from Format A to Format X, move on to the next task.

Fixing Table Formatting

As mentioned earlier, although the imported tables are tagged with the correct table tag, they will not reflect the characteristics of that table tag format. There are a couple of tasks you need to do to fix this: First, go to each table in the document. A good method to use is Edit > Find/ Change. Select Any Table from the Find drop-down menu and press Find. The reason this is such a great method is that the next available table will immediately be found and the table will be selected in its entirety.

Next, here's how to strip the Word formatting from the table:

  1. With the table entirely selected, select Table > Custom Ruling & Shading.

  2. Select both Custom Cell Ruling and Custom Cell Shading.

  3. Select From Table in the Apply Ruling Style, Fill and Color menus. Be certain that every item is checked under To Selection, as illustrated in Figure 12.15.

    Figure 12.15. Stripping Word's formatting from an imported table.

  4. Click on Apply. The current table now takes on the characteristic of the table tag. Continue to change all the tables in the document.

Tip

Keep the Custom Ruling & Shading window and the Find/Change window off to the side on your screen. Then just two quick clicks from both windows will get you through your document faster.

Where's the Header Row?

Although the tables might have had the header row intact in Word, the header row will not be recognized as such in FrameMaker. You need to individually add a header row to each table and then cut and paste the header text into the row.

Is there an easy way to do this? Not really. But, if you use the Assembly Line Style, it's easier and faster to do one repetitive task throughout the entire document. Here's how to do it:

  1. Use Edit > Find/Replace to move from table to table.

  2. With a table selected or place the insertion point anywhere in a table, select Add Rows or Columns from the Table menu.

  3. Type the number of rows you want to be included in the heading row(s). Then select To Heading from the Add Rows To drop-down menu. Click on Add.

  4. Select the row with the actual text included. Either manually select the row or type Esc t h r.

  5. Select Edit > Copy.

  6. Place the insertion point anywhere in the new header row that you added and press Esc t p r. The header text is copied into the header row.

  7. Delete the old header row. Continue with all the tables in the document.

Dealing with Graphic Irregularities

Tip

When converting a document from PageMaker or QuarkXPress, you have to reimport the original graphic files into FrameMaker.

Although many things can go awry with graphics that are part of an imported Word document, this section focuses on just a couple of unquestionably common misbehaviors.

Keep in mind that, after conversion, the graphics are technically treated as being copied into your FrameMaker document. Your FrameMaker document ends up being a bit larger in file size if you have many graphics. To get your file lean and mean, you have to work with referenced graphic files instead. If you choose this method, you must reimport each original source graphic file into your FrameMaker document by reference.

Although graphics imported from Word are contained in an anchored frame, you might notice a couple of irregularities. First, the anchored frame is usually positioned at the insertion point. Next, if you have View > Borders turned on, the outline of the anchored frame is still invisible, which makes it difficult to select for editing. Here's how to fix it:

  1. Check to make sure Borders is turned on (View > Borders).

  2. Select the imported anchored frame. At this point, you won't be able to see the outline of the anchored frame, so take your best guess and click in the general area to select it. After you select it, the anchor points around the outline become visible.

  3. Display the Tools palette. Click on the Pen tool and select None. The outline of the anchored frame is displayed.

  4. Select the anchored frame by clicking on it one time and edit to your liking (Special > Anchored Frame).

Cleaning Out the Catalogs

You made it to the final step of cleaning up your imported Word document. By now, the Paragraph and Character catalogs have accumulated a massive amount of unneeded tags that came over from Word. Trying to weed out the odd ones is a tedious task.

Here's an quick way to clean out the catalogs:

  1. Open a clean FrameMaker template, exactly the same as used in your current document.

  2. Go to the current document (the one with the messy catalogs). Delete all tags from both the Character and Paragraph catalogs.

  3. Use File > Import > Formats to import the paragraph and character formats from the original FrameMaker template. The Paragraph and Character catalogs display a clean set of tags.

Tip

Using File > Utilities > Create & Apply Formats does not work well in this case if all the paragraph tags needed in the template are not currently used by the content of the document.

Summary

Now that you understand how to clean up the aftermath of a converted document from another application in FrameMaker, you're better equipped to implement a solid plan to clean things up efficiently.

Taking it one task at a time breaks the cleanup process into neat, well-defined task work and is much faster than trying to do all the tasks at one time on each page.

It's important to remember that your document might have even more problems than discussed herein. Always examine the converted document first to discover what those problems are. This sets your stage for similar documents in the future.


Chapter 13

Chapter 13. Typical FrameMaker Headaches

  • Working with Inherited Templates
  • Understanding Format Overrides
  • Working with As Is Checkboxes
  • Fixing Unresolved Cross-References
  • Working with Missing Fonts
  • Solving Book File Errors
  • Adding Page Number Prefixes in Generated Files
  • Working with Multiple Page Number Styles in an Index
  • The Running Headers or Footers Appear Empty
  • The Table of Contents Contains Empty Lines
  • Freezing Pagination
  • Excluding the .fm Extension in a Filename Variable
  • Fixing Tables Imported from Microsoft Word
  • Including Running Headers or Footers Across Files
  • Summary

As a FrameMaker user, it's likely that you've run into some typical headaches while performing everyday tasks. Most everyone's seen the dreaded Missing Fonts error message, run into FrameMaker templates that are hard to understand, or have been presented with a variety of documentation problems to which there is no obvious solution.

In this chapter, you learn how to approach and solve some common problems that you might encounter while working on your documents.

Working with Inherited Templates

If you are working with inherited FrameMaker templates that have no accompanying documentation or verbal instruction, take the time to understand the template and how it works before you dive into a project. You can reduce the amount of time by putting together a quick template guide for yourself to use as a cheat sheet while you get better acquainted with the template.

This section reviews some steps you can take towards getting up to speed quickly with an inherited template. Before you begin, create a new, untitled document using the predefined formats from the inherited template. Then input information about the template into the new document and print it for use as a guide.

To create a new, untitled document using the inherited template's format, follow these steps:

  1. Select File > New > Document.

  2. Navigate to the location (on your hard drive) of the inherited template and select that template's filename from the list.

    The template filename appears in the Use Template Text field.

  3. Click on New.

    A new untitled document appears and is ready for you to use.

  4. Save the file with a new filename.

Getting Basic Information About the Template

The first step is to gather some basic information about the template. For example, you need to know the page size, whether it's single- or double-sided, information about header and footer usage, what the column specifications are (single, two-column, or sidehead), how many master pages are included, and what the master pages might be used for.

Table 13.1 lists some commands to get you started with the basic information you'll need about the template. Type the resulting information into the new, untitled document.

Table 13.1. Finding Information About Inherited Templates

Command

Information Found

Format > Pagelayout > Page Size

Page size used in the document.

Format > Pagelayout > Pagination

Single- or double-sided, first page side.

Format > Pagelayout > Column Layout

Determines the number of columns or if sideheads are used.

View > Master Pages

Determines the number of master pages used. The bottom of the document window provides information about the total number of pages.

Double-click on master page header/ footer variables (each one separately).

Displays the Variable window with the variable definition.

See Chapter 4, "Headers and Footers," for more information.

Determines what paragraph tags (if any) are being referenced as source information for headers/footers.

Determines if user variables are being used for a document title displayed in the header and what their definitions are.

Building a Paragraph Tag List

It's likely that your template has a long list of tag names in the Paragraph Catalog. These tags might be meaningless to you if you have no knowledge of each tag's usage or its formatting properties. Therefore, the next step to discover the inner workings of the template is to build a list of used paragraph tags. Although there is no automated method to do this, you can accomplish this task in less than 20 minutes.

In your template guide file, display the Paragraph Catalog and get ready to type. Type the name of the first paragraph tag name in the Paragraph Catalog list, then click on that tag name in the Paragraph Catalog to format the typed text with that tag's properties. Press Enter and do the same for each paragraph tag in the list.

If you discover particular paragraph tags referenced in running header or footer variables (such as Running H/F1), type that information next to the tag name as a note to yourself. In addition, if you discover paragraph tags with numbering properties, type the numbering property next to the corresponding tag name in your list. You can easily copy and paste this information from the Autonumber Property Text field to your document.

You end up with a list of all the paragraph tag names and the aesthetic design of each one, as shown in Figure 13.1.

Figure 13.1. You can create a list of paragraph tags in your inherited template.

Building a Character Tag List

You can build a character tag list in the same way you build the paragraph tag list. Because character formats affect selected text and not a paragraph (unless the entire paragraph is selected), you can type the character tag name on one or two lines, select each typed name, and apply the corresponding name from the Character Catalog, as shown in Figure 13.2.

Figure 13.2. Creating a list of character tags is similar to creating the paragraph tag list.

Determining Font Usage

Notes

If you encounter the Missing Fonts message, read "Working with Missing Fonts" later in this chapter.

Whether your documents will result in print, PDF, or if you plan to share files with others, it's a good idea to know the names of the fonts that are used in the template. If you have not encountered the Missing Fonts message, you can generate a list of fonts that are used in the file after you build your list of paragraph tags (as discussed previously).

From the document window, generate a list of font references. This results in a list of fonts that are currently applied to all the text in the document. Therefore, if you had a paragraph tag with a particular font that was not applied to any text and you generate a list of font references, this font will not show up in the list (unless it is being used in a different paragraph tag that was applied to text).

The resulting list is generic-looking, but the point of this exercise is to get the names of all the fonts used in the document. To generate a list of font references, follow these steps:

  1. Select Special > List of > References.

    The Standalone List of References alert message appears. The message reminds you that you are creating a generated list for an individual file and not a book file.

  2. Click Yes.

  3. In the Don't Include list, double-click on Fonts to move it to the Include References list.

  4. Select Set.

    FrameMaker generates a list of font references. You can format the list if you want. See Chapter 8, "Creating Tables of Contents and Other Lists," for more information on formatting generated lists.

Finding Other Document Elements

You can get information about many more document elements, including cross-references, table formats, and conditional text settings.

Continue gathering information about the template by inserting tables using the various included formats. Type the name of each format along with the table to use it as a good reference later (select Table > Insert Table).

Place several cross-references in your template guide that use the same source information. Then use a different cross-reference format for each one to understand the differences between them (select Special > Cross-Reference).

If you are using conditional text, check to see what condition tags are available along with their characteristics (select Special > Conditional Text).

After you include all these pieces of information in your template guide, you'll be more familiar with the included features of the template and how to best use it for your projects. You might even find ways to improve what's already there.

Understanding Format Overrides

FrameMaker uses predefined formats for Paragraph, Character, and Table Designers, as well as page layouts. If you make a change to paragraph, character, or table formats, and use the Apply To button rather than the Update All button, you end up with a format override. Making changes to paragraph text using the formatting bar also causes this result. In the same way, if you change the column layout of a body page without first changing its corresponding master page layout, you end up with a format override for that body page. Format overrides are common and occur as a result of a change you made to a particular selection that no longer matches the predefined format.

Paragraph and character format overrides are indicated by an asterisk (*) in the status bar. Table and page layout overrides have no indicators. If you include format overrides in documents, each time you make a change to the predefined format, the Format Override window appears, as shown in Figure 13.3.

Figure 13.3. The Format Override window.

Now's a good time to review how format overrides work after they are included in documents. Using the predefined paragraph tag Body as the example, suppose that you have several paragraphs tagged with Body. The Basic properties indicate that Indent: First is 0 inches. If you were to change one paragraph tagged with Body, to Basic > Indent > First to .5 inches, and click Apply To rather then Update All, you would effect a change in that paragraph only, creating a format override. After you include the format override, if you decide later to make another change to the predefined Body tag and select Update All, the Format Override window appears. The following choices are available in the Format Override window:

  • Retain Overrides. Results in the predefined format being updated with the indicated change, and the paragraph with the format override continuing to include its override, as well as the new change.

  • Remove Overrides. Results in the predefined format being updated with the indicated change, and the paragraph with the format override reset back to the predefined format, no longer including the format override.

The only time you won't see the Format Overrides window is if you use Update All to change the predefined format and your insertion point just happens to be in the paragraph with the Format Override. If you do not notice this and make changes to the Paragraph Designer using Update All, the format override becomes part of the predefined format.

You can eliminate format overrides at one time in a document by using the Import Formats commands. To eliminate format overrides, have a clean template handy. The clean template is identical to the file containing the overrides. Follow these steps to import the formats from the template to the document with the overrides:

  1. Open the original template and the file with the overrides.

  2. With the override file active, select File > Import Formats.

  3. Select the clean template as the Source Document.

  4. Select all items in the Import and Update list.

  5. Select While Updating Remove: Other Format/Layout Overrides.

  6. Click on Import.

    The formats from the template are imported into the file. All format overrides are eliminated, whether they are paragraph, character, table, or page layout.

Working with As Is Checkboxes

FrameMaker's As Is setting is a powerful feature that can be tricky. As Is can appear in the Paragraph, Character, and Table Designers, or other dialog boxes. The most common use of the As Is feature is in character formats. As Is allows you to determine what properties will be changed and what properties will not be changed as a result of applying a character format to text. This is why you can create one character tag, Italic, for example, apply it to text of any font family and size, and retain both the font family and size of text while changing only the angle. In this case, the font family and size are set to As Is and only the Angle property is specifically defined as italic.

You might have run into the As Is feature while viewing Paragraph Designer properties after selecting more than one paragraph in a document whose properties are different from each other. For example, suppose that you select two paragraphs whose Default Font properties are different. If you look in the Paragraph Designer > Default Font, the Family pop-up menu shows As Is.

As Is can also change one or more properties of any paragraph, character, or table tags at one time, without changing any other property of the same tag. For example, you can change one specific property of many paragraph tags, without affecting the remaining properties.

The As Is feature is tricky to use in dialog window checkboxes. For example, if a particular checkbox setting is turned on and you want to turn it off, you would normally click the checkbox one time. Clicking the checkbox one time changes the setting to As Is, which is usually indicated by a greyed out checkbox. You have to click the checkbox two times in order to change the selection to the state that you want (in this case, Off).

Examine a simple example of how mistakes happen with As Is. Suppose that you have the Body paragraph tag set up with the Hyphenation setting turned on in Advanced Properties (see A in Figure 13.4) and you want to turn off Hyphenation for all Body tags. If you were to click the Hyphenate setting one time and then click Update All Formats Tagged Body, this would have no effect because that selection is As Is and indicates that you are leaving Hyphenation in its current state. The dialog box labeled B in Figure 13.4 shows a checkbox in As Is state.

Figure 13.4. The checkbox selections for the On, As Is, and Off positions.

You must click two times on the Hyphenation checkbox to turn this selection to the Off position, as shown in C in of Figure 13.4, before you select Update All or Apply To.

Fixing Unresolved Cross-References

Sometimes, FrameMaker cannot update cross-references in documents with the latest source information. When unresolved cross-references occur, an unresolved cross-reference message appears, but the exact cause of the problem isn't spelled out for you. Therefore, you must do some detective work to find out what went wrong before you can solve the cross-reference problem.

FrameMaker cannot update cross-references for the following reasons:

  • A cross-reference marker was deleted from the source information.

  • The source information is part of conditional text that is hidden.

  • The name of the source file changed.

  • The location of the source file changed.

To resolve cross-references, you must understand how to use the Unresolved Cross-Reference window. Although this method works for resolving certain types of unresolved references, such as filename or location changes, if cross-reference markers were deleted for any reason, this window won't be much help. You'll have to take further action to find each individual occurrence of an unresolved cross-reference and reconnect the cross-reference with its source information.

For detailed information on fixing unresolved cross-references, see Chapter 5, "Cross-References."

Working with Missing Fonts

The Missing Fonts error is perhaps one of the most-common problems users experience in FrameMaker. Missing font errors occur when your computer doesn't have the exact font that is used or referenced in the document file. With FrameMaker available on a variety of hardware and software platforms (where the same fonts have names with slight differences), different font configurations for individual computers and multiple users working on document files, it's no wonder that the Missing Fonts error continues to pop up onscreen.

If you are working in a book file, this error can mean trouble. Usually, you don't have to open individual files included in a book in order to update/generate the book file. However, if individual files contain missing fonts (for any reason), the book's update/generate will stop. You must solve the font problem before you attempt to update the book file. A quick fix for this is to open the individual files causing the problem first, and then update the book file. By opening the files first and dismissing the Missing Fonts error message, you can successfully update the book file while those files stay open.

This method is not so practical if you have 25 or 35 files included in your book. Whether a document file is part of a book or not, you should attempt to solve the missing font problem.

Determining the Missing Font Name

It's a good idea to figure out the font names that are missing before you do anything else. The following steps describe how to determine the missing font names:

  1. Open a file that contains missing fonts.

    The Missing Fonts error message appears, as shown in Figure 13.5.

    Figure 13.5. The Missing Fonts error message.

  2. Click OK.

    The Console window produces a list of missing fonts and substitutions for each font.

Fixing Missing Fonts

Before you do anything else, check your computer setup to determine if you have the particular fonts that are missing. If you do not, quit FrameMaker and get the correct fonts installed on your computer. After you have the fonts installed correctly, the error message goes away the next time you open the file.

If you can't install the correct fonts, you can do one of the following:

  • Substitute temporary fonts for the correct fonts.

  • Permanently replace the correct fonts with substitute fonts.

FrameMaker's Font Preference settings enable you to either temporarily or permanently replace the correct fonts. Font preference settings are located in File > Preferences. Determine which method works best for your situation. Table 13.2 shows the result of the font setting turned on or off and why you would choose one or the other.

Table 13.2. Preference Settings for Missing Fonts

Setting

Result

Why Do This

Turn On Remember Missing Font Names

Temporary fonts are substituted for the correct fonts, but the correct fonts are remembered. Therefore, next time this file is opened on a computer with the correct fonts, those fonts are used.

You will encounter the Missing Fonts message each time the file is opened without the correct fonts. The substitute fonts temporarily change the document design and pagination.

• The file came from another computer platform.

• You are editing the file and not doing final production.

• You can temporarily live with substitute fonts for any other reason.

Turn Off Remember Missing Font Names

Temporary fonts are substituted for the correct fonts and the correct fonts are not remembered. Therefore, the next time this file is opened on a computer with the original correct fonts, this will have no effect and the substitute fonts will continue to be used.

• The font is no longer being used and you cannot find it in the file although the error message continues.

• The font is used but you do not need it anymore.

Solving Book File Errors

A multitude of errors can occur while you update book files. In order for information in files to be updated (according to book settings), you must solve any book file errors.

Book files allow you to work with several document files as a unit. A book file also provides the ability to produce a single table of contents or index, based on the included set of document files. Updating information from a book file produces several results. File information, such as numbering and cross-references, are updated with the latest information. Table of contents, indexes, and other generated files are also updated with the latest information.

Sometimes, if there are book file errors, the table of contents or index might not update with the latest information. You might be fooled into thinking something is specifically wrong with the index or the table of contents. There can be, but chances are that the problem originates from other book file errors. Therefore, indexes or table of contents do not update correctly. After book file errors are solved, generated files update correctly.

Fortunately, book file errors are listed in a separate document, which is automatically produced after errors are found. Book file errors usually consist of the following:

  • Couldn't Open File

  • Inconsistent Settings

  • Inconsistent Numbering Properties

  • Unresolved Cross-References

If you decide not to solve book file errors, don't count on updated information in document files or generated files to be correct. The right thing to do is to correct the problems before you continue with book file updates.

Read the section, "Solving Book File Errors," in Chapter 7, "Combining Documents into Books." You learn how to solve each type of book file error.

Adding Page Number Prefixes in Generated Files

If you use chapter-based page numbering in document files, you will have to add the chapter prefix number to page numbers in generated files, such as the table of contents, list of figures, or indexes. Chapter-based numbering in documents includes the chapter number as part of the page number. Each chapter usually restarts at page 1. Thus, a typical chapter-based page number for Chapter 5 would look like this:

5-1, 5-2, 5-3...

When you create a table of contents or an index for the first time, the corresponding page number for each item in the resulting list does not have a chapter-based prefix number. You must add this to each generated file's special text flow, located on the reference page. Thereafter, each time you update a generated file, the prefix number is included in the page-number reference.

For more information on including prefix page numbers in the table of contents lists, see page 249 in Chapter 8, "Creating Tables of Contents and Other Lists." To include prefix numbers in indexes, see page 293 of Chapter 9, "Indexing."

Working with Multiple Page Number Styles in an Index

Sometimes, files included in a book file use different page numbering systems. For example, suppose that you are working with a book file that includes a Preface section with pages numbered as i, ii, iii… , chapter sections with pages numbered as 5-1, 5-2, 5-3… (for Chapter 5), and appendixes with pages numbered A-1, A-2, A-3….

If you include the chapter prefix with the page number in the index, you might run into a problem with page numbers of index entries extracted from the Preface. The Preface page numbers have no prefix. Therefore, if you use the following Building Blocks

<$chapnum>-<$pagenum>

to produce the page numbers in the index, the Preface page numbers would also look something like this:

9-i, 9-ii, 9-iii…

Although you might not actually be using the chapter number anywhere in the Preface file, you cannot suppress this number. You must perform two exercises in order to have the index entry page numbers for the Preface show up as

i, ii, iii…

without the chapter number preceding it. But you will continue to have the chapter number precede the chapters and appendixes. This would look something like this in the index list:

I

Index Entries

Simple 9-6

Installing the Software ii

For detailed information on how to include multiple page number styles in an index, please see page 294.

The Running Headers or Footers Appear Empty

As you saw in Chapter 4, running headers and footers provide information about a document. Usually, this information corresponds to source text in the document with a particular paragraph tag applied. As a result, the running header or footer information changes from page to page, based on the source text in the document.

If your document's running headers or footers do not display the correct source information, review the following list before you redo all your work. It is often a simple error that can cause this type of problem.

  • Make sure that at least one source paragraph is tagged with the paragraph tag referenced in the Running H/F variable.

  • Check the paragraph tag name referenced in the Running H/F variable against the paragraph tag name in the Paragraph Catalog. These must be exactly the same with regard to spelling, capitalization, or spaces.

  • Use Edit > Find/Change > Text > Paragraph Tag to search for the paragraph tag referenced in the Running H/F variable. If you find empty paragraph returns tagged with the referenced paragraph tag, these empty paragraph returns can cause the running header or footer to appear empty.

The Table of Contents Contains Empty Lines

If after generating a table of contents, empty lines are included in the list, you must look in the source document to find the problem. Usually, the cause of this problem is empty paragraph returns in the source document tagged with source paragraph tags included in the table of contents.

It's a good idea to use the automatic hypertext links to jump from the table of contents list to the exact source of the problem listing.

If you don't have hypertext links included in the table of contents list, you have to turn on hypertext links in the Set Up Table of Contents window and regenerate the table of contents. Follow these steps to include hypertext markers in your table of contents:

  1. From a book file, select Table of Contents in the book file list.

  2. Select Edit > Set Up Table of Contents.

  3. Click Create Hypertext Links to turn on this feature.

  4. Select the Set button.

    The Update book window appears.

  5. Select Update.

    The hypertext markers are included in the generated table of contents.

Back to Basics

You can use Control+Alt to click on a hypertext link in a document.

If you don't want to use hypertext links, you can always look on the page of the source document to find the source paragraph with the error.

Freezing Pagination

If you're curious as to how to incorporate change pages into documents, this section is for you. If you have been through many versions of FrameMaker, you might remember when freeze pagination was a documented feature of the program. Although this is no longer documented in FrameMaker, freeze pagination continues to be a working feature.

Although you traditionally use freeze pagination to create change pages in documents, you can also use this feature to resolve pagination problems when pages were inconveniently added by using the Special > Add Disconnected Pages command. This section explores how freeze pagination works to create change pages and how to resolve some pagination problems.

Creating Change Pages

Change pages are useful in documents where new information is added after the fact. For example, if you already sent documentation to your customers and new information is added to the documentation, the change pages can be released, thereby saving you the time of redoing all the documentation.

Change pages work by freezing the current pagination in the document. Then each page is essentially a disconnected page. When you add the change pages to the document, a new blank disconnected page is inserted at the desired location and becomes a point page. A point page has a decimal number added to its page number. Suppose that, after freezing the pagination in a document, you add two change pages between pages 2 and 3. The number of those change pages will be 2.1 and 2.2. If you were to add a change page after page 3, the page number of that page would be 3.1.

Back to Basics

To display the point page number, each body page must correspond to a master page that includes a page number variable.

The following steps guide you through the freezing pagination process:

  1. Press Esc pz on your keyboard in sequence.

    The Freeze Pagination window appears, as shown in Figure 13.6.

    Figure 13.6. The Freeze Pagination window.

  2. Select the Point Page # Style from the drop-down menu.

    The Point Page # Style is the number that appears after the main page number. If you add a change page after page 2 and select Numeric as the point page # style, the result is 2.1, 2.2…. If you select Alphabetic as the point page # style, the result is 2.a, 2.b….

  3. Click Freeze.

    The pagination in the document freezes. Pages added to the document get an automatic point page number.

Back to Basics

To unfreeze pagination, press Esc pz on your keyboard and select Unfreeze.

Understanding the Shortcomings of Freeze Pagination

Although creating change pages can be useful in documents, understanding its shortcomings is equally important. This might clear up some questions you have after performing a freeze pagination in documents:

  • Paragraphs that extend across two pages become two separate paragraphs.

  • Autonumbering doesn't lend itself well to point pages because each page becomes its own text flow, then each number sequence is no longer connected to its numbering sequence on other pages, and you end up with zeros in autonumbers.

  • When tables extend across more than one page, the rows on the second page are automatically placed onto a point page, although they remain connected to the first part of the table. In other words, if a large table is on page 8 and continues on page 9, after freezing pagination, the continuing part of the table is on point page 8.1 and text that comes after the table appears on page 9.

Fixing Disconnected Pages

You might have encountered a document that had a page or two added using the Special > Add Disconnected Pages command. If disconnected pages were added to the document with no specific purpose for being disconnected, such a page can cause some real problems in documents, because it won't be connected to the main text flow. You can resolve this problem by using the Format > Customize Layout > Connect Text Frames command, which allows you to connect text frames to each other one pair at a time. You can also resolve this by freezing and unfreezing the pagination in a document. After you unfreeze the pagination, all the text frames are connected and you no longer have disconnected pages in the document.

Excluding the .fm Extension in a Filename Variable

The <$filename> variable is a helpful piece of information to include in headers, footers, or other locations of your document. The <$filename> variable comes in two varieties:

  • Long filename. Displays the full path and the filename.

  • Short filename. Displays the filename only.

Using either the long or short filename variables produces the following:

filename.fm

If you convert document files to PDF for distribution and included this variable in your document, the original name and extension continue to be displayed in the PDF file. To avoid confusion, it might be helpful to just display the name of the file without the extension.

Here's a quick way to display the filename variable without the .fm extension after you insert the variable in the header, footer, or another location in your document:

  1. Select File > Save As.

    The Save As window appears.

  2. Navigate to the correct location of the file and type "filename" in the Filename field, as shown in Figure 13.7.

    Figure 13.7. You can suppress the .fm filename extension.

    Be sure to include the quotation marks around the name of the file.

  3. Click Save.

    The FrameMaker file extension no longer is used for this file and therefore isn't displayed in the filename variable. Notice that the file sports a generic icon rather than a FrameMaker icon. You will have to open this file from within FrameMaker rather than clicking on the file itself to open it.

Fixing Tables Imported from Microsoft Word

If you've imported documents from Microsoft Word that include tables, you've probably run across some formatting problems with these tables in FrameMaker:

  • If the Word tables have header rows in Word, these will not be header rows in FrameMaker.

  • If you apply FrameMaker table formats to imported Word tables, the format has no effect on the table.

For information on how to solve this problem, see Chapter 12, "Converting Documents from Other Applications."

Including Running Headers or Footers Across Files

Running headers or footers typically correspond to source text within the same file. For example, if a running header refers to source text tagged with the paragraph tag ChapterTitle, that source text is displayed in the header for that file.

This feature works only for the same file, not across files. Suppose that you broke one file into two files and combined them using a book file. If ChapterTitle is a paragraph tag used for the chapter title, and it's referenced in the running header, the chapter title will not show up in the header of the second file if no text is tagged with ChapterTitle in the second file.

In order to get the chapter title from the first file to show up in the header of the second file, you must choose a work-around technique.

  • Insert a cross-reference in File 2 header to the chapter title source in File 1.

  • Insert a Running H/F variable in the File 2 header that refers to the Header/Footer $1 or Header/Footer $2 marker text in the current file.

As I discuss each technique, you can determine which method works best for you.

Using Cross-References

Inserting a cross-reference in file2.fm to source text in file1.fm works best if you want a solution that lends itself to automation. After you insert the cross-reference, if the source text in file1.fm changes, the header information in file2.fm updates with the new information.

Note

For more information on creating cross-references, see Chapter 5, "Cross-References."

Review the steps to create the cross-reference from file2.fm to the chapter title of file1.fm:

  1. Open both file1.fm and file2.fm.

  2. From file2.fm, select View > Master Pages.

  3. Insert the cursor in the master page location where you want the running header to appear.

  4. Select Special > Cross-Reference.

    The Cross-Reference window appears.

  5. Select file1.fm from the Source Document drop-down menu.

    Paragraph tags included in file1.fm appear in the Paragraph Tags list.

  6. Select ChapterTitle, which is the paragraph tag that corresponds to the source text that you want to include in the header.

    All paragraphs tagged with ChapterTitle are displayed in the Paragraphs list on the right.

  7. Select the correct source paragraph,as shown in Figure 13.8.

    Figure 13.8. Cross-reference from file1.fm to file2.fm.

  8. Click Insert to insert the cross-reference in the header.

After you create the cross-reference, you must select or create the correct format in which to display the cross-reference. Figure 13.9 shows one idea of a cross-reference format definition to force the cross-reference to be displayed as Chapter 9 How to Design Web Pages.

Figure 13.9. The format of a header cross-reference.

Using Header/Footer $1

You can insert marker text (that contains the chapter title of file1) in file2.fm and then create a Running H/F in file2.fm that refers to that marker text. This solution works best if the chapter title will not change often. If the chapter title in file1.fm changes, you must manually edit the marker text in file2.fm each time.

To implement this solution, you must work with both the Header/ Footer $1 marker and a Running H/F variable.

Follow these steps to insert a Header/Footer $1 marker at the start of the first paragraph in file2.fm:

  1. Select Special > Marker.

  2. Choose Header/Footer$1 from the Marker Type drop-down menu.

  3. Type text in the Marker Text field that you want to display in the document header, as shown in Figure 13.10.

    Figure 13.10. Use the Marker Text field to create a Header/Footer$1 marker.

  4. Click New Marker.

    The marker is inserted at the beginning of the first paragraph.

Tip

You might want to keep Text Symbols turned on so you can view markers symbols in the text.

After you insert the Header/Footer$1 marker in the document, you can create the Running H/F variable to display the content of the marker on body pages:

  1. Switch to the master pages in file2.fm.

  2. Place the insertion point in the location that you want to insert the running header.

  3. Select Special > Variable.

    The Variable window appears.

  4. Select Chapter Number from the list and click Edit Definition.

  5. Type the word Chapter in front of the <$chapnum> definition and click the Set button.

    The Variable window appears.

  6. Click on Insert.

    Only the Chapter Number variable is inserted in the document header. You must add another variable to display the marker source text that was inserted in the document.

  7. Select Special > Variable.

  8. Select Running H/F 3 in the variable list.

    The definition of Running H/F 3, <$marker1>, is displayed right below the list, as shown in Figure 13.11. <$marker1> references the marker text in the current document that corresponds to Header/Footer$1 marker text.

    Figure 13.11. Creating a running header by using the $Marker1 Building Block.

  9. Click on Insert.

    The two variables are displayed in the header of the document, as shown in Figure 13.11.

Summary

This chapter armed you with a wealth of information to solve some typical problems that you might encounter with FrameMaker. Whether the problem is simple or complicated, users can sometimes overlook the obvious solution (or can't find a solution), especially during the high point of a project.

Often in problem-solving, users try many solutions, but are never certain which action really fixed the problem. Try documenting some of the problems you encounter along with solutions that work so that, in the future, you will have that information handy.


Glossary

absolute pathname

Provides the full path of a file beginning with the highest level and indicates the file location within that hierarchy.

See also [relative pathname]
anchored frame

Contains objects, such as graphics or text frames, and is fixed to a specific location in the text. An anchor symbol appears at the anchor location. When that text moves, the anchored frame (and objects within) moves with it. Select an anchored frame by clicking on the frame or by selecting the anchor symbol. Edit an anchored frame by selecting the frame and choosing Special > Anchored Frame.

As Is setting

When selecting two paragraphs whose Designer Properties are different, As Is appears as the settings indicator. As Is also enables you to determine what properties will be changed and what properties will not be changed as a result of applying a character format to text or a paragraph tag to paragraphs. For check box settings that use As Is, a dimmed check box indicates the As Is setting.

background text/graphics

Information included on master pages. Background text or graphics are displayed on body pages that correspond to master pages containing this information. To be displayed on body pages, information must be contained in untagged background text frames. If you insert text in a tagged body column on a master page, that text will not display on body pages.

body page

Contains the printable content of a document. You can enter and edit document text on body pages. Body pages display background text or graphics and obtain page-layout information from corresponding master pages.

book file

Contains a list of filenames that are included in the book and holds the key to various settings and organization information for each included file. Using a book file, you work in a single document window while viewing or making changes to the overall organization of the document files that make up the book. You also have the ability to produce a single table of contents or index based on the smaller set of document files. You can use a book file for a series of files that make up a book or to link smaller files together that make up one larger file.

Building Blocks

Placeholders used in autonumbering, cross-references, variables, hypertext, and generated files. Building Blocks represent actual text, numbering, system information, and style formats used throughout your document.

condition indicator

Stylistic attributes applied to text, such as underline and strikethrough or various colors. You can define condition indicators by selecting Special > Conditional Text. Click on the condition tag that you want to define indicators for, then click Edit Condition Tag. To show or hide condition indicators, click Show/Hide in the Conditional Text window. Then check or uncheck Condition Indicators. Indicators make it easy to distinguish one conditional text type from another (and from common text).

conditional text

Offers the ability to easily create and maintain more than one version of a document contained within one document file. Each document version is distinctive from the other with the exception of common text, tables, figures, and other elements that are shared by all versions. Conditional text is identified by condition tags. You can define new condition tags by selecting Special > Conditional Text. Next, click Edit Condition Tag to define a new tag name and style indicators. To edit an existing condition tag, select it in the Conditional Text window list, and click Edit Condition Tag.

cross-reference

Refers readers to another location in the document that contains related information. The referenced information is called the source information. When documents are saved as a PDFs, cross-references become clickable links, which enable you to jump to the source information quickly.

cross-reference format

Indicates how cross-reference information is displayed in a document. Cross-references are defined with a combination of text and various Building Blocks and can be displayed any number of ways. For example, a cross-reference might read as See Chapter 8 on page 99, or the same cross-reference might read as See 'Getting Started' in Chapter 8.

default font

Paragraph text appears in the assigned default font of that paragraph tag unless you apply another style to the text, using either the Character Catalog or the Format menu. To switch styled text back to the default font of the paragraph, select the text, and select Default Font from the Character Catalog.

filename suffix

Characters that are added to generated file filenames. Each suffix indicates the type of generated file. For example, filenameLOF.fm indicates that the file is a list of figures. After a suffix is added to a generated file, don't delete the suffix or FrameMaker won't recognize the file as generated and it does not update.

format overrides

Occur as a result of a change that you made to a particular selection that no longer matches the predefined format. Format overrides can occur in paragraph, character, or table formats, as well as column layouts. Format overrides in text are indicated by an asterisk (*) in the status bar area. Overrides add to inconsistency in documents and must be avoided when possible. Documents with many format overrides are not good candidates to convert to HTML.

marker

Non-printing characters used by FrameMaker. Markers are automatically inserted in text to indicate cross-references, sources, hidden conditional text, index entries, hypertext commands, and specific running header/footer source text. You can turn on text symbols to view markers by selecting View > Text Symbols, and you can use Edit > Find/Change > Find > Any Marker to search for markers of any type.

master page

Provides the page layout and any background information that you want to appear on each document page. Text, graphics, headers, and footers are part of that background information. You can include up to 100 master pages.

paragraph default font

One of six properties contained in a paragraph format. Paragraph text appears in the assigned default font of that paragraph tag unless you have applied another style to text, using either the Character Catalog or the Format menu.

paragraph tag

The name assigned to a paragraph format that's stored in the Paragraph Catalog and applied to text in a document. For example, click in paragraph text, then click on a paragraph tag name in the Paragraph Catalog to assign its format to that paragraph. Click in any paragraph and view the paragraph tag name in the left side of the status bar.

pathname

Indicates the location of a particular file or directory on disk or network server. The pathname is displayed in the title bar of an open FrameMaker document.

reference frame

Non-anchored frames that are stored on reference pages. They contain text or graphics for display above or below paragraphs on body pages of a document. You can display reference-frame contents by selecting the Advanced tab in the Paragraph Designer, and selecting either Frame Above Pgf or Below Pgf. To change the name of a reference frame (that is, displayed in the Advanced tab of the Paragraph Designer), click on the reference frame to select it, and select Graphics > Object Properties. Type a new name in the Name field.

reference page

Non-printing pages. They have a few important jobs in FrameMaker, such as storing frequently used graphics and other information in reference frames; defining format structure of generated document files; and maintaining mappings between paragraph tags and HTML tags. You can include up to 100 reference pages. To easily go to a particular reference page, select View > Reference Pages, then View > Go To Page and select the page name from the drop-down menu.

relative pathname

Describes the file or directory location on a computer system relative to the current location.

See also [absolute pathname]
running header or footer

Headers or footers that vary or change from page to page in your document, based on that page's content. Running headers or footers are only inserted onto a master page where they appear to have no fixed value and are displayed according to their name. When viewed from body pages, they assume a value based on content in your document that has been tagged with particular paragraph tags. Running header and footer variables are named Running H/F 1 through Running H/F 4 and can only be viewed in the Special > Variables list from master pages.

status bar

Located at the bottom of a FrameMaker document window, and provides information such as paragraph, character, flow or condition tag names, object size, page number, and zoom settings. You can use the status bar to apply a tag name to text. Select a paragraph, and press Ctrl-9 to apply a paragraph format. The left corner of the status area is highlighted, which prompts you to type a tag name that appears in the catalog.

system variable

Provided by FrameMaker for use in headers and footers. After they're inserted, system variables update themselves based on information that's generated by the system. System variables include Page Number and Page Count, Current Date, Creation Date and Revision Date, Filename (Short), and Filename (Long) (the full path).

template

Consists of preset document formats and features that are used as a basis for other documents. Therefore, formats and features do not have to be re-created every time you begin a new document. Each FrameMaker document is also a template. Templates include these predefined formats: Page Layouts, Paragraph Formats, Character Formats, Table Formats, Color Definitions, Document Properties, Cross-Reference Formats, Variable Definitions, Math Definitions, and Conditional Text Settings.

text symbols

Non-printing characters that indicate tabs, end of paragraphs, end of text flow, and markers in text. Select View > Text Symbols to toggle the display of text symbols on and off. If you use many markers in documents, work with text symbols turned on so you do not delete any markers. If you work with imported text, turn on text symbols to view problematic tabs or empty paragraph returns.

unresolved cross-references

A puzzle that can be solved. Cross-references are unresolved when FrameMaker cannot find its referenced source information. A common occurrence of this is when filenames or locations have changed or if source markers have been deleted. If you cross-reference to documents other than the current document, be sure to save the other document before you close it or the cross-reference source markers will not be saved.

user variable

Creates text that can be used in several locations of your document, such as headers, footers, or within body pages. After a user variable is defined and inserted in several places, you can change the definition of that variable and all occurrences automatically update to display the new information.

variable

Consists of user variables, system variables, and running header/footer variables. Although each of these is used for different reasons, in general, variables provide a method to easily include text or other information in a document without typing it each time because the variable represents the text or other information.

wildcard

Enables you to widen or limit searches in documents while using Edit > Find/Change. For example, to search a document for any number between 3 and 9, select Edit > Find/Change, type [3-9] in the Find text field, and check Use Wildcards and begin searching. You can also use the asterisk in wildcard searches. For example, an "*ing" wildcard search will find words containing the letters provided plus any combination of letters in place of the asterisk.

Word

A popular word-processing program used by the man on the cover of this book.