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