Hi folks, been a long time since I did any csounding, and I'm wondering
where the current documentation for the csound api for python would be
living.

thanks!
Iain



Send bugs reports to this list.
To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"

If you build Csound yourself, just run doxygen in the root Csound
directory. Otherwise, it's in the Windows installers. Don't know about
Unix/Linux.

Regards,
Mike

On 10/19/09, Iain Duncan  wrote:
> Hi folks, been a long time since I did any csounding, and I'm wondering
> where the current documentation for the csound api for python would be
> living.
>
> thanks!
> Iain
>
>
>
> Send bugs reports to this list.
> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> csound"
>

On Mon, 2009-10-19 at 00:55 -0400, Michael Gogins wrote:
> If you build Csound yourself, just run doxygen in the root Csound
> directory. Otherwise, it's in the Windows installers. Don't know about
> Unix/Linux.

Thanks, that worked. I guess that there is not 'python specific' docs
though, we just cross reference with the C/C++ docs and sort it out?

thanks for your help tonight Mike
Iain




Send bugs reports to this list.
To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"

That's right. It's pretty much a one to one mapping.

Regards,
Mike

On 10/19/09, Iain Duncan  wrote:
> On Mon, 2009-10-19 at 00:55 -0400, Michael Gogins wrote:
>> If you build Csound yourself, just run doxygen in the root Csound
>> directory. Otherwise, it's in the Windows installers. Don't know about
>> Unix/Linux.
>
> Thanks, that worked. I guess that there is not 'python specific' docs
> though, we just cross reference with the C/C++ docs and sort it out?
>
> thanks for your help tonight Mike
> Iain
>
>
>
>
> Send bugs reports to this list.
> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> csound"
>

These docs need to be online somewhere. People need to be able to find
them either at sourceforge, csounds, or a search engine.  The API is
becoming more and more import as time goes on, and not having
documentation readily available is likely stopping a lot of people
from even trying it out.

Best,
Jake


On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
 wrote:
> If you build Csound yourself, just run doxygen in the root Csound
> directory. Otherwise, it's in the Windows installers. Don't know about
> Unix/Linux.
>
> Regards,
> Mike
>
> On 10/19/09, Iain Duncan  wrote:
>> Hi folks, been a long time since I did any csounding, and I'm wondering
>> where the current documentation for the csound api for python would be
>> living.
>>
>> thanks!
>> Iain
>>
>>
>>
>> Send bugs reports to this list.
>> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
>> csound"
>>
>
>
> --
> Michael Gogins
> Irreducible Productions
> http://www.michael-gogins.com
> Michael dot Gogins at gmail dot com
>
>
> Send bugs reports to this list.
> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"
>


Send bugs reports to this list.
To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"

yes, and for five years I have been thinking I ought to write an API
reference manual but never quite managed.

Victor
On 20 Oct 2009, at 15:03, Jacob Joaquin wrote:

> These docs need to be online somewhere. People need to be able to find
> them either at sourceforge, csounds, or a search engine.  The API is
> becoming more and more import as time goes on, and not having
> documentation readily available is likely stopping a lot of people
> from even trying it out.
>
> Best,
> Jake
>
>
> On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
>  wrote:
>> If you build Csound yourself, just run doxygen in the root Csound
>> directory. Otherwise, it's in the Windows installers. Don't know  
>> about
>> Unix/Linux.
>>
>> Regards,
>> Mike
>>
>> On 10/19/09, Iain Duncan  wrote:
>>> Hi folks, been a long time since I did any csounding, and I'm  
>>> wondering
>>> where the current documentation for the csound api for python  
>>> would be
>>> living.
>>>
>>> thanks!
>>> Iain
>>>
>>>
>>>
>>> Send bugs reports to this list.
>>> To unsubscribe, send email sympa@lists.bath.ac.uk with body  
>>> "unsubscribe
>>> csound"
>>>
>>
>>
>> --
>> Michael Gogins
>> Irreducible Productions
>> http://www.michael-gogins.com
>> Michael dot Gogins at gmail dot com
>>
>>
>> Send bugs reports to this list.
>> To unsubscribe, send email sympa@lists.bath.ac.uk with body  
>> "unsubscribe csound"
>>
>
>
> Send bugs reports to this list.
> To unsubscribe, send email sympa@lists.bath.ac.uk with body  
> "unsubscribe csound"



Send bugs reports to this list.
To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"

On Tue, 2009-10-20 at 07:03 -0700, Jacob Joaquin wrote:
> These docs need to be online somewhere. People need to be able to find
> them either at sourceforge, csounds, or a search engine.  The API is
> becoming more and more import as time goes on, and not having
> documentation readily available is likely stopping a lot of people
> from even trying it out.

I didn't want to complain too loudly given that I just reshowed my face
here, but I second that. I googled for Csound API docs, and the most
recent things I found were papers from three years ago. It's currently
*way* too hard to find api docs if the plan is to have the api adopted
to any degree by third parties.

Iain

> 
> Best,
> Jake
> 
> 
> On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
>  wrote:
> > If you build Csound yourself, just run doxygen in the root Csound
> > directory. Otherwise, it's in the Windows installers. Don't know about
> > Unix/Linux.
> >
> > Regards,
> > Mike
> >
> > On 10/19/09, Iain Duncan  wrote:
> >> Hi folks, been a long time since I did any csounding, and I'm wondering
> >> where the current documentation for the csound api for python would be
> >> living.
> >>
> >> thanks!
> >> Iain
> >>
> >>
> >>
> >> Send bugs reports to this list.
> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> >> csound"
> >>
> >
> >
> > --
> > Michael Gogins
> > Irreducible Productions
> > http://www.michael-gogins.com
> > Michael dot Gogins at gmail dot com
> >
> >
> > Send bugs reports to this list.
> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"
> >
> 
> 
> Send bugs reports to this list.
> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"



Send bugs reports to this list.
To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"

On Tue, 2009-10-20 at 16:15 +0100, Victor Lazzarini wrote:
> yes, and for five years I have been thinking I ought to write an API
> reference manual but never quite managed.

It seems like is perhaps a lot of scattered api knowledge. Does anyone
have suggestions for how to centralize recipes, docs, etc? A wiki site?

Iain

> 
> Victor
> On 20 Oct 2009, at 15:03, Jacob Joaquin wrote:
> 
> > These docs need to be online somewhere. People need to be able to find
> > them either at sourceforge, csounds, or a search engine.  The API is
> > becoming more and more import as time goes on, and not having
> > documentation readily available is likely stopping a lot of people
> > from even trying it out.
> >
> > Best,
> > Jake
> >
> >
> > On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
> >  wrote:
> >> If you build Csound yourself, just run doxygen in the root Csound
> >> directory. Otherwise, it's in the Windows installers. Don't know  
> >> about
> >> Unix/Linux.
> >>
> >> Regards,
> >> Mike
> >>
> >> On 10/19/09, Iain Duncan  wrote:
> >>> Hi folks, been a long time since I did any csounding, and I'm  
> >>> wondering
> >>> where the current documentation for the csound api for python  
> >>> would be
> >>> living.
> >>>
> >>> thanks!
> >>> Iain
> >>>
> >>>
> >>>
> >>> Send bugs reports to this list.
> >>> To unsubscribe, send email sympa@lists.bath.ac.uk with body  
> >>> "unsubscribe
> >>> csound"
> >>>
> >>
> >>
> >> --
> >> Michael Gogins
> >> Irreducible Productions
> >> http://www.michael-gogins.com
> >> Michael dot Gogins at gmail dot com
> >>
> >>
> >> Send bugs reports to this list.
> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body  
> >> "unsubscribe csound"
> >>
> >
> >
> > Send bugs reports to this list.
> > To unsubscribe, send email sympa@lists.bath.ac.uk with body  
> > "unsubscribe csound"
> 
> 
> 
> Send bugs reports to this list.
> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"



Send bugs reports to this list.
To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"

I think a wiki for this would be great, lots of info gets posted
sporadically on this forum but it would be great to have a centralised
resource, could we put one up on the sourceforge page?


2009/10/20 Iain Duncan :
> On Tue, 2009-10-20 at 16:15 +0100, Victor Lazzarini wrote:
>> yes, and for five years I have been thinking I ought to write an API
>> reference manual but never quite managed.
>
> It seems like is perhaps a lot of scattered api knowledge. Does anyone
> have suggestions for how to centralize recipes, docs, etc? A wiki site?
>
> Iain
>
>>
>> Victor
>> On 20 Oct 2009, at 15:03, Jacob Joaquin wrote:
>>
>> > These docs need to be online somewhere. People need to be able to find
>> > them either at sourceforge, csounds, or a search engine.  The API is
>> > becoming more and more import as time goes on, and not having
>> > documentation readily available is likely stopping a lot of people
>> > from even trying it out.
>> >
>> > Best,
>> > Jake
>> >
>> >
>> > On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
>> >  wrote:
>> >> If you build Csound yourself, just run doxygen in the root Csound
>> >> directory. Otherwise, it's in the Windows installers. Don't know
>> >> about
>> >> Unix/Linux.
>> >>
>> >> Regards,
>> >> Mike
>> >>
>> >> On 10/19/09, Iain Duncan  wrote:
>> >>> Hi folks, been a long time since I did any csounding, and I'm
>> >>> wondering
>> >>> where the current documentation for the csound api for python
>> >>> would be
>> >>> living.
>> >>>
>> >>> thanks!
>> >>> Iain
>> >>>
>> >>>
>> >>>
>> >>> Send bugs reports to this list.
>> >>> To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >>> "unsubscribe
>> >>> csound"
>> >>>
>> >>
>> >>
>> >> --
>> >> Michael Gogins
>> >> Irreducible Productions
>> >> http://www.michael-gogins.com
>> >> Michael dot Gogins at gmail dot com
>> >>
>> >>
>> >> Send bugs reports to this list.
>> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> "unsubscribe csound"
>> >>
>> >
>> >
>> > Send bugs reports to this list.
>> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> > "unsubscribe csound"
>>
>>
>>
>> Send bugs reports to this list.
>> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"
>
>
>
> Send bugs reports to this list.
> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"
>


Send bugs reports to this list.
To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"

The API documents are included in the Windows installers. They could
easily be included in the Linux packages and put online.

Regards,
Mike

On 10/20/09, Iain Duncan  wrote:
> On Tue, 2009-10-20 at 07:03 -0700, Jacob Joaquin wrote:
>> These docs need to be online somewhere. People need to be able to find
>> them either at sourceforge, csounds, or a search engine.  The API is
>> becoming more and more import as time goes on, and not having
>> documentation readily available is likely stopping a lot of people
>> from even trying it out.
>
> I didn't want to complain too loudly given that I just reshowed my face
> here, but I second that. I googled for Csound API docs, and the most
> recent things I found were papers from three years ago. It's currently
> *way* too hard to find api docs if the plan is to have the api adopted
> to any degree by third parties.
>
> Iain
>
>>
>> Best,
>> Jake
>>
>>
>> On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
>>  wrote:
>> > If you build Csound yourself, just run doxygen in the root Csound
>> > directory. Otherwise, it's in the Windows installers. Don't know about
>> > Unix/Linux.
>> >
>> > Regards,
>> > Mike
>> >
>> > On 10/19/09, Iain Duncan  wrote:
>> >> Hi folks, been a long time since I did any csounding, and I'm wondering
>> >> where the current documentation for the csound api for python would be
>> >> living.
>> >>
>> >> thanks!
>> >> Iain
>> >>
>> >>
>> >>
>> >> Send bugs reports to this list.
>> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> "unsubscribe
>> >> csound"
>> >>
>> >
>> >
>> > --
>> > Michael Gogins
>> > Irreducible Productions
>> > http://www.michael-gogins.com
>> > Michael dot Gogins at gmail dot com
>> >
>> >
>> > Send bugs reports to this list.
>> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
>> > csound"
>> >
>>
>>
>> Send bugs reports to this list.
>> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
>> csound"
>
>
>
> Send bugs reports to this list.
> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> csound"
>

The debian packages include them in libcsound64-doc.
I see that csounds.com has the (old?) pdf version of the manual, maybe
it should be replaced by the html versions?

