Repatch (from linux) of OSX IRAF

1 files changed, 378 insertions, 0 deletions

diff --git a/pkg/utilities/nttools/doc/tcreate.hlp b/pkg/utilities/nttools/doc/tcreate.hlp
new file mode 100644
index 00000000..0d12d277
--- /dev/null
+++ b/pkg/utilities/nttools/doc/tcreate.hlp
@@ -0,0 +1,378 @@
+.help tcreate Dec2003 tables
+.nj
+.ih
+NAME
+tcreate -- Create a table from ASCII files describing a table format.
+.ih
+USAGE
+tcreate table cdfile datafile
+.ih
+DESCRIPTION
+This task reads an ASCII file containing column descriptions for a new table.
+The columns are defined and the table created;
+data are read in from a file specified by
+the 'datafile' parameter
+(a specified number of lines may be skipped when reading in data).
+There may be several lines of data per table row.
+Blanks and tabs are skipped.
+Blank lines and lines beginning with # are ignored.
+In-line comments using # are permitted.
+The lines in the input files may be up to 8195 characters long,
+plus one character for the carriage return.
+The input 'datafile' is read free-format.
+
+Undefined values require a place holder in the data file.
+The word INDEF should be used as the place holder
+for undefined (indefinite) numerical values,
+the word "no" for boolean values,
+and a pair of adjacent quotes ("") for undefined character strings.
+If a value for a character string contains one or more blanks,
+or the comment character (#),
+then the entire value must be enclosed in quotes, e.g., "R CrB".
+
+This task can also read a file containing header parameters for the table.
+
+If a problem occurs when reading a particular data field,
+the execution continues, and the table entry is marked as undefined.
+.ih
+PARAMETERS
+.ls table [file name]
+Output file name for the table created by this task.
+
+Note that, if 'table' is an existing FITS file,
+the table that is created will be appended
+as a new extension to the end of the file.
+.le
+.ls cdfile = STDIN [file name]
+The name of the column definition file.
+
+The column definition file contains one line for each column to be created.
+Each line contains up to four values giving attributes of the particular column.
+Every line must have a column name; optionally, it may have a data type,
+display format, and units.  (Embedded blanks in any of these
+attributes must be enclosed in quotes.)  Adjacent quotes are used as
+place holders and let you skip an attribute while defining the next one.
+Column names and data types are NOT case sensitive.
+Neither the format nor data type may contain embedded blanks.
+Display formats may be of the type used by Fortran or those used by SPP.
+If the format is not defined, a default format will be used.
+The format is not used for internal representation of the data and
+is ignored when reading data---it is used only for display purposes,
+for example, by tasks such as 'tedit', 'tread', and 'tprint'.
+Type "help ttools opt=sysdoc" for detailed information about print formats.
+Comment lines may be included in this file
+by beginning the line with the comment symbol (#).
+
+The following data types are recognized by this parameter
+(the default data type is single-precision real):
+.nf
+
+     r - Single-precision real.
+     d - Double-precision real.
+     i - Integer.
+     s - Short integer.
+     b - Boolean.
+     ch*n - Character string of maximum length n.
+.fi
+
+A column of arrays can be created by giving the array length
+in square brackets appended to the data type.
+For example, a data type of r[400] would mean that the column
+contains an array of 400 single-precision real numbers in each row.
+r[20,5,4] would also mean an array of 400 reals,
+but in this case a TDIMi keyword will be written (for column number i)
+that gives the numbers 20, 5 and 4,
+indicating that the array should be regarded as 3-D,
+with 20 elements along the most rapidly varying axis
+and four elements along the least rapidly varying axis.
+Up to seven dimensions may be specified, separated by commas.
+For both of these cases, the data file must contain 400 values
+for that column for each row;
+the values need not all be on the same line of the data file.
+Text tables and column-ordered stsdas tables
+cannot contain arrays; see 'tbltype'.
+
+If you have an existing table
+with columns similar to those
+in the table you would like to create,
+you can use the 'tlcol' task to generate a file
+which can be edited and used as the input 'cdfile' for 'tcreate'.
+That is, the output of 'tlcol' is exactly the format
+that is expected for 'tcreate.cdfile'.
+The syntax is also the same as
+for column definitions in text tables,
+except for the leading "#c " in text tables.
+
+If cdfile = "STDIN" and the input is not redirected,
+the task prints a prompt asking for input.
+Press Control-Z (or Control-D, i.e. your EOF character)
+to terminate the list of column definitions;
+note that the Control-Z must NOT occur on the same line as the last
+column definition.
+.le
+.ls datafile = "STDIN" [file name]
+The name of the input ASCII data file.
+
+The values in the file must be in the order of the columns
+as given in the column-definitions file 'cdfile'.
+Undefined values should have INDEF or "" as place holders
+for numerical or character values, respectively.
+Each row for the table must begin with a new line in 'datafile',
+but there can be multiple lines in 'datafile' for each table row
+(see also 'nlines').
+
+If all data for a table row have been read from an input line
+but there are additional data on the line,
+or if there is a data type mismatch,
+the following warning will be
+printed:  "out of synch or extra data in line <number>".
+
+Lines in the input data file are limited to 8196 characters,
+including the newline at the end of each line.
+If a longer line is encountered, the task will stop with an error.
+
+As with 'cdfile',
+if datafile = "STDIN" and the input is not redirected,
+the task prints a prompt asking for input.
+Enter a carriage return before ending the last line
+and then press Control-Z (or Control-D, i.e. EOF) to close the file.
+.le
+.ls (uparfile) [file name]
+The name of the input ASCII file of header parameters.
+This file is optional.
+
+Each line of this file defines one header parameter,
+except that blank lines and lines beginning with # will be ignored.
+Each line should contain three parts:  keyword, datatype, and value;
+an optional comment may be added following the value.
+The keyword is a string (no embedded blanks) of up to eight characters.
+The datatype is a single letter (t, b, i, r, or d) that indicates the type.
+The value is limited to 70 characters.
+If the type is text (t) it may contain more than one word,
+but in that case it must be enclosed in quotes;
+otherwise, the portion of the value following the first word
+will be interpreted as a comment.
+
+Note that the syntax is not the same as
+for header keywords in text tables.
+The latter uses the much more reasonable "#k keyword = value comment".
+The datatype shouldn't need to be specified,
+since keywords are stored in the table as text strings anyway;
+the current syntax has been retained for backward compatibility.
+
+It is possible, though not recommended, to set uparfile = "STDIN".
+The problem is that it is read twice,
+once just to count the number of entries, and once to read the values,
+so you would have to type in the values twice.
+.le
+.ls (nskip = 0) [integer, min=0, max=INDEF]
+Number of lines to skip at the beginning of the data file.
+
+The 'tcreate' task will also skip blank lines and lines beginning with #;
+it will therefore not usually be necessary to specify 'nskip',
+as header lines may be commented out by inserting a leading #.
+Note that if 'nskip > 0' then exactly 'nskip' lines will be skipped,
+even if some of them are blank or comment lines.
+.le
+.ls (nlines = 0) [integer, min=0, max=INDEF]
+The number of lines in the input data file
+corresponding to one row in the output table.
+If 'nlines = 0' (the default) then lines will
+be read from the data file until every column in the row is filled.
+If 'nlines > 0' then exactly this many lines will be read for each row;
+if for some rows the input data are compressed into fewer than this
+many lines, extra dummy lines must be included following the good data.
+Note that comment lines and blank lines are not counted.
+.le
+.ls (nrows = 0) [integer, min=0, max=INDEF]
+The number of rows to write into the table.
+
+If this value is zero, then the entire input data file will be read.
+If this value is greater than zero then
+no more than 'nrows' will be written to the table,
+even if the data file contains enough data to fill more than
+'nrows' rows of data.
+For a column-ordered table (see the 'tbltype' parameter),
+'nrows' is the number of rows that will be allocated,
+and the actual number in the data file may be smaller.
+.le
+.ls (hist = yes) [boolean]
+Add a history record containing a creation date?
+
+If 'hist = yes', a header parameter will be written to the table with the
+keyword 'HISTORY' that gives the date and time that 'tcreate' was run.
+This parameter is added after those that were read from the 'uparfile', if any.
+.le
+.ls (extrapar = 5) [integer, min=0, max=INDEF]
+Extra space to be reserved for header-parameter records.
+This is the number of records for header parameters that will be allocated,
+in addition to the number needed to hold the parameters
+specified in the 'uparfile' parameter file.
+The default is five,
+which means that after the table is created
+up to five more parameters may be added
+(e.g., by using the 'tupar' task)
+without the table being rewritten to reallocate space.
+.le
+.ls (tbltype = "default") [string, allowed values:  default | row | 
+column | text]
+Type of table to create.
+The default is row-ordered stsdas format.
+To create a FITS table,
+use tbltype = "default"
+and specify a table name ('table')
+with filename extension ".fits", ".fit", or ".??f"
+('?' is any single character).
+.le
+.ls (extracol = 0) [integer, min=0, max=INDEF]
+Extra space to be reserved for columns in the output table.
+This parameter is relevant only for a row-ordered stsdas format table.
+
+This is in addition to the number required to contain those columns
+described by 'cdfile'.
+One unit of space is taken by each
+single-precision, integer, or boolean column.
+A double-precision column requires two units of allocated space,
+and a character-string column takes one unit of space for each four
+characters, or fraction thereof.
+.le
+.ih
+EXAMPLES
+1.  Wait for the user to type in column definitions and data,
+each of which will be terminated by a Control-Z (or Control-D, i.e. EOF).
+The prompts are printed by the 'tcreate' task;
+these are the lines beginning with "Give column definitions"
+and "Give table data".
+The table will have 4 columns and 2 rows.
+.nf
+
+tt> tcreate test STDIN STDIN
+
+Give column definitions (name, datatype, print format, units)
+ ... then newline & EOF to finish.
+name  ch*12
+ra    d     h12.1   hours
+dec   d     h12.0   degrees
+mag   r     f8.2
+^Z
+
+Give table data ... then newline & EOF to finish.
+nameless      3:18:47   42:24   INDEF
+"SA0 123456"  19:00:06.3  -0:00:01  3.5
+^Z
+
+.fi
+2. Create a table called "outfile.tab" using the columns specified
+in "columns.cd" and the data in "data.dat".
+
+tt> tcreate outfile columns.cd data.dat nskip=3
+
+"columns.cd" may contain just the following:
+.sp
+.nf
+STARno I  i5
+X	r      "F6.2"  pixels
+Y	R    F6.2     "pixels"
+MAG R   ""   magnitude
+		SHARP	  R
+				ROUND		r
+STARNAME   ch*15
+.fi
+
+Note the free format of, and embedded tabs in, the column definitions file
+itself.  The format for display of MAG is not specified, but the unit is
+given as magnitude, so adjacent quotes are used to mark the position where
+the display format is expected.
+
+The file "data.dat" may contain (if 'nskip=3', 'nlines=2'):
+.sp
+.nf
+This is a header
+      header2
+       header3
+ 1	3.0	4.0	
+           5.0	6.0	7.0 HD12345
+   2 10.0 11.0 12.0 13.0
+14.0 "HD 122"
+3 20.0    21.0        22.0         23.0     24.0  ""
+dummy line
+.fi
+
+Note the tabbed and free format of the data file
+and the specification of the character strings.
+If the character data contain embedded blanks
+then the whole string should be quoted,
+otherwise this is not necessary.
+The final entry is the null character string.
+
+3. The following column definitions:
+.sp
+.nf
+STARno	 i i6
+X	 r f9.2  pixels
+Y	 r f9.2  pixels
+MAG	 r f9.3
+SHARP	 r f9.3
+ROUND	 r f9.3
+STARNAME ch*15
+
+could be used with the following data file:
+
+     1     7.92     2.64   -3.075    0.436    0.019   XXXXXXXXXXXXXXX
+     2    33.89     3.14   -1.162    0.419    0.223
+     3     3.68     5.07   -2.454    0.421   -0.123   HD12345
+     4    42.70     5.08   -1.285    0.445    0.195   HD 123
+.fi
+
+4. The aperture photometry file from the 'daophot' task
+may have the following data:
+.sp
+.nf
+         1     6.95     2.61   99.999   99.999   99.999   99.999 . . .
+          464.618  9.71  0.52   9.999    9.999    9.999    9.999 . . .
+         2   200.06     2.80   99.999   99.999   99.999   99.999
+          465.180  7.79  0.16   9.999    9.999    9.999    9.999
+         3   156.25     5.17   14.610   14.537   14.483   14.438
+          462.206  7.26  0.37   0.013    0.014    0.015    0.016
+
+
+and could have the following column-definition file:
+
+STARno	i
+X	r
+Y	r
+MAG1	r
+MAG2	r
+MAG3	r
+ .
+ .
+ .
+MAG15	r
+SKYMOD	r
+SKYSD	r
+.fi
+
+The following could be used as an input file to define header parameters.
+.sp
+.nf
+comment t Created 1987 July 22
+NL      i 2
+NX      i 284
+NY      i 492
+THRESH  r 27.0
+AP1     r 3.0
+PH/ADU  r 20.0
+RNOISE  r 6.50
+BAD     r 300.0
+.fi
+.ih
+BUGS
+.ih
+REFERENCES
+This task was written by Phil Hodge.
+.ih
+SEE ALSO
+Type "help ttools opt=sysdoc" for a higher-level description of the 'ttools'
+package.
+See also the files in "tables$doc/".
+.endhelp