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.

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 for each tagged word or phrase. Refer to the English version of a document for the correct character tag.

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.

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:

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 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.

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.

---

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).

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.

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.

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.

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.

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.

---

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 markers need to be translated in book undergoing localization. To do this:

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.

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.

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.

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

orig		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.
print		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.
online		This directory contains all image files that will be used in the online version of your book.

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.

---

PRINT_BW =		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.
PRINT_COLOR =		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.
GIF=		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.
RGB=		Do not to use this variable.
XWD=		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.
BW=		Specifies RGB-format images that have already been converted to black-and-white format.

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:

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
margin.

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.

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

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.

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.