Designing Print Documentation:
FrameMaker Tutorial
Autonumbers, Variables, and Version Control

Developed for Advanced Documentation Students
by
David A. McMurrey
Thomas A. Moore
and
Pam Renwick

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

The following informal introduction to FrameMaker shows you how to use: If you see any errors or think I should have included other tasks, let me know! These tutorials only get you started; if you have more in-depth needs, see Using FrameMaker or Adobe FrameMaker Classroom in a Book. produced by Frame and Adobe. Other tutorials focus on basics, styles, tables, graphics, cross-references, templates, indexes, and the like. (This tutorial is provided for my advanced documentation students on a free, as-is basis, without guarantee of accuracy.) This tutorial is based on FrameMaker version 5.5 for Windows. You may see some minor differences if you are using a later 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".

Variables

In FrameMaker, variables enable you to use short abbreviations that can be expanded automatically to full, complete versions. For example, fm could be used as a variable for FrameMaker. But variables have another, more important use. In an environment where a key term, such as a product name, is likely to change at the last minute and where the corresponding change must be made rapidly in the documentation, 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. In subsequent versions of the product, its name is likely to change. Variables make the process of changing the name in each instance easy and consistent.

Creating a user variable. FrameMaker gives a number of system variables such as dates and file names. It also enables you to create your own user variables. If you are going to write a book made up of several files (chapters), the best way to use your own variables is to establish your variables in the template for that book. (See the tutorial on templates for a detailed introduction.)

  1. Open FrameMaker, and then click File > New.

  2. Click on Portrait to open up the blank page. Save the file by clicking on File > Save As, and name it magic.fm.

  3. In magic.fm, click on Special > Variable. Take a look at the system variables that are available, but press Create Variable to set up your own.

  4. In the Name box of the Edit User Variable dialog box, type an abbreviation (or variable name) that you'll use, for example, fm for FrameMaker. In the Definition box, type the written-out version, for example, FrameMaker.

  5. Press Add to store this variable in the template file. Then press Done in the user variable dialog box, and then Done in the variable dialog box.

  6. To see how it works, press Ctrl-0 (that's a zero), and while keeping an eye on the lower left part of the FrameMaker screen, type f, and then m. As soon as you see the variable name you set up, press Enter; you'll see your complete term in the text area. (Erase this term, however; remember that you are in a template.)

  7. Save and close the magic.fm and open a new file by pressing File > New.

  8. Under Use Template, specify the template, magic.fm, you just created. (You may have to scroll or change directories to find it.)

  9. Click on New. At the blank page, try your variable again.

  10. Save this file as magic1.fm.

Using a variable. Now, imagine that the product name has changed from FrameMaker to FrameMaker-PLUS.

  1. Go back to the template file, magic.fm.

  2. Click on Special > Variable.

  3. In the dialog box, select the fm variable by highlighting it, and click on Edit Definition.

  4. Add -PLUS to the definition of the variable, and then click on Change. (Click on Done to close the two dialog boxes.)

  5. Open the file magic1.fm again. Because it uses the magic.fm template, the name of the product should have changed automatically. (FrameMaker has a method for updating variables without having to open each file; I just need to find it.)

Version Control

Version control seems to be the industry name for the ability to make one set of files support two 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 that text, but that takes up more storage and it is hard to remember 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. Imagine also that version 1 offered free technical support while version 2 does not and that version 2 includes a new feature called the Ultra Widget Subprocessor. Here's how the two versions (which FrameMaker calls conditional text) would 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, would 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 enables you to use color, underscores, strike-throughs, as well as overbars to indicate different versions. But color is the easiest to distinguish. To set up condition tags which you'll use for version control:

  1. Open a new, blank file in FrameMaker.

  2. To set up the versions, click on Special > Conditional Text > Edit Condition Tag. (In this case, we are actually creating condition tags.)

  3. In the Tag box, use the name version1, select Blue as the color, and then click on Set.

  4. Click on Edit Condition Tag again, but this time use the name version2, select Red as the color, and then click on Set.

  5. Now copy the composite text above (with the red and blue) just as you see it into the same FrameMaker file in which you have just defined the condition tags.

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

  7. Click on Special > Conditional Text. In the dialog box, highlight version2, press the left-pointing arrow, and then click on Apply. Move the dialog box away from the paragraph, notice that the phrase is now red. Use these same steps 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.

  8. When you have finished tagging the text, click on Special > Conditional Text. In the dialog box, click on Show/Hide. In the show/hide dialog box, click on version2, then on the right-pointing arrow, and then click on Set.
You should see only the text for version 2 -- the blue stuff. Experiment with the version for awhile. See if you can hide version 2 and show only version 1; see if you can show both versions; see if you can change how a phrase is tagged (for example, add or delete spaces, punctuation, or words.)

If you are working on a book made up of several files, you'd want to set up these condition tags in a template for those files. That way, they'd be available for all the files that used that template.

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.

At first, the system that FrameMaker uses to implement autonumbering seems as though it were invented to drive you crazy. However, the system is logical and makes abundant sense -- after a while. To demonstrate how it works, we'll create some outlines, headings, lists, figure titles, and table titles within a single document. Just remember though that this same system works across files in a book list.

  1. Open a new file in FrameMaker and save it as autonums.fmk.

  2. Type Installing the SuperWidget and then apply FrameMaker's Heading1 to it.

  3. Open the Paragraph Designer, in the Paragraph Designer box name this new style acc_head1, and then click on Commands and then New Format to save it.

  4. Click on Numbering, click in the Autonumbering Format box, then type Section <n+>.<n=0>< >\t in the box just below, and then press Update All. The result will be Section 1.0 Installing the SuperWidget.

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

  6. Create some Body paragraphs between the two first-level headings you just created. Type the text Setting Up for Installation and Troubleshooting Installation just below the acc_head1 installation heading.

  7. In the Setting Up heading, apply FrameMaker's Heading2 style and then rename it acc_head2 in the same way you created acc_head1. This time, however, we'll use a decimal-numbering system; the heading will be 1.1 Setting Up for Installation. In the Autonumber Format box, type <n>.<n+>< >.\t this time. Click on Update All.

    Now, apply acc_head2 to both Setting Up for Installation and Troubleshooting Installation. Notice that the first one is 1.1 and the second is 1.2. Here's how it works: <n+> means add 1 to whatever the value of n is. In this case, because it was at the beginning of the file, n was zero. <n> means use whatever the existing value of n is; don't add anything to it. The < > that you entered in the acc_head1 and acc_head2 styles was to enable you create the figure-numbering style, which is next.

  8. Create some paragraphs below Configuring the SuperWidget. Type Configuring Windows 3 on one line; Configuring for Win95 on the next. Apply the acc_head2 style to these. Notice how these pick up the section 2 number.

  9. Imagine that you had a series of figures to display in Section 1 and that you wanted to number them Figure 1.1, Figure 1.2, and so on. Between sections 1.1 and 1.2, type Layout of a Basic SuperWidget, and then create a style called acc_fig. Enter Figure <n>< >.<n+>.\t in the Autonumbering Format box.

    Create some paragraphs in each of the subsections, and apply acc_fig to each one. You'll see that the figure numbering disregards the numbers in the acc_head2 sections. But note that while the figure numbers pick up section 2, they continue sequentially from the figure numbers in section 1. To fix this problem, change the autonumbering value in acc_head1 to Section <n+>.<n=0>< =0>.\t and click on Update All. The tag < =0> means to make the value for that slot zero but don't display it.

  10. One last wrinkle: imagine that you wanted to have a series of tables independently numbered running throughout this document. Create a Body paragraph anywhere within Section 1. Open the Paragraph Designer, create a style called acc_table, put T:Table <n+>. \t in the Autonumbering Format box, and then click on Update All. Create several tables in both sections and 2; notice that they use a numbering system that's separate from the section and subsection numbers. This is created by the T: which is a special label. It designates a special numbering stream called T:.

It may seem bewildering at the moment, but practice it -- it will soon become very logical and usable. Here's a summary of this autonumbering system. Imagine that you had a book in which you wanted to number the chapters Section 1, Section 2, and so on; the first-level headings, Section 1.1, Section 1.2, and so on, based on the chapter number; the second-level headings, Section 1.1.1, Section 1.1.2, and so on, based on both the chapter 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.

Style

Label

Section

Head 1

Head 2

Figure

Table

Section

M:Section

<n+>

< =0>

< =0>

< =0>

< =0>.

Heading 1

M:Section

<n>

.<n+>

< =0>

< >

< >.

Heading 2

M:Section

<n>

.<n>

.<n+>

< >

< >.

Figure

M:Figure

<n>

< >

< >

.<n+>

< >.

Table

M:Table

<n>

< >

< >

< > .

<n+>.

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

Style

Autonumber tagging

Section

Section <n+>< =0>< =0>< =0>< =0>.

Head 1

H:Section <n>.<n+>< =0>< >< >.

Head 2

H:Section <n>.<n>.<n+>< >< >.

Figure

H:Figure <n>< >< >.<n+>< >.

Table

H:Table <n>< >< >< >.<n+>.

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

By-Chapter Page Numbering

This tutorial is based on FrameMaker version 5.1 for Windows. You may see some minor differences if you are using a different version.

To create page numbers for a chapter that use the chapter number automatically:

  1. Create a paragraph component in FrameMaker for your chapters. Call it chapter, for example.

  2. Go to the Numbering properties, and specify Chapter <n+>. in the blank just below Autonumber Format. This will produce the word "Chapter" followed by the next available number every time you use the chapter paragraph component.

  3. Go Master Pages (click View and then Master Pages) and then insert page numbers as you would normally. (See the FrameMaker basics tutorial.)

  4. While still in Master Pages, set up the by-chapter numbering as follows:

    1. Place your cursor in the header or footer where you want this by-chapter numbering to appear. Click Special then Variable. Select Running H/F 3 and then click Edit Definition.
    2. In the Definition blank, type <$paranumonly[chapter]>. If you named your chapter component differently, use that name instead of "chapter." Click Edit to exit this dialog and click Insert when you get back to the initial dialog.
    3. You'll next need to insert something between the chapter number and the page number. In the footer or header where you are creating this, place your cursor between the Running H/F 3 and the # and then add a space, an en dash and then another space.
    4. Reverse these tags according to the specifications for the footers or headers you are creating.

  5. Now, return to the Body Pages and see how this looks!
Here are the steps to automate headers and footers so that they include the chapter title:
  1. Highlight the chapter title as it appears in the chapter component in the body of the file.

  2. Click Special > Marker. In the Marker dialog box, select Header/Footer $1 as the marker type (your header or footer text should be displayed in market text.) Press Edit Marker to save this definition. Notice that you have two markers for headers and footers: you can use one for odd pages and one for even pages, and create your additional ones as well.

  3. Now, go to the master page of this document (View > Master Pages, and place the text cursor in a header or footer.

  4. Click Format > Headers & Footers > Insert Other and select Running H/F 3.

  5. In the Variable dialog box, select Edit Definition and in the Edit System Variable dialog box, select <$marker1> although it may there already for you.

  6. Click Edit in the Edit System Variable dialog box and then Insert in the Variable dialog box.

  7. Go to the body page; you should see the chapter title you originally put into the marker. Try changing the marker and see how the header or footer text changes accordingly.

Whole-Book Autonumbering

If you want numbering streams to relate to your chapter number, you need to set them as follows in the Autonumber Format blanks, making certain to enter the blank spaces and period exactly as you see them here:

If you've completed this tutorial and are taking an online course in print documentation, go to the FrameMaker workshop area of the Print Documentation Chatroom and let the rest of the class know how you did on this tutorial.


Information and programs provided by hcexres@prismnet.com.