Sun Apr 3 19:44:15 2011 UTC ()
Expand user warning (adding examples) and move to CAVEATS as it's not fixable.


(dholland)
diff -r1.16 -r1.17 src/usr.bin/units/units.1
cvs diff -r1.16 -r1.17 src/usr.bin/units/units.1 (expand / switch to unified diff)

--- src/usr.bin/units/units.1 2011/04/03 19:25:05 1.16
+++ src/usr.bin/units/units.1 2011/04/03 19:44:15 1.17
@@ -1,15 +1,15 @@ @@ -1,15 +1,15 @@
1.\" $NetBSD: units.1,v 1.16 2011/04/03 19:25:05 dholland Exp $ 1.\" $NetBSD: units.1,v 1.17 2011/04/03 19:44:15 dholland Exp $
2.Dd March 28, 2011 2.Dd April 3, 2011
3.Dt UNITS 1 3.Dt UNITS 1
4.Os 4.Os
5.Sh NAME 5.Sh NAME
6.Nm units 6.Nm units
7.Nd conversion program 7.Nd conversion program
8.Sh SYNOPSIS 8.Sh SYNOPSIS
9.Nm 9.Nm
10.Op Fl f Ar filename 10.Op Fl f Ar filename
11.Op Fl qv 11.Op Fl qv
12.Oo 12.Oo
13.Op Ar count 13.Op Ar count
14.Ar from-unit to-unit 14.Ar from-unit to-unit
15.Oc 15.Oc
@@ -149,37 +149,60 @@ will not detect infinite loops that coul @@ -149,37 +149,60 @@ will not detect infinite loops that coul
149by careless unit definitions. 149by careless unit definitions.
150.Pp 150.Pp
151Prefixes are defined in the same way as standard units, but with 151Prefixes are defined in the same way as standard units, but with
152a trailing dash at the end of the prefix name. 152a trailing dash at the end of the prefix name.
153.Sh FILES 153.Sh FILES
154.Bl -tag -width /usr/share/misc/units.lib -compact 154.Bl -tag -width /usr/share/misc/units.lib -compact
155.It Pa /usr/share/misc/units.lib 155.It Pa /usr/share/misc/units.lib
156the standard units library 156the standard units library
157.El 157.El
158.Sh AUTHORS 158.Sh AUTHORS
159.An Adrian Mariano Aq adrian@cam.cornell.edu 159.An Adrian Mariano Aq adrian@cam.cornell.edu
160or 160or
161.Aq mariano@geom.umn.edu 161.Aq mariano@geom.umn.edu
 162.Sh CAVEATS
 163While
 164.Nm
 165can be used as a calculator for many unit-related computations,
 166caution is required: many computations require additional constant
 167factors deriving from the physics (or chemistry or whatever) of the
 168situation.
 169As these factors are dimensionless,
 170.Nm
 171cannot itself either provide them or warn the user when they have been
 172forgotten.
 173For example, one joule is one kilogram meter squared per second
 174squared, by definition; however, the kinetic energy of a one-kilogram
 175object moving at one meter per second is half a joule, not one joule,
 176because of a dimensionless factor that arises from integration.
 177.Pp
 178Also, some pairs of units that have the same dimensionality are
 179nonetheless used to measure different things and attempting to convert
 180between them may require additional fudge factors or be entirely
 181meaningless.
 182For example, torque and energy have the same dimensionality, but
 183attempting to convert torque in newton-meters to energy in joules is
 184nonsensical.
 185There is no practical way for
 186.Nm
 187to warn about these issues either.
162.Sh BUGS 188.Sh BUGS
163The effect of including a 189The effect of including a
164.Sq \&/ 190.Sq \&/
165in a prefix is surprising. 191in a prefix is surprising.
166.Pp 192.Pp
167Exponents entered by the user can be only one digit. 193Exponents entered by the user can be only one digit.
168You can work around this by multiplying several terms. 194You can work around this by multiplying several terms.
169.Pp 195.Pp
170The user must use 196The user must use
171.Sq \&| 197.Sq \&|
172to indicate division of numbers and 198to indicate division of numbers and
173.Sq \&/ 199.Sq \&/
174to indicate division of symbols. 200to indicate division of symbols.
175This distinction should not be necessary. 201This distinction should not be necessary.
176.Pp 202.Pp
177The program contains various arbitrary limits on the length 203The program contains various arbitrary limits on the length
178of the units converted and on the length of the data file. 204of the units converted and on the length of the data file.
179.Pp 205.Pp
180The program should use a hash table to store units so that 206The program should use a hash table to store units so that
181it doesn't take so long to load the units list and check 207it doesn't take so long to load the units list and check
182for duplication. 208for duplication.
183.Pp 
184The program should warn users when they're trying to perform a conversion 
185that doesn't make sense, since there are many such combinations.