diff options
Diffstat (limited to 'pkg/lists/doc')
| -rw-r--r-- | pkg/lists/doc/Lcalc.hlp | 539 | ||||
| -rw-r--r-- | pkg/lists/doc/Lintran.spc.hlp | 60 | ||||
| -rw-r--r-- | pkg/lists/doc/Lists.hlp | 569 | ||||
| -rw-r--r-- | pkg/lists/doc/average.hlp | 49 | ||||
| -rw-r--r-- | pkg/lists/doc/columns.hlp | 38 | ||||
| -rw-r--r-- | pkg/lists/doc/lintran.hlp | 103 | ||||
| -rw-r--r-- | pkg/lists/doc/raverage.hlp | 110 | ||||
| -rw-r--r-- | pkg/lists/doc/rgcursor.hlp | 94 | ||||
| -rw-r--r-- | pkg/lists/doc/rimcursor.hlp | 270 | ||||
| -rw-r--r-- | pkg/lists/doc/table.hlp | 43 | ||||
| -rw-r--r-- | pkg/lists/doc/tokens.hlp | 55 | ||||
| -rw-r--r-- | pkg/lists/doc/unique.hlp | 27 | ||||
| -rw-r--r-- | pkg/lists/doc/words.hlp | 22 |
13 files changed, 1979 insertions, 0 deletions
diff --git a/pkg/lists/doc/Lcalc.hlp b/pkg/lists/doc/Lcalc.hlp new file mode 100644 index 00000000..a21cf8b8 --- /dev/null +++ b/pkg/lists/doc/Lcalc.hlp @@ -0,0 +1,539 @@ +.help lcalc Apr84 "List Calculator" +.nh +Introduction + + The list calculator performs general arithmetic, string, and +conditional operations upon lists. Examples of such operations include +.ls 4 +.ls o +General filtering of lists, i.e., conditionally pass or stop records +within a list. +.le +.ls o +Rearranging the fields of a list. +.le +.ls o +Extracting fields from a list. +.le +.ls o +Merging lists. +.le +.ls o +Arithmetic or string operations upon lists. +.le +.le + +A \fBlist\fR is a text file consisting of a sequence of \fBrecords\fR. +Whitespace normally delimits the fields of a record; newline normally +delimits a record. There may be an arbitrary number of fields within a +record, and records within a list. A record may span several lines of +text if a special delimiter is used. Blank lines and comment lines are +passed on to the output but are otherwise ignored. + +The input language of the list calculator is optimized to provide a +concise notation for expressing the types of operations most commonly +performed upon lists. Operations which cannot be specified by this +somewhat specialized language can easily be programmed as CL scripts. + +.nh +Lists + + Input may consist of one or more logical input lists. Multiple input +lists are by default read simultaneously as discreet lists; they may +optionally be concatenated into a single logical list. +A single list is always generated as output. Multiple input lists +are referred to in expressions as "lN", i.e., "l1", "l2", etc. +If multiple discreet input lists are used, the output list will be +truncated to the length of the shortest input list. + +.nh +Records + + The list calculator breaks each list into a sequence of records. +Each record has the following attributes: + +.nf + record number + record length + number of fields +.fi + +If the record delimiter is other than newline, newline is treated as +whitespace. Records are numbered starting at 1. Record number BOL may +be used to conditionally execute code before processing a list. Record +number EOL is matched only at the end of the list. + +.nh +Fields + + The list calculator breaks each record into a sequence of fields. +Each field has the following attributes: + +.nf + field number + field width (nchars in input record) + datatype + number of significant digits, if a number +.fi + +The "current record" may be thought of as an array F of fields. +The individual fields may be referenced in expressions in either of two +ways. If a single field is to be referenced, the field may be referred +to as the variable fN, e.g., "f1", "f2", and so on. If multiple +input lists are in use, the notation "li.fj" must be used instead. +Sets of fields may be referenced as sections of the array F; +a \fBsection\fR is an operand of type string, and may not be used +in arithmetic expressions. The entire record is most simply referred +to as the string R. The section notation may also be used to refer +to substrings of string type operands, and is discussed in a later section. + +.nh +Calling Sequence + + The principal operands to \fBlcalc\fR are the list template and +the program to be executed. An additional set of positional arguments +may be given; these are passed on to the program and are not used by +\fBlcalc\fR itself. A number of hidden parameters are available to +modify the behavior of the program. + + lcalc (list, program [, p1,...,p9]) + +.nh +Parameters +.ls 4 +.ls lists +A filename template specifying the list files to be processed. Not used +if the standard input is redirected. +.le +.ls program +Either the explicit \fBlcalc\fR program to be run, or if the first character +is an @, the name of a file containing the program. +.le +.ls p1 - p9 +Optional program parameters, referred to in the program as "$1", "$2", etc. +.le +.ls concatenate = no +Treat multiple input lists independently (concatenate = no) or concatenate +all input lists to form a single list. +.le +.ls field_delim = " \t" +A set of characters, any \fIone\fR of which will delimit the fields of an input +record. The default field delimiters are blank and tab (denoted \t). +.le +.ls record_delim = "$" +The \fIpattern\fR which delimits input records. All of the usual pattern +matching meta-characters are recognized. The default is "$", meaning that +end of line delimits input records (each record is a line of the input list). +Special record delimiters may be used to process multiline records. +.le +.ls ofield_delim = "in_field_delim" +The output field delimiter, inserted by the list calculator in output records +to delimit fields. The string "in_field_delim" signals that the first input +field delimiter character is to be used. +.le +.ls orecord_delim = "in_record_delim" +The output record delimiter, used to delimit output records. The default +action is to use the string (not pattern) which delimited the input record. +.le +.ls comments = yes +Pass comment lines and blank lines on to the output list. +.le +.le + +.nh +Statements + + A list transformation is specified by a program consisting of a +sequence of statements. The program may be input either directly on +the command line as a string, or in a file. Statements may be delimited +by either semicolon or newline. + +.nf + prog : stmt + | prog stmt + ; + + stmt : assign eost + | print eost + ; + + eost : '\n' + | ';' + ; +.fi + +There are two types of statements, assignment statements and print +statements. The \fBassignment\fR statements may be used to set or modify +the contents of an internal register. Registers are created and initialized +to zero or to the null string when first referenced in an assignment statement. +The usual modify and replace assignment statements "+=", "//=", etc. are +recognized. + +.nf + assign : IDENT '=' expr + | IDENT OPEQ expr + ; + + print : expr + | expr '?' + | expr '?' expr + ; +.fi + +The \fBprint\fR statement is used to generate output. In its simplest +form the print statement is an expression (e.g., "f5"); the value of the +expression is computed and output as the next field of the output record. + +As a simple example, suppose we wish to swap fields 2 and 3 of a three field +list, dropping field 1 (any additional fields will be discarded): + + lcalc list, "f3,f2" + +.nh +Expressions + + The power of the list calculator derives principally from its ability +to evaluate complex expressions. The operands of an expression may be +fields, registers, command line arguments, functions, constants, or +expressions. The datatype of an expression may be boolean, integer, real, +or string. Conditional expressions may be used to select or reject entire +records, or to conditionally format the fields of output records. + +The standard set of operators are supported. Expressions are evaluated +using the standard operator precedences and associativities. The following +operators are recognized: + + +.nf +binary operators: + + + - * / ** arithmetic + < <= > >= == != @ comparison + && || boolean and, or + // string concatenation + + +unary operators: + + ! - @ +.fi + +The only unconventional operator is the string matching operator @, +used to determine if a string matches a pattern. Usage is as follows: + +.nf + string @ pattern +or + @ pattern +.fi + +The expression evaluates to true if the pattern can be matched. If no +string is given, the entire record is searched. + +The expression syntax recognized by the list calculator is defined in +the figure below. + + +.nf + expr : primary + | expr ',' opnl expr + | '(' expr ')' + ; + + primary : IDENT + | CONSTANT + | primary BINOP opnl primary + | UNOP primary + | primary '?' primary ':' primary + | IDENT '(' arglist ')' + | section + | '(' primary ')' + ; + + section : IDENT '[' flist ']' + ; + + flist : # Empty + | fields + | flist ',' fields + ; + + fields : primary + | primary ':' + | primary ':' ':' primary + | primary ':' primary + | primary ':' primary ':' primary + | '*' + | '-' '*' + | '-' '*' ':' primary + ; +.fi + +.nh +Sections + + The section notation is used to extract substrings from string type +variables. If the variable referenced is F, an array of strings, then +the section indexes the fields of the record; the specified fields are +concatenated to produce the output string. If the variable is a string +variable, an array of characters, then the section specifies a set of +substrings to be concatenated. + +For example, to extract the first three characters of the string +variable "s": + + s[1:3] + +To extract characters 4 through the end of the string: + + s[4:] + +To reverse the order of the characters in the string: + + s[-*] + +To extract the first field of the record: + + f[1] + +To extract all fields, any of the following would do (F is the array of +field strings, whereas R is the entire record as a string): + + r, r[*], r[1:], f, f[*], f[1:] + +To refer to all fields in reverse order: + + f[-*] + +To specify fields 3 through 5: + + f[3:5] + +To specify fields 3, 5, and 7 through 10: + + f[3,5,7:10] + +If multiple input lists are in use, the notation "r1", "r2", etc. should +be used instead. + +.nh +Intrinsic Functions + + All of the standard intrinsic functions are recognized, plus a few +special intrinsic functions. + +.nf + abs exp log min real str + atan2 int log10 mod sin tan + cos len max nint sqrt type +.fi + +Certain of these functions deserve further mention: +.ls 4 +.ls len (expr) +Returns the length of an array or string, e.g., "len(f)" is the number +of fields in the current record, and "len(f2)" is the number of chars in +field 2. +.le +.ls str (expr) +Converts the argument into an operand of type string. +.le +.ls type (expr) +Returns the datatype of the argument. Legal values are "b", "i", "r", +and "s". The string type is the catchall. +.le +.le + +.nh +Variables + + The types of variables implemented in the list calculator are +the field variables ("f1", "f2", etc.), user variables, parameters, +and various builtin variables. All such variables may be used equivalently +within expressions. Only the builtin variables are writable by the +program. +.nh 2 +User Variables + + User variables are named by the user program; only the first 8 characters +of the variable name are significant. A user variable is created when it +is first used in an assignment statement. If the first reference is in a +modify and replace assignment, integer and real variables are initialized +to 0 and string variables are initialized to the null string, before the +modify operation takes place. It is an error if a user variable is first +referenced in an expression. +.nh 2 +Program Parameters + + The parameter variables are optional positional arguments to the +\fBlcalc\fR procedure. There are nine such parameters, "$1" through "$9". +The special parameter "$nargs" specifies the number of these parameters +set on the \fBlcalc\fR command line (the \fBlist\fR and \fBprogram\fR +arguments to \fBlcalc\fR are not counted). Parameters are read only. +.nh 2 +Builtin Variables + + The list calculator manages a number of variables internally. These +variables describe the list and record currently being processed, and are +read only to the user program (with one exception). The internal variables +are used primarily for conditional statements to be executed only at certain +times. + +.ls +.ls nfiles +The number of files in the input list (file template). +.le +.ls rnum +The record number within the list \fBfile\fR currently being processed. +The first record is number 1. +.le +.ls arnum +The absolute record number. +.le +.ls nfields +The number of fields in the current record. +.le +.ls nchars +The number of characters in the current record. +.le +.ls nlines +The number of input lines of text in the current record. +.le +.ls fname +The name of the input file currently being processed. +.le +.ls outfile +The name of the output file. This parameter is writable by the program. +If modified by the program, the current output file is closed and the +new output file is created for writing. +.le +.ls atbol +Set when processing the first record of the first file. +.le +.ls ateol +Set once the last record of the last file has been processed. +.le +.ls atbof +Set when processing the first record of a file. +.le +.ls ateof +Set once the last record of a file has been processed, before reading +the next file. +.le +.le + +.nh +Examples + + The list calculator is a very powerful tool and it is difficult to +present enough examples to illustrate all of the possible applications. +Furthermore, in many applications the list calculator is often used in +combination with other tools such as \fBsort\fR and \fBgraph\fR; we +will not use such programs in our examples here. + +.nh 2 +Simple bandpass filter + +Given a three column list {x,y,string}, pass only those lines for which +y is greater than 100 and less than or equal to 140: + + lcalc list, "f2 > 100 && f2 <= 140 ?" + +Pass only records in list1 wherein the third field has the same value +as the fifth field of list2: + + lcalc "list1,list2", "l1.f3 == l2.f5 ? r1" + +.nh 2 +Simple bandstop filter + +Pass only those records which do \fInot\fR contain the substrings +"obj1, "obj2", or "obj3": + + lcalc list, "!(@obj1 || @obj2 || @obj3) ?" + +.nh 2 +Rearranging and extracting fields + +Move fields 8 and 9 to the beginning of the list: + + lcalc list, "f8,f9,f[1:7],f[10:]" + +Reverse the order of all fields in each record: + + lcalc list, "f[-*]" + +Reverse the text of each record: + + lcalc list, "r[-*]" + +Extract fields 2 and 3 from a list: + + lcalc list, "f2,f3" + +.nh 2 +Merging lists + +Simple merge of two lists: + + lcalc "list1,list2", "r1 r2" + +.nh 2 +Arithmetic operations upon lists + +Scale the third field of each record of a list by the factor 5e3 +(if there is a third field): + + lcalc list, "f1, f2, nfields >= 3 ? f3 * 1e3, f[4:]" + +Print the log of the sum of the first three fields of each record: + + lcalc list, "log(f1+f2+f3)" + +Print the sum of the second field of \fIall\fR records in the list: + + lcalc list, "s+=f2; ateof ? 'sum is ' s" + +.nh 2 +Miscellaneous examples + +Execute the program in file "prog" on a list, passing two arguments: + + lcalc list, "@prog", 33, "circle" + +Process a list according to a complex program entered via the standard input: + + lcalc list, "@STDIN" + +Print record 55 of a list: + + lcalc list, "rnum == 55 ?" + +Edit a list, replacing the third field in each record with the string +"circle" if the input value of the field is "box": + + lcalc list, "f1,f2, f3 == box ? circle : f3, f[4:]" + +.nh 2 +Possible looping examples + + A concise notation for repeating the same operation on a set of fields +would be useful. Use of a very general construct such as the \fBfor\fR +loop is probably not justified, because such operations can already be +performed in a CL script. For the list calculator it would be preferable +to have a very concise notation, even if it is not as flexible. One possible +notation is shown in the example below. The loop variable "fi" is automatically +assigned, and represents field "i" of the record, where i takes on the values +specified by the section. If more than a single statement is to be looped +on, braces must be used to group statements. If loops are nested, the +outer (leftmost) loop is assigned the loop variable fi, the next fj, and so on. + +Print the sum of all fields in each record: + + lcalc list, "s=0; [*] s += fi; s" + +Reverse the characters in each field, without changing the ordering +of the fields: + + lcalc list, "[*] fi[-*]" +.endhelp diff --git a/pkg/lists/doc/Lintran.spc.hlp b/pkg/lists/doc/Lintran.spc.hlp new file mode 100644 index 00000000..9dd5ff98 --- /dev/null +++ b/pkg/lists/doc/Lintran.spc.hlp @@ -0,0 +1,60 @@ +.help lintran Mar84 lists + +.nf +List Operator LINTRAN + + Performs a linear translation on each element of the input list, +producing a transformed list as output. + + lintran (list) + +An input line may contain a variable number of fields. Two fields of each +input line are designated as the x and y coordinates (default cols 1,2). +All other fields are to be preserved across the transformation. Lines which +begin with a sharp ("#") are considered comment lines and are passed on to +the output unmodified, as are blank lines. If either if x or y are indefinite +and a pure translation or scale change is being performed, the corresponding +output coordinate will be indefinite. If either input coordinate is indefinite +and a rotation is being performed, both output coordinates will be indefinite. + + +Parameters: + + list + List or lists to be transformed (template). + + xcol = 1, ycol = 2 + Columns containing the x and y coordinates. + + x1 = 0.0, y1 = 0.0 + Current origin. + + xscale = 1.0, yscale = 1.0 + Scale factor to be applied to the input coordinates, relative + to the current origin [x0,y0]. + + angle = 0.0 + Rotation angle about the origin [x0,y0]. + + x2 = 0.0, y2 = 0.0 + New origin; applied after scaling and rotating the input coords. + + +Examples: + + Shift a coordinate list from the default origin [0,0] to the origin + [10.5,30], saving the result in the file "newlist": + + lintran list, x2=10.5, y2=30, > newlist + + Apply a shift of +3.4 units in x, -1.3 units in y to the input list + read from the standard input, writing the output list on the standard + output: + + (list stream) | lintran x2=3.4, y=-1.3 + + Take x and y from columns 2 and 3, rotate 45 degrees: + + lintran list, xcol=2, ycol=3, angle=45 +.fi +.endhelp 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 diff --git a/pkg/lists/doc/average.hlp b/pkg/lists/doc/average.hlp new file mode 100644 index 00000000..3cfd5599 --- /dev/null +++ b/pkg/lists/doc/average.hlp @@ -0,0 +1,49 @@ +.help average Jul86 lists +.ih +NAME +average -- compute the average and standard deviation +.ih +USAGE +average option +.ih +PARAMETERS +.ls option +Chosen from "add", "subtract" or "new_sample", +in which case the numbers averaged are those in STDIN. +If no argument is given on the command line, "new_sample" is assumed. +.le +.ih +DESCRIPTION +Task \fIaverage\fR computes the average and standard deviation of a list +of numbers. Numeric input is read from STDIN with one number per line. +The mean, sigma and number of samples are written to the standard +output. + +By default, the sample is taken to be +the set of numbers in the standard input when \fIaverage\fR is run. +Additional points can be added to or deleted from the sample by rerunning +\fIaverage\fR with \fBoption\fR equal to one of the following: +.nf + + add -- add points to the sample, recalculate mean and sigma + sub -- subtract points from the sample +.fi + +The sample is reinitialized by setting \fBoption\fR = "new_sample". +.ih +EXAMPLES +Run \fIaverage\fR on the list of numbers in file "numbers". +.nf + + cl> type numbers | average +.fi + +Add in to the sample the list of numbers in file "numbers.2". +.nf + + cl> average add < numbers.2 +.fi +.ih +SEE ALSO +lintran +.endhelp diff --git a/pkg/lists/doc/columns.hlp b/pkg/lists/doc/columns.hlp new file mode 100644 index 00000000..a4f304fa --- /dev/null +++ b/pkg/lists/doc/columns.hlp @@ -0,0 +1,38 @@ +.help columns Nov88 lists +.ih +NAME +columns -- break a multicolumn list into multiple single column lists +.ih +USAGE +columns filename numcols +.ih +PARAMETERS +.ls filename +Name of the input table file. +.le +.ls numcols +The number of columns in the input file. +.le +.ls outroot = "col." +Root name of the output column files. +.le +.ih +DESCRIPTION +Task \fIcolumns\fR is used to reformat a multicolumn list file into separate +files, such that one output file is created for each column in the input +file. It is used to break multicolumn tables into simple CL lists. +Comment lines beginning with the character "#" are ignored. All data +is transferred as text. One file \fBoutroot\fRn is produced for each +column in the input table. +.ih +EXAMPLES +Make 3 files named datacol.1, datacol.2 and datacol.3 from the 3 column +table dtable: +.nf + + cl> columns dtable 3 outroot=datacol. +.fi +.ih +SEE ALSO +fields +.endhelp diff --git a/pkg/lists/doc/lintran.hlp b/pkg/lists/doc/lintran.hlp new file mode 100644 index 00000000..94133e34 --- /dev/null +++ b/pkg/lists/doc/lintran.hlp @@ -0,0 +1,103 @@ +.help lintran Apr84 lists +.ih +NAME +lintran -- perform a linear transformation of a list +.ih +USAGE +lintran files +.ih +PARAMETERS +.ls files +List file or files to be transformed. +.le +.ls xfield = 1, yfield = 2 +Fields containing the x and y coordinates. +.le +.ls x1 = 0.0, y1 = 0.0 +Coordinates of current origin. +.le +.ls xscale = 1.0, yscale = 1.0 +Scale factor to be applied to the input coordinates, relative +to the current origin [x1,y1]. +.le +.ls angle = 0.0 +Rotation angle about the origin [x1,y1]. This angle, measured +counter clockwise from the positive x axis, is entered in +degrees, unless \fBradians\fR = yes. +.le +.ls x2 = 0.0, y2 = 0.0 +Coordinates of the new origin; input coordinates are shifted by an +amount (x2-x1) and (y2-y1). Positive shifts indicate increasing distance +from the current origin. Applied after scaling and rotating the input +coordinates. +.le +.ls radians = no +If this parameter is set to yes, \fBangle\fR is input +in radians, not degrees. +.le +.ls min_sigdigits = 1 +The number of significant digits to be output in the transformed fields +is the maximum of this parameter and the number of input significant digits. +.le +.ih +DESCRIPTION +Specified fields from the input list can be scaled, rotated and shifted. +Two fields of each input line are designated +as the x and y coordinates to be transformed (default: fields 1, 2). +All other fields are be preserved across the transformation. +For clarification, the equations used in the transformation are shown below: + +.ks +.nf + 1. Subtract off the current origin: + + xt = x - x1 + yt = y - y1 + + 2. Scale and rotate the coordinates: + + xs = xt * xscale + ys = yt * yscale + xt = xs * cos(angle) - ys * sin(angle) + yt = xs * sin(angle) + ys * cos(angle) + + 3. Shift to the new origin: + + xt = xt + x2 + yt = yt + y2 +.fi +.ke + +Comment lines and blank lines are passed on to the output unmodified +(a comment line is any line beginning with the character '#'). +If either x or y is indefinite +and no rotation is being performed, the corresponding +output coordinate will be indefinite. If either input coordinate is indefinite +and a rotation is being performed, both output coordinates will be indefinite. +.ih +EXAMPLES +1. Shift the coordinate list frame1 so it represents positions +in a second exposure of a star field, not registered with the first. Take +the coordinates of a star in frame1 to be the current origin +(e.g., [35.7, 389.2]); the new origin is then the coordinates of the same +star in the second exposure ([36.9, 400.0]). The shifted list is saved in +file "frame2": + + cl> lintran frame1 x1=35.7 y1=389.2 x2=36.9 y2=400.0 > frame2 + +2. Apply a shift of +3.4 units in x, -1.3 units in y to the input list +read from the standard input, writing the output list on the standard +output. + + cl> list_stream | lintran x2=3.4 y2=-1.3 + +3. Rotate a coordinate list of a 800x800 frame by 90 degrees. The +rotated coordinate list would represent positions in the field if it had +been rotated, for example, from East to the right to East to the top. +Note that the rotation takes place about the central pixel [400.50,400.50] +and that the current and new origins are the same: + + cl> lintran picture x1=400.5 y1=400.5 x2=400.5 y2=400.5 angle=90 +.ih +SEE ALSO +.endhelp diff --git a/pkg/lists/doc/raverage.hlp b/pkg/lists/doc/raverage.hlp new file mode 100644 index 00000000..4d36851f --- /dev/null +++ b/pkg/lists/doc/raverage.hlp @@ -0,0 +1,110 @@ +.help raverage May07 lists +.ih +NAME +raverage -- running average, standard deviation, and envelope +.ih +USAGE +raverage input nwin +.ih +PARAMETERS +.ls input +Input one or two column list of numbers. Any line that can't be read +as one or two numbers is ignored which means comments are allowed. The +special name "STDIN" may be used to read the numbers from the standard +input pipe or redirection. +.le +.ls nwin +The number of values in the running average window. +.le +.ls sort = no +Numerically sort the first column of the input list by increasing value? +This is done in an temporary file and the +actual input file is not modified. +.le +.ls nsig = 0 +The number of standard deviations below and above the average for the +envelope columns. If the value is greater than zero two extra columns +are output formed by subtracting and adding this number of standard +deviations to the average value. If the value is zero then the +columns not be written. +.le +.ls fd1, fd2 +Internal parameters. +.le +.ih +DESCRIPTION +This task computes the running average and standard deviation of a +one or two column list. For a one column list the ordinal value is +added. Note that the ordinal is only for the lines that are successfully +read so any comments are not counted. So the internal list is always +two columns. + +The input may be a physical file or the standard input. The standard +input is specified by the special name "STDIN". All the input values +are read and stored in a temporary file prior to computing the output. +A temporary file is also used if the input is to be numerically sorted +by increasing value of the first column. Note that the sorting is done +before adding the implied ordinal for one column lists. + +The output has four or six columns depending on whether \fInsig\fR is +zero or greater than zero. + +.nf + average1 average1 stddev number [lower upper] + + average1 - the running average of the first column + average2 - the running average of the second column + stddev - standard deviation of the second column + number - number of values in the statistic + lower - optional lower envelope value + upper - optional upper envelope value +.fi + +The "number" of values may be less than the window if the window size is +larger than the list. + +The number of lines will generally be less than the input because there is +no boundary extension. In other words the first output value is computed +after the first \fInwin\fR values have been read and the last output value +is computed when the end of the list is reached. + +The envelope columns are computed when \fInsig\fR is greater than zero. +The values are + +.nf + lower = average2 - nsig * stddev + upper = average2 + nsig * stddev +.fi + +In many cases the data is intended to represent a scatter plot and one +wants to show the trend and envelope as a function of the first column. +This is where the sorting and envelope options are useful. +.ih +EXAMPLES +1. Compute the running average with a window of 100 values on the list of +numbers in file "numbers". +.nf + + cl> raverage numbers 100 +.fi + +2. Do this using the standard input. In this example use random numbers. + +.nf + cl> urand 100 1 | raverage STDIN 90 +.fi + +3. Make a scatter plot of a two column list with the trend and envelope +overplotted. + +.nf + cl> fields numbers 1,3 | graph point+ + cl> fields numbers 1,3 | raverage STDIN 100 sort+ nsig=3 > tmp + cl> fields tmp 1,2 | graph append+ + cl> fields tmp 1,5 | graph append+ + cl> fields tmp 1,6 | graph append+ +.fi +.ih +SEE ALSO +average, boxcar +.endhelp diff --git a/pkg/lists/doc/rgcursor.hlp b/pkg/lists/doc/rgcursor.hlp new file mode 100644 index 00000000..7a64ec81 --- /dev/null +++ b/pkg/lists/doc/rgcursor.hlp @@ -0,0 +1,94 @@ +.help rgcursor Dec87 lists +.ih +NAME +rgcursor -- read the graphics cursor (makes a list) +.ih +USAGE +gcursor +.ih +DESCRIPTION +Task \fIrgcursor\fR iteratively reads the graphics cursor, writing the +cursor values to the standard output. The standard output is normally +redirected into a text file to generate a coordinate list to be used as +input to one or more other programs. Any IRAF program which reads the +graphics cursor may be run taking input from a list prepared in advance +with \fIrgcursor\fR (as well as interactively, of course). + +A plot should be drawn on the graphics terminal before running \fIrgcursor\fR. +When the program is run a loop is entered, reading the global graphics +cursor until the end of file character (e.g., <ctrl/z>, <ctrl/d>) is typed. +Each cursor read causes a line to be printed on the standard output, after +which the cursor is again read. + +While the program is waiting for the cursor to be read, i.e., whenever +the cursor crosshairs are displayed, the terminal is said to be in +"cursor mode". While in cursor mode, various commands may be entered, +e.g., to zoom in a feature to get a more accurate cursor position, without +terminating the current cursor read. To read the cursor position, enter +any key not recognized as a cursor mode command, i.e., any lower case or +non-alphanumeric character. The actual character one should type depends +upon the program for which the list is intended. If the program will use +only the X and Y coordinates of the cursor any character may be typed, +e.g., tap the space bar. If the program uses the key to determine what +action to take, then you must type a specific key. + +The X and Y coordinates of the cursor position and other information +comprising the cursor value are printed on the standard output when the +cursor is read. The cursor position may optionally be marked whenever the +cursor is read, by setting the ":.markcur" option when in cursor mode. +This is useful when preparing long lists to keep track of the objects +or features that have already been marked. + +For additional information on \fIcursor mode\fR and the format of a cursor +value string, type "help cursor". For information on the key and string values +required by the applications program for which the cursor list is intended, +consult the documentation for that program. +.ih +EXAMPLES +1. Interactively generate a starlist (file "starlist") to be used as input +to another program, e.g., for digital photometry. In this case one would +probably want to start with a contour plot labeled in image pixel coordinates. + +.nf + cl> contour m74 # make the plot + cl> rgcursor > starlist # make the object list + + At this point, the cursor loop is entered and the terminal + is placed into cursor mode. Any of the following commands + might be appropriate: + + \fBcommand\fR \fBaction\fR + + :.markcur+ enables marking of the cursor position + when the cursor is read + + :radius 7 set object radius in pixels + :annulus 10 15 set annulus radii to be used for sky + space_bar mark the position of an object + space_bar mark the position of an object + (etc.) + + Z zoom in on a feature to get a more + accurate cursor read + space_bar mark the position of the object + space_bar mark the position of another object + 0 replot the original plot + + <crtl/z> (EOF) terminates rgcursor +.fi + +Given the above command sequence, the output file "starlist" might +contain the following cursor values. + +.nf + 234.435 78.9292 1 : radius 7 + 234.475 78.9243 1 : annulus 10 15 + 67.2822 282.319 1 \40 + 766.252 344.224 1 \40 + 822.918 311.748 1 \40 + 76.8272 822.139 1 \40 +.fi +.ih +SEE ALSO +rimcursor, cursor +.endhelp diff --git a/pkg/lists/doc/rimcursor.hlp b/pkg/lists/doc/rimcursor.hlp new file mode 100644 index 00000000..9287579a --- /dev/null +++ b/pkg/lists/doc/rimcursor.hlp @@ -0,0 +1,270 @@ +.help rimcursor Mar92 lists +.ih +NAME +rimcursor -- repeatedly read and return image cursor values +.ih +USAGE +rimcursor [image] +.ih +PARAMETERS +.ls image +The name of the reference image to which coordinates should refer. +This parameter will be queried only if \fBrimcursor\fR cannot obtain +the reference image name by other means; e.g. when cursor reads are +being performed using the image display, \fBrimcursor\fR will assume that +\fIimage\fR is the currently displayed image. +.le +.ls wcs = "logical" +The world coordinate system (\fIwcs\fR) to be used for coordinate output. +The following standard world systems are predefined. +.ls logical +Logical coordinates are image pixel coordinates relative to the image currently +being displayed. This is what the raw cursor read returns, so by default, +\fBrimcursor\fR merely passes back the raw image cursor coordinates as +would be returned by "=imcur". +.le +.ls physical +The physical coordinate system is invariant with respect to linear +transformations of the physical image matrix. For example, if the reference +image was created by extracting a section of another image, the physical +coordinates of an object in the reference image will be the pixel coordinates +of the same object in the original image. The physical coordinate system +thus provides a consistent coordinate system (a given object always has the +same coordinates) for all images, regardless of whether any user world +coordinate systems have been defined. +.le +.ls world +The "world" coordinate system is the \fIcurrent default WCS\fR. +The default world system is the system named by the environment variable +\fIdefwcs\fR if defined in the user environment and present in the reference +image WCS description, else it is the first user WCS defined for the image +(if any), else physical coordinates are returned. +.le + +In addition to these three reserved WCS names, the name of any user WCS +defined for the reference image may be given. A user world coordinate system +may be any linear or nonlinear world system. +.le +.ls wxformat = "", wyformat = "" +The default output format for the x and y coordinates. If wxformat or wyformat +are undefined, rimcursor uses formatting options stored with the WCS in the +image header. If the WCS formatting options are not defined in the image +header, then rimcursor uses a default format. +.le +.ls cursor = "" +The source for image cursor input. By default, the hardware image cursor +is read. +.le +.ih +DESCRIPTION +The task \fBrimcursor\fR iteratively reads the image display cursor, +writing the cursor values to the standard output. The standard output +may be redirected into a text file to generate a coordinate list for use +as input to other tasks. Any IRAF program which normally reads the image +cursor interactively may be run taking input from a list prepared +using \fBrimcursor\fR. + +An image should be displayed on the image display device before running +\fBrimcursor\fR, and the device set to display the desired frame. +When the program is run, a loop is entered reading the image +cursor until the end of file character (e.g., <ctrl/d> or <ctrl/z>) is typed. +Each cursor read causes a line to be printed on the standard output, after +which the cursor is again read. Cursor values consist of two coordinates, +a coordinate system identification (currently identifying the display +frame), and the key or colon command typed to terminate the cursor read. +Note this task does not return pixel value information, see \fBimexamine\fR +for this purpose. + +While the program is waiting for the cursor to be read, i.e. whenever +the image cursor is blinking rapidly, the terminal is said to be in +"cursor mode". To read the cursor position, enter any key not +recognized as a cursor mode command (currently there are no cursor mode +commands for the image cursor so any character may be typed). +The colon key returns to text +input for a line of text terminated by a carriage return. This is +called a "colon command". The actual character or colon command one +types depends upon the program for which the list is intended. If the +program will use only the coordinates of the cursor any character may be +typed, e.g., the space bar. If the program uses the key value to +determine what action to take, then you must type a specific key. + +The X and Y coordinates of the cursor position and other information +comprising the cursor value are printed on the standard output when the +cursor is read. To keep track of objects or features marked in a long +set of cursor reads one may want to enable display marking if provided +by the display device; e.g. the \fBimtool\fR display server. +Other useful features, such as zoom, may be available in the display +device also. + +The coordinates returned by \fBrimcursor\fR depend on the type of +world coordinate system chosen by parameter \fIwcs\fR and those defined +by the reference image. The default "logical" coordinates are the +image pixel coordinates being displayed. This is available for all +images and may be required by other tasks which read the generated list. +The "physical" coordinate system provides coordinates from the "original +data image" irrespective of any linear transformations (such as image +sections) used to generate the current image from the original data image. +Coordinates in a user or application defined linear or nonlinear world +coordinate system may be obtained by setting the \fIwcs\fR parameter to +"world" for coordinate output in the default world system, or to the name +of the specific world system for which coordinates are desired. +An example of a world coordinate system for direct astronomical images +is RA and DEC using the tangent (gnonomic) projection. + +Coordinate transformations from the logical coordinates of image pixels +as given by a raw image cursor read, to physical or world coordinates is +performed by \fBrimcursor\fR. This aspect of the task may be used +to transform image pixel coordinate lists of x and y values, as produced +by some tasks such as \fBapphot\fR or \fBdaophot\fR into world +coordinates by specifying cursor input from the file rather than the +image display cursor. + +.ih +FORMATS +A format specification has the form "%w.dCn", where w is the field +width, d is the number of decimal places or the number of digits of +precision, C is the format code, and n is radix character for +format code "r" only. The w and d fields are optional. The format +codes C are as follows: + +.nf +b boolean (YES or NO) +c single character (c or '\c' or '\0nnn') +d decimal integer +e exponential format (D specifies the precision) +f fixed format (D specifies the number of decimal places) +g general format (D specifies the precision) +h hms format (hh:mm:ss.ss, D = no. decimal places) +m minutes, seconds (or hours, minutes) (mm:ss.ss) +o octal integer +rN convert integer in any radix N +s string (D field specifies max chars to print) +t advance To column given as field W +u unsigned decimal integer +w output the number of spaces given by field W +x hexadecimal integer +z complex format (r,r) (D = precision) + + +Conventions for w (field width) specification: + + W = n right justify in field of N characters, blank fill + -n left justify in field of N characters, blank fill + 0n zero fill at left (only if right justified) +absent, 0 use as much space as needed (D field sets precision) + + +Escape sequences (e.g. "\n" for newline): + +\b backspace (not implemented) +\f formfeed +\n newline (crlf) +\r carriage return +\t tab +\" string delimiter character +\' character constant delimiter character +\\ backslash character +\nnn octal value of character + +Examples + +%s format a string using as much space as required +%-10s left justify a string in a field of 10 characters +%-10.10s left justify and truncate a string in a field of 10 characters +%10s right justify a string in a field of 10 characters +%10.10s right justify and truncate a string in a field of 10 characters + +%7.3f print a real number right justified in floating point format +%-7.3f same as above but left justified +%15.7e print a real number right justified in exponential format +%-15.7e same as above but left justified +%12.5g print a real number right justified in general format +%-12.5g same as above but left justified + +%h format as nn:nn:nn.n +%15h right justify nn:nn:nn.n in field of 15 characters +%-15h left justify nn:nn:nn.n in a field of 15 characters +%12.2h right justify nn:nn:nn.nn +%-12.2h left justify nn:nn:nn.nn + +%H / by 15 and format as nn:nn:nn.n +%15H / by 15 and right justify nn:nn:nn.n in field of 15 characters +%-15H / by 15 and left justify nn:nn:nn.n in field of 15 characters +%12.2H / by 15 and right justify nn:nn:nn.nn +%-12.2H / by 15 and left justify nn:nn:nn.nn + +\n insert a newline +.fi + +.ih +EXAMPLES +1. Interactively generate a starlist (file "starlist") to be used as input +to another program, e.g., for digital photometry. + +.nf + cl> display dev$pix 1 # display image in frame 1 + cl> rimcursor > starlist # make the object list + + At this point, the cursor loop is entered and the terminal + is placed into cursor mode. The positions are marked using + the space bar. + + space_bar mark the position of the object + space_bar mark the position of another object + + <ctrl/z> (EOF) terminates rimcursor +.fi + +Given the above command sequence, the output file "starlist" might +contain the following cursor values. + +.nf + 441. 410. 101 \040 + 208. 506. 101 \040 + 378. 68. 101 \040 +.fi + +2. Get world coordinates for the default world coordinate system. + +.nf + cl> rimcur wcs=world + 12.13436 63.5565 101 \040 + 12.13448 63.5529 101 \040 + 12.13499 63.5588 101 \040 +.fi + +Since there is no format information in the image header, the coordinates are +decimal RA and DEC in degrees. + +3. Output the RA and DEC coordinates for an image in sexagesimal degrees. + +.nf + cl> rimcur wcs=world xformat=%12.2h yformat=%12.2h + 19:47:12.25 33:15:03.66 + 19:43:12.10 33:14:38.06 + 19:45:12.40 33:15:56.03 +.fi + +4. Output the RA in sexagesimal hours and DEC in sexagesimal degrees for an +image. + +.nf + cl> rimcur wcs=world xformat=%12.2H yformat=%12.2h + 13:47:12.25 47:15:03.66 + 13:47:12.10 47:15:38.06 + 13:47:12.40 47:15:56.03 +.fi + +5. Convert a list of pixel coordinates to world coordinates. + +.nf + cl> rimcur obs001 wcs=world cursor=coordlist >worldlist +.fi +.ih +NOTES +Future plans call for implementation of cursor mode commands for image +display cursors similar to those available for graphics cursors. +.ih +SEE ALSO +rgcursor, cursors +.endhelp diff --git a/pkg/lists/doc/table.hlp b/pkg/lists/doc/table.hlp new file mode 100644 index 00000000..54cc0e0a --- /dev/null +++ b/pkg/lists/doc/table.hlp @@ -0,0 +1,43 @@ +.help table Jan86 lists +.ih +NAME +table -- format single column input into a table +.ih +USAGE +table input_files +.ih +PARAMETERS +.ls input_files +List of files to be formatted, may be STDIN. +.le +.ls first_col = 7 +Offset to first column of table +.le +.ls last_col = 0 +Offset to last column of table. The value \fBlast_col\fR = 0 indicates +right margin. +.le +.ls ncols = 0 +Number of columns. The value \fBncols\fR = 0 indicates maximum that will fit. +.le +.ls maxstrlen = 0 +Maximum string length for table entry. The value \fBmaxstrlen\fR = 0 +indicates no limit. +.le +.ih +DESCRIPTION +Task \fBtable\fR reads a list of strings from the standard input or a +list of files and assembles a nicely formatted table. If reading +from multiple input files, make a separate table for each. There is no +fixed limit to the size of the table which can be formatted. The table +is not sorted; this should be done as a separate operation if desired. +.ih +EXAMPLES +1. Format a file containing names into a two column table. The table is +sorted alphabetically first. + + cl> sort names | table ncols=2 +.ih +SEE ALSO +words, tokens +.endhelp diff --git a/pkg/lists/doc/tokens.hlp b/pkg/lists/doc/tokens.hlp new file mode 100644 index 00000000..5be408fd --- /dev/null +++ b/pkg/lists/doc/tokens.hlp @@ -0,0 +1,55 @@ +.help tokens Jan86 lists +.ih +NAME +tokens -- break input into stream of tokens +.ih +USAGE +tokens files +.ih +PARAMETERS +.ls files +The list of files to be converted into a stream of tokens. +.le +.ls ignore_comments = yes +Ignore comments in the input string? +.le +.ls begin_comment = "#" +The string marking the start of a comment +.le +.ls end_comment = "eol" +The string marking the end of a comment. The value \fBend_comment\fR = "eol" +means the end of a line terminates a comment. +.le +.ls newlines = yes +Is newline a legal token? +.le +.ih +DESCRIPTION +Task \fItokens\fR breaks the input up into a series of tokens. +The makeup of the +various tokens is defined by the FMTIO primitive ctotok, which is not very +sophisticated, and does not claim to recognize the tokens for any particular +language (though it does reasonably well for most modern languages). Comments +can be deleted if desired, and newlines may be passed on to the output as +tokens. + +Comments are delimited by user specified strings. Only strings which are also +recognized by ctotok() as legal tokens may be used as comment delimiters. +If newline marks the end of a comment, the end_comment string should be given +as "eol". Examples of acceptable comment conventions are ("#", eol), +("/*", "*/"), ("{", "}"), and ("!", eol). Fortran style comments ("^{c}",eol) +can be stripped by filtering with match beforehand. + +Each token is passed to the output on a separate line. Multiple newline +tokens are compressed to a single token (a blank line). If newline is not +desired as an output token, it is considered whitespace and serves only to +delimit tokens. +.ih +EXAMPLES +Break up the source file for this task into tokens: + + cl> tokens tokens.x +.ih +SEE ALSO +words +.endhelp diff --git a/pkg/lists/doc/unique.hlp b/pkg/lists/doc/unique.hlp new file mode 100644 index 00000000..d55d5ac0 --- /dev/null +++ b/pkg/lists/doc/unique.hlp @@ -0,0 +1,27 @@ +.help unique Jan86 lists +.ih +NAME +unique -- remove repeated adjacent lines from a file +.ih +USAGE +unique files +.ih +PARAMETERS +.ls files +List of files to be processed. +.le +.ih +DESCRIPTION +Task \fBunique\fR reads the input comparing adjacent lines. The second and +successive copies of a line are removed; the remainder is passed on to the +standard output. +.ih +EXAMPLES +Remove repeated names from a list. Note the input file has been sorted +alphabetically so repeated names are adjacent. + + cl> sort names | unique > names.final +.ih +SEE ALSO +sort +.endhelp diff --git a/pkg/lists/doc/words.hlp b/pkg/lists/doc/words.hlp new file mode 100644 index 00000000..0df846a1 --- /dev/null +++ b/pkg/lists/doc/words.hlp @@ -0,0 +1,22 @@ +.help words Jan86 lists +.ih +NAME +words -- break the input into a series of words +.ih +USAGE +words files +.ih +PARAMETERS +.ls files +List of files to be processed. +.le +.ih +DESCRIPTION +Task \fBwords\fR is used to break the input up into a series of words +or strings. A word is a sequence of characters delimited by whitespace +or newline. A string is delimited by single or double quotes, and may not +span more than a single line. +.ih +SEE ALSO +tokens, table +.endhelp |