Common Desktop Environment: Help System Author's and Programmer's Guide

12 Providing Help on Help

Contents of Chapter:

Providing Help on Help

For Application Help
For Standalone Help
How Help on Help Is Found

Accessing Help on Help in an Application

To Set the helpOnHelpVolume Resource
To Provide a Using Help Command
To Display Help on Help

Writing Your Own Help on Help Volume

Required Entry Points

To Copy the Help4Help Source Files

This chapter explains how to incorporate a help volume into your application that describes the features of the Help System and how to use them. This help volume provides help on using the Help dialog boxes.

Providing Help on Help

Help on help tells users how to use the Help System. Specifically, it describes such tasks as using hyperlinks, navigating topics, using the index, and printing help topics. Normally, help on help is supplied as an individual help volume named Help4Help.

The Help4Help volume and its source files are included in the Developer's Toolkit. You can use the default volume "as is," or modify it for your application's design.

For Application Help

If you are writing application-specific help, there are two ways to ensure that your application has help on help for its own help dialogs:

Rely on the desktop's help on help volume. For example, on workstations running the desktop, the standard Help4Help volume is installed.
Supply your own help on help volume. The HelpTag source files for the Help4Help volume are provided in the /usr/dt/dthelp/help4help/C directory. A control subdirectory contains HelpTag processing files. You run HelpTag in this directory to create the run-time help file. Graphics files used in the help on help volume are stored in the control/graphics subdirectory.

For Standalone Help

If you are writing standalone help, you are probably relying on the Helpview program already being installed and ready to use. If this is the case, you don't have to worry about help on help because Helpview accesses the standard Help4Help volume by default.

How Help on Help Is Found

Each application that uses the Help System (including Helpview) has a helpOnHelpVolume resource that identifies a help volume to be accessed for help on help topics. For Helpview, this resource is set as follows:

DtHelpview*helpOnHelpVolume: Help4Help

If you provide your own help on help volume, be sure to give it a unique name so it doesn't conflict with another help on help volume that may be installed on the system.

Accessing Help on Help in an Application

Your application should do the following to support help on help:

Set the helpOnHelpVolume resource to identify the help volume you want to access.
Add a Using Help command to the application's Help menu.

To Set the helpOnHelpVolume Resource

Add a line to your application's application-defaults file like this:


App-class*helpOnHelpVolume:  volume

Where App-class is the application's class name and volume is the name of the help on help volume you want to access.

Or, within your application, set the helpOnHelpVolume resource for each help dialog you create.

Examples

This line in dthelpview's application-defaults file (DtHelpview) specifies the help on help volume:
```
DtHelpview*helpOnHelpVolume:  Help4Help
```

To specify the help on help volume when creating a help dialog, add it to the argument list passed to the create function as shown here:

ac = 0;
XtSetArg (al[ac], XmNtitle, "My Application - Help"); ac++; 
XtSetArg (al[ac], DtNhelpOnHelpVolume, "Help4Help");  ac++;
helpDialog = DtCreateHelpDialog (parent, "helpDialog", al, ac);

To Provide a Using Help Command

Add to your Help menu a button labeled Using Help. Also add the necessary activate callback to call your HelpRequestCB() function.
Add support to your HelpRequestCB() function to display help on help. Specifically:
- Create a quick help dialog.
- Set the dialog's title to Help On Help.
- Display the home topic of the help on help volume.
- Manage the quick help dialog.

Example

The following lines create a menu button labeled Using Help... that calls the HelpRequestCB() function.

/* Create the ` Using Help ...' button. */
labelStr = XmStringCreateLtoR ("Using Help ...",           XmSTRING_DEFAULT_CHARSET);
ac = 0; 
XtSetArg (al[ac], XmNlabelString, labelStr);     ac++; 
button = XmCreatePushButtonGadget (parent, "usingHelpButton", al,  ac);
   XtManageChild (button);
   XmStringFree (labelStr); 
   /* Add a callback to the button. */
   XtAddCallback (button,XmNactivateCallback,HelpRequestCB,
   USING_HELP);

USING_HELP is the client data passed to the HelpRequestCB() function when the menu button is chosen by the user. Presumably it has been defined somewhere in the application (perhaps in a Help.h file) as a unique integer:

#define USING_HELP 47

To see how the HelpRequestCB() function handles the USING_HELP case, see the example in the next section, "To Display Help on Help."

To Display Help on Help

Create a quick help dialog (or retrieve one from your cache).
Display in the dialog the home topic of your help on help volume.

Help on help can be displayed in a general help window. However, a quick help dialog is recommended because its user interface is simpler, which is less intimidating to new users who commonly need help on help.

Example

