From 40e5a5811c6ffce9b0974e93cdd927cbcf60c157 Mon Sep 17 00:00:00 2001
From: Joe Hunkeler <jhunkeler@gmail.com>
Date: Tue, 11 Aug 2015 16:51:37 -0400
Subject: Repatch (from linux) of OSX IRAF

---
 unix/boot/generic/generic.hlp | 245 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 245 insertions(+)
 create mode 100644 unix/boot/generic/generic.hlp

(limited to 'unix/boot/generic/generic.hlp')

diff --git a/unix/boot/generic/generic.hlp b/unix/boot/generic/generic.hlp
new file mode 100644
index 00000000..eda8ceb2
--- /dev/null
+++ b/unix/boot/generic/generic.hlp
@@ -0,0 +1,245 @@
+.help generic Feb86 softools
+.ih
+NAME
+generic -- generic preprocessor
+.ih
+USAGE
+generic [-k] [-o ofile] [-p prefix] [-t types] files
+.ih
+PARAMETERS
+.ls 4 -k
+Allow the output files generated by \fIgeneric\fR to clobber any existing
+files.
+.le
+.ls 4 -o ofile
+The name of the output file.  If this option is selected, only a single
+file can be processed.
+.le
+.ls 4 -p prefix
+A prefix to be prepended to the output filenames.  This is useful when
+the output files are to be placed in a different directory.
+.le
+.ls 4 -t types
+The datatypes for which output is desired.  One output file will be generated
+for each type specified, with \fIgeneric\fR automatically generating the
+output filename by appending the type character to the root filename of
+the input file.  The \fItype\fR string is some subset of [ubscilrdx],
+where the type characters are as follows.
+.ls
+.nf
+u	- C unsigned short
+b	- C byte (char)
+c	- SPP character
+s	- SPP short
+i	- SPP int
+l	- SPP long
+r	- SPP real
+d	- SPP double
+x	- SPP complex
+.fi
+.le
+
+This option cannot be used in combination with the -o option, and should
+not be used when generic code is expanded inline, rather than written into
+multiple output files.
+.le
+.ls 4 files
+The input file or files to be processed.  Generic input files should have
+the extension ".gx" or ".gc", although this is not required.  Only a single
+input file can be given if the -o option is specified.
+.le
+.ih
+DESCRIPTION
+The generic preprocessor is used to translate generic source code (code
+written to work for any datatype) into type dependent source code,
+suitable for compilation and insertion into a library.  The generic source
+is translated for each datatype, producing a type dependent copy of the
+source code for each datatype.  There are two primary modes of operation:
+
+.ls
+.ls [1]
+The generic source is embedded in a normal file, bracketed by \fI$for\fR and
+\fI$endfor\fR directives.  There is one input file and one somewhat larger
+output file, with the generic code in the input file being replaced in the
+output file by several copies of the enclosed source, one for each datatype.
+This mode is most commonly used for modules to be linked in their entirety 
+into an applications package.  The "-o" parameter is used to specify
+the output filename.
+.le
+.ls [2]
+The entire input file is generic.  There may be multiple input files, and
+for each input file N output files are generated, one for each datatype
+specified with the "-t" parameter.  The output filenames are automatically
+generated by appending the type character to the root filename of the
+input file.  This mode is most commonly used for object libraries.
+.le
+.le
+
+
+The generic preprocessor operates by token replacement (currently using a
+UNIX \fILex\fR lexical analyzer).  The input stream is broken up into a
+stream of tokens.  Each token is examined to see if it is in the following
+list, and the indicated action is taken if the token is matched.  The generic
+preprocessor directives have the form "$NAME", where $ marks a \fIgeneric\fR
+directive, and where NAME is the name of the directive.
+.ls 10 PIXEL
+Replaced by the current type name, e.g., "int", "real", etc.
+.le
+.ls 10 XPIXEL
+Replaced by the current type name in upper case, preceded by an X,
+e.g., "XINT", "XREAL", etc.  This is used for generic C procedures meant
+to be called from SPP or Fortran.
+.le
+.ls 10 INDEF
+Replaced by the numeric constant denoting indefinite for the current
+datatype.
+.le
+.ls 10 INDEF[SILRDX]
+These strings are \fInot\fR replaced, since the "INDEF" in this case is
+not generic.
+.le
+.ls 10 SZ_PIXEL
+Replaced by "SZ_INT", "SZ_REAL", etc.
+.le
+.ls 10 TY_PIXEL
+Replaced by "TY_INT", "TY_REAL", etc.
+.le
+.ls 10 $PIXEL
+Replaced by the string "PIXEL".  This is used in doubly generic sources,
+where the first pass translates $PIXEL to PIXEL, and the second to the
+actual type string.
+.le
+.ls 10 $INDEF
+Replaced by the string "INDEF".
+.le
+.ls 10 $t
+Replaced by one of the characters [ubcsilrdx].
+.le
+.ls 10 $T
+Replaced by one of the characters [UBCSILRDX].
+.le
+.ls 10 $/.../
+Replaced by the string "...", i.e., whatever is within the // delimiters.
+Used to disable generic preprocessing of arbitrary text.
+.le
+.ls 10 [0-9]+("$f"|"$F")
+Replaced by the corresponding real or double constant.  For example,
+"1$f" translates as "1.0" for type real, but as "1.0D0" for type double.
+.le
+
+.ls 10 $if (expression)
+The conditional preprocessing facility.  If the $IF tests false the code
+which follows is skipped over, and is not copied to the output file.
+Control transfers to the matching $ELSE or $ENDIF.  The following may be
+used in the boolean expression:
+
+.nf
+"datatype"	denotes the current type
+ubcsilrdx	any subset of these characters denotes
+		    the corresponding datatype
+sizeof()	the size of the specified type,
+		    e.g., for comparisons
+
+!= ==		the relational operators
+ >  <  >= <=
+
+
+Examples:
+
+	$if (datatype != dx)
+	    (code to be compiled if type not d or x)
+
+	$if (sizeof(i) <= sizeof(r))
+	    (code to be compiled if size int <= real)
+.fi
+
+$IF constructs may be nested.  The directive may appear anywhere on
+a line.
+.le
+
+.ls 10 $else
+Marks the else clause of a $IF.
+.le
+.ls 10 $endif
+Marks the end of a $IF.  One is required for every $IF.
+.le
+.ls 10 $for (types)
+For each of the listed types, output a translated copy of the code between
+the $FOR and the matching $ENDFOR.  Nesting is permitted.
+
+.nf
+Example:
+	$for (silrd)
+	(any amount of generic code)
+	$endfor
+.fi
+.le
+.ls 10 $endfor
+Marks the end of a $FOR statement.
+.le
+.ls 10 $$
+Replaced by a single $.
+.le
+.ls 10 /*...*/
+C comments are not preprocessed.
+.le
+.ls 10 "..."
+Quoted strings are not preprocessed.
+.le
+.ls 10 #...(EOL)
+SPP comments are not preprocessed.
+.le
+.ls 10 %...(EOL)
+SPP Fortran escapes are not preprocessed.
+.le
+.ih
+EXAMPLES
+1. Translate the generic source "aadd.gx" to produce the six output files
+"aadds.x", "aaddi.x", etc., in the subdirectory "ak", clobbering any
+existing files therein.  The \fIgeneric\fR task is a bootstrap utility
+written in C and is implemented as a CL foreign task, hence the UNIX
+command syntax.
+
+	cl> generic -k -p ak/ -t silrdx aadd.gx
+
+2. Perform an inline transformation ($FOR directive) of the source file
+"imsum.gx", producing the single file "imsum.x" as output.
+
+	cl> generic -k -o imsum.x imsum.gx
+    
+3. The following is a simple example of a typical generic source file.
+For additional examples, see the ".gx" sources in the VOPS, IMIO, IMAGES
+and other directories.
+
+.nf
+# ALIM -- Compute the limits (minimum and maximum values) of a vector.
+# (this is a copy of the file vops$alim.gx).
+
+procedure alim$t (a, npix, minval, maxval)
+
+PIXEL	a[ARB], minval, maxval, value
+int	npix, i
+
+begin
+	minval = a[1]
+	maxval = a[1]
+
+	do i = 1, npix {
+	    value = a[i]
+	    $if (datatype == x)
+		if (abs(value) < abs(minval))
+		    minval = value
+		else if (abs(value) > abs(maxval))
+		    maxval = value
+	    $else
+		if (value < minval)
+		    minval = value
+		else if (value > maxval)
+		    maxval = value
+	    $endif
+	}
+end
+.fi
+.ih
+SEE ALSO
+xc, xyacc
-- 
cgit 

