Victor's proposal was for one manual, my proposal is for two manuals.

Regards,
Mike

-----Original Message-----
From: Steven Yi 
Sent: Nov 15, 2005 1:36 PM
To: csound-devel@lists.sourceforge.net
Subject: Re: [Cs-dev] Csound 5 Reference Manual

Hi All,

I think the Java class library is very well documented, but on the
other hand, I find that the development tools used for Java are also
much more amenable for doing javadocs and encourages using that.  I
also find that most Java libraries publish API docs using Javadoc, but
also put out manuals that are more illustrative of how to use the API.
 So I see no problems with having both.

Regarding Victor's point in his first email, I am not sure I
understood correctly.  Is the proposal now for two manuals, one for
"Users" and one for "Developers"?  If so, I would think that:

>         1.2  Orchestra Language
>         1.3  Score Language

would belong in the Users manual.  Otherwise, setting up a stubbed
developer's manual shouldn't take too long to set up if someone would
like me to do so.  Just a matter of where to put it(in csound5
directory, create a new repository?).

steven


On 11/15/05, Michael Gogins  wrote:
> Then the comments should be fixed up, of course. They can have embedded XML or HTML tags. They also can reference external documents.
>
> I have no objection to long comments in header files. I do have objections to documentation that is not in sync with the code.
>
> For an example of a well documented API done this way, see the Java class library documentation.
>
> Regards,
> Mike
>
>
> -----Original Message-----
> From: Istvan Varga 
> Sent: Nov 15, 2005 11:15 AM
> To: csound-devel@lists.sourceforge.net
> Subject: Re: [Cs-dev] Csound 5 Reference Manual
>
> 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
> 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
> 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_idv28&alloc_id845&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_idv28&alloc_id845&op=click
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net