[measurements/measurements.git] / README


                                  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.3.

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:

- Robert Harder's Base 64 encoder/decoder ( http://iharder.net/base64 ), which
  he has placed in the public domain

- Code by me, Matt McCutchen, which I hereby place in the public domain

Measurements comes with absolutely no warranty.

~~~~
Commit	Line	Data
3a3b5f3c	1
dcaa07ec MM	2	Measurements
	3
	4	http://mattmccutchen.net/measurements/
	5
	6	Written and maintained by Matt McCutchen <matt@mattmccutchen.net>
	7
	8	This OpenOffice.org Calc add-in provides a basic set of spreadsheet functions
	9	for manipulating scientific measurements, tracking units of measure and
	10	significant figures.
3a3b5f3c	11
0aa80534	12	This is version 1.3.
c1a54286	13
dcaa07ec MM	14	To use
	15	------
	16	- You might like to look at the included demo spreadsheet,
	17	measurements-demo.ods .
	18
	19	- Input a measurement as a string consisting of a floating-point numerical
	20	value (scientific notation preferred), a space, and a unit expression. The
	21	unit expression consists of one or more unit symbols, each optionally raised
	22	to an integer power with ^, and separated by *, space (implied multiply), or
	23	/ (inverts the rest of the expression). Example: 1.20E3 kg*m^2/s^2 .
	24	Only a few units are supported so far; see the list in
	25	src/net/mattmccutchen/measurements/Unit.java .
	26
	27	- The number of significant figures is inferred from your entry. You can
	28	indicate that a number is exact by following it with a lowercase x.
	29
	30	- A measurement that does not contain a space is interpreted as an exact pure
	31	number (because the spreadsheet forgets the number of sig figs entered by the
	32	user anyway). To enter an inexact pure number, enter a formula containing a
	33	literal string with a trailing space: ="1.497 " .
	34
	35	- Use the M* functions (MADD, MSUB, MMUL, MDIV, MNEG, MPOWINT, MROOTINT, MPOW,
	36	MEXP, MLN) to do arithmetic on measurements. A computed result shows up as a
	37	scientific-notation value to the correct number of significant figures and
	38	units (for your benefit) followed by a code containing the add-in's
	39	representation of the result (including precision beyond the significant
	40	figures). Example: If mass is in A1 and volume is in A2, put this in A3 to
	41	compute the density: =MDIV(A1;A2) .
	42
	43	- The difference between MPOWINT and MPOW is that MPOW lets you use a
	44	pure-number measurement for the exponent but requires the base to be a pure
	45	number, while MPOWINT lets you use a base with units but requires the exponent
	46	to be an integer.
	47
	48	- To have a computed result shown in units other than the default, pass it and
	49	the desired unit expression to MSTRAS. Example: =MSTRAS("1 m^3";"L") . This
	50	affects only the user-friendly form, not the code.
	51
	52	- If you're picky and want to show the user-friendly form of a result without
	53	the code, use MCLEANSTR. There is also MCLEANSTRAS.
	54
	55	- If you see ERROR, something went wrong, but you have to guess what. :) A
	56	future version might have better diagnostics.
	57
	58	If you find bugs (which are almost certain to exist), please report them to me!
	59
	60	To build
	61	--------
	62	I build the add-in against the OpenOffice.org 3 SDK included with Fedora using
	63	the Eclipse Java builder for the Java code and a makefile for the other steps.
	64	This sequence builds the installable add-in (measurements.oxt):
	65
	66	$ . ./shell-setup
	67	$ make bin-types
	68	Refresh and build the project in Eclipse
	69	$ make
	70
	71	I'm not really confident in what I'm doing here, so your mileage may vary,
	72	especially with other packagings of the SDK.
	73
3a3b5f3c MM	74	Legal
3a3b5f3c MM	75	-----
6673bb34 MM	76	Measurements consists of:
	77
	78	- Robert Harder's Base 64 encoder/decoder ( http://iharder.net/base64 ), which
	79	he has placed in the public domain
	80
	81	- Code by me, Matt McCutchen, which I hereby place in the public domain
	82
	83	Measurements comes with absolutely no warranty.
3a3b5f3c	84
dcaa07ec	85	~~~~