This chapter (IPChap.doc) provides an overview of the structure and usage of the paragraph and character tags used in the IRIS InSight Professional Publisher Templates. It also explains how to use Silicon Graphics implementation of certain FrameMaker features, how to build books, and how to generate and format a table of contents and lists of examples, figures, and tables.
To apply the template to a document file:
Open and stow the appropriate template file.
Open the file to which you are applying the template.
Delete all:
paragraph tags (click Delete at the bottom of the paragraph catalog).
character tags (click Delete at the bottom of the character catalog).
table formats (use Table Format dialog box).
master pages other than Right, Left, and First. Clear all elements on the remaining master pages (Special > Delete Pages).
reference pages (Special > Delete Pages).
Delete unused cross-reference formats:
Go to Special > Cross-Reference and click the Format button. Delete all formats and click Done.
Click Cancel for all warning messages that appear asking if you would like to change all cross-references of format x to editable text.
Click Done when you return to the main cross-reference window.
Select File > Import > Formats and take all the formats from the stowed template file.
The length of the paragraph tag list is more a result of the number of variations within basic tag groups than the number of groups themselves. These variations are necessary to indent paragraphs the proper amount, according to this indentation scheme:
Paragraphs at the same level should be indented the same amount.
The left margin of the second paragraph in a list item should be indented such that it lines up with the left text margin of the previous paragraph (see “Lists” for examples).
Indentation levels for tags within a group use a standard nomenclature: Tagname for the tag that puts the paragraph at the margin; TagnameInd or TagnameInd1 for the first 1/4" indent, and TagnameInd2, 3, 4, and so on for each succeeding 1/4" indent.
 | Note: Headings and introductory matter (AppNum, ChapNum, ChapTitle, GlossaryTitle) are exceptions to this scheme. |
