Initial commit

1 files changed, 244 insertions, 0 deletions

diff --git a/pkg/utilities/nttools/nttools.hlp b/pkg/utilities/nttools/nttools.hlp
new file mode 100644
index 00000000..e02ffbd4
--- /dev/null
+++ b/pkg/utilities/nttools/nttools.hlp
@@ -0,0 +1,244 @@
+.help ttools May2000 tables
+.nj
+
+This package contains tasks for working with tables.
+Tables are files that contain data in row & column format.
+The supported table formats are FITS, STSDAS, and ASCII text.
+Different columns may have different data types,
+but all the values in one column have the same data type.
+In addition to the tabular data,
+a table may contain header parameters identified by keywords.
+
+.nf
+Each column has the following four items of information:
+    (1) a name (case insensitive),
+    (2) data type (real, double, integer, short int, boolean, or text),
+    (3) a format specification for printing the contents of the column,
+    (4) "units", a string (default is null).
+.fi
+
+For STSDAS tables the column names and units
+can be up to 20 characters in length.
+For FITS tables the limit is 68 characters.
+The default column names for ASCII tables are "c1", "c2", "c3", etc.;
+however, there is a "#c" syntax for giving explicit column definitions,
+which is described below.
+
+Header parameters may have data types of
+floating point, integer, boolean, or text.
+Header keywords are limited to eight characters (for FITS compatibility)
+and are converted to upper case.
+
+The print formats are discussed below.
+
+Here is a list of the ttools tasks organized by function:
+
+.nf
+    create a table:
+	tcreate, tedit
+
+    display contents:
+	tprint, tread, tedit, tcheck, thedit, thselect, tupar, gtedit
+
+    modify contents:
+	tedit, thedit, tupar, gtedit
+
+    information about a table:
+	tinfo, tlcol
+
+    database-like utilities:
+	tquery, tsort, tproject, tselect, tdiffer, tjoin, tmatch,
+	tmerge, tproduct, texpand
+
+    statistics, etc:
+	thistogram, tlinear, trebin, tstat
+
+    arithmetic:
+	tcalc, tunits, tintegrate
+
+    convert between table or image header parameter, cl parameter, table datum:
+	keypar, keytab, parkey, partab, tabkey, tabpar
+
+    convert columns of arrays to other formats:
+	txtable, tximage, titable, tiimage, taextract, tainsert
+
+    change column definition or table size:
+	tchcol, tchsize
+
+    miscellaneous:
+	tcopy, tdelete
+.fi
+
+ASCII text tables can be simple files
+(just data in row and column format),
+or they can have header keywords and/or explicit column definitions.
+
+Header keywords and column definitions
+in text tables have the following syntax:
+.nf
+#k keyword = value comment
+#c column_name data_type print_format units
+.fi
+
+The "#k " (or "#K ") must be the first three characters of the line,
+and the space following "k" is required.
+Header keywords can be added to any text table,
+and they do not have to precede the data.
+For a text string keyword,
+quotes around the value are needed if there is a comment,
+in order to distinguish value from comment.
+
+The "#c " (or "#C ") must be the first three characters of the line,
+and the space following "c" is required.
+All column definitions must precede the table data.
+Aside from the "#c ", the syntax is the same as
+the output from 'tlcol' or the 'tcreate.cdfile'.
+Only the column name is required,
+although in most cases you will also need to give the data type
+(the default is d, double precision).
+The print format is not used for reading the text file,
+only for displaying it or printing it out if it was modified.
+The file is read in free format,
+with whitespace (blank or tab) separated columns.
+Text string columns must be enclosed in quotes
+if they contain embedded blanks.
+
+For more information about text tables, "page tables$doc/text_tables.doc".
+
+The print format is used by such tasks as 'tprint', 'tedit', and 'tread'
+to determine how the column values are to be displayed.
+Most of the ordinary Fortran formats are supported for tables.
+Nonstandard formats should not be used for FITS tables
+for reasons of portability.
+The differences between the capabilities of Fortran formats
+and SPP formats are discussed below.
+
+Here is a list of the default print format for each data type,
+given in both SPP style and Fortran style.
+
+.nf
+default formats:
+
+	data type      SPP       Fortran
+	---------      ---       -------
+	real           %15.7g    G15.7
+	double prec    %25.16g   G25.16
+	integer        %11d      I11
+	short          %11d      I11
+	boolean        %6b       L6
+	text string    %-ns      A-n
+.fi
+
+where n for character strings is the string size as given when the
+column was defined.
+The minus sign means that the string will be left justified.
+While a format such as "A-12" is not available in standard Fortran,
+a format may be given with that syntax when using ttools tasks,
+and the format will be converted to SPP style.
+
+SPP formats (and Fortran equivalents) that are supported
+for STSDAS tables are as follows.
+
+.nf
+	SPP    Fortran      meaning
+	---    -------      -------
+	 b        L         boolean "yes" or "no"
+	 d        I         integer, displayed in decimal
+	 x        Z         integer, displayed in hexadecimal
+	 e      E or D      exponential format
+	 f        F         floating point
+	 g        G         use F or E as appropriate
+	 h        H         nn:nn:nn.n
+	 H      (none)      divide by 15, then nn:nn:nn.n
+	 m        M         nn:nn.n
+	 M      (none)      divide by 15, then nn:nn.n
+	 s        A         character string
+.fi
+
+The syntax is "%w.dC" (SPP style) or "Cw.d" (Fortran style),
+where w is the field width,
+d is the number of decimal places (or precision for g format),
+and C is the format code as given in the left column below.
+When giving a format in Fortran style,
+use the format code given in the second column;
+these are shown in upper case but may also be given in lower case.
+Note that H and M are not standard Fortran formats;
+in particular, H is not interpreted as Hollerith.
+See below for more information about H and M formats.
+
+The field width (w) may be given as a positive number,
+a negative number, or preceded by a zero.
+A negative field width means the value should be left justified in the field.
+A leading zero means the field should be padded on the left by zeroes;
+for example, "%04d" or "I04" is equivalent to the standard Fortran "I4.4".
+The d value means the number of decimal places
+for f, h, m, H or M format,
+but it means the digits of precision for g format.
+For character strings, "%s" means left justify and
+use only as much space as needed to print the value;
+"%40s" and "%-40s" mean right and justify respectively in a 40-character field.
+
+When the format is given in SPP style,
+there are two relatively new formats that are not available in Fortran.
+Specifying upper case H or M means that
+the numbers will be divided by 15 before being formatted
+using h or m format respectively.
+This is intended for converting hours to degrees.
+When two table columns contain right ascension and declination,
+both in decimal degrees,
+then appropriate formats might be,
+for example, %12.2H or %9.2M for right ascension
+and %12.1h for declination.
+This would print the right ascension in hours, minutes, seconds
+(or hours and minutes for M format) with two decimals,
+and would print the declination in degrees, minutes, seconds
+with one decimal after the seconds.
+
+Here are some examples.
+
+.nf
+	internal value    format     displayed value
+	--------------    ------     ---------------
+	2.71828           %10.4g          2.718
+	2.71828e27        %10.4g       2.718E27
+	2.71828           %10.4f         2.7183
+	2.71828           %10.4e        2.718E0
+	2.71828           %10.1h      2:43:05.8
+	2.71828           %10.1m         2:43.1
+	2.71828           %07.1m     02:43.1
+	2.71828           %10d                2
+	927               %10d              927
+	927               %-10d      927
+	927               %010d      0000000927
+	ttools            %s         ttools
+	ttools            %10s           ttools
+	ttools            %-10s      ttools
+.fi
+
+FITS and STSDAS tables can have columns that contain arrays ("3-D tables").
+That is, each cell (designated by both a column name and a row number)
+stores a 1-dimensional array of elements instead of a single value.
+
+There are four tasks that act as 3-D table translators. These tasks extract
+information from or insert information into "3-D tables".
+
+The information moved from/to a 3-D table by the tasks in this package can
+have either of two forms, regular 2-D tables or 1-dimensional images.
+Tasks 'txtable' and 'titable' perform, respectively, extractions and
+insertions of 2-D tables. Tasks 'tximage' and 'tiimage' perform, respectively,
+extractions and insertions of images.
+
+Task 'tscopy' is a variant of the 'tcopy' task.
+It performs a standard table copy
+but also supports the selector mechanism to allow copying of sections
+of columns that contain arrays.
+Type "help selectors" for further information about sections.
+
+.ih
+SEE ALSO
+.nf
+selectors
+files in tables$doc/
+.fi
+
+.endhelp