The book file is a list of filenames, each name referencing a file you wish to include in your book. The names are listed in the order in which the files should appear in your book, and attached to each name (though not appearing in the main book file window) is a collection of information about how the file will be paginated, and how figures, tables, and heading paragraphs are numbered. The book file contains both files you create through standard text entry (chapters, appendixes, and so on), and special “generated” files (Table of Contents, List of Figures, List of Tables, Index) that you create and update using utilities in the book file.

When you access the File menu through the book file, the selections are slightly different than for a normal file. This is because the book file is not a true text file that you can edit in the normal manner, but rather an organizational and formatting tool for your book as a whole. When you want to perform operations that affect how the book file orders, paginates, or generates and updates the files it contains, use the book file. If you wish to alter the content of a text file, or change the output of a generated file, open that particular file.

For information on creating and populating a bookfile, see “Creating a Book File”.

The IPFront.doc contains the title page, credits page, a “what's new” section and a record of revision section. Customize the boilerplate information, such as book title, document number, credits, copyright, limited and restricted rights legend, regulatory information, and trademarks, taking care to keep the paragraph tagging the same as the boilerplate. If your book is a revision of an existing book, complete the “What's New in this Guide” and “Record of Revision” sections. If it is a new book, remove these sections from the file.

The IPFront.doc should be named front.doc for your book and be the first file listed in the bookfile.

Once you have created a bookfile and have at least one file listed in it, you can generate a Table of Contents, List of Examples, List of Figures, List of Tables, and an Index from the File > Generate/Update utility. These templates are applied after the generated files are created and provide the necessary formatting and structure to the generated information. See “Applying the Templates to Existing Files ” for instructions on how to apply the IPTemplates to your generated files.

To create generated files, see “Adding Generated Files to Your Book File ”.

The IPIntro.doc template is used for a preface and/or the “About This Guide” portion of your manual. For books with no part tabs or chapter tabs, the IPIntro.doc is positioned in the bookfile directly before the first chapter. When a part tab and/or chapter tab is used, the IPIntro.doc immediately proceeds the tab(s). Since the preface or “About This Guide” is considered part of the front matter of a book, the page numbering continues in roman numeral format.

Tabs are optional divider pages that appear at the beginning of a printed book's chapters, or, in the case of online and printed books, at the beginning a book's parts. Position the tabs in the bookfile accordingly. Do not use tabs before an appendix or a group of appendices. No page numbers appear on tabs; however, the book pagination accounts for their presence.

The IPChap.doc is used for all chapters of a multi-chapter book. For a one-chapter book, use the IPNoChap.doc, where a chapter title but no chapter number appears at the top. Follow the guidelines in the SGI Editorial Style Guide or your company's own style guide when writing the content of your chapters, and use the paragraph and character tags as described in this book for formatting your content.

The IPAppendix.doc is used for one or more appendices in your book and include an appendix title and identifying letter. Follow the guidelines in the SGI Editorial Style Guide or your company's own style guide when writing the content of your appendices, and use the paragraph and character tags as described in this book for formatting your content.

If new terminology is introduced in your book and it is not included in the SGI Glossary of Terms, the IPGlossary.doc can be used to provide the glossary terms and definitions. When a user clicks on a glossary item in the online version of your book, the glossary's definition appears in a restricted viewer. For books with a local glossary, the definition in the local glossary is accessed. If the glossary item doesn't have a local glossary definition, then the definition in the master glossary appears. Also use the IPGlossary.doc if you want a complete glossary for your book.

This is a dummy paragraph.

This is a dummy paragraph.

There are three tags for bulleted lists: Bullet, BulletInd, and BulletInd4.

This is the Bullet tag:

BulletInd appears here within a numbered list:

BulletInd4 is used here within a hanging list:

Use a square bulleted list for substeps within a numbered list.

Use a dashed list for lists that fall within a bulleted list.

For each required level of indentation, there are two variations of the List tag: ListX and ListX1st. Use the ListX1st variation for the first item in the list, and the ListX variation for subsequent items. In all, there are six ordered list tags: List, List1st, ListInd, ListInd.1st, ListInd4, and ListInd4.1st.

This is an example of the List tags:

This is an example of the ListInd tags:

This example uses the ListInd4 paragraph tags:

There are two hanging list tags: HangingList and HangingListInd. If the options or commands you wish to document are longer than the space provided, use a tab and then a forced return (Shift+Enter, Control+J, Alt+Enter, or Alt+M) to begin a new line. Do not alter the paragraph tag.

Here is a sample hanging list:

Here is another sample hanging list. This one uses HangingListInd and a forced return after the tab for each item because at least one of the items exceeds the length of the tab delimiter.

Tabular lists are multi-column tables that do not use the explicit markings (such as headings and titles) that one normally associates with tables. They are either multi-column lists or hanging lists where the item in the first column wraps. They are created using the FrameMaker table utility. Use one of the table formats called TabularList. For the text in a tabular list, use the paragraph tag TabularListText. Anchor the table at the end of the preceding paragraph.

This is a table created with the TabularList format:

This is bulleted list with an indented hanging list created with the TabularList format:

This is a tabular list inside a hanging list:

When you need to embed a line or two of code in regular text, use an Example tag. There are five variations: Example, ExampleInd, ExampleInd2, ExampleInd4, and ExampleInd5.

When you need to embed a line or two of code in regular text, use the Example paragraph tag:

Example

The following example uses ExampleInd:

The following example uses ExampleInd2:

The following example uses ExampleInd4 and ExampleInd5:

ExampleInd4 

For sample programs—or simply for longer code examples—use a Code paragraph tag. To give your code block the correct vertical spacing above it, use the 1st paragraph tag for the first line of code. There are ten basic Code tags: Code1st, Code, CodeInd1st, CodeInd, CodeInd2.1st, CodeInd2, CodeInd4.1st, CodeInd4, CodeInd5.1st, and CodeInd5. In addition, there are four Code tags for displaying longer lines of code that don't fit within the margins: CodeExt1st, CodeExt, CodeMargin1st, and CodeMargin.

---

Note: If you find it necessary to break a line of code, use the proper syntax for the programming language you are documenting.

---

The following example uses Code1st and Code:

Code1st 


Code 

The following example uses CodeInd:

The following example uses CodeInd2:

The following example uses CodeInd4 and CodeInd5:

CodeInd4.1st 


CodeInd4 

If you have long lines of code that require more characters per line, you can use CodeExt1st and CodeExt tags, which reduce the letter spacing and produce an 80-column line within the text margin:

long line of code that wouldn't fit in the text column and uses CodeExt1st tag


another long line that uses the CodeExt tag to keep it from breaking
12345678902234567890323456789042345678905234567890623456789072345678908234567890

You may also use the CodeMargin1st and CodeMargin paragraph tags to display long lines of code:

For *real* long lines of code, you might need to use the CodeMargin1st paragraph tag.


It's companion, for second and following lines, is the CodeMargin paragraph tag

For code and example blocks that you want to be able to cross-reference and display in the List of Examples at the beginning of your book, precede your block with either the CodeTitle or ExampleTitle paragraph tag, depending on the paragraphs that make up your block.

---

Note: Both tags produce the same automatic string preceding the title, and use the same numbering scheme. The differentiation is necessary for online conversion, because Code and Example are different constructs in the SGML DTD.

---

blah, blah, blah
blah, blah, blah
blah, blah, blah

% su 
# df -k 
# Ctrl-D 
%

Typing math equations is different from typing text. The FrameMaker math editor is also a math package that evaluates and solves equations. SGI does not currently use this equation solving capability, but you should enter equations with the proper syntax to give them a mathematically correct look and to enable use of the equation solver in the future.

Equation objects include variables, operators, relations, and functions. Each entry that you make from the keyboard or from the Special > Equations menu has a mathematical meaning. For example, FrameMaker assumes that a single letter is a variable. When you type one letter after another, FrameMaker assumes the variables are to be multiplied, because in mathematical notation, multiplication is implicit when variables are combined with no spaces between them. If what you really intend is a single variable whose name contains two or more characters, you must select Start String from the Equation menu and type the variable name between the quotes. The quotes disappear when you enter the next object in the equation. Use the space bar to select equation objects for editing.

When you use a variable from an equation in a sentence, some engineers prefer that variable to be set off from the surrounding text with a numeric space before and after it. This prevents the variable-width spacing adjustment from being applied to the spaces surrounding the variable, thus making it stand out from the surrounding text.