The introduction, chapters, appendixes, and index have one, and only one, ChapTitle tag. The glossary uses a similar tag, GlossaryTitle. In an introduction, appendix, glossary, or index, the title tag is the first tag in the file. In chapters and appendixes, ChapTitle is preceded by ChapNum and AppNum, respectively. In the introduction, chapters, and appendixes, the ChapTitle tag should always be followed by at least one Text tag, the contents of which introduce the material.
The template supports three levels of headings: Heading1, Heading2, and Heading3. The standard rule for nesting sections is that there should never be only one of any section level nested within the next highest section. This means that Heading1, for example, should be followed by two or more Heading2s, or none at all.
| Note: If you absolutely can't do without a fourth-level head, use a single line of text formatted with the Text paragraph tag and the Bold character tag. |
This is a dummy paragraph.
There are six types of lists: bulleted, square-bulleted, dashed, ordered, hanging, and tabular. Lists may appear at the margin or within other lists (given the specific restrictions described below). However, nesting beyond one level (that is, nesting two or more levels deep) is not supported in the templates. Lists may not appear within Notes, Cautions, Warnings, Hints, Tips, or Shortcuts.
These further restrictions apply to lists:
A list must contain at least two items.
A bulleted list should not appear within a bulleted list. Instead of the nested bullets, use a dashed list for the indented material.
A dashed list appears only within a bulleted list.
A hanging list may not appear within another hanging list.
The square-bulleted list for is used only for substeps within an ordered list.
No sublists may appear inside tabular lists.
There are three tags for bulleted lists: Bullet, BulletInd, and BulletInd4.
This is the Bullet tag:
Bullet Bullet Bullet Bullet Bullet Bullet Bullet Bullet Bullet Bullet Bullet Bullet Bullet Bullet Bullet Bullet Bullet Bullet Bullet Bullet Bullet
Another Bullet
BulletInd appears here within a numbered list:
First list item
BulletInd BulletInd BulletInd BulletInd BulletInd BulletInd BulletInd BulletInd BulletInd BulletInd BulletInd BulletInd
Another BulletInd
Second List Item Second List Item Second List Item Second List Item Second List Item Second List Item Second List Item Second List Item Second List Item
BulletInd4 is used here within a hanging list:
| HangBody | HangItem
| |
| HangBody | HangItem |
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 the List1st paragraph tag. List1st List1st List1st List1st List1st List1st List1st List1st List1st List1st List1st List1st List1st List1st List1st
This is the List paragraph tag. List List List List List List List List List List List List List List List List List List List List List List List List List
This is the List paragraph tag. List List List List List List List List List List List List List List List List List List List List List List List List List
This is an example of the ListInd tags:
Bullet
Bullet
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-Return, Control-j, Alt-Return, or Alt-m) to begin a new line, rather than customize the paragraph tag.
Here is a sample hanging list:
| Item | body of the hanging list item body of the hanging list item body of the hanging list item body of the hanging list item body of the hanging list item body of the hanging list item | |
| another item | body of the second hanging list item |
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 is too long.
Bullet
thisisanitemofarbitrarylength
used to demonstrate what hanging lists should look like when the item to be documented hangs over the explanatory text.shorter item
another hanginglist body.bullet
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 of the 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:
item one | item four | item seven |
item two | item five | item eight |
item three | item six | item nine |
This is bulleted list with an indented hanging list created with the TabularList format:
Bullet
item one
Long explanation of item one. Long explanation of item one. Long explanation of item one. Long explanation of item one. Long explanation of item one. Long explanation of item one. Long explanation of item one. Long explanation of item one.
item two is a long one that wraps and wraps and wraps
Long explanation of item two. Long explanation of item two. Long explanation of item two. Long explanation of item two. Long explanation of item two. Long explanation of item two. Long explanation of item two. Long explanation of item two. Long explanation of item two. Long explanation of item two. Long explanation of item two.
Bullet
This is a tabular list inside a hanging list:
| HangItem | HangBody
|
Text is the standard unadorned paragraph tag. Text always appears at least once following a ChapTitle or HeadingX. It can be used within any section, interspersed with Code, Example, Hint, Tip, Note, Caution, Warning, or any type of list. It can also appear as a second and following paragraph in any type of list. There are five levels of indentation for regular text: Text, TextInd, TextInd2, TextInd4, and TextInd5.
This sentence is Text, and the tag in the bulleted item is TextInd:
The example below uses TextInd2:
Bullet
Bullet
The following example uses TextInd4 and TextInd5:
| HangItem | HangBody TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 | |
| HangItem | HangBody |
[1] For margin comments, use the MarginText paragraph tag. You'll have to create an anchored frame with a text block, as is done in the block to the left of this paragraph, and line up the baselines of the first lines of the two blocks.
The Code and Example tags both produce Courier text. The only difference between the two is the amount of spacing between paragraphs: Code produces less, Example more. Code is used mainly for blocks of programming code or output, where it's important to fit as much on the page (or screen) as possible. Example is used mainly for single code lines (Code and Example are basically interchangeable in this context) or for sequences of command lines. Code and Example can appear at the margin, or within lists, but not within Hints, Tips, Notes, Cautions, Warnings, or Shortcuts.
Code and Example tags do not contain any tabs. Do not add any tabs. If you do, you run two risks: Using File > Import > Formats From will overwrite them, and your code will not be formatted correctly if your book goes online. If you need to import code or example text that contains tabs, there are scripts available to convert the tabs to spaces before you import the text in FrameMaker.
 | Caution: Once you begin a block with an Example, Code1st, CodeExt1st, or CodeMargin1st paragraph, you must tag subsequent paragraphs in the block with the appropriate variation of that tag for second and following paragraphs. If you mix and match Code and Example tags, the online tools become confused and may mis-tag or mis-format your block. |
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:
For sample programs—or simply for longer code examples—use a Code paragraph tag. It uses more compact vertical spacing than Example. Use the 1st paragraph tag for the first line of code to give your sample the correct vertical spacing. 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:
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:
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 our SGML DTD. |
Example 1-1. Code Block Beginning With the CodeTitle Paragraph Tag
blah, blah, blah blah, blah, blah blah, blah, blah |
There are five message tags: Msg, Msg1st, MsgExpl, MsgMargin, and MsgMargin1st. These are the tags for things like error messages, system feedback, and so on. This is the sequence for error message constructs:
one Msg1st (or variants) paragraph tag
zero or more Msg (or variants) paragraph tags
one or more MsgExpl paragraph tags
zero or more paragraph tags that can appear following the paragraph tag MsgExpl.
MsgExpl MsgExpl MsgExpl MsgExpl MsgExpl MsgExpl MsgExpl MsgExpl MsgExpl MsgExpl MsgExpl MsgExpl MsgExpl
BulletInd4 BulletInd4 BulletInd4 BulletInd4 BulletInd4 BulletInd4 BulletInd4 BulletInd4
ExampleInd5 ExampleInd5 ExampleInd5 ExampleInd5
TextInd5 TextInd5 TextInd5 TextInd5 TextInd5 TextInd5
Note: NoteInd5 
Tip: HintInd5
TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 TextInd4
ExampleInd4 ExampleInd4 ExampleInd4 ExampleInd4 |
ListInd4.1st ListInd4.1st ListInd4.1st ListInd4.1st ListInd4.1st
TextInd5 TextInd5 TextInd5 TextInd5 TextInd5 TextInd5 TextInd5
ListInd4 ListInd4 ListInd4 ListInd4 ListInd4 ListInd4
| Note: NoteInd4 |
If you need more space, use MsgMargin1st and MsgMargin.
023456789012345678902234567890323456789042345678905234567890623456789072345678908234567890923 023456789012345678902234567890323456789042345678905234567890623456789072345678908234567890923
MsgExpl MsgExpl MsgExpl MsgExpl MsgExpl MsgExpl MsgExpl MsgExpl MsgExpl MsgExpl MsgExpl
TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 TextInd4
ListInd4.1st ListInd4.1st ListInd4.1st ListInd4.1st ListInd4.1st ListInd4.1st ListInd4.1st
ListInd4 ListInd4 ListInd4 ListInd4 ListInd4 ListInd4 ListInd4 ListInd4 ListInd4 ListInd4
TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 TextInd4 TextInd4
| Note: NoteInd4 |
BNFTerm and BNFRule set up text to follow the Backus-Naur Form, a notational convention that describes the syntax of a programming language.
| BNFTerm | BNFRule BNFRule |
There are two tags for checkoff boxes:
Use the Equation paragraph tag to produce equations with titles and numbering. If you don't want the numbering, use the appropriate version of the Text tag necessary to produce the proper level of indentation. For full instructions on how to produce equations, see the FrameMaker documentation.
| Note: Equations are not currently supported online, except as snapped figures. If your document is going online and you wish to have equations in it, snap them and treat them as figures. |
 |
