Chapter 2. Preparing Your Workstation
Prev |  | Next

## Chapter 2. Preparing Your Workstation

The book development process requires access to the bookbuilding and viewing tools.

This chapter explains how to prepare your workstation for book development. The chapter contains these sections:

- “Summary of Software/Configuration Requirements”

- “Setting Up Tools and Environment”

- “Setting Up a Workarea”

- “Organizing a Local Working Directory”

## Summary of Software/Configuration Requirements

When you complete the procedures in the remaining sections of this chapter, your workstation will be configured with the software required to build and view online books. The following items are required:

IRIX 6.5.X |  | The base operating system. The SGI Book Building Tools will run on SGI systems running IRIX 6.5 or higher.
FrameMaker |  | You must create your documents using FrameMaker 3.1.X or later in order to use the tools or generate SGML with an SGML editor.
bookbuild tools |  | The translation and figure-processing tools that convert FrameMaker files and associated images to HTML format. (This conversion process is called a bookbuild.) These tools are part of the SGI Book Publishing distribution, in the `insight_dev` product.
`smake` utility |  | A parallel version of `make` that includes additional features, a program that uses a specified rule set to invoke the appropriate translation and figure-processing tools under various bookbuilding conditions. `smake` allows multiple tool invocations at once, which lets your book build faster. `smake` is automatically invoked when you use any of the `make` commands documented in this guide, so you can pretend you're just using `make`. The `make` and `smake` utilities are probably already installed on your workstation; they're part of the software subsystem`dev.sw.make`. To use these utilities, you also need the `irix_dev.sw.headers` subsystem (for IRIX 6.5).
Web Browser |  | The bookbuilding process creates HTML files that can be viewed with any web browser, such as Netscape. (Netscape should be installed on your workstation as it is part of the standard IRIX distribution. If it is not installed, you can find it on the IRIX 6.5 Applications CD.) Additionally the insight_base, insight, infosearch and sgsearch products are used to view the installed book through the InfoSearch web application.
other tools |  | You need the following additional software subsystems installed in order to make full use of the bookbuilding tools: `eoe.sw.imagetools` (basic figure processing tools), and the PostScript-processing and printing tools in `impr_rip.sw.impr` and `x_eoe.sw.Xfonts`.

## Setting Up Tools and Environment

To make a book viewable online, your workstation must have access to the tools that process FrameMaker files into files that can be viewed with a web browser, InfoSearch or SGIHelp.

### Installing Subsystems

The `make` and `impr_rip` subsystems must be installed on your local system (`impr_rip` will require a separate license). The `insight_dev` subsystem can be installed on your local system or symbolically linked to your workarea. All of the tools described in this section should be installed in the standard default location of /.

#### Subsystems for IRIX 6.5 Workstations

Table 2-1 lists the subsystems to install on a local system, or on a local system and a system symbolically linked to your workarea, if the system(s) are running IRIX 6.5, along
with the distribution locations for the subsystems.

Table 2-1. Products and Subsystems to Install on IRIX 6.5.17 or Newer Systems

Base CD Name | Overlay CD Name | Product or Subsystem
--- | --- | ---
development-libraries | 1 or 2 | dev.sw.make
development-libraries | 1 or 2 | irix_dev.sw.headers
foundation | 1 or 2 | eoe.sw.imagetools
foundation | 1 or 2 | x_eoe.sw.Xfonts
applications | applications | impr_rip.sw.impr [a]
foundation | overlay 4 | insight_base
applications | overlay 4 | insight
applications | overlay 4 | infosearch
applications | overlay 4 | sgsearch
applications | applications | insight_dev
[a] Requires additional license

To check if any of the subsystems are already installed on the local system, enter

    % versions dev irix_dev eoe impr_rip x_eoe insight insight_base insight_dev

Compare the output to the subsystems listed in Table 2-1. If any of the subsystems are not listed, they will need to be installed. If you need help installing the missing subsystems, see your system administrator or the book, IRIX Admin: Software Installation and Licensing.

## Setting Up a Workarea

A workarea contains the directories of all the books you are writing or have in production. Figure 2-1 Figure 2-1 shows a typical SGI workarea.

Figure 2-1. A Typical SGI Workarea

## Organizing a Local Working Directory

A working directory contains working copies of the files that compose a book, as well as the subdirectories and support files that are needed to produce hard copy and online versions of the book (see Table 2-2). Such a directory is often called a “local working directory” in environments which use a document archiving system; in such an environment, you copy the archived document into a working directory on your local system and make any changes to that local copy.

