annotate man/man1/options.1 @ 0:5242703e91d3 tip

Initial checkin for AIM92 aimR8.2 (last updated May 1997).

.TH OPTIONS 1 "1 September 1993"

.SH NAME
options \- a general description of the AIM tools options handler.

.SH SYNTAX

.nf
    command line  ::=  <program name>  [<options>]  [<filename>]

    option        ::=  <flag option> | <valued option>

    flag option   ::=  -<name> | [-]<name>=on|off

    valued option ::=  -<name>[=]<value> | [-]<name>=<value>
.fi

.SH DESCRIPTION

A program may take one or more files as input, and several options to set
internal parameters. The function of the options handler is to parse the
command line and interpret options according to the defined syntax,
to assign internal default values to the internal parameters represented by
each option, and then to override these using any corresponding options
found on the command line.


.SH "Command line syntax"

Programs which do not read input from files have a command line:

.nf
    <program name>  [<options>]
.fi

Programs which expect to read input from one or more files have command line syntax:

.nf
    <program name>  [<options>]  [<filenames>]
.fi

The command line parser assumes that each space-separated token on the command
line is either an option or a filename.
The strategy is to parse the command
line until either it is empty or a token with invalid option syntax is found.
All tokens remaining on the command line after parsing are assumed
to be input filenames.
Programs which read from one or more files expect the filenames to be given as
the final arguments on the command line.
If the command line is empty after parsing the options, but a file is expected,
then input is read from the standard input, (eg. via re-direction or a pipe).
The filename `-' is also interpreted as the standard input.

Typographical errors which cause options to have bad syntax are therefore treated as
potential filenames.
The program reports the error as if it were a file not found, by printing a message
on the stderr:

.nf
    <program name>: can't open <option>
.fi

and quits with an exit status of 1.
In the (unlikely) event that a file with a name matching the error is found
then this file will be opened for input to the program.

.SH "Option syntax"

The general syntax for flag options (which do not take a <value> part) is:

.nf
    -<name> | [-]<name>=on|off
.fi

The general syntax for valued options is:

.nf
    -<name>[=]<value> | [-]<name>=<value>
.fi

The usual Unix notation is observed, (characters within square brackets
are optional and the bar sign denotes exclusive OR) so that flag options
may take any of the forms:

.nf
    -<name>
    -<name>=on
     <name>=on
    -<name>=off
     <name>=off
.fi

Similarly, valued options may take any of the forms:

.nf
    -<name><value>
    -<name>=<value>
     <name>=<value>
.fi

Option syntax is designed to be compatible between a Unix options
style and a more declarative style. This is facilitated by allowing the <name>
part of each option to be given in abbreviated form provided this
is unambiguous with other options for the program.

The general option syntax in Unix and the declarative style respectively is:

.nf
    -<name><value>
    <name>=<value>
.fi

An example of the same option in both styles respectively would be:

.nf
    -t10
    time=10
.fi


In many cases the option names are designed to be unambiguous from the first
letter to allow for complete compatibility, but in some cases the need for
declarative option names was felt to override the need for absolute compatibility.
If necessary any option name can easily be changed by changing the name
given in the first field of the static Options structure defined near the
top of each program source code, and then re-compile the program.
The change affects only the user interface via the options handler and has
no other side effects.

An exact match for option <name> is unambiguous even if the <name> matches
the head of another option <name>.

If insufficient of the <name> part is given to disambiguate it from other
options, then the program prints a message on the stderr:

.nf
    <program name>: ambiguous option [<option>]
.fi

and quits with an exit status of 1.

For example, if a program takes options with names `frames' and `frameshift'
then the following are synonymous for setting the frameshift to 20:

.nf
    frameshift=20
    framesh=20
    -framesh20
.fi

but the following would be ambiguous:

.nf
    -f20
    -frame20
.fi

However an exact match is allowed to be unambiguous, so that the following would
set the frames option to 3:

.nf
    frames=3
    -frames3
.fi

.SH "Option values"

The <value> part may take the form of a number with optional units.
Time variables may be given in s (seconds) ms (milliseconds) and p (sample points).
The default with no units is interpreted as sample points.
For example:

.nf
    10      10 samples
    10p     10 samples
    10s     10 seconds
    10ms    10 milliseconds
.fi

Values given with time units are converted to a number of samples internally
using the given `samplerate' option.

Frequency variables take Hz (Hertz) and kHz (KiloHertz).
The default with no units is interpreted as Hertz..
For example:

.nf
    20000   20000 Hertz
    20000Hz 20000 Hertz
    20kHz   20000 Hertz
.fi

A <value> may be given as a hyphen-separated range of values with the general syntax:

.nf
    <value> = a[-b]
.fi

where `a' and `b' are both values or the strings "min" or "max".
For example, the `frame' option is used to select a range of frames for
processing:

.nf
    frame=a      Select just the a'th frame.
    frame=a-b    Select frames from the a'th to b'th inclusive.
    frame=min    Select the first frame.
    frame=max    Select the last frame.
    frame=a-max  Select frames from the a'th to the last inclusive.
    frame=min-b  Select frames from the first to the b'th inclusive.
.fi

Values which specify a time or frequency range take units as appropriate.
For example:

.nf
    range=10ms-40ms
.fi


.SH "On-line help"

All tools take an option called `help' which causes the program to print
help information on the stdout.
The following are usually synonymous calls for help:

.nf
    <program name>  -h
    <program name>  -help
    <program name>   help=on
.fi

In some cases the abbreviation `-h' will be ambiguous with another option
name, however `-help' and `help=on' are always unambiguous.
The help printed on the stdout includes a summary of the program's
application, it's command-line syntax or usage, and a list of the program
options with their default values and a brief comment about the use of each option.
The option syntax for each option is printed in place of
option comment line when the call for help takes the form:

.nf
    <program name>  help=syntax
.fi

Help with particular named options can be called with:

.nf
    <program name>  help=<name>
.fi

where the <name> part can be abbreviated provided it is unambiguous.
Certain options are `silent' in the sense that they are not printed in the
options list by the standard call for help because they are considered to
be rarely used. However they can be included in the options list by the call:

.nf
    <program name>  help=all
.fi

Silent options are assigned on the command line in the same way as ordinary
options.

.SH BUGS

A filename which matches a typographical error in option name would be
opened for input, leading to unexpected results.
.SH COPYRIGHT
.LP
Copyright (c) Applied Psychology Unit, Medical Research Council, 1995
.LP
Permission to use, copy, modify, and distribute this software without fee 
is hereby granted for research purposes, provided that this copyright 
notice appears in all copies and in all supporting documentation, and that 
the software is not redistributed for any fee (except for a nominal 
shipping charge). Anyone wanting to incorporate all or part of this 
software in a commercial product must obtain a license from the Medical 
Research Council.
.LP
The MRC makes no representations about the suitability of this 
software for any purpose.  It is provided "as is" without express or 
implied warranty.
.LP
THE MRC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 
ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL 
THE A.P.U. BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES 
OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, 
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, 
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS 
SOFTWARE.