Help files provide online information about an application's functions.
Whenever an end user must be given general information on how your application is structured, a help text is needed that can be invoked from within the application.
Whenever an end user must be given specific information on what may be entered in an input field control, for example, a short text is needed that can be accessed from the input field control.
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 this 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 you optionally add a comment for your internal documentation purposes.
It is also possible to use several help files for one application. In this case, you must specify the help file in the dialog's attributes window. You can also use the same help file for more than one dialog.
The .rtf file and the corresponding help topic information created with the help organizer must be converted to a .hlp file. In this way, your end user can retrieve help information from the Natural application. This conversion into a .hlp file is done with the help compiler.
The Natural installation procedure also installs a version of the Microsoft help compiler on your disk. You will find the help compiler in a subdirectory of drive-letter:\Program Files\Software AG\product-acronym\version-number\Natural which is called HCn where n depends on the operating system on which Natural has been installed.
For more information on how to use the help compiler and on how to create the .hlp file from your .rtf file, please refer to the READn.TXT file in this directory where n is depending on the operating system.
There is also an example of a small help file which was generated with the help organizer.
This example help file is called BROWHLP.HLP and is located in the resource directory of library SYSEXEVT. You can find the files BROWHLP.RTF, BROWHLP.HPJ and README.TXT in the following directory:
drive-letter\Program Files\Software AG\product-acronym\version-number\Natural\Samples\sysexevt\help
To see a demonstration of the example help file
Go to library SYSEXEVT.
This library contains a browse application with a dialog called BROWSE1.
Start the SAG-DEMO-DB database. This is a prerequisite to running the browse application.
Start dialog BROWSE1 to run the application.
Press F1 with the focus being on various elements of the application.
To see a demonstration of the help organizer (looking at the contents
of BROWHLP.RTF)
Follow the instructions in the README.TXT file.
For each help topic you create, you can in general follow this sequence
of steps
Invoke the help organizer's main dialog.
Select a dialog element.
Generate a new help topic ID or enter the ID of your choice. To generate a help topic ID automatically, the help ID must be "0" (default). To enter a help topic ID, either you fill in the "Help ID" entry of the dialog or dialog element, or you fill in the help topic ID in the Online Help Organizer main dialog.
Return to the Online Help Organizer dialog.
Assign the help topic ID.
Enter the external definitions for the help topic ID, such as the help text and the topic.
Return to the Online Help Organizer dialog.
Go to the topic list and see whether this new help topic fits your general organization of the help file to be created.
Return to the Online Help Organizer dialog.
Save everything.
These steps are described in detail in the following sections.
To invoke the Online Help Organizer
dialog
From the menu, choose .
Or:
Press CTRL+ALT+H.
The main dialog appears. It contains the following:
| Entry | Meaning |
|---|---|
| Caption | Online Help Organizer - pathname (location of the .rtf file to be generated from a help topic text). |
| Help IDs in Dialog | Name of the current dialog. You organize your Help IDs dialog by dialog. |
| Control Name | The handle name or the handle names of all dialog elements
inside the dialog.
You can not change these handle names here. |
| Help ID | The Help ID attribute value for the dialog or dialog element. You may assign several Help ID values to one dialog element. If there are several Help IDs, you can view them by pulling down the drop-down list box. If you select a Help ID, either you can extend its definition or you can enter a new Help ID of your choice. |
| Topic | The name of the help topic. You can not edit this name here, but in the help topic's extended definition dialog box. |
| Help text | The help text. You can edit this text here or in the help
topic's Extended Definition dialog box.
It is possible to enter RTF formatting commands if the help text begins with a "{\" and ends with a "}". This signifies "raw mode". In raw mode, special RTF characters ('{', '}' and '\') must be escaped by a preceding backslash if they are to be treated as literal characters. However, even in raw mode, it is not necessary to enter line feed (\line) commands explicitly. |
| Action: | |
| New ID... | Invokes the Help ID Generation dialog where you can generate a Help ID for those dialogs or dialog elements for which the Help ID is still "0" (default). |
| Ext Def... | Invokes the Extended Definitions - (...) dialog. |
| Clear | Resets the currently selected Help ID to zero and clears the help topic text that was associated to the Help ID. |
| Topic List | Invokes the Global Topic List dialog. |
| OK | Saves your settings, exits the dialog and generates the
necessary help files. These files include a
helpfilename.rtf help topic file, a
helpfilename.hpj help project file, a
helpfilename.cnt contents file, a
helpfilename.hm Help ID mapping file and a
helpfilename.cshelp.cnt contents include file.
The help project and contents files are only generated if they do not already exist, ensuring that any changes made directly to these files (e.g. via a text editor) are not lost. |
| Apply | Saves your settings and generates the help files (as for the pushbutton) without exiting the dialog. Allows you to save the changes and switch to and from the help compiler without having to leave and re-enter the help organizer. |
| Cancel | Exits the dialog without saving the settings. |
| Help | Provides online help on the dialog. |
The Online Help Organizer dialog may be re-sized. The position and dimensions are saved between sessions in the user profile (.PRU).
To generate a new help topic ID
From the Help Organizer Main dialog, select a dialog or dialog element and choose the button.
The Help ID Generation dialog appears.
(Optional) Enter a starting value which Natural will use to generate the next new ID.
This Help ID is valid only for the current dialog. To avoid duplicate Help IDs in the same Natural application, you define exclusive numerical ranges for the help topic IDs of a dialog. The starting value enables you start off the Help IDs at the beginning of the numerical range. You can, for example, decide that your dialog uses the range of 50 to 60. You enter "50" as the starting base and your first generated ID will be 50.
Choose to generate the Help ID.
Or:
Choose to exit the dialog without
generating.
Note:
You can also generate Help IDs for several dialogs/dialog elements
at once. To do so, you must select several dialogs/dialog elements in the
Online Help Organizer dialog. The IDs are then
generated sequentially starting from the lowest ID available.
To extend a help topic ID's definition
From the Help Organizer Main dialog, select a Help ID and choose the button.
The Extended Definitions dialog appears. It contains the following:
| Entry | Meaning |
|---|---|
| Caption | Extended Definitions - [current HELP-ID] |
| Topic: | Enter the heading of the help topic here. |
| Help Text: | Enter the text of the help topic here. |
| Keywords: | Enter the keywords of your help topic here. Keywords enable the end user of your Natural application to find the topic by selecting the button in the Help window. |
| Browse sequences: | Enter your browse sequences here. A browse sequence is useful if you want to group your help topics by subject. Browse sequences can also consist of an optional alphanumeric sort key, separated from the browse sequence name by a colon (e.g. mysequence:sort_key). |
| Macro: | Enter the name of your help macro here. Help macros enable you to customize your help. |
| Comment: | This section is for your internal help project documentation. |
| OK | Saves your settings and exits the dialog. |
| Cancel | Exits the dialog without saving the settings. |
| Help | Provides online help on the dialog. |
This information will be part of the .rtf file to be generated and will be interpreted by the help compiler.
The Extended Definitions dialog may be resized. The position and dimensions are saved between sessions in the user profile (.PRU).
To edit the global topic list
From the Help Organizer Main dialog, choose the button.
The Global Topic List dialog appears. It contains the following:
| Entry | Meaning |
|---|---|
| Caption | Global Topic List - [File: selectedfilepath] |
| Line in the table | Each line in the table represents a help topic. It lists its Help ID, the topic name and the extended definitions associated with it. |
| Action: | |
| Undo | Undoes the last editing action, especially deletion. |
| Delete | If a help topic is selected, this topic is deleted. |
| Ext Def... | Invokes the Extended Definitions dialog for the selected help topic. |
| Move Entry | Allows you to change the sequence of help topic entries. |
| MoveUp | Moves the selected help topic upwards within a browse sequence of help topic entries. |
| MoveDown | Moves the selected help topic downwards within a browse sequence of help topic entries. |
| OK | Saves your settings and exits the dialog. |
| Cancel | Exits the dialog without saving the settings. |
| Help | Provides online help on the dialog. |
This list contains all of the topics in the help file. Note that the topics are always maintained in browse sequence order.
The Global Topic List dialog may be resized. The position and dimensions are saved between sessions in the user profile (.PRU).