Previous: mpl Data Set Format
Up: User's Manual for the mpl Scientific Toolkit
Next: Limitations of mpl Format
Previous Page: mpl Data Set Format
Next Page: Limitations of mpl Format
Previous: mpl Data Set Format
Up: User's Manual for the mpl Scientific Toolkit
Next: Limitations of mpl Format
Previous Page: mpl Data Set Format
Next Page: Limitations of mpl Format
Originally, it was intended that the Toolkit programs would be self-documenting, since each program will respond with usage information if it is run improperly. Experience has shown that the usage summaries provided by the programs are not sufficient for most users. Still, the user may obtain help for any program simply by running the program without any command-line input. With some experience, this will answer many questions without the need to refer to this document. The general form of the ``usage message'' that each program responds with is
usage: program_name required_argument1 required_argument2 ...
[optional_argument_1] [optional_argument_2] ...
{choice1.1 | choice1.2 | ...}
{choice2.1 | choice2.2 | ...}
[{optional_choice1.1 | optional_choice1.2 | ...}]
[{optional_choice2.1 | optional_choice2.2 | ...}] .
In words: required arguments (e.g., the name of the input data set) are listed without delimiters. Optional arguments (usually a
program-control ``switch", or an optional output filename), are delimited by square brackets. Sets of arguments that the user
must choose one and only one of are grouped by curly braces and separated by vertical bars. Optional sets of arguments
that the user may choose one (and only one) of are grouped by curly braces inside square brackets.
Options, or ``switches", are of the general form
-keyword[=value1[,value2...]],with several alternative forms recognized: you may use / instead of -, and : or , instead of =. Any keyword may be abbreviated when entered on the command line, so long as enough characters are supplied to make the keyword uniquely identifiable. If the value listed in the usage message has single quotes around it, then the value must be typed literally (e.g., as in -average=rms); you should not type the single quotes yourself in running the program. Such values may, like the keywords, be abbreviated. In contrast, a value listed in double quotes represents a string that may need to be enclosed double quotes (if, for example, it contains spaces, as in -title="x vs y").
This syntax is altered for the usage synopses in the following pages, since the availability of different type faces makes it possible to add some clarity. With the exception of the characters '[' and '{', items in ordinary type face are typed literally, with possible abbreviation. Any word in italics represents a user-supplied item or list of items. As above, double quotes are used to identify items that may require quotation in order to be parsed properly.
Most programs accept the -format argument to allow the user to select the output format of the data. This argument requires a C-style format string, which contains one or more sequences of the form[1] %[ field-width][. precision format-type. The optional field-width is the minimum number of characters that will be used to print the number. The optional precision is the number of digits desired after the decimal point. The format-type specifier is one of 'f', 'e', or 'g', giving floating-point, exponential, or adaptive floating/exponential format, respectively. A typical format string is `` %15.8e %15.8e'', which provides for printing of two columns in exponential format with 9 digits displayed. Note that if uncertainties are included in the data, the number of format sequences in the format string must be increased appropriately.
borland@aps.anl.gov