1 files changed, 143 insertions, 0 deletions
diff --git a/pkg/utilities/nttools/doc/tunits.hlp b/pkg/utilities/nttools/doc/tunits.hlp
new file mode 100644
index 00000000..553ebb6e
--- /dev/null
+++ b/pkg/utilities/nttools/doc/tunits.hlp
@@ -0,0 +1,143 @@
+.help tunits Jan99 ttools
+.ih
+NAME
+tunits -- Convert a table column from one set of units to another
+.ih
+USAGE
+tunits table column newunits
+.ih
+DESCRIPTION
+Tunits converts a column in a table from one set of units to
+another. It supports both scalar and array columns. You supply the
+table and column name and the new units you want the column to be
+in. Optionally, you can apply the current column units if the units
+string stored in the table is missing or incorrect. Tunits only
+supports multiplicative conversions, conversions that involve additive
+changes, like Kelvin to Celsius, are not supported. Unit names and
+conversions are read from two tables. You can copy these tables and
+edit them if you want to add new conversions.
+
+You can find out the current units for a table column by running
+tlcol. If a units conversion is not supported by this task and you
+know the conversion formula, you can run tcalc.
+
+Tunits must parse the unit strings you pass it, which requires that
+they follow a certain set of rules. Units can be a simple units name,
+such as ergs, or a units name raised to a power, such as meters^2, or
+the product or quotient of units names raised to a power, such as
+feet/sec or gm*cm/s^2. If two units names are next to each other
+without any operator between them, a multiplication is assumed. If a
+units name is followed by a number, the units name is assumed to be
+raised to that power.
+
+Powers can also be specified by preceding the unit name with the
+string "square", "sq", "cubic", or "cu". For example, "square meter"
+is equivalent to "meter^2".
+
+The operators recognized are:
+
+.nf 
+division	/ or per
+multiplication	*
+exponentiation	^ or **
+.fi
+
+Division has the lowest priority and exponentiation the highest. This
+means ergs/sec*angstrom is interpreted as ergs/(sec*angstrom) and not
+(ergs/sec)*angstrom, as it would be in most computer languages. The
+default priority can be changed by changed by grouping terms with
+parentheses. 
+
+Each set of units can have several synonymous names. These names are
+listed in the abbreviations table. Case is not significant in names
+and regular plurals (made by adding an "s") are converted to the
+singular. Names should contain only alphabetic characters.  Blanks,
+underscores and digits are not allowed.
+
+The conversions supported by this task are read from the units
+conversion table. The table lists the old and new units and a
+conversion factor. Only one conversion is allowed for each set of
+units. 
+
+.ih
+PARAMETERS
+.ls table [file]
+The name of the table the conversion is applied to.
+.le
+.ls column [string]
+The column to be converted. Both scalar and array columns are
+supported.
+.le
+.ls newunits [string]
+The new set of units for the column. The format of this parameter is
+described above. This task writes the new units to the units field in
+the table column.
+.le
+.ls (oldunits = " ") [string]
+The units that the table column is currently in. If the value of this
+parameter is blank, the units will be read from the table.
+.le
+.ls (abrevtab = "ttools$tunits/abrev.tab") [file]
+A table of alternate names for each unit. This table contains two
+columns. The first column is the name of the units and the second
+column is the standard abbreviation. Because the default table is an
+ascii file, columns are read positionally and not by column names
+
+Many units have more than one name or abbreviation. Using a standard
+abbreviation allows units to be converted to a standard form, which
+simplifies calculations. The standard abbreviation is used internally
+when computing the conversion factor. Case is not significant in names
+and regular plurals (made by adding an "s") are converted to the
+singular before looking them up in the table. Names should contain
+only alphabetic characters.  Blanks, underscores and digits are not
+allowed.
+
+The name of this table is a parameter to allow you to create your own
+table of standard abbreviations, with additional units.
+.le
+.ls (unittab = "ttools$tunits/units.tab") [file]
+A table of conversion factors from one set of units into another.
+This table contains four columns. The first is the conversion factor,
+a double precision number. The second is the units the task tries to
+convert from. The third column is the units the task tries to convert
+to. The fourth column is contains the boolean variable swap, explained
+a little later. 
+
+The table is interpreted as "There are <factor> <from> in a <to>."
+For example, "There are 100 centimeters in a meter."  The last column,
+swap, does not change the sense of the sentence but does change the
+direction that the conversion is applied, For example, "60 seconds in
+a minute" is actually a conversion from minutes to seconds because
+swap is yes. Unit conversions should set swap to yes when the desired
+conversion is not an exact value, but its inverse is. Only one
+conversion is allowed per unit, which simplifies the program logic
+considerably. Conversions should be chosen so that they ultimately
+resolve to MKS units. To prevent endless loops conversions from the
+fundamental units of MKS are checked for and forbidden. However, the
+program does not check for other loops, so be careful when adding new
+conversions!
+
+As in the case of the abbreviation table, the table name is a
+parameter to allow you to create your own table with additional unit
+conversions. 
+.le
+.ls (verbose = no) [bool]
+If you set this parameter to yes, the task will print a message to
+STDERR for each units conversion utilized in computing the conversion
+factor.
+.le
+.ih
+EXAMPLES
+Convert watts to ergs per second. Print the diagnostic messages:
+
+.nf
+tt> tunits source.tab power "ergs/sec" old=watts verb+
+.fi
+.ih
+REFERENCES
+This task was written by Bernie Simon
+.ih
+SEE ALSO
+tlcol, tcalc
+
+.endhelp