I am thinking in terms of a full reference manual for
csound,
both from the perspective of the csound language and the
csound lib and API. A 'definitive reference'.

I don't see too much of a distinction between users and
developers, from the point of view of reference manual.
We are all users anyway. But for csound language-only
users, we can always produce User's guides and tutorials,
as separate documents.

>
> 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&opclick
> _______________________________________________
> 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