Providing custom Windows Help

  • Article

Applies To: Windows Server 2003, Windows Server 2003 R2, Windows Server 2003 with SP1, Windows Server 2003 with SP2

Providing custom Windows Help

Using the CMAK wizard, you can customize the Connection Manager Help, which consists of definition Help and troubleshooting Help:

  • Definition Help provides a brief description of each interface item. This type of Help topic appears in a small pop-up window. Users display topics by right-clicking an interface item and then clicking What's This? in the pop-up menu that appears. In all dialog boxes except the logon dialog box, users can also display definition Help by clicking the question-mark icon in the title bar and then clicking an interface item.

  • Troubleshooting Help provides a structured approach to diagnosing and resolving many common connection problems. Users start the Troubleshooting Help for Connection Manager by clicking Help in the logon dialog box. The question-and-answer format guides users through the process of determining the most likely causes of the problem. The troubleshooter then provides possible solutions, based on the user's feedback.

Both the definition and troubleshooting Help files are compiled into a single .hlp file. This compiled file is incorporated into the service profile for distribution to users. The default Help is Cmmgr32.hlp. If you do not want to use the default Help, you can use the CMAK wizard to specify custom Help to replace the default in your service profile.

Note

  • There are two areas of Help information that you cannot customize in the definition Help. The first non-customizable Help is for the Dialing Properties dialog box, which users see when they click the Dialing Rules button on the General tab of the Properties dialog box. This dialog box, along with its associated Help, is a component of the Telephony Application Programming Interface (TAPI) and, although it is incorporated as a part of Connection Manager, it cannot be modified. The second area of non-customizable Help is for the Advanced tab. The contents of this tab is a component of the operating system, and, although it is incorporated as part of Connection Manager, it cannot be modified.

How to customize the default Help files

If you want to include custom Windows Help, you must prepare your files before you run the CMAK wizard. Your CMAK folder contains all the source files for the default Help. To create custom Help, you need to copy the default Help source files, including the project [.hpj] file, rename them, edit the renamed files, and recompile them. Putting them in a separate folder helps prevent the original files from being accidentally altered. Following is information for creating custom Help, including a description of all of the source files and the tools required to modify these source files. (A basic understanding of Windows Help systems and user-education concepts is assumed.)