Typing math equations is different from typing text. The FrameMaker math editor is also a math package that evaluates and solves equations. Silicon Graphics does not currently use this equation solving capability, but you should enter equations with the proper syntax anyway, 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 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 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 from the Symbol font rather than a dash to indicate a negative value or a subtraction. Similarly, enter the multiply symbol (Ctrl+q 4) 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.”
There are two tags used for figures that appear inline in the hard copy: Fig and FigTitle. The template also uses a third tag (FigTitleMargin) for figures that appear in the margin of the hard copy. The Fig tag should not have any text in it. Its sole purpose is to serve as a placeholder for the anchored frame that holds the figure. FigTitle follows immediately after Fig, and holds the title of the figure. FigTitleMargin holds the title of figure in the margin.
Use this procedure to set figures up correctly:
Press Enter to create a new paragraph.
Press Enter again to create a paragraph that automatically has the FigTitle paragraph tag applied to it. Type in the figure title.
Place the cursor in the Fig paragraph and select Anchored Frame from the Special menu.
In the Anchored Frame dialog box, choose these settings:
Anchoring Position: Below Current Line
Alignment: Right
Cropped, but not Floating
Size: your choice (the frame can be resized once it's inserted)
Click New Frame.
Import your figure by reference into the anchored frame, using the File > Import > File dialog box.
To select a text object in an anchored frame, the anchored frame itself, or a text column on a page without opening the toolbox and changing to the arrow selection tool, simply hold down Ctrl while clicking the object. Shift select selects and deselects additional objects after the first object is selected.
Use the micro-adjust feature to move graphic objects in incremental (smaller than grid units) steps, even when Snap to grid is turned on: hold down Ctrl and use the arrow keys to move objects.
Side-column figures, such as Figure 1-2, are a bit more difficult to set up than inline figures. However, once you set up your first one, you can cut out about half the steps by copying the anchored frame marker, pasting it into the appropriate spot, and adjusting the frame size to fit your new figure.
| Caution: If you create additional figures using this method, be sure to delete all the text in the figure title, including any cross-reference target markers. |
To create a side-column figure, follow these steps:
Place the cursor at the beginning of the paragraph containing the reference to the figure.
Select Anchored Frame from the Special menu and set the following:
Anchor Position: Left side of column
Width: 1.375"
Height: Guess and then adjust in Step 3
Near-Side Offset: -1.375"
Base-Line Offset: - (Height-.1)"
Import your figure by reference into the anchored frame, using the File > Import > File dialog box.
Place the cursor just after the anchored frame symbol you created and add another anchored frame with the following measurements:
Anchor Position: left side of column
Width: 1.375"
Height: .625" (enough for three lines of text)
Near-Side Offset: -1.375"
Base-Line Offset: Subtract .67" from baseline offset of previous frame.
Draw a text box inside the lower frame so that its edges butt the edges of the frame. You may need to turn off Snap in the Graphics menu to do this.
Place the cursor in the text box, click FigTitleMargin and type in the name of the figure.
To create tables, use the FrameMaker table facility. You can access its features by selecting various menu choices in the Table menu. For complete instructions on how to create and modify FrameMaker tables, see the FrameMaker documentation.
To create a table, follow these steps:
Place the cursor at the end of the paragraph that immediately precedes where you want the table to go.
Choose Insert Table from the Table menu, select the proper Table Format and number of body rows (you can always add or delete these later), and click Insert.
The templates use three paragraph tags for text in the various parts of a table. Body cells use the TableText paragraph tag. Heading Cells use the TableHead paragraph tag. The table title goes in the table block above the table. It uses the TableTitle paragraph tag. All these tags should be applied automatically when you create your table. Tables can be customized by adding, deleting, or resizing rows and columns as needed. They should always line up with the left text margin.
| Caution: Though you may use any character tags you wish within a table, do not use any paragraph tags other than those designated for each of the three table parts. In addition, if you put any equations or graphics in your tables, they will not appear online. |
Table 1-1 uses the Table-5Col table format tag found in the Table Format dialog box.
Table 1-1. Real N x N Operations (TableTitle)[a]
N | Load 4, 4*N | N | Load 4, 4*N | N |
|---|---|---|---|---|
128 | .003 | 128 | .003 | 128 |
256 | .0105 | 256 | .0105 | 256 |
512 | .039 | 512[b] 312 | .039 | 512 |
128 | .003 | 128 | .003 | 128 |
256 | .0105 | 256 | .0105 | 256 |
512 | .039 | 512 | .039 | 512 |
1024 | .150 | 1024 | .150 | 1024 |
[b] This is a table footnote in a table cell. It uses the TableFootnote tag. | ||||
If you have a multi-page table, the string “(continued)” should appear after “Table X-X.” You force this string to appear by inserting the 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.
| Note: To facilitate the addition of the Table Continuation variable to the template, you must now add a Tab before your title when using the TableTitle paragraph tag. |
| Note: If your table spans more than one page, you may find that the spacing between the end of the table and the beginning of the following paragraph is incorrect. This has been logged as a bug by FrameMaker. To add extra space, increase the Space After for the table itself in the Table Format dialog box. |
Hints, Tips, Notes, Cautions, Warnings, and Shortcuts are used to provide short, supplemental or cautionary information. They are not meant to provide space for long blocks of interpolated information. Therefore, there is no support for second and following paragraphs either in the templates or in the online translator.
| Note: The workaround, if you absolutely must add a line of Code or Example after your Note, is to use two forced returns, like this: line of code |
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:
Bullet
Bullet
The following example uses HintInd4 and HintInd5:
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:
Bullet
Bullet
The following example uses TipInd4 and TipInd5:
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:
Bullet
Bullet
The following example uses NoteInd4 and NoteInd5:
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:
Bullet
Bullet
The following example uses CautionInd4 and CautionInd5:
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. Unfortunately, this icon must be added manually, following this procedure:
Place the cursor at the very beginning of a warning paragraph.
Select Anchored Frame from the Special menu and select the correct settings according to the type of warning paragraph tag you are using. See Table 1-2.
Table 1-2. Anchored Frame Specs for Warning Tags
Paragraph Tag
Anchor
PositionBaseline
OffsetNear-Side
OffsetHeight
Width
Warning
Left side
-0.2"
-1.5"
0.5"
.05"
WarningInd1
Left side
-0.2"
-1.75"
0.5"
0.5"
WarningInd2
Left side
-0.2"
-2.0"
0.5"
0.5"
When you complete this and reactivate the page, you see an empty box to the left of the Warning.
Go to the Warning Reference Page and copy the warning symbol in the square box. The icon is clearly labelled and has an explanation with it. After you copy, go back to the Body Page.
Select the anchored frame you created and use the Paste command to paste the icon into the frame. Do not move the icon around in the frame. It is positioned correctly and moves with the text.
| Note: This procedure is not as complicated as it looks and it works in all cases but one: when the Warning paragraph is the first paragraph on the page. In this case, FrameMaker bumps the anchored frame down so it doesn't run above the top of the upper margin. So, you must add an empty Text tag above the Warning tag, then set the Space Above for the Warning paragraph to 0.0". This workaround is not recommended until you are certain that a Warning tag will fall at the top of a page. |
The four flag tags in this section have been created for writers to use in internal drafts They are based on the Warning paragraph tag from the standard IPChap.doc template.
There are four Flag paragraph tags. They are for internal use only and should be tagged with the Comment condition so they don't appear in finished books. The online translator does not currently support these tags, and the bookbuild will break if you try to build a file without making the text conditional.
Examples of the four tags appear when viewing the templates through FrameMaker.
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:
They are easy for editors and reviewers to locate and distinguish from live text.
They are easy to find when the document is final and it's time to remove them.
They add visual interest and relieve the monotony.
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:
Place the cursor at the very beginning of a flag paragraph.
Select the Anchored Frame option from the Special menu and select the correct settings according to the type of flag paragraph tag you are using. See Table 1-3.
Table 1-3. Anchored Frame Specs for Flag Tags
Paragraph Tag
Anchor
PositionBaseline
OffsetNear-Side
OffsetHeight
Width
FlagEditor
Left side
-0.4"
-1.5"
0.7"
0.6"
FlagFiction
Left side
-0.4"
-1.5"
0.7"
0.5"
FlagMissing
Left side
-0.4"
-1.5"
0.5"
0.7"
FlagNew
Left side
-0.2"
-1.5"
0.5"
1.0"
When you complete this and reactivate the page, you will see an empty box to the left of the flag paragraph.
Go to the Warning reference page and copy the icon from the appropriate box. The icon is clearly labelled and has an explanation with it. After you copy, go back to the Body Page.
Select the anchored frame you created and use the Paste command to paste the icon into the frame. Do not move the icon around in the frame. It is positioned correctly and moves with the text.
Flag paragraphs are not supported in the translator, so they will not appear in the IRIS InSight 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's time to remove the flag paragraphs from your document, you can find them quickly by using the FrameMaker Find function:
Select Find/Change from the Edit menu.
Change the Find popup menu to Paragraph Tag.
Click the Use Wildcards button.
Type flag* in the text area.
Click the Find button.
This is an example sentence that has a footnote at the end.[2]
The paragraph tag called PageBreak breaks the paragraph that follows the tag to the next page. To use PageBreak, create an empty paragraph immediately preceding the paragraph you wish to break to the next page, and apply the tag to the empty paragraph.
Character tags may appear within any paragraph tag. The only restriction on their use is that they should be applied only to actual visible characters or to spaces within a character-formatted string.
Many of the character tags in the character catalog are used to format non-editable text in such paragraph tags as Warning and FigTitle. Table 1-4 describes the character tags you may use for character formatting, along with their formatting specs.
Tag | Print Format | Online Format | Comments |
|---|---|---|---|
bold | bold |
| |
italic | italic | For onscreen buttons only. | |
Helvetica 8pt | NA | For figures only, does not appear in main text | |
Helvetica 8pt | NA | For figures only; does not appear in main text | |
Helvetica 8pt | NA | For figures only; does not appear in main text | |
CmdLineOpt | Palatino bold | body-font bold |
|
italic | italic |
| |
italic | italic |
| |
Palatino Italic | italic |
| |
Palatino bold | body-font bold |
| |
italic | underlined |
| |
Helvetica Bold | Helvetica Bold |
| |
italic | italic |
| |
Palatino bold | body-font bold |
| |
Palatino Regular 10pt; default text | red | Used for link launch | |
Palatino Regular 10pt; default text | red | Used for reference page (man page) launch in IRIS InSight | |
Courier | Courier |
| |
subscript | subscript |
| |
superscript | superscript |
| |
Σψμβολ | Σψμβολ |
| |
Courier Bold | Courier Bold |
| |
Palatino Italic | Italic |
|
The templates support the standard method for index creation using markers as described in the FrameMaker documentation. However, this can become tedious and error-prone if you are trying to create or update a large set of index markers. To address this problem, an alternate method in index creation was developed. It relies upon a conditional text format, IndexEntry. The IndexEntry conditional text format is part of the standard set of conditional formats provided with each template file.
In addition, the IPIX.doc file for formatting generated indexes designates a small set of characters that will be ignored during index sorting. The set of ignored characters, their effect on sorting, and the syntax for overriding the ignore instructions are outlined in “Template-Specific Index Entry Syntax Rules”.
Below are some tips to help make index creation a less painful experience:
Be careful about how you treat blank spaces before and after your index entries. For example, if you put an index entry at the beginning of a paragraph and put an unconditional blank between the index entry and the real beginning of the text, your paragraph will be improperly indented.
FrameMaker can automatically generate lists of markers that can be very handy. Use Generate/Book from the File menu, check List, select List of Markers or Alphabetical Marker List, click Generate and go on from there.
Using the Search window to search for Any Marker, Marker of Type:, or Marker Text: is also very handy.
For an explanation of the standard rules for index entry syntax, see the FrameMaker documentation. The templates have defined the following characters as “ignored” for index sorting purposes:
$ dollar sign / slash . period < less than " double quote “ left double quote ” right double quote - hyphen – endash — emdash |
So, for instance, the entry
/etc/hosts |
is sorted as though the slashes were absent. The full entry (under E) appears as
E /etc/hosts |
Be aware that because all instances of an ignored character are ignored, sequences like the following are possible:
/etc/ghosts /etchosts /etc/root |
This is mainly a problem with the / character, since the other ignored characters rarely appear anywhere but the beginning of an index entry. In the case of the / character, it was decided that the advantage of having the leading / ignored outweighed the disadvantage of having to put up with a few cases where an ignored / in the midst of an entry caused an unusual sort order.
The following rules apply to ignored characters in index entry syntax.
If an ignored character appears in brackets, it is “unignored” for sorting purposes:
/etc/hosts[/] is sorted (under Symbols) as:
Symbols /etc/hosts
If the ignored character in brackets is followed by any text, the entry is sorted according to the full bracketed string, and the ignored character is ignored.
/etc[/etc] is sorted as:
E /etc
The unignore “flag” can be grouped with other sort instructions in brackets.
/etc[;/;blah] is sorted as:
Symbols /etc
and
B /etc
and
E /etc
There is a standard set of cross-reference formats in the templates. You may use these or create your own, up to a maximum of twenty-four. If you need more room, you may even delete existing tags. However, do not change the specs for any existing tags, because your modifications will go away if you or the next author ever reapply the template defaults.
For information on how to use the FrameMaker cross-reference features, see the FrameMaker documentation.
The online tools do not recognize cross-reference format tags. They rely solely on the cross-reference string that appears in the text. This is why you can add any new formats you wish.
Crossbook links for online documents can also be created using markers (See “Markers”).
Cross-references in figures (callouts) do not automatically appear as hot links online.
There are five custom markers:
| 15 | Marker #15 is used to override DTD restrictions on certain constructs: type “override” into the marker. | |||
| 16 | CrossBook Link is used to flag cross-book links for QA purposes. | |||
| 17 | Executable is used to execute external applications online. The syntax is either If you want an icon in the margin, use this syntax:
If you want clickable text, use this:
Use the second option in conjunction with the Launchword character tag to create a hot word, or set of words, that launches an executable. The marker should immediately precede the tagged word(s). This paragraph contains a marker using ebt_launch. Note the icon that appears in the margin. This paragraph contains hot text that launches an application. | |||
| 18 | The build tools translator turns this construct into a cross-book link, same as what you get with the standard FrameMaker cross-reference tool:
Marker #18 should have text using this syntax:
| |||
| 19 | Marker #19 ends a marker-created crossbook link (See marker #18 above). It is empty. |
The templates support six text conditions:
Comment
HelpSubTopic
IndexEntry
OnlineOnly
PrintOnly
ColorPrintOnly
For information on how to use the FrameMaker conditional text features, see the FrameMaker documentation.
The IRIS InSight inline widget allows you to use digital media in your online document. The syntax is as follows:
type:referenced_filename
Movie_Title
For the first paragraph, use the InlineObj paragraph tag. type can be SGIVIDEO, SGIRGB, SGIAUDIO, or SGIINVENTOR. The title paragraph is optional. It uses the InlineTitle paragraph tag. Both InlineObj and InlineTitle must use the OnlineOnly conditional tag.
Use the HelpTopic or HelpSubTopic paragraph tags for embedding help in an online document. For instructions on creating a help document or embedding help in an online book, see the IRIS InSight Professional Publishers User's Guide.
The book file is really nothing more than 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. It is 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.
You can create a book file as soon as you have at least one standard text file that will go into it. If you do so at this point, you will be able to take advantage of such book file utilities as automatic pagination and creation of generated files. You will also be able to open your files by double-clicking their names in the book file. Once you have created your book file, keep it open while working on any files it contains. This will help you keep track of your files and allow you immediate access to book file utilities.
To create a book file, follow these steps:
Open a document that will be part of your book.
Choose Generate/Book from the File menu.
Choose the radio button that says “New multi-file book, including filename.doc.”
A new window should pop up on your screen within a few seconds. The header bar should have a name like filename.book and main window should contain the name of the document you had open when you chose Generate. This new window is your book file.
After you have generated a new multi-file book, save the file as your book file using a prefix that will easily identify your book, such as Prog.book. This prefix will become the prefix for generated filenames. FrameMaker names generated files according to the title of the book file in which they reside. So, if your book file is named Prog.book, then you will have names like Prog.TOC, Prog.LOT, and so on. You can't change these generated filenames later.
“Add” and “generate” are two separate procedures in FrameMaker. “Add” means add a file pointer to a book file. “Generate” refers to the actual process of searching constituent files for designated paragraph tags and creating a “generated” file. Please note that the book file itself is also considered a “generated” file.
To add names of files created through standard text entry (chapters, appendixes, and so on), follow these steps;
Select Add File from the File menu. The window that comes up has three main areas. The top portion allows you to choose the type of file you wish to add.
Choose Document File. The left portion lets you choose where you would like the file to go in you book file. You can highlight any file in the list and chose Before or After Current File from the pulldown menu directly above the list. The right portion lists the files you can add.
Choose the one you want and click Add. The name of the file should appear in the book file.
Highlight the new filename by clicking it, and go to Set Up File in the File menu. The window that appears allows you to set the specs necessary for your file to have the correct page and paragraph numbering.
After the name of the new file appears, highlight it by clicking on it and choose Set Up File in the File menu. The window that appears allows you to set the specifications necessary for your file to have the correct page and paragraph numbering. The following tables describe the specifications that should be set for text files you add to your book depending on the combination of part tabs and tabs in your book.
Table 1-5 shows the specifications that should be set for text files that you add to your book when there are no part tabs or tabs:
Table 1-5. Page Setup for Text Files (No Part Tabs or Tabs)
Filename | First Page | Page | Paragraph | Prefix |
|---|---|---|---|---|
Front.doc | right | restart | restart | not used |
Intro.doc | right | continue | restart | not used |
Chap1.doc | right | restart | restart | not used |
Chap2.doc | right | continue | continue | not used |
AppendixA.doc | right | continue | restart | not used |
AppendixB.doc | right | continue | continue | not used |
Glossary.doc | right | continue | continue | not used |
Table 1-6 shows the specifications that should be set for text files that you add to your book when there are tabs
Table 1-6. Page Setup for Text Files (With Tabs)
Filename | First Page | Page | Paragraph | Prefix |
|---|---|---|---|---|
Front.doc | right | restart | restart | not used |
Intro.doc | right | continue | restart | not used |
Tab1.doc | right | restart | restart | not used |
Chap1.doc | right | continue | continue | not used |
Tab2.doc | right | continue | continue | not used |
Chap2.doc | right | continue | continue | not used |
TabA.doc | right | continue | restart | not used |
AppendixA.doc | right | continue | continue | not used |
TabB.doc | right | continue | continue | not used |
AppendixB.doc | right | continue | continue | not used |
Glossary.doc | right | continue | continue | not used |
Table 1-7 describes the specifications that should be set for text files that you add to your book when there are part tabs
Table 1-7. Page Setup for Text Files (With Part Tabs)
Filename | First Page | Page | Paragraph | Prefix |
|---|---|---|---|---|
Front.doc | right | restart | restart | not used |
Intro.doc | right | continue | restart | not used |
PartTab1.doc | right | restart | restart | not used |
Chap1.doc | right | continue | continue | not used |
PartTab2.doc | right | continue | continue | not used |
Chap2.doc | right | continue | continue | not used |
AppendixA.doc | right | continue | restart | not used |
AppendixB.doc | right | continue | continue | not used |
Glossary.doc | right | continue | continue | not used |
Table 1-8 describes the specifications that should be set for text files that you add to your book when there are part tabs and tabs
Table 1-8. Page Setup for Text Files (With Part Tabs and Tabs)
Filename | First Page | Page | Paragraph | Prefix |
|---|---|---|---|---|
Front.doc | right | restart | restart | not used |
Intro.doc | right | continue | restart | not used |
PartTab1.doc | right | restart | restart | not used |
Tab1.doc | right | continue | continue | not used |
Chap1.doc | right | continue | continue | not used |
PartTab2.doc | right | continue | continue | not used |
Tab2.doc | right | continue | continue | not used |
Chap2.doc | right | continue | continue | not used |
TabA.doc | right | continue | restart | not used |
AppendixA.doc | right | continue | continue | not used |
TabB.doc | right | continue | continue | not used |
AppendixB.doc | right | continue | continue | not used |
Glossary.doc | right | continue | continue | not used |
To add names of files to be created through the FrameMaker file generation utility (Contents, Figures, Tables, Index), follow these steps:
Select Add File from the File menu.
From the top portion of the window that appears, choose the type of file you wish to add.
If it is a TOC, LOE, LOF, or LOT, choose Generated List, and use the popup menu directly to the right to select the type of generated file you wish to add.
If it is an Index, choose Generated Index and use the popup menu directly to the right to select Standard Index.
From the right portion of the Add File window, choose where you would like the file to go in your book file. You can highlight any file in the list and chose Add File Before or Add File After from the popup menu directly above the list. When you are satisfied with your choices, click Add.
The Set Up File window immediately appears. It provides various FrameMaker utilities with the information necessary to create and paginate your new generated file. Table 1-9 describes the settings you should use for each type of generated file:
Table 1-9. Page Setup for Generated Files
Filename
First Page
SidePage
NumberingParagraph
NumberingPrefix
Include Paragraph Tagged
TOC.doc
right
continue
restart
not used
ChapTitle,
GlossaryTitle,
Heading1,
Heading2,
Heading3 (optional)LOE.doc
right
continue
restart
not used
CodeTitle
ExampleTitleLOF.doc
right
continue
restart
not used
FigTitle,
FigTitleMarginLOT.doc
right
continue
restart
not used
TableTitle
IX.doc
right
continue
continue
not used
Index
Once you have made your choices, press Enter and the new filename appears in your book file. You can tell it is a generated file by the plus symbol that appears immediately to the right of the name.
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 1-6 through Table 1-9 for the proper specs.
The best way to create your generated files is as follows:
Set up your book file as described in “Creating a Book File”.
Copy the generated sections of the template to your working directory.
Rename the copied template files using the same names that these sections have in the book file.
Select File > Generate/Update.
This way, 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 FrameMaker pops up unformatted files 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.
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 Generate/Update to repaginate the files.
If your autonumbering doesn't work, here are some possible causes:
You haven't built the book, set up your files in your book, or repaginated using Generate/Update.
You've hardwired the autonumbering.
One or more chapters or appendixes don't have the proper Num or Title tag.
You're using an old or hybrid version of the template.
You have Freeze Pagination turned on.