FrameMaker Tutorial:
Autonumbers, Variables, & Version Control

Developed for advanced documentation students by
David A. McMurrey Pam Renwick
Thomas A. MooreJacqueline J. Pulido

See the FrameMaker resource page for additional study materials. Got a question about this tutorial? Post it in the FrameMaker FAQ


The following FrameMaker tutorial shows you how to use: This tutorial is provided for advanced documentation students on a free, as-is basis, without guarantee of accuracy. If you see any errors or think we should have included other tasks, let us know!

Other tutorials focus on the basics, graphics, styles, tables, templates, master pages, book building, and conversion techniques. These tutorials only get you started; if you have more in-depth needs, see the Adobe FrameMaker User Guide or Adobe FrameMaker Classroom in a Book.

The tutorial's instructions are based on FrameMaker version 6.0 for Windows. You may encounter some minor differences if you are using another version.

Note: For the sake of brevity, we use an abbreviated style for menu commands throughout this lesson. For example, "Choose File > New" means "Choose New from the File menu".

Using Variables

Every variable has a unique name and a definition (value). By simply changing the definition of a variable, you can edit every occurrence of a certain word or phrase within your document or book automatically. Often, variables are used when a key term, such a product name, is expected to change at the last minute and when the corresponding change must be made rapidly. Variables are essential in technical publishing for new or upgraded products. Product names are often not decided until a few weeks before the product goes to market, and in subsequent product versions, its name is likely to change. Variables make the process of changing the product name in each instance easy and consistent. Variables also allow you to use short abbreviations that can be automatically expanded to complete passages of text. For example, FM can be used as a variable for the text FrameMaker 6.0.

Along with the existing set of system variables, such as dates and file names, FrameMaker enables you to create your own user variables. If you are going to write a book made up of several documents (chapters), the best way to use your own variables is to establish the variables in the template for that book, as this next lesson shows you. (If you are not familiar with using templates, go to the Templates tutorial for a detailed introduction.)

First, create a new template:

  1. Open FrameMaker and choose File > New > Document.

  2. From the New dialog box, click Portrait to create a new blank document.

  3. Choose File > Save. In the File name box, type variable.tem for the template name and click Save.

    Note: If you are working in the TCM computer lab, use the A: drive to save your file on a diskette.

  4. Choose Special > Variable. Use the scroll bar in the Variable dialog box to at look at the existing system variables:

    Variable dialog box

