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

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

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/man1/options.1	Fri May 20 15:19:45 2011 +0100
@@ -0,0 +1,289 @@
+.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.
+