Programmer's Job

As a programmer, you add code into your application so that when a user requests context-sensitive help, the application displays help information that is relevant to what the application is doing at that time.

The/usr/dt/share/examples/dthelp directory contains source code for a sample program called dthelpdemo. It demonstrates how to add help dialogs to an OSF/Motif application.

Consider How Your Help Is Accessed

Providing useful information to the user requires considering the following:

• What confusing situations commonly arise? Specific help in these situations can save users lots of time.

• Why is the user asking for help now instead of earlier or later? If there are several steps in a process and the user is not at the first step, branch to information that is specific to the step being done. This is more helpful than displaying the same information at each step. If the user is at the first step, make available both detailed information about the first step and an overview of all the steps.

• Is the user requesting context-specific help or just browsing the help information? If it is context-specific, supply information that's relevant to the task now being done.

Collaborate With the Help Author

Close collaboration with the online help author is needed because the author needs to know how each context-specific topic is reached and the programmer needs to know what is explained in each context-specific topic. Without such coordination, the user may see irrelevant, ambiguous, or misleading information.

Collaboration makes the best use of the programmer's understanding of the application and the author's understanding of how to best communicate relevant information to the user.

Identify Help Entry Points

An application provides online help by establishing help entry points. Entry points are defined in the application and associated with specific help topics. Each of the ways that a user can request help--the Help key, button, or menu--represent entry points. For example, consider an application with a Print dialog box that has a Help button. The author writes a help topic that describes the contents of the dialog box and supplies you with the ID of the topic. You can then associate the ID of the help topic with the Help button using a callback routine.

Create and Manage Help Dialogs

The Help System application program interface is designed especially for use with OSF/Motif applications. Specifically, Help extends the OSF/Motif widget set by providing two new widget classes (plus convenience functions to manipulate them):

• General help dialog, which provides a help window that includes a menu bar and a topic tree, in addition to a help topic display area.

• Quick help dialog, which provides a simple help window with a topic display area and a few dialog buttons.

You can use either or both of these types of help windows within your application. Once the application is compiled (with the Help library), the help windows become part of the application.

Chapter 9, Creating and Managing Help Dialog Boxesdescribes the general help and quick help dialog boxes.

Package and Distribute Help

Your product package includes both the runtime help file (volume.sdl) and its graphics files. Additionally, you can provide a help family file that enables your volume to be viewed using the Front Panel Help Viewer.

If the help volume uses execution links, you should collaborate with the author to include the appropriate execution link resources in your application's application defaults file. Chapter 13, Preparing an Installation Package discusses which help files are delivered with your application.