Revamp the readme.

- Format it like the bigint readme.
- Add use instructions from the Web page.
- Add build instructions.

diff --git a/README b/README
index dcec653..c766aa0 100644 (file)
--- a/README
+++ b/README
@@ -1,10 +1,76 @@
-This is Measurements, an OpenOffice.org Calc add-in that provides
-functions for tracking units of measure and significant figures.
 
-See: http://mattmccutchen.net/measurements/
+                                  Measurements
+
+                     http://mattmccutchen.net/measurements/
+
+       Written and maintained by Matt McCutchen <matt@mattmccutchen.net>
+
+This OpenOffice.org Calc add-in provides a basic set of spreadsheet functions
+for manipulating scientific measurements, tracking units of measure and
+significant figures.
 
 This is version 1.1.
 
+To use
+------
+- You might like to look at the included demo spreadsheet,
+  measurements-demo.ods .
+
+- Input a measurement as a string consisting of a floating-point numerical
+  value (scientific notation preferred), a space, and a unit expression.  The
+  unit expression consists of one or more unit symbols, each optionally        raised
+  to an integer power with ^, and separated by *, space (implied multiply), or
+  / (inverts the rest of the expression).  Example: 1.20E3 kg*m^2/s^2 .
+  Only a few units are supported so far; see the list in
+  src/net/mattmccutchen/measurements/Unit.java .
+
+- The number of significant figures is inferred from your entry.  You can
+  indicate that a number is exact by following it with a lowercase x.
+
+- A measurement that does not contain a space is interpreted as an exact pure
+  number (because the spreadsheet forgets the number of sig figs entered by the
+  user anyway).  To enter an inexact pure number, enter a formula containing a
+  literal string with a trailing space: ="1.497 " .
+
+- Use the M* functions (MADD, MSUB, MMUL, MDIV, MNEG, MPOWINT, MROOTINT, MPOW,
+  MEXP, MLN) to do arithmetic on measurements.  A computed result shows up as a
+  scientific-notation value to the correct number of significant figures and
+  units (for your benefit) followed by a code containing the add-in's
+  representation of the result (including precision beyond the significant
+  figures).  Example: If mass is in A1 and volume is in A2, put this in A3 to
+  compute the density: =MDIV(A1;A2) .
+
+- The difference between MPOWINT and MPOW is that MPOW lets you        use a
+  pure-number measurement for the exponent but requires the base to be a pure
+  number, while MPOWINT lets you use a base with units but requires the exponent
+  to be an integer.
+
+- To have a computed result shown in units other than the default, pass it and
+  the desired unit expression to MSTRAS.  Example: =MSTRAS("1 m^3";"L") .  This
+  affects only the user-friendly form, not the code.
+
+- If you're picky and want to show the user-friendly form of a result without
+  the code, use MCLEANSTR.  There is also MCLEANSTRAS.
+
+- If you see ERROR, something went wrong, but you have to guess what.  :)  A
+  future version might have better diagnostics.
+
+If you find bugs (which are almost certain to exist), please report them to me!
+
+To build
+--------
+I build the add-in against the OpenOffice.org 3 SDK included with Fedora using
+the Eclipse Java builder for the Java code and a makefile for the other steps.
+This sequence builds the installable add-in (measurements.oxt):
+
+$ . ./shell-setup
+$ make bin-types
+Refresh and build the project in Eclipse
+$ make
+
+I'm not really confident in what I'm doing here, so your mileage may vary,
+especially with other packagings of the SDK.
+
 Legal
 -----
 Measurements consists of:
@@ -16,4 +82,4 @@ Measurements consists of:
 
 Measurements comes with absolutely no warranty.
 
--- Matt McCutchen <matt@mattmccutchen.net>
+~~~~