Chapter 3. Using FrameMaker Files and IPTemplate Features

This chapter provides information on how best to use FrameMaker features to produce online and printed books, as well as pointers to related information elsewhere in this book.

All FrameMaker files supplied to you for localization have been authored using the IRIS InSight Professional Publisher IPTemplates. The paragraph and character tags, tables formats, cross-reference formats, conditional text tags, MIF markers, master pages, and reference pages should be consistent from one file to the next.

In the process of translation, tags or markers may be unintentionally removed or it may become necessary to replace a figure with its localized version. Instructions for restoring or updating those tags and markers are included in the following sections:

Note: While translating a book, please do not add paragraph tags, character tags, or markers, and try to avoid deleting markers. Always use the new English version of a document as the guideline for choosing tags and placing markers.

Tagging FrameMaker Files

Before you begin, be sure you are using files created using IPTemplates. The example files included with the IPTemplates in your vendor kit contain information on basic tagging sequences and standard uses of the various tags.

This section offers some general tips for tagging.

Use Character Tags, Not Character Formats

If you want individual characters to look a certain way, be sure to use the supplied character tags to change their look. Do not use the FrameMaker character designer tool to simply change the format of a character. The build tools look only at tags, not at any modifications you may have made to a character's format.

Use Valid Tag Sequences

The example files that come with the templates contain descriptions of the various tags and where/how they may be used. For example, don't put the ChapTitle tag before the ChapNum tag, or the FigTitle tag before the ChapTitle tag, or the Heading2 tag directly after the ChapTitle tag. The online translator expects to see only certain sequences of paragraph and character tags and produces errors for what it considers invalid sequences.

Note: Do not create your own tags. The build tools cannot translate unknown tags.

Use the Correct Character Tag

Use the correct character tag for each tagged word or phrase. Refer to the English version of a document for the correct character tag.

Create Equations as Figures

The current build tools do not support FrameMaker equations. If you want an equation in your online book, you must use snapshot or other screen-capture tools to snap a picture of the equation. snapshot saves the equation as a .rgb file and you can import a .bw version of this .rgb file as if it were a figure. Don't give the equation a figure title, though, or it will show up in the list of figures as a figure.

Don't Use Character Tags on Tabs, Soft Returns, or Hard Returns

In general, try to keep character tags on the specific word or phrase you're tagging, without tagging surrounding whitespace. In particular, never apply a character tag to a tab or a soft return[1] . It is easy to apply character tags to whitespace characters by mistake, particularly when you're working with a hanging list (note that a tab character that has a character tag applied to it generates a warning message), so be careful.

Here are a couple of things to watch out for when tagging:

  • If possible, select the word you're tagging by double-clicking it. This keeps you from accidentally selecting extra spaces or tabs.

  • It's sometimes difficult to see your selection clearly in FrameMaker, so it is hard to notice if you've selected spaces or tabs in addition to words. If you've accidentally tagged a hard return or a soft return along with the preceding word, insert a space between the return and the word before it. Tag this space with the Default Paragraph Format character tag. This procedure is necessary because hard and soft returns in FrameMaker take the character tag of the character preceding them; you can't just tag the return itself to fix the problem.

Don't Put Tabs in Code

Format code examples with spaces, rather than tabs. Tabs in code don't display properly online.

If you are copying or importing any code examples into your FrameMaker file, be sure to turn the FrameMaker Smart Spaces feature off. Otherwise, multiple spaces will be squashed down to one space and you'll lose your formatting. Also, turn off Smart Quotes so that code samples use straight quotation marks instead of curved ones. Be sure to turn on Smart Spaces and Smart Quotes after you're done working with code samples.

Create Valid Copyright and Trademark Symbols

Create copyright, registration, and trademark symbols according to the instructions listed here. If you use any other method for creating these symbols, you'll run into problems when you convert your files to SGML.

  • To create the copyright symbol (©), hold down Ctrl and press Q, then release both keys, hold down Shift, and type a zero (0).

  • To create a registered trademark symbol (®), hold down Ctrl and press Q, then release both keys, hold down Shift, and type a nine (9). Apply the Superscript character tag to the registered trademark symbol after it is inserted.

  • To create a trademark symbol (™), hold down Ctrl and press Q, then release both keys, hold down Shift, and press eight (8). Apply the Superscript character tag to the registered trademark symbol after it is inserted.

Create Valid Dashes

