This chapter provides information on how best to use FrameMaker features to produce online books, as well as pointers to related information elsewhere in the book. This chapter contains these sections:
“Tagging FrameMaker Files” provides some important rules for using paragraph and character tags in your FrameMaker files.
“Creating Online Links” explains the different types of links and how they appear and behave in the IRIS InSight viewer. This section also provides guidelines and instructions for creating links in your book.
“Creating Tables” explains how to create a table correctly using the FrameMaker tools. If you don't follow these instructions when creating a table, your table might not display properly online.
For information on creating and importing figures, see the instructions in Chapter 6, “Working With Figures.”
For instructions on creating online help and integrating it into a GUI application, see Chapter 7, “Creating Online Help.”
Before you begin, be sure you are using the standard Silicon Graphics template, so that you can be sure that you have the most current tags. The example files that come with the templates contain information on basic tagging sequences and standard uses of the various tags.
This section offers some general tips for tagging.
If you want individual characters to look a certain way, be sure to use the supplied character tags to change their look. 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 contain descriptions of the various tags and where/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 can't translate any tags they don't know about. |
Use the correct character tag for each tagged word or phrase. Prefer content-based tags (based on the kind of information being tagged) 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 other screen-capture tools to snap 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 screen captures, see Appendix B, “Capturing Images for FrameMaker Documents.”
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[1] . 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 out for when tagging:
If possible, select the word you're tagging by double-clicking on it. This keeps you from accidentally selecting extra spaces or tabs. (Unfortunately, sometimes double-clicking does not select the entire “word” you're tagging, because the word is a C expression or something else containing unusual characters.)
It's sometimes difficult to see your selection clearly in FrameMaker, so it's hard to notice if you've selected spaces or tabs in addition to words. If you've accidentally tagged a hard return or a soft return along with the preceding word, insert a space between the return and the word before it. Tag this space with the Default Paragraph Format character tag. This procedure is necessary because hard and soft returns in FrameMaker take the character tag of the character preceding them; you can't just tag the return itself to fix the problem.
Format code examples with spaces, rather than tabs. Tabs in code don't display properly online. Conversion scripts exist to convert tabs to spaces before importing code examples into FrameMaker files.
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. (All of these key sequences can also be found in the “Character Sets” appendix to the FrameMaker documentation.)
To create the copyright symbol (©), hold down <Ctrl> and press q, then release both keys, hold down <Shift>, and type a right parenthesis ( ) ).
To create a registered trademark symbol (®), hold down <Ctrl> and press q, then release both keys, hold down <Shift>, and type a left parenthesis ( ( ). Apply the Superscript character tag to the registered trademark symbol after it is inserted. If you don't know whether to use a trademark symbol or a registered-trademark symbol, consult your company's legal department.
To create a trademark symbol (™), hold down <Ctrl> and press q, then release both keys, hold down <Shift>, and press asterisk (*). This symbol is automatically superscripted; don't apply the Superscript character tag to it.
Create en dashes and em dashes according to the instructions listed here. (These key sequences can also be found in the “Character Sets” appendix to the FrameMaker documentation.) If you use any other method for creating these symbols, you might create problems when you convert your files to SGML.
To create an en dash (–), hold down <Ctrl> and press q, then release both keys, hold down <Shift>, and press p.
To create an em dash (—), hold down <Ctrl> and press q, then release both keys, hold down <Shift>, and press q.
Links are connections between items of information, whether within the same online book or between separate online documents. When the reader clicks a linked item (whether text or an icon), either the InSight viewer scrolls to the referenced material, or the material appears in a popup window (depending on what kind of material is referenced).
Links fall into two groups based on whether they are automatically generated from the structure of the document (structural links) and require no writer effort, or explicitly created by the writer during document development (writer-generated links).
A structural link is automatically created from the structure of the document during the conversion process. Lists of such links appear in the various Views in InSight. 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 place 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 5-1 summarizes the writer-generated link types:
Table 5-1. Cross-Reference Link Types
Link Type | How to Create | Appearance in InSight | Link Behavior |
|---|---|---|---|
Cross-reference to text or table within a book | Use the FrameMaker cross-reference format | Cross-reference appears in bold blue in the text | Viewer scrolls to referenced information |
Cross-reference to a figure within a book | Use the FrameMaker cross-reference format | Cross-reference appears in bold blue in the text | Figure comes up in a restricted view |
Cross-reference to another book | Use the FrameMaker cross-reference format | Cross-reference appears in red in text | Referenced information appears in new viewer |
Glossary link | Use the FrameMaker character tag, GlossaryItem; then create a glossary entry in your book's glossary file | Item is underlined | Definition appears in a pop-up window |
Index link | Use the FrameMaker index marker | Index entry appears in the Index View. Instead of a page number, location in the text appears as bold blue cross- reference to the associated heading/title | Viewer scrolls to referenced information |
Reference page link | Tag an item with the RefPage character tag | Item appears as red text | Text window appears containing indicated reference page |
Inline media | Use the InlineObj and InlineTitle paragraph tags. See “InSight Inline Object Tags” in the sample chapter file (in the samples subdirectory of the template directory) for details of syntax | Object appears in media viewer inside InSight viewer window | Media viewer controls appropriate to media type allow user to manipulate or view media |
Launch an application (including a World Wide Web browser) | Use a FrameMaker marker of type 17, as indicated in “Markers” in the sample chapter file (in the samples subdirectory of the template directory) | Either icon in margin or hot text, depending on how you set up the link | Application comes up in a new window |
It is recommended that for each chapter and appendix of your book, you begin with a list of the top-level sections in that part, making part of each item a cross-reference to the specified heading. This approach serves two purposes:
It allows the online reader to click on any item in the list and have the viewer scroll to that point in the text.
It creates cross-reference targets on all top-level headings. (Whenever you create a cross-reference, FrameMaker automatically creates a target marker at the referenced location.) These targets can be used by other writers to link to your book (see “Creating Cross-Reference Links to Other Books”).
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, 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.
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.
To create a cross-reference link to another book, either use the FrameMaker Cross-Reference tool, or use a combination of markers recognized by the translator. The former method is generally preferred. The latter is most often used when referencing a document whose source is an SGML document, rather than a FrameMaker document.
Cross-book links appear as bold red text within the online document. When the reader clicks on the link, 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:
There is no way to guarantee that any two books (even those documenting the same product) will be revised simultaneously, so it's possible that another book you link to may change after your book releases, breaking your link to the other book.
You usually don't have the same access to another book that you have to your own; in particular, you can't create a new link target in the referenced book.
The first problem is a coordination and document management issue. At present, there is no agreed-upon policy for when to create cross-book links or how to track them. 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 you want to link to. 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.
Note that you cannot currently create a cross-book link to a target book for which you do not have access to any of the source files (whether FrameMaker or SGML source).
The following procedure explains how to create a link to someone else's book using the FrameMaker cross-reference utility. Note that in order to create a cross-book link using this method, you need to have access to the FrameMaker document files that were used to create the book you're linking to. You also need to know the target book's short title—you can get that information from the target book's Makefile if you have access to that.
The general idea is that you're going to create a normal FrameMaker cross reference to the target file, but the procedure is a little bit tricky because you have to specify both the target filename and the short title of the target book. To make a cross-book link, follow these steps:
Follow your local procedures for obtaining a copy of the target book's document files and Makefile. Place the copy in a directory named short_title (the short title of the target book), or else create a symbolic link named short_title that links to the directory containing the copy of the target book. The directory or symbolic link can be anywhere in your filesystem, as long as it's called short_title.
Open up the target file in FrameMaker. When opening it, be certain to navigate to the file by way of the directory or symbolic link named short_title; if you don't do this, your link won't work.
Open your file that will contain the cross-book cross reference and place the cursor where you want the cross reference to go.
From the “Special” Menu in your document window, choose “Cross-Reference... “
From the Source Document menu in the resulting dialog, select the name of the file that contains the section you want to reference.
Choose the Source Type called X-Ref Markers.
Select the appropriate Reference Source.
Note: The X-Ref Markers list is a list of FrameMaker cross-reference targets in the target file. If the target you want to reference does not appear in the list of X-Ref Markers, then it does not have an associated cross-reference target and you can't reference it unless you can persuade the owner of the document to put the target in for you. Since you don't (or shouldn't) have permission to write to someone else's book, you can't create it yourself. Select a cross-reference format.
Click the Insert button.
Remove the target document from your system using your usual procedures.
Use the method described in this section to create a cross-book link to another book using the FrameMaker Marker tool. Note that you can only use this procedure with target books for which you have SGML source files. It's a somewhat complicated procedure, so if you have access to the target book's FrameMaker document files, you may prefer to use the procedure in “Using the Cross-Reference Utility” earlier in this chapter.
To create a cross-book link using markers:
Open the FrameMaker chapter in your book and insert the cursor at the beginning of the text where the cross-book link marker will be placed.
Go to the FrameMaker menu bar and select Marker from the Special menu.
In the Marker dialog, select Type 18 from the Marker Type pop-up menu.
In the Marker Text box, enter information about the cross-book link using this syntax:
target_short_title<Space>unique_id
where target_short_title is the short title of the target book, and unique_id is the identifying number associated with the target element in the target book. To identify the correct unique_id, look in the SGML file for the target book; find the target element and look for an <XREFTARGET> tag nearby. For instance, in the following example the unique_id for the TITLE element is 57332:
<SECTION2 LBL="" HELPID = ""><TITLE>Supplementary Reading<XREFTARGET ID="57332"></TITLE><PARAGRAPH>Refer to these documents to supplement the information in this guide:</PARAGRAPH>
Press the New Marker button to create a new marker containing the information you've specified.
Move the cursor from the beginning of the text where the cross-book link will be placed to the end of the text.
From the Marker dialog box, select Type 19 from Marker Type. Leave the Marker Text box empty.
Press the New Marker button to create a new empty marker of type 19.
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 character tags. |
Glossary links appear as underlined words in the text. When the reader clicks on the word, the definition appears in a restricted view. The link itself is either to the Silicon Graphics global glossary common to all books, or to a local glossary specific to the book. 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 underlined 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.
To create a local glossary tailored specifically to your book, use the glossary 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).
Online books require certain limitations in index entries:
Index entries can be no more than three levels deep.
You can't put an index marker in a table footnote.
A character format in an index entry can't cross a semicolon or colon boundary; for instance, <Italics>entry:subentry<Default Para Font> won't work the way you might expect it to. Instead, you'd have to use <Italics>entry<Default Para Font>:<Italics>subentry<Default Para Font>.
Special characters that result in entity references (such as special characters for foreign languages) may not sort correctly in the online index.
Sorting ignores these characters if they appear as the first character in an index entry: “, <, $, ., /, and <space>.
Use the FrameMaker table tools to create tables. Use one of the FrameMaker table formats labelled TableXcol. If you try to create a table some other way—by using tabs, for example—it won't display properly online.
You can include footnotes in a table, if you use the FrameMaker paragraph tag TableFootnote rather than the tag Footnote.