On Tue, 2009-10-20 at 15:53 -0400, Michael Gogins wrote:
> The API documents are included in the Windows installers. They could
> easily be included in the Linux packages and put online.
> 
> Regards,
> Mike
> 
> On 10/20/09, Iain Duncan  wrote:
> > On Tue, 2009-10-20 at 07:03 -0700, Jacob Joaquin wrote:
> >> These docs need to be online somewhere. People need to be able to find
> >> them either at sourceforge, csounds, or a search engine.  The API is
> >> becoming more and more import as time goes on, and not having
> >> documentation readily available is likely stopping a lot of people
> >> from even trying it out.
> >
> > I didn't want to complain too loudly given that I just reshowed my face
> > here, but I second that. I googled for Csound API docs, and the most
> > recent things I found were papers from three years ago. It's currently
> > *way* too hard to find api docs if the plan is to have the api adopted
> > to any degree by third parties.
> >
> > Iain
> >
> >>
> >> Best,
> >> Jake
> >>
> >>
> >> On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
> >>  wrote:
> >> > If you build Csound yourself, just run doxygen in the root Csound
> >> > directory. Otherwise, it's in the Windows installers. Don't know about
> >> > Unix/Linux.
> >> >
> >> > Regards,
> >> > Mike
> >> >
> >> > On 10/19/09, Iain Duncan  wrote:
> >> >> Hi folks, been a long time since I did any csounding, and I'm wondering
> >> >> where the current documentation for the csound api for python would be
> >> >> living.
> >> >>
> >> >> thanks!
> >> >> Iain
> >> >>
> >> >>
> >> >>
> >> >> Send bugs reports to this list.
> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >> >> "unsubscribe
> >> >> csound"
> >> >>
> >> >
> >> >
> >> > --
> >> > Michael Gogins
> >> > Irreducible Productions
> >> > http://www.michael-gogins.com
> >> > Michael dot Gogins at gmail dot com
> >> >
> >> >
> >> > Send bugs reports to this list.
> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> >> > csound"
> >> >
> >>
> >>
> >> Send bugs reports to this list.
> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> >> csound"
> >
> >
> >
> > Send bugs reports to this list.
> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> > csound"
> >
> 
> 


-- 
Saludos,
Felipe Sateler

On Tue, 2009-10-20 at 15:53 -0400, Michael Gogins wrote:
> The API documents are included in the Windows installers. They could
> easily be included in the Linux packages and put online.
> 

I'm not sure that would change adequately what happens, ( or rather
doesn't!) when one googles 'csound API', know what I mean? It's like a
hidden project. ;-)

Iain


> Regards,
> Mike
> 
> On 10/20/09, Iain Duncan  wrote:
> > On Tue, 2009-10-20 at 07:03 -0700, Jacob Joaquin wrote:
> >> These docs need to be online somewhere. People need to be able to find
> >> them either at sourceforge, csounds, or a search engine.  The API is
> >> becoming more and more import as time goes on, and not having
> >> documentation readily available is likely stopping a lot of people
> >> from even trying it out.
> >
> > I didn't want to complain too loudly given that I just reshowed my face
> > here, but I second that. I googled for Csound API docs, and the most
> > recent things I found were papers from three years ago. It's currently
> > *way* too hard to find api docs if the plan is to have the api adopted
> > to any degree by third parties.
> >
> > Iain
> >
> >>
> >> Best,
> >> Jake
> >>
> >>
> >> On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
> >>  wrote:
> >> > If you build Csound yourself, just run doxygen in the root Csound
> >> > directory. Otherwise, it's in the Windows installers. Don't know about
> >> > Unix/Linux.
> >> >
> >> > Regards,
> >> > Mike
> >> >
> >> > On 10/19/09, Iain Duncan  wrote:
> >> >> Hi folks, been a long time since I did any csounding, and I'm wondering
> >> >> where the current documentation for the csound api for python would be
> >> >> living.
> >> >>
> >> >> thanks!
> >> >> Iain
> >> >>
> >> >>
> >> >>
> >> >> Send bugs reports to this list.
> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >> >> "unsubscribe
> >> >> csound"
> >> >>
> >> >
> >> >
> >> > --
> >> > Michael Gogins
> >> > Irreducible Productions
> >> > http://www.michael-gogins.com
> >> > Michael dot Gogins at gmail dot com
> >> >
> >> >
> >> > Send bugs reports to this list.
> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> >> > csound"
> >> >
> >>
> >>
> >> Send bugs reports to this list.
> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> >> csound"
> >
> >
> >
> > Send bugs reports to this list.
> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> > csound"
> >
> 
> 



Send bugs reports to this list.
To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"

I've never thought about it that way, but yeah, hidden project sounds
about right. The term API isn't even present in the table of contents
of the Csound manual.

Best,
Jake
---
The Csound Blog - http://csound.noisepages.com/



On Tue, Oct 20, 2009 at 6:24 PM, Iain Duncan  wrote:
> On Tue, 2009-10-20 at 15:53 -0400, Michael Gogins wrote:
>> The API documents are included in the Windows installers. They could
>> easily be included in the Linux packages and put online.
>>
>
> I'm not sure that would change adequately what happens, ( or rather
> doesn't!) when one googles 'csound API', know what I mean? It's like a
> hidden project. ;-)
>
> Iain
>
>
>> Regards,
>> Mike
>>
>> On 10/20/09, Iain Duncan  wrote:
>> > On Tue, 2009-10-20 at 07:03 -0700, Jacob Joaquin wrote:
>> >> These docs need to be online somewhere. People need to be able to find
>> >> them either at sourceforge, csounds, or a search engine.  The API is
>> >> becoming more and more import as time goes on, and not having
>> >> documentation readily available is likely stopping a lot of people
>> >> from even trying it out.
>> >
>> > I didn't want to complain too loudly given that I just reshowed my face
>> > here, but I second that. I googled for Csound API docs, and the most
>> > recent things I found were papers from three years ago. It's currently
>> > *way* too hard to find api docs if the plan is to have the api adopted
>> > to any degree by third parties.
>> >
>> > Iain
>> >
>> >>
>> >> Best,
>> >> Jake
>> >>
>> >>
>> >> On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
>> >>  wrote:
>> >> > If you build Csound yourself, just run doxygen in the root Csound
>> >> > directory. Otherwise, it's in the Windows installers. Don't know about
>> >> > Unix/Linux.
>> >> >
>> >> > Regards,
>> >> > Mike
>> >> >
>> >> > On 10/19/09, Iain Duncan  wrote:
>> >> >> Hi folks, been a long time since I did any csounding, and I'm wondering
>> >> >> where the current documentation for the csound api for python would be
>> >> >> living.
>> >> >>
>> >> >> thanks!
>> >> >> Iain
>> >> >>
>> >> >>
>> >> >>
>> >> >> Send bugs reports to this list.
>> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> >> "unsubscribe
>> >> >> csound"
>> >> >>
>> >> >
>> >> >
>> >> > --
>> >> > Michael Gogins
>> >> > Irreducible Productions
>> >> > http://www.michael-gogins.com
>> >> > Michael dot Gogins at gmail dot com
>> >> >
>> >> >
>> >> > Send bugs reports to this list.
>> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
>> >> > csound"
>> >> >
>> >>
>> >>
>> >> Send bugs reports to this list.
>> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
>> >> csound"
>> >
>> >
>> >
>> > Send bugs reports to this list.
>> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
>> > csound"
>> >
>>
>>
>
>
>
> Send bugs reports to this list.
> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"
>


Send bugs reports to this list.
To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"

On Tue, 2009-10-20 at 19:08 -0700, Jacob Joaquin wrote:
> I've never thought about it that way, but yeah, hidden project sounds
> about right. The term API isn't even present in the table of contents
> of the Csound manual.

Has anyone thought of using Sphinx? For python projects it makes
producing hand written docs much easier, and it's possible to include
docstests that run right while building the docs. And the generated html
is great. 

I guess really what the API needs is a users guide, up online in some
format that is easily crawled. 

Iain

> 
> Best,
> Jake
> ---
> The Csound Blog - http://csound.noisepages.com/
> 
> 
> 
> On Tue, Oct 20, 2009 at 6:24 PM, Iain Duncan  wrote:
> > On Tue, 2009-10-20 at 15:53 -0400, Michael Gogins wrote:
> >> The API documents are included in the Windows installers. They could
> >> easily be included in the Linux packages and put online.
> >>
> >
> > I'm not sure that would change adequately what happens, ( or rather
> > doesn't!) when one googles 'csound API', know what I mean? It's like a
> > hidden project. ;-)
> >
> > Iain
> >
> >
> >> Regards,
> >> Mike
> >>
> >> On 10/20/09, Iain Duncan  wrote:
> >> > On Tue, 2009-10-20 at 07:03 -0700, Jacob Joaquin wrote:
> >> >> These docs need to be online somewhere. People need to be able to find
> >> >> them either at sourceforge, csounds, or a search engine.  The API is
> >> >> becoming more and more import as time goes on, and not having
> >> >> documentation readily available is likely stopping a lot of people
> >> >> from even trying it out.
> >> >
> >> > I didn't want to complain too loudly given that I just reshowed my face
> >> > here, but I second that. I googled for Csound API docs, and the most
> >> > recent things I found were papers from three years ago. It's currently
> >> > *way* too hard to find api docs if the plan is to have the api adopted
> >> > to any degree by third parties.
> >> >
> >> > Iain
> >> >
> >> >>
> >> >> Best,
> >> >> Jake
> >> >>
> >> >>
> >> >> On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
> >> >>  wrote:
> >> >> > If you build Csound yourself, just run doxygen in the root Csound
> >> >> > directory. Otherwise, it's in the Windows installers. Don't know about
> >> >> > Unix/Linux.
> >> >> >
> >> >> > Regards,
> >> >> > Mike
> >> >> >
> >> >> > On 10/19/09, Iain Duncan  wrote:
> >> >> >> Hi folks, been a long time since I did any csounding, and I'm wondering
> >> >> >> where the current documentation for the csound api for python would be
> >> >> >> living.
> >> >> >>
> >> >> >> thanks!
> >> >> >> Iain
> >> >> >>
> >> >> >>
> >> >> >>
> >> >> >> Send bugs reports to this list.
> >> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >> >> >> "unsubscribe
> >> >> >> csound"
> >> >> >>
> >> >> >
> >> >> >
> >> >> > --
> >> >> > Michael Gogins
> >> >> > Irreducible Productions
> >> >> > http://www.michael-gogins.com
> >> >> > Michael dot Gogins at gmail dot com
> >> >> >
> >> >> >
> >> >> > Send bugs reports to this list.
> >> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> >> >> > csound"
> >> >> >
> >> >>
> >> >>
> >> >> Send bugs reports to this list.
> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> >> >> csound"
> >> >
> >> >
> >> >
> >> > Send bugs reports to this list.
> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> >> > csound"
> >> >
> >>
> >>
> >
> >
> >
> > Send bugs reports to this list.
> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"
> >
> 
> 
> Send bugs reports to this list.
> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"



Send bugs reports to this list.
To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"

Yes, it should be replaced by the html.

Mkg

On Oct 20, 2009 6:43 PM, "Felipe Sateler" <fsateler@gmail.com> wrote:

The debian packages include them in libcsound64-doc.
I see that csounds.com has the (old?) pdf version of the manual, maybe
it should be replaced by the html versions?

On Tue, 2009-10-20 at 15:53 -0400, Michael Gogins wrote: > The API documents are included in the Wi...

Saludos,
Felipe Sateler

Putting it online, i.e. at csounds.com, would solve that problem.

Regards,
Mike

On 10/20/09, Iain Duncan  wrote:
> On Tue, 2009-10-20 at 15:53 -0400, Michael Gogins wrote:
>> The API documents are included in the Windows installers. They could
>> easily be included in the Linux packages and put online.
>>
>
> I'm not sure that would change adequately what happens, ( or rather
> doesn't!) when one googles 'csound API', know what I mean? It's like a
> hidden project. ;-)
>
> Iain
>
>
>> Regards,
>> Mike
>>
>> On 10/20/09, Iain Duncan  wrote:
>> > On Tue, 2009-10-20 at 07:03 -0700, Jacob Joaquin wrote:
>> >> These docs need to be online somewhere. People need to be able to find
>> >> them either at sourceforge, csounds, or a search engine.  The API is
>> >> becoming more and more import as time goes on, and not having
>> >> documentation readily available is likely stopping a lot of people
>> >> from even trying it out.
>> >
>> > I didn't want to complain too loudly given that I just reshowed my face
>> > here, but I second that. I googled for Csound API docs, and the most
>> > recent things I found were papers from three years ago. It's currently
>> > *way* too hard to find api docs if the plan is to have the api adopted
>> > to any degree by third parties.
>> >
>> > Iain
>> >
>> >>
>> >> Best,
>> >> Jake
>> >>
>> >>
>> >> On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
>> >>  wrote:
>> >> > If you build Csound yourself, just run doxygen in the root Csound
>> >> > directory. Otherwise, it's in the Windows installers. Don't know
>> >> > about
>> >> > Unix/Linux.
>> >> >
>> >> > Regards,
>> >> > Mike
>> >> >
>> >> > On 10/19/09, Iain Duncan  wrote:
>> >> >> Hi folks, been a long time since I did any csounding, and I'm
>> >> >> wondering
>> >> >> where the current documentation for the csound api for python would
>> >> >> be
>> >> >> living.
>> >> >>
>> >> >> thanks!
>> >> >> Iain
>> >> >>
>> >> >>
>> >> >>
>> >> >> Send bugs reports to this list.
>> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> >> "unsubscribe
>> >> >> csound"
>> >> >>
>> >> >
>> >> >
>> >> > --
>> >> > Michael Gogins
>> >> > Irreducible Productions
>> >> > http://www.michael-gogins.com
>> >> > Michael dot Gogins at gmail dot com
>> >> >
>> >> >
>> >> > Send bugs reports to this list.
>> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> > "unsubscribe
>> >> > csound"
>> >> >
>> >>
>> >>
>> >> Send bugs reports to this list.
>> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> "unsubscribe
>> >> csound"
>> >
>> >
>> >
>> > Send bugs reports to this list.
>> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
>> > csound"
>> >
>>
>>
>
>
>
> Send bugs reports to this list.
> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> csound"
>

