diff options
| author | Joseph Hunkeler <jhunkeler@gmail.com> | 2015-07-08 20:46:52 -0400 |
|---|---|---|
| committer | Joseph Hunkeler <jhunkeler@gmail.com> | 2015-07-08 20:46:52 -0400 |
| commit | fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 (patch) | |
| tree | bdda434976bc09c864f2e4fa6f16ba1952b1e555 /pkg/system/doc | |
| download | iraf-linux-fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4.tar.gz | |
Initial commit
Diffstat (limited to 'pkg/system/doc')
40 files changed, 3429 insertions, 0 deletions
diff --git a/pkg/system/doc/Sys.hlp b/pkg/system/doc/Sys.hlp new file mode 100644 index 00000000..89d66d7f --- /dev/null +++ b/pkg/system/doc/Sys.hlp @@ -0,0 +1,349 @@ +.help utilities Oct83 "IRAF System Utilities" +.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. + +.ks +.ls 4 ALLOCATE device + +Allocate a device (i.e., a tape drive). Some devices must be allocated +before they can be accessed for i/o. Deallocation occurs automatically +upon logoff, or upon execution of DEALLOCATE. The following devices may +be allocated: + +.nf +Devices: + mta Magtape unit A. + mtb Magtape unit B. + ima Image display unit A. + imb Image display unit B. +.fi +.le +.ke + +.ks +.ls BEEP +Beep the terminal bell. Used as in "> munch;beep" to signal when a +lengthy command has finished. Otherwise, an IRAF program will only +ring the terminal bell when an error has occurred. +.le +.ke + +.ks +.ls CLEAR + +Clear the terminal screen. +.le +.ke + +.ks +.ls CONCATENATE files [,output_file] + +Concatenate the named input files to the standard output or to the named +output file if given. All input files should be of the same type (text or +binary). The default type of the output file is the same as that of the +first input file; this may be overridden by setting the hidden parameter +"out_type". The standard input is assumed to be a text file unless overridden +by setting out_type. If no output file is given on the command line, the +standard output is assumed. + +.nf +Hidden Parameters: + out_type string = "in_type" Output file type (text|binary) + append bool = 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. +.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). Devices +are automatically deallocated upon logoff if not explicitly deallocated +with the deallocate command. +.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 without first removing their protection. + +.nf +Hidden Parameters: + verify bool = no Generate query to verify that each + file should indeed be deleted. +.fi +.le +.ke + +.ks +.ls DEVSTATUS device + +Print status information (i.e., is the device allocated, to whom, etc.) +for the named device. +.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. The "long" format +gives file protection status, type (text, binary, directory, or executable), +access modes (owner, group, world), owner name, size in bytes, date of +last modify, and the file name. + +.nf +Hidden Parameters: + option string = "m" 1 one-column format + a use time of last access + c use time of creation + l long format + m multicolumn format (default) + 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 current directory, 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 HEAD files + +Print the first few lines of each of the named files on the standard +output. If more than one file is printed, a brief header is printed to +identify each file. + +.nf +hidden params: + nlines int = 12 number of lines to print +.fi +.le +.ke + +.ks +.ls LPRINT files + +The named text files (or the standard input) are printed on the standard +line printer device. If several files are to be printed, each file is +printed starting on a new page, and file pages are broken and printed +with numbered headers. If reading from the standard input, the input +stream is copied to the printer without pagination, though pages may still +be broken by embedding formfeed characters in the text. The map_cc +option may be used to turn off all control character mapping, if binary +data is to be sent to the printer. + +.nf +Hidden Parameters: + map_cc bool = yes Map control characters into a printable + sequence (^L, etc.) +.fi +.le +.ke + +.ks +.ls MATCH pattern, files + +Search each text 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 Parameters: + stop bool = no Stop matched lines and pass unmatched + lines to the output instead. +.fi +.le +.ke + +.ks +.ls NEWS + +Page through the system news file, starting with the most recent entries. +The system news file is a sort of electronic bulletin board, used to +post announcements and notes of general interest. +.le +.ke + +.ks +.ls PAGE files + +The named text files (or the standard input) are displayed a page at a +time on the standard output. If there is more than one input file, +a brief header is printed at the beginning of each file. + +.nf +Hidden Parameters: + map_cc bool = yes Map control characters into a printable + sequence (^L, etc.) +.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 prevents only deletion or clobber of the entire +file: the contents of the file may still be overwritten. +.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 + +Sort and/or merge the text files named in the list, or sort the standard +input if no list. Sorting is by line or column, alphabetically or +numerically, in forward or reverse order. + +.nf +Hidden Parameters: + numeric_sort bool = no Sort numerically instead of + alphabetically, if datum is + a number. + reverse_sort bool = no Reverse the sense of the sort. + column int = 0 If 0, sort the entire line, else + sort the indicated column. + ignore_whitespace bool = yes Ignore leading whitespace if + sorting full lines. + merge bool = no Merge the input files, which are + assumed to already have been + sorted. +.fi +.le +.ke + +.ks +.ls SPY + +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 Parameters: + verbose bool = no Give more detailed information. +.fi +.le +.ke + +.ks +.ls STTY [terminal] + +Identify the type of terminal being used, if different than the system +default. This is necessary to tell the system the control sequence to +be used to clear the screen, the dimensions of the screen, etc. If no +arguments are given, the current terminal status is given. + +.nf +Hidden Parameters: + baud int = 0 If nonzero, the system takes the + argument as the new baud rate. + ncols int = 0 If nonzero, the argument becomes + the number of columns per screen. + nlines int = 0 If nonzero, the argument becomes + the number of lines per screen. +.fi +.le +.ke + +.ks +.ls TAIL files + +Print the last few lines of each of the named text files on the +standard output. + +.nf +Hidden Parameters: + nlines int = 12 Number of lines to print. +.fi +.le +.ke + +.ks +.ls TEE file + +Copy the standard input to the standard output, as well as to the named +output file. + +.nf +Hidden Parameters: + out_type string = "text" Type of output file (text|binary). + append bool = no Append to the output file. +.fi +.le +.ke + +.ks +.ls TIME + +Print the current time and date. +.le +.ke + +.ks +.ls TYPE files + +Copy the named text files to the standard output. If more than one file is +to be typed, a brief header is printed at the beginning of each file, +identifying the file. +.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 +.endhelp diff --git a/pkg/system/doc/Sys_intro.hlp b/pkg/system/doc/Sys_intro.hlp new file mode 100644 index 00000000..03d7e797 --- /dev/null +++ b/pkg/system/doc/Sys_intro.hlp @@ -0,0 +1,137 @@ +.help system May83 "General Aspects of the System Package" +.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. +.endhelp diff --git a/pkg/system/doc/allocate.hlp b/pkg/system/doc/allocate.hlp new file mode 100644 index 00000000..66d3353f --- /dev/null +++ b/pkg/system/doc/allocate.hlp @@ -0,0 +1,52 @@ +.help allocate Jan86 system +.ih +NAME +allocate -- allocate a device +.ih +USAGE +allocate device +.ih +PARAMETERS +.ls device +The device to be allocated. +.le +.ih +DESCRIPTION +\fBAllocate\fR allocates a device for exclusive access by one user, and +readies the device for i/o by some other program. A list of the devices +available on the local system is maintained in the file \fBdev$tapecap\fR +which needs to be configured by the site manager before it can be used. +The status of given device may be obtained by calling \fIdevstatus\fR. +.ih +EXAMPLES + +1. Print a list of the allocatable devices. The logical device names are +given at the left in the output text; ignore the information to the right. +\fBNote\fR: The dev$devices file should be configured by the site manager +when new tape devices are installed. Beginning with V2.9 it is used for +informational purposes only. +.ks +.nf + cl> type dev$devices + mta ... + mtb ... + mtc ... + iis ... +.fi +.ke + + +2. Allocate a tape drive after checking its status. + +.ks +.nf + cl> devstatus mtb + device mtb is not currently allocated + cl> + cl> allocate mtb +.fi +.ke +.ih +SEE ALSO +deallocate, devstatus +.endhelp diff --git a/pkg/system/doc/bench.hlp b/pkg/system/doc/bench.hlp new file mode 100644 index 00000000..1e8b373e --- /dev/null +++ b/pkg/system/doc/bench.hlp @@ -0,0 +1,56 @@ +.help bench Dec2010 system +.ih +NAME +bench -- simple benchmark tool +.ih +USAGE +bench +.ih +DESCRIPTION +The BENCH task provides a simple benchmark meant to simulate CCD processing +of three images. The tasks used exercise both disk- and CPU-intensive +applications and offer a crude comparison of performance between machines, +but it is not intended to be a comprehensive benchmark. There are no +parameters. +.ih +EXAMPLES +1. Run the benchmark: + +.nf + ecl> bench + + Bench started at 09:45:58 + + =====> Making images... + Making zero... + Making flat... + Making 3 objs... + + =====> Normalizing flat... + : + + =====> Subtracting zero from 3 images... + : + + =====> Dividing flat into 3 images... + : + + =====> Combining 3 images... + : + + =====> Median filtering image... + : + + =====> Deleting all images... + + Bench started at 09:45:58 + Bench ended at 09:46:56 + + Total execution time = 58.0 seconds + Total time Make 5 imgs Proc 3 imgs Combine 3 imgs Median 1 img + 58.0 25.0 10.0 4.0 19.0 +.fi + +.ih +SEE ALSO +.endhelp diff --git a/pkg/system/doc/chkupdate.hlp b/pkg/system/doc/chkupdate.hlp new file mode 100644 index 00000000..c4209753 --- /dev/null +++ b/pkg/system/doc/chkupdate.hlp @@ -0,0 +1,72 @@ +.help chkupdate Oct13 system +.ih +NAME +chkupdate - Check for an available IRAF update +.ih +USAGE +chkupdate +.ih +PARAMETERS +.ls interval = 0 +Number of days between updates checks. A value less than zero will disable +the checks entirely, a value of zero will cause a check to be made with +each login. +.le +.ls ref_file = "iraf$.release_date" +.le +.ls release = ")_.release" +Current IRAF release version. This value is inherited from the CL 'release' +parameter by default. +.le +.ls baseurl = "http://iraf.noao.edu/ftp" +Base URL to the IRAF release timestamp directory. +.le +.ls verbose = yes +Print verbose output? +.le +.ih +DESCRIPTION +This task compares the currently installed IRAF version with what is +available from the NOAO servers and will indicate whether an update is +available. The task is executed from the login.cl each time you login +to the CL, however the comparison is only done if 1) the uparm$update +file used to indicate the time of last check does not exist, 2) the +\fIinterval\fR parameter is zero to indicate the check should be done +with each login, or 3) more than \fIinterval\fR days have passed since +the last time the servers were contacted. An \fIinterval\fR value less +that zero may be used to disable the version updates entirely. + +The update check is done by comparing the file timestamp of the file +named in the \fIref_file\fR parameter with a distribution timestamp file +on the NOAO servers. The URL to this file is constructed from the +\fIbaseurl\fR and \fIrelease\fR parameters in addition to the \fIarch\fR +environment value, yielding a unique URL for each version and each platform. +If the contents of the file contain a timestamp more recent than the +timestamp of the \fIref_file\fR value, a message is printed to indicate +an update is available, otherwise a message is printed indicating the +installed system is current. +.ih +EXAMPLES + +1. Check whether an IRAF update is available, regardless of when we last +checked. + +.nf + cl> chkupdate interval=0 +.fi + +2. Check for an IRAF update once a month. + +.nf + cl> chkupdate.interval = 30 +.fi + +.ih +NOTES +This task is called automatically from the login.cl file at startup. + +Modifying the timestamp information of the \fIref_file\fR parameter, e.g. +by moving the IRAF tree, may invalidate the output. +.ih +SEE ALSO +.endhelp diff --git a/pkg/system/doc/concatenate.hlp b/pkg/system/doc/concatenate.hlp new file mode 100644 index 00000000..e3cd4fdc --- /dev/null +++ b/pkg/system/doc/concatenate.hlp @@ -0,0 +1,82 @@ +.help concatenate Nov84 system +.ih +NAME +concatenate -- connect files together into one big file +.ih +USAGE +concatenate files [output_file] +.ih +PARAMETERS +.ls files +The list of input files. The standard input, STDIN, may be specified to +interactively enter a few lines of text rather than read from a disk file. +All input files should be of the same type (binary or text). +.le +.ls output_file +The name of the output file. If no file is explicitly specified the +standard output (STDOUT) is used. +.le +.ls out_type = in_type +The output file type is forced if this parameter is defined as "binary" +or "text". If "out_type" does not begin with a "b" (or "B"), or a +"t" ("T"), then the output type is either "text", if the output file is +the standard output, or is determined from the type of the first input file. +.le +.ls append = no +If set to "yes", "files" are appended to "output_file". +.le +.ih +DESCRIPTION +Each file in the input file list is appended to the output file. +If "output_file" is not the standard output, and if output redirection (">") +was not specified on the command line, the resulting stream of data is placed +in a file. The input can be STDIN, which makes for an easy way to enter a +few lines of text into a file (but \fItype\fR is usually more convenient). +If entering data via the standard input, type the end of file character, +e.g., <ctrl/z>, to terminate the input sequence. +.ih +EXAMPLES + +1. Write out file1, followed by file2, to the terminal screen. Note that +there must be no space after the comma. + +.nf + cl> concatenate file1,file2 +.fi + +2. Write out files file1 and file2 into the new file "outfile". + +.nf + cl> concatenate file1,file2 outfile +.fi + +3. Copy what you type (up to the end-of-file character) into the file junk. + +.nf + cl> concatenate STDIN junk +.fi + +4. Write out the contents of each of the files whose names are given in "list", +one per line, and append this data to "junk". + +.nf + cl> concatenate @list junk append+ +.fi + +5. Concatenation is also possible using \fItype\fR, e.g., the following +command will append the contents of "file" to the file "outfile", which will +be created if it does not already exist. + + cl> type file >> outfile + +The redirect-append operator ">>" may be used to append the output of any +task to a file. + +.ih +NOTES +All input files should be of the same type, either all "text" or all +"binary". +.ih +SEE ALSO +copy, type +.endhelp diff --git a/pkg/system/doc/copy.hlp b/pkg/system/doc/copy.hlp new file mode 100644 index 00000000..9c58566d --- /dev/null +++ b/pkg/system/doc/copy.hlp @@ -0,0 +1,47 @@ +.help copy Nov84 system +.ih +NAME +copy -- copy a file, or a set of files to a directory +.ih +USAGE +copy input output +.ih +PARAMETERS +.ls input +The input file or list of files to be copied. +.le +.ls output +The (new) output file when copying one file to another, or the destination +directory when copying a set of files. +.le +.ls verbose = no +If set to "yes", a line of the type " from -> to " is printed on the +terminal for each file copied to a directory. This parameter is not +used when copying one file to another. +.le +.ih +DESCRIPTION +Copy makes a copy of a single file, or it copies a set of files to a different +directory. +.ih +EXAMPLES + +1. Copy all files in the current directory with extension ".x" to the +directory "home$src". As each copy is made, the user is informed. + + cl> copy *.x home$src ver+ + +2. Make a copy "fred.BAK" of the file "fred". + + cl> copy fred fred.BAK + +3. Copy the "graphcap" file from the remote node "lyra" to the current node, +without changing the name of the file. Note that "." is a synonym for the +current directory. + + cl> copy lyra!dev$graphcap . + +.ih +SEE ALSO +concatenate, movefiles +.endhelp diff --git a/pkg/system/doc/count.hlp b/pkg/system/doc/count.hlp new file mode 100644 index 00000000..09601019 --- /dev/null +++ b/pkg/system/doc/count.hlp @@ -0,0 +1,44 @@ +.help count Nov84 system +.ih +NAME +count -- determine number of lines, words and characters in a file +.ih +USAGE +count files +.ih +PARAMETERS +.ls files +A template specifying the files to be examined. +.le +.ih +DESCRIPTION +For each file, count determines the number of lines, words, and +characters in the file. A word is defined as a sequence of characters +delimited by one or more blanks or tabs, or by the end of a line. +If \fIcount\fR is run on more than one file, each output line is identified +by the file name, and a final output line gives the total number +of lines, words, and characters in all files. +.ih +EXAMPLES + +1. Count the number of lines, words and characters in all files in the +current directory with the extensions ".x" and ".h". + + cl> count *.[xh] + +2. Count the number of .x files in the current directory. + + cl> dir *.x op=1 | count + +3. Count the number of \fIset\fR environment definitions. + + cl> set | count + +4. Count the number of references to the READ function in all .x files in +the current directory. + + cl> match "read#(" *.x | count +.ih +SEE ALSO +directory +.endhelp diff --git a/pkg/system/doc/deallocate.hlp b/pkg/system/doc/deallocate.hlp new file mode 100644 index 00000000..803c9d6a --- /dev/null +++ b/pkg/system/doc/deallocate.hlp @@ -0,0 +1,34 @@ +.help deallocate Jan86 system +.ih +NAME +deallocate -- deallocate a device +.ih +USAGE +deallocate device +.ih +PARAMETERS +.ls device +The device to be deallocated. +.le +.ls rewind = yes +Rewind the device before deallocating? +Ignored for devices other than magtape. +.le +.ih +DESCRIPTION +Deallocate a previously allocated device. The CL will print an error +message if one attempts to logout while devices are still allocated, +but if \fIlogout\fR is typed several times you will be allowed to logout +with the devices still allocated. The CL does not automatically +deallocate devices upon logout. +.ih +EXAMPLES + +1. Deallocate logical magtape drive B. + + cl> dealloc mtb + +.ih +SEE ALSO +allocate, devstatus, file dev$devices, dev$tapecap +.endhelp diff --git a/pkg/system/doc/delete.hlp b/pkg/system/doc/delete.hlp new file mode 100644 index 00000000..78ac7df3 --- /dev/null +++ b/pkg/system/doc/delete.hlp @@ -0,0 +1,57 @@ +.help delete Nov84 system +.ih +NAME +delete -- delete a file or files +.ih +USAGE +delete files +.ih +PARAMETERS +.ls files +The list of files to be deleted. +.le +.ls verify = no +Check with the user before deleting a file. If verify is enabled the file +name is printed and the user is queried before the default action is taken. +.le +.ls default_action = yes +This is the default action to take when operating in "verify" mode. +For example, if the default action is "yes", one need only type RETURN in +response to the verify prompt to delete the file. +.le +.ls allversions = yes +Delete all versions of a file. This parameter has no effect on systems like +UNIX which do not support multiple file versions. +.le +.ls subfiles = yes +Delete subfiles. Not currently used. +.le +.ih +DESCRIPTION +\fIDelete\fR destroys a file or files and returns the space they occupied to +the host system, to be reused for other files. Once a file has been deleted, +it is gone forever (unless a copy exists somewhere). Enabling \fIverify\fR +gives one the opportunity to say yes or no before each file is deleted; this +is particularly useful when \fIfiles\fR is a template. Note that +\fIprotect\fR can be used to protect files from deletion, accidental or +otherwise. Imagefiles are automatically protected by the system to remind +the user to use \fIimdelete\fR to delete images (this is necessary because +an image is stored in more than one physical file). +.ih +EXAMPLES + +1. Delete all files with extension ".x", verifying each file deletion before +it is performed. + + cl> delete *.x ver+ + +2. List all files in the current directory, deleting only those files for +which the user responds to the verify prompt with "yes" or "y". Note that +"delete *" is a very dangerous operation. + + cl> delete * ver+ def=no + +.ih +SEE ALSO +protect, unprotect, imdelete +.endhelp diff --git a/pkg/system/doc/devstatus.hlp b/pkg/system/doc/devstatus.hlp new file mode 100644 index 00000000..bccd7ffe --- /dev/null +++ b/pkg/system/doc/devstatus.hlp @@ -0,0 +1,57 @@ +.help devstatus Jan86 system +.ih +NAME +devstatus -- print status information for a device +.ih +USAGE +devstatus device +.ih +PARAMETERS +.ls device +The device for which status information is requested. +.le +.ls verbose = no +Print additional system dependent device information (may not be implemented +on all systems). +.le +.ih +DESCRIPTION +\fBDevstatus\fR tells whether the named device has been allocated. +In the case of a magtape drive allocated to the current user, additional +information is printed noting the tape position and the type of operation +last performed. If the device is not currently allocated, i.e., available +for allocation, or if the device has already been allocated by another user, +one of the following messages is printed: + +.nf + device is not currently allocated + device is allocated to XXXX +.fi + +A list of the allocatable devices, including the host system names for the +devices, can be obtained by paging the file \fBdev$devices\fR providing +that file has been properly configure by the Site Manager at installation +time. The dev$tapecap file is used to define the tape devices available +on the system. +.ih +EXAMPLES + +1. Get status information for the logical tape drive "mta", which we have +just allocated. Note that the tape position is printed only if we are the +owner of the drive. + +.nf + cl> dev mtb + # Magtape unit `mta' allocated to `smith' Fri 12:04:16 07-Jan-86 + file = 1 + record = 1 + unit just allocated: no i/o has yet occurred +.fi + +.ih +BUGS +Information can only be requested for a single device at a time. +.ih +SEE ALSO +allocate, deallocate +.endhelp diff --git a/pkg/system/doc/directory.hlp b/pkg/system/doc/directory.hlp new file mode 100644 index 00000000..8c4382e9 --- /dev/null +++ b/pkg/system/doc/directory.hlp @@ -0,0 +1,148 @@ +.help directory Mar87 system +.ih +NAME +directory -- list the contents of a file directory +.ih +USAGE +directory [files] +.ih +PARAMETERS +.ls files +A file template specifying the files to be listed, or the name of the directory +whose contents are to be listed. If omitted entirely, the contents of the +current directory are listed. +.le +.ls long = no +Long format listing. The long format listing lists each file on a separate +line, noting the file permissions, file type, file size, modify date, owner, +etc. of each file. +.le +.ls ncols = 0 +If nonzero, the number of columns of output in multicolumn format. +.le +.ls maxch = 18 +The maximum number of characters to be displayed in each filename. +Truncation may be desirable when listing a directory containing one or two +files with very long filenames. +.le +.ls sort = yes +Sort the file list alphabetically. If sorting is disabled the directory +program lists the files in the order in which they are read from the +directory, which may or may not be sorted. The directory listing is produced +line by line as files are read from the directory, rather than accumulating +the entire file list in memory before composing the table, hence this is the +fastest method of listing a directory, particularly if the directory is very +large. +.le +.ls all = no +List all files, including the hidden ("." prefixed) files, and files with +reserved filename extensions used internally by the VOS. +.le +.ih +DESCRIPTION +The \fBdirectory\fR task lists or prints information describing some subset +of the files in a directory or directories. If no name template is given, +"." is assumed, i.e., all files in the current directory are listed. + +The long format listing gives a file type string, followed by +the name of the owner of the file, the file size, date and time at which +the file was last modified, and lastly the file name. +The file type string has fields noting if the file is a directory file (d), +an executable file (x), a text or binary file (t or b), a protected file (p), +and summarizing the file permissions (read or write, r or b) for the owner, +the group, and the rest of the world. A minus sign indicates that the file +does not have that particular attribute. + +All file names are printed in the IRAF virtual filename syntax, which is the +same on all host machines. IRAF filenames may be up to 32 characters in +length, may contain any combination of alphanumeric characters, underscore, +or period, and are case sensitive. Some of the common filename extensions +are listed below; these are mapped to and from the host filename extensions +when a file is accessed, a directory is listed, or a filename template is +expanded. + +.nf + .a object library + .c C source file + .cl CL source file + .e executable (runnable) file + .f Fortran source file + .gX generic source file (X=[cx]) + .h global header file + .hlp help file + .o object file + .par CL parameter file + .s assembler source file + .x SPP source file +.fi + +When listing large directories, the time required to accumulate and sort the +entire directory in memory before producing the output listing may become +significant (i.e., more than a few seconds). If this happens, try setting +the \fIsort\fR option to \fIno\fR, and the directory listing should appear +immediately. +.ih +EXAMPLES + +1. List all the files in the current directory in tabular format. + + cl> dir + +2. Print detailed information on all files in the current directory. + +.nf + cl> dir l+ + -t-rwr-r- iraf 269 Oct 16 1983 README + dt-rwrwr- iraf 1024 Feb 7 12:48 doc + -t-rwr-r- iraf 60 Jan 30 1984 files.par + -t-rwr-r- iraf 420 Jan 30 1984 files.x + -b-rwrwr- system 187338 Jan 29 19:27 libpkg.a + xb-rwr-r- iraf 363520 Jan 29 19:29 x_system.e + -b-rwrwr- system 5037 Jan 19 22:15 x_system.o + -t-rwr-r- iraf 633 Jan 19 22:01 x_system.x +.fi + +3. Print a single column listing of all the files with extension ".h" +in the logical directory "lib$". + +.nf + cl> dir lib$*.h l+ + lib$chars.h + lib$clio.h + lib$clpopn.h + (etc) +.fi + +4. While in the "system" directory, print the contents of the parallel +directory "dataio". + +.nf + cl> cd pkg$system + cl> dir ../dataio +.fi + +5. Test if the file "alpha" exists in the current directory. In the example, +the output given indicates that the file was not found. + +.nf + cl> dir alpha + no files found +.fi + +6. Print the contents of the directory USR$2:[IRAF.LOCAL] on the remote VMS +node "draco" (requires IRAF network access to the remote node). + +.nf + cl> dir draco!usr\$2:\[iraf.local] +.fi +.ih +BUGS +There is no provision for wildcarding directories, e.g., "dir */*.x". +The long format listing can currently only be sorted by filename (although +the \fIsort\fR program may be used in a pipe). The file existence test will +not be performed if individual files are named as list elements within +a filename template. +.ih +SEE ALSO +files, pathnames +.endhelp diff --git a/pkg/system/doc/diskspace.hlp b/pkg/system/doc/diskspace.hlp new file mode 100644 index 00000000..538f308d --- /dev/null +++ b/pkg/system/doc/diskspace.hlp @@ -0,0 +1,33 @@ +.help diskspace Feb85 system +.ih +NAME +diskspace -- summarize disk space utilization +.ih +USAGE +diskspace +.ih +DESCRIPTION +\fIDiskspace\fR lists the disk devices available on the host system, +giving the name, capacity, and free space available on each device. +The format and contents of the output are host system dependent. +.ih +EXAMPLE + +1. Print the available diskspace (UNIX host). + +.nf + cl> disk + Filesystem kbytes used avail capacity Mounted on + /dev/hp0a 7421 5312 1366 80% / + /dev/hp0g 38430 5340 29246 15% /tmp + /dev/hp0h 51598 38848 7590 84% /usr + /dev/ra0a 8007 5657 1549 79% /mnt + /dev/ra0d 88179 46043 33318 58% /u1 + /dev/ra0e 54382 46694 2248 95% /local + /dev/ra0f 145435 93733 37158 72% /u2 + /dev/ra0g 28720 350 25497 1% /usr/spool + /dev/ra0h 79798 41696 30122 58% /iraf + /dev/ra1h 397102 306688 50702 86% /tmp2 + /dev/ra2h 397102 275010 82380 77% /tmp3 +.fi +.endhelp diff --git a/pkg/system/doc/fcache.hlp b/pkg/system/doc/fcache.hlp new file mode 100644 index 00000000..b5230307 --- /dev/null +++ b/pkg/system/doc/fcache.hlp @@ -0,0 +1,140 @@ +.help fcache Jun2011 system +.ih +NAME +fcache -- list, clean or manipulate the file cache +.ih +USAGE +fcache cmd +.ih +PARAMETERS +.ls cmd +Cache command to execute. A description of each command is given below. +.le +.ls pattern = "*" +Filename substring pattern to match when initializing the cache with +the \fIinit\fR command. +.le +.ls src = "" +Source string used to generate the cache filename. This is typically +the full path to a local file being cached or a URL. +.le +.ls fname = "" +Name of the file in the cache. +.le +.ls extn = "" +Cache filename extension. +.le +.ls age = -1 +Age of the file (in days) to be purged with the \fIpurge\fR command. A value +less than zero means that the \fIcache_age\fR environment variable should +is used to set the age, a value of zero means to delete all files in the +cache (same as the \fIinit\fR command), a value greater than zero means +that files older than this age will be deleted. +.le +.ls verbose = no +Print status information as the task processes the command. +.le +.ls wait = yes +Block on operation? If 'yes' then the task will block until the requested +file becomes available in the cache. +.le +.ls cache = "cache$" +Cache directory to be used. +.le + +.ih +DESCRIPTION +The \fIFCACHE\fR command is used to list or manage the system file cache +named by the \fIcache\fR parameter. If the \fIcache\fR directory does not +exist, it will be created when required. The \fIcache_age\fR environment +variable determines the default maximum age of files in the cache, older +files are automatically removed by the login.cl as part of the startup +process. + +The IRAF file cache is used primarily to cache local copies of URLs in the +system to prevent repeated downloads when accessing URLs from tasks. This +allows a URL to be passed to multiple tasks without explicitly requiring +the user to create a named (temporary) file themselves. + +The \fIcmd\fR parameter determines the action to take, other parameters are +used as needed depending on the command according to the following table: + +.nf + Command Input Pars Output Pars Action + ------- ---------- ----------- ------ + init pattern Initialize the cache + purge age Purge old files + destroy Destroy the cache + list List cache contents + lookup src fname,extn Lookup a file in the cache + access src Is file in cache? + add src extn fname Add file to the cache + delete src fname Delete file from cache + wait src Wait for access to file +.fi + +The \fIlookup\fR command works in two ways: If a \fIsrc\fR string is +provided then the \fIfname\fR parameter will contain the matching cached +file (and \fIextn\fR will contain the optional extension), if the \fIfanme\fR +parameter is specified then on output \fIsrc\fR will contain the original +filename/URL. + +.ih +EXAMPLES + +1. Remove all "url" files from the cache. +.nf + cl> fcache init pattern="url" +.fi + +2. List the contents of the file cache. +.nf + cl> fcache list +.fi + +3. Destroy a cache directory (i.e. remove it entirely). +.nf + cl> fcache destroy cache="/tmp/cache" +.fi + +4. Purge all cache files older than 7 days: +.nf + cl> fcache purge age=7 +.fi + +5. Determine if a URL is already in the cache: +.nf + cl> fcache add src="/tmp/dpix.fits" + cl> fcache list + f1128531670 1 /tmp/dpix.fits + f789045894 1 http://iraf.noao.edu/vao/dpix.fits + cl> fcache access src="/tmp/dpix.fits" + yes + cl> fcache access src="http://iraf.noao.edu/vao/dpix.fits" + yes +.fi + +6. Delete a cached URL: +.nf + cl> fcache delete src="http://iraf.noao.edu/vao/dpix.fits" +.fi + +7. Add a local file to the cache, then look it up: +.nf + cl> fcache add src="/tmp/test.fits" + cl> fcache lookup src="/tmp/test.fits" + cl> =fcache.fname + f1295587026 + cl> fcache lookup fname="f1295587026" + cl> =fcache.src + /tmp/test.fits +.fi + + +.ih +BUGS + +.ih +SEE ALSO +head +.endhelp diff --git a/pkg/system/doc/files.hlp b/pkg/system/doc/files.hlp new file mode 100644 index 00000000..f2a0996f --- /dev/null +++ b/pkg/system/doc/files.hlp @@ -0,0 +1,72 @@ +.help files Jun86 system +.ih +NAME +files -- expand a file name template into a list of files +.ih +USAGE +files template +.ih +PARAMETERS +.ls template +A file name template specifying the set of files to be listed. +.le +.ls sort = "yes" +Sort the file list. +.le +.ih +DESCRIPTION +\fIFiles\fR lists all files matching the given template. The existence of +the listed files is checked only if pattern matching is used, hence \fIfiles\fR +may also be used to parse a comma delimited list of strings which are not +necessarily filenames. \fIFiles\fR performs the same function as "dir l+" +but is simpler and more convenient to use when generating file lists. + +The \fIfiles\fR task and all other tasks which operate upon groups of files +use the \fBfile template\fR facility to specify the set of files to be +operated upon. This should not be confused with the \fBimage template\fR +facility, used by tasks which operate upon sets of images and which is +documented in the manual page for the \fIsections\fR task. + +Pattern matching in a file template is provided by the usual pattern matching +meta-characters "*?[]", documented in the CL User's Guide. Pattern matching +is used to select files from one or more directories. In addition, the +filename template notation provides two operators for generating new filenames +from the matched filenames. These are the \fBconcatenation\fR operator "//", +and the \fBstring substitution\fR operator "%chars%newchars%". +The concatenation operator concatenates either a prefix to a filename, +or a suffix to the root of a filename. The string substitution operator +uses the "chars" to match filenames, and then replaces the "chars" by the +"newchars" to generate the final output filename. Either string may be null +length to insert into or delete characters from a filename. +.ih +EXAMPLES + +1. Generate a single column list of files in the current directory, +sorted in ASCII collating sequence. + + cl> files + +2. Generate an unsorted single column list of files in logical directory +"lib$". Each entry in the output list is of the form "lib$...". + + cl> files lib$ sort- + +3. Generate a file list to be used to make a set of new files. The new file +names will be the old file names with "_1" concatenated to the root, e.g., +"root.x" would map to "root_1.x" and so on. + + cl> files root.*//_1 + +4. Generate a file list similar to that in [3], adding a directory prefix +to each filename. + + cl> files dir$//root.* + +5. Use string substitution to change the filename extension of a set of files +to ".y". + + cl> files root.%*%y% +.ih +SEE ALSO +directory, pathnames, images.sections +.endhelp diff --git a/pkg/system/doc/gripes.hlp b/pkg/system/doc/gripes.hlp new file mode 100644 index 00000000..3938e1ea --- /dev/null +++ b/pkg/system/doc/gripes.hlp @@ -0,0 +1,67 @@ +.help gripes Mar86 system +.ih +NAME +gripes -- send gripes or suggestions to the system +.ih +USAGE +gripes subject +.ih +PARAMETERS +.ls subject +The subject of the gripe; any string, usually the name of package or task +to which the gripe refers. +.le +.ls verbose = yes +Print instructions on how to enter text whenever \fIgripes\fR is run. +.le +.ih +DESCRIPTION +The \fBgripes\fR task is used to post complaints, suggestions, or any other +formal or informal comments regarding the IRAF system. Each gripe is +appended to the system gripesfile "hlib$gripesfile", a public file which +can be read by anyone by simply typing "page hlib$gripesfile" within IRAF. +Use \fBtail\fR instead of \fBpage\fR to read only the most recent gripes. +A copy of each gripe is also sent immediately to one or members of the IRAF +group via electronic mail, to insure that the gripe gets read promptly (this +feature is not available on all host systems). + +Gripe text is read from the standard input. A line containing only a period +terminates the gripe, as does the end of file character (e.g., <ctrl/z>). +If the line containing only "~e" is entered a text editor will be called up +to edit the text of the gripe. + +Users are encouraged to use the gripe facility at will. Be assured that +someone will at least read the gripe, although there is no guarantee that +any action will be taken. In many cases there will be no response from the +system, but nonetheless the gripe will be seen and it may well influence +the direction in which the system evolves. Do not avoid posting gripes for +fear that you do not understand something about the system; if enough users +find some aspect of the system or a program confusing then that is more +than sufficient reason for a gripe. +.ih +EXAMPLES + +1. The user has discovered some nasty features of the \fIimdelete\fR task +and enters the following gripe. Note the use of the "." to terminate +the text. + +.nf + cl> gripe + Subject: image deletion + Enter text of gripe. Type <eof> or '.' to quit: + + IMDEL * will delete non image files as well as images! + It should be possible to delete images with the normal + DELETE command. + . + cl> +.fi +.ih +BUGS +There is currently no provision for communicating gripes from a remote site +back to the site that wrote the software, unless some person manually mails +a gripe (or the accumulated gripesfile). +.ih +SEE ALSO +news +.endhelp diff --git a/pkg/system/doc/head.hlp b/pkg/system/doc/head.hlp new file mode 100644 index 00000000..0b2f6393 --- /dev/null +++ b/pkg/system/doc/head.hlp @@ -0,0 +1,39 @@ +.help head Nov84 system +.ih +NAME +head -- print the first few lines of the specified files +.ih +USAGE +head files +.ih +PARAMETERS +.ls files +The list of files to be dealt with, quite possibly given as +a template, such a "image*". +.le +.ls nlines = 12 +The number of lines to be printed. +.le +.ih +DESCRIPTION +\fIHead\fR prints, on the standard output, the first \fInlines\fR of each +file that matches the given file list. If the file list has more than one +name in it, a short header precedes each listing. +.ih +EXAMPLES + +1. Print the first 12 lines of each help file in the current directory. + + cl> head *.hlp + +2. Print the first line of each help file. + + cl> head *.hlp nl=1 + +3. Print the most recently defined \fIset\fR environment definitions. + + cl> set | head +.ih +SEE ALSO +tail, page +.endhelp diff --git a/pkg/system/doc/help.hlp b/pkg/system/doc/help.hlp new file mode 100644 index 00000000..74a53917 --- /dev/null +++ b/pkg/system/doc/help.hlp @@ -0,0 +1,599 @@ +.help help Oct01 system +.ih +NAME +help -- print online documentation for the named modules or packages +.ih +USAGE +help [template] +.ih +PARAMETERS +.ls template +A string listing the modules or packages for which help is desired. +Each list element may be a simple name or a pattern matching template. +Abbreviations are permitted. If \fItemplate\fR is omitted a long format +menu will be printed for the current package, listing each task (or +subpackage) and describing briefly what it is. +.le +.ls file_template = no +If this switch is set the template is interpreted as a filename matching +template, and all help blocks found in the named files are output. The help +database is not searched, hence manual pages can be printed or documents +may be formatted without entering the files into a help database. +In other words, "help file.hlp fi+" makes it possible to use \fIhelp\fR as +a conventional text formatter. +.le +.ls all = no +Print help for all help modules matching \fItemplate\fR, rather than only the +first one found. +.le +.ls parameter = "all" +If the value of this parameter is not "all", only the help text +for the given parameter will be printed. +.le +.ls section = "all" +If the value of this parameter is not "all", only the help text for the +given section (e.g. "usage", "description", "examples") will be printed. +.le +.ls option = help +The option parameter specifies the type of help desired, chosen from +the following: +.ls help +Print the full help block for the named module. +.le +.ls source +Print the source code for the module (which often contains additional +detailed comments). +.le +.ls sysdoc +Print the technical system documentation for the named module. +.le +.ls directory +Print a directory of all help blocks available for the named package. +.le +.ls alldoc +Print all help blocks in the file containing the help block for +the named procedure (i.e., both the user and system documentation). +.le +.ls files +Print the names of all help files associated with the named modules or +packages. +.le +.ls summary +Print only the titles and sizes of help blocks in referenced help files. +The contents of the blocks are skipped. Titles are printed for \fIall\fR +help blocks found in the file containing the help block for the named module. +.le +.le +.ls page = yes +Pause after every page of output text. Turning this off for large documents +speeds up output considerably. +.le +.ls nlpp = 59 +The number of lines per page if output is redirected, e.g., to \fIlprint\fR. +.le +.ls lmargin = 1 +Left margin on output. +.le +.ls rmargin = 72 +Right margin on output. +.le +.ls search = no +If enabled the +.hr #l_template template +is interpreted as a search string and the task +is started with the search panel open with the results of the search. The +.hr #l_file_template file_template +parameter is ignored with search turned on. +.le +.ls home = "" +The home page for the task. If not set and no +.hr #l_template template +is specified +the task will start with the online help in the main window, otherwise it +may be set to a filename to be displayed when the task starts. This file +may contain a text help block which will be formatted before display, or +it may be a valid HTML file. See below for a description of the format of +a homepage file which provides links to tasks. +.le +.ls printer = "printer" +Default hardcopy printer name. If the \fIvalue\fR of the parameter is the +reserved string "printer", the actual device is the value of the CL +environment variable \fIprinter\fR. +.le +.ls showtype = no +Add task-type suffix in package menus? +.le +.ls quickref = "uparm$quick.ref" +Name of the quick-reference file used for searching. This file is created +the first time the task is run in GUI mode or whenever it doesn't exist, +or when any help database file has been updated. +.le +.ls uifname = "lib$scr/help.gui" +The user interface file. This file is what defines the look and behavior +of all the graphical user interface elements. Experts may create variants +of this file. +.le +.ls helpdb = "helpdb" +The filename of the help database to be searched. If the \fIvalue\fR of the +parameter is the reserved string "helpdb", the actual filename is the value +of the CL environment variable \fIhelpdb\fR. +.le +.ls device = "terminal" +Output device if the standard output is not redirected. Allowable values +include: +.ls terminal +If the \fIvalue\fR of +the parameter is the reserved string "terminal", the actual device name is +the value of the CL environment variable \fIterminal\fR. +.le +.ls text +Output the formatted help page as plain text. +.le +.ls gui +Invoke the GUI for browsing the help system. This option will only work if +the \fIstdgraph\fR environment variable is set the \fIxgterm\fR, and the +user is running IRAF from an \fIXGterm\fR window. +.le +.ls html +Output the formatted help page as HTML text. +.le +.ls ps (or postscript) +Output the formatted help page as postscript. +.le +.le +.ih +BASIC USAGE +Despite the complex appearing hidden parameters, \fBhelp\fR is easy to use +for simple tasks. \fBHelp\fR is most commonly used to get help on the current +package, and to get help on a program named in a CL menu. To get help on +the current package one need only type \fBhelp\fR without any arguments. +For example, if the current package is \fBplot\fR, the command and its output +might appear as follows: + +.nf + pl> help + contour - Make a contour plot of an image + graph - Graph one or more image sections or lists + pcol - Plot a column of an image + pcols - Plot the average of a range of image columns + prow - Plot a line (row) of an image + prows - Plot the average of a range of image lines + surface - Make a surface plot of an image + pl> +.fi + +To get help on a module one supplies the module name as an argument, + + pl> help graph + +and the manual page for the \fBplot.graph\fR program will be printed on the +terminal. To get a hardcopy of the manual page on the printer, the output +may be redirected to the line printer, as follows: + + pl> help graph | lprint +.ih +DESCRIPTION +The function of the \fBhelp\fR program is to perform a depth first search +of the help database \fIhelpdb\fR, printing help for all packages and modules +matching the template. By default the standard IRAF help database is searched, +but any other help database may be searched if desired. A help database is +precompiled with the \fBmkhelpdb\fR program to speed up runtime searches for +help modules. The standard IRAF help database contains the documentation and +source for all CL programs and system and math library procedures installed +in IRAF. + +A help template is a string type parameter to the CL. The form of a template +is a list of patterns delimited by commas, i.e., + + "pattern1, pattern2, ..., patternN" + +The form of a pattern is + + package_pattern.module_pattern + +If the "." is omitted \fImodule_pattern\fR is assumed. The standard pattern +matching meta-characters, i.e., "*?[]", are permitted in patterns. +Simple patterns are assumed to be abbreviations. + +.ih +GUI OPERATION + +The GUI component of the task is a front-end to the IRAF +.hr system.help \fBhelp\fR +task which provides on-the-fly conversion of help documents to HTML for +presentation in the GUI or formatted PostScript for hardcopy. +The GUI is started by setting the +.hr #l_device \fIdevice\fR +parameter to the special value \fIgui\fR, it is only available when using +an XGterm window to start IRAF and assuming the \fIstdgraph\fR environment +variable is set to \fRxgterm\fR. + +Help pages may be loaded on the command line, through use of a +file browser, or by navigating the help databases using a familiar CL +package menu scheme. It also features a search capability similar to the +.hr system.references \fBreferences\fR +task and a complete history mechanism. + +When invoked with no command line arguments the task starts as a browser +and the user is presented with a GUI that has the toplevel CL package menu +in the upper navigation window. The main display window below will contain +any help page specified in the +.hr #l_template template +parameter or loaded on +the command line by specifying the +.hr #l_template template +and +.hr #l_file_template file_template +parameters. If the +.hr #l_search search +parameter is enabled the +.hr #l_template template +is taken to be a search phrase and the database is searched for tasks +matching the keyword and the GUI will appear with the search panel mapped +so the user can select the task help to +view. When no +.hr #l_template template +is given the main display window will start with the page specified by the +.hr #l_home home +parameter, this can be a user-defined HTML file giving links to specific tasks +(see below for details) or if +.hr #l_home home +is empty the display will contain the online help for the task. + +The first time the task is run, or whenever the help database is updated, +a quick reference file (specified by the task +.hr #l_quickref quickref +parameter) and package menu file will be created in the user's \fIuparm\fR +directory to speed up help searching and subsequent startups of the task. + +.ih +NAVIGATING THE HELP SYSTEM +When run as a GUI browser \fIHELP\fR works very much like any WWW browser. +The top panel is a list widget that will always contain a CL package listing, +at startup this will be the toplevel \fI"Home"\fR package menu one would see +when first logging into the CL containing the core system packages, NOAO +package, and any site-specific external package, or in the case of starting +with a specific task it will be the parent package for the task. Additionally, +system documents for the +.hr os \fBos\fR +HSI routines and the +.hr sys.imfort \fBimfort\fR +and +.hr math \fBmath\fR +interfaces will be available in the \fIHome\fR package although +these are programmatic interfaces and not tasks which can be executed. + +New packages or task help pages are loaded by selecting an item from the +package menu list using the left mouse button. If the requested item is a +package, the menu listing will change as though the package were loaded in +the CL, and the help display panel will contain a listing of the package +tasks with a one-line description for each task such as would be seen with +a \fI"help <package>"\fR command using the standard task. New items may then +be selected using either the menu list or links in the display panel. If the +item is a task, the help page for the task will appear in the display panel. +In either case new pages may be selected from the menu listing. + +Specific help documents may also be requested by entering the task/package +name in the \fBTopic\fR text widget above the menu list. As when selecting +from the package menu list, items selected this way will cause the menu +list to change to the package menu for the parent package if the item is a +task (displaying the help page in the display panel) or the package menu +if the item is a package (displaying the one-liner package listing in the +display panel). + +Using the \fBBack\fR button will revert to the previous page in the history +list which will either be the previously loaded package or help page. +Similarly, selecting the \fBForward\fR button will move the next page further +down in the history list, either button will become insensitive when the +end of the list on either end is reached. Selecting the \fBUp\fR button will +cause the browser to immediately jump up the previous package, skipping +over any help pages that were loaded in between. The \fBHome\fR button will +cause the default homepage (either the user-defined page if specified by the +task \fIhome\fR parameter or the online help) to be displayed. Browsing +in this way can also be done using the navigation menu created by hitting +the right mouse button while in the main display panel. + +Users can also jump to specific pages in the history list using the +\fBHistory\fR button on the main menubar. The right column of the menu +will indicate whether the item is a task, package, internal link or a text +file. The history list is truncated at about 40 entries in the menu but +the user may work back incrementally by selecting the last item of the +menu, after which the History button will display the previous 40 entries. +The history list may be cleared except for the current page by selecting +the \fIClear History\fR menu item. + +.ih +BROWSING A HELP DOCUMENT +Once a help page is loaded the middle menubar above the display panel +will change to activate widgets based on the position within the history +list and options available for a particular page. The left-most group +of buttons are the standard navigation buttons described above. +The middle group of buttons contains the \fBSections\fR and +\fBParameters\fR buttons which are used to browse within a help document. +The \fISections\fR button is a menu listing all of the sections found +within a help page, allowing the user to jump to a specific section +rather than scrolling through the entire document. The \fISections\fR +menu is also available using the middle mouse button from the +main display area. The \fIParameters\fR button is similarly a menu +listing of all task parameter help sections found within the document. +Both or either of these buttons will become insensitive when no section +or parameter information is found in the document. + +The right-most group of buttons represent the various help options available +for each page. The default is to get the task help, however help pages +may have an associated \fBsource\fR file or \fBsysdoc\fR (e.g. if the task is +a CL script there may be a pointer to the script source itself, or a package +may have a general overview document listed as the system document). Once +a help page is loaded these buttons will change become sensitive if that option +is available, simply select the button to view the option. Selecting the +\fBFiles\fR button will bring up a panel listing all the files associated +with a particular help topic. When a help topic is selected and an option is +defined but the file does not exist, the options button will display a yellow +diamond icon even if the button is insensitive, a green icon indicates the +currently selected option. This feature may be disabled by selecting the +"Show missing files" item from the main menubar \fBOptions\fR menu. + +.ih +SEARCHING +Searching the help database is done by selecting the \fBSearch\fR button +from the main menubar to bring up the search panel. Users may then enter +one or more keywords into the \fBTopic\fR field at the bottom of the panel +and initiate the search with either a carriage return or hitting the +\fISearch\fR button just beside it. The panel will then show a list of all +tasks and packages which match the search phrase along with a one-line +description of the task. Help pages may be displayed by selecting either the +task or package link with the left mouse button, in both case the package +menu list on the main help window will be updated to list the package +contents allowing other tasks from that package to be selected in the normal +way. + +By default the exact phrase entered in the topic window will be used for the +search. This can be relaxed by toggling the "Require exact match" button +at the top of the panel. For example, to search for all tasks matching +\fIeither\fR the keyword "flat" or "field" turn off the exact match +toggle and the search will return not only tasks matching "flat field" but +also any task description containing only one of the words such as the +VELVECT task which plots velocity \fIfield\fRs. + +Within a help document itself one can search for a string by selecting +the \fBFind\fR button from the main menubar to bring up a panel used to +enter the search string. When the text is entered the main display +window will reposition itself and highlight the text found within the +document. Searches can be repeated and will wrap around the document +automatically, searches can be done either forward or backward through +the text and may be case insensitive. + +.ih +USER_DEFINED HOME PAGES +By default the \fIhelp\fR GUI will start with the online help page displayed +in the main help window. The user can change this by setting the task +\fBhome\fR parameter to be a path to any valid file. This file may be plain +text, a help document in LROFF format which will be converted to HTML for +display, or a native HTML document. + +HTML files may contain URLs of the form +.nf + \fB<a href=\fI[package.]task\fB>\fIurl_text\fB</a> +.fi + +where \fIurl_text\fR is the text to appear in the window and the URL itself +consists of an optional package and task name delimited by a period. For +example, to create a link to the +.hr onedspec.splot \fBsplot\fR +task in a document one would use the URL +.nf + \fB<a href=onedspec.splot>splot</a>\fR +.fi + +In this way users can create a homepage which serves as a \fI"bookmark"\fR +file or index of shortcuts to the most commonly accessed help pages. + +.ih +LOADING FILES +Text files may be loaded on the command line when starting the task by +specifying the filename and setting the +.hr #l_file_template file_template +task parameter. The named file +will be searched for a \fI.help\fR LROFF directing indicating it contains +a help block that will be converted to HTML for display. If no help +block is found the file will be displayed as-is, meaning existing +HTML documents can be loaded and will be formatted correctly. + +Once the task is running users may load a file by selecting the \fBOpen +File...\fR menu item from the main menubar \fBFile\fR menu or the +right-mouse-button menu from within the main display area. This will +open a file browser allowing users to change directories by using the +navigation buttons at the top of the panel, or selecting items from the +leftmost directory listing. Selecting a file on the rightmost list will +cause it to be loaded and automatically formatted if it contains a help +block. The file list may be filtered to select only those files matching +a particular template by changing the \fBFilter\fR box at the top of +the panel. Filenames or directories may be entered directly using the +\fBSelection\fR box at the bottom of the panel. + +.ih +SAVING FILES +Once a file has been loaded in the browser it may be saved to disk as +either \fIsource\fR (i.e. the original LROFF file if that was converted +for the display, or whatever file is currently displayed regardless of +format), \fItext\fR to save formatted plain text such as that produced +by the standard \fBhelp\fR task, \fIHTML\fR to save the converted HTML +used in the display, or \fIPostScript\fR to save formatted PostScript of +the document such as that sent to the printer using the \fBPrint\fR +button. Not all options will be available depending on the format of the +input text, unavailable options will be insensitive in the GUI. + +The \fBSave\fR panel is opened by selecting the \fBSave As...\fR menu +item from the main menubar \fBFile\fR menu or the right-mouse-button +menu from within the main display area. The file browser operates the +same as when loading images, the only difference is that file selection +simply defines the filename to be used and does not cause the save to +occur automatically. Users can overwrite existing files by selecting the +\fIOptions\fR toggle at the bottom of the panel. + +.ih +HARDCOPY OUTPUT AND SAVING DISK FILES. +Help pages may be output to any configured IRAF printer by selecting the +main menubar \fBPrint\fR button to bring up the print panel. Task help pages +will be converted to formatted PostScript and may be sent to either a +printer or saved to disk depending on the selection made in the printer +panel. If the printer name is set to the special value \fI"printer"\fR then +the device named by the CL \fIprinter\fR environment variable will be used. +When saving to disk files the default action is to save to a filename whose +name is the task name plus a ".ps" extension. Either of these are changeable +within the GUI as is the default page size to be used when generating the +PostScript. + +The main menubar \fBFile\fR button can also be used to bring up the file +browser in order to save the current document to disk. Help pages may be +saved as either the origin LROFF source for the file, formatted text as you +would get from the standard help task, HTML as is displayed in the GUI, or +formatted PostScript. The choice of formats is dictated by the type of file +being displayed (e.g. you cannot save PostScript of a program source). + +.ih +LROFF DIRECTIVE EXTENSIONS FOR HTML +To better support HTML links within documents and to other help pages two +new directives have been added to the LROFF text formatter. These are +\fB.hr\fR to specify a link (an HTML \fIHREF\fR directive) and \fB.hn\fR +to specify a name (an HTML \fINAME\fR directive). The syntax for these are +as follows: +.nf + + \fB.hn\fI <name>\fR + \fB.hr\fI <link> <text> \fR +.fi + +where \fI<name>\fR is the destination name of an internal link, \fI<link>\fR +is the URL of the link to be created, and \fI<text>\fR is the text to be +displayed in the HTML. The URL syntax is either a '#' character followed +by a destination name, a simple \fItask\fR name or \fIpackage\fR name, +or a \fIpackage.task\fR pair giving a more precise task. For internal links +the current document is repositioned so the name is at the top of the display, +for task help links new help pages will be loaded in the browser. + +These directives are ignored when converting the LROFF to either formatted +plain text or PostScript. + +.hn examples_target +.ih +GUI EXAMPLES +1) Start \fIhelp\fR as a GUI browser: +.nf + + cl> help dev=gui +.fi + +2) Begin by searching for the phrase 'gauss', tasks and packages may be +selected from the search panel which will appear when the task starts: +.nf + + cl> help gauss dev=gui search+ +.fi + +3) Load an LROFF help page in the browser at startup +.nf + + cl> help mytask.hlp dev=gui file+ +.fi + +.ih +EXAMPLES + +1. Print the help text for the program \fIdelete\fR in the package +\fIsystem\fR (output will be directed to the terminal): + +.nf + cl> help system.delete +or + cl> help delete +or + cl> help del +.fi + +2. Print the help text on the line printer: +.nf + + cl> help delete | lprint +.fi + +3. Print help for the current package: +.nf + + cl> help +.fi + +4. Print the usage section of all modules in the package \fBimages\fR: +.nf + + cl> help images.* section=usage +.fi + +5. Print a directory of all help blocks in the packages \fBclpackage\fR +and \fBclio\fR (and any others whose names begin with the string "cl"): +.nf + + cl> help cl* op=dir +.fi + +6. Print a directory of each package in the database (useful for getting an +overview of the contents of a help database): +.nf + + cl> help * op=dir +.fi + +7. Print the source for all of the string utilities in the system library +package \fBfmtio\fR: +.nf + + cl> help fmtio.str* op=source +.fi + +8. Find all tasks that delete something: +.nf + + cl> help * | match delete +.fi + +9. Print the manual pages for the \fIhelp\fR and \fIlprint\fR tasks on the +default printer device: +.nf + + cl> help help,lprint | lpr +.fi + +10. Capture the manual page for task \fIhedit\fR in a text file, in a form +suitable for printing on any device. +.nf + + cl> help hedit dev=text > hedit.txt +.fi + +11. Print the manual page for task \fIhedit\fR as a Postscript file. +.nf + + cl> help hedit dev=ps | lprint +.fi + +.ih +BUGS +On some systems, typing the next command keystroke before the end-of-page +prompt is printed may result in the character being echoed (messing up the +output) and then ignored when raw mode is enabled for the prompt. + +.ih +SEE ALSO +.hr system.references references +, +.hr system.phelp phelp +, +.hr system.mkhelpdb mkhelpdb +, +.hr system.hdbexamine hdbexamine +, +.hr system.mkmanpage mkmanpage +, +.hr system.lroff lroff +, the online task help documents. +.endhelp diff --git a/pkg/system/doc/lprint.hlp b/pkg/system/doc/lprint.hlp new file mode 100644 index 00000000..33997b0e --- /dev/null +++ b/pkg/system/doc/lprint.hlp @@ -0,0 +1,65 @@ +.help lprint Nov84 system +.ih +NAME +lprint -- print a file or files +.ih +USAGE +lprint files +.ih +PARAMETERS +.ls files +A filename template specifying the files to be printed. +.le +.ls device = "printer" +The output device. If the value of \fIdevice\fR is the reserved string +"printer", the name of the actual printer device is taken from the value +of the environment variable "printer". +.le +.ls map_cc = yes +If set to "yes", any unprintable characters embedded in the text are printed +in the form "^X", where ^A is <ctrl/A> (ASCII 1), and so on. +.le +.ls paginate = "auto" +If \fIpaginate\fR is set to "auto" and the standard input is not redirected, +pages are broken and a header is printed at the top of each page. +If \fIpaginate\fR is set to "auto" and the standard input \fIis\fR redirected, +the input text is not paginated, allowing proper operation when \fIlprint\fR +is used in a pipe, e.g., taking input from \fIhelp\fR. +If "paginate" is set to "yes", pages are broken even if the input text +is being read from STDIN. +.le +.ls label = "STDIN" +If displaying a header with input from the standard input, use the +"label" string where the filename would appear in a normal header. +.le +.ih +DESCRIPTION +The named files, or the standard input, are printed on the standard +line printer device. Each file is printed starting at the top of a new +page, with a header giving the page number and the date of last modification +for the file. Pagination and headers are normally suppressed when reading +input from the standard input, but may be enabled if desired. +.ih +EXAMPLES + +1. Print all files with an extension of either ".x" or ".h", followed by +all files with the extension ".com". Note that filename sorting occurs only +within a comma delimited field of the filename template, hence the "*.[xh]" +files are printed in sort order, followed by the ".com" files. + + cl> lprint *.[xh],*.com + +2. Print the output of the \fIimstat\fR task on the versatec printer, +paginating the output with the given label on each page. Note that the +command may be broken after the "pipe" character without need for +explicit backslash continuation. + +.nf + cl> imstat nite1.* | + >>> lprint pag+ label="Image Statistics" device=versatec +.fi + +.ih +SEE ALSO +type +.endhelp diff --git a/pkg/system/doc/match.hlp b/pkg/system/doc/match.hlp new file mode 100644 index 00000000..3338af3d --- /dev/null +++ b/pkg/system/doc/match.hlp @@ -0,0 +1,77 @@ +.help match Nov84 system +.ih +NAME +match -- match a pattern against the lines in a file or files +.ih +USAGE +match pattern files +.ih +PARAMETERS +.ls pattern +The pattern to be matched. A pattern may contain any of the +pattern matching \fImeta-characters\fR described below. +.le +.ls files +A template specifying the file or files to be searched. Omitted if the +standard input is redirected. +.le +.ls meta-characters = yes +Set to "no" to disable the pattern matching meta-characters, e.g., when +you want to explicitly match one of the meta-characters as a regular character. +.le +.ls stop = no +If \fIstop\fR is enabled, lines with match the pattern are "stopped" (not +passed to the output), otherwise only those lines with match the pattern +are output. +.le +.ls print_file_names = yes +If more than one file is being searched, preface each printed line +with the "file_name: ". +.le +.ih +DESCRIPTION +The listed files are searched for the given pattern, copying each line that +matches to the standard output. If "stop" is set the action is reversed, +i.e., all lines are passed on to the output except those which match the +pattern. If no files are named text is read from the standard input. +The pattern matching meta-characters are described in the table below. + +.nf + ^ matches the beginning of a line + $ matches the end of a line + ? matches any single character + * matches zero or more of whatever is at the left + [12345] matches any single character in the given set + [1-5] matches any single character in a range + [^a-z] matches any character NOT in the range/set + # matches whitespace + {chars} turns off case sensitivity inside the braces + \ used to include a meta-character in the pattern +.fi + +If more than one file is being searched, each output line is prefixed +with its file name. +.ih +EXAMPLES + +1. From all the lines displayed by "set", print only those that have +the string "tty" somewhere in them. + + cl> set | match tty + +2. Find all tasks that delete something. + + cl> help * | match delete + +3. Delete all the "red" objects from the list file "catalog". + + cl> match red catalog stop+ > newcatalog + +4. Type out the file "spool", omitting all lines that end in a colon, +and paginating the output. + + cl> match ":$" spool stop+ | page +.ih +SEE ALSO +lcase, ucase, translit, sort, unique +.endhelp diff --git a/pkg/system/doc/mkdir.hlp b/pkg/system/doc/mkdir.hlp new file mode 100644 index 00000000..de7a03c4 --- /dev/null +++ b/pkg/system/doc/mkdir.hlp @@ -0,0 +1,34 @@ +.help mkdir May85 system +.ih +NAME +mkdir -- make a new directory +.ih +USAGE +mkdir newdir +.ih +PARAMETERS +.ls newdir +New directory or subdirectory to be made. +.le +.ih +DESCRIPTION +\fIMkdir\fR creates a new directory with the given name. +\fINewdir\fR may be an IRAF virtual directory name (not a logical name) +or a host directory name. +.ih +EXAMPLES + +1. Make a subdirectory named "sub1". + + cl> mkdir sub1 + +2. Make a subdirectory "sub2" below "sub1". The subdirectory "sub1" must +already exist. + + cl> mkdir sub1/sub2 + +3. Make a directory "blue" at the same level in the directory hierarchy as +the current directory (".." is a synonym for the previous directory). + + cl> mkdir ../blue +.endhelp diff --git a/pkg/system/doc/mkscript.hlp b/pkg/system/doc/mkscript.hlp new file mode 100644 index 00000000..5aa33204 --- /dev/null +++ b/pkg/system/doc/mkscript.hlp @@ -0,0 +1,161 @@ +.help mkscript Nov85 system +.ih +NAME +mkscript -- make a script for a command sequence to be run in batch +.ih +USAGE +mkscript script task submit +.ih +PARAMETERS +.ls script +Script file name. Commands will be successively added to this file. +.le +.ls task +Task name of command to be added to the script. If given on the command +line then only commands for this task may be added to the script. +If not given on the command line then the task will query for a task +name for each new command. Currently the task name must not be abbreviated. +.le +.ls submit +Submit the completed script as a background job as the last act of the task? +If not given on the command line the task will query before submitting the +script. +.le +.ls append = no +Append new commands to an existing script file? +If no the file will be deleted first. If \fIverify\fR = yes +the user will be asked to confirm the deletion. +.le +.ls hidden = yes +Include hidden parameters in each command? +.le +.ls verify = yes +Verify each command, any file deletions, and the final script? +.le +.ls logfile = "script.log" +Script log file name. When the script is submitted as a background job +by this task any command and error output is directed to this file. +.le +.ih +DESCRIPTION +A command script is created consisting of a number of commands to be +executed sequentially. The task assumes the responsibility of formatting +the command and placing it in the script file. The user sets the +parameter values using the parameter editor \fBeparam\fR. As an optional +final stage the task will optionally submit the script as a background job. + +The sequence of steps are outline as follows: +.ls (1) +If the script already exists and \fIappend\fR = no the script file +is deleted. When \fIverify\fR = yes the deletion is verified with the +user. +.le +.ls (2) +If the task is not specified on the command line then the user +is queried for a task name. +.ls (2a) +The task must be loaded. If it has not been loaded a message is printed +and the task query is repeated. +.le +.le +.ls (3) +\fBEparam\fR is now invoked to allow the user to set the task +parameters. +.le +.ls (4) +If \fIverify\fR = yes the command is printed and the user is asked if the +command is ok. If ok the command is added to the script. +.le +.ls (5) +The user is asked if another command is to be added to the script. While +the response is yes steps 2 to 5 are repeated. +.le +.ls (6) +If \fIverify\fR = yes the script is paged and the user is asked if the +script is ok. If not ok the script is deleted, with user confirmation, +and steps 2 to 6 are repeated. +.le +.ls (7) +If the submit parameter is not specified on the command line the user +is asked if the script should be submitted as a background job. +.le + +The parameter \fIhidden\fR is important for the following reason. If +the hidden parameters are not explicitly included in the script commands +then the values of the hidden parameters will be those in the parameter +file at the time of execution. Thus, in changes in the hidden parameters +with \fBeparam\fR or explicit changes may produce unexpected results. +However, if the hidden parameters are never changed then the commands +are more readable when the hidden parameters are not included. +.ih +EXAMPLES +One of the most common usages in data reductions is to create repeated +commands with different input data or parameters. + +.nf +cl> mkscript script.cl transform + +[\fIeparam\fR is called to set the parameter values for \fItransform\fR] + +transform ("n1r.008", "n1r.008a", "disp012,distort,disp013", +database="identify.db", interptype="spline3", x1=1., x2=256., dx=1., +nx=256., xlog=no, y1=4300., y2=6300., dy=INDEF, ny=800., ylog=no, +flux=yes, logfiles="STDOUT,logfile") + +Is the command ok? (yes): +Add another command? (yes): + +[\fIeparam\fR is called again for task \fItransform\fR] + +transform ("n1r.010", "n1r.010a", "disp013,distort", +database="identify.db", interptype="spline3", x1=1., x2=256., dx=1., +nx=256., xlog=no, y1=4300., y2=6300., dy=INDEF, ny=800., ylog=no, +flux=yes, logfiles="STDOUT,logfile") + +Is the command ok? (yes): +Add another command? (yes): no + +[The script is paged] + +Is the script ok? (yes): +Submit the script as a background job? (yes): +Script script.cl submitted at: +Fri 10:32:57 01-Nov-85 +[1] +.fi + +To combine several tasks: + +.nf +cl> mkscript script.cl ver- sub- hid- +Task name of command to be added to script: response + +[\fIeparam\fR is called for \fIresponse\fR and parameter values are set] + +Add another command? (yes): +Task name of command to be added to script: imarith +... +Add another command? (yes): no +.fi + +To run the command script as a foreground job: + +cl> cl < script.cl + +To run the command script as a background job: + +cl> cl < script.cl >& logfile & + +Note that the output including possible error output is redirected to a logfile. +.ih +BUGS +The current implementation is preliminary. It is done with a script which +makes it seem somewhat slow. The most important bug is that the command +formatter is based on the output of \fBlparam\fR. If a task parameter +name exceeds 12 characters it is truncated by \fBlparam\fR and is then +also truncated by the command formatter. The script will then fail when +executed! Also the task name may not be abbreviated. +.ih +SEE ALSO +eparam +.endhelp diff --git a/pkg/system/doc/movefiles.hlp b/pkg/system/doc/movefiles.hlp new file mode 100644 index 00000000..73374474 --- /dev/null +++ b/pkg/system/doc/movefiles.hlp @@ -0,0 +1,38 @@ +.help movefiles Nov84 system +.ih +NAME +movefiles -- move files to a directory +.ih +USAGE +movefiles files directory +.ih +PARAMETERS +.ls files +A template specifying the file or files to be moved. +.le +.ls directory +The directory to which the files are to be moved. +.le +.ls verbose = no +If set to "yes", tell user as each file is moved. +.le +.ih +DESCRIPTION +This routine moves the specified files to the named directory. +If a subdirectory and a logical directory both exist with the same +name as the destination directory, the subdirectory is used. +.ih +EXAMPLES + +1. Move all files whose names start with `im' and end with `ab' to +the directory `dir'. Since "verbose" defaults to "no", do the work silently. + + cl> movefiles im*ab dir + +2. Move all files in the current directory into the directory one level up. + + cl> move * .. +.ih +SEE ALSO +copy, rename +.endhelp diff --git a/pkg/system/doc/netstatus.hlp b/pkg/system/doc/netstatus.hlp new file mode 100644 index 00000000..059f6819 --- /dev/null +++ b/pkg/system/doc/netstatus.hlp @@ -0,0 +1,44 @@ +.help netstatus Feb86 system +.ih +NAME +netstatus -- print the status of the local network +.ih +USAGE +netstatus +.ih +PARAMETERS +None. +.ih +DESCRIPTION +\fINetstatus\fR prints the status of the local network as perceived by the +system process x_system.e (the network status may differ for each subprocess). +The status output identifies the local node, lists all nodes in the local +network, and lists all the aliases (recognized names) for each node. +A message will be printed if networking is disabled on the local machine. +The local network is defined by the table files "dev$hosts", "dev$uhosts", +and "dev$hostlogin". +.ih +EXAMPLES + +.nf +cl> netstatus +Local node `draco' (5), default node `draco', 12 nodes in local network + + NODE SERVER NREFS STATUS ALIASES + 1 0 0 00000 aquila vax1 a 1 class1 plot print + 2 0 0 00000 lyra vax2 b 2 class2 + 3 0 0 00000 vela vax3 3 v class3 + 4 0 0 00000 carina vax5 c 5 class5 + 5 0 0 00000 draco vax6 6 d class6 0 + 6 0 0 00000 tucana sun1 t + 7 0 0 00000 hydra sun2 h + 8 0 0 00000 mensa pc1 m + 9 0 0 00000 pictor pc2 + 10 0 0 00000 octans sun3 o + 11 0 0 00000 pavo mvax1 p + 12 0 0 00000 volans lsi1 +.fi + +.ih +SEE ALSO +.endhelp diff --git a/pkg/system/doc/news.hlp b/pkg/system/doc/news.hlp new file mode 100644 index 00000000..1b12f24c --- /dev/null +++ b/pkg/system/doc/news.hlp @@ -0,0 +1,58 @@ +.help news Mar90 system +.ih +NAME +news -- print the revisions summary for the current IRAF version +.ih +USAGE +news +.ih +DESCRIPTION +The \fInews\fR task uses the standard IRAF file pager to review a formatted +summary of the system revisions for the version of IRAF being run. +The revisions summaries for older versions of the system are also provided: +use the \fIN\fR and \fIP\fR pager keys to display the next or previous +system revisions summary. The revisions summary is given in the file +"doc$newsfile". + +For reasons of brevity, only the revisions summary is printed. For detailed +information on the revisions made to a particular science package, type + + cl> help <pkg>.revisions op=sys + +where "pkg" is the name of the CL package for which revisions information +is desired. For detailed information on the revisions to the system +software and programming interfaces, examine the system notes file, +given in the file "notes.*" in the directory "iraf$local". The system +notes files for older versions of the system will be found in the "doc" +directory. +.ih +BUGS +The revisions summary is often lengthy and may be easier to read if a +printed copy is made. + +Redirecting the output of \fInews\fR, e.g., to \fIlprint\fR, doesn't work +at present. +.ih +EXAMPLES +1. Page the revisions summary for the current IRAF release. + + cl> news + +2. Print the revisions summary. + + cl> lprint doc$newsfile + +3. Page the system notes file. Anyone who develops software for IRAF +should review this file with each new release, to see what has changed. +Documentation for new system facilities is often given in the system +notesfile. + + cl> page iraf$local/notes.* + +4. Review the revisions summary for the IMAGES package. + + cl> phelp images.revisions op=sys +.ih +SEE ALSO +help, phelp, page +.endhelp diff --git a/pkg/system/doc/page.hlp b/pkg/system/doc/page.hlp new file mode 100644 index 00000000..92cfd105 --- /dev/null +++ b/pkg/system/doc/page.hlp @@ -0,0 +1,146 @@ +.help page Nov86 system +.ih +NAME +page -- display a file or files one page at a time +.ih +USAGE +page files +.ih +PARAMETERS +.ls files +The list of files. If omitted, text is read from the standard input. +.le +.ls map_cc = yes +Map non-printing control characters into printable form, e.g., BEL +(ctrl/G, ASCII 7) is printed as "^G". +.le +.ls clear_screen = no +If set, the screen is cleared before each page is written. +.le +.ls first_page = 1 +The first page to be printed. Pages are defined by form feed characters +embedded in the text. +.le +.ls prompt = "" +Optional prompt string for the end-of-page prompt. If no prompt string is +given the name of the file being paged is used. +.le +.ls device = "terminal" +The output device. The special device \fItext\fR may be specified to +represent standout mode with upper case rather than reverse video characters. +.le +.ih +DESCRIPTION +\fIPage\fR displays a file on the terminal, one page of text at a time, +pausing between successive pages of output until a key is typed on the +terminal. Pages are normally broken when the screen fills, but may also +be delimited by form feed characters embedded in the input text. +A prompt is printed after each page of text naming the current file, +showing the percentage of the file which has been displayed, and the numeric +order of the file within the file list if a file template was given. + +When the end of page prompt is displayed any of the following command +keystrokes may be entered. Command keystrokes are input in raw mode, +i.e., no carriage return is required to pass the command to the program. + +.ks +.nf + . go to the beginning of the current file [BOF] + : colon escape (see below) + ? display a one-line command summary + G go to the end of the current file [EOF] + N,<ctrl/n> go to the next file + P,<ctrl/p> go back to the previous file + b back up one page + d scroll down half a page of text + e edit the current file + f,space advance to the next page + j,return scroll down one line + k back up one line + n search for the next occurrence of a pattern + q quit + u back up half a screen + + <ctrl/c> quit (interrupt) + <ctrl/z> quit (EOF) + <ctrl/d> quit (EOF) +.fi +.ke + +If an unrecognized keystroke is entered the terminal will beep. The following +colon commands are recognized in addition to the single keystroke commands +described above. + +.ks +.nf + :!<clcmd> send a command to the CL (:!! for host command) + :/<pattern> advance to line matching the given pattern + :file <fname> display file "fname" (may be abbreviated) + :help print summary of colon commands + :line [+/-]N goto line N (relative move if +/- given) + :spool <fname> spool output to the named file +.fi +.ke + +The \fI:clcmd\fR facility is used to send commands to the CL from within +the context of the pager. For example, ":!cl" will temporarily suspend the +pager, allowing CL commands to be entered until the command "bye" is entered, +causing execution of the pager to resume. Note that since the \fIpage\fR +task resides in the system process \fIx_system.e\fR, it will be necessary +for the CL to connect a second system process if the command issued calls +another task in the system package, since the first system process will +still be running, i.e., executing the \fIpage\fR task. This is harmless, +but the second process may be removed from the process cache with +\fIflprcache\fR if desired, after exiting the original \fIpage\fR task. + +The sequence ":/" followed by a pattern will cause the current input stream +to be searched for the next occurrence of the pattern given. A pattern once +entered is retained indefinitely and may be used in subsequent searches by +typing the single keystroke `n', without need to reenter the pattern. +Searching stops at the end of the current file, requiring a `.' to wrap back +around to the beginning of the file, or a `N' to advance to the next file. + +The \fI:file\fR command is used to change the current position within the +file list specified by \fIfiles\fR, and may not be used to page a file not +specified in the initial template. Note that the filename may be abbreviated, +and that searching stops with the first file lexically greater than or equal +to the given string (hence ":file x" might return file "y"). + +The \fI:line N\fR command may be used to randomly position to the indicated line +within the current file. If the line number argument N is preceded by a plus +or minus the argument is taken to be an offset from the current position. + +The \fI:spool\fR command is used to spool output to a file. Each time a +file line is printed on the screen, it is appended to the named file as well. +One can interactively position to the desired line of the file and then turn +on spooling to extract a portion of the file or stream being displayed. +A subsequent \fI:spool\fR command with no filename will turn spooling off. +Issuing a \fI:spool\fR to begin spooling on a new file when already spooling +to some other file will cause the old spool file to be closed. +.ih +EXAMPLES + +1. Page through all of the files in the directory "lib" which have +the extension ".h". + + cl> page lib$*.h + +2. Use \fIhelp\fR to format the text in the file "doc$spp.hlp", displaying +the formatted document beginning on page 5 (the entire document has to be +formatted first so it takes a minute or so to get any output). + + cl> help doc$spp.hlp fi+ | page first=5 + +3. Run \fIrfits\fR to print a long format listing of the headers of a series +of FITS images from a magnetic tape, directing the output through \fIpage\fR +so that it does not flash by when you aren't looking. + + cl> rfits mta make- long+ | page +.ih +BUGS +Since \fIpage\fR does not currently buffer any input text, backwards motions +and absolute line positioning are not permitted when paging the standard input. +.ih +SEE ALSO +type, match, head, tail +.endhelp diff --git a/pkg/system/doc/pathnames.hlp b/pkg/system/doc/pathnames.hlp new file mode 100644 index 00000000..3719fe28 --- /dev/null +++ b/pkg/system/doc/pathnames.hlp @@ -0,0 +1,42 @@ +.help pathnames Nov84 system +.ih +NAME +pathnames -- print the host pathnames for a set of files +.ih +USAGE +pathnames [template] +.ih +PARAMETERS +.ls template +A filename template specifying the set of files for which pathnames +are desired. If omitted, the pathname of the current working or default +directory is printed. The list of file names can come from the standard input. +.le +.ls sort = yes +Sort the output in ASCII collating sequence. +.le +.ih +DESCRIPTION +\fIPathnames\fR converts a list of IRAF virtual file names into their host +system equivalents. When called with no arguments, the function of +\fIpathnames\fR is to print the current default directory. +.ih +EXAMPLES + +1. Print the pathname of the current default directory (sample output for +a VMS host system). + +.nf + cl> path + draco!DRB1:[IRAF.SYS.FIO] +.fi + +2. Translate the file "vfiles", containing a list of virtual filenames, into +the equivalent list of host system filenames, e.g., for use as input to a +foreign task. + + cl> path @vfiles > hfiles +.ih +SEE ALSO +directory, files +.endhelp diff --git a/pkg/system/doc/phelp.hlp b/pkg/system/doc/phelp.hlp new file mode 100644 index 00000000..2230eb29 --- /dev/null +++ b/pkg/system/doc/phelp.hlp @@ -0,0 +1,61 @@ +.help phelp Mar90 system +.ih +NAME +phelp -- page the output of the HELP task +.ih +USAGE +phelp template +.ih +PARAMETERS +The \fIphelp\fR parameters are the same as for \fIhelp\fR except that +the \fIpage\fR and \fInlpp\fR parameters are omitted. +.ih +DESCRIPTION +The \fIphelp\fR task is a front end to \fIhelp\fR which spools the output +of \fIhelp\fR in a scratch file, then calls the file pager \fIpage\fR to +view the output text. The advantage is that while \fIhelp\fR pages its +output, one can only move forward through the output text. By using +\fIphelp\fR it is possible to randomly scan the spooled help text, e.g., +skipping forward to get a quick overview and then backing up to read the +details more carefully. This capability is especially useful when viewing +large multipage help pages, or when viewing a number of related help pages +all at once. +.ih +EXAMPLES +1. Page the help page for the \fImkpkg\fR task. + + cl> phelp mkpkg + +2. View the help pages for all the tasks in the IMAGES package. + + cl> phelp images.* + +When viewing multiple help pages as in this last example, note that the +'N' and 'P' keystrokes in the pager may be used to move to the next or +previous help page. "." will return to the first help page (the start +of the spooled help text) and 'G' will skip to the end of file. Type '?' +while in the pager to get a summary of the most often used keystrokes. + +3. Format and page the Lroff (IRAF HELP) format document "MWCS.hlp" in +the system directory "mwcs". + +.nf + cl> cd mwcs + cl> phelp MWCS.hlp fi+ +.fi + +In this case the text being viewed is not part of the on-line help system, +but is a technical document describing one of the IRAF programming interfaces. +Any .hlp file may be viewed in this way. +.ih +TIME REQUIREMENTS +\fIphelp\fR is not quite as fast as \fIhelp\fR since it must fully format +the help text into a temporary file before the file can be viewed. For +small help pages, or to view only the first few screens of a help page, +the \fIhelp\fR task will be faster. +.ih +BUGS +.ih +SEE ALSO +page, help, references +.endhelp diff --git a/pkg/system/doc/protect.hlp b/pkg/system/doc/protect.hlp new file mode 100644 index 00000000..6a0049e4 --- /dev/null +++ b/pkg/system/doc/protect.hlp @@ -0,0 +1,36 @@ +.help protect Nov84 system +.ih +NAME +protect -- protect files from deletion +.ih +USAGE +protect files +.ih +PARAMETERS +.ls files +A template specifying the file or files to be protected. +.le +.ih +DESCRIPTION +\fIProtect\fR asserts protection from deletion for the specified files. +A protected file can be deleted only by first "unprotecting" it. +File protection is preserved when a file is copied or renamed, +even when copied or renamed to a remote network node, +but may be lost when a file is backed up on tape and later restored +(depending upon what utility one uses). Note that imagefiles are +automatically protected to prevent accidental deletion of the header +file, leaving a "zombie" pixel file somewhere on disk. +.ih +EXAMPLES + +1. Protect the file "paper.ms" from deletion, accidental or otherwise. + + cl> protect paper.ms + +2. Protect all the ".ms" files from deletion. + + cl> protect *.ms +.ih +SEE ALSO +unprotect, delete +.endhelp diff --git a/pkg/system/doc/references.hlp b/pkg/system/doc/references.hlp new file mode 100644 index 00000000..a67b4182 --- /dev/null +++ b/pkg/system/doc/references.hlp @@ -0,0 +1,78 @@ +.help references Jun89 system +.ih +NAME +references -- find all help database references to a given topic +.ih +USAGE +references topic +.ih +PARAMETERS +.ls topic +The topic for which help is desired, i.e., a keyword, phrase, or pattern +which the help database or quick-reference file is to be searched for. +.le +.ls quickref = "uparm$quick.ref" +The name of the optional quick-reference file. +.le +.ls updquick = no +Create or update the quick-reference file, e.g., because new packages +have been added to the global help database. Updating the quick-reference +file automatically enables \fIusequick\fR, discussed below. +.le +.ls usequick = no +Use the quick-reference file. By default, a runtime search of all the package +menus in the full help database is performed, which ensures that all packages +are searched, but which is comparatively slow. +.le +.ih +DESCRIPTION +The \fIreferences\fR task is used to search the help database for all tasks +or other help modules pertaining to the given topic, where \fItopic\fR may be +a keyword, phrase, or any general pattern as would be input to the \fImatch\fR +task. By default the full help database will be searched. If desired, +the "one-liner" information used for topic searching may be extracted and +used to prepare a quick-reference file to speed further searches. +This is not done by default because the help database is too dynamic, e.g., +new external packages may be installed at any time, by any user, or new +tasks may be added to existing packages at any time. + +References to tasks (or other objects) are printed in the form + +.nf + keyword1 - one line description + keyword2 - one line description +.fi + +and so on. To determine the \fIpackage pathname\fR of each named task, +get \fIhelp\fR on the named \fIkeyword\fR and the pathname will be seen at +the top of the help screen, followed by additional information about the +referenced object. If there are multiple objects with the same name, +a "help <keyword> \fIall+\fR" may be required to locate a particular one. +.ih +EXAMPLES +1. Find all help on CCDs. + + cl> ref ccd + +2. Create or update your private quick-reference file. + + cl> ref upd+ + +3. Examine the quick-reference file to get a summary of all the tasks +or other help modules in the help database. + + cl> page (ref.quickref) +.ih +TIME REQUIREMENTS +If a quick-reference file is used searching takes seconds, otherwise it +might take a minute or so for the typical large help database containing +all help modules for the core system and several external, layered packages. +.ih +BUGS +Only the one-liner (NAME) field describing each help module is used for +the searches. With a little work searching could be made much more +comprehensive as well as faster. +.ih +SEE ALSO +help, match +.endhelp diff --git a/pkg/system/doc/rename.hlp b/pkg/system/doc/rename.hlp new file mode 100644 index 00000000..226045da --- /dev/null +++ b/pkg/system/doc/rename.hlp @@ -0,0 +1,69 @@ +.help rename Aug97 system +.ih +NAME +rename -- rename a file or set of files +.ih +USAGE +rename file newname +.ih +PARAMETERS +.ls file +A template specifying the file or files to be renamed. +.le +.ls newname +If a single file is being renamed, the new filename, else the new name of +the field being renamed in a set of filenames. If \fInewname\fR is a +directory the input files will be moved to this directory with the same +name. +.le +.ls field = all +If set to "all" the file name remains unchanged and the \fInewname\fR is +assumed to be a destination directory in the case of multiple input files, +or the new filename (which may contain a new directory path) in the case of +a single input file. If set to \fIldir\fR the \fInewname\fR value is taken +to be a destination directory and the file is moved to this directory. +Setting to \fIroot\fR will rename only the root portion of the filename, +a value of \fIextn\fR will change or append the extension. \fInewname\fR +cannot contain a directory path when changing the root or extn field. +.le +.ih +DESCRIPTION +\fIRename\fR renames either a single file to "newname", or a set of files, +changing either the ldir, root or the extension part of each name. +If \fInewname\fR is a directory or \fIfield\fR is "ldir" the input files +are moved to this directory and the filenames remain the same. When +modifying the root or extension part of the filename \fInewname\fR is the +new root or extension name for the input files, an extension will be added +to the file name if it doesn't already exist and the extension field is being +modified. For multiple input files it is assumed +that \fInewname\fR is a directory if the value of \fIfield\fR is "all", +otherwise an error is generated to prevent overwriting files. +.ih +EXAMPLES + +1. Rename file "fred" to "jay". + + cl> rename fred jay + +2. Change the root name of a set of files from "out" to "pkout". + + cl> rename out.x,out.o,out.par pkout field=root + +3. Change the extension of all ".f77" files from ".f77" to ".f". + + cl> rename *.f77 f field=extn + +4. Move all files with a ".dat" extension to a new directory. + + cl> rename *.dat data$ + cl> rename *.dat /data/user + +5. Add a ".fits" extension to all files in a directory. + + cl> rename im00* fits field=extn +.ih +BUGS +.ih +SEE ALSO +movefiles, copy +.endhelp diff --git a/pkg/system/doc/rewind.hlp b/pkg/system/doc/rewind.hlp new file mode 100644 index 00000000..0519f81c --- /dev/null +++ b/pkg/system/doc/rewind.hlp @@ -0,0 +1,36 @@ +.help rewind Apr92 system +.ih +NAME +rewind -- rewind a previously allocated device +.ih +USAGE +rewind device +.ih +PARAMETERS +.ls device +The device to be rewound. +.le +.ls initcache = yes +Initialize the magtape device position cache for the device. This causes +the magtape i/o system to "forget" what it thinks it knows about things +like the number of files on the tape, the amount of tape used, and so on. +.le +.ih +DESCRIPTION +\fIRewind\fR rewinds the specified device, which is most likely +a magnetic tape, and which has been previously allocated to the user. + +By default \fIrewind\fR will initialize the device position cache. When +changing tapes, one should always either rewind or deallocate and reallocate +the device, to force the magtape system to recompute the number of files +on the tape and to ensure that the tape is left in a defined position. +.ih +EXAMPLES + +1. Rewind logical tape drive a. + + cl> rewind mta +.ih +SEE ALSO +allocate, deallocate, devstatus +.endhelp diff --git a/pkg/system/doc/sort.hlp b/pkg/system/doc/sort.hlp new file mode 100644 index 00000000..7d89657b --- /dev/null +++ b/pkg/system/doc/sort.hlp @@ -0,0 +1,62 @@ +.help sort Mar87 system +.ih +NAME +sort -- sort a file or the standard input +.ih +USAGE +sort input_file +.ih +PARAMETERS +.ls input_file +The text file to be sorted. If the standard input is redirected the standard +input is sorted. +.le +.ls column = 0 +If 0, sort entire text lines, else sort based on data/text starting +in the specified column. Columns are delimited by whitespace. Thus, +.nf + 12 abc 34 56 +.fi +has four columns, "abc" being in the second. +.le +.ls ignore_whitespace = no +Ignore leading whitespace. Useful only when column = 0 and the sort is +non-numeric. +.le +.ls numeric_sort = no +If set, make numerical (rather than ASCII text) comparisons. +.le +.ls reverse_sort = no +If set, sort in reverse text/numeric order. +.le +.ih +DESCRIPTION +\fISort\fR sorts the contents of the given text file, or the +standard input, either on a textual (based on the ASCII collating +sequence), or on a numeric basis. If a numeric sort is requested, +and either field in any comparison is non-numeric, a string (ASCII) +comparison will be made instead. +.ih +EXAMPLES + +1. Sort the output of the set command into alphabetic (ASCII collating) +order. + + cl> set | sort + +2. Sort the contents of "file", in reverse ASCII order, ignoring the +contents of columns 1 through 4. + + cl> sort file rev+ col=5 + +3. Print a long form directory listing with the files sorted by size, +largest files first. + + cl> dir | sort num+ rev+ col=3 +.ih +BUGS +Only one file can be sorted per call, and only one column or all columns can +be used for the sort. The current program is inefficient for large numeric +sorting tasks because the same numeric field may be decoded into its +corresponding binary value many times. +.endhelp diff --git a/pkg/system/doc/spy.hlp b/pkg/system/doc/spy.hlp new file mode 100644 index 00000000..33ffa52c --- /dev/null +++ b/pkg/system/doc/spy.hlp @@ -0,0 +1,26 @@ +.help spy Feb85 system +.ih +NAME +spy -- tell who is logged in and what they are doing +.ih +USAGE +spy [v] +.ih +DESCRIPTION +\fISpy\fR prints a summary of who is on the system and what they are doing. +The optional argument \fIv\fR (short for \fIverbose\fR) causes more detailed +information to be given. The operation of this task is machine dependent, +as is the quantity and format of the information returned. +.ih +EXAMPLES +.nf +cl> spy + 4:36pm up 24 days, 5:42, 2 users, load average: 0.29, 0.15, 0.18 +User tty login@ idle JCPU PCPU what +roger ttyh8 4:21pm 15 8 5 -csh +alice ttyh9 4:26pm 44 27 w +.fi +.ih +SEE ALSO +diskspace +.endhelp diff --git a/pkg/system/doc/tail.hlp b/pkg/system/doc/tail.hlp new file mode 100644 index 00000000..bd91e617 --- /dev/null +++ b/pkg/system/doc/tail.hlp @@ -0,0 +1,50 @@ +.help tail Nov84 system +.ih +NAME +tail -- print the last few lines of the specified files +.ih +USAGE +tail files +.ih +PARAMETERS +.ls files +A template specifying the files to be listed. +.le +.ls nlines = 12 +The number of lines to be printed. If negative, the number +of lines to be skipped, counting from the beginning of the file. +.le +.ih +DESCRIPTION +For each file in the input file list, \fItail\fR copies the last \fInlines\fR +of the file to the standard output. If there is more than one file in the +input file list, as one line header is printed before each file. +If "nlines" is negative, then abs(nlines) lines are skipped, and the rest +of the file is printed, i.e., the tail of the file is still printed, but +the offset is measured from the beginning of the file rather than the end. +.ih +EXAMPLES + +1. Prints the last 12 lines of each help file in the current directory. + + cl> tail *.hlp + +2. Print the last line of each help file. + + cl> tail *.hlp nl=1 + +3. Prints the third through fifth lines of "file". The same thing +might be done (at least conceptually) by "head file,nlines=5" +piped into "tail ,nlines=3". However, \fItail\fR does not work on STDIN. + +.nf + cl> tail file nl=-2 | head nl=3 +.fi +.ih +BUGS +\fITail\fR does not presently work on standard input, and therefore cannot +be used in pipes. +.ih +SEE ALSO +head +.endhelp diff --git a/pkg/system/doc/tee.hlp b/pkg/system/doc/tee.hlp new file mode 100644 index 00000000..466b3751 --- /dev/null +++ b/pkg/system/doc/tee.hlp @@ -0,0 +1,36 @@ +.help tee Nov84 system +.ih +NAME +tee -- tee the standard output to a file +.ih +USAGE +tee file +.ih +PARAMETERS +.ls file +The name of the output file. +.le +.ls out_type = "text" +The type of output file to be created, either "text" or "binary". +.le +.ls append = no +If set, append to an existing file, otherwise create a new file. +.le +.ih +DESCRIPTION +\fITee\fR copies its input to both the standard output and the named file. +Its primary use is in pipes where one wants to capture some intermediate output. +.ih +EXAMPLES + +1. The results of the \fIset\fR command are captured in the file "temp", +and are also passed on to the "match" command. The result is +a "temp" file of perhaps 100 lines, with the output to the screen +only around 5 lines. + + cl> set | tee temp | match tty +.ih +BUGS +Since the processes in an IRAF pipe execute serially rather than concurrently, +the teed output will not appear until all tasks to the left have completed. +.endhelp diff --git a/pkg/system/doc/touch.hlp b/pkg/system/doc/touch.hlp new file mode 100644 index 00000000..aedb35a0 --- /dev/null +++ b/pkg/system/doc/touch.hlp @@ -0,0 +1,71 @@ +.help touch Jan04 system +.ih +NAME +touch -- change file access and modification times +.ih +USAGE +touch files +.ih +PARAMETERS +.ls files +List of files to be created or touched. +.le +.ls create = yes +If enabled, the file will be created as a zero-length text file if it doesn't +already exist. +.le +.ls atime = yes +Change the access time of the file. Will not change the modification time +unless \fImtime\fR is also set. +.le +.ls mtime = yes +Change the modification time of the file. Will not change the access time +unless \fIatime\fR is also set. +.le +.ls time = "" +Time and date to set for the file. The format of this string may be any +of DD/MM/YY or CCYY-MM-DD (in which case time is assumed to be midnight of +that day), or CCYY-MM-DDTHH:MM:SS[.SSS...] to specify both date and time. +If not specified, the current system time is used unless the \fIref_file\fR +parameter is set. If specified, \fIref_file\fR will be ignored. +.le +.ls ref_file = "" +Use the corresponding times of the specified file for modifying the +times of the \fIinput_files\fR. If not specified, the current time is +used unless the \fItime\fR parameter is set. +.le +.ls verbose = no +Print verbose output of the files and times being reset. +.le +.ih +DESCRIPTION +The \fItouch\fR task sets the access and modification times of each file +in the \fIfiles\fR list. The file will be created if it does not already +exist when the \fIcreate\fR parameter is set. The time used can be +specified by \fItime\fR parameter or by the corresponding fields of the +file specified by \fIref_file\fR, otherwise the current system time will +be used. The task will update both the modification and access times of +the file unless disabled by the \fIatime\fR or \fImtime\fR parameter. + +.ih +EXAMPLES + +1. Update the times of all SPP source files in the current directory: + + cl> touch *.x + +2. Create an empty file on a remode node: + + cl> touch ursa!/data/trigger_file + +3. Reset the file modification time to 2:33:45 pm on June 5, 2003: + + cl> touch nite1.fits time="2003-06-05T14:23:45" + +4. Reset the file modification time to match dev$hosts: + + cl> touch nite1.fits ref_file=dev$hosts + +.ih +SEE ALSO +.endhelp diff --git a/pkg/system/doc/type.hlp b/pkg/system/doc/type.hlp new file mode 100644 index 00000000..f8af91cd --- /dev/null +++ b/pkg/system/doc/type.hlp @@ -0,0 +1,43 @@ +.help type Nov84 system +.ih +NAME +type -- type a file or files on the standard output +.ih +USAGE +type input_files +.ih +PARAMETERS +.ls input_files +A template specifying the file or files to be typed. +.le +.ls map_cc = yes +If set, output any non-printing control characters in the input text in +a printable form, e.g., ctrl/c (ASCII 3) would be output as ^C. +.le +.ls device = "terminal" +The output device, defaulting to the user's terminal. If the special device +"text" is named, any standout mode control characters embedded in the text +will cause the enclosed text to be output in upper case. +.le +.ih +DESCRIPTION +\fIType\fR copies the named files (or the files selected by +the file template) to the standard output. +If there is more than one file in the input list, a header naming the file +to be printed will precede each output file. +.ih +EXAMPLES + +1. Type all files in the current directory with the extension ".x" on the +standard output. Do not pause between files or pages (unlike \fIpage\fR). + + cl> type *.x + +2. Capture the manual page for task \fIhedit\fR in a text file, in a form +suitable for printing on any device. + + cl> help hedit | type dev=text > hedit.doc +.ih +SEE ALSO +page, head, tail, concatenate, lprint +.endhelp diff --git a/pkg/system/doc/unprotect.hlp b/pkg/system/doc/unprotect.hlp new file mode 100644 index 00000000..99120c07 --- /dev/null +++ b/pkg/system/doc/unprotect.hlp @@ -0,0 +1,27 @@ +.help unprotect Nov84 system +.ih +NAME +unprotect -- remove file protection +.ih +USAGE +unprotect files +.ih +PARAMETERS +.ls files +A template specifying the file or files from which delete protection is +to be removed. +.le +.ih +DESCRIPTION +\fIUnprotect\fR removes delete protection from the named files. +A "protected" file cannot be deleted or clobbered. +.ih +EXAMPLES + +1. Remove file protection from the listed files. + + cl> unprotect alpha,beta,gamma.x,*.db +.ih +SEE ALSO +protect, delete +.endhelp diff --git a/pkg/system/doc/urlget.hlp b/pkg/system/doc/urlget.hlp new file mode 100644 index 00000000..da6ede83 --- /dev/null +++ b/pkg/system/doc/urlget.hlp @@ -0,0 +1,84 @@ +.help urlget Sep2011 system +.ih +NAME +urlget -- Get a (http) URL to the named file +.ih +USAGE +urlget url fname +.ih +PARAMETERS +.ls url +The URL to download. +.le +.ls fname +The name of the file to create containing the URL contents. If not +specified, the trailing part of the URL is used as the filename. +.le +.ls use_cache = yes +Use the system file cache? If 'yes' and the file already exists in the +cache, the cached file will be copied to the output filename. +If 'no' then the URL will be downloaded again. +.le +.ls extn = "" +Optional filename extension to put on the cached filename. This can be +used to force files to be saved as a particular type in the cache. +.le +.ls verbose = no +Print verbose output? +.le +.ls cache = "cache$" +Logical cache directory name. +.le + +.ih +DESCRIPTION +The \fIURLGET\fR task is used to download a URL (HTTP protocol only) to a +local file named by the \fIfname\fR parameter. If no \fIfname\fR is given, +a filename is constructed from the last part of the URL (i.e. +characters trailing any of the '?', '/', or '&' delimiters). Because +the URL may not point to a static file, use of the \fIfname\fR parameter +is recommended. + +If the \fIuse_cache\fR parameter is set, the URL will only be downloaded if +it does not already exist in the file cache pointed to by the \fIcache\fR +parameter, otherwise the cached file will be copied to the output filename. +The \fIextn\fR parameter may be to used to force a specific file extension +to be appended to the filename in the cache, this allows a URL to be passed +to a task and treated as if it were a file of a specific type. + +.ih +EXAMPLES + +1. Download a FITS image from a URL (these are equivalent): + +.nf + cl> urlget http://iraf.noao.edu/foo.fits + cl> urlget http://iraf.noao.edu/foo.fits foo.fits +.fi + +2. Force a URL to be downloaded again: +.nf + cl> urlget http://iraf.noao.edu/foo.fits use_cache=no +.fi + +3. Download a URL with special characters: +.nf + cl> urlget http://iraf.noao.edu/scripts/tget?f=foo.fits +or + cl> s1 = "http://iraf.noao.edu/scripts/tget?f=foo.fits" + cl> urlget(s1) +or + cl> s1 = "http://iraf.noao.edu/scripts/tget?f=foo.fits&d=/iraf/web" + cl> urlget(s1,"foo.fits",verbose+) +.fi + +Escaping special characters isn't required from the commandline since the +URL is assumed to be whitespace or comma delimited. + +.ih +BUGS + +.ih +SEE ALSO + +.endhelp |