You may put extraneous files in a working directory and create any extra subdirectories that you wish; however, all files that are actually part of the book must be named according to prescribed naming conventions. These conventions ensure successful book builds and smooth handoffs to other people who need to use your files.

| Note: Refer to the information in this section throughout the development process to be sure that your working directory contains the required set of files and subdirectories in the correct location.

### Standard Files in a Local Working Directory

Figure 2-2 illustrates the source files that compose the hard and soft copy versions of a technical manual. These files should be archived periodically during the book development cycle. The asterisk (*) indicates files and directories that are unnecessary for books that ship only in hard-copy format.

Figure 2-2. Files and Directories in a Working Directory

Table 2-2 describes the files and directories shown in Figure 2-2. The asterisk (*) indicates files and directories used only for online books.

Table 2-2. Files and Directories in a Book Directory

File | Description
--- | ---
`print` directory | Contains the images used in figures for the printed version of the book. This directory should only contain standard graphics types (EPS, AI, RGB, BW, PS, PDF and GIF). All figures in your FrameMaker files should be imported by reference from this directory.
*`online` directory | Contains the figures for the online version of the book, generated during the build process.
*`help` directory | Contains the helpmap file(s) for linking SGIHelp to the book. See Chapter 7, “Creating Online Help ”, for details.
`tabs` directory | Contains chapter tabs for the book. Part tabs, if any, must be in the same directory as the document files.
FrameMaker document files (with .`doc` or .`fm` suffix) | Includes all FrameMaker files for the book: front matter, introduction, chapters, appendices, glossary, and all generated files (TOC, LOF, LOT, and IX). Note that generated files from FrameMaker 5.X have a .`fm` suffix.
filename.`book` | The FrameMaker file that contains information about all component files for a book.
*SGML files (with .`sgm` suffix) | The SGML translations of the .`doc` or .`fm` files; `.sgm` files are the components of the online version of your book. Building a book (with the `make` command) generates these files.
*`Makefile` file | Specifies information about how to build your book. The `Makefile` is used to generate the SGML files for the online version of the book.
*`README` file | Contains the writer's name, the date, and the full title, part number, and short title of the book. In addition, gives any other information about the book that might be helpful to future writers, production specialists, or build engineers.
*`prod` directory | Contains information that might be used by the writer or production specialist for purposes such as storing print vendor specifications, PostScript files and PDF files.

### Observing Naming Conventions

Observe these conventions for naming FrameMaker files:

- All composed FrameMaker document files (front matter, introduction, chapters, appendices, and glossary) must end with the suffix .`doc` or `.fm`. Generated files (TOC, LOF, LOT, LOE, and IX) end with the suffix .`fm`. See Table 2-3 for guidelines for when to use which suffixes.

- The front matter file should include the string “front” in the file name (`PSAGfront.doc`, for example).

- The file containing the introduction to the book—called “About This Guide” in SGI documents—should include the strings “about” or “intro” in its name (`00.about.doc`, for example)

- Chapter filenames should include the chapter number in their names. (`01.getstart.doc`, for example, might be a good name for the first chapter of a book.) Starting the filename with the chapter number means that the filenames appear in the correct order in file-open dialog boxes, when listed by `ls`, and so forth. Including a mnemonic word in the file's title can be very helpful if you subsequently add or remove chapters in the middle of a book. Thus, filenames like `09.debug.doc` are preferable to names like `ch9.doc`.

- Appendix filenames should include the appendix letter in their names (`C.variables.doc`, for example, for the third appendix in a book). Again it's useful to start with the sequence letter and to include a key word, rather than using filenames like `AppA.doc`.

- To name your book file, first choose a title for your book, then abbreviate it to form a short title. See “Choosing a Book's Title” and “Choosing a Book's Short Title” for help with this choice. Name the book file short_title`.book`, where short_title is the short title you've chosen for the book.

- Your FrameMaker-generated TOC, LOF, LOT, and Index files will end with the suffix .fm. For example, if your book file is called MyBook.book, the generated files are MyBookTOC.fm, `MyBookLOF.fm`, MyBookLOT.fm, and MyBookIX.fm. FrameMaker chooses these filenames by default when you generate the files within a book.

Table 2-3. Guidelines for Determining Makefile and File Suffixes

