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, view, and archive (internal to SGI) online books. The following items are required:
| IRIX 6.2 or 6.5 | The base operating system. The IRIS InSight Professional Publisher tools will not run under IRIX 5.2 or earlier, or under IRIX 6.1 Although there should be no problem installing the IRIX 6.2 subsystems on IRIX 6.3 or 6.4 systems, no testing has been done by SGI to ensure the tools will work. | |
| 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 an InSight-viewable format. (This conversion process is called a bookbuild.) These tools are part of the IRIS InSight Professional Publisher distribution, in the insight_dev.sw.tools subsystem. | |
| 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) or eoe.hdr.lib subsystem (for IRIX 6.2). | |
| IRIS InSight software | The IRIS InSight viewer, support files for IRIS InSight, and help files for InSight and SGI Help. This software should already be installed on your workstation; it's part of the standard IRIX distribution. The IRIS InSight viewer occupies about 2 MB of disk space without books. | |
| 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. | |
| revision control software | SGI publications groups check files into and out of a document archive using the tools in the eoe.sw.rcs subsystem. ptools are based on RCS (the Revision Control System). If your company uses such a system, you'll need the appropriate revision-control software. This book assumes that you have some sort of system for checking files into and out of an archive; if you don't use such a system, just ignore any references to checking in or checking out files. |
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 make and impr_rip subsystems must be installed on your local system. The insight_dev subsystem can be installed on your local system or symbolically linked to your workarea. The prod_toolroot subsystem, which contains productivity tools for use by SGI production editors and is an SGI-internal product, 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.2, along with the distribution locations for the subsystems.
Table 2-1. Subsystems to Install on IRIX 6.2 Systems
IRIX 6.2 | SGI Distribution Location | CD Name and Distribution Location |
|---|---|---|
dev.sw.make | dist.engr:/released/6.2/products/ | irix-6.2-development-libraries/dev |
eoe.hdr.lib | dist.engr:/released/6.2/products/ | irix-6.2-part-1-of-2/eoe |
eoe.sw.imagetools | dist.engr:/released/6.2/products/ | irix-6.2-part-1-of-2/eoe |
eoe.sw.rcs [a] | dist.engr:/released/6.2/products/ | irix-6.2-part-1-of-2/eoe |
impr_rip.sw.impr | dist.engr:/released/6.2/products/ | irix-6.2-applications-11-98/ |
x_eoe.sw.Xfonts | dist.engr:/released/6.2/products/ | irix-6.2-part-1-of-2/x_eoe |
insight_base.sw.eoe | dist.engr:/released/6.2/products/ | irix-6.2-applications-11-98/ |
insight.sw.xhelp_dev | dist.engr:/released/6.2/products/ | irix-6.2-applications-11-98/ |
insight.sw.client | dist.engr:/released/6.2/products/ | irix-6.2-applications-11-98/insight |
insight.sw.data | dist.engr:/released/6.2/products/ | irix-6.2-applications-11-98/insight |
insight.sw.sgihelp | dist.engr:/released/6.2/products/ | irix-6.2-applications-11-98/insight |
insight_dev.sw.tools | dist.engr:/released/6.2/products/ | irix-6.2-applications-11-98/../dev/ |
[a] For writers using Revision Control System | ||
Table 2-2 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-2. Subsystems to Install on IRIX 6.5 Systems
RIIX 6.5 Subsystem | SGI Distribution Location | CD Name and Distribution Location |
|---|---|---|
dev.sw.make | dist.engr:/released/6.5/products/ | irix-6.5-development-libraries/dev |
irix_dev.sw.headers | dist.engr:/released/6.5/products/ | irix-6.5-development-libraries/ |
eoe.sw.imagetools | ist.engr:/released/6.5/products/ | irix-6.5-foundation-1/eoe |
eoe.sw.rcs [a] | dist.engr:/released/6.5/products/ | irix-6.5-foundation-1/eoe |
x_eoe.sw.Xfonts | dist.engr:/released/6.5/products/ | irix-6.5-foundation-1/x_eoe |
impr_rip.sw.impr | dist.engr:/released/6.5/products/ | irix-6.5-applications-02-99/ |
insight_base.sw.eoe | dist.engr:/released/6.5/products/ | irix-6.5-foundation-1/insight_base |
insight.sw.client | dist.engr:/released/6.5/products/ | irix-6.5-applications-02-99/insight |
insight.sw.data | dist.engr:/released/6.5/products/ | irix-6.5-applications-02-99/insight |
insight.sw.sgihelp | dist.engr:/released/6.5/products/ | irix-6.5-applications-02-99/insight |
insight.sw.xhelp_dev | dist.engr:/released/6.5/products/ | irix-6.5-applications-02-99/insight |
insight_dev.sw.tools | dist.engr:/released/6.5/products/ | irix-6.5-applications-02-99/../dev/ |
[a] For writers using Revision Control System | ||
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 or Table 2-2. If any of the subsystems are not listed, they need to be installed. Follow the instructions in “Installing Subsystems Using Inst ” or “Installing Subsystems Using Software Manager” to install the missing subsystems.
To install any subsystem using inst, the command line installation tool, perform the following steps:
 | Note: If you need help using inst, see your system administrator or the book, IRIX Admin: Software Installation and Licensing. |
Become superuser (root).
% su
To install the subsystem, enter
# inst -f /<path>/<to>/<installable>/<image> Inst> keep * Inst> list Inst> i <subsystem_name> Inst> list i
Confirm that the subsystem(s) you want to install are marked for installation. Then enter
Inst> go
When the installation is complete, quit Inst.
Inst> q
To install any subsystem using the Software Manager, the standard SGI graphical installation utility, perform the following steps:
| Note: If you need help running swmgr, see your system administrator or the Personal System Administration Guide. |
Become superuser (root).
% su
To execute Software Manager, enter
% swmgr
or
Choose System > Software Manager from the Toolchest
Specify the location of the software distribution in the Available Software text field, then click the Lookup button.
Click the Customize Installation button. After a brief processing period, a list of software appears.
Select Software > Short Product Names, 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 checkbox and the product name.
Select the subsystems you need to install by clicking the Install checkbox. For example, if you want to install the IRIS InSight software subsystems, check:
insight.sw.client
insight.sw.data
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 by selecting File > Quit.
A workarea contains the directories of all the books you are writing or have in production. Figure 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-3). 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-3 describes the files and directories shown in Figure 2-2. The asterisk (*) indicates files and directories used only for online books.
Table 2-3. 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(s) for linking SGI Help to the book. See Chapter 8, “ 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, 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 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. |
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) may end with the suffix .fm. See Table 2-4 for guidelines for when to use which suffixes.
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 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 must end with the suffix .doc or .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-4. 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 IRIS InSight 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. 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 IRIS 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 IRIS 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 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 IRIS 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. See “Editing the Makefile” in Chapter 6 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 IRIS 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. 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 IRIS InSight.
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 IRIS InSight 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 have to edit it to make it work with your particular book. Directions for editing the Makefile are given in Chapter 6, “Building Online Books”.