Create en dashes and em dashes according to the instructions listed here. If you use any other method for creating these symbols, you might create problems when you convert your files to SGML.

  • To create an en dash (–), hold down Ctrl and press Q, then release both keys, hold down Shift, and press P.

  • To create an em dash (—), hold down Ctrl and press Q, then release both keys, hold down Shift, and press Q.

Note: En and em dashes do not translate properly in Japanese documentation.


Footnotes and table footnotes are supported in IRIS InSight. To create them, use the Footnote paragraph tag (for footnotes within text) or the TableFootnote paragraph tag (for footnotes in tables).

Hanging Lists

A paragraph tagged as HangingList should look like the following when View > Text Symbols is activated:

"testseite">   Dise Wahl wird im ....

When the HangingList item extends beyond the delimiter, the paragraph should look like the following:

"testseite senden"><
               Dise Wahl wird im ....

Notice that a tab comes before the soft return. The tab is required in order for the build tools to create the structure of the online HangingList.

Using Conditional Text

The IPTemplate supports six text conditions which allow for several different outputs from a single Frame source. Table 3-1 describes these conditional text settings and their use. Note that some “legacy” documents include additional conditional text settings that are no longer used but have not been removed from the Frame source. These obsolete settings are still supported during bookbuilding.

Note: During bookbuilding, appropriate Show/Hide settings are automatically set with the application of the conditional.doc file (which is in the FrameMaker-to-.mif translation portion of the bookbuild tools). Conditional text show/hide settings need only be applied as shown in Table 3-1 when the book is scheduled for print and PostScript files must be generated as a deliverable.

Table 3-1. Conditional Text Settings

Conditional Text




Applied to an anchored frame containing the separated image for a color print book



Applied to text meant as a reminder to the writer or a note to the editor



Applied to the portion of text following a help topic that is intended to show up as “help” in SGIHelp (if the whole HelpTopic-to-next-HelpTopic section of text is not intended to be help)



Apply to index entries; used in conjunction with the Index marker and a Framemaker indexing macro



Apply to HelpTopic paragraphs or any text that should be seen only in the online version of a book



Apply to any text that should be seen only in the print version of a book.


Creating Online Links

Links are connections between items of information, whether within the same online book or between separate online documents. When the reader clicks a linked item (whether text or an icon), either the IRIS InSight viewer scrolls to the referenced material, or the material appears in a popup window (depending on what kind of material is referenced).

Links fall into two groups based on whether they are automatically generated from the structure of the document (structural links) and require no writer effort, or explicitly created by the writer during document development (writer-generated links).

Automatic Links

A structural link is automatically created from the structure of the document during the conversion process. Lists of such links appear in the various Views in IRIS InSight. All the headings listed in the Table of Contents (TOC) view in IRIS InSight, for example, are automatically linked to the corresponding headings within the book itself. The same goes for all figures, tables, and media shown in their respective View lists. The result is that a reader can click any item in a list view and the text area scrolls to the appropriate place in the online book.

Writer-Generated Links

The writer can use various FrameMaker tools to create links to text, tables, or figures in the same book (or in another book), between the text and the glossary, between the text and a reference (man) page, or between the index and the text. The use of specific markers can also allow for launchable URLs. Each link has its own appearance and behavior.

Table 3-2 summarizes the writer-generated link types.

Table 3-2. Cross-Reference Link Types

Link Type

How to Create

Appearance in
IRIS InSight

Link Behavior

Cross-reference to text or table within a book

Use the FrameMaker cross-reference format.

Cross-reference appears in bold blue in the text.

Viewer scrolls to referenced information.

Cross-reference to a figure within a book

Use the FrameMaker cross-reference format.

Cross-reference appears in bold blue in the text.

Viewer scrolls to referenced figure. Click on figure title and figure comes up in a restricted view.

Cross-reference to a table within a book

Use the FrameMaker cross-reference format.

Cross-reference appears in bold blue in the text.

Viewer scrolls to referenced table. Click on table title and table comes up in a restricted view.

Cross-reference to an example within a book

Use the FrameMaker cross-reference format.

Cross-reference appears in bold blue in the text.

Viewer scrolls to example title.

Cross-reference to another book (see Chapter 4, “External Cross References and Multiple Link Targets”)

Use the FrameMaker cross-reference format MIF markers 18 and 19.

Cross-reference appears in red in text.

Referenced information appears in new viewer.

Glossary link

Use the FrameMaker character tag, GlossaryItem; then create a glossary entry in your book's glossary file.

Item is underlined.

