tomwalters@0: .TH OPTIONS 1 "1 September 1993"
tomwalters@0: 
tomwalters@0: .SH NAME
tomwalters@0: options \- a general description of the AIM tools options handler.
tomwalters@0: 
tomwalters@0: .SH SYNTAX
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     command line  ::=  <program name>  [<options>]  [<filename>]
tomwalters@0: 
tomwalters@0:     option        ::=  <flag option> | <valued option>
tomwalters@0: 
tomwalters@0:     flag option   ::=  -<name> | [-]<name>=on|off
tomwalters@0: 
tomwalters@0:     valued option ::=  -<name>[=]<value> | [-]<name>=<value>
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: .SH DESCRIPTION
tomwalters@0: 
tomwalters@0: A program may take one or more files as input, and several options to set
tomwalters@0: internal parameters. The function of the options handler is to parse the
tomwalters@0: command line and interpret options according to the defined syntax,
tomwalters@0: to assign internal default values to the internal parameters represented by
tomwalters@0: each option, and then to override these using any corresponding options
tomwalters@0: found on the command line.
tomwalters@0: 
tomwalters@0: 
tomwalters@0: .SH "Command line syntax"
tomwalters@0: 
tomwalters@0: Programs which do not read input from files have a command line:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     <program name>  [<options>]
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: Programs which expect to read input from one or more files have command line syntax:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     <program name>  [<options>]  [<filenames>]
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: The command line parser assumes that each space-separated token on the command
tomwalters@0: line is either an option or a filename.
tomwalters@0: The strategy is to parse the command
tomwalters@0: line until either it is empty or a token with invalid option syntax is found.
tomwalters@0: All tokens remaining on the command line after parsing are assumed
tomwalters@0: to be input filenames.
tomwalters@0: Programs which read from one or more files expect the filenames to be given as
tomwalters@0: the final arguments on the command line.
tomwalters@0: If the command line is empty after parsing the options, but a file is expected,
tomwalters@0: then input is read from the standard input, (eg. via re-direction or a pipe).
tomwalters@0: The filename `-' is also interpreted as the standard input.
tomwalters@0: 
tomwalters@0: Typographical errors which cause options to have bad syntax are therefore treated as
tomwalters@0: potential filenames.
tomwalters@0: The program reports the error as if it were a file not found, by printing a message
tomwalters@0: on the stderr:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     <program name>: can't open <option>
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: and quits with an exit status of 1.
tomwalters@0: In the (unlikely) event that a file with a name matching the error is found
tomwalters@0: then this file will be opened for input to the program.
tomwalters@0: 
tomwalters@0: .SH "Option syntax"
tomwalters@0: 
tomwalters@0: The general syntax for flag options (which do not take a <value> part) is:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     -<name> | [-]<name>=on|off
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: The general syntax for valued options is:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     -<name>[=]<value> | [-]<name>=<value>
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: The usual Unix notation is observed, (characters within square brackets
tomwalters@0: are optional and the bar sign denotes exclusive OR) so that flag options
tomwalters@0: may take any of the forms:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     -<name>
tomwalters@0:     -<name>=on
tomwalters@0:      <name>=on
tomwalters@0:     -<name>=off
tomwalters@0:      <name>=off
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: Similarly, valued options may take any of the forms:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     -<name><value>
tomwalters@0:     -<name>=<value>
tomwalters@0:      <name>=<value>
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: Option syntax is designed to be compatible between a Unix options
tomwalters@0: style and a more declarative style. This is facilitated by allowing the <name>
tomwalters@0: part of each option to be given in abbreviated form provided this
tomwalters@0: is unambiguous with other options for the program.
tomwalters@0: 
tomwalters@0: The general option syntax in Unix and the declarative style respectively is:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     -<name><value>
tomwalters@0:     <name>=<value>
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: An example of the same option in both styles respectively would be:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     -t10
tomwalters@0:     time=10
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 
tomwalters@0: In many cases the option names are designed to be unambiguous from the first
tomwalters@0: letter to allow for complete compatibility, but in some cases the need for
tomwalters@0: declarative option names was felt to override the need for absolute compatibility.
tomwalters@0: If necessary any option name can easily be changed by changing the name
tomwalters@0: given in the first field of the static Options structure defined near the
tomwalters@0: top of each program source code, and then re-compile the program.
tomwalters@0: The change affects only the user interface via the options handler and has
tomwalters@0: no other side effects.
tomwalters@0: 
tomwalters@0: An exact match for option <name> is unambiguous even if the <name> matches
tomwalters@0: the head of another option <name>.
tomwalters@0: 
tomwalters@0: If insufficient of the <name> part is given to disambiguate it from other
tomwalters@0: options, then the program prints a message on the stderr:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     <program name>: ambiguous option [<option>]
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: and quits with an exit status of 1.
tomwalters@0: 
tomwalters@0: For example, if a program takes options with names `frames' and `frameshift'
tomwalters@0: then the following are synonymous for setting the frameshift to 20:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     frameshift=20
tomwalters@0:     framesh=20
tomwalters@0:     -framesh20
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: but the following would be ambiguous:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     -f20
tomwalters@0:     -frame20
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: However an exact match is allowed to be unambiguous, so that the following would
tomwalters@0: set the frames option to 3:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     frames=3
tomwalters@0:     -frames3
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: .SH "Option values"
tomwalters@0: 
tomwalters@0: The <value> part may take the form of a number with optional units.
tomwalters@0: Time variables may be given in s (seconds) ms (milliseconds) and p (sample points).
tomwalters@0: The default with no units is interpreted as sample points.
tomwalters@0: For example:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     10      10 samples
tomwalters@0:     10p     10 samples
tomwalters@0:     10s     10 seconds
tomwalters@0:     10ms    10 milliseconds
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: Values given with time units are converted to a number of samples internally
tomwalters@0: using the given `samplerate' option.
tomwalters@0: 
tomwalters@0: Frequency variables take Hz (Hertz) and kHz (KiloHertz).
tomwalters@0: The default with no units is interpreted as Hertz..
tomwalters@0: For example:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     20000   20000 Hertz
tomwalters@0:     20000Hz 20000 Hertz
tomwalters@0:     20kHz   20000 Hertz
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: A <value> may be given as a hyphen-separated range of values with the general syntax:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     <value> = a[-b]
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: where `a' and `b' are both values or the strings "min" or "max".
tomwalters@0: For example, the `frame' option is used to select a range of frames for
tomwalters@0: processing:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     frame=a      Select just the a'th frame.
tomwalters@0:     frame=a-b    Select frames from the a'th to b'th inclusive.
tomwalters@0:     frame=min    Select the first frame.
tomwalters@0:     frame=max    Select the last frame.
tomwalters@0:     frame=a-max  Select frames from the a'th to the last inclusive.
tomwalters@0:     frame=min-b  Select frames from the first to the b'th inclusive.
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: Values which specify a time or frequency range take units as appropriate.
tomwalters@0: For example:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     range=10ms-40ms
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: 
tomwalters@0: .SH "On-line help"
tomwalters@0: 
tomwalters@0: All tools take an option called `help' which causes the program to print
tomwalters@0: help information on the stdout.
tomwalters@0: The following are usually synonymous calls for help:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     <program name>  -h
tomwalters@0:     <program name>  -help
tomwalters@0:     <program name>   help=on
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: In some cases the abbreviation `-h' will be ambiguous with another option
tomwalters@0: name, however `-help' and `help=on' are always unambiguous.
tomwalters@0: The help printed on the stdout includes a summary of the program's
tomwalters@0: application, it's command-line syntax or usage, and a list of the program
tomwalters@0: options with their default values and a brief comment about the use of each option.
tomwalters@0: The option syntax for each option is printed in place of
tomwalters@0: option comment line when the call for help takes the form:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     <program name>  help=syntax
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: Help with particular named options can be called with:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     <program name>  help=<name>
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: where the <name> part can be abbreviated provided it is unambiguous.
tomwalters@0: Certain options are `silent' in the sense that they are not printed in the
tomwalters@0: options list by the standard call for help because they are considered to
tomwalters@0: be rarely used. However they can be included in the options list by the call:
tomwalters@0: 
tomwalters@0: .nf
tomwalters@0:     <program name>  help=all
tomwalters@0: .fi
tomwalters@0: 
tomwalters@0: Silent options are assigned on the command line in the same way as ordinary
tomwalters@0: options.
tomwalters@0: 
tomwalters@0: .SH BUGS
tomwalters@0: 
tomwalters@0: A filename which matches a typographical error in option name would be
tomwalters@0: opened for input, leading to unexpected results.
tomwalters@0: .SH COPYRIGHT
tomwalters@0: .LP
tomwalters@0: Copyright (c) Applied Psychology Unit, Medical Research Council, 1995
tomwalters@0: .LP
tomwalters@0: Permission to use, copy, modify, and distribute this software without fee 
tomwalters@0: is hereby granted for research purposes, provided that this copyright 
tomwalters@0: notice appears in all copies and in all supporting documentation, and that 
tomwalters@0: the software is not redistributed for any fee (except for a nominal 
tomwalters@0: shipping charge). Anyone wanting to incorporate all or part of this 
tomwalters@0: software in a commercial product must obtain a license from the Medical 
tomwalters@0: Research Council.
tomwalters@0: .LP
tomwalters@0: The MRC makes no representations about the suitability of this 
tomwalters@0: software for any purpose.  It is provided "as is" without express or 
tomwalters@0: implied warranty.
tomwalters@0: .LP
tomwalters@0: THE MRC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 
tomwalters@0: ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL 
tomwalters@0: THE A.P.U. BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES 
tomwalters@0: OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, 
tomwalters@0: WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, 
tomwalters@0: ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS 
tomwalters@0: SOFTWARE.
tomwalters@0: