Chapter 1. Overview

This chapter provides an overview of the process required to produce localized books for Silicon Graphics as well as specific notes that may be useful to you. The following topics are discussed:

Roles of Localization and Technical Publications Production

Silicon Graphics' Localization Department (L10N) oversees the language translation of IRIX operating systems, software, and books. As the project manager for localizing books, L10N determines the books to be translated, qualifies and hires the localization vendors, details the project schedule, provides linguistic review at various stages of the project, and authorizes the payment of your bills.

Technical Publications Production provides production personnel to prepare files, complete localization specs, provide technical support, perform quality assurance and help testing, generate test reports, file bug reports, and build final images for manufacturing release.

Project Milestones

In general, all book localization projects include the same series of tasks and follow a schedule based on dependencies.

Table 1-1 shows a typical localization project's milestones, the expected duration to complete the task, and the milestone(s) that must be completed before the task can begin.

Table 1-1. Book Localization Milestones, Duration, and Dependencies

Milestone ID



Dependency ID


L10N selects vendors and obtains nondisclosure agreement so tools may be provided




L10N defines the list of books to be translated




L10N and Production sends the vendor kit (including build tools) and the first set of diff files to the vendor(s)

1- 3



L10N receive a cost estimate (quote) from the vendor(s)




L10N establishes an initial project schedule (Schedule 1)




Vendor begins the translation




English document freeze occurs




L10N defines milestones




English manufacturing release (MR) occurs




Production sends the vendor(s) the final diff files (if required)

1 - 3



L10N receives the final quote from the vendor(s)




L10N determines the final list of books (if needed)




Vendor begins the document update based on the new diff files (if necessary)




L10N provides the final project schedule


9, 11


Vendor provides the first hand-off of project files


13, 6


Production and the subsidiaries review the vendor's first hand-off and provide feedback




Vendor incorporates feedback and provides a second hand-off of project files




Production and the subsidiaries review the vendor's second hand-off




Subsidiary review is completed




Vendor incorporates second hand-off (final) changes and provides final hand-off


18, 19


Production completes final quality assurance testing and checks in files




Vendor incorporates final changes (if necessary)




L10N creates CD images


21, 22


Production and L10n test CD images




L10N releases the CD to manufacturing




First customer ship date occurs




The schedule for a typical localization project, including the project's milestones and dependencies, is shown in Figure 1-1.

Figure 1-1. Localization Project Schedule with Dependencies

Vendor Kits

Before the project starts, you will be given some hardware and the software tools you need to meet your deliverables requirement.

Localization's Kit

The L10N vendor kit includes

Production's Kit

Technical Publications Production will supply the following:

  • Silicon Graphics' WorldView Books Production Guide

  • IRIS InSight Professional Publisher Templates (also known as IPTemplates)

  • Book building tools and instructions for installation

    • make

    • insight_dev

    • prod_toolroot

    • impr_rip

    • impr_kanji (Japanese only)

  • Scripts and instructions for their use

  • Silicon Graphics system (if necessary)

Project Files

Silicon Graphics will supply all the files you need to produce the English version of a book. These files and their naming conventions are discussed in these sections:

Localization Specification

You will receive a localization specification for each book undergoing localization. The localization specification provides a list of the files that are being supplied to you and describes the deliverables expected from you.

Word Count Text File

Word count text files are ASCII text files containing all word count information for a new English book. If a book is being revised, the word count file will also show the differences in word counts from a prior English revision that was later localized to the current English revision.

The naming convention is YY.MM.DD.00X-XXXX-nnn.wc.txt for books undergoing localization for the first time and YY.MM.DD.00X-XXXX-nnX_nnY, where 00X_00Y are the two revisions that have been compared to one another.

Example 1-1 shows a typical wc.txt file.

Example 1-1. Word Count Text File









File Names

Total word count











Total diffs =
inserted + deleted




Document Files

The files you download from Silicon Graphics should be all that you need to produce an English version of a document. These files include


FrameMaker source files for the book


FrameMaker bookfile


SGML files for the online version of the book


Text file with instructions

orig directory  

