The book development process requires access to the book-building 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, view, and archive online books. The following items are required:
| IRIX 5.3 | The base operating system. The InSight Professional Publisher tools will not run under IRIX 5.2 or earlier, or under IRIX 6.1. | |
| FrameMaker | You must create your documents using FrameMaker 3.1.X or later in order to use the tools. | |
| book-build tools |
| |
| smake utility | A parallel version of make, a program that uses a specified rule set to invoke the appropriate translation and figure-processing tools under various book-building 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 dev.hdr.lib subsystem. | |
| InSight software |
| |
| other tools | You need the following additional software subsystems installed in order to make full use of the book-building tools: eoe2.sw.imgtools (basic figure processing tools), and the PostScript-processing tools in impr_rip.sw.impr and impr_fonts.sw.adobe22. | |
| revision control software |
|
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 IRIS InSight or SGI Help. In addition, your workstation must be running IRIS InSight software so that you can check the online book for problems during development.
The dev.hdr.lib and dev.sw.make subsystems must be installed on your workstation before you can use the book-building tools. The installed version of make must be from the same base operating system release as the version of IRIX that you are running; that is, if you're running IRIX 5.3, you must use the IRIX 5.3 version of make. To compare your version numbers, enter this command:
% showprods -D 3 dev.hdr dev.sw.make eoe1
If the IRIX version numbers listed for eoe1 and dev are different, install the correct version of make. See your system administrator if you have questions about software installation.
The IRIS InSight viewer occupies about 2 MB of disk space without books. It's installed by default, but if it isn't already installed on your workstation you can install it using Software Manager, the standard Silicon Graphics graphical installation utility.
 | Note: If you need help running swmgr, see your system administrator or the Personal System Administration Guide. |
Here's how to install InSight:
Become superuser:
% su
Execute Software Manager:
% swmgr
Specify the location of the InSight software distribution in the Available Software text region, then click the Lookup button.
Click the Customize Installation button. After a brief processing period, a list of InSight software appears.
Select Short Product Names from the Software menu, if it isn't already selected. (If it is, leave it selected.)
Click the folded arrow icon to display a list of subsystems. The folded arrow icon appears between the Install checkbooks and the product name.
Select these subsystems by clicking the Install checkbooks:
insight.books.ViewerHelp
insight.books.help
insight.sw.client
insight.sw.data
insight.sw.public
insight.sw.sgihelp
Click the Start button to install your selections.
Click the OK button when the successful installation message comes up.
Exit Software Manager, using the Quit command in the File menu.
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-1). 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-1 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-1 describes the files and directories shown in Figure 2-1. The asterisk (*) indicates files and directories used only for online books.
Table 2-1. Files and Directories in a Book Directory
File | Description |
|---|---|
print directory | Contains the images used in figures for the printed version of the book. To generate and populate the print directory, use the command make _print. All figures in your FrameMaker files should be imported by reference from this directory. |
orig directory | Contains the original images for all figures in the book. Files are either complete figures or figure components that must be processed before storing in the print or online directories. |
*online directory | Contains the figures for the online version of the book, generated during the build process. |
*help directory | Contains the helpmap file for linking SGI Help 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 suffix) | Includes all FrameMaker files for the book: front matter, introduction, chapters, appendices, glossary, and all generated files (TOC, LOF, LOT, and IX). |
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 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, as well as to generate the various forms of the figure files. |
*README file | Contains the writer's name, the date, and the full title, part number, and short name 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 editor for purposes such as storing print vendor specifications. |
Observe these conventions for naming FrameMaker files:
All FrameMaker document files (front matter, introduction, chapters, appendices, glossary, and all generated files) must end with the suffix .doc.
The front matter file should include the string “front” in its name (PSAGfront.doc, for example)
The file containing the introduction to the book—called “About This Guide” in Silicon Graphics 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 enormously helpful if you ever subsequently add or remove chapters in the middle. 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 should end with the suffix .doc. For example, if your book file is called MyBook.book, the generated files are MyBookTOC.doc, MyBookLOF.doc, MyBookLOT.doc, and MyBookIX.doc. FrameMaker chooses these filenames by default when you generate the files within a book.
For consistency, it's a good idea to follow standard conventions in naming a book. Silicon Graphics has complex guidelines on choosing a title for any kind of document, including many unusual cases. Luckily, 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):
Installation
Language
Programmer's
System Administrator's
User's
The document_type indicates what kind of book it is:
Overview
Tutorial
Guide
Reference Manual
By mixing and matching from the two lists, you should be able to choose a title relatively easily. Here are some examples of titles of Silicon Graphics book titles:
ImageVision Library® Programmer's Guide
IRIS® Volume Manager System Administrator's Tutorial
OpenGL® Porting Guide
WebMagic™ User's Guide
A short title is an abbreviated way to refer to a book. 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 InSight books; to refer to other books when making cross-book links; and to identify books which contain an item a user has searched for in the main InSight 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 that for a programmer's guide should end with “_PG.” Also, the short title of a book is used to identify its subdirectory in the InSight book directories, so you can't 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.
| 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 InSight Professional Publisher to create new FrameMaker files for your book. These template files are located in the directory /usr/share/Insight/templates/frame/IPTemplate. That directory contains a subdirectory called samples which contains a sample book that uses the template. If you're unfamiliar with this template, start by launching FrameMaker and opening the file IPChap.doc from the samples directory; that file contains information on all tags and formatting procedures for FrameMaker documents that will be converted to InSight.
In addition to FrameMaker template files, the book-building 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. Copy the file /usr/share/Insight/templates/make/Makefile_books 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_books ./Makefile % chmod 644 Makefile |
Once you've set up your Makefile, you have to edit it to make it work with your particular book. Directions for editing the Makefile are given in Chapter 3, “Building Online Books.”