Definition appears in a pop-up window.

Index link

Use the FrameMaker index marker.

Index entry appears in the Index View. Instead of a page number, location in the text appears as bold blue cross- reference to the associated heading/title.

Viewer scrolls to referenced information.

Reference page link

Tag an item with the RefPage character tag.

Item appears as red text.

Text window appears containing indicated reference page.

Inline media

Use the InlineObj and InlineTitle paragraph tags. See “InSight Inline Object Tags” in the sample chapter file (in the samples subdirectory of the template directory) for details of syntax.

Object appears in media viewer inside InSight viewer window.

Media viewer controls appropriate to media type allow user to manipulate or view media.

Launch an application (including a World Wide Web browser)

Use a FrameMaker marker of type 17, as indicated in “Markers” in the sample chapter file (in the samples subdirectory of the template directory).

Either icon in margin or hot text, depending on how you set up the link.

Application comes up in a new window.

Creating Cross-Reference Links Within a Book

Cross-reference links within a book are created using the FrameMaker Cross-Reference tool. They appear as bold blue text within the online document. When the reader clicks the link, IRIS InSight either scrolls to the text if the link is to a table or text, or opens the figure in a restricted view if the link is to a figure.

Be sure to use an appropriate cross-reference format. Note that the conversion tool automatically removes any page numbers that appear in your cross-reference text. If your book will appear in print as well as online, it's a good idea to use cross-reference formats that include page numbers to help hard copy readers navigate through the book.

Creating Glossary Links

Glossary links appear as underlined words in the online text. When the reader clicks on the word, the definition appears in a restricted view. The link itself is either to the Silicon Graphics Glossary of Terms (007-1859-nnn, a global glossary common to all books), or to a local glossary specific to the book. IRIS InSight searches the local glossary first (if it exists), then searches the global glossary.

To make a glossary item, tag the word using the GlossaryItem character tag. In order to match, the text that you tag GlossaryItem must be spelled and punctuated identically to the text of a GlossaryTerm in your glossary.

This restriction (requiring the linked reference to be identical to the entry) can cause some problems in localized documents. For instance, if you have a glossary entry for the term “window,” you can't link to it from the words “windows” or “windowing” in the text; and it can be difficult to re-word the text to fit the format of the glossary entry. One workaround for this problem is to create additional cross-referencing glossary entries for those words—have an entry for “windows,” for instance, which simply says “see `window,'” with the word “window” linked to the glossary entry. (You can put glossary links inside the glossary itself.)

Note: A common problem with glossary items occurs when a GlossaryItem-tagged word has a space in front of it that is also tagged as a GlossaryItem. If a GlossaryItem is more than one word, sometimes the space between the words is not selected as a GlossaryItem; in these cases it is as though two different glossary items were selected.

Creating Index Entries

Creating New Index Entries

Index entries appear in the Index View in much the same way as they would in a hard copy index. The major difference is that instead of a page number, the location in the text appears as a bold blue cross-reference to the associated heading or title.

Use FrameMaker Index markers to create index entries for the back-of-the-book index (so called to distinguish it from the full-text index that the build tools create).

Online books require certain limitations in index entries:

  • Index entries can be no more than three levels deep.

  • You cannot put an index marker in a table footnote.

  • A character format in an index entry cannot cross a semicolon or colon boundary; for instance, <Italics>entry:subentry<Default Para Font> won't work the way you might expect it to. Instead, you'd have to use <Italics>entry<Default Para Font>:<Italics>subentry<Default Para Font>.

  • Special characters that result in entity references (such as special characters for localized languages) may not sort correctly in the online index.

  • Sorting ignores these characters if they appear as the first character in an index entry: “, <, $, ., /, and <space>.

Translating or Updating Existing Index Entries

Index markers need to be translated in book undergoing localization. To do this:

  1. Select Find/Change from the Edit menu.

  2. Choose “Marker of Type:” from the pulldown menu next to the Find field.

  3. Enter Index in the field to the right of “Markers of Type:”.

  4. Click the Find button.

When an Index marker is found, select “Marker …” from the Special Menu and edit the text. Click the Edit Marker button when the change is complete. Use the Find/Change utility to continue searching for Index markers.

Creating Tables

Use the FrameMaker Table > Insert Table feature to create tables. Use one of the FrameMaker table formats labeled TableXcol.

You can include footnotes in a table if you use the FrameMaker paragraph tag TableFootnote rather than the tag Footnote.

Working With Figures

