Repatch (from linux) of OSX IRAF

1 files changed, 288 insertions, 0 deletions

diff --git a/pkg/language/doc/params.hlp b/pkg/language/doc/params.hlp
new file mode 100644
index 00000000..d0ebed8d
--- /dev/null
+++ b/pkg/language/doc/params.hlp
@@ -0,0 +1,288 @@
+.help parameters Feb86 language
+.ih
+NAME
+parameters -- IRAF parameters and their usage
+.ih
+DISCUSSION
+
+1. \fIIntroduction\fR
+
+    Parameters are the primary means of communicating information between
+the user and IRAF tasks, and between separate IRAF tasks.  Each user
+effectively has their own copy of the parameters for the tasks they run,
+and by tailoring these as they wish, they may customize the IRAF environment.
+Here we describe characteristics of IRAF parameters.
+The syntax of parameter declarations is described elsewhere.
+
+
+2. \fIParameter Types\fR
+
+    The CL supports a variety of parameter datatypes, from the conventional
+string, integer, and floating point types, to the exotic struct and cursor
+types.  There is no complex type in the CL.
+
+.ls char
+Character parameters are used to store strings of ASCII characters.
+By default character parameters have a maximum length of 64 characters,
+but this may be extended using the \fIlength\fR option when the parameter
+is declared.  A character parameter consisting of a single character can
+usually be treated as an integer, with a value equal to the ASCII value
+of the character.
+.le
+.ls int
+Integer parameters are used to store integer information.  Integer parameters
+are stored internally as a long integer, permitting at least 32 bits of
+precision.
+.le
+.ls real
+Real parameters are stored internally as double's.
+In general they may be entered with or without a decimal point,
+and with or without an exponent.  Note that the exponent should be
+entered using an E not a D.
+.le
+.ls bool
+Boolean parameters may only have the values \fIyes\fR or \fIno\fR.
+.le
+.ls file
+File parameters are basically character parameters which are required
+to be valid file names.  All operations legal on characters are legal
+on file parameters.  Various checks on the accessibility or existence
+of a file may be automatically performed when a \fIfile\fR type parameter
+is used at runtime.
+.le
+.ls struct
+Struct parameters are characters strings which are treated specially by
+the scan and fscan functions.  Scan and fscan set structs to the
+remainder of the line being scanned without further parsing.
+.le
+.ls gcur, imcur
+The cursor parameters have a character string value with a predefined cursor
+value format.  When a cursor type parameter is read in "query" mode, the
+hardware cursor on the graphics terminal or image display is physically read.
+If the cursor parameter is list-structured, cursor input may also be taken
+from a list (text file).  For a more detailed discussion of cursor control
+in the CL, type \fIhelp cursors\fR.
+.le
+
+
+3. \fIList-Directed Parameters\fR
+
+    Frequently one may have a list of values, e.g. numbers or file names,
+which one wishes to analyze in turn.  To do this one may use a list-directed
+parameter.  The parameter is defined with its value field set
+to the name of a file containing the list.  The next time it is referenced
+its value will not be the string containing the file name, but rather
+the first value in the list.  Subsequent calls will return later
+values in the list until an end-of-file is reached, at which point
+the parameter will appear to be undefined.  The file may be
+rewound using the p_filename attribute of the parameter.  Assigning the
+null string to a list parameter closes the associated list file.
+
+.nf
+	int	*list = "listfile.lis"
+	int	cur_val
+
+	for (i=1;  i < nlist;  i+=1) {
+	    cur_val = list
+	    analyze (cur_val)
+	}
+
+.fi
+
+A common usage of struct list-directed parameters is to read files in
+conjunction with the \fIfscan\fR function.  The following example prints
+out a file.
+
+.nf
+	struct	*slist = "filer.lis"
+	struct	line
+
+	while (fscan (slist, line) != EOF)
+	    print (line)
+.fi
+
+
+4. \fIModes\fR
+
+    The mode of a parameter determines two qualities: whether the parameter
+is prompted for when it is accessed, and whether the parameter is "learned",
+i.e. whether its value is saved between invocations of a task.
+
+A hidden parameter is never prompted for unless it is undefined
+or has an illegal value.  A query parameter is prompted for every time
+it is referenced, except that a query parameter which is set on a
+command line is not queried for when it is accessed within that task.
+
+These are the two basic modes, but a parameter may also be defined
+to be automatic.  This means that the parameter will use the mode
+not of the task, but of the package the task is part of, or by the CL.
+When an automatic parameter is referenced the CL searches
+up this hierarchy to find a mode which is not automatic and uses
+this for the mode.  If the mode switch at all levels is automatic
+then the mode is set to hidden.  The mode switch at the task, package
+and CL levels is determined by the VALUE, not the mode, of the
+parameter with the name "mode" associated with the task, package or CL.
+
+Query and automatic parameters are learned by default, while hidden parameters
+are not.
+
+
+5. \fIRanges\fR
+
+    The CL supports ranges for integer and real variables, and enumeration
+lists for character strings.  A user may specify either or both of a minimum
+and maximum for numbers, and the CL will reject
+any values which fall out of this range.  Range checking is only
+performed during querying, or inside \fIeparam\fR, not when a value
+is assigned directly.  For an enumerated string the input string
+is matched against any of the enumerated possibilities
+using a minimum-matching technique.  A value with no match is rejected.
+
+
+6. \fIParameter Attributes\fR
+
+    The user may access the different elements of a parameter using
+the parameter attributes.  For some parameters certain of the
+attributes will be meaningless or undefined.
+
+.ls p_name
+The name of the parameter.
+.le
+.ls p_type
+A string indicating the basic type of the parameter:
+
+.nf
+	b	-- boolean
+	i	-- int
+	r	-- real
+	s	-- string/char
+	f	-- file
+	struct	-- struct
+	gcur	-- graphics cursor
+	imcur	-- image cursor=
+.fi
+.le
+.ls p_xtype
+This is the same as p_type except that the string is prefixed by "*"
+if the parameter is list directed.
+.le
+.ls p_mode
+A string indicating the mode of the parameter composed of the characters:
+
+.nf
+	q  --  query
+	a  --  automatic
+	h  --  hidden
+	l  --  learned
+.fi
+.le
+.ls p_value
+The value of the parameter.  For a list-directed parameter this is a
+element in the file, not the file name.  Generally this is what is accessed
+when the parameter attribute is not specified.
+.le
+.ls p_length
+For string type parameters (i.e. char, struct, file, gcur, imcur),
+the maximum length of the string.
+.le
+.ls p_mimimum
+The minimum value for a parameter.  Also for enumerated strings
+the enumeration list.
+.le
+.ls p_maximum
+The maximum value for a parameter.
+.le
+.ls p_filename
+For list-directed parameters the file name associated with the parameter.
+.le
+
+
+Attributes may appear on either side of an equals sign, e.g.
+
+.nf
+	list.p_filename = "test.fil"
+	= str.p_length
+	range = integ.p_maximum - integ.p_minimum
+	list.p_xtype =
+	= system.page.first_page.p_minimum	# Fully qualified.
+.fi
+
+It is illegal to assign to the p_name, p_type and p_xtype fields.
+Most of the direct use of the parameter attributes is expected to be
+in systems level programming.
+
+
+7. \fIArrays\fR
+
+    The user may define arrays of arbitrary dimensionality within the CL.
+The arrays are referenced in the conventional fashion with
+the index list enclosed in square brackets, and the individual
+elements separated by commas.  In their internal representation,
+arrays are similar to those in Fortran, with the first element
+changing fastest as one traverses memory.  The limits of
+each index may be specified.
+
+In general the CL can only access one element of the array at a time
+but there is an automatic looping feature which permits the
+appearance of array arithmetic.  Any executable statement
+in which an array is referenced but  in which the exact element of the array
+is not defined (an "open" array reference)
+will cause the CL to implicitly execute that
+statement within a loop over all the elements of the array.  More
+than one "open" array may appear in the expression but they
+agree on the limits of the loop.  For example,
+
+.nf
+	real x[20,20], y[20], z[10,20], t[20]
+
+	y = x[1,*]
+	t = log(y)
+	z = x[1:10,*]
+.fi
+
+
+8. \fIScope\fR
+
+    A parameter is known via an implicit reference if the task in which
+it is defined is active.  In an implicit reference the parameter
+name only, without a task or package qualifier, is given.  The CL
+is always active, so that its parameters are always known.  In a
+script, the script itself is active, so its parameters may be used
+implicitly.  If the script calls another task, that sub-task may
+reference the invoking tasks parameters implicitly.
+
+For an explicit reference, i.e. with task and package qualifiers,
+the parameter is known if the package in which the task is defined
+is active.  For example, when starting the CL, the "lists" package
+is not active, thus the parameters of the "sort" task may not
+be referenced even in the form "lists.sort.param".  However since
+the system package is activated during login to the CL, the parameters
+of "page" may be referenced by "page.param".  In general a package
+qualifier is used only to remove ambiguity between tasks with the
+same name in two different packages.
+
+
+9. \fIStorage\fR
+
+    There are several places in which parameters are stored.
+On disk the CL searches
+for the parameters for a task in three locations.  For a procedure
+script, the default parameters are found in the script file itself, while
+other scripts and executables have a parameter file with defaults in
+the same directory as the script or executable.  These default values
+are used the first time a task is run, or whenever the default values
+have been updated more recently than the user's copy of the parameters.
+The user's copy is created when a task terminates, and retains any
+"learned" changes to the parameters.  It is created in a directory
+pointed to by the IRAF logical "uparm" which is usually a sub-directory
+of the default IRAF directory for the user.
+
+The user may also use in-core storage for the parameters using
+the cache command.  This keeps parameters for frequently used tasks
+available without requiring disk access.  Cached parameters
+are copied to disk when the CL exits, or when the update command
+is used.
+.ih
+SEE ALSO
+lparam, eparam, cache, unlearn, update, cursor
+.endhelp