[ODE] ODE Documentation

[STenyaK (Bruno Gonzalez)]

I agree. Doxygen should be complementary. Maybe something similar to what  
Ogre [  http://ogre3d.org  ] guys do could be done:

Documentation
=============
-Manual   --> Current ODE api
-API Reference    --> Doxygen generated docs
-Wiki (Tutorials etc)    --> other kinds of information, like    
http://www.ogre3d.org/wiki


On Fri, 31 Mar 2006 02:18:54 +0200, Geoff Carlton <gcarlton at iinet.net.au>  
wrote:

> If doxygen is introduced, it should be in parallel, rather than dropping
> the current doc.  I like doxygen, but have found the "out of the box"
> results leave much to be desired, especially compared ODE's the current
> API document.
>
> You just can't beat a high quality hand tailored PDF document, where
> everything is put into its own logical section.  A good document is more
> than just function definitions - each section has ideas that need to be
> conveyed first, such as the concept of what a joint is.  If I add a half
> dozen functions for offset geom, the document should have a new section
> explaining the idea, not just regenerate itself with a dozen new
> function hyperlinks on the main page.
>
> Does anybody know where the "source format" for the current document
> is?  If it were found, I would suggest a format for the API document be
> the converted to the OpenOffice ODF format.  It is a standard format,
> there are many free cross platform editors that use it, and OpenOffice
> can natively convert to PDF (and perhaps HTML?).  Given how solid the
> ODE API is, and how few changes there have been even now since 0.5, I
> would think it would be very easy to keep it in sync.
>
> So I would suggest three parts, at least in the short term:
>  - User manual (wiki, etc)
>  - API manual (single document, exported to PDF, HTML, DOC, etc)
>  - doxygen interface
>
> Geoff
>
>
>
> Jean-Sebastien Guay wrote:
>> Hello,
>>
>>
>>> Separate documentation into:
>>> - User manual (tutorial style approach)
>>> - Reference manual (api)
>>>
>>
>> I agree completely. The current user manual tries to be both and fails  
>> at both
>> IMVHO. A user manual should consist of several short pages with a  
>> how-to style
>> of writing. Then, if we need more implementation details, we can go  
>> check the
>> Doxygen reference.
>>
>> For a good example of this, see OpenSG's documentation. There's a  
>> tutorial
>> http://www.opensg.org/doc-1.6.0/TutorialIntroduction.html
>> and an API reference
>> http://www.opensg.org/doc-1.6.0/index.html
>>
>> In this case, they used Doxygen for both, but the tutorial could work as
>> straight HTML or anything else. A Wiki in this sense would work well,  
>> as long
>> as you keep pages short and to the point (easy to update, easy to find
>> information).
>>
>> J-S
>> --
>> ______________________________________________________
>> Jean-Sebastien Guay     jean-sebastien.guay at polymtl.ca
>>                          http://whitestar02.webhop.org
>> _______________________________________________
>> ODE mailing list
>> ODE at q12.org
>> http://q12.org/mailman/listinfo/ode
>>
>>
>>
> _______________________________________________
> ODE mailing list
> ODE at q12.org
> http://q12.org/mailman/listinfo/ode
>



-- 
Saludos,
     STenyaK

_______________________________________________
Site:   http://1ksurvivor.homeip.net  <1kSurvivor>
         http://motorsport-sim.org     <Motorsport>
         http://kwh.iespana.es         <KuantikalWareHouse>
         http://emuletutorial.info     <EmuleTutorial>
ICQ:    153709484
Mail:   stenyak AT gmail DOT net