\input texinfo  @c -*-texinfo-*-
@c %**start of header
@setfilename udunits2prog.info
@settitle udunits2 Program Guide
@c %**end of header
@dircategory Science
@direntry
* udunits2: (udunits2prog).     The Unidata units-conversion program.
@end direntry
@copying
@include COPYRIGHT
@end copying

@titlepage
@title The @code{udunits2} Program
@author Steven R. Emmerson

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top, Synopsis, (dir), (dir)
@top udunits2
This manual describes how to use the @code{udunits2} program.
This program allows you to discover the definition of a unit
as well as convert numeric values between compatible units.

@insertcopying
@end ifnottex

@menu
* Synopsis::            Terse usage example
* Options::             Command-line options
* Description::         Description of the program
* See Also::            Additional information
* Complete Index::      Complete index
@end menu

@node Synopsis, Options, Top, Top
@chapter Synopsis
@cindex synopsis

@example
udunits2 -h
@end example

@example
udunits2 [-A|-L|-U] [-r] [-H have] [-W want] [XML_file]
@end example

@node Options, Description, Synopsis, Top
@chapter Options
@cindex options

The following options and arguments are supported:

@table @code
@item -A
Use the ASCII character-set.
@item -L
Use the ISO Latin-1 (ISO-8859-1) character-set.
@item -U
Use the full Unicode character-set with UTF-8 encoding.
@item -h
Print a help message.
@item -r
Reveal any problems with the units database (by default, no error messages are
printed during import of the database).
@item -H have
Use @code{have} unit for conversion. The default is the reply to the prompt.
@item -W want
Use @code{want} unit for conversion. An empty string requests the definition of
the @code{have} unit. The default is the reply to the prompt.
@item XML_file
The pathname of the XML-formatted units database.
If not specified, then the default, compile-time pathname is used.
@end table

@node Description, See Also, Options, Top
@chapter Description

When successfully started without the @code{-H have} or @code{-W want} options,
the program will print the prompt

@example
You have: 
@end example

At this point you can exit the program by entering the end-of-file character
(usually control-D) or continue by entering either a value or a unit.
(a value comprises a numerical value and a unit.
For example, 

@example
You have: 80 km/h
You want: 
@end example

At this point, if you enter a blank line, then the program will assume
that you entered a unit in the previous line and will print
the definition of that unit in terms of the base units of the
unit-system that it imported on startup.  For example,

@example
You have: 80 km/h
You want: 
    22.2222222222222 m.s-1
You have:
@end example

Details of the formatting depend on the character-set being used.
@xref{Options}.

Alternatively, at the ``@kbd{You want:}'' prompt you can enter the unit
in which you want the previously-entered value.
For example,

@example
You have: 80 km/h
You want: mi/h
    80 km/h = 49.7097 mi/h
    x/(mi/h) = 0.621371*(x/(km/h))
You have:
@end example

The first line after ``@kbd{You want:}'' shows the ``have'' value in the 
desired ``want'' unit.

The second line shows the transformation between numerical values
in the ``have'' unit to numerical values in the ``want'' unit.  The
symbol ``@kbd{x}'' represents the physical quantity in question.
See @url{http://physics.nist.gov/Pubs/SP811/sec07.html}.

@node See Also, Complete Index, Description, Top
@chapter See Also

@xref{Top, , UDUNITS-2, udunits2lib, The UDUNITS-2 C API Guide}, for
information on the UDUNITS-2 library, which is used by this program.

@node Complete Index, , See Also, Top
@unnumbered Index

@printindex cp

@bye
