Creating a help library

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:

  1 ADDCONST
  Add a scalar to an NDF data structure.
  Description:
    The routine adds a scalar (i.e. constant) value to each pixel of
    an NDF’s data array to produce a new NDF data structure.

  2 Parameters
  For information on individual parameters, select from the list below:

  3 INPUT
  INPUT = NDF (Update)
    Input NDF data structure, to which the value is to be added.

  3 CONST
  Enter a scalar value.
  This will be added to each element in the main data array of the NDF.

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:

$ LIB/HELP/CREATE MYHELP ! Creates MYHELP.HLB
$ LIB/HELP MYHELP ADDCONST ! Inserts ADDCONST.HLP into MYHELP.HLP

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:

  interface ADDCONST
    parameter      INPUT          # Input NDF
       position    1
       ...
       helpkey     ’ADAM_EXAMPLES:MYHELP ADDCONST PARAMETERS INPUT’
    endparameter
    parameter      CONST          # Scalar value to add
       position    2
       ...
       helpkey     ’ADAM_EXAMPLES:MYHELP ADDCONST PARAMETERS CONST’
    endparameter
  endinterface

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:

  interface ADDCONST
    helplib     ’ADAM_EXAMPLES:MYHELP ADDCONST PARAMETERS’
    parameter      INPUT          # Input NDF
       position    1
       ...
       helpkey     ’INPUT’
    endparameter
    parameter      CONST          # Scalar value to add
        position    2
        ...
       helpkey     ’CONST’
    endparameter
  endinterface

Having done this, the help can be accessed by typing ? in response to a prompt as shown below:

  $ RUN ADDCONST
  INPUT - Input NDF structure > ?

  ADDCONST

   PARAMETERS

     INPUT

        INPUT = NDF (Update)
        Input NDF data structure, to which the value is to be added.

  INPUT - Input NDF structure >

Typing ?? rather than ? leaves the user in the HELP system to browse through any other available information. Pressing

<

>

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:

  $ ICL
  ICL> DEFHELP ADDCONST ADAM_EXAMPLES:MYHELP
  ICL> HELP ADDCONST
      ... Help information appears

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.

19 Creating a help library