Silicon Graphics online build tools can support six image formats for use in figures. An
extension (suffix) on the filename of the imported image designates the format of the image. Except for FrameMaker line art, all images must be imported by reference into a FrameMaker document, from the print subdirectory of your book directory.

Original image files and the components of composite figures are stored in a directory called orig. During the build process, the images in orig are processed and placed into two additional figure-related directories that the build process generates: print, which contains processed images for the hard-copy book; and online, which contains processed images for the online book. All image files in orig must be listed in the Makefile to specify how the build tools should process them.

For localized books that include screen captures or “snaps” of GUIs, wait until after the operating system or application default files are translated before capturing replacement GUIs. A utility such as snapshot can be used snap GUIs. Composite images, or screen snaps which have FrameMaker callouts and arrows added within the anchored frame, may be updated in an application such as Adobe Photoshop.

If a figure is deleted and needs to be reimported, import the figure as “by reference only” from the print directory.

Supported Image Formats

The book-building tools currently support the image formats listed in Table 3-3. Note that composite figures (figures containing multiple imported images in a single anchored frame) are supported for some, but not all, image formats.

Table 3-3. Image Formats Supported by the Build Tools

Image Format

Number of Files per Anchored Frame


One or more

FrameMaker line art

One or more

RGB and FrameMaker line art

One or more of either

Encapsulated PostScript, including Adobe Illustrator






Image File Naming Conventions

The orig directory normally contains at least one image file for each figure in your book (composite figures may use more than one file). The filename for each image file in the orig directory must end with a standard extension (or suffix) that designates the format of the image.

Table 3-4 shows the standard extension for each image format that is currently supported. Notice that Table 3-4 does not include an extension for FrameMaker line art, because line art figures are not imported files.

Table 3-4. Image File Naming Conventions

File Format


Adobe Illustrator PostScript


color RGB


black and white RGB


Non-Illustrator PostScript

.ps or .PS





[a] These images are screen snapshots (or other RGB files) that have been converted to black and white with the tobw utility.

Figure Subdirectories

The local working directory for a book contains three subdirectories for use with figures:


Place all original image files in this directory. All RGB snaps, Adobe Illustrator files, and other original pieces of art belong in this directory.

For books that are printed in color, store the color versions for the printed copy in orig; import a black and white FPO (For Position Only) version into the FrameMaker document from the print directory.

Note: If you have localized the callouts on a figure, or have done a new screen capture of a localized menu or dialog box, name the figure file with the same name as its English equivalent.


This directory, once you've populated it by using the make print command, contains all image files that will be used in the printed version of your book. Any image files that are imported into anchored frames must be imported from the print directory.


This directory contains all image files that will be used in the online version of your book.

Adding Image Files to the Makefile

The Makefile controls the conversion of images into the appropriate format for the online and printed versions of your book. During the build process, the build tools automatically convert imported file references into the appropriate references to the online directory.

Note: There should be no reason to change or add image files to the Makefile. For images with localized callouts or GUIs, ensure that they have the same filenames as their English equivalents before copying them into the orig directory.


Use this variable to specify original RGB color images that will be imported as black and white images for the printed book. The files that you list on the PRINT_BW line appear as eight-bit color GIF images in the online book. All image files listed on the PRINT_BW line must be stored in the orig directory with a .rgb extension.

Note: Files listed in the PRINT_BW variable can't be part of a composite figure.


Use this variable to specify RGB color images that will appear in color in both the printed version and the online version of your book. The files that you list on the PRINT_COLOR line appear as color GIF images in the online book. All image files listed on the PRINT_COLOR line must be stored in the orig directory with a .rgb extension.

PostScript =  

Use this variable to specify all PostScript images (including Adobe Illustrator files) in your book. These images appear in color in FrameMaker and in the online version of your book; they appear in color in the printed version if printed on a color printer. Image files listed on the PostScript line must be stored in the orig directory with either a .ps or a .ai extension.


Use this variable to specify all GIF images in your book. All image files listed on the GIF line must be stored in the orig directory with a .gif extension. Color GIF files appear in color in the online version of your book; black and white GIF files appear in black and white in the online version of your book. Be sure to use GIF 87a format instead of GIF 89a; you can use the file command to find out what format a given file is in. Some version of the togif utility translate to GIF 89a; be sure to use the version of togif that comes with IRIS InSight Professional Publisher.

Note: FrameMaker does not display or print GIF images.


Do not to use this variable.


