[src/trunk]: src/usr.bin/units Expand user warning (adding examples) and move...

[dholland <dholland%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/d2ca7fceb5a1
branches:  trunk
changeset: 763765:d2ca7fceb5a1
user:      dholland <dholland%NetBSD.org@localhost>
date:      Sun Apr 03 19:44:15 2011 +0000

description:
Expand user warning (adding examples) and move to CAVEATS as it's not fixable.

diffstat:

 usr.bin/units/units.1 |  33 ++++++++++++++++++++++++++++-----
 1 files changed, 28 insertions(+), 5 deletions(-)

diffs (51 lines):

diff -r 292c4c446456 -r d2ca7fceb5a1 usr.bin/units/units.1
--- a/usr.bin/units/units.1     Sun Apr 03 19:25:05 2011 +0000
+++ b/usr.bin/units/units.1     Sun Apr 03 19:44:15 2011 +0000
@@ -1,5 +1,5 @@
-.\"    $NetBSD: units.1,v 1.16 2011/04/03 19:25:05 dholland Exp $
-.Dd March 28, 2011
+.\"    $NetBSD: units.1,v 1.17 2011/04/03 19:44:15 dholland Exp $
+.Dd April 3, 2011
 .Dt UNITS 1
 .Os
 .Sh NAME
@@ -159,6 +159,32 @@
 .An Adrian Mariano Aq adrian%cam.cornell.edu@localhost
 or
 .Aq mariano%geom.umn.edu@localhost
+.Sh CAVEATS
+While
+.Nm
+can be used as a calculator for many unit-related computations,
+caution is required: many computations require additional constant
+factors deriving from the physics (or chemistry or whatever) of the
+situation.
+As these factors are dimensionless,
+.Nm
+cannot itself either provide them or warn the user when they have been
+forgotten.
+For example, one joule is one kilogram meter squared per second
+squared, by definition; however, the kinetic energy of a one-kilogram
+object moving at one meter per second is half a joule, not one joule,
+because of a dimensionless factor that arises from integration.
+.Pp
+Also, some pairs of units that have the same dimensionality are
+nonetheless used to measure different things and attempting to convert
+between them may require additional fudge factors or be entirely
+meaningless.
+For example, torque and energy have the same dimensionality, but
+attempting to convert torque in newton-meters to energy in joules is
+nonsensical.
+There is no practical way for
+.Nm
+to warn about these issues either.
 .Sh BUGS
 The effect of including a
 .Sq \&/
@@ -180,6 +206,3 @@
 The program should use a hash table to store units so that
 it doesn't take so long to load the units list and check
 for duplication.
-.Pp
-The program should warn users when they're trying to perform a conversion
-that doesn't make sense, since there are many such combinations.