Rules to Use | DTD[a] | Makefile | FrameMaker File Suffix | Languages and Encodings Supported
--- | --- | --- | --- | ---
commonbookrules commonbookdef | SGIDOC | Makefile_sgmldoc | .`doc` | English German French Japanese (EUC)
commondocrules commondocdef | SGIDOCBK or SGIDOC | Makefile_sgidocbk | .`doc` or .`fm` | Same as above plus Japanese (EUC and SJIS) Korean Traditional Chinese (BIG5 and UCNS) Simplified Chinese (GBK and UGB)
[a] The functionality of the two DTDs is essentially the same; the online appearance is different, especially for character tags. Before convert ing all your bookbuilding to the new SGIDOCBK DTD, you'll want to perform a sample bookbuild and view it in your web browser to ensure its online appearance more closely matches your company's style guide than the appearance created by SGIDOC.

#### Choosing a Book's Title

For consistency, follow standard conventions in naming a book. SGI has guidelines on choosing a title for any kind of document, including many unusual cases. Fortunately, most titles follow a fairly simple structure:

product_name audience_type document_type

The audience_type indicates who the book is aimed at, or the kind of task that the book describes. Choices include (among other possibilities):

- Owner's

- User's

- Language

- Programmer's

- Developer's

- System Administrator's

- Installation

The document_type indicates what kind of book it is:

- Overview

- Tutorial

- Guide

- Reference Manual

- Instructions

By mixing and matching from the two lists, you should be able to easily choose a title. Here are some examples of SGI book titles:

- Octane Workstation Owner's Guide

- MineSet 3.0 Enterprise Edition User's Guide

- C Language Reference Manual

- ImageVision Library Programmer's Guide

- IRIS Volume Manager System Administrator's Tutorial

- Motif Porting Guide

- WebMagic User's Guide

#### Choosing a Book's Short Title

A short title is an abbreviated way to refer to a book. It is utilized by a variety of the book building tools and is necessary in deriving an online book. The short title also serves as the name of the directory location where the book is stored upon installation. A book's short title should be a condensed version of its full title, no more than twelve characters long. Short titles are used in a variety of ways: as the titles of icons representing iconified online books; and to identify books containing an item for which a user has searched in the main library window.

Short titles follow conventions similar to those used in the full titles of books; for instance, the short title of a user's guide should end with “_UG”, while the short title for a programmer's guide should end with “_PG.” Also, the short title of a book is used to identify its subdirectory in the online book directories, so you can not use spaces or other characters that are illegal in a filename (such as * or /).

Be sure to list your book's short title on the TITLE line of your `Makefile`, and in your `README` file. See “Editing the Makefile” in Chapter 5 for details.

| Note: Do not use the short title of your book as the basis for the name of any file other than the book file. For example, short_title`.doc` (where short_title is the short title of your book) is not a valid name for a chapter file.

### Copying Template Files to Your Working Directory

#### SGI Book Building Templates

Use the template files provided with the SGI Book Building Environment to create new FrameMaker files for your book. These template files are located in the directory `/usr/share/Insight/templates/frame/IPTemplate`. This directory also contains a subdirectory called `samples` which contains a sample book that uses the templates. If you're unfamiliar with this template, start by launching FrameMaker and open the `IP.book`. Each file is a self-documenting instruction set that includes information on all tags and formatting procedures for FrameMaker documents that will be converted to online formats.

#### Makefile

In addition to FrameMaker template files, the bookbuilding tools also require a `Makefile`. This file specifies the characteristics necessary to prepare a document for online viewing—particularly information about what files are part of the document to be built.

If you are building your book with the SGIDOCBK DTD, copy the file `/usr/share/Insight/templates/make/Makefile_sgidocbk` into your working directory, rename it to `Makefile`, and then set the permissions so you can both read and write it:

    % cd working_directory
    % cp /usr/share/Insight/templates/make/Makefile_sgidocbk ./Makefile
    % chmod 644 Makefile

If you are building your book using the older SGIDOC DTD, copy the file `/usr/share/Insight/templates/make/Makefile_sgmldoc` into your working directory, rename it to `Makefile`, and then set the permissions so you can both read and write it:

    % cd working_directory
    % cp /usr/share/Insight/templates/make/Makefile_sgmldoc ./Makefile
    % chmod 644 Makefile

| Note: The functionality of the two DTDs is essentially the same; the online appearance is different, though, 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 your web browser to ensure its online appearance more closely matches your company's style guide than the appearance created by SGIDOC.

Once you've set up your `Makefile`, you will edit it to make it work with your particular book. Directions for editing the `Makefile` are given in Chapter 5, “Building Online Books”.

Prev | Table of Contents | Next
Chapter 1. Getting Started |  | Chapter 3. Using FrameMaker Files and Template Features