The online build tools currently support six image formats for use in figures. An extension (suffix) on the file name of the imported image designates the format of the image. You can have figures in your book that don't use the supported image formats, including composite figures composed of a combination of image formats, by means of a workaround. 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.
This chapter explains how to prepare figures during the book development process. The chapter contains these sections:
The book-building tools currently support the image formats listed in Table 6-1. Note in Table 6-1 that composite figures (figures containing multiple imported images in a single anchored frame) are supported for some, but not all, image formats.
Table 6-1. Image Formats Supported by the Build Tools
Image Format | Number of Files per Anchored Frame |
|---|---|
One or more | |
One or more | |
RGB and FrameMaker line art | One or more of either |
One | |
One | |
One |
Unsupported composite formats, such as figures composed of multiple Adobe Illustrator™ files or figures composed of multiple file formats (a combination of RGB and PostScript, for example), can be included in a book. However, these composites require a workaround (see “Workaround for Unsupported Image Types”).
All image files, including the elements of composites, must be stored in the orig directory. As with supported figures, the elements of unsupported composites must be listed in the Makefile and imported from the print directory.
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 6-2 shows the standard extension for each image format that is currently supported. Notice that Table 6-2 does not include an extension for FrameMaker line art, since line art figures are not imported files:
Table 6-2. Image File Naming Conventions
File Format | Extension |
|---|---|
Adobe Illustrator PostScript | |
color RGB | |
black and white RGB | .bw[a] |
Non-Illustrator PostScript | |
GIF | |
XWD | |
[a] These images are screen snapshots (or other RGB files) that have been converted to black and white with the tobw utility. | |
The local working directory for a book contains three subdirectories for use with figures:
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.
The Makefile contains variables that specify image formats and conversion processes. Use the following instructions when listing image files in Makefile. List each image file in only one place in the Makefile. You might also find it useful to look ahead to Table 6-3 when deciding where to list image files in the Makefile.
| 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.
| |||
| PRINT_COLOR = |
| |||
| 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 InSight Professional Publisher.
| |||
| RGB= | Use this variable to specify images that should be processed for 24-bit color in the online version of a book. All image files on the RGB line must be stored in orig with an .rgb extension. Note that 24-bit images may appear dithered on some monitors, and InSight doesn't display in 24 bits by default; many or most customers won't see your images in 24 bits even if you include 24-bit images with your book.
| |||
| 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 will appear in color in both the printed and the online versions of your book; black and white XWD files will 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. This type of image is sometimes present in documentation created outside of Silicon Graphics, but the BW line is almost never needed for images generated with Silicon Graphic tools |
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 and online directories and how to import images into FrameMaker files from print:
If you've already copied the Makefile template to your local working directory, skip to step 2. If you haven't already done this, do it now:
% cp /usr/share/Insight/templates/make/Makefile_books Makefile
The Makefile file specifies information about your book to the build tools. It contains variables that you must set and instructions for how to set them. See “Editing the Makefile” for additional information.
Change write permissions on your copy of the Makefile file.
% chmod 664 Makefile
Edit the Makefile template.
% vi Makefile
(You can use a different text editor, such as emacs or jot, if you prefer. If you use FrameMaker to edit this file, be sure you save as text when you're done editing.) Set the image variables in the Makefile that apply to your imported image files, such as PostScript and PRINT_BW (see “Processing and Importing Image Files”). At this point you can also set the other variables, such as TITLE and BOOK_FILES, if you wish, but only the image variables are required to generate the print directory.
Execute 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.
Import your image files. See Table 6-3 for filename extensions.
Open each FrameMaker file that should contain imported images. The method that you use to import the image files depends on the current importing settings in the document files:
If your FrameMaker files do not specify orig or print as the location of imported image files, the FrameMaker application warns that it can't import the files. To continue, specify the print directory as the new location of your image files.
If your FrameMaker files specify orig as the location of the imported image files, the FrameMaker application does not issue a warning; it opens the files, importing images from the orig directory. In this case, you must re-import all of the image files, specifying the print directory as the image file location. To re-import image files, temporarily rename the orig directory, then reopen the document file to generate a FrameMaker error. Specify the print directory version of the image files in the error dialog box. When the re-importing is complete, rename the temporary directory to orig.
If your book contains images with unsupported formats, use this workaround to prepare the images for processing by the book-building tools. This procedure assumes that you already have an anchored frame in your FrameMaker file that contains an unsupported image format:
Snap the composite picture as an RGB file.
Copy the new RGB file to the orig directory.
Add the new image file to the PRINT_BW line in Makefile.
Execute the make _print command to add the file to the print directory.
Create a second frame in your FrameMaker document:
Using the same Fig paragraph tag, insert a second anchored frame below the location of the original frame containing the unsupported image.
Note: Be sure that you have a single figure title for the anchored frame pair. The title should appear below the second frame. Import the .bw image into the new frame from the print directory.
Tag the frame containing the unsupported version of the figure with the PrintOnly conditional text tag.
The PrintOnly tag appears on the Conditional Text menu.
Tag the frame containing the .bw version of the figure with the OnlineOnly conditional text tag.
The OnlineOnly tag appears on the Conditional Text menu.
| Note: When you print the document, be sure to turn off the OnlineOnly condition using the Show/Hide selection on the Conditional Text menu. During the book-building process, the PrintOnly condition (among others) is turned off automatically. |
Occasionally, you may find that the quality of a printed version of an image created by automatic conversion is unacceptable. This may happen, for instance, if your images have a black background that shows up fine online, but overwhelms any reversed-out line art in print. To produce a custom version for print:
Perform a screen snap on the original version and put it in the orig directory.
Edit the Makefile as usual and execute make _print.
Modify a copy of the original file and put it in the print directory.
This modification might involve either of these tasks:
Running an image processing tool on the file.
Changing the X resource values for an application to increase contrast, and re-snapping a window with contrasts acceptable for a black and white book.
Import the print version of the figure as usual.
| Note: This process works because make does not reprocess an image file for the print directory if the file in print is more recent than its counterpart in the orig directory. For this reason, you must recreate a custom print version whenever you update the original. If you do not recreate the custom version, make will replace the custom version with the newer, automatically generated version that does not contain your changes. |
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 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 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 4, “Finding and Fixing Online Book 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 6-3 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 6-3 also shows the file extension in the orig and print directories and the Makefile variable where the file should be listed.
Table 6-3. Image Formats for Hard and Soft Copy
File Format | FrameMaker | IRIS InSight | Suffix | Makefile | Suffix |
|---|---|---|---|---|---|
RGB | black/white RGB | GIF | .rgb | PRINT_BW | .bw |
black/white RGB | black/white RGB | GIF | .bw | BW | .bw |
RGB | RGB | GIF | .rgb | PRINT_COLOR | .clr |
RGB | RGB | 24-bit RGB | .rgb | RGB | .rgb |
AI PostScript | AI PostScript | GIF | .ai | PostScript | .ai |
PostScript (non-AI) | PostScript (non-AI) | GIF | .ps | PostScript | .ps |
GIF | GIF (not viewable) | GIF | .gif | GIF | .gif |
XWD | XWD | GIF | .xwd | XWD | .xwd |
For all image formats except black/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/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.