Notes

  • Be careful when modifying the Help files. Troubleshooting any changes you make to these files may be difficult. Avoid changing Windows Help file footnotes. Do not change any of the topic IDs (the number sign [#] footnotes).

  • When specifying your custom Help file in the CMAK wizard, browse to it. If you type the name, no validation is done on the file name (including the file extension).

  • Be sure to test the Help files on all target platforms before delivering your service profile to your users. Test Help by starting Connection Manager and using both the definition Help and troubleshooting Help. Testing Help by opening the .hlp file outside of Connection Manager does not allow verification of functionality.

Source files

The following files are included with the Connection Manager Administration Kit. By copying and editing these source files, compiling your customized project (.hpj) file, and then specifying the name of your compiled custom Help file in the CMAK wizard, you can provide custom Help to your users.

  • Cmmgr32.hlp (the default compiled Help file) is installed on your hard disk in the %windir%\system32 folder.

  • The following online Help components are installed on your hard disk in the \Program Files\CMAK\Support\CMHelp folder.

    • Cmmgr32.hpj (the Help project file)

    • Cmctx32.rtf (the text document source for definition Help)

    • Cmtrb32.rtf (the text document source for troubleshooting Help)

    • Cmmgr32.h (the header file containing definition Help IDs)

Note

  • Graphics (such as bullets) and the template file (What7.dot) are not included, so you should create these files as appropriate to the look you want to provide in your Help.

You must have all of these files if you want to customize and rebuild the online Help system. Suggestions for customizing entries in each file are discussed later in this section.

Important

  • To customize the Help files for a service profile, copy the default Help files (except for the cmmgr32.hlp file), rename them, and then edit only the renamed files. Do not edit the original default files. When you rename the files, be sure to update the names referenced in the .hpj file, including the name of the .hlp file. If you customize Help but do not rename the .hlp file, the CMAK wizard could accidentally incorporate both the default and custom files when building the service profile.

Note

  • In addition to Help files, you can provide custom readme and procedural documentation to your users. For more information on the additional documentation that you can customize for your users, see Providing user documentation.

Required tools

To customize Help files, you need both of the following:

  • A word-processing program, such as Microsoft Word, that reads and writes .rtf files.

  • A 32-bit Help compiler, such as Help Workshop version 4.01.

Note

  • You can obtain the Help compiler (Hcw.exe) and associated files by downloading both the Microsoft Platform SDK build environment and the additional SDK components (tools) from the Microsoft SDKs at the Microsoft Developer Network (MSDN) on the Microsoft Web site. However, only limited documentation on how to create and edit Help is available in the SDK.

What should be customized?

The most commonly customized Help information is that contained in the .rtf files, including the text for both definition and troubleshooting Help.

Customization suggestions for definition Help

The text for definition Help is in the Cmctx32.rtf file. In the following list of customization suggestions, each topic is referred to by its topic ID (the # footnote).

Help topic ID Customization information

IDH_LOGON_SVCMSG

You can use this topic to provide definition Help for the support text in the logon dialog box. This topic is available to your users only if you specify support information when you run the CMAK wizard. The default text for this message is "No Help topic is associated with this item." You can modify this text to provide assistance for the support information specified for your users. For example, if you provide a phone number for customer support in the logon dialog box, you might want to provide a description of your customer support service in this topic.

IDH_PHONEBOOK_SERVICETYP

In the Phone Book dialog box, this topic provides Help for the Service Type list. You can customize this topic to reflect the service types that you support and provide a brief description of each.

IDH_PHONEBOOK_ACCESSNUMS and IDH_PHONEBOOK_MORE

In the Phone Book dialog box, these topics provide Help for the Access Numbers and More Access Numbers lists. You can edit the text to change it or add information about the available numbers, such as which numbers incur user fees and which do not. The default text specifies that additional charges are incurred for using these numbers.

IDH_PHONEBOOK_SVCMSG

In the Phone Book dialog box, this topic provides Help for the phone book customer service message area (next to the More access numbers box). This message appears only if alternate access numbers are available for the selected geographic area. You can use this topic to provide additional customer service information about the numbers that you make available in the More access numbers box.

Throughout the Cmctx32.rtf file, you might want to convert the term "your service" to the name of your service. For example, IDH_LOGON_NAME contains: "The name you use to log on to your service." Changing "your service" to "Awesome Computers" (the name of the fictitious company used in this documentation) would change this information to: "The name you use to log on to Awesome Computers."

Customization suggestions for troubleshooting Help

Text for troubleshooting Help is in the Cmtrb32.rtf file. The following list of customization suggestions includes reference topics by title and by topic ID (the # footnote).

Troubleshooter topic ID Customization information

ICM_TRB (Logon troubleshooter)

This topic is the starting point for users to identify possible problems. If you have specific problems that you want to address, you can add your own paths to the troubleshooter, starting at this point or any other point. You can add topics to cover as many situations as you want.

ICM_TRB_CUSTSUP_NUMS (Contact customer support)

This topic provides users with customer support information. Add your specific customer support phone numbers, hours of operation, and any other useful information. Users display this topic from other topics that recommend contacting customer support.

ICM_TRB_GIVEUP and ICM_TRB_GIVEUP_PHONE (Next steps)

One of these two topics appears at the end of all troubleshooting paths. You can provide additional instructions for users who try all troubleshooting possibilities and still are not able to connect to your service.

As with the definition Help, you might want to change the term "your service" to the name of your service, wherever it appears in this file.

Customizing and compiling the project file

If you customize the .rtf files, you must customize the project (.hpj) file (using Help Workshop 4.01 or another appropriate Help editor) to include the names of these custom .rtf files. You can also change other project information in the .hpj file. For example, if you do not want to use "Troubleshooting Help for Connection Manager" in the title bar of the Help screens, you can change the title in the .hpj file by changing "TITLE" under [Options] and "proc4" under [Windows].

After you have finished editing the .hpj and .rtf files, you must compile the .hpj file to create the .hlp file. When you run the CMAK wizard to create your service profile, specify the name of your custom .hlp file in the wizard.

Note

  • The .h (mapping) file contains the topic IDs for the definition Help. Editing this file may prevent Connection Manager from displaying the appropriate definition Help.