As mentioned in Section 7, it is possible to store help information associated with a program in a HELP library. The whereabouts of this help can be indicated in the program interface file. The procedure to provide help information for the program ADDCONST is outlined below.
The first step is to create a help file appropriate for the program. This is a text file and has the default
extension .HLP
. ADDCONST is a very simple program with only two parameters: INPUT – which is
used to get the name of an input NDF, and CONST, a scalar value which is added to the NDF main
data array. An appropriate help file ADAM_EXAMPLES:ADDCONST.HLP is reproduced
below:
The structure of the text file is hierarchical; the above file contains four items, ADDCONST, Parameters,
INPUT
and CONST
. Each item has a position in the hierarchy within the help file as indicated by the
number 1, 2 or 3 at the beginning of a line. The lines of text following each item contain the help
information associated with it. For example, ADDCONST
is a first-level object containing the
application name and is followed by several lines of text containing general information
associated with the application. Parameters
is a second-level object, with a single line of
associated text. The individual parameters are each at the third level. In this case there are
two, INPUT
and CONST
, each of which is followed by a number of lines of associated help
information.
This help file must be inserted into a help library. The commands to create such a library – in this case called MYHELP.HLB – and insert ADDCONST.HLP are as follow:
The final step is to modify the ADDCONST interface file so that the program knows where to look for
the help information. This is done using the helpkey
field. The location of help information for a
particular item is indicated by specifying the help library and the position in the library hierarchy
where the information is stored. For example, the help information for the parameter CONST is
located in MYHELP ADDCONST PARAMETERS CONST
. A suitably modified ADDCONST.IFL is shown
below:
An obvious refinement suggests itself. The location of the help library appropriate for a
program can be specified once in the interface file, and the helpkey associated with each
parameter can merely point to the location of the help within that library. Indeed not just the
library name, but a location within the help library hierarchy can be specified using the
helplib
field. Only the part specific to each parameter need be given in the helpkey field
for that parameter. Thus the interface file for ADDCONST could be amended as shown
below:
Having done this, the help can be accessed by typing ?
in response to a prompt as shown
below:
Typing ??
rather than ?
leaves the user in the HELP system to browse through any other available information. Pressing
<CR>
one or more times (according to the current level in the help library) restores the program
prompt.
It is also possible to examine the help information without running the program. This is usually done under ICL using the command DEFHELP as shown below:
The directory where the help library resides must be specified in the DEFHELP command; otherwise DEFHELP will search for MYHELP.HLB in system directories.
Usually help libraries contain information on a number of programs; other help files could be
prepared and inserted into MYHELP.HLB. If a program has a standard ADAM prologue, an
appropriate .HLP
file can be generated automatically; see Section 20 for details.