Initial commit

1 files changed, 161 insertions, 0 deletions

diff --git a/pkg/language/doc/task.hlp b/pkg/language/doc/task.hlp
new file mode 100644
index 00000000..d5e4aacc
--- /dev/null
+++ b/pkg/language/doc/task.hlp
@@ -0,0 +1,161 @@
+.help "task,redefine" Apr87 language
+.ih
+NAME
+.nf
+task     -- define a new IRAF task
+redefine -- redefine an IRAF task
+.fi
+.ih
+USAGE
+.nf
+task     t1 [t2 ...] = tfile
+redefine t1 [t2 ...] = tfile
+.fi
+.ih
+PARAMETERS
+.ls t1, t2, ...
+The names of the new logical tasks.  The task name should be prefixed by a $
+if the task has no parameter file.  An optional extension should be appended
+if either the standard input or output of the task is a binary stream, rather
+than text.  For example, "$mytask.tb" denotes a task with no parameter file,
+a text standard input, and a binary standard output.
+.le
+.ls tfile
+The name of the file to be executed or interpreted to run the task.
+The type of the task is determined by the file extension.  An ".e" extension
+indicates an executable task, while ".cl" indicates a CL script task or
+procedure.  The \fItfile\fR string is prefixed by a $ to define a
+\fIforeign task\fR (see the discussion below).
+.le
+.ih
+DESCRIPTION
+The \fItask\fR statement defines a new task to the CL, and is required before
+the task can be run from the CL.  The new task is added to the "current
+package", i.e., the package that is listed when "?" is entered.  Any task
+definitions made since the current package was entered will be discarded
+when the package is exited.
+
+In addition to defining a new task, the \fItask\fR statement defines the
+type and attributes of the new task.  Three types of tasks can be defined:
+script (.cl), executable (.e), and foreign ($...).  A task is assumed to
+have a parameter file ("taskname.par", in the same directory as \fItfile\fR),
+unless the taskname is explicitly prefixed by a $.  A suffix or extension
+may optionally be added to the task name to indicate whether the input and
+output streams are text or binary.  The default is text, meaning that if
+output (or input) is redirected to a file, the file will be opened as a
+text file.
+
+The \fIforeign task\fR facility allows host system tasks, e.g., host utilities
+or user written Fortran or C programs, to be called from the CL as if they
+were regular IRAF tasks.  The command line of a foreign task is parsed
+like that of any other task (and unlike an OS escape), allowing expression
+evaluation, i/o redirection, and background job submission.  The difference
+between a regular IRAF task and a foreign task is that the foreign tasks have
+little or no access to IRAF facilities, are usually machine dependent
+(and programs which use them are machine dependent), and cannot be cached.
+Nonetheless the foreign task facility is very useful for personalizing and
+extending the IRAF environment with a minimum of effort.
+
+The \fItask\fR statement includes facilities for defining how the host system
+argument list for a foreign task will be built when the task is called from
+the CL.  The simplest form of the foreign task statement is the following:
+
+	task [$]taskname = "$host_command_prefix"
+
+where \fIhost_command_prefix\fR is the first part of the command string to be
+passed to the host system.  Any command line arguments are simply tacked onto
+the end of this string, delimited by blanks.
+
+If this is insufficient then argument substitution may be used to define how
+the argument list is to be built up.  The macro \fB$N\fR denotes argument N
+from the CL command line, with the first argument being number 1.  The macro
+\fB$0\fR is a special case, and is replaced the name of the task being
+executed.  Likewise, \fB$*\fR denotes all arguments.  If the character
+following the $ is enclosed in parenthesis, the corresponding argument string
+will be treated as an IRAF virtual filename, with the equivalent host system
+filename being substituted for use in the host command.  Any other character
+sequences are passed on unchanged.  The argument substitution macros are
+summarized in the table below.
+
+.ks
+.nf
+	$0		task name
+	$N		argument N
+	$*		all arguments
+	$(...)		host system filename translation of "..."
+.fi
+.ke
+
+When a task is invoked, an executable is run by starting an attached
+sub-process, while a script is run by starting a new level of the CL
+with its standard input set to the script file.
+
+An executable image may contain any number of executable CL tasks, hence it
+can be pointed to by multiple task names or in multiple \fItask\fR statements.
+A script file can only contain one script task.
+
+\fIRedefine\fR has the same syntax as the \fItask\fR command, but all the
+task names must already be defined in the current package.  It is often
+useful after misspelling the task file name in a task command.
+.ih
+EXAMPLES
+1. Call up the editor to create a new program (task) mytask.x.  Compile
+the new program.  Declare it using the task statement and then run it.
+
+.nf
+	cl> edit mytask.x			# edit
+	cl> xc mytask.x				# compile & link
+	cl> task $mytask = mytask.e		# define task
+	cl> mytask arg1 arg2			# run it
+.fi
+
+2. Define a script task with associated parameter file (if the script is
+a \fIprocedure\fR, the parameter file is omitted since procedure scripts
+always have defined parameters).
+
+	cl> task myscript = myscript.cl
+
+3. Define the four new tasks implot, graph, showcap, and gkiextract.
+All have parameter files except showcap.  The gkiextract task has a
+binary output stream.  All tasks are executable and are stored in the
+executable file "plot$x_plot.e".  Note the use of comma argument
+delimiters in this example; this is a compute mode example as would
+be found in a package script task.
+
+.nf
+	task	implot,			# compute mode syntax
+		graph,
+		$showcap,
+		gkiextract.tb	= "plot$x_plot.e"
+.fi
+
+4. Make the listed UNIX programs available in the IRAF environment as
+foreign tasks.  None of the tasks has a parameter file.  The "$foreign"
+declares the tasks as foreign, and indicates that the IRAF task name
+is the same as the host system task name.
+
+	cl> task $ls $od $rlogin = $foreign
+
+5. Define a couple of foreign tasks for VMS, where the command to be sent
+to VMS is not the same as the IRAF task name.
+
+.nf
+	cl> task $run	= $run/nodebug
+	cl> task $debug = $run/debug
+	cl> task $top	= "$show proc/topcpu"
+.fi
+.ih
+BUGS
+The distinction between command and compute mode syntax can be confusing.
+When defining tasks in your login.cl or in a package script task, use
+compute mode, with commas between the arguments and all strings quoted
+(there are plenty of examples in the system).  When typing in \fItask\fR
+statements interactively, use command mode.  If you forget and leave in
+the commas, they will be assumed to be part of the task name, causing the
+following error message when the task is run:
+
+	ERROR: IRAF Main: command syntax error
+.ih
+SEE ALSO
+prcache, flprcache, package
+.endhelp