Chapter 12 Providing Help on Help

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.

• "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"

• "To Copy the Help4Help Source Files"

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

1. Add to your Help menu a button labeled Using Help. Also add the necessary activate callback to call your HelpRequestCB() function.

2. 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

1. Create a quick help dialog (or retrieve one from your cache).

2. 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".

See Also

• "To Create a Quick Help Dialog"

• "To Display a Help Topic"

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.)

To Copy the Help4Help Source Files

1. 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.

2. 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