Happy to host the Csound API and examples/models of API in use @  
cSounds.com

Dr. B.


Dr. Richard Boulanger  -  rboulanger@berklee.edu



On Oct 21, 2009, at 8:44 AM, Michael Gogins wrote:

> Putting it online, i.e. at csounds.com, would solve that problem.
>
> Regards,
> Mike
>
> On 10/20/09, Iain Duncan  wrote:
>> On Tue, 2009-10-20 at 15:53 -0400, Michael Gogins wrote:
>>> The API documents are included in the Windows installers. They could
>>> easily be included in the Linux packages and put online.
>>>
>>
>> I'm not sure that would change adequately what happens, ( or rather
>> doesn't!) when one googles 'csound API', know what I mean? It's  
>> like a
>> hidden project. ;-)
>>
>> Iain
>>
>>
>>> Regards,
>>> Mike
>>>
>>> On 10/20/09, Iain Duncan  wrote:
>>>> On Tue, 2009-10-20 at 07:03 -0700, Jacob Joaquin wrote:
>>>>> These docs need to be online somewhere. People need to be able  
>>>>> to find
>>>>> them either at sourceforge, csounds, or a search engine.  The  
>>>>> API is
>>>>> becoming more and more import as time goes on, and not having
>>>>> documentation readily available is likely stopping a lot of people
>>>>> from even trying it out.
>>>>
>>>> I didn't want to complain too loudly given that I just reshowed  
>>>> my face
>>>> here, but I second that. I googled for Csound API docs, and the  
>>>> most
>>>> recent things I found were papers from three years ago. It's  
>>>> currently
>>>> *way* too hard to find api docs if the plan is to have the api  
>>>> adopted
>>>> to any degree by third parties.
>>>>
>>>> Iain
>>>>
>>>>>
>>>>> Best,
>>>>> Jake
>>>>>
>>>>>
>>>>> On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
>>>>>  wrote:
>>>>>> If you build Csound yourself, just run doxygen in the root Csound
>>>>>> directory. Otherwise, it's in the Windows installers. Don't know
>>>>>> about
>>>>>> Unix/Linux.
>>>>>>
>>>>>> Regards,
>>>>>> Mike
>>>>>>
>>>>>> On 10/19/09, Iain Duncan  wrote:
>>>>>>> Hi folks, been a long time since I did any csounding, and I'm
>>>>>>> wondering
>>>>>>> where the current documentation for the csound api for python  
>>>>>>> would
>>>>>>> be
>>>>>>> living.
>>>>>>>
>>>>>>> thanks!
>>>>>>> Iain
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> Send bugs reports to this list.
>>>>>>> To unsubscribe, send email sympa@lists.bath.ac.uk with body
>>>>>>> "unsubscribe
>>>>>>> csound"
>>>>>>>
>>>>>>
>>>>>>
>>>>>> --
>>>>>> Michael Gogins
>>>>>> Irreducible Productions
>>>>>> http://www.michael-gogins.com
>>>>>> Michael dot Gogins at gmail dot com
>>>>>>
>>>>>>
>>>>>> Send bugs reports to this list.
>>>>>> To unsubscribe, send email sympa@lists.bath.ac.uk with body
>>>>>> "unsubscribe
>>>>>> csound"
>>>>>>
>>>>>
>>>>>
>>>>> Send bugs reports to this list.
>>>>> To unsubscribe, send email sympa@lists.bath.ac.uk with body
>>>>> "unsubscribe
>>>>> csound"
>>>>
>>>>
>>>>
>>>> Send bugs reports to this list.
>>>> To unsubscribe, send email sympa@lists.bath.ac.uk with body  
>>>> "unsubscribe
>>>> csound"
>>>>
>>>
>>>
>>
>>
>>
>> Send bugs reports to this list.
>> To unsubscribe, send email sympa@lists.bath.ac.uk with body  
>> "unsubscribe
>> csound"
>>
>
>
> -- 
> Michael Gogins
> Irreducible Productions
> http://www.michael-gogins.com
> Michael dot Gogins at gmail dot com
>
>
> Send bugs reports to this list.
> To unsubscribe, send email sympa@lists.bath.ac.uk with body  
> "unsubscribe csound"



Send bugs reports to this list.
To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"

On Wed, 2009-10-21 at 08:44 -0400, Michael Gogins wrote:
> Putting it online, i.e. at csounds.com, would solve that problem.

Ok, I guess we are not understanding each other. What I am getting at is
that the API docs are not what I would call adequate documentation for a
project if the project is intending to garner adoption. Compared to
other open source frameworks I use for my python web dev business, it is
very sparse. It's good, sure, put it is only a C/C++ reference manual.
Correct me if I'm wrong, but I don't see any examples or class
documentation for the python, java, or ruby wrappers. 

Now, I understand very few people like writing docs. But seriously, if
the goal is to encourage people to use the CsoudAPI, the doc situation
and online resource situation needs improving far beyond just putting
the api referrence on line. If that is not the goal, than no problem.
Maybe that is not the goal. It seems too bad though because you and
others have clearly put a ton of work into making the csound API
awesome, and frankly, I think outside of academia there is very very
little awareness of it for how long it's been around and so usable.

For examples of good documentation, I would say this is what I'm talking
about:

http://docs.repoze.org/bfg/1.1/

Note, narrative documentation, code examples, doctests, api docs,
tutorials, and examples, are all linked and part of the same web docs.
That's built with Sphinx by the way. 

Iain

> 
> Regards,
> Mike
> 
> On 10/20/09, Iain Duncan  wrote:
> > On Tue, 2009-10-20 at 15:53 -0400, Michael Gogins wrote:
> >> The API documents are included in the Windows installers. They could
> >> easily be included in the Linux packages and put online.
> >>
> >
> > I'm not sure that would change adequately what happens, ( or rather
> > doesn't!) when one googles 'csound API', know what I mean? It's like a
> > hidden project. ;-)
> >
> > Iain
> >
> >
> >> Regards,
> >> Mike
> >>
> >> On 10/20/09, Iain Duncan  wrote:
> >> > On Tue, 2009-10-20 at 07:03 -0700, Jacob Joaquin wrote:
> >> >> These docs need to be online somewhere. People need to be able to find
> >> >> them either at sourceforge, csounds, or a search engine.  The API is
> >> >> becoming more and more import as time goes on, and not having
> >> >> documentation readily available is likely stopping a lot of people
> >> >> from even trying it out.
> >> >
> >> > I didn't want to complain too loudly given that I just reshowed my face
> >> > here, but I second that. I googled for Csound API docs, and the most
> >> > recent things I found were papers from three years ago. It's currently
> >> > *way* too hard to find api docs if the plan is to have the api adopted
> >> > to any degree by third parties.
> >> >
> >> > Iain
> >> >
> >> >>
> >> >> Best,
> >> >> Jake
> >> >>
> >> >>
> >> >> On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
> >> >>  wrote:
> >> >> > If you build Csound yourself, just run doxygen in the root Csound
> >> >> > directory. Otherwise, it's in the Windows installers. Don't know
> >> >> > about
> >> >> > Unix/Linux.
> >> >> >
> >> >> > Regards,
> >> >> > Mike
> >> >> >
> >> >> > On 10/19/09, Iain Duncan  wrote:
> >> >> >> Hi folks, been a long time since I did any csounding, and I'm
> >> >> >> wondering
> >> >> >> where the current documentation for the csound api for python would
> >> >> >> be
> >> >> >> living.
> >> >> >>
> >> >> >> thanks!
> >> >> >> Iain
> >> >> >>
> >> >> >>
> >> >> >>
> >> >> >> Send bugs reports to this list.
> >> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >> >> >> "unsubscribe
> >> >> >> csound"
> >> >> >>
> >> >> >
> >> >> >
> >> >> > --
> >> >> > Michael Gogins
> >> >> > Irreducible Productions
> >> >> > http://www.michael-gogins.com
> >> >> > Michael dot Gogins at gmail dot com
> >> >> >
> >> >> >
> >> >> > Send bugs reports to this list.
> >> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >> >> > "unsubscribe
> >> >> > csound"
> >> >> >
> >> >>
> >> >>
> >> >> Send bugs reports to this list.
> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >> >> "unsubscribe
> >> >> csound"
> >> >
> >> >
> >> >
> >> > Send bugs reports to this list.
> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> >> > csound"
> >> >
> >>
> >>
> >
> >
> >
> > Send bugs reports to this list.
> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> > csound"
> >
> 
> 



Send bugs reports to this list.
To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"