Use this variable to specify all XWD images in your book. All image files listed on the XWD line must be stored in the orig directory with a .xwd extension. Color XWD files appear in color in both the printed and the online versions of your book; black and white XWD files appear in black and white in both the printed and the online versions of your book.


Specifies RGB-format images that have already been converted to black-and-white format.

Processing and Importing Image Files

All image files used in a book must be imported into a FrameMaker document from the print directory for a book to build successfully.

This procedure explains how to generate and populate the print directory:

  1. In the book directory, run the make print command:

    % make print 

    The make print command creates a print directory and copies the files from orig to print, converting any formats as needed.

  2. Open each FrameMaker file that should contain imported images.

There are two tags used for figures that appear inline in the hard copy: Fig and FigTitle.
The template also uses a third tag (FigTitleMargin) for figures that appear in the margin
of the hard copy. The Fig tag should not have any text in it. Its sole purpose is to serve as
placeholder for the anchored frame that holds the figure. FigTitle follows immediately
after Fig, and holds the title of the figure. FigTitleMargin holds the title of figure in the

Setting up Figures

Use this procedure to set up figures correctly:

  1. Place the cursor at the end of the paragraph containing the reference to the figure.

  2. Press Enter to create a new paragraph.

  3. Apply the Fig paragraph tag to the paragraph.

  4. Press Enter again to create a paragraph that automatically has the FigTitle paragraph tag applied to it, and type in the figure title.

  5. Place the cursor in the Fig paragraph and select Anchored Frame from the Special menu.

  6. In the Anchored Frame dialog box, choose these settings and then click New Frame:

    • Anchoring Position: Below Current Line

    • Alignment: Right

    • Cropped, (not Floating)

    • Size: width = 5.375” and height = whatever is appropriate for your figure (the frame can be resized once it's inserted)

  7. Import your figure by reference from the print directory into the anchored frame, using the File > Import > File dialog box. See Figure 3-1.

    Figure 3-1. Dummy Figure Title Using FigTitle Paragraph Tag

Note: To select a text object in an anchored frame, the anchored frame itself, or a text column on a page without opening the toolbox and changing to the arrow selection tool,
simply hold down Ctrl while clicking on the object. Pressing Shift and clicking over an object selects or deselects additional objects after the first object is selected.

Use the micro-adjust feature to move graphic objects in incremental (smaller than grid units) steps (even when Snap is turned on): hold down Ctrl and use the arrow keys to move objects.

Things to Remember About Figures

For your book to build properly (without errors) you must follow all the rules in this list:

  • Import all images by reference from the print directory. When you build your book, the online tools automatically grab the corresponding images from the online directory for display in IRIS InSight.

  • Import each image into an anchored frame. For figures that appear within normal page boundaries, the frame must be anchored to an empty paragraph (blank line) that is tagged with the Fig paragraph tag.

  • In order for a figure title to appear in the List of Figures in IRIS InSight, the Fig paragraph tag has to be followed by FigTitle paragraph tag.

  • Margin figures are composed of two anchored frames, one for the image and one for the caption. The anchored frame for the caption cannot appear before the anchored frame for the figure. If it does, the .err file for the chapter containing the margin figure will contain an error message (see Chapter 6, “Debugging Bookbuild Errors”).

    Margin figures occasionally cause translator errors, producing the error message “Cannot process indirect frame on page...” To correct this error, save the FrameMaker file containing the margin figure in MIF format, then open the .mif file and save it as a .doc file.

Table 3-5 lists the various file formats that can occur in the orig directory. For each format, it shows the format of the file in a FrameMaker document, which produces the hard-copy version of the figure, and the format of the file in IRIS InSight, which produces the figure in online books. Table 3-5 also shows the file extension in the orig and print directories and the Makefile variable where the file should be listed.

Table 3-5. Image Formats for Hard and Soft Copy

File Format
in orig

File Format

IRIS InSight
File Format

in orig


in print


black/white RGB





black/white RGB

black/white RGB













24-bit RGB




AI Encapsulated PostScript






Encapsulated PostScript (non-AI)

Encapsulated PostScript (non-AI)






GIF (not viewable)











For all image formats except black-and-white RGB, color palette information remains unchanged during image file processing. This means that a black and white original produces a black and white figure, and a color original produces a color figure.

For the black-and-white RGB format, color palette information is reduced to black and white during processing. This means that both black and white and color originals produce black and white figures.

[1] You can create a soft return by holding down the Shift key and pressing Enter.