Even if you don't use equations, keep in mind that the typography of mathematical symbols is different from that of letters and text symbols. For example, a minus sign has a slightly different appearance and vertical alignment from a dash symbol. A multiplication symbol is different from the letter x.

Use the minus symbol and apply the Symbol character tag rather than use a dash to indicate a negative value or a subtraction. Similarly, enter the multiply symbol (Ctrl+Q 4 and apply the Symbol character tag) rather than the letter x when you intend to represent multiplication. The most common case of this is when quoting dimensions, as in 3 × 5. Do not use the letter x to represent “3 by 5.”

Table A-1 contains a list of the most common mathematical symbols and how to create them so they appear correctly in your FrameMaker document as well as your online book. See FrameMaker Help's keyboard map for additional symbols.

Tables can be customized by adding, deleting, or resizing rows and columns as needed.

If you need additional columns or rows:

To delete any unnecessary rows or columns:

If you need to delete an entire table and its table title:

To resize columns:

Tables should always line up with the left text margin.

Figures, such as screen snaps of icons or other small images, can be included in a table cell. To include a figure within a table:

Table A-2 uses the Table-5Col table format tag found in the Table Format dialog box.

If you have a multi-page table, the string “(continued)” should appear after “Table X-X.” To force this string to appear, insert the Special > Variable > TableContinuation variable before the Tab in your table title. It does not appear in the first page of your table, so you may choose to insert it as a precaution even if your table currently fits on a single page.

Use one of the Hint paragraph tags to provide supplemental information related to the text. There are five Hint tags: Hint, HintInd1, HintInd2, HintInd4, and HintInd5.

This example uses Hint.

---

Tip: Hint Hint Hint Hint Hint Hint Hint Hint Hint Hint Hint Hint Hint Hint Hint Hint Hint Hint Hint Hint Hint Hint Hint Hint Hint Hint

---

The example below uses HintInd:

The following example uses HintInd2:

The following example uses HintInd4 and HintInd5:

HangItem		HangBody Tip: HintInd4 HintInd4 HintInd4 HintInd4 HintInd4 HintInd4 HintInd4 HintInd4 HintInd4 HintInd4
HangItem		HangBody BulletInd4 Tip: HintInd5 HintInd5 HintInd5 HintInd5 HintInd5 HintInd5 HintInd5 HintInd5 HintInd5 HintInd5 BulletInd4

Use one of the Tip paragraph tags to provide supplemental information related to the text. There are five Tip tags: Tip, TipInd1, TipInd2, TipInd4, and TipInd5.

This example uses Tip:

---

Tip: Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip Tip

---

The example below uses TipInd:

The following example uses TipInd2:

The following example uses TipInd4 and TipInd5:

HangItem		HangBody Tip: TipInd4 TipInd4 TipInd4 TipInd4 TipInd4 TipInd4 TipInd4 TipInd4 TipInd4 TipInd4 TipInd4 TipInd4
HangItem		HangBody BulletInd4 Tip: TipInd5 TipInd5 TipInd5 TipInd5 TipInd5 TipInd5 TipInd5 TipInd5 TipInd5 TipInd5 TipInd5 TipInd5 BulletInd4

Use one of the Note paragraph tags to provide supplemental information related to the text. There are five Note tags: Note, NoteInd1, NoteInd2, NoteInd4, and NoteInd5.

This example uses Note:

---

Note: Note Note Note Note Note Note Note Note Note Note Note Note Note Note Note Note Note Note Note Note Note Note Note Note Note

---

The example below uses NoteInd:

The following example uses NoteInd2:

The following example uses NoteInd4 and NoteInd5:

HangItem		HangBody Note: NoteInd4 NoteInd4 NoteInd4 NoteInd4 NoteInd4 NoteInd4 NoteInd4 NoteInd4 NoteInd4 NoteInd4
HangItem		HangBody BulletInd4 Note: NoteInd5 NoteInd5 NoteInd5 NoteInd5 NoteInd5 NoteInd5 NoteInd5 NoteInd5 NoteInd5 BulletInd4

Use one of the Caution paragraph tags to point out actions that may cause damage to your system. There are five Caution paragraph tags: Caution, CautionInd1, CautionInd2, CautionInd4, and CautionInd5.

This example uses Caution:

---

Caution: Caution Caution Caution Caution Caution Caution Caution Caution Caution Caution Caution Caution Caution Caution Caution

