Again, the issue about doxygen is not completeness. It is correctness, which is more important than completeness. 

The current state of Csound documentation, and of documentation in other similar open source projects, should be sufficient proof that good intentions will not in fact produce correct documentation. Doxygen won't either, but it will definitely get a lot closer. A handwritten intro can be used to provide a little bit of completeness.

Regards,
Mike

-----Original Message-----
From: Victor Lazzarini 
Sent: Nov 15, 2005 9:04 AM
To: csound-devel@lists.sourceforge.net
Subject: Re: [Cs-dev] Csound 5 Reference Manual

At 13:53 15/11/2005, you wrote:
>Victor Lazzarini wrote:
>
>>Csound 5 Reference Manual
>>1. Csound Language
>>         1.1  Frontends
>>                 1.1.1        Csound command-line program
>>                 1.1.2        CsoundVST
>>                 1.1.3        Csoundapi~
>>                 1.1.4        FlCsound
>>                 1.1.5        TclCsound
>>         1.2  Orchestra Language
>>         1.3  Score Language
>>2. Csound Utilities
>>         2.1  Analysis utilities
>>         2.2  File and soundfile utilities
>>         2.3  Score utilities
>>3. Csound Host API
>>         3.1  The C Language API
>>         3.2  Language Wrappers
>>                 3.2.1        Python
>>                 3.2.2        Java
>>                 3.2.3        Common Lisp
>>                 3.2.4        Tcl/Tk
>>4. Csound Module API
>
>Most of 1. and 2. (with the exception of the special frontends)
>is already in the CVS manual, although it may need to be better
>organized to improve the usability of the manual.

That was my idea.

>However, 3. and
>4. are largely undocumented at this time, so a lot of work is
>needed to add up to date API documentation. I would offer help in
>writing manuals, but the basic structure of the API documentation
>needs to be created first (perhaps with initially empty manual
>templates for each function first, which can be easily completed
>later by whoever has enough information on a particular issue).

Yes, that information is not generally available, apart from the
comments in the header files. What would be the most suitable
format? Something akin to man pages (section 3)? I agree that
we should have an unified format.

However, I am not too keen on using Doxygen-type documentation. I
think it would be better and more complete to do it by hand. I can offer
to do bits of it, if needed.



Victor Lazzarini
Music Technology Laboratory
Music Department
National University of Ireland, Maynooth 



-------------------------------------------------------
This SF.Net email is sponsored by the JBoss Inc.  Get Certified Today
Register for a JBoss Training Course.  Free Certification Exam
for All Training Attendees Through End of 2005. For more info visit:
http://ads.osdn.com/?ad_id=7628&alloc_id=16845&op=click
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/csound-devel





-------------------------------------------------------
This SF.Net email is sponsored by the JBoss Inc.  Get Certified Today
Register for a JBoss Training Course.  Free Certification Exam
for All Training Attendees Through End of 2005. For more info visit:
http://ads.osdn.com/?ad_id=7628&alloc_id=16845&op=click
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net