From an application written with the dialog editor, you can invoke help for a specified help topic ID. Please bear in mind that you will have to create parts of the help associated with these help topic IDs outside the Natural development environment. You will also have to compile the help with the platform-specific help compiler.

To keep an overview of all the different help sections in an application, Natural provides you with the help organizer. With this organizer,

• you assign a help ID (HELP-ID attribute value) to a specific dialog element;

• you write the help text for the associated help topic; this text is converted to a .rtf file to be processed by the help compiler;

• you optionally define the help topic's keywords;

• you optionally assign a help compiler macro to the help topic;

• and optionally you add a comment for your internal documentation purposes.

To create a help topic

1. Invoke the help organizer's main dialog.

2. Select a particular dialog element.

3. Generate a new help topic ID.

4. Return to the help organizer main dialog.

5. Assign the generated help topic ID.

6. Enter the external definitions for the help topic ID, such as the help topic text and the topic name.

7. Return to the help organizer main dialog.

8. Go to the topic list and see whether this new help topic fits your general organization of the help file to be created.

9. Return to the help organizer main dialog.

10. Save everything.

A dialog or dialog element can also be assigned a HELP-ID number independently of the help organizer.

To do so

• Open the corresponding attributes window. Enter a numeric value in the Help ID entry.

You must use the help topic's .h file to map the numerical ID that you enter here to the corresponding help topic ID (created by a markup in the .hlp file).

Natural expects the help file to be located in the resource (RES) subdirectory of the current library or one of the STEPLIBs, or in the directory referred to by the environment variable NATGUI_BMP. By default, Natural searches for a help file with the same name as the current library, but you can explicitly set the name of the help file via the HELP-FILENAME attribute. If no file extension is specified, Natural searches for a compiled HTML help file with the extension ".chm" first, then (if not found) for a WinHelp help file with the extension ".hlp". Thus, if no file extension is specified, it is possible to upgrade from using WinHelp to using HTML help without changing the Natural program. Note, however, that the Help Organizer only supports WinHelp. If you wish to create HTML help content, you must use an external help authoring tool to do so.

Whenever an end user presses F1 in an active dialog, Natural first queries for a file with the value of the HELP-FILENAME attribute plus the extension ".hnn" where nn is the Natural language code. If it does not find such a file, it queries for a file with the value of HELP-FILENAME plus the extension ".hlp"

Whenever the dialog element has the focus and the end user presses F1, Natural jumps to this help ID.

To build a help file

1. Go to your command prompt.

2. Change to the directory referred to by the environment variable $NATGUI_BMP.

3. Issue the command HCRTF -X helpfilename.

   Note:
   This assures that the directory containing HCRTF.EXE is specified in the PATH environment variable.

To test a help file

1. Invoke a dialog in your application.

2. Press F1.

   The help topic for the dialog should appear.

Alternatively, the help file can be conveniently built and tested interactively by opening the .hpj file in the Help Compiler Workshop (HCW.EXE).

To display help in a popup window

1. Check the Popup Help option in the dialog attributes window.

2. Run the dialog.

3. Press F1 with the focus on a control which has a help ID associated with it.

   The help topic associated with the focus control should appear in a popup window.