---

The next example uses CautionInd:

The following example uses CautionInd2:

The following example uses CautionInd4 and CautionInd5:

HangItem		HangBody Caution: CautionInd4 CautionInd4 CautionInd4 CautionInd4 CautionInd4 CautionInd4 CautionInd4
HangItem		HangBody BulletInd4 Caution: CautionInd5 CautionInd5 CautionInd5 CautionInd5 CautionInd5 CautionInd5 CautionInd5 BulletInd4

Use one of the Warning paragraph tags to call attention actions or practices that may cause physical harm to the user. There are three Warning paragraph tags: Warning, WarningInd, and WarningInd2.

This example uses Warning:

---

Warning: warning warning warning warning warning warning warning warning warning warning warning warning warning warning warning warning warning

---

The following example uses WarningInd:

The following example uses WarningInd2:

Each of the three warning paragraph tags has an icon to the left of it. This icon must be added manually, following this procedure:

There are two shortcut tags: Shortcut and ShortcutInd.

---

Tip: Shortcut Shortcut Shortcut Shortcut Shortcut Shortcut Shortcut Shortcut Shortcut Shortcut Shortcut Shortcut Shortcut Shortcut

---

Text paragraph

Writers are encouraged to use these tags to communicate with their editors and reviewers, rather than inserting comments in brackets or in different fonts. The advantages of using these tags are as follows:

Each of the four flag tags has an icon in the left margin of the tagged paragraph. If you copy an existing flag paragraph from your document or from this template, you will copy the icon with it. In other cases, you must add the icon manually. Follow this procedure:

Flag paragraphs are not supported in the translator, so they will not appear in the HTML versions of your documents. However, your document will build properly with flag paragraph tags in it if you mark them as conditional text. This must be done manually.

When it is time to remove the flag paragraphs from your document, you can find them quickly by using the FrameMaker Edit > Find/Change function:

“Add” and “generate” are two separate procedures in FrameMaker. “Add” means add a file pointer to a bookfile. “Generate” refers to the actual process of searching constituent files for designated paragraph tags and creating a “generated” file. Please note that the bookfile itself is also considered a “generated” file.

To add names of files created through standard text entry (chapters, appendixes, and so on) to your bookfile, follow these steps;

Table A-6 shows the specifications that should be set for text files that you add to your book when there are no part tabs or chapter tabs:

Table A-7 shows the specifications that should be set for text files that you add to your book when there are chapter tabs.

Table A-8 describes the specifications that should be set for text files that you add to your book when there are part tabs.

Table A-9 describes the specifications that should be set for text files that you add to your book when there are part tabs and chapter tabs.

To add names of files to be created through the FrameMaker file generation utility (Contents, Figures, Tables, Index), follow these steps:

At this point, the file itself does not actually exist. What you have done is add the name of a file that FrameMaker will create when you choose Generate/Update from the File menu. See the section “Generating the TOC, LOE, LOF, LOT and Index ” for instructions on how to generate these files.

FrameMaker assumes that when you finally generate your generated files (as opposed to just adding their names to the book file), all the appropriate files are in your book file in the correct order, and have been set up with the correct specifications using File > Set Up File.

To rearrange files so they are in the proper order, use File > Rearrange Files. The window that appears is self-explanatory. This window is the only place where files can be deleted from your book.

After rearranging your files, use File > Set Up File to check for the proper specs, or fix any files that weren't set up when they were added to the book file. See Table A-7 through Table A-10 for the proper specs.

The best way to create your generated files is as follows:

FrameMaker assumes that it is overwriting existing files and simply dumps the generated text into a pre-formatted template section. You should then be able to open up your generated file and see it already fully formatted.

One way to tell if this procedure hasn't worked is if unformatted files pop up at the end of the generation process. This indicates that FrameMaker did not recognize the renamed template copies you put in with your document files, probably because you misnamed them. If this occurs, simply apply the templates to your generated files by using File > Import > Formats. Then choose File > Generate/Update to regenerate the content.

The template uses a single autonumbering scheme to run Chap/AppNum, the “#-” in the footer, Headings, Tables, Figures, Examples, and Equations. The scheme relies upon your having built a book, set up your files, and used File > Generate/Update to repaginate the files.

If your autonumbering doesn't work, here are some possible causes: