Description:
This
application reads a series of Fortran 77 source code files containing prologue information formatted
using STARLSE (SUN/105) and produces an output file containing user documentation for each
routine in a format suitable for insertion into a help library. The help library format may be chosen to
suit either a package of application programs (i.e. ADAM A-tasks) or a set of ordinary subroutines or
functions, such as a subroutine library.
Usage:
PROHLP IN [OUT]
Parameters:
ATASK =
_LOGICAL (Read)
If ATASK is set to TRUE, then a help library format suitable for a package of
application programs (i.e. ADAM A-tasks) is produced. If it is set to FALSE, then the help library
format produced is suitable for a subroutine library. [TRUE]
IN() = LITERAL (Read)
A list of
(optionally wild-carded) file specifications which identify the Fortran 77 source code files to
be used for input. Up to 10 values may be given, but only a single specification such as
’∗.FOR
’
is normally required.
If the SINGLE parameter is set to TRUE (the default), then only a single prologue will be expected in
each input file. If it is set to FALSE, then there is no limit to the number of prologues which
may be held in each input file.
OUT = FILE (Write)
The output file to which the help
information will be written. The information in this file will need to be inserted into a
help library for use. [PROHLP.HLP]
SINGLE = _LOGICAL (Read)
If SINGLE is set to
TRUE, then only a single prologue will be expected at the start of each input file; if the file
contains more than one prologue, then the remaining ones will be ignored. If SINGLE is set
to FALSE, then each input file will be searched for all the prologues it contains and each
will be processed in turn. When appropriate, the former option (the default) will result
in faster execution since only the initial prologue information must then be read, rather
than the entire contents of each input file. [TRUE]
Examples:
PROHLP PROG.FOR
PROG.HLP
Extracts prologue information from the application program source code held
in the file PROG.FOR and produces a help library entry for it. The program’s name is
used as the level-1 help keyword. The output is written to the file PROG.HLP. PROHLP
∗.FOR
OUT=SUBS.HLP ATASK=FALSE
Extracts prologue information for a subroutine library, whose source code resides
in the files ∗.FOR,
one routine per file. Help library entries describing the routines are written to the file SUBS.HLP, with
each routine’s name being used as a level-1 help keyword. PROHLP IN=SOURCE.FOR NOATASK
NOSINGLE
Extracts prologue information from a sequence of subroutines or functions which are all
held in the file SOURCE.FOR and produces help library entries for them in the default output file
PROHLP.HLP. Each routine name is used to form a separate level-1 help keyword. PROHLP
IN=["A∗.FOR","B∗.FOR"]
NOATASK
In this example, a sequence of input file specifications is given. Each will be processed in
turn to generate a help file entry from the first prologue encountered in each file. Output is written to
the file PROHLP.HLP. Once again, each routine name generates a separate level-1 help keyword.
Notes:
Care must be taken to ensure that begin-prologue and end-prologue lines (starting
’∗+’
and ’∗-’
respectively) appear before and after each prologue and that
’+’ and
’-’ symbols are not used in the second column elsewhere in the file, otherwise prologues may not be
correctly identified.
Timing
The execution time is approximately proportional to the amount of
information to be read from the input files. In addition, the time will be increased somewhat if the
input code resides in a large number of separate files, due to the need to open and close each file. If
there is only one prologue in each input file, then execution time will be minimised if SINGLE is set to
TRUE, since only the initial prologue information need then be read, rather than the entire contents of
each file.
Copyright © 2000 Council for the Central Laboratory of the Research Councils