The following program segment is part of a HelpRequestCB() function. Presumably, the USING_HELP constant is passed to the function because the user chose Using Help from the application's Help menu or chose the Help button in a quick help dialog.

This example assumes that the application never creates more than one Help On Help dialog and maintains its widget ID in a variable called onHelpDialog.

case USING_HELP:
   if (onHelpDialog == (Widget)NULL)
     {
        /* Get a quick help dialog for use as the ` help on help' dialog. */
        onHelpDialog = FetchHelpDialog (True);

        if (onHelpDialog == (Widget)NULL)
          /* We didn't get a dialog! Add your error handling code here. */
     }

   /* Set the proper volume and ID to display the home topic of
      the help on help volume. Also, set the dialog's title.   */
   ac = 0;   XtSetArg (al[ac], XmNtitle,  "Help On Help");     ac++;
   XtSetArg (al[ac], XmNhelpType,   DT_HELP_TYPE_TOPIC); ac++;
   XtSetArg (al[ac], XmNhelpVolume, "Help4Help");        ac++;
   XtSetArg (al[ac], XmNlocationId, "_hometopic");       ac++;
   XtSetValues (onHelpDialog, al, ac);

   /*  If the ` help on help' dialog is already managed, it might
       be in another workspace, so unmanage it.  */
   if (XtIsManaged (onHelpDialog))
     XtUnmanageChild (onHelpDialog);

   /* Manage the ` help on help' dialog. */
   XtManageChild (onHelpDialog);

   break;

To see how the rest of the HelpRequestCB() function might be structured, refer to the example in "To Add a Help Callback."

Writing Your Own Help on Help Volume

If you need to provide your own help on help volume, you should start with the existing Help4Help volume and then make the necessary changes. All the source files used to write the Help4Help volume are provided in the /usr/dt/dthelp/help4help/C directory.

To prevent installation conflicts, name your help on help volume something other than Help4Help. Consider picking a name that is specific to your product. For example, if your application's help volume is Newapp, your help for help volume could be NewappH4H.

Required Entry Points

To ensure that context-sensitive help within a help dialog operates correctly, you must provide the following entry points (IDs) within your help on help volume. (These are already included in the Help4Help source files.)

ID: Topic Description
_hometopic: Displays an introduction to using the help system. This topic is displayed when you choose Using Help from the general help dialog's Help menu, or when you press F1 in a quick help dialog. (The ID _hometopic is created automatically by the <hometopic> element.)
_copyright: Displays the copyright and version information for the help on help volume. This topic is displayed when you choose Version from the general help dialog's Help menu. (The ID _copyright is created automatically by the <copyright> element.)
history: Displays a topic that describes how to use the History dialog. This topic is displayed when you choose Help or press F1 within the History dialog.
printing: Displays a topic describing how to use the Print dialog. This topic is displayed when you choose Help or press F1 within the Print dialog.
index-search: Displays a topic describing how to use the Index Search dialog. This topic is displayed when you choose Help or press F1 within the Index Search dialog.
volume-select: Displays a topic describing how to use the Search Volume Selection Dialog. This topic is displayed when you choose Help or press F1 within the Search Volume Selection Dialog.

To Copy the Help4Help Source Files

Copy the entire /usr/dt/dthelp/help4help/C directory to a new working directory (new-dir) using a command like this:
```
 cp -r /usr/dt/dthelp/help4help/C new-dir 
```
This creates new-dir and copies all the files and directories into it.
To permit editing the files (which are copied as read only), change the permissions using a command like this:
```
 chmod -R u+w new-dir 
```

The Help4Help volume uses these HelpTag source files:

MetaInfo
Toc
Tasks
HomeTopic
Concepts
Reference
Glossary

Also included is a control directory, where you run HelpTag to create the run-time help file. Graphics are stored in the control/graphics subdirectory.

Be sure to rename the Help4Help.htg file before running HelpTag. Your help on help volume should have a unique name to prevent conflicts with other help on help volumes.

Example

The following commands create a copy of the help on help volume and make its files writable. (Presumably the projects subdirectory already exists.)

cp -r /usr/dt/dthelp/help4help/C /users/dex/projects/NewHelp4Help chmod -R u+w /users/dex/projects/NewHelp4Help

To build a new version of the run-time help files, first ensure that the directory /usr/dt/bin is in your search path. Then, change to the new directory, rename the Help4Help.htg file, and run HelpTag:

cd /users/dex/projects/NewHelp4Help

mv Help4Help.htg NewH4H.htg dthelptag NewH4H

When the HelpTag software is done, you can display the new help on help volume using this command:

dthelpview -helpVolume NewH4H

Generated with CERN WebMaker

12 Providing Help on Help

Providing Help on Help

For Application Help

For Standalone Help

Examples

Example

Example

See Also

Example