Explanatory Notes

The specification of parameters has the following format.

     name  =  type (access)
        description

This format also includes a Usage entry. This shows how the application is invoked from the command line. It lists the positional parameters in order followed by any prompted keyword parameters using a ``KEYWORD=?'' syntax. Defaulted keyword parameters do not appear. Positional parameters that are normally defaulted are indicated by being enclosed in square brackets. Keyword (i.e. not positional) parameters are needed where the number of parameters are large, and usually occur because they depend on the value of another parameter. These are denoted by a curly brace; the parameters on each line are related, and each line is mutually exclusive. An example should clarify.

contour ndf [comp] mode ncont [key] [device]
$\left\{ {\begin{tabular}{l} low=? high=? \\ percentiles=? \\ sigmas=? \end{tabular} } \right.$
mode

NDF, COMP, MODE, NCONT, KEY, DEVICE, and SMOOTHING are all positional parameters. Only NDF, MODE, and NCONT would be prompted if not given on the command line. The remaining parameters depend on the value of MODE. If the mode is to nominate a list of contour heights, HEIGHTS will be needed (MODE = "Free"); alternatively, if the mode requires a start height and spacing between contours FIRSTCNT and STEPCNT should be specified (MODE = "Linear" or "Magnitude"). Note that there are other modes that do not require additional information, and hence no more parameters.

There is also an Examples section. This shows how to run the application from the command line. More often you'll enter the command name and just some of the parameters, and be prompted for the rest. Note that the examples are the strings expected by the tasks. They are operating-system neutral as KAPPA has run on several different operating systems. UNIX shells or operating-system command languages will often interpret as special characters some or all of []()\^~"'$*? that may form part of the KAPPA command-line syntax. So in practice you should escape any such special characters that appear in these examples, as appropriate to your command language or shell. For instance, from the C-shell the fourth example of COMPAVE could be written like the following.

     compave cosmos galaxy '[4,3]' weight title='"COSMOS compressed"'
     compave cosmos galaxy \[4,3\] weight title=\"COSMOS compressed\"

Backslash escapes individual special characters, whereas quotes placed around text escape all occurrences of special characters within the quotes.

Some parameters will only be used when another parameter has a certain value or mode. These are indicated by the name of the mode in parentheses at the end of the parameter description, but before any default, e.g. Parameter DEVICE in CENTROID is only relevant when Parameter MODE is "Cursor".

%name means the value of parameter name.

The description entry has a notation scheme to indicate normally defaulted parameters, i.e. those for which there will be no prompt. For such parameters a matching pair of square brackets ([]) terminates the description. The content between the brackets mean

[]

Empty brackets means that the default is created dynamically by the application, and may depend on the values of other parameters. Therefore, the default cannot be given explicitly.

[,]

As above, but there are two default values that are created dynamically.

[default]

Occasionally, a description of the default is given in normal type, e.g. the size of the plotting region in a graphics application, where the exact default values depend on the device chosen.

[default]

If the brackets contain a value in teletype-fount, this is the explicit default value.