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. 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. 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 DocBook source files for the Help4Help volume are provided in the /usr/dt/dthelp/help4help/C directory. You run DocBook in this directory to create the run-time help file. Graphics files used in the help on help volume are stored in the graphics subdirectory. 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. 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. 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. 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. 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); 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. 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.” 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, but a quick help dialog is recommended because its user interface is simpler and less intimidating to the new users who commonly need help on help. 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 . 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. 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. This ID is generated automatically for PartIntro, so do not try to specify it explicitly. _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. This ID is generated automatically for LegalNotice, so do not try to specify it explicitly. 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. 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 DocBook source files: MetaInfo.sgm Toc.sgm Tasks.sgm Home.sgm Concepts.sgm Ref.sgm Appendix.sgm Graphics are stored in the graphics subdirectory. Be sure to rename the Help4Help.sgm file before running DocBook. Your help on help volume should have a unique name to prevent conflicts with other help on help volumes. 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.sgm file, and run DocBook: cd /users/dex/projects/NewHelp4Help mv Help4Help.sgm NewH4H.sgm dtDocBook NewH4H When the DocBook software is done, you can display the new help on help volume using this command: dthelpview -helpVolume NewH4H