[ODE] ODE Documentation

[Bram Stolk]

J. Perkins wrote:
> I'd like to start working on updating the install/build portion of the
> ODE documentation. I wanted to get some feedback on what people
> thought of the current single-page HTML format for the documentation.
> Would it be better to move the documentation to the wiki? Or perhaps
> something more like php.net, where topics are broken out to separate
> pages and people can leave comments?
> 
> The single-page HTML has the advantage of being easy to ship with the
> software, but obviously it falls out of date very easily. The
> wiki...well, the ODE wiki is just very ugly  but it seems to work. The
> php.net solution is most complicated (I'd probably install Drupal on
> opende.sf.net - see http://www.drupal.org/) but having the ability to
> answer FAQs right inline with the relevant documentation is a sweet
> feature.
> 
> I'm looking for input, let me know what you think and I'll try to get it done.

My recommendations are as follows:

Documentation is doomed to fail, if there are obstacles for updating.

Separate documentation into:
- User manual (tutorial style approach)
- Reference manual (api)

Let user manual be under the community's control: everyone can contribute,
the obstacle is very small. (-> WIKI)

To lower the obstacle for updates to ref manual: keep reference doc and
source code in same file. This is so called 'literate programming'.
The ref doc is then generated daily from svn sources by scanning for
c++ comments in the source that preceed the func defs.
I believe the doxygen tool can do this?

  Bram