The repoze manual that you cite as an example is organized in just the
way I suggest. The top-level manual is the "User's Guide." This
includes, as a section, the "API Reference" which, no surprise, is
automatically generated by a tool from comments in source code (the
tool, in this case, is called Sphinx (http://sphinx.pocoo.org/).

In short, it doesn't matter how the material "looks," what matters is
how it "is." There is a manually written user's guide and an
automatically generated generated reference manual here, just as there
is in something like a majority of software documentation.

Regards,
Mike

On 10/21/09, Iain Duncan  wrote:
> On Wed, 2009-10-21 at 08:44 -0400, Michael Gogins wrote:
>> Putting it online, i.e. at csounds.com, would solve that problem.
>
> Ok, I guess we are not understanding each other. What I am getting at is
> that the API docs are not what I would call adequate documentation for a
> project if the project is intending to garner adoption. Compared to
> other open source frameworks I use for my python web dev business, it is
> very sparse. It's good, sure, put it is only a C/C++ reference manual.
> Correct me if I'm wrong, but I don't see any examples or class
> documentation for the python, java, or ruby wrappers.
>
> Now, I understand very few people like writing docs. But seriously, if
> the goal is to encourage people to use the CsoudAPI, the doc situation
> and online resource situation needs improving far beyond just putting
> the api referrence on line. If that is not the goal, than no problem.
> Maybe that is not the goal. It seems too bad though because you and
> others have clearly put a ton of work into making the csound API
> awesome, and frankly, I think outside of academia there is very very
> little awareness of it for how long it's been around and so usable.
>
> For examples of good documentation, I would say this is what I'm talking
> about:
>
> http://docs.repoze.org/bfg/1.1/
>
> Note, narrative documentation, code examples, doctests, api docs,
> tutorials, and examples, are all linked and part of the same web docs.
> That's built with Sphinx by the way.
>
> Iain
>
>>
>> Regards,
>> Mike
>>
>> On 10/20/09, Iain Duncan  wrote:
>> > On Tue, 2009-10-20 at 15:53 -0400, Michael Gogins wrote:
>> >> The API documents are included in the Windows installers. They could
>> >> easily be included in the Linux packages and put online.
>> >>
>> >
>> > I'm not sure that would change adequately what happens, ( or rather
>> > doesn't!) when one googles 'csound API', know what I mean? It's like a
>> > hidden project. ;-)
>> >
>> > Iain
>> >
>> >
>> >> Regards,
>> >> Mike
>> >>
>> >> On 10/20/09, Iain Duncan  wrote:
>> >> > On Tue, 2009-10-20 at 07:03 -0700, Jacob Joaquin wrote:
>> >> >> These docs need to be online somewhere. People need to be able to
>> >> >> find
>> >> >> them either at sourceforge, csounds, or a search engine.  The API is
>> >> >> becoming more and more import as time goes on, and not having
>> >> >> documentation readily available is likely stopping a lot of people
>> >> >> from even trying it out.
>> >> >
>> >> > I didn't want to complain too loudly given that I just reshowed my
>> >> > face
>> >> > here, but I second that. I googled for Csound API docs, and the most
>> >> > recent things I found were papers from three years ago. It's
>> >> > currently
>> >> > *way* too hard to find api docs if the plan is to have the api
>> >> > adopted
>> >> > to any degree by third parties.
>> >> >
>> >> > Iain
>> >> >
>> >> >>
>> >> >> Best,
>> >> >> Jake
>> >> >>
>> >> >>
>> >> >> On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
>> >> >>  wrote:
>> >> >> > If you build Csound yourself, just run doxygen in the root Csound
>> >> >> > directory. Otherwise, it's in the Windows installers. Don't know
>> >> >> > about
>> >> >> > Unix/Linux.
>> >> >> >
>> >> >> > Regards,
>> >> >> > Mike
>> >> >> >
>> >> >> > On 10/19/09, Iain Duncan  wrote:
>> >> >> >> Hi folks, been a long time since I did any csounding, and I'm
>> >> >> >> wondering
>> >> >> >> where the current documentation for the csound api for python
>> >> >> >> would
>> >> >> >> be
>> >> >> >> living.
>> >> >> >>
>> >> >> >> thanks!
>> >> >> >> Iain
>> >> >> >>
>> >> >> >>
>> >> >> >>
>> >> >> >> Send bugs reports to this list.
>> >> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> >> >> "unsubscribe
>> >> >> >> csound"
>> >> >> >>
>> >> >> >
>> >> >> >
>> >> >> > --
>> >> >> > Michael Gogins
>> >> >> > Irreducible Productions
>> >> >> > http://www.michael-gogins.com
>> >> >> > Michael dot Gogins at gmail dot com
>> >> >> >
>> >> >> >
>> >> >> > Send bugs reports to this list.
>> >> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> >> > "unsubscribe
>> >> >> > csound"
>> >> >> >
>> >> >>
>> >> >>
>> >> >> Send bugs reports to this list.
>> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> >> "unsubscribe
>> >> >> csound"
>> >> >
>> >> >
>> >> >
>> >> > Send bugs reports to this list.
>> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> > "unsubscribe
>> >> > csound"
>> >> >
>> >>
>> >>
>> >
>> >
>> >
>> > Send bugs reports to this list.
>> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
>> > csound"
>> >
>>
>>
>
>
>
> Send bugs reports to this list.
> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> csound"
>

On Wed, 2009-10-21 at 14:43 -0400, Michael Gogins wrote:
> The repoze manual that you cite as an example is organized in just the
> way I suggest. The top-level manual is the "User's Guide." This
> includes, as a section, the "API Reference" which, no surprise, is
> automatically generated by a tool from comments in source code (the
> tool, in this case, is called Sphinx (http://sphinx.pocoo.org/).

> 
> In short, it doesn't matter how the material "looks," what matters is
> how it "is." There is a manually written user's guide and an
> automatically generated generated reference manual here, just as there
> is in something like a majority of software documentation.

I'm not referring to the look either, I'm referring to the content,
writing, and organization. If I open the index file from the doxygen
generated docs from Csound5.11, I see one page of narrative docs and
then links to api docs for C and C++ only. If there is a User Manual, it
sure isn't obvious where to find it. Could you tell me where this is?

I'm not sure what you're saying, are you saying the Csound docs already
have a user manual comparable to repoze.bfg and I can't find it, or that
yes we do need one? If the latter, I would like to help out with
situation, though my time is limited. 

Iain

> 
> Regards,
> Mike
> 
> On 10/21/09, Iain Duncan  wrote:
> > On Wed, 2009-10-21 at 08:44 -0400, Michael Gogins wrote:
> >> Putting it online, i.e. at csounds.com, would solve that problem.
> >
> > Ok, I guess we are not understanding each other. What I am getting at is
> > that the API docs are not what I would call adequate documentation for a
> > project if the project is intending to garner adoption. Compared to
> > other open source frameworks I use for my python web dev business, it is
> > very sparse. It's good, sure, put it is only a C/C++ reference manual.
> > Correct me if I'm wrong, but I don't see any examples or class
> > documentation for the python, java, or ruby wrappers.
> >
> > Now, I understand very few people like writing docs. But seriously, if
> > the goal is to encourage people to use the CsoudAPI, the doc situation
> > and online resource situation needs improving far beyond just putting
> > the api referrence on line. If that is not the goal, than no problem.
> > Maybe that is not the goal. It seems too bad though because you and
> > others have clearly put a ton of work into making the csound API
> > awesome, and frankly, I think outside of academia there is very very
> > little awareness of it for how long it's been around and so usable.
> >
> > For examples of good documentation, I would say this is what I'm talking
> > about:
> >
> > http://docs.repoze.org/bfg/1.1/
> >
> > Note, narrative documentation, code examples, doctests, api docs,
> > tutorials, and examples, are all linked and part of the same web docs.
> > That's built with Sphinx by the way.
> >
> > Iain
> >
> >>
> >> Regards,
> >> Mike
> >>
> >> On 10/20/09, Iain Duncan  wrote:
> >> > On Tue, 2009-10-20 at 15:53 -0400, Michael Gogins wrote:
> >> >> The API documents are included in the Windows installers. They could
> >> >> easily be included in the Linux packages and put online.
> >> >>
> >> >
> >> > I'm not sure that would change adequately what happens, ( or rather
> >> > doesn't!) when one googles 'csound API', know what I mean? It's like a
> >> > hidden project. ;-)
> >> >
> >> > Iain
> >> >
> >> >
> >> >> Regards,
> >> >> Mike
> >> >>
> >> >> On 10/20/09, Iain Duncan  wrote:
> >> >> > On Tue, 2009-10-20 at 07:03 -0700, Jacob Joaquin wrote:
> >> >> >> These docs need to be online somewhere. People need to be able to
> >> >> >> find
> >> >> >> them either at sourceforge, csounds, or a search engine.  The API is
> >> >> >> becoming more and more import as time goes on, and not having
> >> >> >> documentation readily available is likely stopping a lot of people
> >> >> >> from even trying it out.
> >> >> >
> >> >> > I didn't want to complain too loudly given that I just reshowed my
> >> >> > face
> >> >> > here, but I second that. I googled for Csound API docs, and the most
> >> >> > recent things I found were papers from three years ago. It's
> >> >> > currently
> >> >> > *way* too hard to find api docs if the plan is to have the api
> >> >> > adopted
> >> >> > to any degree by third parties.
> >> >> >
> >> >> > Iain
> >> >> >
> >> >> >>
> >> >> >> Best,
> >> >> >> Jake
> >> >> >>
> >> >> >>
> >> >> >> On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
> >> >> >>  wrote:
> >> >> >> > If you build Csound yourself, just run doxygen in the root Csound
> >> >> >> > directory. Otherwise, it's in the Windows installers. Don't know
> >> >> >> > about
> >> >> >> > Unix/Linux.
> >> >> >> >
> >> >> >> > Regards,
> >> >> >> > Mike
> >> >> >> >
> >> >> >> > On 10/19/09, Iain Duncan  wrote:
> >> >> >> >> Hi folks, been a long time since I did any csounding, and I'm
> >> >> >> >> wondering
> >> >> >> >> where the current documentation for the csound api for python
> >> >> >> >> would
> >> >> >> >> be
> >> >> >> >> living.
> >> >> >> >>
> >> >> >> >> thanks!
> >> >> >> >> Iain
> >> >> >> >>
> >> >> >> >>
> >> >> >> >>
> >> >> >> >> Send bugs reports to this list.
> >> >> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >> >> >> >> "unsubscribe
> >> >> >> >> csound"
> >> >> >> >>
> >> >> >> >
> >> >> >> >
> >> >> >> > --
> >> >> >> > Michael Gogins
> >> >> >> > Irreducible Productions
> >> >> >> > http://www.michael-gogins.com
> >> >> >> > Michael dot Gogins at gmail dot com
> >> >> >> >
> >> >> >> >
> >> >> >> > Send bugs reports to this list.
> >> >> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >> >> >> > "unsubscribe
> >> >> >> > csound"
> >> >> >> >
> >> >> >>
> >> >> >>
> >> >> >> Send bugs reports to this list.
> >> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >> >> >> "unsubscribe
> >> >> >> csound"
> >> >> >
> >> >> >
> >> >> >
> >> >> > Send bugs reports to this list.
> >> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >> >> > "unsubscribe
> >> >> > csound"
> >> >> >
> >> >>
> >> >>
> >> >
> >> >
> >> >
> >> > Send bugs reports to this list.
> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> >> > csound"
> >> >
> >>
> >>
> >
> >
> >
> > Send bugs reports to this list.
> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> > csound"
> >
> 
> 



Send bugs reports to this list.
To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"

Can't you hear what I'm saying? Currently there is a reference manual
but not a user's guide. We need both. Perhaps you missed some of my
posts about this.

Regards,
Mike

On 10/21/09, Iain Duncan  wrote:
> On Wed, 2009-10-21 at 14:43 -0400, Michael Gogins wrote:
>> The repoze manual that you cite as an example is organized in just the
>> way I suggest. The top-level manual is the "User's Guide." This
>> includes, as a section, the "API Reference" which, no surprise, is
>> automatically generated by a tool from comments in source code (the
>> tool, in this case, is called Sphinx (http://sphinx.pocoo.org/).
>
>>
>> In short, it doesn't matter how the material "looks," what matters is
>> how it "is." There is a manually written user's guide and an
>> automatically generated generated reference manual here, just as there
>> is in something like a majority of software documentation.
>
> I'm not referring to the look either, I'm referring to the content,
> writing, and organization. If I open the index file from the doxygen
> generated docs from Csound5.11, I see one page of narrative docs and
> then links to api docs for C and C++ only. If there is a User Manual, it
> sure isn't obvious where to find it. Could you tell me where this is?
>
> I'm not sure what you're saying, are you saying the Csound docs already
> have a user manual comparable to repoze.bfg and I can't find it, or that
> yes we do need one? If the latter, I would like to help out with
> situation, though my time is limited.
>
> Iain
>
>>
>> Regards,
>> Mike
>>
>> On 10/21/09, Iain Duncan  wrote:
>> > On Wed, 2009-10-21 at 08:44 -0400, Michael Gogins wrote:
>> >> Putting it online, i.e. at csounds.com, would solve that problem.
>> >
>> > Ok, I guess we are not understanding each other. What I am getting at is
>> > that the API docs are not what I would call adequate documentation for a
>> > project if the project is intending to garner adoption. Compared to
>> > other open source frameworks I use for my python web dev business, it is
>> > very sparse. It's good, sure, put it is only a C/C++ reference manual.
>> > Correct me if I'm wrong, but I don't see any examples or class
>> > documentation for the python, java, or ruby wrappers.
>> >
>> > Now, I understand very few people like writing docs. But seriously, if
>> > the goal is to encourage people to use the CsoudAPI, the doc situation
>> > and online resource situation needs improving far beyond just putting
>> > the api referrence on line. If that is not the goal, than no problem.
>> > Maybe that is not the goal. It seems too bad though because you and
>> > others have clearly put a ton of work into making the csound API
>> > awesome, and frankly, I think outside of academia there is very very
>> > little awareness of it for how long it's been around and so usable.
>> >
>> > For examples of good documentation, I would say this is what I'm talking
>> > about:
>> >
>> > http://docs.repoze.org/bfg/1.1/
>> >
>> > Note, narrative documentation, code examples, doctests, api docs,
>> > tutorials, and examples, are all linked and part of the same web docs.
>> > That's built with Sphinx by the way.
>> >
>> > Iain
>> >
>> >>
>> >> Regards,
>> >> Mike
>> >>
>> >> On 10/20/09, Iain Duncan  wrote:
>> >> > On Tue, 2009-10-20 at 15:53 -0400, Michael Gogins wrote:
>> >> >> The API documents are included in the Windows installers. They could
>> >> >> easily be included in the Linux packages and put online.
>> >> >>
>> >> >
>> >> > I'm not sure that would change adequately what happens, ( or rather
>> >> > doesn't!) when one googles 'csound API', know what I mean? It's like
>> >> > a
>> >> > hidden project. ;-)
>> >> >
>> >> > Iain
>> >> >
>> >> >
>> >> >> Regards,
>> >> >> Mike
>> >> >>
>> >> >> On 10/20/09, Iain Duncan  wrote:
>> >> >> > On Tue, 2009-10-20 at 07:03 -0700, Jacob Joaquin wrote:
>> >> >> >> These docs need to be online somewhere. People need to be able to
>> >> >> >> find
>> >> >> >> them either at sourceforge, csounds, or a search engine.  The API
>> >> >> >> is
>> >> >> >> becoming more and more import as time goes on, and not having
>> >> >> >> documentation readily available is likely stopping a lot of
>> >> >> >> people
>> >> >> >> from even trying it out.
>> >> >> >
>> >> >> > I didn't want to complain too loudly given that I just reshowed my
>> >> >> > face
>> >> >> > here, but I second that. I googled for Csound API docs, and the
>> >> >> > most
>> >> >> > recent things I found were papers from three years ago. It's
>> >> >> > currently
>> >> >> > *way* too hard to find api docs if the plan is to have the api
>> >> >> > adopted
>> >> >> > to any degree by third parties.
>> >> >> >
>> >> >> > Iain
>> >> >> >
>> >> >> >>
>> >> >> >> Best,
>> >> >> >> Jake
>> >> >> >>
>> >> >> >>
>> >> >> >> On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
>> >> >> >>  wrote:
>> >> >> >> > If you build Csound yourself, just run doxygen in the root
>> >> >> >> > Csound
>> >> >> >> > directory. Otherwise, it's in the Windows installers. Don't
>> >> >> >> > know
>> >> >> >> > about
>> >> >> >> > Unix/Linux.
>> >> >> >> >
>> >> >> >> > Regards,
>> >> >> >> > Mike
>> >> >> >> >
>> >> >> >> > On 10/19/09, Iain Duncan  wrote:
>> >> >> >> >> Hi folks, been a long time since I did any csounding, and I'm
>> >> >> >> >> wondering
>> >> >> >> >> where the current documentation for the csound api for python
>> >> >> >> >> would
>> >> >> >> >> be
>> >> >> >> >> living.
>> >> >> >> >>
>> >> >> >> >> thanks!
>> >> >> >> >> Iain
>> >> >> >> >>
>> >> >> >> >>
>> >> >> >> >>
>> >> >> >> >> Send bugs reports to this list.
>> >> >> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> >> >> >> "unsubscribe
>> >> >> >> >> csound"
>> >> >> >> >>
>> >> >> >> >
>> >> >> >> >
>> >> >> >> > --
>> >> >> >> > Michael Gogins
>> >> >> >> > Irreducible Productions
>> >> >> >> > http://www.michael-gogins.com
>> >> >> >> > Michael dot Gogins at gmail dot com
>> >> >> >> >
>> >> >> >> >
>> >> >> >> > Send bugs reports to this list.
>> >> >> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> >> >> > "unsubscribe
>> >> >> >> > csound"
>> >> >> >> >
>> >> >> >>
>> >> >> >>
>> >> >> >> Send bugs reports to this list.
>> >> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> >> >> "unsubscribe
>> >> >> >> csound"
>> >> >> >
>> >> >> >
>> >> >> >
>> >> >> > Send bugs reports to this list.
>> >> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> >> > "unsubscribe
>> >> >> > csound"
>> >> >> >
>> >> >>
>> >> >>
>> >> >
>> >> >
>> >> >
>> >> > Send bugs reports to this list.
>> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> > "unsubscribe
>> >> > csound"
>> >> >
>> >>
>> >>
>> >
>> >
>> >
>> > Send bugs reports to this list.
>> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
>> > csound"
>> >
>>
>>
>
>
>
> Send bugs reports to this list.
> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> csound"
>

On Wed, 2009-10-21 at 14:59 -0400, Michael Gogins wrote:
> Can't you hear what I'm saying? Currently there is a reference manual
> but not a user's guide. We need both. Perhaps you missed some of my
> posts about this.

Ha ha, I think so, I kinda thought we had wires crossed. It was not
immediately clear to me whether you meant csound already has a users
manual or not. Also, you *did* say that you thought putting the
generated docs online would solve the problems I mentioned, when clearly
it will not if we don't have a users manual or basically any narrative
documentation, so I think the confusion on my part is quite
understandable. 

Does anyone have objections to a user manual being started in an svn
repository on a third party server? I have rented servers that I could
put a trac+subversion instanct up on to hold sphinx files plus examples.

Iain


> 
> Regards,
> Mike
> 
> On 10/21/09, Iain Duncan  wrote:
> > On Wed, 2009-10-21 at 14:43 -0400, Michael Gogins wrote:
> >> The repoze manual that you cite as an example is organized in just the
> >> way I suggest. The top-level manual is the "User's Guide." This
> >> includes, as a section, the "API Reference" which, no surprise, is
> >> automatically generated by a tool from comments in source code (the
> >> tool, in this case, is called Sphinx (http://sphinx.pocoo.org/).
> >
> >>
> >> In short, it doesn't matter how the material "looks," what matters is
> >> how it "is." There is a manually written user's guide and an
> >> automatically generated generated reference manual here, just as there
> >> is in something like a majority of software documentation.
> >
> > I'm not referring to the look either, I'm referring to the content,
> > writing, and organization. If I open the index file from the doxygen
> > generated docs from Csound5.11, I see one page of narrative docs and
> > then links to api docs for C and C++ only. If there is a User Manual, it
> > sure isn't obvious where to find it. Could you tell me where this is?
> >
> > I'm not sure what you're saying, are you saying the Csound docs already
> > have a user manual comparable to repoze.bfg and I can't find it, or that
> > yes we do need one? If the latter, I would like to help out with
> > situation, though my time is limited.
> >
> > Iain
> >
> >>
> >> Regards,
> >> Mike
> >>
> >> On 10/21/09, Iain Duncan  wrote:
> >> > On Wed, 2009-10-21 at 08:44 -0400, Michael Gogins wrote:
> >> >> Putting it online, i.e. at csounds.com, would solve that problem.
> >> >
> >> > Ok, I guess we are not understanding each other. What I am getting at is
> >> > that the API docs are not what I would call adequate documentation for a
> >> > project if the project is intending to garner adoption. Compared to
> >> > other open source frameworks I use for my python web dev business, it is
> >> > very sparse. It's good, sure, put it is only a C/C++ reference manual.
> >> > Correct me if I'm wrong, but I don't see any examples or class
> >> > documentation for the python, java, or ruby wrappers.
> >> >
> >> > Now, I understand very few people like writing docs. But seriously, if
> >> > the goal is to encourage people to use the CsoudAPI, the doc situation
> >> > and online resource situation needs improving far beyond just putting
> >> > the api referrence on line. If that is not the goal, than no problem.
> >> > Maybe that is not the goal. It seems too bad though because you and
> >> > others have clearly put a ton of work into making the csound API
> >> > awesome, and frankly, I think outside of academia there is very very
> >> > little awareness of it for how long it's been around and so usable.
> >> >
> >> > For examples of good documentation, I would say this is what I'm talking
> >> > about:
> >> >
> >> > http://docs.repoze.org/bfg/1.1/
> >> >
> >> > Note, narrative documentation, code examples, doctests, api docs,
> >> > tutorials, and examples, are all linked and part of the same web docs.
> >> > That's built with Sphinx by the way.
> >> >
> >> > Iain
> >> >
> >> >>
> >> >> Regards,
> >> >> Mike
> >> >>
> >> >> On 10/20/09, Iain Duncan  wrote:
> >> >> > On Tue, 2009-10-20 at 15:53 -0400, Michael Gogins wrote:
> >> >> >> The API documents are included in the Windows installers. They could
> >> >> >> easily be included in the Linux packages and put online.
> >> >> >>
> >> >> >
> >> >> > I'm not sure that would change adequately what happens, ( or rather
> >> >> > doesn't!) when one googles 'csound API', know what I mean? It's like
> >> >> > a
> >> >> > hidden project. ;-)
> >> >> >
> >> >> > Iain
> >> >> >
> >> >> >
> >> >> >> Regards,
> >> >> >> Mike
> >> >> >>
> >> >> >> On 10/20/09, Iain Duncan  wrote:
> >> >> >> > On Tue, 2009-10-20 at 07:03 -0700, Jacob Joaquin wrote:
> >> >> >> >> These docs need to be online somewhere. People need to be able to
> >> >> >> >> find
> >> >> >> >> them either at sourceforge, csounds, or a search engine.  The API
> >> >> >> >> is
> >> >> >> >> becoming more and more import as time goes on, and not having
> >> >> >> >> documentation readily available is likely stopping a lot of
> >> >> >> >> people
> >> >> >> >> from even trying it out.
> >> >> >> >
> >> >> >> > I didn't want to complain too loudly given that I just reshowed my
> >> >> >> > face
> >> >> >> > here, but I second that. I googled for Csound API docs, and the
> >> >> >> > most
> >> >> >> > recent things I found were papers from three years ago. It's
> >> >> >> > currently
> >> >> >> > *way* too hard to find api docs if the plan is to have the api
> >> >> >> > adopted
> >> >> >> > to any degree by third parties.
> >> >> >> >
> >> >> >> > Iain
> >> >> >> >
> >> >> >> >>
> >> >> >> >> Best,
> >> >> >> >> Jake
> >> >> >> >>
> >> >> >> >>
> >> >> >> >> On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
> >> >> >> >>  wrote:
> >> >> >> >> > If you build Csound yourself, just run doxygen in the root
> >> >> >> >> > Csound
> >> >> >> >> > directory. Otherwise, it's in the Windows installers. Don't
> >> >> >> >> > know
> >> >> >> >> > about
> >> >> >> >> > Unix/Linux.
> >> >> >> >> >
> >> >> >> >> > Regards,
> >> >> >> >> > Mike
> >> >> >> >> >
> >> >> >> >> > On 10/19/09, Iain Duncan  wrote:
> >> >> >> >> >> Hi folks, been a long time since I did any csounding, and I'm
> >> >> >> >> >> wondering
> >> >> >> >> >> where the current documentation for the csound api for python
> >> >> >> >> >> would
> >> >> >> >> >> be
> >> >> >> >> >> living.
> >> >> >> >> >>
> >> >> >> >> >> thanks!
> >> >> >> >> >> Iain
> >> >> >> >> >>
> >> >> >> >> >>
> >> >> >> >> >>
> >> >> >> >> >> Send bugs reports to this list.
> >> >> >> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >> >> >> >> >> "unsubscribe
> >> >> >> >> >> csound"
> >> >> >> >> >>
> >> >> >> >> >
> >> >> >> >> >
> >> >> >> >> > --
> >> >> >> >> > Michael Gogins
> >> >> >> >> > Irreducible Productions
> >> >> >> >> > http://www.michael-gogins.com
> >> >> >> >> > Michael dot Gogins at gmail dot com
> >> >> >> >> >
> >> >> >> >> >
> >> >> >> >> > Send bugs reports to this list.
> >> >> >> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >> >> >> >> > "unsubscribe
> >> >> >> >> > csound"
> >> >> >> >> >
> >> >> >> >>
> >> >> >> >>
> >> >> >> >> Send bugs reports to this list.
> >> >> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >> >> >> >> "unsubscribe
> >> >> >> >> csound"
> >> >> >> >
> >> >> >> >
> >> >> >> >
> >> >> >> > Send bugs reports to this list.
> >> >> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >> >> >> > "unsubscribe
> >> >> >> > csound"
> >> >> >> >
> >> >> >>
> >> >> >>
> >> >> >
> >> >> >
> >> >> >
> >> >> > Send bugs reports to this list.
> >> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >> >> > "unsubscribe
> >> >> > csound"
> >> >> >
> >> >>
> >> >>
> >> >
> >> >
> >> >
> >> > Send bugs reports to this list.
> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> >> > csound"
> >> >
> >>
> >>
> >
> >
> >
> > Send bugs reports to this list.
> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> > csound"
> >
> 
> 



Send bugs reports to this list.
To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"

Just an aside but the current doxygen html reference which I posted
today falls far behind what could be done. I'd be happy to start
editing csound.h to include code examples and better descriptions of
what the different functions do. It would also be relatively
straightforward to include the java and python equivalent function in
the comments so they appear also.

Rory.


2009/10/21 Iain Duncan :
> On Wed, 2009-10-21 at 14:59 -0400, Michael Gogins wrote:
>> Can't you hear what I'm saying? Currently there is a reference manual
>> but not a user's guide. We need both. Perhaps you missed some of my
>> posts about this.
>
> Ha ha, I think so, I kinda thought we had wires crossed. It was not
> immediately clear to me whether you meant csound already has a users
> manual or not. Also, you *did* say that you thought putting the
> generated docs online would solve the problems I mentioned, when clearly
> it will not if we don't have a users manual or basically any narrative
> documentation, so I think the confusion on my part is quite
> understandable.
>
> Does anyone have objections to a user manual being started in an svn
> repository on a third party server? I have rented servers that I could
> put a trac+subversion instanct up on to hold sphinx files plus examples.
>
> Iain
>
>
>>
>> Regards,
>> Mike
>>
>> On 10/21/09, Iain Duncan  wrote:
>> > On Wed, 2009-10-21 at 14:43 -0400, Michael Gogins wrote:
>> >> The repoze manual that you cite as an example is organized in just the
>> >> way I suggest. The top-level manual is the "User's Guide." This
>> >> includes, as a section, the "API Reference" which, no surprise, is
>> >> automatically generated by a tool from comments in source code (the
>> >> tool, in this case, is called Sphinx (http://sphinx.pocoo.org/).
>> >
>> >>
>> >> In short, it doesn't matter how the material "looks," what matters is
>> >> how it "is." There is a manually written user's guide and an
>> >> automatically generated generated reference manual here, just as there
>> >> is in something like a majority of software documentation.
>> >
>> > I'm not referring to the look either, I'm referring to the content,
>> > writing, and organization. If I open the index file from the doxygen
>> > generated docs from Csound5.11, I see one page of narrative docs and
>> > then links to api docs for C and C++ only. If there is a User Manual, it
>> > sure isn't obvious where to find it. Could you tell me where this is?
>> >
>> > I'm not sure what you're saying, are you saying the Csound docs already
>> > have a user manual comparable to repoze.bfg and I can't find it, or that
>> > yes we do need one? If the latter, I would like to help out with
>> > situation, though my time is limited.
>> >
>> > Iain
>> >
>> >>
>> >> Regards,
>> >> Mike
>> >>
>> >> On 10/21/09, Iain Duncan  wrote:
>> >> > On Wed, 2009-10-21 at 08:44 -0400, Michael Gogins wrote:
>> >> >> Putting it online, i.e. at csounds.com, would solve that problem.
>> >> >
>> >> > Ok, I guess we are not understanding each other. What I am getting at is
>> >> > that the API docs are not what I would call adequate documentation for a
>> >> > project if the project is intending to garner adoption. Compared to
>> >> > other open source frameworks I use for my python web dev business, it is
>> >> > very sparse. It's good, sure, put it is only a C/C++ reference manual.
>> >> > Correct me if I'm wrong, but I don't see any examples or class
>> >> > documentation for the python, java, or ruby wrappers.
>> >> >
>> >> > Now, I understand very few people like writing docs. But seriously, if
>> >> > the goal is to encourage people to use the CsoudAPI, the doc situation
>> >> > and online resource situation needs improving far beyond just putting
>> >> > the api referrence on line. If that is not the goal, than no problem.
>> >> > Maybe that is not the goal. It seems too bad though because you and
>> >> > others have clearly put a ton of work into making the csound API
>> >> > awesome, and frankly, I think outside of academia there is very very
>> >> > little awareness of it for how long it's been around and so usable.
>> >> >
>> >> > For examples of good documentation, I would say this is what I'm talking
>> >> > about:
>> >> >
>> >> > http://docs.repoze.org/bfg/1.1/
>> >> >
>> >> > Note, narrative documentation, code examples, doctests, api docs,
>> >> > tutorials, and examples, are all linked and part of the same web docs.
>> >> > That's built with Sphinx by the way.
>> >> >
>> >> > Iain
>> >> >
>> >> >>
>> >> >> Regards,
>> >> >> Mike
>> >> >>
>> >> >> On 10/20/09, Iain Duncan  wrote:
>> >> >> > On Tue, 2009-10-20 at 15:53 -0400, Michael Gogins wrote:
>> >> >> >> The API documents are included in the Windows installers. They could
>> >> >> >> easily be included in the Linux packages and put online.
>> >> >> >>
>> >> >> >
>> >> >> > I'm not sure that would change adequately what happens, ( or rather
>> >> >> > doesn't!) when one googles 'csound API', know what I mean? It's like
>> >> >> > a
>> >> >> > hidden project. ;-)
>> >> >> >
>> >> >> > Iain
>> >> >> >
>> >> >> >
>> >> >> >> Regards,
>> >> >> >> Mike
>> >> >> >>
>> >> >> >> On 10/20/09, Iain Duncan  wrote:
>> >> >> >> > On Tue, 2009-10-20 at 07:03 -0700, Jacob Joaquin wrote:
>> >> >> >> >> These docs need to be online somewhere. People need to be able to
>> >> >> >> >> find
>> >> >> >> >> them either at sourceforge, csounds, or a search engine.  The API
>> >> >> >> >> is
>> >> >> >> >> becoming more and more import as time goes on, and not having
>> >> >> >> >> documentation readily available is likely stopping a lot of
>> >> >> >> >> people
>> >> >> >> >> from even trying it out.
>> >> >> >> >
>> >> >> >> > I didn't want to complain too loudly given that I just reshowed my
>> >> >> >> > face
>> >> >> >> > here, but I second that. I googled for Csound API docs, and the
>> >> >> >> > most
>> >> >> >> > recent things I found were papers from three years ago. It's
>> >> >> >> > currently
>> >> >> >> > *way* too hard to find api docs if the plan is to have the api
>> >> >> >> > adopted
>> >> >> >> > to any degree by third parties.
>> >> >> >> >
>> >> >> >> > Iain
>> >> >> >> >
>> >> >> >> >>
>> >> >> >> >> Best,
>> >> >> >> >> Jake
>> >> >> >> >>
>> >> >> >> >>
>> >> >> >> >> On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
>> >> >> >> >>  wrote:
>> >> >> >> >> > If you build Csound yourself, just run doxygen in the root
>> >> >> >> >> > Csound
>> >> >> >> >> > directory. Otherwise, it's in the Windows installers. Don't
>> >> >> >> >> > know
>> >> >> >> >> > about
>> >> >> >> >> > Unix/Linux.
>> >> >> >> >> >
>> >> >> >> >> > Regards,
>> >> >> >> >> > Mike
>> >> >> >> >> >
>> >> >> >> >> > On 10/19/09, Iain Duncan  wrote:
>> >> >> >> >> >> Hi folks, been a long time since I did any csounding, and I'm
>> >> >> >> >> >> wondering
>> >> >> >> >> >> where the current documentation for the csound api for python
>> >> >> >> >> >> would
>> >> >> >> >> >> be
>> >> >> >> >> >> living.
>> >> >> >> >> >>
>> >> >> >> >> >> thanks!
>> >> >> >> >> >> Iain
>> >> >> >> >> >>
>> >> >> >> >> >>
>> >> >> >> >> >>
>> >> >> >> >> >> Send bugs reports to this list.
>> >> >> >> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> >> >> >> >> "unsubscribe
>> >> >> >> >> >> csound"
>> >> >> >> >> >>
>> >> >> >> >> >
>> >> >> >> >> >
>> >> >> >> >> > --
>> >> >> >> >> > Michael Gogins
>> >> >> >> >> > Irreducible Productions
>> >> >> >> >> > http://www.michael-gogins.com
>> >> >> >> >> > Michael dot Gogins at gmail dot com
>> >> >> >> >> >
>> >> >> >> >> >
>> >> >> >> >> > Send bugs reports to this list.
>> >> >> >> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> >> >> >> > "unsubscribe
>> >> >> >> >> > csound"
>> >> >> >> >> >
>> >> >> >> >>
>> >> >> >> >>
>> >> >> >> >> Send bugs reports to this list.
>> >> >> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> >> >> >> "unsubscribe
>> >> >> >> >> csound"
>> >> >> >> >
>> >> >> >> >
>> >> >> >> >
>> >> >> >> > Send bugs reports to this list.
>> >> >> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> >> >> > "unsubscribe
>> >> >> >> > csound"
>> >> >> >> >
>> >> >> >>
>> >> >> >>
>> >> >> >
>> >> >> >
>> >> >> >
>> >> >> > Send bugs reports to this list.
>> >> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
>> >> >> > "unsubscribe
>> >> >> > csound"
>> >> >> >
>> >> >>
>> >> >>
>> >> >
>> >> >
>> >> >
>> >> > Send bugs reports to this list.
>> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
>> >> > csound"
>> >> >
>> >>
>> >>
>> >
>> >
>> >
>> > Send bugs reports to this list.
>> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
>> > csound"
>> >
>>
>>
>
>
>
> Send bugs reports to this list.
> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"
>


Send bugs reports to this list.
To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"

I think adding examples and more documentation to csound.h is very
good. Also, don't forget:

-- csound.hpp
-- CppSound.hpp
-- CsoundFile.hpp

I don't think adding Python and Java equivalents is a good idea at
all, though! Horrors! One person will maintain the documentation, one
person will maintain the API, before you know it they will contradict
each other, and nobody will know about or do anything about it until
it has annoyed a number of users. And probably, based on my
experience, not even then.

This is the whole reason for using tools like Doxygen or Sphinx!

I think SWIG is working on ways to get Doxygen comments into the
appropriate format for the SWIG-generated wrapper functions in terms
appropriate for the wrapper language. When this is ready, we should
use it. Until then, I think we should stick with C/C++.

Regards,
Mike

On 10/21/09, Rory Walsh  wrote:
> Just an aside but the current doxygen html reference which I posted
> today falls far behind what could be done. I'd be happy to start
> editing csound.h to include code examples and better descriptions of
> what the different functions do. It would also be relatively
> straightforward to include the java and python equivalent function in
> the comments so they appear also.
>
> Rory.
>
>
> 2009/10/21 Iain Duncan :
>> On Wed, 2009-10-21 at 14:59 -0400, Michael Gogins wrote:
>>> Can't you hear what I'm saying? Currently there is a reference manual
>>> but not a user's guide. We need both. Perhaps you missed some of my
>>> posts about this.
>>
>> Ha ha, I think so, I kinda thought we had wires crossed. It was not
>> immediately clear to me whether you meant csound already has a users
>> manual or not. Also, you *did* say that you thought putting the
>> generated docs online would solve the problems I mentioned, when clearly
>> it will not if we don't have a users manual or basically any narrative
>> documentation, so I think the confusion on my part is quite
>> understandable.
>>
>> Does anyone have objections to a user manual being started in an svn
>> repository on a third party server? I have rented servers that I could
>> put a trac+subversion instanct up on to hold sphinx files plus examples.
>>
>> Iain
>>
>>
>>>
>>> Regards,
>>> Mike
>>>
>>> On 10/21/09, Iain Duncan  wrote:
>>> > On Wed, 2009-10-21 at 14:43 -0400, Michael Gogins wrote:
>>> >> The repoze manual that you cite as an example is organized in just the
>>> >> way I suggest. The top-level manual is the "User's Guide." This
>>> >> includes, as a section, the "API Reference" which, no surprise, is
>>> >> automatically generated by a tool from comments in source code (the
>>> >> tool, in this case, is called Sphinx (http://sphinx.pocoo.org/).
>>> >
>>> >>
>>> >> In short, it doesn't matter how the material "looks," what matters is
>>> >> how it "is." There is a manually written user's guide and an
>>> >> automatically generated generated reference manual here, just as there
>>> >> is in something like a majority of software documentation.
>>> >
>>> > I'm not referring to the look either, I'm referring to the content,
>>> > writing, and organization. If I open the index file from the doxygen
>>> > generated docs from Csound5.11, I see one page of narrative docs and
>>> > then links to api docs for C and C++ only. If there is a User Manual,
>>> > it
>>> > sure isn't obvious where to find it. Could you tell me where this is?
>>> >
>>> > I'm not sure what you're saying, are you saying the Csound docs already
>>> > have a user manual comparable to repoze.bfg and I can't find it, or
>>> > that
>>> > yes we do need one? If the latter, I would like to help out with
>>> > situation, though my time is limited.
>>> >
>>> > Iain
>>> >
>>> >>
>>> >> Regards,
>>> >> Mike
>>> >>
>>> >> On 10/21/09, Iain Duncan  wrote:
>>> >> > On Wed, 2009-10-21 at 08:44 -0400, Michael Gogins wrote:
>>> >> >> Putting it online, i.e. at csounds.com, would solve that problem.
>>> >> >
>>> >> > Ok, I guess we are not understanding each other. What I am getting
>>> >> > at is
>>> >> > that the API docs are not what I would call adequate documentation
>>> >> > for a
>>> >> > project if the project is intending to garner adoption. Compared to
>>> >> > other open source frameworks I use for my python web dev business,
>>> >> > it is
>>> >> > very sparse. It's good, sure, put it is only a C/C++ reference
>>> >> > manual.
>>> >> > Correct me if I'm wrong, but I don't see any examples or class
>>> >> > documentation for the python, java, or ruby wrappers.
>>> >> >
>>> >> > Now, I understand very few people like writing docs. But seriously,
>>> >> > if
>>> >> > the goal is to encourage people to use the CsoudAPI, the doc
>>> >> > situation
>>> >> > and online resource situation needs improving far beyond just
>>> >> > putting
>>> >> > the api referrence on line. If that is not the goal, than no
>>> >> > problem.
>>> >> > Maybe that is not the goal. It seems too bad though because you and
>>> >> > others have clearly put a ton of work into making the csound API
>>> >> > awesome, and frankly, I think outside of academia there is very very
>>> >> > little awareness of it for how long it's been around and so usable.
>>> >> >
>>> >> > For examples of good documentation, I would say this is what I'm
>>> >> > talking
>>> >> > about:
>>> >> >
>>> >> > http://docs.repoze.org/bfg/1.1/
>>> >> >
>>> >> > Note, narrative documentation, code examples, doctests, api docs,
>>> >> > tutorials, and examples, are all linked and part of the same web
>>> >> > docs.
>>> >> > That's built with Sphinx by the way.
>>> >> >
>>> >> > Iain
>>> >> >
>>> >> >>
>>> >> >> Regards,
>>> >> >> Mike
>>> >> >>
>>> >> >> On 10/20/09, Iain Duncan  wrote:
>>> >> >> > On Tue, 2009-10-20 at 15:53 -0400, Michael Gogins wrote:
>>> >> >> >> The API documents are included in the Windows installers. They
>>> >> >> >> could
>>> >> >> >> easily be included in the Linux packages and put online.
>>> >> >> >>
>>> >> >> >
>>> >> >> > I'm not sure that would change adequately what happens, ( or
>>> >> >> > rather
>>> >> >> > doesn't!) when one googles 'csound API', know what I mean? It's
>>> >> >> > like
>>> >> >> > a
>>> >> >> > hidden project. ;-)
>>> >> >> >
>>> >> >> > Iain
>>> >> >> >
>>> >> >> >
>>> >> >> >> Regards,
>>> >> >> >> Mike
>>> >> >> >>
>>> >> >> >> On 10/20/09, Iain Duncan  wrote:
>>> >> >> >> > On Tue, 2009-10-20 at 07:03 -0700, Jacob Joaquin wrote:
>>> >> >> >> >> These docs need to be online somewhere. People need to be
>>> >> >> >> >> able to
>>> >> >> >> >> find
>>> >> >> >> >> them either at sourceforge, csounds, or a search engine.  The
>>> >> >> >> >> API
>>> >> >> >> >> is
>>> >> >> >> >> becoming more and more import as time goes on, and not having
>>> >> >> >> >> documentation readily available is likely stopping a lot of
>>> >> >> >> >> people
>>> >> >> >> >> from even trying it out.
>>> >> >> >> >
>>> >> >> >> > I didn't want to complain too loudly given that I just
>>> >> >> >> > reshowed my
>>> >> >> >> > face
>>> >> >> >> > here, but I second that. I googled for Csound API docs, and
>>> >> >> >> > the
>>> >> >> >> > most
>>> >> >> >> > recent things I found were papers from three years ago. It's
>>> >> >> >> > currently
>>> >> >> >> > *way* too hard to find api docs if the plan is to have the api
>>> >> >> >> > adopted
>>> >> >> >> > to any degree by third parties.
>>> >> >> >> >
>>> >> >> >> > Iain
>>> >> >> >> >
>>> >> >> >> >>
>>> >> >> >> >> Best,
>>> >> >> >> >> Jake
>>> >> >> >> >>
>>> >> >> >> >>
>>> >> >> >> >> On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
>>> >> >> >> >>  wrote:
>>> >> >> >> >> > If you build Csound yourself, just run doxygen in the root
>>> >> >> >> >> > Csound
>>> >> >> >> >> > directory. Otherwise, it's in the Windows installers. Don't
>>> >> >> >> >> > know
>>> >> >> >> >> > about
>>> >> >> >> >> > Unix/Linux.
>>> >> >> >> >> >
>>> >> >> >> >> > Regards,
>>> >> >> >> >> > Mike
>>> >> >> >> >> >
>>> >> >> >> >> > On 10/19/09, Iain Duncan  wrote:
>>> >> >> >> >> >> Hi folks, been a long time since I did any csounding, and
>>> >> >> >> >> >> I'm
>>> >> >> >> >> >> wondering
>>> >> >> >> >> >> where the current documentation for the csound api for
>>> >> >> >> >> >> python
>>> >> >> >> >> >> would
>>> >> >> >> >> >> be
>>> >> >> >> >> >> living.
>>> >> >> >> >> >>
>>> >> >> >> >> >> thanks!
>>> >> >> >> >> >> Iain
>>> >> >> >> >> >>
>>> >> >> >> >> >>
>>> >> >> >> >> >>
>>> >> >> >> >> >> Send bugs reports to this list.
>>> >> >> >> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with
>>> >> >> >> >> >> body
>>> >> >> >> >> >> "unsubscribe
>>> >> >> >> >> >> csound"
>>> >> >> >> >> >>
>>> >> >> >> >> >
>>> >> >> >> >> >
>>> >> >> >> >> > --
>>> >> >> >> >> > Michael Gogins
>>> >> >> >> >> > Irreducible Productions
>>> >> >> >> >> > http://www.michael-gogins.com
>>> >> >> >> >> > Michael dot Gogins at gmail dot com
>>> >> >> >> >> >
>>> >> >> >> >> >
>>> >> >> >> >> > Send bugs reports to this list.
>>> >> >> >> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
>>> >> >> >> >> > "unsubscribe
>>> >> >> >> >> > csound"
>>> >> >> >> >> >
>>> >> >> >> >>
>>> >> >> >> >>
>>> >> >> >> >> Send bugs reports to this list.
>>> >> >> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
>>> >> >> >> >> "unsubscribe
>>> >> >> >> >> csound"
>>> >> >> >> >
>>> >> >> >> >
>>> >> >> >> >
>>> >> >> >> > Send bugs reports to this list.
>>> >> >> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
>>> >> >> >> > "unsubscribe
>>> >> >> >> > csound"
>>> >> >> >> >
>>> >> >> >>
>>> >> >> >>
>>> >> >> >
>>> >> >> >
>>> >> >> >
>>> >> >> > Send bugs reports to this list.
>>> >> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
>>> >> >> > "unsubscribe
>>> >> >> > csound"
>>> >> >> >
>>> >> >>
>>> >> >>
>>> >> >
>>> >> >
>>> >> >
>>> >> > Send bugs reports to this list.
>>> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
>>> >> > "unsubscribe
>>> >> > csound"
>>> >> >
>>> >>
>>> >>
>>> >
>>> >
>>> >
>>> > Send bugs reports to this list.
>>> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
>>> > "unsubscribe
>>> > csound"
>>> >
>>>
>>>
>>
>>
>>
>> Send bugs reports to this list.
>> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
>> csound"
>>
>
>
> Send bugs reports to this list.
> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> csound"


-- 
Michael Gogins
Irreducible Productions
http://www.michael-gogins.com
Michael dot Gogins at gmail dot com


Send bugs reports to this list.
To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"

On Wed, 2009-10-21 at 15:34 -0400, Michael Gogins wrote:
> I think adding examples and more documentation to csound.h is very
> good. Also, don't forget:
> 
> -- csound.hpp
> -- CppSound.hpp
> -- CsoundFile.hpp
> 
> I don't think adding Python and Java equivalents is a good idea at
> all, though! Horrors! One person will maintain the documentation, one
> person will maintain the API, before you know it they will contradict
> each other, and nobody will know about or do anything about it until
> it has annoyed a number of users. And probably, based on my
> experience, not even then.
> 
> This is the whole reason for using tools like Doxygen or Sphinx!
> 
> I think SWIG is working on ways to get Doxygen comments into the
> appropriate format for the SWIG-generated wrapper functions in terms
> appropriate for the wrapper language. When this is ready, we should
> use it. Until then, I think we should stick with C/C++.

I agree with Michael on this, I think there is a need for a separate
Python and C/C++ manual. I'm principally interested in the python side
myself. Apologies that I didn't see the massive thread on the dev list,
hence my confusion.

Iain

> 
> Regards,
> Mike
> 
> On 10/21/09, Rory Walsh  wrote:
> > Just an aside but the current doxygen html reference which I posted
> > today falls far behind what could be done. I'd be happy to start
> > editing csound.h to include code examples and better descriptions of
> > what the different functions do. It would also be relatively
> > straightforward to include the java and python equivalent function in
> > the comments so they appear also.
> >
> > Rory.
> >
> >
> > 2009/10/21 Iain Duncan :
> >> On Wed, 2009-10-21 at 14:59 -0400, Michael Gogins wrote:
> >>> Can't you hear what I'm saying? Currently there is a reference manual
> >>> but not a user's guide. We need both. Perhaps you missed some of my
> >>> posts about this.
> >>
> >> Ha ha, I think so, I kinda thought we had wires crossed. It was not
> >> immediately clear to me whether you meant csound already has a users
> >> manual or not. Also, you *did* say that you thought putting the
> >> generated docs online would solve the problems I mentioned, when clearly
> >> it will not if we don't have a users manual or basically any narrative
> >> documentation, so I think the confusion on my part is quite
> >> understandable.
> >>
> >> Does anyone have objections to a user manual being started in an svn
> >> repository on a third party server? I have rented servers that I could
> >> put a trac+subversion instanct up on to hold sphinx files plus examples.
> >>
> >> Iain
> >>
> >>
> >>>
> >>> Regards,
> >>> Mike
> >>>
> >>> On 10/21/09, Iain Duncan  wrote:
> >>> > On Wed, 2009-10-21 at 14:43 -0400, Michael Gogins wrote:
> >>> >> The repoze manual that you cite as an example is organized in just the
> >>> >> way I suggest. The top-level manual is the "User's Guide." This
> >>> >> includes, as a section, the "API Reference" which, no surprise, is
> >>> >> automatically generated by a tool from comments in source code (the
> >>> >> tool, in this case, is called Sphinx (http://sphinx.pocoo.org/).
> >>> >
> >>> >>
> >>> >> In short, it doesn't matter how the material "looks," what matters is
> >>> >> how it "is." There is a manually written user's guide and an
> >>> >> automatically generated generated reference manual here, just as there
> >>> >> is in something like a majority of software documentation.
> >>> >
> >>> > I'm not referring to the look either, I'm referring to the content,
> >>> > writing, and organization. If I open the index file from the doxygen
> >>> > generated docs from Csound5.11, I see one page of narrative docs and
> >>> > then links to api docs for C and C++ only. If there is a User Manual,
> >>> > it
> >>> > sure isn't obvious where to find it. Could you tell me where this is?
> >>> >
> >>> > I'm not sure what you're saying, are you saying the Csound docs already
> >>> > have a user manual comparable to repoze.bfg and I can't find it, or
> >>> > that
> >>> > yes we do need one? If the latter, I would like to help out with
> >>> > situation, though my time is limited.
> >>> >
> >>> > Iain
> >>> >
> >>> >>
> >>> >> Regards,
> >>> >> Mike
> >>> >>
> >>> >> On 10/21/09, Iain Duncan  wrote:
> >>> >> > On Wed, 2009-10-21 at 08:44 -0400, Michael Gogins wrote:
> >>> >> >> Putting it online, i.e. at csounds.com, would solve that problem.
> >>> >> >
> >>> >> > Ok, I guess we are not understanding each other. What I am getting
> >>> >> > at is
> >>> >> > that the API docs are not what I would call adequate documentation
> >>> >> > for a
> >>> >> > project if the project is intending to garner adoption. Compared to
> >>> >> > other open source frameworks I use for my python web dev business,
> >>> >> > it is
> >>> >> > very sparse. It's good, sure, put it is only a C/C++ reference
> >>> >> > manual.
> >>> >> > Correct me if I'm wrong, but I don't see any examples or class
> >>> >> > documentation for the python, java, or ruby wrappers.
> >>> >> >
> >>> >> > Now, I understand very few people like writing docs. But seriously,
> >>> >> > if
> >>> >> > the goal is to encourage people to use the CsoudAPI, the doc
> >>> >> > situation
> >>> >> > and online resource situation needs improving far beyond just
> >>> >> > putting
> >>> >> > the api referrence on line. If that is not the goal, than no
> >>> >> > problem.
> >>> >> > Maybe that is not the goal. It seems too bad though because you and
> >>> >> > others have clearly put a ton of work into making the csound API
> >>> >> > awesome, and frankly, I think outside of academia there is very very
> >>> >> > little awareness of it for how long it's been around and so usable.
> >>> >> >
> >>> >> > For examples of good documentation, I would say this is what I'm
> >>> >> > talking
> >>> >> > about:
> >>> >> >
> >>> >> > http://docs.repoze.org/bfg/1.1/
> >>> >> >
> >>> >> > Note, narrative documentation, code examples, doctests, api docs,
> >>> >> > tutorials, and examples, are all linked and part of the same web
> >>> >> > docs.
> >>> >> > That's built with Sphinx by the way.
> >>> >> >
> >>> >> > Iain
> >>> >> >
> >>> >> >>
> >>> >> >> Regards,
> >>> >> >> Mike
> >>> >> >>
> >>> >> >> On 10/20/09, Iain Duncan  wrote:
> >>> >> >> > On Tue, 2009-10-20 at 15:53 -0400, Michael Gogins wrote:
> >>> >> >> >> The API documents are included in the Windows installers. They
> >>> >> >> >> could
> >>> >> >> >> easily be included in the Linux packages and put online.
> >>> >> >> >>
> >>> >> >> >
> >>> >> >> > I'm not sure that would change adequately what happens, ( or
> >>> >> >> > rather
> >>> >> >> > doesn't!) when one googles 'csound API', know what I mean? It's
> >>> >> >> > like
> >>> >> >> > a
> >>> >> >> > hidden project. ;-)
> >>> >> >> >
> >>> >> >> > Iain
> >>> >> >> >
> >>> >> >> >
> >>> >> >> >> Regards,
> >>> >> >> >> Mike
> >>> >> >> >>
> >>> >> >> >> On 10/20/09, Iain Duncan  wrote:
> >>> >> >> >> > On Tue, 2009-10-20 at 07:03 -0700, Jacob Joaquin wrote:
> >>> >> >> >> >> These docs need to be online somewhere. People need to be
> >>> >> >> >> >> able to
> >>> >> >> >> >> find
> >>> >> >> >> >> them either at sourceforge, csounds, or a search engine.  The
> >>> >> >> >> >> API
> >>> >> >> >> >> is
> >>> >> >> >> >> becoming more and more import as time goes on, and not having
> >>> >> >> >> >> documentation readily available is likely stopping a lot of
> >>> >> >> >> >> people
> >>> >> >> >> >> from even trying it out.
> >>> >> >> >> >
> >>> >> >> >> > I didn't want to complain too loudly given that I just
> >>> >> >> >> > reshowed my
> >>> >> >> >> > face
> >>> >> >> >> > here, but I second that. I googled for Csound API docs, and
> >>> >> >> >> > the
> >>> >> >> >> > most
> >>> >> >> >> > recent things I found were papers from three years ago. It's
> >>> >> >> >> > currently
> >>> >> >> >> > *way* too hard to find api docs if the plan is to have the api
> >>> >> >> >> > adopted
> >>> >> >> >> > to any degree by third parties.
> >>> >> >> >> >
> >>> >> >> >> > Iain
> >>> >> >> >> >
> >>> >> >> >> >>
> >>> >> >> >> >> Best,
> >>> >> >> >> >> Jake
> >>> >> >> >> >>
> >>> >> >> >> >>
> >>> >> >> >> >> On Sun, Oct 18, 2009 at 9:55 PM, Michael Gogins
> >>> >> >> >> >>  wrote:
> >>> >> >> >> >> > If you build Csound yourself, just run doxygen in the root
> >>> >> >> >> >> > Csound
> >>> >> >> >> >> > directory. Otherwise, it's in the Windows installers. Don't
> >>> >> >> >> >> > know
> >>> >> >> >> >> > about
> >>> >> >> >> >> > Unix/Linux.
> >>> >> >> >> >> >
> >>> >> >> >> >> > Regards,
> >>> >> >> >> >> > Mike
> >>> >> >> >> >> >
> >>> >> >> >> >> > On 10/19/09, Iain Duncan  wrote:
> >>> >> >> >> >> >> Hi folks, been a long time since I did any csounding, and
> >>> >> >> >> >> >> I'm
> >>> >> >> >> >> >> wondering
> >>> >> >> >> >> >> where the current documentation for the csound api for
> >>> >> >> >> >> >> python
> >>> >> >> >> >> >> would
> >>> >> >> >> >> >> be
> >>> >> >> >> >> >> living.
> >>> >> >> >> >> >>
> >>> >> >> >> >> >> thanks!
> >>> >> >> >> >> >> Iain
> >>> >> >> >> >> >>
> >>> >> >> >> >> >>
> >>> >> >> >> >> >>
> >>> >> >> >> >> >> Send bugs reports to this list.
> >>> >> >> >> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with
> >>> >> >> >> >> >> body
> >>> >> >> >> >> >> "unsubscribe
> >>> >> >> >> >> >> csound"
> >>> >> >> >> >> >>
> >>> >> >> >> >> >
> >>> >> >> >> >> >
> >>> >> >> >> >> > --
> >>> >> >> >> >> > Michael Gogins
> >>> >> >> >> >> > Irreducible Productions
> >>> >> >> >> >> > http://www.michael-gogins.com
> >>> >> >> >> >> > Michael dot Gogins at gmail dot com
> >>> >> >> >> >> >
> >>> >> >> >> >> >
> >>> >> >> >> >> > Send bugs reports to this list.
> >>> >> >> >> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >>> >> >> >> >> > "unsubscribe
> >>> >> >> >> >> > csound"
> >>> >> >> >> >> >
> >>> >> >> >> >>
> >>> >> >> >> >>
> >>> >> >> >> >> Send bugs reports to this list.
> >>> >> >> >> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >>> >> >> >> >> "unsubscribe
> >>> >> >> >> >> csound"
> >>> >> >> >> >
> >>> >> >> >> >
> >>> >> >> >> >
> >>> >> >> >> > Send bugs reports to this list.
> >>> >> >> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >>> >> >> >> > "unsubscribe
> >>> >> >> >> > csound"
> >>> >> >> >> >
> >>> >> >> >>
> >>> >> >> >>
> >>> >> >> >
> >>> >> >> >
> >>> >> >> >
> >>> >> >> > Send bugs reports to this list.
> >>> >> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >>> >> >> > "unsubscribe
> >>> >> >> > csound"
> >>> >> >> >
> >>> >> >>
> >>> >> >>
> >>> >> >
> >>> >> >
> >>> >> >
> >>> >> > Send bugs reports to this list.
> >>> >> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >>> >> > "unsubscribe
> >>> >> > csound"
> >>> >> >
> >>> >>
> >>> >>
> >>> >
> >>> >
> >>> >
> >>> > Send bugs reports to this list.
> >>> > To unsubscribe, send email sympa@lists.bath.ac.uk with body
> >>> > "unsubscribe
> >>> > csound"
> >>> >
> >>>
> >>>
> >>
> >>
> >>
> >> Send bugs reports to this list.
> >> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> >> csound"
> >>
> >
> >
> > Send bugs reports to this list.
> > To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe
> > csound"
> 
> 
> -- 
> Michael Gogins
> Irreducible Productions
> http://www.michael-gogins.com
> Michael dot Gogins at gmail dot com
> 
> 
> Send bugs reports to this list.
> To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"



Send bugs reports to this list.
To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"

On Wed, 2009-10-21 at 12:51 -0700, Iain Duncan wrote:
> On Wed, 2009-10-21 at 15:34 -0400, Michael Gogins wrote:
> > I think adding examples and more documentation to csound.h is very
> > good. Also, don't forget:
> > 
> > -- csound.hpp
> > -- CppSound.hpp
> > -- CsoundFile.hpp
> > 
> > I don't think adding Python and Java equivalents is a good idea at
> > all, though! Horrors! One person will maintain the documentation, one
> > person will maintain the API, before you know it they will contradict
> > each other, and nobody will know about or do anything about it until
> > it has annoyed a number of users. And probably, based on my
> > experience, not even then.
> > 
> > This is the whole reason for using tools like Doxygen or Sphinx!
> > 
> > I think SWIG is working on ways to get Doxygen comments into the
> > appropriate format for the SWIG-generated wrapper functions in terms
> > appropriate for the wrapper language. When this is ready, we should
> > use it. Until then, I think we should stick with C/C++.
> 
> I agree with Michael on this, I think there is a need for a separate
> Python and C/C++ manual. I'm principally interested in the python side
> myself. Apologies that I didn't see the massive thread on the dev list,
> hence my confusion.

Ehm, Mike was saying that he thinks there should be _no_
language-specific information. Given that the language bindings are
automatically generated, maintaining separate docs would lead to
inconsistencies.
Although given that the C and C++ languages use manual memory management
(and have other differences wrt to python and Java), I think notes
describing the differences would be needed. Nothing more, since they are
essentially the same.


-- 
Saludos,
Felipe Sateler

Iain: Felipe is indeed saying what I was saying -- with respect to API
reference documentation and comments in source code.

Felipe: With respect to handwritten user guide documentation, Iain is
correct, there should be at least a certain amount of
language-specific documentation. It just should not get get into
sources, you are correct it would quickly become inconsistent.

Regards,
Mike

On 10/21/09, Felipe Sateler  wrote:
> On Wed, 2009-10-21 at 12:51 -0700, Iain Duncan wrote:
>> On Wed, 2009-10-21 at 15:34 -0400, Michael Gogins wrote:
>> > I think adding examples and more documentation to csound.h is very
>> > good. Also, don't forget:
>> >
>> > -- csound.hpp
>> > -- CppSound.hpp
>> > -- CsoundFile.hpp
>> >
>> > I don't think adding Python and Java equivalents is a good idea at
>> > all, though! Horrors! One person will maintain the documentation, one
>> > person will maintain the API, before you know it they will contradict
>> > each other, and nobody will know about or do anything about it until
>> > it has annoyed a number of users. And probably, based on my
>> > experience, not even then.
>> >
>> > This is the whole reason for using tools like Doxygen or Sphinx!
>> >
>> > I think SWIG is working on ways to get Doxygen comments into the
>> > appropriate format for the SWIG-generated wrapper functions in terms
>> > appropriate for the wrapper language. When this is ready, we should
>> > use it. Until then, I think we should stick with C/C++.
>>
>> I agree with Michael on this, I think there is a need for a separate
>> Python and C/C++ manual. I'm principally interested in the python side
>> myself. Apologies that I didn't see the massive thread on the dev list,
>> hence my confusion.
>
> Ehm, Mike was saying that he thinks there should be _no_
> language-specific information. Given that the language bindings are
> automatically generated, maintaining separate docs would lead to
> inconsistencies.
> Although given that the C and C++ languages use manual memory management
> (and have other differences wrt to python and Java), I think notes
> describing the differences would be needed. Nothing more, since they are
> essentially the same.
>
>
> --
> Saludos,
> Felipe Sateler
>

On Wed, 2009-10-21 at 16:26 -0400, Michael Gogins wrote:
> Iain: Felipe is indeed saying what I was saying -- with respect to API
> reference documentation and comments in source code.
> 
> Felipe: With respect to handwritten user guide documentation, Iain is
> correct, there should be at least a certain amount of
> language-specific documentation. It just should not get get into
> sources, you are correct it would quickly become inconsistent.

right, this is where I think sphinx doctest builds would be useful.
Though I'm not sure how I'm going to do that, I guess just assert that
nothing raised exceptions.

Iain

> 
> Regards,
> Mike
> 
> On 10/21/09, Felipe Sateler  wrote:
> > On Wed, 2009-10-21 at 12:51 -0700, Iain Duncan wrote:
> >> On Wed, 2009-10-21 at 15:34 -0400, Michael Gogins wrote:
> >> > I think adding examples and more documentation to csound.h is very
> >> > good. Also, don't forget:
> >> >
> >> > -- csound.hpp
> >> > -- CppSound.hpp
> >> > -- CsoundFile.hpp
> >> >
> >> > I don't think adding Python and Java equivalents is a good idea at
> >> > all, though! Horrors! One person will maintain the documentation, one
> >> > person will maintain the API, before you know it they will contradict
> >> > each other, and nobody will know about or do anything about it until
> >> > it has annoyed a number of users. And probably, based on my
> >> > experience, not even then.
> >> >
> >> > This is the whole reason for using tools like Doxygen or Sphinx!
> >> >
> >> > I think SWIG is working on ways to get Doxygen comments into the
> >> > appropriate format for the SWIG-generated wrapper functions in terms
> >> > appropriate for the wrapper language. When this is ready, we should
> >> > use it. Until then, I think we should stick with C/C++.
> >>
> >> I agree with Michael on this, I think there is a need for a separate
> >> Python and C/C++ manual. I'm principally interested in the python side
> >> myself. Apologies that I didn't see the massive thread on the dev list,
> >> hence my confusion.
> >
> > Ehm, Mike was saying that he thinks there should be _no_
> > language-specific information. Given that the language bindings are
> > automatically generated, maintaining separate docs would lead to
> > inconsistencies.
> > Although given that the C and C++ languages use manual memory management
> > (and have other differences wrt to python and Java), I think notes
> > describing the differences would be needed. Nothing more, since they are
> > essentially the same.
> >
> >
> > --
> > Saludos,
> > Felipe Sateler
> >
> 
> 



Send bugs reports to this list.
To unsubscribe, send email sympa@lists.bath.ac.uk with body "unsubscribe csound"

On Wed, Oct 21, 2009 at 9:29 PM, Iain Duncan  wrote:

> Correct me if I'm wrong, but I don't see any examples or class
> documentation for the python, java, or ruby wrappers.

I haven't been following all of this, but there are a bunch of Python
examples included with the source, in the examples/ directory. Looks
like some others too. Not all the examples work the same way, and they
didn't make everything completely clear for me, but it would be good
to keep them in some form.

-Chuckk