This chapter explains how to use FrameMaker and the online bookbuilding process to create online help for an application. The same source file is used for online books and SGI Help; when you're writing a book, you can mark sections of it to be used by the help system.
The following sections are included in this chapter:
The SGI Help system relies upon several main components:
A FrameMaker file containing special labels that mark the sections you want to use as help topics. When you build the online book, these labels become a part of the SGML file.
A helpmap file that provides a mapping between the help topics in the online book and the Help menu in the application.
A help server that handles communication between the application and the helpmap file.
Figure 7-1 shows the flow of how an application accesses its help information.
Depending on its complexity, an application can include a help menu as well as a help button (context-sensitive). Widget strings are used to tie the application to its helpmap .
The helpmap is the key to making help work correctly. This ASCII text file provides a mapping between the help menu in the application and the help topics in the online book. Each helpmap line contains six fields that define the mapping. The third field of the helpmap corresponds to one of the application's Help pull-down menu items and to a help topic in the FrameMaker source used to create the online document.
Any full section of a book—from one heading to the next heading of the same or higher level—can be used as a help topic. To mark it as such, place an empty paragraph above the chosen section's heading (any paragraph tagged Heading1, Heading2, or Heading3); then, in this new paragraph, enter a unique one-word label to identify the section. Tag the label with the HelpTopic paragraph tag; then apply the OnlineOnly conditional text tag to it. Here's a more detailed set of instructions:
Place the cursor on a blank line above the heading of the section you want to use as a help topic.
If you place it above a Heading1, the help topic will include any Heading2 and Heading3 subsections that the marked section contains. If you place it above a Heading2, the help topic will include any Heading3 subsections that the marked section contains.
Type a unique label for that topic. Later, you'll be entering this label into the helpmap file, thereby tying the help topic to the application.
Do not put spaces or hyphens in the label. Ensure that you choose a name that another writer isn't likely to use. For example, you might want to include the application name, or an abbreviation of the name, followed by some other text.
Tag the paragraph with the HelpTopic paragraph tag.
Choose Special > Conditional Text.
Select the entire paragraph containing the new label; then choose OnlineOnly from the Conditional Text dialog. Click the left-pointing arrow button in the dialog to move “OnlineOnly” into the “In:” column; then click the Apply button. Close the Conditional Text dialog.
Parts of sections of a book can also be used as help topics. Note that such pieces must be complete SGML structural units, such as paragraphs or tables or figures; you can't use part of a paragraph, or part of a table, or part of a figure, as a help topic. In fact, if you use a table you must also use the entire paragraph that the table anchor appears in.
To create a help topic from a piece of a section, follow these steps:
Place the cursor on a blank line above the first paragraph of the subsection you want to use as a help topic.
Type a unique label for that topic, then a colon, then a title for the topic. The label follows the same rules as for HelpTopic, above; the title is necessary since there's no section title to use for the help card title. The label and title are eventually put into the helpmap file by the bookbuilding tools, thereby tying the help topic to the application.
Remember not to put spaces or hyphens in the label, and to choose a name that another writer isn't likely to use.
Tag the paragraph with the HelpSubTopic paragraph tag.
Choose Special > Conditional Text.
Select the entire paragraph containing the new label; then choose OnlineOnly from the Conditional Text dialog. Click the left-pointing arrow button in the dialog to move “OnlineOnly” into the “In:” column; then click the Apply button. Leave the Conditional Text dialog open.
Now select all of the text that you wish to appear in the help topic. Choose HelpSubTopic from the Conditional Text dialog. Click the left-pointing arrow button in the dialog to move “HelpSubTopic” into the “In:” column; then click the Apply button. Close the Conditional Text dialog.
The number of help labels you need to include depends on the complexity of the application and the method by which people will access help. There are two common approaches to online help: a Help button or a Help menu.
If the application has a Help button, add a label to your book above the heading of the section that you want to appear when the user clicks the Help button. If the application allows you to open several windows, each with its own Help button and help card, put a different label above each topic that should come up in response to a Help button. Provide the help labels to the application developer so they can be incorporated into the application's code. The application passes this info to the help server when the user clicks a Help button.
If the application has a Help menu, add a label to your book above each section that should appear in the Help menu or should appear when a user requests context sensitive help for a particular area of the window. If the application is based on the IRIS ViewKit interface toolkit, you do not have to pass this information on to the developer. If it is not ViewKit-based, you need to provide the developer with a list of the topics for the menu and all of the associated labels. The application developer will then incorporate these labels into the application's code.
Note: Tag your FrameMaker files the same way regardless of whether you're creating context-sensitive help or menu-based help. The difference between the two is indicated in the helpmap file.
The helpmap file acts as the glue that binds the help topics to the application. In this ASCII text file, you list the topics that you've designated as “help” in your FrameMaker files, and you specify when the topic should appear—when a user chooses a particular item from the Help menu, for example, or when the user clicks in a certain place in the window.
The name and location of the helpmap file are important. If the application is based on IRIS ViewKit, name the file AppName.helpmap. The AppName should be the same as the name of the application's defaults file in /usr/lib/X11/app-defaults (usually a capitalized form of the name of the executable). If the application isn't ViewKit-based, the writer and the developer need to agree on a name to use for the helpmap file.
Place the file in your working directory, in a subdirectory called help. For example, suppose your book directory is /usr/people/debbie/books/Desktop_UG. The helpmap file should be placed in /usr/people/debbie/books/Desktop_UG/help.
Each line of the helpmap file contains six fields separated by semicolons. All fields must be in the same line of text (so don't press Enter when you reach the end of the line, even if the line wraps in your ASCII test editor). Here's the format to use, followed by explanations of the fields:
topic_num;short_title;title_str;level_id;help_key;widget_string |
| topic_num | A number that indicates what type of help topic it is: 0: Not on a help menu—either context sensitive or tied to a Help button 1: Overview topic on the Help menu 2: Task-oriented entry that shows up on the Help menu 3: “Keys & Shortcuts” entry on the Help menu | |
| book_name | The short title of the book that contains the help topic. | |
| title_str | The name of the topic. This determines what appears on the Help menu and in the index. This name can be different from the HeadingX title that appears in the FrameMaker file. Be sure to fill in this field even if the topic is one that doesn't appear on a Help menu. | |
| level_id | A number indicating whether the item is a top-level menu entry or on a rollover menu. Use 0 if the item is a top-level entry, or isn't on a menu (as with button or context-sensitive help). | |
| help_key | The label in your FrameMaker file that is associated with this help topic. | |
| widget_string | Specific information that identifies the application, or portion of the application, to which the help topic belongs. For the “Overview” menu entry, use AppName.windowName.overview If the topic is tied to a help button, use AppName.windowname For a list of “Keys & Shortcuts,” use AppName.windowName.keys If the topic is tied to a portion of the window (as is true for context sensitive help), you need the fully qualified widget string. You can include several different widget strings if you want to use the same topic for different regions of the window. See “Creating Context Sensitive Help” and “Setting Up the Fallback Mechanism for Context Sensitive Help”. |
This section contains a sample helpmap file.
1;Desktop_UG;The Desks Overview Window;0;ov_deskoverview;Overview.DesksOverview.overview 2;Desktop_UG;Creating a Desk;0;ov_createdesk;Overview.DesksOverview 2;Desktop_UG;Switching Between Desks;0;ov_switchdesk;Overview.DesksOverview 2;Desktop_UG;Moving Windows Between Desks;0;ov_moveitems;Overview.DesksOverview 2;Desktop_UG;Copying Windows Between Desks;0;ov_copyitem;Overview.DesksOverview 2;Desktop_UG;Listing All the Windows;0;ov_listall;Overview.DesksOverview 2;Desktop_UG;Renaming a Desk;0;ov_renamedesk;Overview.DesksOverview 2;Desktop_UG;Deleting a Desk;0;ov_deletedesk;Overview.DesksOverview 2;Desktop_UG;Placing a Window in All Desks;0;ov_globaldesk;Overview.DesksOverview 2;Desktop_UG;Manipulating Windows;0;ov_manipulatewin;Overview.DesksOverview 2;Desktop_UG;Changing the Overview Display;0;ov_changeviews;Overview.DesksOverview 2;Desktop_UG;Changing the Order of Desks;1;ov2_arrangedesks;Overview.DesksOverview 2;Desktop_UG;Displaying the Names of Items in a Desk;1;ov2_displaynames;Overview.DesksOverview 2;Desktop_UG;Hints for Resizing;1;ov2_resizinghints;Overview.DesksOverview 2;Desktop_UG;Viewing Desks as Snapshots or Buttons;1;ov2_displaybutton;Overview.DesksOverview 2;Desktop_UG;Resizing Snapshots or Buttons;1;ov2_resizebutton;Overview.DesksOverview 0;Desktop_UG;The Desk Display Area;0;ovcon_display;Overview.DesksOverview.MainView.Frame.viewport.Bboard 0;Desktop_UG;The Global Desk;0;ovcon_global;Overview.DesksOverview.MainView.globalDesk 0;Desktop_UG;About Desks Overview Menus;0;ov_aboutmenus;Overview.DesksOverview.menuBar 0;Desktop_UG;The Overview Menu;0;ovcon_overmenu;Overview.DesksOverview.menuBar.Overview 0;Desktop_UG;The Desks Menu;0;ovcon_deskmenu;Overview.DesksOverview.menuBar.Desks 0;Desktop_UG;The Window Menu;0;ovcon_winmenu;Overview.DesksOverview.menuBar.Windows 0;Desktop_UG;The List All Window;0;ovcon_listwindow;Overview.WindowList_popup 3;Desktop_UG;Keys and Shortcuts;0;ov_keyshortcuts;Overview.DesksOverview.keys |
You can create a rollover menu for a help topic. For example, suppose a Help menu includes the topic “Changing the Overview Display” and you want to include information on various ways in which you can change the display. You set this up through the helpmap file by using a different level_id for the rollover menu items. Note the level_id of 0 in the first entry and the level_id of 1 in subsequent entries:
2;Desktop_UG;Changing the Overview Display;0;ov_changeviews;Overview.DesksOverview 2;Desktop_UG;Changing the Order of Desks;1;ov2_arrangedesks;Overview.DesksOverview 2;Desktop_UG;Displaying the Names of Items;1;ov2_displaynames;Overview.DesksOverview 2;Desktop_UG;Hints for Resizing;1;ov2_resizinghints;Overview.DesksOverview 2;Desktop_UG;Viewing Desks as Snapshots or Buttons;1;ov2_displaybutton;Overview.DesksOverview 2;Desktop_UG;Resizing Snapshots or Buttons;1;ov2_resizebutton;Overview.DesksOverview |
If an application has a Help menu, you can create context sensitive help. Context sensitive help allows you to provide information about specific areas of controls on a window. For example, the InPerson desktop conferencing software has an area into which you can drop icons that represent the people you want to call. This is called a drop pocket. Context sensitive help might explain what the drop pocket is and how to use it.
To create context sensitive help, you must identify the area of the window to which you want to link the help topic. You do so by giving the full name of the widget in that area of the window. (A widget, in X parlance, is an element of a user interface—a button, scroll bar, text area, or other interface item.) The widget's full name includes the name of each widget in the hierarchy that contains it, from the entire window down to the specific area in question. For example, here is the widget name for the drop pocket on the InPerson window:
InPerson.callWindow.Form.GroupPanel.scroll.iconForm.Xdraw |
If the application is ViewKit-based, and has been linked to the help server, you can get the widget name relatively easily:
Open a shell window.
Kill the help server and restart it in debugging mode by typing:
% /etc/killall sgihelp % sgihelp -debug
Choose “Click for Help” from the Help menu, then click on the region for which you want to provide context sensitive help. The widget string appears in the shell window. Below is an example of what you might see in the shell window:
% sgihelp -debug REQUEST =client="InPerson" command="view" book="" keyvalue="callWindow.Form.GroupPanel.scroll.iconForm.Xdraw" separator="." user_data="" title="InPerson" subsys="InPerson.books.InPerson_AG and InPerson.books.InPerson_UG" INFO FOR HELPMAP =InPerson.callWindow.Form.GroupPanel.scroll.iconForm.Xdraw
The INFO FOR HELPMAP field contains the widget name to use in your helpmap.
You might not provide context sensitive help for every button or set of controls on a window. However, you need to make sure that something reasonable appears, no matter where a user clicks. For example, if a user clicks on an area for which there isn't any specific context sensitive help, you might display the Overview help card.
Here's how it works. When a user requests context sensitive help, the help server looks to see if that widget name appears in the helpmap file. If not, it drops the last item in the widget name and tries again to find a match. It continues doing this until it finds a match. For example, suppose a user is browsing a book and requests context sensitive help on the Go Back button. The widget string that gets reported is:
MyApp.IvForm.ivPane2.commandArea.DocCmdAreaRC.goBack |
Suppose help is not available for the Go Back button. The help server continues searching and finds a match with this portion of the widget string:
MyApp.IvForm.ivPane2 |
Here's a helpmap entry which causes the Overview card to display under those circumstances:
1;InsightHelp;Overview;0;inshelp_overview;Insight.overview;Insight.InsightBook.InsightBook.IvForm.ivPane2 |
You can include a link to one or more World Wide Web pages in your help menu if you so desire. This feature can be useful, for instance, if you want to provide release notes, frequently asked questions lists, and other such time-sensitive information by way of the Web.
Including a URL in a help menu is much like placing any other item in that menu; it merely requires a line in the helpmap. (Note, though, that not all customers have access to the Web, so you shouldn't put any critical information on a web page.) The format is identical to other lines in the helpmap file. For topic_num and level_id, use 0 even though the item will appear on the Help menu. For short_title, give the complete URL. For title_str, give the entry you want to appear in the Help menu; you should also indicate somehow to the user that this item launches a web browser. (You can, for instance, use the word “(web)” in parentheses at the end of the title_str.) Leave the help_key field blank; there is no help topic in the book that this item corresponds to. And finally, the widget_string should be the name of the application's top-level widget. For example:
0;HREF=http://dyne.yoyo.com/dougom/Tutorial.html;examples (Web):;0; ;Cvpav.cvpav |
This section outlines the process of building and testing online help. Once you've checked in the files and the application has been built, you can install the product and test the help. This section explains how to test the help before the product is rebuilt. It does not provide details on the make book command or the setup that's required to build an online book. See Chapter 5, “Building Online Books”, for that information.
To test an online book with access to the application:
Install the application and book using the instructions in “Viewing an Installed Book ” in Chapter 5.
If you're already running the help system, kill it by typing:
% /etc/killall sgihelp
It will automatically restart when you next request help.
If you're running the application whose online help you want to test, quit out of the application and re-launch it.
If the application has a Help menu, select the “Overview” entry to launch SGIHelp. See Figure 7-2. If the application has a Help button, click it to launch SGIHelp.
Study the information in right viewer pane to ensure that the appropriate help card information for first helpkey is shown. (The first helpkey is usually associated with an overview of the application.) Figure 7-3 is an example of the help for the Apanel application.
Choose the next item from the Help menu and ensure that the correct help card appears in the right pane.
Continue choosing each item in the Help menu and ensure that the correct help cards appear in the right pane.
Test the context sensitive help by choosing Help > Click for Help and position and click the question-mark cursor over a particular location of the application's GUI (scrollbar, menu bar, button, etc.) that you know to have associated help information.
Repeat step 8 until you have tested all the context sensitive help.
If your system “beeps” and a different help card doesn't appear in the right viewer pane or if a dialog box appears, then either
the corresponding line of the helpmap needs to be fixed.
the help topic is missing from the online book (and is probably missing or mis-tagged in the FrameMaker file).
See “Troubleshooting” for more information.
To test an online help book when the application is not available, do the following:
Make sure your helpmap file is installed in /usr/share/help. For example,
/usr/share/help/App.name.helpmap
In a shell, type:
% sgihelp -app App.name
Now double-click on items in the left viewer pane (the Table of Contents) and ensure that the correct help card(s) appear in the right pane.
You can also invoke a specific key using the shell (command-line). For example:
% sgihelp -app App.name -k helpkey_name
The viewer should update and display the appropriate help card; and highlight the entry in the left pane (if it is a part of the Table of Contents).
If a user hasn't installed the correct online book, an error message will be seen when online help is accessed. To make this error message as useful as possible, you need to ask the application engineers to include two extra lines in the application's defaults file. Here's an example of what appears in the app-defaults file for the Desks Overview tool:
*helpSubSys: desktop_eoe.books.Desktop_UG *helpTitle: Desks Overview |
If a user doesn't have the book installed, a message comes up saying to install the desktop_eoe.books.Desktop_UG subsystem.
When you begin testing the online help, you may see one of several problems:
The help server says that it's unable to find help on a particular topic. See “No Help Available”.
The wrong section appears when you choose a help topic. See “The Wrong Help Topic Appears”.
If you get a message saying something like “Sorry, no help available on that topic”:
Check to make sure the book is installed. Look in all the relevant subdirectories of your company's bookshelves directory under /usr/share/Insight/library, including any Help subdirectories.
Check the generated file booklist.txt in the relevant subdirectory of your company's bookshelves directory under /usr/share/Insight/library. Make sure it has an entry for the book, and that the book's title is spelled correctly.
Make sure the helpmap file is in /usr/share/help.
If the wrong section of the book appears when you click the Help button or choose a topic, you probably have a problem in the FrameMaker file, or a mismatch between the application, the FrameMaker file, and the helpmap file.
In the FrameMaker file:
Make sure that the paragraph with the help label is tagged HelpTopic.
Make sure that the heading below the HelpTopic is not accidentally tagged with the HelpTopic paragraph tag.
Make sure the text in the HelpTopic paragraph is OnlineOnly conditional text.
To check for a mismatch between the FrameMaker file, the helpmap file, and the application:
Stop the help server and restart it by typing the following:
% /etc/killall sgihelp % sgihelp -debug
Click on a Help button or choose a topic from a Help menu. A bunch of text appears in the shell window. Here are two examples:
REQUEST =client="Overview" command="view" book="Desktop_UG" keyvalue="ov_createdesk" separator="." user_data="" title="Desks Overview" subsys="desktop_eoe.books.Desktop_UG" REQUEST =client="Overview" command="view" book="" keyvalue="DesksOverview.menuBar.Desks" separator="." user_data="" title="Desks Overview" subsys="desktop_eoe.books.Desktop_UG" INFO FOR HELPMAP =Overview.DesksOverview.menuBar.Desks
| client | The name of the application. Make sure the name of the helpmap file and the last entry in the file match this. | |
| book | The short title of the book that contains the help content. Make sure the spelling in the helpmap file and booklist.txt file match this. | |
| keyvalue | One of two pieces of information: either the HelpTopic tag in your FrameMaker file and helpmap file or a portion of the widget string for the context sensitive help.If it's the label or tag you've used to mark the help topic, check the helpmap file to make sure the spelling, capitalization, and punctuation match. | |
| INFO FOR HELPMAP | The widget string to be used for context sensitive help. Make sure this matches the widget string you've placed in the helpmap file. |