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 Latex user documentation for each
routine. The documentation 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:
PROLAT IN [OUT]
Parameters:
ATASK = _LOGICAL (Read)
If
ATASK is set to TRUE, then a style of documentation suitable for a package of application
programs (i.e. ADAM A-tasks) is produced. If it is set to FALSE, then the documentation
produced is suitable for a subroutine library. [TRUE]
DOCUMENT = _LOGICAL (Read)
If
DOCUMENT is set to TRUE, then the output file will be a complete Latex document and will
contain all necessary layout definitions, etc. Such a file may be passed directly to Latex for
processing. If DOCUMENT is set to FALSE, then the output file will contain only the information
extracted from the input files. In this case, additional Latex commands must be added to
produce a complete document (see the Latex Definitions section for details). This latter option
would typically be used when the output is to be included in a larger document which
already contains the necessary definitions. [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 Latex
documentation will be written. [prolat.tex]
PAGE = _LOGICAL (Read)
If PAGE is set to TRUE,
then a new output page will be started to hold the information extracted from each input
prologue. If PAGE is set to FALSE, then this will not occur. The default behaviour is to
start each prologue description on a new page for applications packages (ADAM A-tasks),
but for routine descriptions in subroutine libraries to follow end-to-end. []
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:
PROLAT MYPROG.FOR MYPROG.TEX
Extracts prologue information from the
application program source code held in the file MYPROG.FOR and produces a Latex
user document for it. The Latex output is written to the file MYPROG.TEX. PROLAT
∗.FOR
OUT=SUBS.TEX ATASK=FALSE
Extracts prologue information for a subroutine library, whose source code resides
in the files ∗.FOR,
one routine per file. A Latex document describing the routines is written to the file SUBS.TEX. PROLAT
IN=SOURCE.FOR NOATASK NODOCUMENT NOSINGLE
Extracts prologue information from a
sequence of subroutines or functions which are all held in the file SOURCE.FOR and produces Latex
output in the default output file prolat.tex. This output file contains only the routine descriptions (no
Latex definitions) and is therefore suitable for inclusion in a larger document. PROLAT
IN=["∗.FOR","∗.GEN"]
NOATASK PAGE
In this example, a sequence of input file specifications is given. Each will be
processed in turn to generate Latex documentation from the first prologue encountered in each file.
Output is written to the file prolat.tex with the description of each routine starting on a new page.
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.
Latex Definitions
If the DOCUMENT=FALSE
option is chosen, then the output file will contain none of the Latex command definitions
needed to produce the final document. To define these commands, the contents of the file
$STARLINK_DIR/share/sst.tex must be included in the Latex input file in the preamble (in
the standard SUN template). The layout definitions in this file are designed to operate
correctly within the Latex environment normally used in a Starlink User Note (see the file
$STARLINK_DIR/share/sun.tex).
It is recommended that you include the contents of the file $STARLINK_DIR/share/sst.tex
in your final document explicitly rather than by using the Latex
∖include
directive, otherwise it may not be possible to process the document in future if changes have to be
made to the Latex definitions in this file.
Copyright © 2000 Council for the Central Laboratory of the Research Councils