From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001
From: Joseph Hunkeler <jhunkeler@gmail.com>
Date: Wed, 8 Jul 2015 20:46:52 -0400
Subject: Initial commit

---
 sys/vops/doc/vops.hlp | 260 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 260 insertions(+)
 create mode 100644 sys/vops/doc/vops.hlp

(limited to 'sys/vops/doc/vops.hlp')

diff --git a/sys/vops/doc/vops.hlp b/sys/vops/doc/vops.hlp
new file mode 100644
index 00000000..dc415afa
--- /dev/null
+++ b/sys/vops/doc/vops.hlp
@@ -0,0 +1,260 @@
+
+.help VOPS Feb83 "Vector Primitives"
+.sh
+Introduction
+
+    The vector primitives are abstract machine instructions which
+operate on vectors.  The "a" prefixed operators are for one dimensional
+arrays, and the "m" prefixed operators are for two dimensional
+arrays (matrices).  Each generic instruction is implemented as a
+set of operators, one for each data type.
+
+There are no vector primitives for the type BOOL.  If a "b" suffix is given,
+the vector primitive is understood to operate on unsigned machine bytes.
+The "u" suffix is used for the special type unsigned short integer.
+
+The binary operators ("c = a op b") come in two forms.  If the regular
+three character instruction mnemonic is used, the B operand must be vector.
+If the letter "k" is added to the mnemonic, the B operand must be a constant.
+These dual mode operators are flagged (with "(k)") in the table below.
+
+
+.nf
+     Instruction	    Operation		          Data Types
+
+	cht__		b = a (change datatype)		  UBcsilrdx
+	clr_		fill a with zeros		    csilrdx
+	mov_	(k)	b = a (copy vector)		    csilrdx
+
+	abs_		b = abs(a)			     silrdx
+	log_		b = log10(a)			     silrdx
+	lln_		b = natural_log(a)		     silrdx
+	sqr_		b = sqrt(a)			     silrdx
+	srt_		b = sort(a)			    csilrdx
+	neg_		b = -a				     silrdx
+	map_		b = (a + k1) * k2		     silrdx
+	map_B		b = (a + k1) * k2		     silrdx
+	lut_		b = lut[a] (lookup table)	    csil
+	lui_		b = interp (a, x)		     silrd
+	rep_		a = newval if (low<=a<=high)	    csilrdx
+
+	add_	(k)	c = a + b			     silrdx
+	sub_	(k)	c = a - b			     silrdx
+	mul_	(k)	c = a * b			     silrdx
+	div_	(k)	c = a / b			     silrdx
+	min_	(k)	c = min(a,b)			     silrd
+	max_	(k)	c = max(a,b)			     silrd
+	mod_	(k)	c = mod(a,b)			     silrd
+	pow_	(k)	c = a ** int_pwr 		     silrdx
+	exp_	(k)	c = a ** real_pwr		     silrdx
+
+	not_		b = !a				     sil
+	and_	(k)	c = and(a,b)			     sil
+	bor_	(k)	c = or(a,b)			     sil
+	xor_	(k)	c = xor(a,b)			     sil
+
+
+.tp 4
+other vector primitives:
+
+	lim_	ngpix =	 lim_ (a, npix; minval, maxval)	     silrdx
+	win_	nrej =	 win_ (a, npix, lcut, hcut)	     silrdx
+	avg_	ngpix =	 avg_ (a, npix; mean, sigma)	     silrdx
+	rav_	ngpix =	 rav_ (a, npix; mean, sigma; ksig)   silrdx
+?	med_	ngpix =	 med_ (a, ia, npix; median) 	     silrd
+.fi
+
+
+For example, "aaddr(a,b,c,npix)" would add the two REAL vectors A and B,
+of length NPIX, placing the sum in the vector C.  To add a constant K to
+the vector A, "aaddkr(a,k,c,npix)" would be used.
+The sequence "aclrb(a,nbytes)" would zero NBYTES machine bytes,
+starting at location A.
+
+.sh
+Preprocessing Generic Operators
+
+    A preprocessor is provided to convert a generic operator into a set
+of type specific operators.  By coding only generic operators, the programmer
+only has to maintain a single piece of code, reducing the possibility of
+an error, and greatly reducing the amount of work.
+
+The GENERIC preprocessor takes as input files written in either the IRAF
+preprocessor language or C (or any other language which provides macro
+definitions), with embedded preprocessor directives and keywords.
+.sh
+Usage
+
+    The calling sequence for the preprocessor (on the UNIX system)
+is as follows:
+
+	generic [-t types] [-p prefix] [-o outfile] file [file...]
+
+Any number of files may be processed.
+.sh
+Flags
+
+    The following (optional) flags are provided to control the types
+and names of the generated files:
+.ls 8
+.ls 8 -t
+Used to specify the datatypes of the files to be produced.  The default
+value is "silrdx", meaning types SHORT through COMPLEX.  Other possible
+types are "BU", i.e., unsigned byte and unsigned short.  The generic
+preprocessor does not support type boolean.
+.le
+.ls -p
+An optional prefix string to be added to each file name generated.  Provided
+to make it convenient to place all generated files in a subdirectory.
+If the name of the file(s) being preprocessed is "aadd.x", and the prefix
+is "d/", the names of the generated files will be "d/aadds.x", "d/aaddi.x",
+"d/aaddl.x", and so on.
+.le
+.ls -o
+If an output filename is specified with the -o flag, only a single input file
+may be processed.  Any "$t" sequences embedded in the output file name
+will be replaced by the type "suffix" character to generate the filenames
+of the type specific files in the generic family.  If no $t sequence is given,
+the type suffix is appended to the filename.  If no -o output filename is
+given, the names of the output files are formed by concatenating the type
+suffix to the root of the input filename.
+.le
+.le
+.sh
+Directives
+
+    The action of the preprocessor is directed by placing "$xxx" directives
+in the text to be processed.  The identifiers INDEF and PIXEL are also
+known to the preprocessor, and will be replaced by their type specific
+equivalents (INDEF --> INDEFS, INDEFI, etc., PIXEL --> short, int, real, etc.)
+in the generated text.  Comments (#... and /* ... */), quoted strings (".."),
+and escaped lines (^%) are passed on unchanged.  
+
+.ls 4
+.ls 20 $/text/
+The text enclosed by the matching slashes is passed through unchanged.
+.le
+.ls $t
+The lowercase value of the current type suffix character (one of [bucsilrdx]).
+.le
+.ls $T
+The uppercase value of the current type suffix character (one of [BUCSILRDX]).
+.le
+.ls digits$f
+Replaced by "digits.0" if the current type is REAL, by "digits.0D0" if the
+current type is DOUBLE, by "(digits,digits)" if the type is complex, or by
+"digits" for all other datatypes.
+.le
+.ls $if
+Conditional compilation.  Two forms of the $if statment are implemented:
+
+.nf
+	$if (datatype == <chars>)
+	$if (datatype != <chars>)
+
+or
+	$if (sizeof(<t1>) <relop> sizeof(<t2>))
+.fi
+
+where <chars>, <t1>, and <t2> are type suffix characters ("silrd", etc.),
+and where <relop> is one of the relational operators
+
+	==  !=  <=  <   >=  >
+
+Nesting is permitted.  Conditional statements need not be left justified,
+i.e., whitespace may be placed between BOL and a $xx preprocessor directive.
+.le
+.ls $$if
+Replaced by "$if".  Not evaluated until the second time the file is
+processed.
+.le
+.ls $else, $$else
+Begins a section of code which gets processed if the $if condition was
+false.
+.le
+.ls $endif, $$endif
+Terminates a $if or $else construct.
+.le
+.ls TY_PIXEL
+Replaced by TY_INT, TY_REAL, and so on.
+.le
+.ls SZ_PIXEL
+Replaced by SZ_INT, SZ_REAL, and so on.
+.le
+.ls PIXEL
+Replaced by the datatype keyword of the file currently being generated
+(int, real, etc.).
+.le
+.ls XPIXEL
+Replaced by the defined type (XCHAR, XINT, ect.).  Used in generic C
+programs which will be called from the subset preprocessor, and which
+must manipulate the subset pp datatypes.
+.le
+.ls $PIXEL
+Replaced by the string "PIXEL" (used to postpone substitution until the
+next pass).
+.le
+.ls INDEF
+Replaced by the INDEF parameter for the current datatype (INDEFS, INDEFI,
+INDEFL, INDEF, or INDEFX).
+.le
+.ls $INDEF
+Replaced by the string "INDEF".
+.le
+.le
+
+.sh
+Example
+
+    The following generic operator computes the square root of a vector.
+The members of the generic family would be called "asqrs", "asqri",
+and so on.
+
+.ks
+.nf
+	# ASQR -- Compute the square root of a vector (generic)
+
+	procedure asqr$t (a, b, npix)
+
+	PIXEL	a[npix], b[npix]
+	int	npix, i
+
+	begin
+		do i = 1, npix {
+		    if (a[i] < 0$f || a[i] == INDEF)
+			b[i] = INDEF
+		    else {
+			$if (datatype != rdx)
+			    b[i] = sqrt(double(a[i]))
+			$else
+			    b[i] = sqrt(a[i])
+			$endif
+		    }
+		}
+	end
+.fi
+.ke
+
+.sh
+Doubly Generic Operators
+
+    The preprocessor can also be used to generate doubly generic operators
+(operators which have two type suffixes).  A good example is the type
+conversion operator ACHTxy, which converts a vector of type X to a vector
+of type Y.  If there are seven datatypes (csilrdx), this generic family will
+consist of 49 members.
+
+Doubly generic programs are preprocessed once to expand the first suffix,
+then each file generated by the first pass is processed to expand the
+second suffix.  On the UNIX sytstem, this might be done by a command
+such as
+
+.nf
+	generic acht.x; generic -p dir/ acht[silrd].x
+	rm acht[silrd].x
+.fi
+
+This would expand "acht" in the current directory (generating 5 files),
+then expand each of the "acht$t" files in the subdirectory "dir/",
+creating a total of 25 files in the subdirectory.  The final command
+removes the 5 intermediate files.
-- 
cgit 

