xref: /dragonfly/usr.bin/units/units.1 (revision 8e1c6f81) 
1.\" $FreeBSD: src/usr.bin/units/units.1,v 1.18 2005/02/13 22:25:25 ru Exp $
2.\" $DragonFly: src/usr.bin/units/units.1,v 1.4 2008/08/12 09:28:22 matthias Exp $
3.Dd August 12, 2008
4.Dt UNITS 1
5.Os
6.Sh NAME
7.Nm units
8.Nd conversion program
9.Sh SYNOPSIS
10.Nm
11.Op Fl f Ar filename
12.Op Fl qv
13.Op Ar from-unit to-unit
14.Sh OPTIONS
15The following options are available:
16.Bl -tag -width indent
17.It Fl f Ar filename
18Specify the name of the units data file to load.
19.It Fl q
20Suppress prompting of the user for units and the display of statistics
21about the number of units loaded.
22.It Fl v
23Print the version number.
24.It Ar from-unit to-unit
25Allow a single unit conversion to be done directly from the command
26line.
27The program will not print prompts.
28It will print out the
29result of the single specified conversion.
30.El
31.Sh DESCRIPTION
32The
33.Nm
34program converts quantities expressed in various scales to
35their equivalents in other scales.
36The
37.Nm
38program can only
39handle multiplicative scale changes.
40It cannot convert Celsius
41to Fahrenheit, for example.
42It works interactively by prompting
43the user for input:
44.Bd -literal
45    You have: meters
46    You want: feet
47            * 3.2808399
48            / 0.3048
49
50    You have: cm^3
51    You want: gallons
52            * 0.00026417205
53            / 3785.4118
54
55    You have: meters/s
56    You want: furlongs/fortnight
57            * 6012.8848
58            / 0.00016630952
59
60    You have: 1|2 inch
61    You want: cm
62            * 1.27
63            / 0.78740157
64.Ed
65.Pp
66Powers of units can be specified using the '^' character as shown in
67the example, or by simple concatenation: 'cm3' is equivalent to 'cm^3'.
68Multiplication of units can be specified by using spaces, a dash or
69an asterisk.
70Division of units is indicated by the slash ('/').
71Note that multiplication has a higher precedence than division,
72so 'm/s/s' is the same as 'm/s^2' or 'm/s s'.
73Division of numbers
74must be indicated using the vertical bar ('|').
75To convert half a
76meter, you would write '1|2 meter'.
77If you write '1/2 meter' then the
78units program would interpret that as equivalent to '0.5/meter'.
79If you enter incompatible unit types, the units program will
80print a message indicating that the units are not conformable and
81it will display the reduced form for each unit:
82.Bd -literal
83    You have: ergs/hour
84    You want: fathoms kg^2 / day
85    conformability error
86            2.7777778e-11 kg m^2 / sec^3
87            2.1166667e-05 kg^2 m / sec
88.Ed
89.Pp
90The conversion information is read from a units data file.
91The default
92file includes definitions for most familiar units, abbreviations and
93metric prefixes.
94Some constants of nature included are:
95.Pp
96.Bl -column -offset indent -compact "mercury"
97.It "pi	ratio of circumference to diameter
98.It "c	speed of light
99.It "e	charge on an electron
100.It "g	acceleration of gravity
101.It "force	same as g
102.It "mole	Avogadro's number
103.It "water	pressure per unit height of water
104.It "mercury	pressure per unit height of mercury
105.It "au	astronomical unit
106.El
107.Pp
108The unit 'pound' is a unit of mass.
109Compound names are run together
110so 'pound force' is a unit of force.
111The unit 'ounce' is also a unit
112of mass.
113The fluid ounce is 'floz'.
114British units that differ from
115their US counterparts are prefixed with 'br', and currency is prefixed
116with its country name: 'belgiumfranc', 'britainpound'.
117When searching
118for a unit, if the specified string does not appear exactly as a unit
119name, then
120.Nm
121will try to remove a trailing 's' or a
122trailing 'es' and check again for a match.
123.Pp
124To find out what units are available read the standard units file.
125If you want to add your own units you can supply your own file.
126A unit is specified on a single line by
127giving its name and an equivalence.
128Be careful to define
129new units in terms of old ones so that a reduction leads to the
130primitive units which are marked with '!' characters.
131The
132.Nm
133program will not detect infinite loops that could be caused
134by careless unit definitions.
135Comments in the unit definition file
136begin with a '/' character at the beginning of a line.
137.Pp
138Prefixes are defined in the same was as standard units, but with
139a trailing dash at the end of the prefix name.
140If a unit is not found
141even after removing trailing 's' or 'es', then it will be checked
142against the list of prefixes.
143Prefixes will be removed until a legal
144base unit is identified.
145.Pp
146Here is an example of a short units file that defines some basic
147units.
148.Pp
149.Bl -column -offset indent -compact "minute"
150.It "m	!a!
151.It "sec	!b!
152.It "micro-	1e-6
153.It "minute	60 sec
154.It "hour	60 min
155.It "inch	0.0254 m
156.It "ft	12 inches
157.It "mile	5280 ft
158.El
159.Sh FILES
160.Bl -tag -width /usr/share/misc/units.lib -compact
161.It Pa /usr/share/misc/units.lib
162the standard units library
163.El
164.Sh AUTHORS
165.An Adrian Mariano Aq adrian@cam.cornell.edu
166.Sh BUGS
167The effect of including a '/' in a prefix is surprising.
168.Pp
169Exponents entered by the user can be only one digit.
170You can work around this by multiplying several terms.
171.Pp
172The user must use | to indicate division of numbers and / to
173indicate division of symbols.
174This distinction should not
175be necessary.
176.Pp
177The program contains various arbitrary limits on the length
178of the units converted and on the length of the data file.
179.Pp
180The program should use a hash table to store units so that
181it does not take so long to load the units list and check
182for duplication.
183