Copyright: Microsoft Developer Studio Extension Help


Using Your Own Help Files to Get F1 Help
Using WinHelp Files for F1 Help

You can get F1 source-file help from WinHelp rather than InfoViewer by choosing the Use External Help file command on the Help menu. When the command is checked, all source-file F1 help requests are sent to a specified WinHelp file. By default, this file is Microsoft Developer Studio Extension Help, EXTHELP.HLP.

  To toggle the Use Extension Help command, choose Use Extension Help from the Help menu.

When toggled on, WinHelp looks in the index for the specified help file to find a match for the F1 request. WinHelp displays a topic if it finds a match. WinHelp opens the Index tab to the closest keyword if there is no match.

You can combine other WinHelp file indexes with the EXTHELP.HLP index or change the default to another WinHelp file. The advantage of combining indexes with the EXTHELP.HLP index is that third-party set-up programs will try to combine indexes with EXTHELP.HLP when combining indexes. F1 help will look in the combined index for a match. But the easiest way to get F1 help from your own help file is to change the default to another file.

To take advantage of the Use Extension Help feature, you can:

1. Edit your registry to change the default for extension help. Take me there.

2. Combine your help index with the index for the default EXTHELP.HLP. EXTHELP.HLP is setup in the product \HELP directory. Take me there.

3. Optionally, you can include your Contents file (.CNT) with the Extension Help Contents file (EXTHELP.CNT). Take me there.

Note  You must use help files compiled with HC31.EXE or greater to combine indexes or contents files.

Notes on Using Extension Help

1. If you have combined the index of a help file compiled with HC31.EXE, the Winhelp 4.0 Help Topics dialog opens without a Contents tab. A Contents tab is not needed for F1 help. However, you can create a Contents file for any Windows 3.1 or NT 3.5 or earlier help file, then combine it with EXTHELP.CNT. See your Winhelp 4.0 SDK documentation for details on creating a Contents file.

2. When Developer Studio parses a keyword in a source file, it looks for an exact match with a keyword in the Winhelp file index. If Winhelp cannot match the keyword exactly, it opens the Winhelp 4.0 Index to the closest match. The Winhelp index is created from K footnotes in .RTF topics. For the best results, include the bare keyword in the topic K footnote, i.e.,”MyMember” rather than “The MyMember Function.” When a parsed keyword is matched exactly in the help index, the help topic window opens rather than the Index.

3. When the Use Extension Help command is toggled on, you can’t get help from Books Online. This means, for example, that F1 help on errors searches external help. Toggle off the Use Extension Help command to search Books Online.

Tip  You can assign a shortcut key to this command. The command is listed as HelpUseExtensionHelp under the Help category in the Keyboard Tab on the Customize dialog.

4. Third-party setup programs can automatically combine indexes and content files with the default EXTHELP files.

1. 	Visual C++ will automatically restore registry information to the default values if the DEVELOPER key or HELP key is deleted. Repeat the steps to edit the registry to change the default help file if needed.

1. 	When the Use Extension Help command is checked, choosing the Contents or Search commands on the Help menu opens the specified WinHelp file. To open or search the current InfoViewer title, uncheck the Use Extension Help command.

Editing the Registry to Change the Default Help File

  To edit your registry

1. Open the Registry Editor to the EXTENSION key under:

HKEY_CURRENT_USER/SOFTWARE/MICROSOFT/DEVELOPER/HELP

There are three values under EXTENSION key:

Enable  Adds the Use Extension Help command to the Help menu. The default value is 1.

Filename  Lists the path to the EXTHELP help file. The default value is

..\MSDEV\HELP\EXTHELP.HLP

State  Holds a value to keeps track whether Use Extension Help is on or off. The default value is 0. This value is changed by Microsoft Developer Studio.

You’ll only need to edit the Filename value.

3. Double-click the Filename value. Edit the path and filename.

4. Restart Developer Studio to read the new Registry value.

Tip  You can assign an access key to this command. The command is listed as HelpUseExtensionHelp under the Help category in the Keyboard Tab on the Customize dialog.

Combining Another Help Index with the Extension Help Index

You can combine help file indexes by adding an :Index command to a base contents (.CNT) file. The :Index command references the help index you want to combine. When the base help file opens, WinHelp automatically merges the files into a single index. Extension Help searches that single index for help keywords.

  To combine your index

1. Open ..\MSDEV\HELP\EXTHELP.CNT in a text editor.

2. Add the :Index command to specify the name of your Help file. The :Index command follows the :Title command that identifies Extension help. The :Index command takes two parameters:

help_title       Specifies the title of the Help file (to display in the Topics Found dialog box).

HLP-filename  Specifies the name of a Help (.HLP) file.

Example:

:Base EXTHELP.HLP

:Title Microsoft Developer Studio Extension Help

:Index Your Own Help File=myhelp.hlp  ;my own help file

3. Save your changes and open Extension Help to create a combined index.

Use a separate :Index command for each Help file whose keywords you want included in the index. You can include as many Help files as you want.

Use a space before an equal sign (=) that indicates a Help file or a semicolon (;) that indicates a comment. Use a backslash (\) before an equal sign or semicolon that is to be treated literally.

This command is valid only in a Contents file.

Including Another Contents File with the Extension Help Contents File

The :Include command in a Contents file specifies the name of another Contents file to be included in the current Contents file. When a Help file opens with an :Include command as part of its Contents file, the contents of the other file is listed in the Contents tab of the Help Topics dialog. You may want this for navigational purposes; it is unnecessary for F1 help support.

  To include your contents file

1. Open ..\MSDEV\HELP\EXTHELP.CNT in a text editor.

2. Add the :Include command to specify the name of your Help file. This command can be placed anywhere in a Contents file.

The :Include command takes a single parameter:

cnt-filename	Specifies the name of the Contents file that you want to insert in the current Contents file.

Example:

:Include myfile.cnt   ;this is my own contents file

3. Save your changes and open Extension Help to include your contents file.

You can include as many Contents files as you want.

If WinHelp cannot find the file specified with the :Include command when the user opens the Help file, no error message is displayed to the user. If WinHelp does find the specified file, the topics in the included Contents file are added to the Contents tab at the position where the :Include command exists in the Contents file.

The :Include command is used typically to merge Contents files that are being managed by different authors.

If the parent Contents file has a :Base command that specifies a default window and you want the included Contents file to have the same default window, the included Contents file must also contain a :Base command specifying the same window.

Use a space before a semicolon (;) that indicates a comment. Use a backslash (\) before a semicolon or equal sign that is to be treated literally.

The :Include command is valid only in a Contents file.

Note  See your SDK documentation for details on creating a Contents file.