All the original artwork for the book

  • .rgb files are RGB screen captures.

  • .ai files are Encapsulated PostScript files authored in Adobe Illustrator.

  • .ps files are Encapsulated PostScript files authored in Adobe Illustrator.

  • .mv files are Silicon Graphics movie format files.

print directory 

The print versions of the artwork for the book

  • .bw files are the grayscale versions of the .rgb files after they have been put through the tobw tool.

online directory 

All .gif files for the online version of the book

help directory 

All the helpmaps necessary for the book to act as online help for an application or utility

diff directory  

All the compare (CMP) and summary (SUM) files documenting the differences between this version and a previous version of the book.

IRIS InSight Professional Publisher Templates

Silicon Graphics uses single-source documentation for all its technical manuals. All content is input into FrameMaker which is considered the documentation “source.”

A set of custom-designed FrameMaker templates, known as IPTemplates, are used for all Silicon Graphics books. Each template has its own set of character and paragraph catalogs and cross-reference formats. These paragraph and character tags and cross-reference formats must be used in order for the mif-to-sgm translations to work correctly. The translator and build tools include a set of styles that determine how the tags and cross-references will appear in a hard copy or online book. A more detailed description of the templates can be found in Chapter 3, “Using FrameMaker Files and IPTemplate Features.”

All English source files provided to you have been authored using the IPTemplate or have had the IPTemplate applied to them. It is unlikely that you would need to apply an IPTemplate to any documents before you translate them, but if tags or formats are inadvertently changed, a complete set of IPTempates are included with your Vendor Kit. See “Applying the Templates to Existing Files” in the IRIS InSight Professional Publisher Templates for instructions on how to apply a template.

Note: Do not create “custom” tags or change the cross-reference formats. This could cause errors during the bookbuild process. Silicon Graphics will not accept documents with errors.

Online and Printed Documents

From the FrameMaker source, the documentation can take two different paths simultaneously. These paths are discussed in the following sections:

FrameMaker-to-Online Documents

This is a very general overview of what happens during the conversion to online. This process starts with a FrameMaker .doc file that is saved out as a Frame Maker Interchange Format (MIF) file. An ASCII text file, the .mif file can be easily parsed by an application or script. From the mif file, a translator converts the mif into a standard generalized marker language (SGML) file. The sgml files are merged into one DynaText book. DynaText files can be viewed using a DynaText viewer. Figure 1-2 shows the process that is used for converting FrameMaker docs into an online book. Note that this process is automated with tools provided to you.

Figure 1-2. Document File Process: FrameMaker File to DynaText Book

Viewing an Online Book in IRIS InSight and on the Web

To add functionality, Silicon Graphics puts a wrapper around the DynaText viewer and calls it IRIS InSight. IRIS InSight provides capabilities such as cross-book linking; launchable universal resource locators (URLs), reference (man) pages, glossary definitions, and applications; and complete internal-book cross-referencing.

Silicon Graphics uses a Web utility from Inso Providence that automatically converts DynaText books into hypertext marker language (HTML) on the fly. This comes at a loss of functionality normally found in IRIS InSight. Silicon Graphics does nothing special to make the books show up on the Web. If you have a Silicon Graphics system with DynaWeb enabled, it views the same source that IRIS InSight views on the same system.

FrameMaker File to Printed Document

Using the same FrameMaker document used in Figure 1-2, PostScript files are made and sent to a print vendor to be printed.

Before you generate the PostScript files,

  • Paginate the FrameMaker document to remove widowed or orphaned text or list items.

  • Remove the master page from pages with no content, such as even pages at the end of a chapter.

  • Regenerate front-matter files and the index (if applicable) to update cross references.

You will not be expected to create PostScript files for books in Latin 1 languages, such as French, German, or Spanish. You may be required to create PostScript files for books using multibyte characters, such as Japanese or Korean. See the L10N specification for the list of files you'll be expected to deliver.

Figure 1-3. Hard Copy Process

Document and Directory Part Numbers

Silicon Graphics documents are assigned ten-digit part numbers with the format 00X-XXXX-nnn. The document's directory name is the part number, and it contains all the files required for a document. Localized documents use this part number and a two-letter language code to differentiate the part number and the document's directory from its English counterpart. For example, 007-2825-nnnJP is the Japanese version of 007-2825-nnn. Possible language codes are shown in “Part Number Language Codes for Localized Books”.

