Chapter 5. Building Online Books
Prev |  | Next

## Chapter 5. Building Online Books

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: The 5.0 tools are backward-compatible, so books undergoing revision can use the new `Makefile_sgidocbk`, which uses the SGIDOCBK DTD (commondocdefs) or the older `Makefile_sgmldoc`, which uses the SGIDOC DTD (commondocrules). The functionality of the two DTDs is essentially the same; the online appearance is different, however, especially for character tags. Before converting all your book building to the new SGIDOCBK DTD, you'll want to perform a sample bookbuild and view it in a web browser to ensure its online appearance more closely matches your company's style guide than the appearance created by SGIDOC.

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

- “Editing the Makefile”

- “Files and Directories Generated by make”

- “Arguments to the make Command”

- “Using make Commands”

- “If make Doesn't Work”

- “make book Error Messages”

- “Viewing a Built Book”

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

## Editing the Makefile

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

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

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

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

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

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

## Files and Directories Generated by `make`

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.

Figure 5-1. Files Produced During the make Process

### Intermediate Files

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.

`.mif` files |  | These are ASCII versions of the FrameMaker `.doc` or .`fm` files, in Frame's Maker Interchange Format. The MIF to SGML translation software reads and converts these files to SGML.
.`sgm` files |  | These are individual SGML files, produced from the `.mif` files by the MIF to SGML translation software. One .`sgm` file is generated for each FrameMaker file listed in the `Makefile`.
booklist`.txt` file |  | This file contains the bookshelf, book icon, language, title, short title, part number, and hidden variable information from the `Makefile`.
short_title`.idx` file |  | This file contains index information for the SGML version of the book.
short_title`.sgml` file |  | This file contains the concatenated SGML for all the files listed in the `Makefile`, plus all the information from the `short_title.idx` file.
short_title`.full` file |  | This file contains the concatenated .`err` files and a report on any corss-reference errors.

### Error 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 `build` Directory

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.

## Arguments to the `make` Command

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

## Using `make` Commands

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

### Initial `make`: `make book.full`

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:

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

2. Change directories to your local working directory.

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

### Debugging Individual Files: filename`.err`

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.

### Making a Viewable Book: `make book`

If you want to view your book online and aren't interested in the error reports, follow these steps:

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

2. Change directories to your local working directory.

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

### Verifying an Error-Free Book: `make book.full`

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:

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

2. Change directories to your local working directory.

3. Type the `make` command.

       % make book.full

4. Check the short_title`.full` file to make sure there are no errors or unresolved references or glossary terms.

5. 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 `make` Doesn't Work

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

- Remember to use `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 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` Error Messages

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

### Problem: File Already Locked

    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.

### Problem: Can't Open File

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

### Problem: `commonbookdefs` File Errors

    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.

### Problem: Can't Open `booklist.txt` File

    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.

### Problem: Must Have impr_rip.sw.impr

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

### Problem: Cannot Map `libnsl.so` Library

    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.

## Viewing a Built Book

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.

### Viewing an Uninstalled 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

### Viewing an Installed Book

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:

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

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

#### Viewing in Web Browser

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.

#### Viewing with InfoSearch

Use this procedure to view an installed book with InfoSearch:

1. Launch InfoSearch.

   To launch the InfoSearch browser, type the command

       % infosearch

2. Click Online Books to display the bookshelves.

3. Click the bookshelf on which your book is installed.

4. Click the book's folder icon or title to open the book.

Prev | Table of Contents | Next
Chapter 4. Working With Figures |  | Chapter 6. Finding and Fixing Online Build Errors