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

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

  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

  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

  Generated with CERN WebMaker