The online build tools can 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 bookbuilding tools currently support the image formats listed in Table 5-1. Note in Table 5-1 that composite figures (figures containing multiple imported images in a single anchored frame) are supported for some, but not all, image formats.
Table 5-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 “Using 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 5-2 shows the standard extension for each image format that is currently supported. Notice that Table 5-2 does not include an extension for FrameMaker line art, since line art figures are not imported files.
Table 5-2. Image File Naming Conventions
File Format | Extension |
|---|---|
Adobe Illustrator Encapsulated PostScript | |
color RGB | |
black and white RGB | .bw[a] |
Non-Illustrator Encapsulated 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 5-3 when deciding where to list image files in the Makefile.
A completed desription of the Makefile and how to edit all its parameters can be found in “Editing the Makefile” in Chapter 6.
| 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 = | 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.
| |||
| EPS = | Use this variable to specify all Encapsulated PostScript images (including Adobe Illustrator EPS 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 IRIS 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. |
The drawing tools in FrameMaker allow users to work with straight and curved lines, circles, polygons, and text. Frame artwork is PostScript-based and commonly used for simple illustrations or callouts to imported artwork.
To create FrameMaker line art:
Press Enter to create a new paragraph.
Press Enter again to create a paragraph that automatically has the FigTitle paragraph tag applied to it. Type in the figure title.
Place the cursor in the Fig paragraph and Choose Special > Anchored Frame.
In the Anchored Frame dialog box, choose these settings:
Anchoring Position: Below Current Line
Alignment: Right
Cropped
Size: width = 5.375” and height = your choice (the frame can be resized once it's inserted)
Click New Frame.
Choose Graphics > Tools.
Use the drawing tools with a line weight of 0.5 pts. to create your simple diagram.
Use the A button to create a text cursor and click it in the anchored frame.
Choose Callout from the font catalog and type the callout.
Avoid using CalloutBold and CalloutSmall.
Do not use text boxes.
Select the callout using the Object Selection tool (the black arrow in the Tools GUI) and position the callout using the Ctrl and arrow keys.
It's often necessary to use screen captures as illustrations in books. There are a variety of tools available to aid you in producing screen captures; use whichever seems most appropriate to your needs.
The snapshot utility (/usr/sbin/snapshot) is part of the IRIX 6.2 and later system software, in the eoe.sw.gltools software subsystem. snapshot reads an area of the screen specified by the user and saves it to a file named snap.rgb in your home directory. This utility can capture an entire screen. For more information on snapshot, refer to the snapshot man page.
IRIS InSight Professional Publisher includes three shell-script capture utilities, all of which can be found in /usr/share/Insight/bin and are part of the insight_dev.sw.tools subsystem. All three scripts require /usr/sbin/scrsave (which is part of the eoe.sw.gltools subsystem in the IRIX 6.2 and later distributions).
To use these tools, you must append /usr/share/Insight/bin to your path or PATH environment variable. This variable is initialized in your ~/.cshrc file if you use the C shell or a shell derived from the C shell, and in your ~/.profile file if you use the Bourne shell or a shell derived from it. Be sure to use the rehash command after editing your .cshrc file.
| bsnap | Snaps a bordered image without rubber-banding and captures screen images to RGB. Allows variable time delay with the -s command-line option. Includes window borders by default; to avoid window borders, use the -n option. | |
| ssnap | identical to bsnap, except that after capturing a window, it shrinks the window to 65% of its size in both horizontal and vertical directions, then brightens and sharpens the result. ssnap requires /usr/sbin/izoom and /usr/sbin/hipass3, both of which are part of the eoe.sw.imagetools subsystem. | |
| winsnap | Has no command-line options. Doesn't capture window borders. |
In addition to these tools, if you have an Indy or O2 system you probably have the /usr/sbin/capture utility installed on it. capture, an interactive program that records digital media files, is part of the dmedia_tools.sw.movietools subsystem. It can capture images from an IndyCam or O2CAM, a video input, or the screen. See the capture(1) reference page for more information.
Name your screen capture figure files descriptively, so that someone else can tell which figures go where. The filenames should end in the .rgb suffix. For example, if your book is called MyBook, and you have three figures in chapter one, you might name the figures mybook_fig1.1.rgb, mybook_fig1.2.rgb, and mybook_fig1.3.rgb. Or you might use descriptive names such as 01.1.sample.rgb, 01.2.menubar.rgb, and 01.3.dialog.rgb.
The screen capture procedure is slightly different depending on what you want to capture: full windows, portions of windows, or pull-down menus. Note that for any of these approaches, if you want to show your screen capture against a white background, you must first place the background, then place the window you're capturing on top of that background. One way of doing this is to open a shell window with a white background:
% xwsh -bg white |
If you want to capture an entire window, with or without its borders, use bsnap.
In a shell window, change to the directory where you are going to store the screen captures (the orig subdirectory of your book's working directory).
Decide what you're going to name the screen capture. (See “Screen Capture File Names” for some guidelines.)
Bring the window you want to capture to the front, leaving part of your shell window visible.
If you want to include the window's border (including its title bar), launch bsnap from the shell window:
% bsnap filename
If you don't want to include the window's border, launch bsnap like this:
% bsnap -n filename
Click anywhere in the window you wish to capture.
Wait a few seconds for the capture to complete.
Verify that the capture worked as desired:
% ipaste filename
If the image isn't as you expected, repeat steps 3 through 8.
If you only want to snap part of a window, it's best to use snapshot.
Change to the directory where you are going to store the screen captures (the orig subdirectory of your books' working directory).
Decide what you're going to name the screen capture. (See “Screen Capture File Names” for some guidelines.)
Bring the window you want to capture to the front, leaving part of your shell window visible.
Start snapshot from the shell window:
% snapshot
Use the right mouse button in the snapshot window to bring up the snapshot menu. Select “New file name” from that menu. Enter the name you want your screen capture to have. Press Enter.
Move the snapshot window out of the way:
Move the cursor over the snapshot window.
Press Alt+F7.
Move the cursor; the snapshot window's outline moves with it.
Click the left mouse button when the window is where you want it.
With the cursor still in the snapshot window, hold down the Shift key to let snapshot retain keyboard and mouse focus.
Still holding down the Shift key, move the camera cursor into the window you want to capture.
Drag out a rectangle, using the left mouse button, around the portion you want to capture.
Move the cursor off to one side and, still keeping the Shift key depressed, use the right mouse button to bring up the snapshot menu. Choose “Save as filename” from that menu.
To make additional screen captures, repeat steps 7 through 10.
Use the same procedure for pull-down menus as for complete windows, except:
Use bsnap -s 5 to make bsnap delay five seconds before beginning the capture.
After you click in the window you're capturing from, quickly pull down the menu you want to capture. Keep it pulled down for several seconds, until bsnap finishes.
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_sgidocbk Makefile
(for books to be built using the SGIDOCBK DTD)
or
% cp /usr/share/Insight/templates/make/Makefile_sgmldoc Makefile
(for books to be built using the SGIDOC DTD)
Note: The functionality of the two DTDs is essentially the same; the online appearance is different, however, especially for character tags. Before converting all your bookbuilding to the new SGIDOCBK DTD, you'll want to perform a sample bookbuild and view it in IRIS InSight to ensure its online appearance more closely matches your company's style guide than the appearance created by SGIDOC. 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” in Chapter 6 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 nedit, 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 as described in “ Figure Tags” in Chapter 3. See Table 5-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 bookbuilding 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 bookbuilding 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 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.
Table 5-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 5-3 also shows the file extension in the orig and print directories and the Makefile variable where the file should be listed.
Table 5-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 |
Adobe Illustrator Encapsulated PostScript | Adobe Illustrator Encapsulated PostScript | GIF | .ai | EPS | .ai |
Encapsulated PostScript | Encapsulated PostScript | GIF | .eps or .ps | EPS | .eps or .ps |
GIF | GIF | 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.