The book building process creates HTML files from DocBook XML files and from FrameMaker source files via intermediate SGML files. It also generates the additional files that are required to create the HTML for use with any web browser, InfoSearch and the SGIHelp viewer. The build process also generates error reports to help you debug source files and create error-free online documents. For more information on the SGI Book Building Environment and the benefits of the book building tools, see “SGI Book Building Architecture” in Chapter 1. For details on using DocBook XML files directly, see Appendix B, “Building DocBook XML Books”.
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 a web browser, and/or test the resulting online help.
 | Note: Books built with tools versions 4.2 and lower are no longer supported as an online delivery format. The 5.0 and future tools will derive platform-independent HTML online books from all previously supported source documents and applications. |
| Note: If you need to build books for the SJIS Japanese locale or any Chinese or Korean languages and locales, you must use the SGIDOCBK DTD. |
This chapter explains how to build a book, generate error reports, and view the built book in a web browser. The chapter includes these sections:
-
Note: The build process is more efficient if you compose and import figures, and then use the File > Generate/Update command in the FrameMaker book file, before beginning the build.
If you don't have a Makefile in your book's working directory, follow the instructions in “Makefile” in Chapter 2.
The Makefile specifies the FrameMaker files that compose the book and gives information about environment variables. 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 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 the 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 your book is the part number identification for the book. For example:
007-2863-001, 9/99
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 library, in this form:
/usr/share/Insight/library/SGI_bookshelves/<companyname>_shelf
(You can use a standard abbreviation of your company's name as your companyname, but all books from a given company must use the same abbreviation.) For instance, a company named YoyoDyne Systems would specify
/usr/share/Insight/library/SGI_bookshelves/YoyoDyne_shelf
for the BOOKSHELF variable; the books would then appear 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.
SGI 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 SGI bookshelves are located in the /usr/share/Insight/library/SGI_bookshelves directory.
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 chapter tabs.
Table 5-1 lists the FrameMaker files that you should and should not include in the BOOK_FILES variable.
Table 5-1. FrameMaker Files to Include and Omit in Makefile
Include
Omit
Front matter file
About This Guide or Introduction file
Part tabs
Chapter files
Appendix files
Glossary file
Table of Contents
List of Figures
List of Tables
List of Examples
Index
Book file
Chapter tabs
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
automatically converted image files
intermediate files
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 6, “Finding and Fixing Online Build 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.
A complete bookbuild can take anywhere from 15 seconds to 30 minutes or more, depending on the size of the book, the speed of your workstation, and the amount of activity on your workstation. Subsequent builds take less time, depending on the number of source files that you edited since your previous build.
Figure 5-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 6, “Finding and Fixing Online Build Errors”. For information on error files, see “Error Files” in Chapter 6.
| .err files | This file contains errors and warnings generated from the corresponding .sgm or .sgml file. You should fix all messages labeled ERROR, but you may ignore the messages labeled WARNING. | |
| short_title.full file | The make book.full command generates this file. It contains the concatenated .err files, the portion of the Makefile containing the variables (title, part number, bookshelf, book icon, etc.), a report on unresolved cross-references, a list of multiple link targets, and a list of unresolved glossary links. |
The make book command produces a subdirectory called build 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 5-1 shows the basic sequence.
| Note: See “Summary of Software/Configuration Requirements” in Chapter 2 for a list of subsystems that must be installed on your workstation prior to using the make command. |
Table 5-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 5-2. make Commands For the Entire Book
Command | Output |
|---|---|
make book | A build subdirectory containing a viewable book. |
make book.err | short_title .err file, containing all ERROR and WARNING messages for the book. |
make book.full | short_title .full file containing all error information, including link error reports; also a build subdirectory containing a viewable book. |
Table 5-3 lists the commands for individual FrameMaker files.
Table 5-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 5-4 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 _online when building figures instead of just make online.
Table 5-4. make _online Command for Figures
Command | Output |
|---|---|
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 5-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 5-5. make Commands for Removing Files
Command | Result |
|---|---|
make clean | Removes the online book and any intermediate build files |
make clobber | Removes the above and all automatically generated image files |
The make command argument that you choose 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 short_title.full file contains no errors. Then make sure the newly generated book is viewable in a web browser and InfoSearch, 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 6, “Finding and Fixing Online Build Errors”.
As a first step in the debugging process, use the make book.full command to build the HTML 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; you may reopen them at any point after MIF files are generated.)
Change directories to your local working directory.
Generate the SGML files and error reports.
% make book.full
This converts your FrameMaker files into HTML and creates a complete error report file that you can use to debug your book. (“Checking the .full File” in Chapter 6 and “Finding and Fixing Errors” in Chapter 6 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 usually takes from 30 seconds to 30 minutes 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. 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 |
If you want to see a concantenated version of all your .err files, use this command:
% more *.err |
To save the output in a file, add > filename to the end of your command.
See “Finding and Fixing Errors” in Chapter 6 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; you may reopen them at any point after MIF files are generated.)
Change directories to your local working directory.
Generate the book.
% make book
This command builds the files needed to display your book in a web browser. “Viewing a Built Book” explains how to view the HTML book.
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 in a web browser 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; you may reopen them at any point after MIF files are generated.)
Change directories to your local working directory.
Type the make command.
% make book.full
Check the short_title.full file to make sure there are no errors or unresolved references or glossary terms.
To view the online book, point your web browser to the build directory and open the index.html file, or enter a command similar to
% netscape ./build/sgi_html/index.html
If a web browser is already running, go to the URL mentioned at the end of the make output when generating the online book. The output looks like:
For Review: file://<path_to_book>/build/sgi_html/index.html
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_sgidoc or Makefile_sgidocbk 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 or .fm files are in use.)
Make sure all the filenames in the Makefile are spelled correctly, and that there are no extra spaces after the short title, 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 except the last.
Run df to make sure you have room in TMPDIR (type echo $TMPDIR to get the actual path; when TMPDIR is not defined, it defaults to /usr/tmp). 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. See the tmpnam(3S) man page for further information.
Verify that your filenames (particularly figures) end in the appropriate extensions (suffixes).
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 filenames, or anything else that doesn't look quite right.
Try copying a new Makefile_sgidocbk or Makefile_sgmldoc into your working directory from /usr/share/Insight/templates/make, 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 6.
FrameMaker reports error -1 "File already locked by login @ machine on date" *** Error code 1 smake: 1 error |
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, though. If you get something like this, open your Makefile and look at the line that lists the short title 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 be 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.
"Makefile", line 16: Could not find /usr/share/Insight/templates/make/commonbookdefs
"Makefile", line 51: Could not find include file '${COMMONBOOKDEFS}'
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 Encapsulated 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 eoe.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” in Chapter 1, and “Guidelines for Cross-Referencing in Online Books” in Chapter 1, in completing an evaluation of an online book.
To view the online book, point your web browser to the build directory and open the index.html file, or enter a command similar to
% netscape ./build/sgi_html/index.html |
This command assumes that you're in your working directory.
Or go to the URL mentioned at the end of the make output when generating the online book. This output looks like:
For Review: file://<path_to_book>/build/sgi_html/index.html |
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. |
Take the necessary steps required to properly install the 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 from where to install the subsystem image. The software engineers for your product should be able to provide this information.
Use swmgr to install the book on your workstation.
If you need help using swmgr, see IRIX Admin: Software Installation and Licensing.
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.
To browse the available bookshelves and books on the local system in your web browser or in the IRIX Interactive Desktop File Manager, open the following file:
/usr/share/Insight/library/SGI_bookshelves/index.html |
Localized books can be browsed by opening the following file:
/usr/share/Insight/library/<language>_bookshelves/index.html |
Click on the bookshelf on which your book is installed; then click on the book title to open and view that book.
Use this procedure to view an installed book with InfoSearch:
Launch InfoSearch.
To launch the InfoSearch browser, type the command
% infosearch
Click Online Books to display the bookshelves.
Click the bookshelf on which your book is installed.
Click the book's folder icon or title to open the book.