The book-building process creates SGML files from FrameMaker source files. It also generates the additional files that are required to view the SGML using the IRIS InSight viewer or the SGI Help viewer. The build process also generates error reports to help you debug source files and create error-free online documents.
To invoke the build process, use the make command. You can give make a variety of arguments to perform different build-related tasks. The make command reads a file called Makefile, which describes the book and the source documents using a set of variables. Once a book is built, writers and production editors can proofread it while viewing it in IRIS InSight, and/or test the resulting online help.
This chapter explains how to build a book, generate error reports, and view the built book with IRIS InSight. The chapter includes these sections:
 | Note: The build process goes more smoothly if you compose and import figures, and then use the Generate/Update command in the FrameMaker book file, before beginning the build. |
The Makefile specifies the FrameMaker files that compose the book and gives information about the figure files in the book. The Makefile also specifies the short title and full title of your book, the part number and date, any foreign language attributes, and the bookshelf where the book is displayed. An edited version of the Makefile that contains the specifications for your book must be stored in your local working directory to build the book.
| Note: Be prepared to supply the short title (see “Choosing a Book's Short Title” in Chapter 2), bookshelf, and a list of your document and figures files during this procedure. (Though you can change any of these things and rebuild the book later if necessary.) |
The Makefile is self-documenting; it contains instructions on what to add and where to add it. The procedure that follows provides supplementary information for editing Makefile.
Edit the TITLE variable:
Specify the short title for your book as the value for the TITLE variable. For help choosing a short title, see “Choosing a Book's Short Title” in Chapter 2.
Note: Do not use the short title of your book as the basis for the name of any files in your document other than the book file. For example, if short_title.book is the name of your book file, then short_title.doc is not a valid filename (though short_titleCh1.doc is a valid filename). Edit the FULL_TITLE variable.
Specify the full title for your book as it appears on the cover. For help choosing a full title, see “Choosing a Book's Title” in Chapter 2.
Edit the VERSION variable.
Specify the version number, month and year for this revision. The version number for a Silicon Graphics book is the part number for the book. For example:
007-2863-001, 9/95
Edit the BOOKSHELF variable.
Specify the directory in which your company's bookshelves are located and bookshelf on which your book is to appear in the InSight library, in this form: /usr/share/Insight/library/companyname_bookshelves/companyname. (You can use a standard abbreviation of your company's name as your companyname if you wish, but in that case all books from a given company must use the same abbreviation.) For instance, a company named YoyoDyne Systems would specify /usr/share/Insight/library/YoyoDyne_bookshelves/YoyoDyne for the BOOKSHELF variable; the books would then appear in InSight under a bookshelf named “YoyoDyne.” Note that since companyname is part of a directory name, it must follow all rules for UNIX filenames—for instance, companyname can't contain characters such as spaces, slashes, or asterisks.
Silicon Graphics publications can appear on any of three bookshelves: SGI_EndUser, SGI_Developer, and SGI_Admin. Field Engineer manuals go on the SGI_Service bookshelf. All Silicon Graphics bookshelves are in the /usr/share/Insight/library/SGI_bookshelves directory.
Edit the BOOK_ICON variable.
Specify which icon should represent your book on the bookshelf in InSight. Valid icon choices for Silicon Graphics publications are sgi_end_user, sgi_developer, and sgi_admin. Silicon Graphics Field Engineer manuals use the “binder” icon. Books developed outside of Silicon Graphics use the “generic” icon, which is the default.
Edit the BOOK_FILES variable:
Specify the source files that compose your book, in the order in which they appear in the book. Include the front matter, introduction, chapter, appendix, and glossary files in the order in which they appear in the book. Do not include any generated files (index, TOC, LOE, LOF, or LOT). Also leave out part and chapter tabs.
Table 3-1 lists the FrameMaker files that you should and should not include in the BOOK_FILES variable.
Table 3-1. FrameMaker Files to Include and Omit in Makefile
Include
Omit
Front matter file
About This Guide or Introduction file
Chapter files
Appendix files
Glossary file
Table of Contents
List of Figures
List of Tables
List of Examples
Index
Book file
Specify figure information:
Use the information in “Adding Image Files to the Makefile”, to complete this step. The Makefile file contains several variables that you can edit to specify how to process your figures files to display them in the online version of your book. When you assign values to figure variables, keep these facts in mind:
The make commands can only process the original figure files in the orig directory. This processing populates the print and online directories with correctly formatted figures.
The print directory is generated by the make _print command; it contains figure files that are processed specifically for the paper version of a book. All figure files that are imported into FrameMaker files must be imported from print—so if you create a new figure in the orig directory, you must use make _print to put a usable version of that figure in the print directory before you can import the figure (from the print directory) into your book.
The online directory is generated by the make _online command; it contains figure files that are processed specifically for the online version of a book.
Edit the INLINE_MEDIA variable, if needed.
Specify the name of inline media objects for movie, audio, or Inventor files if your book contains any.
You can run make with a variety of different arguments. The argument that you use determines the generated files that result from the build. The make command produces four different types of files: files that are actually part of the online book; image files for use in figures in the printed version of the book; intermediate files; and error files. Intermediate files are artifacts of the build process. make must produce these files in the course of creating an online book, and the files can be used to speed up subsequent book builds when only part of the book source has changed. The intermediate files are also used to create error files, which are reports of various types of source errors detected during the build process. Error files are not necessary steps in the build process and, though it is generally not recommended, it is possible to create an online book without generating any error files.
| Note: For instructions on how to find and fix errors reported in the various error files, see Chapter 4, “Finding and Fixing Online Book Errors.” |
Since the build process is a sequence of steps, make commands that take source files closer to a finished online book necessarily require that all earlier steps are completed. Likewise, generating an error file that relies on certain intermediate files will cause those intermediate files to be updated, if necessary, before an error report is generated.
Figure 3-1 shows where the various intermediate and error files are produced during the build process.
The make command generates a sequence of intermediate files in the process of creating an online document. Some are descendants of individual source files, while others combine information generated from all the source files for a book. All intermediate files appear in your document directory. They are generated automatically as part of the online build process. By using different make commands, you can produce a single file or set of files instead of all the generated files.
Error files list errors found in the various intermediate files. For instructions on how to find and fix errors, see Chapter 4, “Finding and Fixing Online Book Errors.” For information on error files, see “Error Files” in Chapter 4.
The make book command produces a subdirectory called books in your working directory that contains the built version of the book. See “Viewing a Built Book” for more information.
The make command takes many arguments, giving you flexibility to build different pieces of your book or selected error files. Since the build process is a sequence of steps, make commands that require more steps necessarily take longer. Figure 3-1 shows the basic sequence.
| Note: The dev.sw.make and dev.hdr.lib subsystems must be installed on your workstation to use the make command. The installed versions of those subsystems must be from the same base operating system as the version of IRIX that you are running. See “Checking the make Utility” for details. |
Table 3-2 lists the commands that operate on all files in a book. To perform any action listed in the table, enter the command exactly as shown.
Table 3-2. make Commands For the Entire Book
Command | Output |
|---|---|
make book | A books subdirectory containing a viewable book. |
make book.err | shortname .err file, containing all ERROR and WARNING messages for the book. |
make book.full | shortname .full file containing all error information, including link error reports and unresolved glossary terms; also a books subdirectory containing a viewable book. |
Table 3-3 lists the commands for individual FrameMaker files.
Table 3-3. make Commands for Single FrameMaker Files
Command | Output |
|---|---|
make filename.mif | FrameMaker MIF file from filename.doc |
make filename.sgm | SGML file from filename.mif |
make filename.err | error/warning report on filename.sgm |
Table 3-3 lists the commands that operate on figure files. Note the underscores; make can get confused when its argument is both a build rule and a directory name, so you should use make _print and make _online when building figures instead of just make print and make online.
Table 3-4. make Commands for Figures
Command | Output |
|---|---|
make _print | newly updated figure files in the print directory |
make _online | newly updated figure files in the online directory (note that composite figures are not updated by this command; to update composite figures, you must rebuild the .sgm file that contains them) |
Table 3-5 lists the commands that remove previously-built files. Note that none of these commands removes your source files (such as your FrameMaker document files and the files in the orig subdirectory). However, take care in using these commands if you've modified any generated files (such as image files in print or online) by hand.
Table 3-5. make Commands for Removing Files
Command | Effect |
|---|---|
make clean_book | Removes the books subdirectory (which contains the online book, if previously built) and all generated MIF files, plus the short_title .sgml file |
make clean_reports | Removes the error report files, including the .full file |
make clean | Removes all of the above, as well as any temporary files that have been left in place |
make clean_figures | Removes all files from the online subdirectory |
make clean_sgm | Removes generated SGML files |
make clobber | Removes all of the above |
make clean_print | Removes files in print subdirectory |
make clobber_all | Removes all of the above |
Which argument you should choose for the make command depends on the stage of development of your book. Use these recommendations as a general strategy for choosing a make argument:
Run make book.full on a book fairly early in the development process to generate error reports that you can use to begin debugging. Try to fix as many of these errors as possible before creating your first viewable book.
After fixing most of the errors from your initial make book.full, you can produce .err files for individual source files, as needed, as you continue development. You should also build the entire book periodically using make book or make book.full to monitor the progress of your online book.
Finally, before you incorporate the final book files into your software build, you must run make book.full and verify that your shortame.full file contains no errors you should fix. Then make sure the newly generated book is viewable with InSight, that all figures and tables work, and that the book looks the way you want it to look.
The make commands provide some information as they run; this information appears in the window from which you issued the command. If a make command encounters an unresolvable error, it reports an error message. If a make command terminates abnormally, see “If make Doesn't Work” for suggestions on finding and fixing the problem.
For instructions on how to find and fix errors that appear in the various error reports generated by make, see Chapter 4, “Finding and Fixing Online Book Errors.”
As a first step in the debugging process, use the make book.full command to build the SGML files with full error reports. (This command also generates a viewable copy of the book.) These reports give you an idea of how far along your book is, and how much work it may take to get it online. Try to eliminate as many of the easy, obvious errors as you can before you try and view your book. After you've fixed most of the errors, you can rebuild the viewable book using make book or make book.full.
To run make book.full, follow this procedure:
Close all your FrameMaker files. (The files must remain closed until the MIF files have been generated from them; at any point after that you may reopen them.)
Change directories to your local working directory.
Generate the SGML files and error reports.
% make book.full
This converts your FrameMaker files into SGML and creates a complete error report file that you can use to debug your book. (Chapter 4, “Finding and Fixing Online Book Errors,” explains how to do this debugging.) This complete error report is called short_title.full, where short_title is the short title of your book. The make book.full command also generates individual .err files, one for each chapter of the book; you can examine those files individually if you prefer, instead of the entire .full file.
make book.full may take anywhere from a minute to half an hour depending on the size and contents of the book.
There's no need to rebuild the entire book every time you make a change. This takes time and CPU cycles, and in many cases the amount of noticeable change is fairly minimal. Usually, a better strategy is to clean up and rebuild files individually, rebuilding the entire book only when you feel you have accumulated significant changes.
You can produce an error report (a .err file) for either individual files or the complete book. The .err files list errors pertaining to document structure as well as information about incorrect tag use. To produce a .err file for a single source file, type:
% make filename.err |
To produce a .err file for an entire book, replace filename in the above example with the book's short title.
See Chapter 4, “Finding and Fixing Online Book Errors,” for instructions on fixing errors.
If you want to view your book online and aren't interested in the error reports, follow these steps:
Close all your FrameMaker files. (The files must remain closed until the MIF files have been generated from them; at any point after that you may reopen them.)
Change directories to your local working directory.
Generate the book.
% make book
This command builds the files needed to display your book in the IRIS InSight viewer. “Viewing a Built Book” explains how to view the book in IRIS InSight.
The last thing you should do before checking in final book files is to run make book.full to verify that you have cleaned out all the errors in your book and to make sure that your online book builds. Then check the newly built book with the InSight viewer to make sure it looks the way you want it to.
To build your final book:
Close all your FrameMaker files. (The files must remain closed until the MIF files have been generated from them; at any point after that you may reopen them.)
Change directories to your local working directory.
Type the make command.
% make book.full
Check the error files to make sure there are no errors.
To view the online book, type:
% iiv -f -b .
If a make command doesn't work, use these suggestions to correct the problem:
Try to find and interpret the error message. Usually, the final cryptic “error code 2” (or similar error) will have been preceded by a more coherent message farther back in the build output. Look for phrases such as “cannot process”, “cannot find”, or “file not found.”
Make sure that you renamed Makefile_books to Makefile, and that the permissions are right: you need permission to read and write the Makefile. For information on setting up your Makefile, see “Copying Template Files to Your Working Directory” in Chapter 2.
Make sure all your FrameMaker files are closed. Look for stray .lck files in your working directory. These are “lock” files that should exist only as long as the corresponding Frame file is open. (Note that .mif files cannot be generated if the corresponding .doc files are in use.)
Make sure all the filenames in the Makefile are spelled correctly, and that there are no extra spaces after the shortname, or after any of the line continuation characters (\).
Examine the Makefile to verify that lists of files extending over multiple lines have a backslash (\) at the end of every line but the last.
Run df to make sure you have room in TMPDIR (type echo $TMPDIR to get the actual path). The make commands (particularly the figure-processing parts) can use quite a bit of space in the temporary directory specified by the TMPDIR environment variable; if there's no room, the commands won't work properly.
Verify that your files (particularly figures) end in the appropriate extensions (suffixes).
Remember to use make _print instead of make print (and make _online instead of make online).
Try using make -n book.full (or use -n with any of the make commands). This tells you exactly what make is trying to do. Look for extra spaces, misspelled file names, or anything else that doesn't look quite right.
Try copying a new Makefile into your working directory from /usr/share/Insight/templates/make/Makefile_books, and moving the entries from your current Makefile to the new one.
make book errors occur during execution of the make book or make book.full commands. This section contains a list of such error messages, their causes, and how to fix them.
Note that these errors are different from the errors that occur during translation from MIF to SGML. make book errors appear in a shell window while a make command is running, and usually prevent the command from completing until you fix the problem. Translation errors are listed in error files (such as the .err and .full files) and don't usually prevent a make command from completing. For information on translation errors, see “MIF-to-SGML Translation Errors” in Chapter 4.
FrameMaker reports error -1 "File already locked by login @ machine on date" *** Error code 1 smake: 1 error |
Here login is a login name (probably yours), machine is a machine name (probably yours), and date is a date (probably the current date). This means make can't open one (or more) of the FrameMaker files because it's locked. Close all your FrameMaker files (from within FrameMaker) and try again. If you don't have any open FrameMaker files, look through your book directory and remove any files that end in .lck. Try make book again. Another possible problem could be that someone else has logged in to your machine and moved or opened your files.
========Building master SGML File======== cat: cannot open .sgml.tmp *** Error code 2 ---Short_title --- cat: cannot open .sgml.tmp ***Error code 2 smake: 2 errors |
Here, Short_title is the short title of your book. This error message isn't quite so informative. If you get something like this, open your Makefile and look at the line that lists the shortname of the book. Look for extra spaces or punctuation. In the example shown above, there is an extra space following the short title of the book. Make sure the short title listed in the Makefile is the same as the name of your book file.
make: file '/usr/share/Insight/templates/make/commonbookdefs' line 3: Must ba a separator (: or ::) for rules (bu39) make:file '/usr/share/Insight/templates/make/commonbookdefs' line 3: Syntax error |
The dev.sw.make software subsystem is not properly installed. Re-install it. (Note that the pathname specified in the error message may vary depending on where the InSight Professional Publisher tools are located.)
"Makefile", line 16: Could not find /usr/share/Insight/templates/make/commonbookdefs
"Makefile", line 51: Could not find include file '${COMMONBOOKRULES}'
Fatal errors encountered -- cannot continue
|
This error indicates that the build tools are not properly installed or mounted.
mkbook warning: can't open file './booklist.txt'. |
The booklist.txt isn't writable. Make it writable using chmod. The booklist.txt file is generated by the build tools; don't edit it by hand.
--- online/figurename.ai --- ps2gif: ERROR - you must have impr_rip.sw.impr for this to work |
The specified figure is a PostScript® file, but the tools you need to process PostScript files are not installed. Either install them (they're in the impr_rip.sw.impr software subsystem) or use only non-PostScript figures.
29292://usr/frame/bin/sgi.irix.mips/fmbatch: rld: Fatal Error: cannot map soname 'libnsl.so' using any of the filenames /usr/lib/libnsl.so:/lib/libnsl.so:/lib/cmplrs/cc/libnsl.so:/usr/lib \ /cmpls /cc/libnsl.so:/usr/lib/libns --- font.mif --- *** Error code 1 ---localfigrules --- *** Error code 208 |
This indicates that the networking software for the license manager isn't installed. Install the eoe1.sw.svr4net software subsystem.
It is important to view a built book regularly during the development process to evaluate the online presentation of your material. It might be useful to review the information provided in “Guidelines for Organizing an Online Book”, and “Guidelines for Cross-Referencing in Online Books”, in completing an evaluation of an online book.
Use the following command to display a book with InSight during the book development process. This command assumes that you're in your working directory.
% iiv -f -b . |
In this command, the arguments to the iiv command (-f -b .) direct InSight to launch in the foreground (ignoring any other copy of InSight that might be running) and to look for a books directory in the current directory. You can also specify other pathnames (including relative pathnames) in an iiv command to open books in different directories. However, any directory that you specify must contain a local books directory that was created by a successful book build.
To view an uninstalled book on a different workstation, log in remotely to the other workstation, go to the appropriate directory, and launch InSight:
% rlogin guest@hostname % cd bookbuild_directory % iiv -f -b . |
In addition to viewing a book during the development process, you might also want to verify the installed image of your book. Viewing the installed image shows the final form of the online book as it will appear to the intended audience.
| Note: Before using this procedure, be sure that your workstation contains the disk space that the book requires. If you are viewing Help material, you will also need additional disk space for the application that your material documents. |
Use this procedure to view an installable book:
Determine the location of the installable book images.
An installable image of a book is part of the software subsystem that the book documents. Find out where to install the subsystem image from. The software engineers for your product should be able to provide this information.
Use swmgr to install the book on your workstation.
Use the standard software installation process to install your book.
Note: You might be required to install prerequisite subsystems before installing a book. To install Help material, for instance, you must also install the associated application. Start IRIS InSight to view the book.
% iiv
This command starts InSight and displays the newly installed book on a bookshelf.
Note: If you are viewing Help material, start the associated application and use the application's help feature to view your material.