[ODE] Updating ODE documentation (was: hello world)

[Russ Smith]

> Obviously Russ has better things to do
> with his time than write docs, so he doesnt do this.

my policy up to this point has been to make sure everything
in the public API is documented in the manual, so that a user knows
what features are available (there are a few exceptions such as the
math libs and error handling). so there is *some* documentation for
*most* things, but most things could use more detailed explanations
and such. as i get the time i try to make things clearer in the
manual, e.g. with the joint type pictures. but right now, a serious 
user of ODE is going to have to go elsewhere to get a grounding in 
basic physics concepts.

i consider better docs for ODE an absolute must-have requirement 
to make it useful for more people. most users of ODE will be 
people with software engineering backgrounds, not physics, and the
documentation should reflect this. so, for example, the contact
parameters like 'bounce' should be explained in intuitive terms,
with examples (but the equations are also there for reference).

some things like the 'slide' parameters, the CFM and ERP are
very non-intuitive, and whole chapters could be written about how
to use them.

a note on the naming: i used names like 'bounce' instead of 
'coefficient of resitiution' for a couple of reasons:
  * shorter C constant names (unless you used, say 'COR', which is
    not very informative).
  * the precise meaning of 'bounce' may change in the (distant) future
    if ODE ever supports multiple physical models.

russ.

--
Russell Smith
http://www.q12.org