[ODE] documentation initiative

[Luke Palmer]

John Miles writes:
> > Have you ever done any cross-platform development?  Yeah, everyone is
> > using windows, but a whole different everyone is using linux, OSX, etc.
> > And you have no idea how difficult it is (many times impossible) to make
> > something cross-platform without a pre-build step.
> 
> The resulting headers from the prebuild step really should be added to
> the distribution and hand-maintained.  The usual application for a
> build-time configurator is when you know that the only system you'll
> run on is the same as the one you're compiling on.  That doesn't apply
> in this case, and, at any rate, there are no CPU-specific definitions
> (e.g., AMD versus Intel, SSE versus 3DNow!) in config.h, just
> platform-specific ones.  You're not going to convince anyone that
> config.h could only have sprung forth from the brow of configurator.c.
> :)  

Hmm, I guess pre-build config is really only necessary among the *NIXes,
and it wouldn't be so much a pain to have #defines and a /D in the
project.

I guess my only standing concern is that already pointed out:  who will
do it?  We need a maintainer, because files get added, build flags get
changed, etc.  It's not easy maintaining things in both a Makefile and
some Microsoft format (I don't even know if it's text (?)).

But I'm now convinced that a VS project would be a good idea in CVS.

>  
> > It didn't take us much to build on windows, all you have to do is read
> > the Wiki, download GNU make (they point you right to it, and there's no
> > "install", just a copy), run a batch file, and type "make".  Simple
> > stuff for any programmer. 
> 
> ... until you try to build a .DLL, which is what many Windows people
> tend to want, at least during development.  Suddenly, life isn't so
> simple when you find that dInfinity == 0.0F in your application
> because the configurator didn't understand how to export symbols from
> a Win32 DLL properly.

Touché.  Didn't try that.

> >, which a lot of developers (contrary to your
> > claims) do.  Just the releases should be fine.
> 
> Unfortunately, as (many) others have noted, that's really not the case.

You're talking about a lot of developers working on platforms other than
Windows?  Well, I beg to differ, but for the sake of supressing a
nah-uh/uh-huh argument, I'll just leave this where it is.

Luke