Repatch (from linux) of OSX IRAF

1 files changed, 365 insertions, 0 deletions

diff --git a/pkg/utilities/nttools/doc/tupar.hlp b/pkg/utilities/nttools/doc/tupar.hlp
new file mode 100644
index 00000000..3c8d99b3
--- /dev/null
+++ b/pkg/utilities/nttools/doc/tupar.hlp
@@ -0,0 +1,365 @@
+.help tupar Jun97 tables
+.nj
+.ih
+NAME
+tupar -- Edit table header parameters.
+.ih
+USAGE
+tupar table
+.ih
+DESCRIPTION
+This task is an interactive editor that allows the user to modify table
+header parameters.
+Prompts are written to STDERR rather than
+STDOUT so that STDOUT can be redirected to a file.
+If STDERR is redirected, no prompts will appear.
+Prompting is also turned off if the input is redirected from a file.
+
+The table to be edited is copied to a temporary table
+in the same directory as the original table
+(or in tmp$ if the first copy attempt fails),
+and the changes are made to that copy.
+When you exit 'tupar',
+the copy is renamed back to the name of the original table.
+If you quit rather than exit,
+then the copy is deleted, so the original table will remain unchanged.
+
+The prompt ":" is used by the task when it is waiting for user input.
+At this prompt the user can enter any editor command.
+The "e" command (or end of file, e.g. Control-Z) will exit the editor.
+The following commands are available:  e, q, g, p, d, r, k, t, l.
+These commands are interpreted as exit, quit (without saving changes),
+get, put, delete, replace, change keyword name, type, and list respectively.
+Each of these commands is described in detail below:
+
+The exit command, specified by "e" or end of file,
+will close the file--saving all changes,
+and open the next file if more than one file was specified
+for the 'table' input parameter.
+
+The quit command is similar to exit except that changes that were made
+to the header parameters will not take effect,
+unless 'inplace = yes'.
+If changes were made to the table header
+you will be prompted for confirmation
+unless the command was given followed by "!";
+for example, "q!" or "quit!".
+
+The type command, specified by "t", and the list command,
+specified by "l",
+both display header parameters---one header per line of output.
+The difference between the two commands is that list will show the parameter
+number and type will not.
+Entering the command "t" or "l" will produce
+a listing of all header parameters.
+Optionally, an integer may follow
+the command indicating that only a particular parameter is to be displayed.
+Two integers following the command indicate a range of parameters.
+If a number is specified that is beyond the range of valid headers,
+an error message will be displayed.
+The output consists of the name of the header parameter,
+its data type (indicated by a single letter,
+"r" for real, "b" for boolean, "i" for integer, or "d" for double),
+and its current value.
+If the keyword has an associated comment,
+the comment will be displayed following the value.
+The following are examples of valid syntax for listing header parameters:
+.nf
+t
+l
+t 3
+l 300 310
+.fi
+
+The get command, indicated by "g", will look for a specific keyword and
+display its current value.
+Optionally, the data type can be specified
+using the letter "r" for real, "i" for integer, "d" for double, or
+"b" for boolean.
+If no data type is specified, then the type is assumed to be text.
+If the data type is specified,
+the type immediately follows the "g" command;
+for example, typing the command "gd X" will get the value 
+contained in the header keyword "X" and display it as a double-precision
+real value.
+If "X" does not exist, no output will be produced.
+If the keyword has an associated comment,
+the get command displays the comment following the value;
+a text string value will be enclosed in quotes
+to distinguish the value from the comment.
+Examples of valid syntax follow:
+.nf
+g history
+gd coeff0
+gi numpts
+.fi
+
+The put command, specified by "p", will either replace the value of an
+existing parameter,
+or it will create a new parameter if the specified parameter is not found.
+The "p" command is followed on the command line by a keyword
+name and the parameter value.
+A comment may optionally follow the value.
+The "p" command itself should
+be followed by a single letter type specifier, "i" for integer,
+"r" for real, "d" for double, or "b" for boolean.
+If no type is specified, then the data type is assumed to be text.
+In order to specify a comment with a parameter of type text,
+the parameter value must be enclosed in quotes
+in order to distinguish it from the comment.  (Keyword names
+HISTORY and COMMENT are already comments,
+and further comments cannot be added to them.)
+Examples of valid put command syntax follow:
+.nf
+p comment Created for testing.
+gd coeff0
+pd coeff0 3.141592653589793
+pi ncoeff 7 number of coefficients
+pt fittype chebychev
+pt fittype "chebychev" type of fit that these coefficients represent
+.fi
+
+The replace command, specified by "r", works much like the put command
+described above; however, it will prompt the user for confirmation before
+actually changing any values in the table.
+A parameter can be specified by name or by number.
+The "r" command will not change a keyword name or a data type,
+whereas the "p" command can.
+After the command is entered,
+the current value of the keyword is displayed and
+the editor waits for a new value to be entered by the user.
+Pressing the return key indicates that no change is to be made.
+Pressing the space bar will blank the current value.
+You will then be prompted for
+confirmation unless the command was issued as "r!" or the input was
+redirected from a file.
+The default action is given by the 'delete_default' parameter.
+
+A range of contiguous parameters can be replaced at one time by giving
+the names or numbers of the first and last parameters to be replaced.
+This can involve a lot of prompting for confirmation,
+especially if several tables are being edited with 'same=yes'.
+In this context, "contiguous" means adjacent in the table header.
+Thus, when replacing a range by name,
+it is not the parameters that fall alphabetically within the limits
+that will be replaced
+but rather the parameters that are numerically within the limits.
+When editing a list of tables with 'same=yes',
+the same replacement string is used for each table.
+Thus it is essential that there be the same number of parameters in
+the range in all tables being edited.
+When no replacement value is given (i.e., just hit the return key),
+then the current keyword value is not changed,
+either in the first table or in subsequent tables.
+
+Sample replace commands follow:
+.nf
+r coeff0
+r 17
+r! 17
+r junk dummy
+r junk 12
+r 5 12
+.fi
+
+The delete command, specified by "d", will delete a header parameter by
+either name or number.
+The editor prompts for confirmation of delete,
+unless input is redirected from a file.
+The default action is given by the 'delete_default' parameter.
+If you do not want to be prompted for confirmation, enter the command as "d!".
+If you want to delete a history or comment record other than the first,
+you can identify the parameter by number rather than name.
+
+A range of contiguous parameters can be deleted at one time by giving
+the names or numbers of the first and last parameters to be deleted.
+As with replacing a range of parameters,
+a contiguous block of parameters will be deleted.
+
+Examples of valid delete commands follow:
+.nf
+d testflag
+d 17
+d! 17
+d junk dummy
+d junk 12
+d 5 12
+.fi
+
+The "k" command changes the name of a keyword
+without changing the data type, value, or comment.
+Give the current and new keyword names following the "k".
+Note that keywords are limited to eight characters.
+If the name of a COMMENT or HISTORY keyword is changed,
+only the first occurrence of that keyword will be changed.
+
+Examples of valid change keyword commands follow:
+.nf
+k history comment
+k dummy test
+.fi
+.ih
+PARAMETERS
+.ls table [file name template]
+A table name or list of table names whose header parameters are to be edited.
+Unless 'inplace = yes',
+each table will be copied (one at a time) to a temporary table,
+and changes are made to the copy until you exit.
+This can cause problems if there is not enough disk space for the copy;
+however, the 'inplace' parameter can
+be set to "yes" so that the tables are opened in-place.
+.le
+.ls (same = no) [boolean]
+Apply the same set of instructions to all tables?  
+
+This is only relevant when more than one table is being edited.
+If 'same = no', instructions are processed separately for each table,
+with the "e" command used to end processing of a table and open
+the next table.
+
+If 'same = yes', the same instruction set is applied to all tables.
+These instructions will be read from STDIN (which may be redirected)
+and saved in a local buffer while the first table in the list is open.
+For each subsequent table the instructions will be read from the local buffer.
+Caution is advised when deleting or replacing parameters, especially by
+number; remember that prompting for confirmation is turned off if the
+input is redirected or if the instruction is given as "d!" or "r!".
+
+If 'same = yes' and you quit (rather than exit) from editing the first table,
+the behavior of the task depends on whether changes were made before quitting.
+If changes were made then the task aborts immediately
+without opening the other tables in the input list.
+If no change was made then the other tables are processed.
+The idea is to allow "g", "t", and "l" commands
+and still be able to quit rather than exit,
+since nothing was modified.
+If changes were made but you quit,
+that's interpreted as trying to recover from an error,
+so we don't change the first table and we don't continue.
+.le
+.ls (verbose = yes) [boolean]
+Display the name of each table when it is opened?  
+
+If STDOUT is redirected
+then these file names will be written to STDERR as well as to STDOUT.
+.le
+.ls (readonly = no) [boolean]
+Prevent changes from being made to the file?  
+
+If 'readonly = yes', then the
+table is opened with read only access.  This is useful for viewing the
+contents of the table while at the same time preventing changes from
+being made to it.  (Only the "g", "t", and "l" commands are useful in
+read only mode).
+.le
+.ls (inplace = no) [boolean]
+Edit the original table in-place?
+
+By default a copy of the original table is made,
+either in the same directory or in tmp$.
+This makes it possible to quit without saving changes.
+If the table is large, however,
+it may be undesirable to make a copy,
+so the 'inplace' parameter gives you the option
+of editing the original table.
+In this case, however, it will not be possible to quit without saving changes.
+.le
+.ls (quit_default = no) [boolean]
+The value of this parameter is the default response to the prompt
+for confirmation if you give the quit command.
+.le
+.ls (delete_default = yes) [boolean]
+The value of this parameter is the default response to the prompt
+for confirmation for the delete and replace commands.
+.le
+.ls go_ahead [boolean]
+The user does not set this explicitly.
+It is the parameter which is actually gotten in response to a prompt.
+.le
+.ih
+EXAMPLES
+1. This example reads all history records from all tables in the default
+directory and writes them to 'history.lis'.
+.nf
+
+tt> tupar *.tab same=yes verbose=no readonly=yes >history.lis
+        (The task writes a ":" prompt and waits for input.)
+:g history
+:q
+tt>
+.fi
+
+2. This example illustrates the use of each of the commands when editing
+parameters in one table.  This kind of interactive use of the task
+would not be appropriate when operating on a list of tables unless
+the 'same' parameter is set to "no".
+.nf
+
+tt> tupar junk
+        (The task writes the table name and a ":" prompt and waits for input.)
+junk.lis
+:g garvage
+        (The keyword was not found, so nothing was displayed.)
+:g garbage
+GARBAGE = 3.1416926535
+:pd garbage 3.1415926535
+:p comment yet another comment
+:t
+GARBAGE  d 3.1415926535
+COMMENT  t This is the first comment.
+PI       t 3.1415926535  not an accurate value
+COMMENT  t yet another comment
+:l 3 999
+ 3 PI       t '3.1415926535'  not an accurate value
+ 4 COMMENT  t yet another comment
+:g pi
+PI = '3.1415926535'  not an accurate value
+:gd pi
+PI = 3.1415926535  not an accurate value
+:pd pi 3.14159265358979323846 a more accurate value
+:l
+ 1 GARBAGE  d 3.1415926535
+ 2 COMMENT  t This is the first comment.
+ 3 PI       d 3.141592653589793  a more accurate value
+ 4 COMMENT  t yet another comment
+:d garbage
+The following parameter is to be deleted:
+GARBAGE  d 3.1415926535
+   ...   OK to delete ? (yes):			(user hits return)
+:d comment
+The following parameter is to be deleted:
+COMMENT  t This is the first comment.
+   ...   OK to delete ? (yes): n		(user types n)
+:l 4
+parameter out of range; max is 3
+:d 3
+The following parameter is to be deleted:
+COMMENT  t yet another comment
+   ...   OK to delete ? (yes):			(user hits return)
+:t
+COMMENT  t This is the first comment.
+PI       d 3.141592653589793  a more accurate value
+:r 1
+keyword COMMENT, type t; give replacement value:
+This is the first comment.			(TUPAR writes this & waits)
+this is a comment				(this line entered by user)
+Current parameter and its replacement are:
+COMMENT  t This is the first comment.
+COMMENT  t this is a comment
+   ...   OK to replace ? (yes): n		(user types n)
+no action taken
+:q
+tt>
+.fi
+.ih
+BUGS
+.ih
+REFERENCES
+This task was written by Phil Hodge.
+.ih
+SEE ALSO
+tprint, tdump, tedit
+
+Type "help tables opt=sys" for a higher-level description of the 'tables' 
+package.
+.endhelp