I would very much prefer more than one manual here. The API reference (and the module reference) should be automatically generated from comments in the code by doxygen or some similar tool. Otherwise, it will inevitably get out of date. That is why these tools are used in almost all open source projects.

Regards,
Mike

-----Original Message-----
From: Istvan Varga 
Sent: Nov 15, 2005 8:53 AM
To: csound-devel@lists.sourceforge.net
Subject: Re: [Cs-dev] Csound 5 Reference Manual

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. 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).


-------------------------------------------------------
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

Michael Gogins wrote:

> I would very much prefer more than one manual here. The API reference
 > (and the module reference) should be automatically generated from comments
 > in the code by doxygen or some similar tool. Otherwise, it will inevitably
 > get out of date.

Unfortunately, the documentation in the comments is often not quite
sufficient for anything other than a quick reference on the basic
syntax. For a real, detailed manual you need more than just comments
extracted from headers (that is, unless you do not mind having comments
of 1-2 pages or more for each function in the header files).
While a real manual might not be a strict requirement for a Csound 5
release, it would definitely be useful to have eventually, and make it
easier for people new to the Csound API to actually use it without
running into weird problems or having to look at the source code to
find important information that is not in the header comments.
Last, but not least, a full documentation is also a description of
standard behavior (also with explicit mentioning of what is undefined)
that one can rely on without strange compatibility issues in later
releases.

> That is why these tools are used in almost all open source  projects.

Many of those projects have quite poor documentation (e.g. ALSA).


-------------------------------------------------------
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