20 Prologues

All of the example programs discussed so far have been fairly short and to-the-point. However real ADAM programs have lengthy prologues which describe the program’s function, parameters, arguments, history, deficiencies, authors etc. The main purpose of such prologues is to document the program for prospective users and make the job of maintenance easier.

ADAM prologues are highly standardised. It is worthwhile to follow the standard – not least because utilities exist to automatically produce both LATEX documentation and help libraries from standard prologues. These utilities form part of the Simple Software Tools package (SST) and are briefly described later in this section. The SST package is fully documented in SUN/110.

Rather than typing in a prologue from scratch, a programmer can edit an existing one or use the STARLSE editor described in SUN/105. An example ADAM prologue is reproduced on the opposite page and the prologue of the accompanying interface file is reproduced below. The complete files are contained in ADAM_EXAMPLES:CADD.FOR and CADD.IFL.

  #+
  #  Name:
  #     CADD.IFL
  
  #  Type of module:
  #     ADAM A-task parameter interface.
  
  #  Author:
  #     RFWS: R.F. Warren-Smith (STARLINK)
  #     {enter_new_authors_here}
  
  #  History:
  #     11-APR-1990 (RFWS):
  #  Original version.
  #     {enter_changes_here}
  
  #-

The SST utilities used to produce documentation and help modules can be summarised as follow:

PROLAT – for producing LATEX documentation. The PROLAT utility processes a file (or files) containing a prologue of the correct form, to produce a .TEX file (called PROLAT.TEX by default). This file can then be processed in the normal way (see SUN/12). The sequence of commands below illustrate the procedure for processing the file CADD.FOR.
  $ SST                          ! Make SST available
  $ PROLAT CADD.FOR              ! Process CADD.FOR to produce PROLAT.TEX
  $ LATEX PROLAT                 ! Usual sequence to LaTeX and print
  $ DVICAN PROLAT
  $ PRCN PROLAT.DVI-CAN
PROHLP – for producing help libraries. Just as PROLAT produces a .TEX file, PROHLP produces a .HLP text file (called PROHLP.HLP by default) which can be inserted into a HELP library as shown below. (See Section 19 for more information on HELP libraries.)
  $ SST                                   ! Make SST available
  $ PROHLP CADD.FOR                       ! Process CADD.FOR to produce PROHLP.HLP
  $ LIBRARY/HELP MYHELP.HLB PROHLP.HLP    ! Insert HLP file into MYHELP.HLB

        SUBROUTINE CADD( STATUS )
  *+
  *  Name:
  *     CADD
  
  *  Purpose:
  *     Add a scalar to an NDF data structure.
  
  *  Language:
  *     Starlink Fortran 77
  
  *  Type of Module:
  *     ADAM A-task
  
  *  Invocation:
  *     CALL CADD( STATUS )
  
  *  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.
  
  *  ADAM Parameters:
  *     IN = NDF (Read)
  *        Input NDF data structure, to which the value is to be added.
  *     OUT = NDF (Write)
  *        Output NDF data structure.
  *     SCALAR = _DOUBLE (Read)
  *        The value to be added to the NDF’s data array.
  *     TITLE = LITERAL (Read)
  *        Value for the title of the output NDF. A null value will cause
  *        the title of the NDF supplied for parameter IN to be used
  *        instead. [’KAPPA - Cadd’]
  
  *  Notes:
  *     -  This routine correctly processes the AXIS, DATA, QUALITY,
  *     LABEL, TITLE, UNITS and VARIANCE components of an NDF data
  *     structure and propagates all extensions. Bad pixels and all
  *     non-complex numeric data types can be handled. The HISTORY
  *     component is simply propagated without change, if present.
  
  *  Arguments:
  *     STATUS = INTEGER (Given and Returned)
  *        The global status.
  
  *  Authors:
  *     RFWS: R.F. Warren-Smith (STARLINK)
  *     {enter_new_authors_here}
  
  *  History:
  *     11-APR-1990 (RFWS):
  *        Original version.
  *     {enter_changes_here}
  
  *  Bugs:
  *     {note_any_bugs_here}
  
  *-