Now, create your own user variable:

  1. In the Variable dialog box, click Create Variable to open the Edit User Variable dialog box.

  2. In the Name box, type FM for the variable's name. In the Definition box, type FrameMaker 6.0 for the variable's value. Your settings should look like this:

    Edit User Variable

    Note: Variable names are case-sensitive; FM is not the same as fm.

  3. Click Add to store this variable and then, click Done twice to exit the dialog boxes.

  4. To insert your new variable, press Ctrl + 0 (that's a zero) and while keeping an eye on the left side of the status bar, type f, and then m to find your variable. As soon as you see FM in the status bar, press Enter to display its value at the insertion point:

    Status Bar

  5. Since you are creating a template, press Ctrl + Z to erase this text.

  6. Click on the X located in the upper right corner of the document window to close the template and click Yes, when asked to save before closing.

Create a new document from your template:
  1. Choose File > New > Document and in the New dialog box, locate and select your template's directory.

  2. Click on variable.tem to select this file as the template. The file name appears in Use Template box.

  3. Click New to open your new document.

  4. Try inserting your variable in the document window. (Remember to press Ctrl + 0. Then, type f, and m. When FM appears in the status bar, press Enter.)

  5. Choose File > Save, type vari-01 for the file name, and click Save.

Now, imagine that the product name has changed from FrameMaker 6.0 to FrameMaker-PLUS. Let's go back and change the variable's definition in the template first:

  1. Choose File > Open to open your template, select the template's directory, and double-click on variable.tem.

  2. Choose Special > Variable.

  3. In the Variable dialog box, click on the FM variable to highlight it, then click Edit Definition.

  4. In the Definition box, delete the 6.0 and add -PLUS to the variable's definition, then click Change. Click Done twice to close the dialog boxes.

  5. Click on the Save button ( Save File ) to save the template.

Now, you can import the change to your document:
  1. Choose Window > vari-01.fm to view your document.

  2. Choose File > Import > Formats to import template's settings.

  3. From the Import from Document pull-down menu, select variable.tem.fm.

  4. In the Import and Update area, make sure Variable Definitions is checked (selected). If not, click on this option. (It doesn't matter if the other options are selected or not.)

  5. Click Import. The variable's value in your document automatically updates to FrameMaker-PLUS.

Note: You can use these same procedures to update documents in a book.

Using Version Control

Version control seems to be the industry name for the ability to make one set of files support two or more versions. Imagine that you have written a document for two separate clients and that the two documents differ only in a few names, numbers, and paragraphs. You could maintain two separate versions of this text, but this requires more storage space and makes it difficult to update both versions.

Version control enables you to keep everything in one set of files and hide or show a particular version. Imagine that you must maintain documentation for two versions of the same product: SuperWidget Version 1 and SuperWidget Version 2. Also imagine Version 1 offers free technical support while Version 2 does not and Version 2 includes a new feature called the Ultra Widget Subprocessor. Here's how the two versions look separately:

Version 1: We are proud to announce the new SuperWidget. Free technical support is available at 1-800-567-8900. The new SuperWidget enables you to process all your objects efficiently and effectively.

Version 2: We are proud to announce the new version of SuperWidget. The SuperWidget enables you to process all your objects efficiently and effectively. This new version includes the Ultra Widget Subprocessor, which provides background processing.

Combining these two versions into one paragraph, using blue for the first and red for the second version, look like this:

We are proud to announce the newthe new version of the SuperWidget. Free technical support is available at 1-800-567-8900. The new SuperWidget enables you to process all your objects efficiently and effectively. This new version includes the Ultra Widget Subprocessor, which provides background processing.

FrameMaker calls the text that differs from one version to another conditional text (shown here in blue and red). The text that is common to all versions is call unconditional text (shown here in black). FrameMaker enables you to use color, underscores, strike-throughs, as well as overbars to indicate different versions. Color is often used, since it is the easiest to distinguish.

To set up condition tags which you'll use for version control:

  1. First, open a new blank document. (Press Ctrl + N and click Portrait.)

  2. Choose File > Save, type version for the file name, and click Save.

  3. To set up the different versions, choose Special > Conditional Text.

  4. In the Conditional Text dialog box, click Edit Condition Tag. (In this case, you are actually creating condition tags.)

  5. In the Tag box, type the name version1. From the Color pull-down menu, select Blue, and then click Set.

  6. Click Edit Condition Tag again, but this time type the name version2 and select Red as the color. Then, click Set.

    Note: If you are working on a book that consists of several files, you'd want to set up these condition tags in the template for those files. This way, the tags are available for all the files that use the template.

  7. Close ( X ) the Conditional Text dialog box.

  8. Now, copy the combined text from the paragraph above (with the blue, red, black text), exactly as it is typed, into your FrameMaker document.

  9. To begin tagging the different parts of the paragraph for version control, select the new version of the , including the space immediately after the second the.

  10. Choose Special > Conditional Text again. In the dialog box, select version2, then click the left-pointing arrow. The settings should look like this:

    Conditional Text

  11. Click Apply and notice this text is now red. (Move the Conditional Text dialog box away from the paragraph, if needed.)

  12. Repeat this procedure for each segment of the text that is conditional -- that appears only in one version or the other.

    Note: It's important to include or exclude spaces and periods in such a way that when only one version is showing the spacing and punctuation will be correct.

  13. When you have finished tagging the entire paragraph, click Show/Hide in the Conditional Text dialog box.

  14. In the Show/Hide dialog box, click version2, then click on the right-pointing arrow. The dialog box looks like this:

    Show/Hide

  15. Click Set and you should see only the text for version1 -- the blue text. Experiment with this version for a while; try adding or deleting spaces, punctuation, or words.

  16. Repeat the above procedure to hide version1 and show version2 -- the red text. Also experiment with this version; see if you can change how a phrase is tagged.

Creating Autonumbers

FrameMaker enables you to automate all numbering streams within a document -- including multi-file documents such as books. Numbering streams include such things as page numbers (including by-chapter numbering); part, chapter, and section numbers; figure and table numbers; the numbers in various levels of numbered lists; and just about anything else you can imagine that must be automatically incremented across a document. The feature that makes this possible is autonumbering.

To learn how autonumbering works, you'll create a few different numbering streams and add:

By the way, don't worry if at first it seems as though the system FrameMaker uses to implement autonumbering was invented to drive you crazy. After a while, the system is logical and makes abundant sense -- just practice it.

Adding Autonumbers Based on Section Numbers

In this lesson, you will learn how to add autonumbers based on section numbers to some headings, figure titles, and table titles. To keep things simple, let's work in a single document. Just remember this same system works across files in a book.

First, create some headings with section numbers:

  1. Open a new, blank document. (Press Ctrl + N and click Portrait.)

  2. Choose File > Save, type autonum for the file name, and click Save.

  3. In the document window, type Installing the SuperWidget, then open the Paragraph Catalog ( Paragraph Catalog button ) and apply Heading1 to it.

  4. Next, create a new paragraph tag. Make sure the insertion point is still in the Heading1 paragraph, and open the Paragraph Designer (Ctrl + M).

  5. In the Paragraph Tag box, type acc_head1 for the new tag name, then click the Commands pull-down menu and select New Format.

  6. In the New Format dialog box, make sure Store in Catalog and Apply to Selection are both checked and then click Create to save this new tag.

  7. Next, click the Numbering tab in the Paragraph Designer. Type Section <n+>.<n=0>< > \t in the Autonumbering Format box, as shown below:

    Autonumbering box

    Notice when you place the insertion point in the Autonumbering Format box, a checkmark automatically appears, showing the autonumbering feature is active.

  8. Click Update All. Your heading now looks like this:

    Header

  9. Place the insertion point at the end of this paragraph, then press Enter to create a new body paragraph.

  10. Type Configuring the SuperWidget and apply the acc_head1 to it.

Next, create some subheadings with a decimal-numbering system:

  1. Create a new body paragraph beneath the Installing the SuperWidget heading and type Setting Up for Installation. Then, press Enter and type Troubleshooting Installation.

  2. Go back and place the insertion point in your first subheading, Setting Up for Installation, and apply Heading2 to it.

  3. In the Paragraph Designer, create a new paragraph tag named acc_head2 in the same way you created acc_head1.

  4. Click the Numbering tab in the Paragraph Designer. This time, type <n>.<n+>< > \t in the Autonumbering Format box. Then, click Update All. The heading is now 1.1 Setting Up for Installation.

  5. Apply acc_head2 to Troubleshooting Installation subheading. Notice the first subheading is labeled 1.1 and the second is 1.2.

  6. Create a new body paragraph beneath the Configuring the SuperWidget heading and type Configuring for Windows 3 on one line, then press Enter and type Configuring for Win95/98 on the next line.

  7. Also apply acc_head2 to these two subheadings. Notice how these pick up the Section 2 number.

    Here's how this numbering works: the counter n+ adds 1 to whatever the value of n is. In this case, because it was at the beginning of the file, n is zero. Eliminating the plus sign, n means use whatever the current value of n is; don't add anything to it. The < > you entered in the format is a placeholder for the figure-numbering style, which you will create next.

Create figure titles based on the section numbers. Imagine that you had a series of figures to display in Sections 1 and 2 and you wanted to number them Figure 1.1, Figure 1.2, Figure 2.1, Figure 2.2, and so on:

  1. Below subsection 1.1, create a new body paragraph and type Layout of a Basic SuperWidget.

  2. In the Paragraph Designer, create a new paragraph tag named acc_fig for this paragraph .

  3. Click the Numbering tab and type Figure <n>< >.<n+> \t in the Autonumbering Format box. Then, click Update All. The figure title is now Figure 1.1 Layout of a Basic SuperWidget.

  4. Now, type at least two paragraphs (any text you want) under each of the subsections (1.1, 1.2, 2.1, etc.), and apply acc_fig to each of these paragraphs.

  5. Notice while the figure numbers recognize Section 2, they continue sequentially from the figure numbers in Section 1. To fix this problem, click the Numbering tab and change the autonumbering value for acc_head1 to Section <n+>.<n=0>< =0> \t and click Update All. The tag < =0> tells FrameMaker to make the value for this slot is zero, but not to display it.

Now, create some table titles with autonumbering. Imagine that you want to have a series of tables independently numbered running throughout this document:

  1. Create a new body paragraph anywhere within Section 1.

  2. In the Paragraph Designer, create a new paragraph tag named acc_table for this paragraph.

  3. Click the Numbering tab in the Paragraph Designer. Type T:Table <n+> \t in the Autonumbering Format box, and then click Update All.

  4. Create several paragraphs in both Sections 1 and 2 and apply acc_table to each of these paragraphs. Notice the tables use a numbering system that's separate from the section and subsection numbers. This is created by the T:, which is known as a series label. It designates an independent numbering stream named T:.

  5. Close ( X ) both the Paragraph Designer and Paragraph Catalog.

Here's a summary of an autonumbering system based on section numbers. Imagine you wanted to number your document based on Section 1, Section 2, and so on; the first-level headings, Section 1.1, Section 1.2, and so on, based on the main section number; the second-level headings, Section 1.1.1, Section 1.1.2, and so on, based on both the main section number and the first-level heading number; and finally table and figure numbering based on the main section number, Table 1.1, Table 1.2, Figure 1.1, Figure 1.2, and so on.

The following is a table of these autonumber tags as you would enter them for each tag:

Tag

Label

Section

Head1

Head2

Figure

Table

Section

M:Section

<n+>

< =0>

< =0>

< =0>

< =0>

Head1

M:Section

<n>

.<n+>

< =0>

< >

< >

Head2

M:Section

<n>

.<n>

.<n+>

< >

< >

Figure

M:Figure

<n>

< >

< >

.<n+>

< >

Table

M:Table

<n>

< >

< >

< > .

<n+>

In the Autonumber Format box, the spacing would like this:

Tag

Autonumber Format

Section

M:Section <n+>< =0>< =0>< =0>< =0> \t

Head1

M:Section <n>.<n+>< =0>< >< > \t

Head2

M:Section <n>.<n>.<n+>< >< > \t

Figure

M:Figure <n>< >< >.<n+>< > \t

Table

M:Table <n>< >< >< >.<n+> \t

Note: There is a space between the empty brackets, < >, just before the zero in < =0>, just after the labels Section, Table, and Figure, and just before the tab stop \t -- but no other spaces anywhere else in these tags.

Adding Autonumbers Based on Chapter Numbers

In this lesson, you will learn how to insert by-chapter page numbering, add the chapter's title into the header or footer frame, and base autonumbering on chapter numbers. First, create a new paragraph tag for the chapter's title:
  1. Open another new blank document. (Press Ctrl + N and click Portrait.)

  2. Choose File > Save, type chapter for the file name, and click Save.

  3. In the document window, type SuperWidget Installation Procedures, then open the Paragraph Catalog ( Paragraph Catalog button ) and apply Title to it.

  4. Open the Paragraph Designer (Ctrl + M) and create a new paragraph tag named Chapter for this paragraph.

  5. Click on the Numbering tab in the Paragraph Designer. Type Chapter <$chapnum>: \t in the Autonumbering Format box, and then click Update All. This produces the word "Chapter" followed by the chapter number; in this case, its value is one, since this is a single document:

    Chapter tag

    Note: If this document was part of a book, the book file determines the chapter number's value.

Set up the by-chapter page numbering as follows:
  1. Choose View > Master Pages and place the insertion point in the footer frame.

  2. Choose Special > Variable. From the Variables list, select Chapter Number, then click Insert to insert this system variable.

  3. You'll need to insert a symbol between the chapter number and the page number. In the footer, add a space after the 1, then type a dash symbol, and then add another space.

  4. Now, choose Format > Headers & Footers > Insert Page# to insert the page number.

    Your footer frame should look like this:

    Footer

  5. If you use by-chapter numbering, you must change:

    <$paratext> <$pagenum>

    to

    <$paratext> <$chapnum>-<$pagenum>

    at the very bottom of the reference page in the generated TOC file and then update the book. In the generated index file, change:

    <$pagenum>

    to

    <$chapnum>-<$pagenum>

    at the very bottom of the reference page in the generated index file and then update the book.

  6. View the Body Pages and see how this looks in the document.
Now, automate the headers and footers so that they include the chapter title:
  1. In the document window, select (highlight) the chapter title, SuperWidget Installation Procedures.

  2. Choose Special > Marker. In the Marker dialog box, select Header/Footer $1 from the Marker Type pull-down menu (the chapter title should be displayed automatically in Market Text box.)

    Marker dialog box

    Notice that you have two markers ($1 and $2) for headers and footers; you can use one for odd pages and one for even pages, and create your own as well.

  3. Click New Marker to insert the marker.

  4. View the Master Pages and place the insertion point in the header frame.

  5. Choose Format > Headers & Footers > Insert Other.

  6. Select Running H/F 3 from the Variable list and click Edit Definition.

  7. In the Edit System Variable dialog box, select <$marker1> from the Building Blocks, if it's not already there for you.

  8. Click Edit in the Edit System Variable dialog box, and then click Insert in the Variable dialog box.

  9. View the Body Pages; you should see the chapter title that you originally put into the marker. Try editing the marker and see how the title's text changes accordingly.

Finally, here's how to base autonumbering on chapter numbers. Imagine that you are creating a book and each document in the book file is a chapter within the book, and under each chapter, there are first and second-level headings, along with figure and table titles. The autonumbering tags would look like this:

Example

Tag

Autonumber Format

Chapter 3:

Chapter

Chapter <$chapnum>: \t

Section 3.1

Head1

M:Section <$chapnum>.<n+>< =0> \t

Section 3.1.1

Head2

M:Section <$chapnum>.<n>.<n+> \t

Figure 3-1

Figure

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

Table 3-1

Table

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

The advantage of the <$chapnum> building block is that you can control the chapter numbering for an entire book; it keeps your chapter numbers up-to-date and accurate so that you can reorder, add, and delete documents without having to worry about updating the chapter numbers yourself. Try and create the tags illustrated in the table above. If you would like to learn more about chapter and page numbering for books, go to the Book Building tutorial.

This tutorial introduced you to three very useful features in FrameMaker: variables, version control, and autonumbering. By incorporating these features into your documents, you will be able to create and edit your files more efficiently and effectively.


Information and programs provided by hcexres@prismnet.com.