This chapter explains how to use FrameMaker and the online book building 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 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.
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. And make sure 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 Conditional Text from the Special menu.
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 book-building 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 Conditional Text from the Special menu.
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. You have to tell the application developer what these labels are. 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 on 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 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.
Note that you tag your FrameMaker files in 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 it, 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 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/IRISEssentials. The helpmap file should be placed in /usr/people/debbie/books/IRISEssentials/help.
Each line of the helpmap file contains six fields. The fields are separated by semicolons; all fields should be on the same line of text (so don't press Return when you reach the end of the line, even if that makes the line wrap in the middle of a word). Here's the format to use, followed by explanations of the fields:
topic_num;book_name;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 and Shortcuts entry on the Help menu | |
| book_name | The short name 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 label 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;IRISEssentials;The Desks Overview Window;0;ov_deskoverview;Overview.DesksOverview.overview 2;IRISEssentials;Creating a Desk;0;ov_createdesk;Overview.DesksOverview 2;IRISEssentials;Switching Between Desks;0;ov_switchdesk;Overview.DesksOverview 2;IRISEssentials;Moving Windows Between Desks;0;ov_moveitems;Overview.DesksOverview 2;IRISEssentials;Copying Windows Between Desks;0;ov_copyitem;Overview.DesksOverview 2;IRISEssentials;Listing All the Windows;0;ov_listall;Overview.DesksOverview 2;IRISEssentials;Renaming a Desk;0;ov_renamedesk;Overview.DesksOverview 2;IRISEssentials;Deleting a Desk;0;ov_deletedesk;Overview.DesksOverview 2;IRISEssentials;Placing a Window in All Desks;0;ov_globaldesk;Overview.DesksOverview 2;IRISEssentials;Manipulating Windows;0;ov_manipulatewin;Overview.DesksOverview 2;IRISEssentials;Changing the Overview Display;0;ov_changeviews;Overview.DesksOverview 2;IRISEssentials;Changing the Order of Desks;1;ov2_arrangedesks;Overview.DesksOverview 2;IRISEssentials;Displaying the Names of Items in a Desk;1;ov2_displaynames;Overview.DesksOverview 2;IRISEssentials;Hints for Resizing;1;ov2_resizinghints;Overview.DesksOverview 2;IRISEssentials;Viewing Desks as Snapshots or Buttons;1;ov2_displaybutton;Overview.DesksOverview 2;IRISEssentials;Resizing Snapshots or Buttons;1;ov2_resizebutton;Overview.DesksOverview 0;IRISEssentials;The Desk Display Area;0;ovcon_display;Overview.DesksOverview.MainView.Frame.viewport.Bboard 0;IRISEssentials;The Global Desk;0;ovcon_global;Overview.DesksOverview.MainView.globalDesk 0;IRISEssentials;About Desks Overview Menus;0;ov_aboutmenus;Overview.DesksOverview.menuBar 0;IRISEssentials;The Overview Menu;0;ovcon_overmenu;Overview.DesksOverview.menuBar.Overview 0;IRISEssentials;The Desks Menu;0;ovcon_deskmenu;Overview.DesksOverview.menuBar.Desks 0;IRISEssentials;The Window Menu;0;ovcon_winmenu;Overview.DesksOverview.menuBar.Windows 0;IRISEssentials;The List All Window;0;ovcon_listwindow;Overview.WindowList_popup 3;IRISEssentials;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;IRISEssentials;Changing the Overview Display;0;ov_changeviews;Overview.DesksOverview 2;IRISEssentials;Changing the Order of Desks;1;ov2_arrangedesks;Overview.DesksOverview 2;IRISEssentials;Displaying the Names of Items in a Desk;1;ov2_displaynames;Overview.DesksOverview 2;IRISEssentials;Hints for Resizing;1;ov2_resizinghints;Overview.DesksOverview 2;IRISEssentials;Viewing Desks as Snapshots or Buttons;1;ov2_displaybutton;Overview.DesksOverview 2;IRISEssentials;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 reading a book in InSight and requests context sensitive help on the Go Back button. The widget string that gets reported is:
Insight.InsightBook.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:
Insight.InsightBook.InsightBook.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 book_name, 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 |
That's all there is to it; when the user chooses this item from the Help menu, a Web browser is launched and the URL is opened.
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 3, “Building Online Books,” for that information.
To test an online book:
Build the book:
% make book |
Change directories into the subdirectory where the book has been created:
% cd books |
You should be in a directory named something like /usr/people/debbie/books/IRISEssentials/books
List the contents of the directory:
% ls |
You should see a directory named after the book. For instance, in this example, you see a directory named IRISEssentials. This is the directory that contains the online book and help.
Copy this online book directory (IRISEssentials in the example) into /usr/share/Insight/library/companyname_bookshelves/companyname/books, where companyname is the name or abbreviation for your company (as determined in “Editing the Makefile” in Chapter 3).
Edit the associated booklist.txt file. For example, if you copied the book files into the directory /usr/share/Insight/library/Yoyo_bookshelves/Yoyo/books, edit the booklist.txt file in /usr/share/Insight/library/Yoyo_bookshelves/Yoyo.
Make sure that this file includes an entry for the book whose files you copied. If it doesn't, copy the information from the booklist.txt file in your working directory.
Copy the helpmap file into the directory /usr/share/help.
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.
Now you're ready to try using the online help that you've created.
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.IRISEssentials *helpTitle: Desks Overview |
If a user doesn't have the book installed, a message comes up saying to install the desktop_eoe.books.IRISEssentials 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="IRISEssentials" keyvalue="ov_createdesk" separator="." user_data="" title="Desks Overview" subsys="desktop_eoe.books.IRISEssentials" REQUEST =client="Overview" command="view" book="" keyvalue="DesksOverview.menuBar.Desks" separator="." user_data="" title="Desks Overview" subsys="desktop_eoe.books.IRISEssentials" 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 name 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. | |
| INFO FOR HELPMAP |
|