Most online or printed document part numbers begin with 007. Help books usually begin with 008. The middle four digits are the base part number, and the final three digits indicate the revision level.

Basic Book Set: Short Titles and Part Numbers

A short title is condensed version of a book's full title. No more than 12 characters long, short titles are used in the Makefile for bookbuilding and as the titles of icons representing iconified IRIS InSight books.

A sample list of part numbers and their corresponding short titles are shown in Table 1-2.

Table 1-2. Document Name and Part Number Matrix

Part Number (VERSION)


Document Name (FULL_TITLE)



Desktop User's Guide



Personal System Administration Guide



Silicon Graphics Glossary of Terms

Global Glossary



Quick Answers



System Monitor Errors Help



Desktop Error Message Help



InSight Help



SGIHelp Viewer Help



Confidence Test Help



Confidence Test Errors Help



Nedit Help

Part Number Language Codes for Localized Books

The two-letter language codes currently in use for books are











It is important that localized document directories include this language code as a suffix. For example, the French document directory for the book 007-2825-nnn would be named 007-2825-nnnFR.

Standard Silicon Graphics Bookshelves

Silicon Graphics documents are usually classified as one of the following:


Administrator's guides


Programmer's or reference guides

End User 

Owner's or user's guides


Online-only help books (these do not appear in IRIS InSight)

Each of these types of books has its own online bookshelf in IRIS InSight. The BOOKSHELF variable in a document's Makefile determines the online bookshelf where the book appears. For a more complete description, see “Editing the Makefile”.

Guidelines for Translators

Adding Text

Make sure that the translation matches the source, or English document, as closely as possible. If extra text is added to the document, it will be difficult to update the document at a later date. For example, if the English version of a paragraph is about five lines long and the translated version is about one page long, that means you have added too much detail to the translation. When the book is revised, a compare and summary utility is used to compare the old and the new English versions. The differences in the documentation are then given to you so that you can update the old translated version. If there is extra text in the translated version, there is no utility to ensure that those longer paragraphs are updated properly in a later revision.

Checking Consistency

Make sure that the documentation matches the software which it is intended to support or document. In some cases, the documentation may reference software that requires a particular hardware item before the software will work (such as an IndyCam camera). If you do not have this equipment, contact the Silicon Graphics localization project manager and arrange either for the delivery of the hardware or for Localization to complete the consistency check.

Checking Documentation

Compare the translated version of a document against its English version. Check to make sure that:

  • the table of contents has the same number of headings and that they are the correct heading level

  • the same number of paragraphs are present

  • paragraphs have the same tags

  • characters have the same tags

  • cross references appear in the correct paragraph

  • cross references are the same in format and function

  • GlossaryItem-tagged words appear in the same paragraph

  • figures match the sofware

  • bullets are the correct shape

  • sequential lists are numbered correctly

  • the index shows up in the appropriate language

  • paragraphs tagged as Note, Shortcut, Hint, Tip, Warning, and Caution appear correctly in the appropriate language

  • if a glossary item is more than one word, select and tag all the words and the character space(s) between them as GlossaryItem

  • no text appears in English in the translated document unless appropriate or absolutely neccessary

Localization Requirements

As stated in the localization specifications sent with all source files, please consider the following points when translating a document:

  • Unless your localization project manager indicates otherwise, you must supply books that build error-free before they are sent to Silicon Graphics.

  • All books should closely match the new English source.

  • All character and paragraph tags should match those in the new English source.

  • The same number of markers should exist in both the translated books and the new English source and the markers should be the same as in the new English source.

  • All cross references (internal and external) must work the same as the English source.

  • Index markers must be translated and work properly.

There may be instances where the English source is not error-free. If the English source includes errors or warnings, there is no obligation on your part to fix these errors. These errors should be brought to Silicon Graphics' attention, however, and can be included in your periodic status reports.

Reference Materials

IRIS InSight Professional Publisher User's Guide, 007-2863-nnn

IRIS Insight Professional Publisher Templates, 007-2892-nnn