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:
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. |
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.
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 /.
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.
A workarea contains the directories of all the books you are writing or have in production. Figure 2-1Figure 2-1 shows a typical SGI workarea.
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. |
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.
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. |
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
|
|
| FrameMaker |
|
|---|---|---|---|---|
commonbookrules | SGIDOC | Makefile_sgmldoc | .doc | English |
commondocrules | SGIDOCBK or SGIDOC | Makefile_sgidocbk | .doc or .fm | Same as above plus |
[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. | ||||
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
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. |
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.
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”.