If you want individual characters to have a particular look, be sure to use the supplied character tags to change their appearance. Do not use FrameMaker's character designer tool to simply change the format of a character. The build tools look only at tags, not at any modifications you may have made to a character's format. If you don't understand the distinction between tags and formats, refer to the FrameMaker documentation.

The example files that come with the templates and Chapter 3, “Using the IPTemplates to Author Documents” contain descriptions of the various tags and where and how they may be used. For example, don't put the ChapTitle tag before the ChapNum tag, or the FigTitle tag before the ChapTitle tag, or the Heading2 tag directly after the ChapTitle tag. The online translator expects to see only certain sequences of paragraph and character tags and produces errors for what it considers invalid sequences.

---

Note: Don't create your own tags, because the build tools cannot translate any tags they don't know about.

---

Use the correct character tag for each tagged word or phrase. Content-based tags (based on the kind of information being tagged) are preferable to format-based tags (based on the physical appearance of characters). For example, if you're tagging a command, use the Command character tag rather than the Italics character tag. Use the format-based character tags, such as Italics and Bold, only when the template doesn't contain a specific tag that fits your word or phrase.

The current build tools do not support FrameMaker equations. If you want an equation in your online book, you must use snapshot or some other screen capture tools to capture a picture of the equation. snapshot saves the equation as a .rgb file and you can import this .rgb file as if it were a figure. Don't give the equation a figure title, though, or it will show up in the list of figures as a figure. For more information about creating equations, see “ Equation Paragraph Tags” in Chapter 3; information about screen captures can be found in “Capturing Images” in Chapter 5.

In general, try to keep character tags on the specific word or phrase you're tagging, without tagging surrounding whitespace. In particular, never apply a character tag to a tab or a soft return^[8] . It's easy to apply character tags to whitespace characters by mistake, particularly when you're working with a hanging list (note that a tab character that has a character tag generates a warning message), so be careful.

Here are a couple of things to watch for when tagging:

Format code examples with spaces, rather than with tabs. Tabs in code don't display properly online because the translator doesn't recognize them for that paragraph tag. Conversion scripts exist to convert tabs to spaces before importing code examples into FrameMaker files.

---

Note: Be sure to turn off FrameMaker's Format > Document > Text Options > Smart Spaces feature before you import any code examples into your FrameMaker file. Otherwise, multiple spaces will be squashed down to one space and you'll lose your formatting. (Also turn off Smart Quotes so that code samples use straight quotation marks instead of curved ones.) Be sure to turn on Smart Spaces (and Smart Quotes) after you're done working with code samples.

---

Create copyright, registration, and trademark symbols according to the instructions listed here. If you use any other method for creating these symbols, you'll run into problems when you convert your files to SGML.

Create en dashes and em dashes according to the instructions listed here. If you use any other method for creating these symbols, you might create problems when you convert your files to SGML.

Footnotes and table footnotes are supported in IRIS InSight. To create them, use the Special > Footnote feature and the Footnote paragraph tag (for footnotes within text) or the TableFootnote paragraph tag (for footnotes in tables).

A structural link is automatically created from the structure of the document during the conversion process. Lists of such links appear in the IRIS InSight > Views menu. All the headings listed in the Table of Contents (TOC) view in InSight, for example, are automatically linked to the corresponding headings within the book itself. The same goes for all figures, tables, and media shown in their respective View lists. The result is that a reader can click any item in a list view and the text area scrolls to the appropriate location in the online book.

The writer can use various FrameMaker tools to create links to text, tables, or figures in the same book (or in another book), between the text and the glossary, or between the index and the text. Each link has its own appearance and behavior.

Table 4-1 summarizes the writer-generated link types:

Cross-reference links within a book are created using the FrameMaker Cross-Reference tool. They appear as bold blue text within the online document. When the reader clicks the link, IRIS InSight either scrolls to the text if the link is to a table or text, or opens the figure in a restricted view if the link is to a figure.

In the example shown in Figure 4-1, the cross reference is referring to Figure A, and Figure A is located two paragraphs below the cross reference. When the reader clicks on the blue “Figure A” text, they are automatically jumped to the image and title for Figure A.

Figure 4-1. Diagram of Cross Reference Targets

To establish a cross-reference:

Table 4-2 shows a matrix of the possible cross-reference formats for each tag.

---

Note: Only paragraph tags and their possible cross-reference formats that can generate a useful cross-reference are listed in Table 4-2.

---

Be sure to use an appropriate cross-reference format. Note that the conversion tool automatically removes any page numbers that appear in your cross-reference text; if your book will appear in print as well as online, it's a good idea to use cross-reference formats that include page numbers to help hard copy readers navigate through the book.

Cross-book links appear as bold red text within the online document. When the reader clicks on the link, IRIS InSight opens the appropriate book (if it's available) and either scrolls to the text if the link is to a table or text, or opens the figure in a restricted view if the link is to a figure.

Although cross-references between documents are much like cross-references between files within a book, there are two problems that complicate the situation tremendously:

The first problem is a coordination and document management issue. If you want to create cross-book links, please take the time to evaluate the risk of having it break. If the book you want to link to is in development, be sure to talk with the author. If the book has already been released, find out when it will be revised and how extensive the changes will be.

Once you have decided to create a cross-book link, you must make sure that there's a cross-reference target in the other book at the point to which you want to link. If such a target doesn't exist already, you need to ask the writer of the other book to create a target for you. It's probably not a good idea to make changes to someone else's book without asking first, especially if you use a revision control system to check documents into and out of a central archive.

To create a cross-book link using markers:

The result is a piece of your document with this structure:

<type-18_marker>text<type-19_marker>

where “text” is the text that will be marked as a link, the type-18 marker contains the name of the target book and the ID of the target element, and the type-19 marker is empty (a placeholder to indicate the end of the cross-reference text).

---

Note: The text between the markers cannot contain any character tags other than DocTitle.

---

Glossary links appear as blue italicized words in the online text. When the reader clicks on the word, the definition appears in a restricted viewer. The link itself is either to the SGI Glossary of Terms, a global glossary common to all books, or to a local glossary specific to the book. IRIS InSight searches the local glossary first (if it exists), then searches the global glossary.

To make a glossary item, tag the word using the GlossaryItem character tag. Do this only where you think it is important, not every time the word appears; otherwise your book will be peppered with blue italicized glossary links. In order to match, the text that you tag GlossaryItem must be spelled and punctuated identically to the text of a GlossaryTerm in your glossary.

---

Note: This restriction (requiring the linked reference to be identical to the entry) can cause some problems. For instance, if you have a glossary entry for the term “window,” you can't link to it from the words “windows” or “windowing” in the text; and it can be difficult to re-word the text to fit the format of the glossary entry. One workaround for this problem is to create additional cross-referencing glossary entries for those words—have an entry for “windows,” for instance, which simply says “see `window,'” with the word “window” linked to the glossary entry. (You can put glossary links inside the glossary itself.)

---

To create a local glossary tailored specifically to your book, use the IPGlossary.doc template provided with the book template files. Once you've created your glossary, add its filename (usually simply glossary.doc) to your Makefile at the end of the list of chapter files. The build tools automatically create links between words tagged GlossaryItem and the corresponding entries in the glossary file.

Index entries appear in the Index View in much the same way as they would in a hard copy index. The major difference is that instead of a page number, the location in the text appears as a bold blue cross-reference to the associated heading or title.

Use FrameMaker index markers to create index entries for the back-of-the-book index (so called to distinguish it from the full-text index that the build tools create).

$ dollar sign
/ slash
. period
< less than
" double quote
“ left double quote
” right double quote
- hyphen
– endash
— emdash

/etc/hosts

E
/etc/hosts

/etc/ghosts
/etchosts
/etc/root

To create a link to a reference page, use the Refpage character tag. Be sure to tag the entire reference page name, including the parentheses, if there are any. The reference page name will appear in red text online and, when clicked, will launch the reference page in a shell. In print, the reference page name appears in the default font (Palatino).

IRIS InSight supports the inclusion of digital media files created from SGIVIDEO, SGIRGB, SGIAUDIO, or SGIINVENTOR. To create a link to digital media in your online document, perform the following steps:

Here is an example of an SGIINVENTOR file.

IRIS Insight supports the ability to launch a Web browser and point it to a particular Universal Resource Locator (URL) as well as to launch an application using the Launchword character tag in conjunction with Marker Type 17.