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

---
 pkg/lists/doc/Lists.hlp | 569 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 569 insertions(+)
 create mode 100644 pkg/lists/doc/Lists.hlp

(limited to 'pkg/lists/doc/Lists.hlp')

diff --git a/pkg/lists/doc/Lists.hlp b/pkg/lists/doc/Lists.hlp
new file mode 100644
index 00000000..5b90ca7b
--- /dev/null
+++ b/pkg/lists/doc/Lists.hlp
@@ -0,0 +1,569 @@
+.help utilities May83 "IRAF System Utilities"
+.sh
+Basic IRAF System Utilities
+
+    A number of standard utilities are available as part of the IRAF
+user interface.  These utilities, most of which operate on files, are
+summarized later in this document.  A general discussion of files in
+the IRAF system follows.  The reader is assumed to have some familiarity
+with the IRAF command language (CL).
+
+
+.sh
+Virtual File Names
+
+    File names may be specified in a machine independent fashion, or with
+OS dependent pathnames.  A Virtual File Name (VFN) has the following form:
+
+
+.nf
+	ldir$root.extn
+
+where
+
+	ldir		logical directory or device name
+	root		root or base file name
+	extn		extension denoting the type of file
+.fi
+
+
+The LDIR and EXTN fields are optional.  The ROOT and EXTN fields may contain
+up to 20 characters selected from the set [a-zA-Z0-9_.+-#].  The EXTN field
+may not exceed three characters.  The EXTN field is separated from the ROOT
+by the character "." (dot).  If the ROOT field contains one or more occurrences
+of the dot character, the final dot delimited field is understood to be
+the extension.
+
+Logical directories are defined in the CL, using the SET command to associate
+an OS dependent pathname with a keyword in the environment table.  Logical
+directory prefixes are recursively expanded.
+
+A number of standard logical directories and devices are defined by the CL
+at startup time.  Additional logical directories are defined by applications
+packages upon entry, and become undefined when dictionary space is reclaimed
+on exit from the package.  The user may override environment definitions at
+will, by issuing SET commands to redefine environment variables.
+
+
+.sh
+File List Templates
+
+    Whenever it makes sense, the IRAF utilities are set up to process a list
+of files, rather than a single file.  In the descriptions of the standard
+utilities in the next section, "files" is a template or pattern specifying
+a list of files to be processed in some way.  The template is a string type
+parameter to the CL, which is expanded by a procedure (CLGFIL) in the
+compiled systems or applications task into an EOF terminated list of files.
+
+A template may consist of one or more file names, directory names,
+list file names, or patterns.  List elements are delimited by commas.
+A list file is denoted by prepending the character "@" to the pathname
+of the list file.  A pattern may be applied to the contents of either
+a list file or a directory.  The pattern is separated from the list file
+or directory name by the character "$".  A pattern all by itself is
+applied to the current directory.  Either logical or OS dependent
+pathnames may be used.
+
+A list element may refer only to a single directory.  Thus, one cannot
+specify a pattern such as "*/*.x", as is possible in UNIX.
+
+Some examples of templates follow:
+
+.nf
+	file
+	"file1, file2"
+	"*.x"
+	"[A-Z]*, *.com, ../$, ../fio/$*.x, lib$*.h, file, @list$*.vs"
+	"sia1:[iraf.lib]$*.h, uparm$cl_*.par"
+.fi
+
+The magic filenames "STDIN", "STDOUT", and "STDERR" have a special
+meaning.  Passing one of these special filenames to a task causes
+the named stream to be "reopened", transparently to the applications
+program.  Thus, for example, one can reference "STDIN" in a template,
+and the applications program will read from the standard input when
+it opens the corresponding file in the template.
+
+For example,
+
+	cl> concat "file1, @STDIN, STDIN, file2", > ofile
+
+concatenates the file "file1", the contents of the files named in the
+standard input (until the first EOF), the contents of the standard input
+itself (until the second EOF), and the contents of the file "file2",
+placing the output in the file "ofile".
+
+
+.sh
+File Protection and Clobber
+
+    The IRAF file interface (FIO) provides file protection and synchronization
+facilities, under control of user definable environment variables.
+
+File "clobber" refers to the overwriting of an existing file when a new
+file of the same name is created as an output file.  If "clobber" is
+defined as "no" in the environment, an IRAF task will abort if a new file
+would clobber an existing file.  If file clobber is enabled, FIO will try
+to overwrite the old file, and will abort if it cannot do so.
+
+	cl> set clobber = "yes"
+
+More explicit file protection is provided by the CL commands PROTECT and
+UNPROTECT.  A protected file cannot be deleted, accidentally or otherwise,
+until the protection has been removed with the UNPROTECT command or system
+call.
+
+A final form of file protection is provided to prevent a file from being
+clobbered which is already open by a task.  Thus, "COPY file,file" will
+abort when FIO discovers that "file" is already opened for reading.  This
+holds even if file clobber is enabled.
+
+
+.sh
+File Synchronization
+
+    File synchronization is useful when a process requires exclusive access
+to a file which is already open for exclusive access by another process.  
+When this situation occurs, the second task may abort with a message stating
+that it cannot access the file, or the task may wait for the file to become
+available.  File waiting is especially important for batch processes.
+
+	cl> set file_wait = "yes"
+
+The file wait option is controlled by the "file_wait" variable in the
+environment.  If file waiting is enabled, and a process finds that it
+has to wait to access a file, a warning message will be printed on the
+standard error output before the affected process goes to sleep.
+
+
+
+.sh
+Description of the Standard Utility Routines
+
+    Most of the system utilities are set up to read from either the
+standard input or a list of files.  If not reading from the standard
+input, and the input file template is not given on the command line,
+a prompt will be issued for the input file list.  If the output is a
+single file or directory, and output is not redirected, a prompt will
+be issued for the output file.
+
+The following list of system utilities is expected to adequately meet
+the needs of both general users and programmers.  Most notably missing
+are file editing facilities and the X-compiler.  These will be added
+to the system utilities package at some point in the future.  Other more
+specialized utilities and tools, such as are needed for general image
+processing, graphics, database management, magtape i/o, and so on, will
+be provided in the form of new packages in the months to come.
+
+.ks
+.ls 4 ALLOCATE device
+
+Allocate a device (e.g., a tape drive).  The standard logical tape
+drive names will probably be "mt0" and "mt1".
+.le
+.ke
+
+.ks
+.ls CLEAR
+
+Clear the terminal screen.
+.le
+.ke
+
+.ks
+.ls COLUMNS [files] [, c = "1,3,5-8"]
+
+Breaks the named file or files (or the standard input) up into a stream
+of words, written one word per line on the standard output.  A "word"
+is any whitespace delimited sequence of characters, or a quoted string.
+
+The hidden parameter COLUMNS may be used to extract only a particular column,
+or any list of columns, from each line.  If the list contains only the
+element "0" (the default) all columns are extracted, and placed on separate
+output lines.  If multiple columns are specified, only those columns given
+in the list are extracted, and all extracted columns from an input line
+appear together on a single output line.  If the last element in the list
+is "0", all remaining columns in the input line are extracted and placed
+on the output line.
+
+.nf
+Hidden params:
+    columns		string	["0"]	List of columns.
+.fi
+.le
+.ke
+
+.ks
+.ls CONCATENATE [files] [,output_file]
+
+Concatenate the input files to the output file.  If no input file is
+given, the standard input is used.  If no output file is given, the
+standard output is used.
+
+.nf
+hidden params:
+    otype		string	["*"]	text or binary output file
+    append		yes/no	[no]	append to output file
+.fi
+.le
+.ke
+
+.ks
+.ls COPY [file | files] [,output_file | directory]
+
+Copy the input file to the output file, or copy each file in the
+input list to the directory given as the second argument.
+
+.nf
+hidden params:
+    otype		string	["*"]	text or binary output file
+    append		yes/no	[no]	append to output file
+.fi
+.le
+.ke
+
+.ks
+.ls COUNT [files]
+
+Count the number of lines, words, and characters in each file
+in the input list.  Print the totals for each file and for all files.
+.le
+.ke
+
+.ks
+.ls DEALLOCATE device
+
+Deallocate a previously allocated device (e.g., a tape drive).
+.le
+.ke
+
+.ks
+.ls DELETE [files]
+
+Delete the named files.  A warning message is printed if a file
+cannot be deleted.  It is not considered an error to attempt to
+delete a file which does not exist.  Protected files cannot be
+deleted.
+.le
+.ke
+
+.ks
+.ls DIRECTORY [files] [,op=string]
+
+Tabulate information on all files matching the template given as the
+first argument on the standard output.  If no template is given, the
+contents of the current directory are displayed.
+
+.nf
+hidden params:
+    option	   string ["c"]	    1	one-column format
+				    a	use time of last access
+				    c	n-column format
+				    l	long format
+				    s	add size in Kb
+				    t	time sort
+				    r	reverse sort
+
+e.g.: "dir op=l"	(show current directory, long form)
+      "dir '*.x',op=lt"	(all ".x" files in cwd, long form)
+.fi
+.le
+.ke
+
+.ks
+.ls DISKSPACE
+
+Summarize the amount of disk space available on the local system.
+This command and its output are machine dependent.  This command
+may not be available on all systems.
+.le
+.ke
+
+.ks
+.ls ECHO [arglist]
+
+Echo any arguments on the standard output.
+.le
+.ke
+
+.ks
+.ls HEAD [files]
+
+Print the first few lines of each of the named files on the standard
+output.  A brief header is printed to identify each file.
+
+.nf
+hidden params:
+    nlines		int	[8]	number of lines to print
+.fi
+.le
+.ke
+
+.ks
+.ls HELP [task(s)]
+
+Retrieve documentation for the named task(s) from the help database,
+and format it on the standard output.  If no task name is given, the
+tasks comprising the current package are summarized, one line per task
+(task name followed by a brief description).  Help may be obtained for
+multiple tasks by supplying a template.  Tasks not in the current
+package search path may be referenced by specifying the pathname to
+the task ("package.task").
+
+.nf
+Hidden params:
+    option	string	[h] 	h	full help text
+				u	usage section only
+				p	program documentation
+				s	source code
+				f	give file names
+
+    file	fname	[""]	file containing help text
+    lmargin	int	[1]
+    rmargin	int	[75]
+    page	yes/no	[yes]	paginate output
+    nlpp	int	[24]	number of lines per page
+.fi
+.le
+.ke
+
+.ks
+.ls LCASE [file]
+
+Copy the named file or the standard input (a text stream) to the
+standard output, converting all alphabetic characters to lower case.
+.le
+.ke
+
+.ks
+.ls MANPAGE [task(s)]
+
+Print "manual pages" for each of the named tasks.  Manual pages are
+produced by breaking the help text for a task up into successive
+pages delimited by formfeed characters.  Each page has a header and
+a page number.  To print manual pages, the output of MANPAGE should
+be piped to PRINT ("manpage task(s) | print").
+
+.nf
+Hidden params:
+    lmargin		int	[1]	left margin
+    rmargin		int	[72]	right margin
+    nlpp		int	[60]	number of lines per page
+    first_page		int	[1]	first page to be printed
+    last_page		int	[0]	last page to be printed
+    file		fname	[""]	file containing help text
+.fi
+.le
+.ke
+
+.ks
+.ls MATCH pattern [,files] [,rev+]
+
+Search each file for the given pattern.  Copy a line to the standard
+output if the pattern can be matched.  Match against the standard input
+if no files are named.
+
+.nf
+hidden params:
+    reverse		yes/no	[n]	print lines NOT matched
+.fi
+.le
+.ke
+
+.ks
+.ls PAGE [files]
+
+The named files (or the standard input) are displayed a page at a
+time on the standard output.
+
+.nf
+Query mode params:
+    continue		y/n	[y]	query mode param, used to
+					provide the pause at the
+					end of each page, or to
+					exit early.
+hidden params:
+    nlpp		int	[24]	number of lines per page
+
+.fi
+.le
+.ke
+
+.ks
+.ls PRINT [files]
+
+The named files (or the standard output) are printed on the standard
+line printer device.  If a list of files are to be printed, each
+file is printed started on a new page, and file pages are broken and
+printed with numbered headers.  If PRINT is reading from its standard
+input, the input stream is copied to the printer without pagination.
+
+The input stream may contain ASCII standard control characters (e.g.
+formfeed), which will be processed if necessary prior to transmission
+to the output device.
+
+.nf
+hidden params:
+    page		yes/no	[no]	paginate the standard input
+    nlpp		int	[60]	number of lines per page
+    szline		int	[132]	maximum line length
+    device		string		name of printer device
+.fi
+.le
+.ke
+
+.ks
+.ls PROTECT [files]
+
+Protect the named files from deletion or clobber, accidental or
+otherwise.  It is not considered an error to attempt to protect
+a file which is already protected.  Protecting a file only prevents
+deletion of the file: write permission is not withdrawn.
+.le
+.ke
+
+.ks
+.ls RENAME [file | files] [,output_file | directory]
+
+Rename a file, or move each file in the input list to the directory
+given as the second argument.
+.le
+.ke
+
+.ks
+.ls SORT [files] [,options]
+
+Sort and merge the text files named in the list, or sort the standard
+input if no list.
+
+.nf
+hidden params:
+    numeric		yes/no	[n]	numeric sort
+    reverse		yes/no	[n]	reverse the sense of the sort
+    column		integer	[1]	column to be sorted
+    whitespace		yes/no	[y]	ignore leading whitespace
+.fi
+.le
+.ke
+
+.ks
+.ls SPY [v+]
+
+Get information on who is using the system, what they are up to, how
+much cpu time, etc., they have used, and so on.  This command, and the
+information it gives, are machine dependent.  This command may not be
+available on all systems.
+
+.nf
+hidden params:
+    verbose		yes/no	[no]	get more information
+.fi
+.le
+.ke
+
+.ks
+.ls TABLE [files]
+
+The input, consisting of a list of words, one word per line, is read
+into a buffer in memory, and organized into a table which is printed
+on the standard output.  The size of the table which can be formatted
+is limited by the amount of available buffer space.
+
+.nf
+Hidden params:
+    ncols		int	[0]	desired number of columns
+    lmargin		int	[1]	left margin of table
+    rmargin		int	[75]	right margin of table
+    maxch		int	[0]	max chars to print from each
+					word or string in the input.
+.fi
+.le
+.ke
+
+.ks
+.ls TAIL [files]
+
+Print the last few lines of each of the named files on the standard output.
+
+.nf
+hidden params:
+    nlines		int	[8]	number of lines to print
+.fi
+.le
+.ke
+
+.ks
+.ls TEE [files]
+
+Copy the standard input to the standard output, as well as to each
+of the named files.
+
+.nf
+hidden params:
+    otype		string	["*"]	text or binary output file
+    append		yes/no	[n]	append to the named files
+.fi
+.le
+.ke
+
+.ks
+.ls TIME
+
+Print the current time and date.
+.le
+.ke
+
+.ks
+.ls TYPE [files]
+
+Copy the named files to the standard output.  A brief header is
+printed at the beginning of each file, identifying the file.
+.le
+.ke
+
+.ks
+.ls UCASE [file]
+
+Copy the named file or the standard input (a text stream) to the
+standard output, converting all alphabetic characters to upper case.
+.le
+.ke
+
+.ks
+.ls UNPROTECT [files]
+
+Remove delete protection from the named files.  It is not considered
+an error to attempt to remove protection from a file which is not
+protected.
+.le
+.ke
+
+
+
+.sh
+CL Directives
+
+.ks
+.ls CHDIR directory
+
+Change the current working directory.  CHDIR without any arguments
+prints the name of the current working directory on the standard
+output.
+.le
+.ke
+
+.ks
+.ls SET [param [= value_string]]
+
+Set the value of an environment variable.  If the variable is not
+already defined, it becomes defined.  If the variable is already
+defined, the old value is (temporarily and silently) overridden.
+A variable defined or redefined with SET is discarded when CL
+dictionary space is reclaimed.
+
+SET without any arguments displays the current environment.
+.le
+.ke
+
+(etc.)
+.endhelp
-- 
cgit 

