I created a html version of csound.h using doxygen which formatted
things quite well and looks pretty good. Should we then simply start
editing csound.h rather than starting with a whole new format such as
is in the reference manual, just a thought. Either way I'd be happy to
contribute examples and such.

Rory.


2009/10/21 victor :
> I propose we have a good C API reference for the next release. I can
> initiate it,
> but I hope we can collaborate on this.
>
> We could use the same format that has been used for the manual. So if Andres
> could put a section in it called API reference and a template XML file, then
> we can
> proceed from the top of csound.h down.
>
> Victor
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel
>
>

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

No. I think we need to do a proper reference manual. Doxygen is only good
as a stop-gap measure.

Victor
----- Original Message ----- 
From: "Rory Walsh" 
To: "Developer discussions" 
Sent: Wednesday, October 21, 2009 9:29 AM
Subject: Re: [Cs-dev] API documentation


I created a html version of csound.h using doxygen which formatted
things quite well and looks pretty good. Should we then simply start
editing csound.h rather than starting with a whole new format such as
is in the reference manual, just a thought. Either way I'd be happy to
contribute examples and such.

Rory.


2009/10/21 victor :
> I propose we have a good C API reference for the next release. I can
> initiate it,
> but I hope we can collaborate on this.
>
> We could use the same format that has been used for the manual. So if 
> Andres
> could put a section in it called API reference and a template XML file, 
> then
> we can
> proceed from the top of csound.h down.
>
> Victor
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel
>
>

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/csound-devel 


------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

Doxygen is the best way to do a reference manual. I used to work as a technical writer before I started working as a programmer. The manuals that I and my colleagues made with doxygen and similar tools were both more complete and more useful than the ones we did by hand. Doxygen also has the advantage of being a drop dead simple toolchain. Please expand on the existing manual and do not reinvent wheels.

Mkg

On Oct 21, 2009 4:33 AM, "victor" <Victor.Lazzarini@nuim.ie> wrote:

No. I think we need to do a proper reference manual. Doxygen is only good
as a stop-gap measure.

Victor

----- Original Message ----- From: "Rory Walsh" <rorywalsh@ear.ie> To: "Developer discussions" <cso...

> I propose we have a good C API reference for the next release. 
...
> We could use the same format that has been used for the manual. 

+1

Stef



------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

Like Victor I am suspicious of doxygen "manuals".  I have not seen one
yet that told be anything useful.
==John ffitch

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

I'm also of the mind that doxygen is most likely not a sufficient
solution. We need a manual that caters to composers, not technical
C/C++ gurus.

I'm spreading myself thin these days, but I'll be happy to help out in
any way I can. This API manual is too important to not do it right.

Best,
Jake


On Wed, Oct 21, 2009 at 5:57 AM, jpff  wrote:
> Like Victor I am suspicious of doxygen "manuals".  I have not seen one
> yet that told be anything useful.
> ==John ffitch
>
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel
>

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net
http

I have verified that the following projects use Doxygen or similar
tools that transform comments in source code to generate reference
manuals. These include some of the important tools and third party
packages used by Csound.

Java API reference
FLTK class reference
wxWidgets class reference
PortAudio reference
PortMidi reference
The GNU libstd++ reference (i.e. the Standard C++ Library that we use
to build the C++ parts of Csound)

I submit that most Csound developers would have learned something
useful from the above sources. Unless you guys know all this stuff by
heart.

Regards,
Mike








On 10/21/09, jpff  wrote:
> Like Victor I am suspicious of doxygen "manuals".  I have not seen one
> yet that told be anything useful.
> ==John ffitch
>
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel
>


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

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

> We need a manual that caters to composers, not technical
> C/C++ gurus.

To be clear, the manual should also be a good tech manual, in addition
to catering to composers.

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

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

I've uploaded the simple examples I created from the csound api using
doxygen, I think they look good and with a few more comments could be
very good. Granted it's far from perfect but keeping all the
comments/examples and what not in the source seems like a good idea to
me. You can check them out here:
http://rorywalsh.ear.ie/csoundDoxy/html/index.html
As csound.h is currently the only file comments you will need to hit
the Files tab and click on csound.h, half way down the page there is a
list of the different functions. These could easily be altered to
include sample code.

Rory.


2009/10/21 Michael Gogins :
> I have verified that the following projects use Doxygen or similar
> tools that transform comments in source code to generate reference
> manuals. These include some of the important tools and third party
> packages used by Csound.
>
> Java API reference
> FLTK class reference
> wxWidgets class reference
> PortAudio reference
> PortMidi reference
> The GNU libstd++ reference (i.e. the Standard C++ Library that we use
> to build the C++ parts of Csound)
>
> I submit that most Csound developers would have learned something
> useful from the above sources. Unless you guys know all this stuff by
> heart.
>
> Regards,
> Mike
>
>
>
>
>
>
>
>
> On 10/21/09, jpff  wrote:
>> Like Victor I am suspicious of doxygen "manuals".  I have not seen one
>> yet that told be anything useful.
>> ==John ffitch
>>
>> ------------------------------------------------------------------------------
>> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
>> is the only developer event you need to attend this year. Jumpstart your
>> developing skills, take BlackBerry mobile applications to market and stay
>> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
>> http://p.sf.net/sfu/devconference
>> _______________________________________________
>> Csound-devel mailing list
>> Csound-devel@lists.sourceforge.net
>> https://lists.sourceforge.net/lists/listinfo/csound-devel
>>
>
>
> --
> Michael Gogins
> Irreducible Productions
> http://www.michael-gogins.com
> Michael dot Gogins at gmail dot com
>
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel
>

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

yes, doxygen stuff does not explain how to use the API. while it is very 
much worthwhile, IMO it is definitely in need of some human-written 
documentation giving an overall picture of the whole API structure and 
usage.

Stef



------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

Yes I agree but doxygen manuals can include all this info. Check out
the manuals for the projects Michael listed above, especially the
wxWidgets which I use extensively.
http://docs.wxwidgets.org/2.6/wx_classref.html Each of the class refs
include examples where needed. There is also an overview page too, all
this can be done with doxygen. I've played around with the current
reference manual and it's a nightmare to edit.

Rory.


2009/10/21 Stéphane Rollandin :
> yes, doxygen stuff does not explain how to use the API. while it is very
> much worthwhile, IMO it is definitely in need of some human-written
> documentation giving an overall picture of the whole API structure and
> usage.
>
> Stef
>
>
>
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel
>

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

Agreed.  It's the same issue with Javadocs.  One thing I liked about
Rory's example he just posted is the main page has quite a bit of
info.  I don't see it as either-or but really we need both,
documentation on the level of API library as well as higher-level
integration documentation to explain how to use the pieces together.
Whether we create a Doxygen doc and separate doc for big-picture or
try to do as Rory shows by integrating the big-picture doc isn't a big
issue for me as long as both are represented.

As for designing the API docs for composers, I don't know what that
means really. When I'm composing I don't want to think about API's. :P
 If it means making the API easy to use and well documented, then I'm
all for it.

steven

2009/10/21 Stéphane Rollandin :
> yes, doxygen stuff does not explain how to use the API. while it is very
> much worthwhile, IMO it is definitely in need of some human-written
> documentation giving an overall picture of the whole API structure and
> usage.
>
> Stef
>
>
>
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel
>

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

I believe that an accurate reference manual is a prerequisite for any
other sort of documentation on the API. And doxygen is just the right
tool for creating reference manuals.
A separate manual can be in the form of a how-to, tutorial or getting
started guide.

The doxygen information is good. However, it is hard to find what is
useful and what is not. Lots of undocumented structures, #defines and
other stuff. Most of them because (AFAIK) they don't need to be used by
an API user. In that case, they should be hidden from the documentation.
I'm not quite sure how to do this. It is really ironic that a package
designed to create documentation has it in a very difficult to
search/browse form.

On Wed, 2009-10-21 at 06:29 -0700, Jacob Joaquin wrote:
> I'm also of the mind that doxygen is most likely not a sufficient
> solution. We need a manual that caters to composers, not technical
> C/C++ gurus.
> 
> I'm spreading myself thin these days, but I'll be happy to help out in
> any way I can. This API manual is too important to not do it right.
> 
> Best,
> Jake
> 
> 
> On Wed, Oct 21, 2009 at 5:57 AM, jpff  wrote:
> > Like Victor I am suspicious of doxygen "manuals".  I have not seen one
> > yet that told be anything useful.
> > ==John ffitch
> >
> > ------------------------------------------------------------------------------
> > Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> > is the only developer event you need to attend this year. Jumpstart your
> > developing skills, take BlackBerry mobile applications to market and stay
> > ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> > http://p.sf.net/sfu/devconference
> > _______________________________________________
> > Csound-devel mailing list
> > Csound-devel@lists.sourceforge.net
> > https://lists.sourceforge.net/lists/listinfo/csound-devel
> >
> 
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay 
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel


-- 
Saludos,
Felipe Sateler

While I have not used all of the packages below, I have used some of them,
and my opinion of their documentation standard is not very high.

Victor

----- Original Message ----- 
From: "Michael Gogins" 
To: "Developer discussions" 
Sent: Wednesday, October 21, 2009 2:34 PM
Subject: Re: [Cs-dev] API documentation


>I have verified that the following projects use Doxygen or similar
> tools that transform comments in source code to generate reference
> manuals. These include some of the important tools and third party
> packages used by Csound.
>
> Java API reference
> FLTK class reference
> wxWidgets class reference
> PortAudio reference
> PortMidi reference
> The GNU libstd++ reference (i.e. the Standard C++ Library that we use
> to build the C++ parts of Csound)
>
> I submit that most Csound developers would have learned something
> useful from the above sources. Unless you guys know all this stuff by
> heart.
>
> Regards,
> Mike
>
>
>
>
>
>
>
>
> On 10/21/09, jpff  wrote:
>> Like Victor I am suspicious of doxygen "manuals".  I have not seen one
>> yet that told be anything useful.
>> ==John ffitch
>>
>> ------------------------------------------------------------------------------
>> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
>> is the only developer event you need to attend this year. Jumpstart your
>> developing skills, take BlackBerry mobile applications to market and stay
>> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
>> http://p.sf.net/sfu/devconference
>> _______________________________________________
>> Csound-devel mailing list
>> Csound-devel@lists.sourceforge.net
>> https://lists.sourceforge.net/lists/listinfo/csound-devel
>>
>
>
> -- 
> Michael Gogins
> Irreducible Productions
> http://www.michael-gogins.com
> Michael dot Gogins at gmail dot com
>
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel 


------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

I thought we were discussing a reference manual.

Typically, for a piece of sofware, there is a reference manual that
documents all of the functions and facilities of the software without
reference to how they might be used. This is what Doxygen or javadoc
is the best tool for. And there is also a user guide that documents
how to use the software, starting with basic use cases and going on
from there.

For example, in the Java documentation, the "API Documentation" is a
reference manual generated by javadoc, and the various separate
"Tutorials" are the user guides. Similarly, for wxWidgets, there is
one manual, in the form of a user's guide, but it contains a class
reference section that is completely generated by Doxygen.

If you need a Csound API manual for composers, you do not need a
technical reference only (though you still do need that). You also
need a user guide. Doxygen and its ilk are, of course, not the right
tool for writing user guides.

"A Csound Tutorial"  and the CsoundAC tutorial, both by me,  both have
material that is more like a user guide, but they do not go into
enough detail. I do not know how much detail is really required.
Possibly "A Csound Tutorial" could be expanded with material on
programming new client for the Csound API that uses the Csound
performance thread, and control channels. This would be 5-10 pages of
additional material, and cover most of what most programmers would
need to know.

But it might be a better, because less confusing, to do an all-new
Csound API User's Guide that is just about using the API. This would
not replace the existing API reference, it would supplement it.

User guides are more work than reference manuals. I think you guys are
completely correct that we need a better user guide to the API, but
you are wrong that there is a need to replace the reference. They are
not the same kind of animal.

Regards,
Mike

On 10/21/09, Jacob Joaquin  wrote:
> I'm also of the mind that doxygen is most likely not a sufficient
> solution. We need a manual that caters to composers, not technical
> C/C++ gurus.
>
> I'm spreading myself thin these days, but I'll be happy to help out in
> any way I can. This API manual is too important to not do it right.
>
> Best,
> Jake
>
>
> On Wed, Oct 21, 2009 at 5:57 AM, jpff  wrote:
>> Like Victor I am suspicious of doxygen "manuals".  I have not seen one
>> yet that told be anything useful.
>> ==John ffitch
>>
>> ------------------------------------------------------------------------------
>> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
>> is the only developer event you need to attend this year. Jumpstart your
>> developing skills, take BlackBerry mobile applications to market and stay
>> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
>> http://p.sf.net/sfu/devconference
>> _______________________________________________
>> Csound-devel mailing list
>> Csound-devel@lists.sourceforge.net
>> https://lists.sourceforge.net/lists/listinfo/csound-devel
>>
>
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel
>


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

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

What I meant when I said write the API for composers is that we need
to write docs for our target audience.  That's everyone from people
who just want to algorithmically generate some sine waves to full on
developers using Csound as a synth engine in their software.  As you
put it, making the API docs easy and well documented.

I may have jumped the gun with my disapproval of doxygen. I really
don't care what is used as long as the manual itself is well written
and well organized. I'm just happy that there seems to be much
enthusiasm for this much needed manual. We should still take the time
to study the alternatives, and try to find the right platform for the
job at hand.

In the mean time, maybe can try to define what the goals for the API manual are?

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



On Wed, Oct 21, 2009 at 7:29 AM, Steven Yi  wrote:
> Agreed.  It's the same issue with Javadocs.  One thing I liked about
> Rory's example he just posted is the main page has quite a bit of
> info.  I don't see it as either-or but really we need both,
> documentation on the level of API library as well as higher-level
> integration documentation to explain how to use the pieces together.
> Whether we create a Doxygen doc and separate doc for big-picture or
> try to do as Rory shows by integrating the big-picture doc isn't a big
> issue for me as long as both are represented.
>
> As for designing the API docs for composers, I don't know what that
> means really. When I'm composing I don't want to think about API's. :P
>  If it means making the API easy to use and well documented, then I'm
> all for it.
>
> steven

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net
https://lists.sourceforge.net/list

I think the documentation standard for Java is very high, and I think
most technical writers and programmers would agree.

There are tutorials for all typical use cases of a very large system,
they go into adequate technical detail, there are overviews of the
entire Java system  and of each subsystem, and I find the javadoc API
reference to be complete and almost entirely error-free.

I have had to do less stumbling around and experimenting after reading
the Java documentation than with any other system, with the single
exception of the Sybase documentation, which sets the standard in my
opinion. Python is quite well documented, but it is harder to navigate
the Python documentation than the Java documentation.

Regards,
Mike



On 10/21/09, victor  wrote:
> While I have not used all of the packages below, I have used some of them,
> and my opinion of their documentation standard is not very high.
>
> Victor
>
> ----- Original Message -----
> From: "Michael Gogins" 
> To: "Developer discussions" 
> Sent: Wednesday, October 21, 2009 2:34 PM
> Subject: Re: [Cs-dev] API documentation
>
>
>>I have verified that the following projects use Doxygen or similar
>> tools that transform comments in source code to generate reference
>> manuals. These include some of the important tools and third party
>> packages used by Csound.
>>
>> Java API reference
>> FLTK class reference
>> wxWidgets class reference
>> PortAudio reference
>> PortMidi reference
>> The GNU libstd++ reference (i.e. the Standard C++ Library that we use
>> to build the C++ parts of Csound)
>>
>> I submit that most Csound developers would have learned something
>> useful from the above sources. Unless you guys know all this stuff by
>> heart.
>>
>> Regards,
>> Mike
>>
>>
>>
>>
>>
>>
>>
>>
>> On 10/21/09, jpff  wrote:
>>> Like Victor I am suspicious of doxygen "manuals".  I have not seen one
>>> yet that told be anything useful.
>>> ==John ffitch
>>>
>>> ------------------------------------------------------------------------------
>>> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
>>> is the only developer event you need to attend this year. Jumpstart your
>>> developing skills, take BlackBerry mobile applications to market and stay
>>> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
>>> http://p.sf.net/sfu/devconference
>>> _______________________________________________
>>> Csound-devel mailing list
>>> Csound-devel@lists.sourceforge.net
>>> https://lists.sourceforge.net/lists/listinfo/csound-devel
>>>
>>
>>
>> --
>> Michael Gogins
>> Irreducible Productions
>> http://www.michael-gogins.com
>> Michael dot Gogins at gmail dot com
>>
>> ------------------------------------------------------------------------------
>> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
>> is the only developer event you need to attend this year. Jumpstart your
>> developing skills, take BlackBerry mobile applications to market and stay
>> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
>> http://p.sf.net/sfu/devconference
>> _______________________________________________
>> Csound-devel mailing list
>> Csound-devel@lists.sourceforge.net
>> https://lists.sourceforge.net/lists/listinfo/csound-devel
>
>
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel
>


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

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

As I said previously, we need two manuals, not one. We need the
current API reference manual generated from Doxygen, which and and
should be be improved by improving the comments in the source code.

We also need a separate "Csound API User's Guide" to cover material such as:

-- What the basic purposes and uses of the API are and could be.
-- What the various layers in the API are and what they are for (this
exists in the reference, but should moved into the user's guide and
expanded).
-- Linking with the Csound API libraries in various platforms,
languages, toolchains: at a minimum C, C++, Python, and Java on
Windows/MinGW, Linux, and OS X.
-- Using the basic Csound API to just render a csd.
-- Using the performance-thread stuff to embed Csound in programs that
also do other things while Csound runs.
-- Using the event channel stuff with client GUIs.
-- Using the Csound file management stuff.
-- Feeding audio into, and out of, Csound as it runs; this currently
works with C, C++, and Java at least but few people do it because it
is very hard to just figure out.

Regards,
Mike

On 10/21/09, Jacob Joaquin  wrote:
> What I meant when I said write the API for composers is that we need
> to write docs for our target audience.  That's everyone from people
> who just want to algorithmically generate some sine waves to full on
> developers using Csound as a synth engine in their software.  As you
> put it, making the API docs easy and well documented.
>
> I may have jumped the gun with my disapproval of doxygen. I really
> don't care what is used as long as the manual itself is well written
> and well organized. I'm just happy that there seems to be much
> enthusiasm for this much needed manual. We should still take the time
> to study the alternatives, and try to find the right platform for the
> job at hand.
>
> In the mean time, maybe can try to define what the goals for the API manual
> are?
>
> Best,
> Jake
> ---
> The Csound Blog - http://csound.noisepages.com/
>
>
>
> On Wed, Oct 21, 2009 at 7:29 AM, Steven Yi  wrote:
>> Agreed.  It's the same issue with Javadocs.  One thing I liked about
>> Rory's example he just posted is the main page has quite a bit of
>> info.  I don't see it as either-or but really we need both,
>> documentation on the level of API library as well as higher-level
>> integration documentation to explain how to use the pieces together.
>> Whether we create a Doxygen doc and separate doc for big-picture or
>> try to do as Rory shows by integrating the big-picture doc isn't a big
>> issue for me as long as both are represented.
>>
>> As for designing the API docs for composers, I don't know what that
>> means really. When I'm composing I don't want to think about API's. :P
>>  If it means making the API easy to use and well documented, then I'm
>> all for it.
>>
>> steven
>
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel
>


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

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

I think this is a great start. Two manuals sounds like a very
plausible solution. And if later it makes sense to combine them into a
single doc, the Csound API User's Guide could be one section, while
the reference manual could be another section.

If we work under the philosophy of "release early, release often" then
perhaps we could start prioritizing what needs to be done first, so
that we can get some information up ASAP. This way, more people can
start getting their hands on the API sooner, while at the same time,
help communicate to the outside world that Csound is still very much
an active project.

As soon as I get some time, I'll look into writing some examples.  And
I'll be happy to proof read anything and everything.

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



On Wed, Oct 21, 2009 at 8:44 AM, Michael Gogins
 wrote:
> As I said previously, we need two manuals, not one. We need the
> current API reference manual generated from Doxygen, which and and
> should be be improved by improving the comments in the source code.
>
> We also need a separate "Csound API User's Guide" to cover material such as:
>
> -- What the basic purposes and uses of the API are and could be.
> -- What the various layers in the API are and what they are for (this
> exists in the reference, but should moved into the user's guide and
> expanded).
> -- Linking with the Csound API libraries in various platforms,
> languages, toolchains: at a minimum C, C++, Python, and Java on
> Windows/MinGW, Linux, and OS X.
> -- Using the basic Csound API to just render a csd.
> -- Using the performance-thread stuff to embed Csound in programs that
> also do other things while Csound runs.
> -- Using the event channel stuff with client GUIs.
> -- Using the Csound file management stuff.
> -- Feeding audio into, and out of, Csound as it runs; this currently
> works with C, C++, and Java at least but few people do it because it
> is very hard to just figure out.
>
> Regards,
> Mike
>
> On 10/21/09, Jacob Joaquin  wrote:
>> What I meant when I said write the API for composers is that we need
>> to write docs for our target audience.  That's everyone from people
>> who just want to algorithmically generate some sine waves to full on
>> developers using Csound as a synth engine in their software.  As you
>> put it, making the API docs easy and well documented.
>>
>> I may have jumped the gun with my disapproval of doxygen. I really
>> don't care what is used as long as the manual itself is well written
>> and well organized. I'm just happy that there seems to be much
>> enthusiasm for this much needed manual. We should still take the time
>> to study the alternatives, and try to find the right platform for the
>> job at hand.
>>
>> In the mean time, maybe can try to define what the goals for the API manual
>> are?
>>
>> Best,
>> Jake
>> ---
>> The Csound Blog - http://csound.noisepages.com/
>>
>>
>>
>> On Wed, Oct 21, 2009 at 7:29 AM, Steven Yi  wrote:
>>> Agreed.  It's the same issue with Javadocs.  One thing I liked about
>>> Rory's example he just posted is the main page has quite a bit of
>>> info.  I don't see it as either-or but really we need both,
>>> documentation on the level of API library as well as higher-level
>>> integration documentation to explain how to use the pieces together.
>>> Whether we create a Doxygen doc and separate doc for big-picture or
>>> try to do as Rory shows by integrating the big-picture doc isn't a big
>>> issue for me as long as both are represented.
>>>
>>> As for designing the API docs for composers, I don't know what that
>>> means really. When I'm composing I don't want to think about API's. :P
>>>  If it means making the API easy to use and well documented, then I'm
>>> all for it.
>>>
>>> steven
>>
>> ------------------------------------------------------------------------------
>> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
>> is the only developer event you need to attend this year. Jumpstart your
>> developing skills, take BlackBerry mobile applications to market and stay
>> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
>> http://p.sf.net/sfu/devconference
>> _______________________________________________
>> Csound-devel mailing list
>> Csound-devel@lists.sourceforge.net
>> https://lists.sourceforge.net/lists/listinfo/csound-devel
>>
>
>
> --
> Michael Gogins
> Irreducible Productions
> http://www.michael-gogins.com
> Michael dot Gogins at gmail dot com
>
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel
>

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net
https://li

I do not care for the toolchain used with the Csound manual. If there
is any way to use LaTeX (my preference, used for the tutorials I have
written) or anything else, I would like to hear about it.

Reasons:

docbook toolchain is harder to install and configure than LaTeX,
especially on Windows.
docbook is harder to edit than LaTeX.
docbook takes longer to compile than LaTeX
docbook output does not look as good as LaTeX output

I understand that docbook provides various alternative output formats
(better than LaTeX does) and I am not proposing to change it for the
Csound reference manual. I would just prefer something better suited
to the task of a tutorial or user guide.

Regards,
Mike

On 10/21/09, Jacob Joaquin  wrote:
> I think this is a great start. Two manuals sounds like a very
> plausible solution. And if later it makes sense to combine them into a
> single doc, the Csound API User's Guide could be one section, while
> the reference manual could be another section.
>
> If we work under the philosophy of "release early, release often" then
> perhaps we could start prioritizing what needs to be done first, so
> that we can get some information up ASAP. This way, more people can
> start getting their hands on the API sooner, while at the same time,
> help communicate to the outside world that Csound is still very much
> an active project.
>
> As soon as I get some time, I'll look into writing some examples.  And
> I'll be happy to proof read anything and everything.
>
> Best,
> Jake
> ---
> The Csound Blog - http://csound.noisepages.com/
>
>
>
> On Wed, Oct 21, 2009 at 8:44 AM, Michael Gogins
>  wrote:
>> As I said previously, we need two manuals, not one. We need the
>> current API reference manual generated from Doxygen, which and and
>> should be be improved by improving the comments in the source code.
>>
>> We also need a separate "Csound API User's Guide" to cover material such
>> as:
>>
>> -- What the basic purposes and uses of the API are and could be.
>> -- What the various layers in the API are and what they are for (this
>> exists in the reference, but should moved into the user's guide and
>> expanded).
>> -- Linking with the Csound API libraries in various platforms,
>> languages, toolchains: at a minimum C, C++, Python, and Java on
>> Windows/MinGW, Linux, and OS X.
>> -- Using the basic Csound API to just render a csd.
>> -- Using the performance-thread stuff to embed Csound in programs that
>> also do other things while Csound runs.
>> -- Using the event channel stuff with client GUIs.
>> -- Using the Csound file management stuff.
>> -- Feeding audio into, and out of, Csound as it runs; this currently
>> works with C, C++, and Java at least but few people do it because it
>> is very hard to just figure out.
>>
>> Regards,
>> Mike
>>
>> On 10/21/09, Jacob Joaquin  wrote:
>>> What I meant when I said write the API for composers is that we need
>>> to write docs for our target audience.  That's everyone from people
>>> who just want to algorithmically generate some sine waves to full on
>>> developers using Csound as a synth engine in their software.  As you
>>> put it, making the API docs easy and well documented.
>>>
>>> I may have jumped the gun with my disapproval of doxygen. I really
>>> don't care what is used as long as the manual itself is well written
>>> and well organized. I'm just happy that there seems to be much
>>> enthusiasm for this much needed manual. We should still take the time
>>> to study the alternatives, and try to find the right platform for the
>>> job at hand.
>>>
>>> In the mean time, maybe can try to define what the goals for the API
>>> manual
>>> are?
>>>
>>> Best,
>>> Jake
>>> ---
>>> The Csound Blog - http://csound.noisepages.com/
>>>
>>>
>>>
>>> On Wed, Oct 21, 2009 at 7:29 AM, Steven Yi  wrote:
>>>> Agreed.  It's the same issue with Javadocs.  One thing I liked about
>>>> Rory's example he just posted is the main page has quite a bit of
>>>> info.  I don't see it as either-or but really we need both,
>>>> documentation on the level of API library as well as higher-level
>>>> integration documentation to explain how to use the pieces together.
>>>> Whether we create a Doxygen doc and separate doc for big-picture or
>>>> try to do as Rory shows by integrating the big-picture doc isn't a big
>>>> issue for me as long as both are represented.
>>>>
>>>> As for designing the API docs for composers, I don't know what that
>>>> means really. When I'm composing I don't want to think about API's. :P
>>>>  If it means making the API easy to use and well documented, then I'm
>>>> all for it.
>>>>
>>>> steven
>>>
>>> ------------------------------------------------------------------------------
>>> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
>>> is the only developer event you need to attend this year. Jumpstart your
>>> developing skills, take BlackBerry mobile applications to market and stay
>>> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
>>> http://p.sf.net/sfu/devconference
>>> _______________________________________________
>>> Csound-devel mailing list
>>> Csound-devel@lists.sourceforge.net
>>> https://lists.sourceforge.net/lists/listinfo/csound-devel
>>>
>>
>>
>> --
>> Michael Gogins
>> Irreducible Productions
>> http://www.michael-gogins.com
>> Michael dot Gogins at gmail dot com
>>
>> ------------------------------------------------------------------------------
>> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
>> is the only developer event you need to attend this year. Jumpstart your
>> developing skills, take BlackBerry mobile applications to market and stay
>> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
>> http://p.sf.net/sfu/devconference
>> _______________________________________________
>> Csound-devel mailing list
>> Csound-devel@lists.sourceforge.net
>> https://lists.sourceforge.net/lists/listinfo/csound-devel
>>
>
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel
>


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

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

The problem with LaTeX is that it is not very good at generating html
output, which would be ideal, so that the manual can be searched by
search engines.

On Wed, 2009-10-21 at 12:15 -0400, Michael Gogins wrote:
> I do not care for the toolchain used with the Csound manual. If there
> is any way to use LaTeX (my preference, used for the tutorials I have
> written) or anything else, I would like to hear about it.
> 
> Reasons:
> 
> docbook toolchain is harder to install and configure than LaTeX,
> especially on Windows.
> docbook is harder to edit than LaTeX.
> docbook takes longer to compile than LaTeX
> docbook output does not look as good as LaTeX output
> 
> I understand that docbook provides various alternative output formats
> (better than LaTeX does) and I am not proposing to change it for the
> Csound reference manual. I would just prefer something better suited
> to the task of a tutorial or user guide.
> 
> Regards,
> Mike
> 
> On 10/21/09, Jacob Joaquin  wrote:
> > I think this is a great start. Two manuals sounds like a very
> > plausible solution. And if later it makes sense to combine them into a
> > single doc, the Csound API User's Guide could be one section, while
> > the reference manual could be another section.
> >
> > If we work under the philosophy of "release early, release often" then
> > perhaps we could start prioritizing what needs to be done first, so
> > that we can get some information up ASAP. This way, more people can
> > start getting their hands on the API sooner, while at the same time,
> > help communicate to the outside world that Csound is still very much
> > an active project.
> >
> > As soon as I get some time, I'll look into writing some examples.  And
> > I'll be happy to proof read anything and everything.
> >
> > Best,
> > Jake
> > ---
> > The Csound Blog - http://csound.noisepages.com/
> >
> >
> >
> > On Wed, Oct 21, 2009 at 8:44 AM, Michael Gogins
> >  wrote:
> >> As I said previously, we need two manuals, not one. We need the
> >> current API reference manual generated from Doxygen, which and and
> >> should be be improved by improving the comments in the source code.
> >>
> >> We also need a separate "Csound API User's Guide" to cover material such
> >> as:
> >>
> >> -- What the basic purposes and uses of the API are and could be.
> >> -- What the various layers in the API are and what they are for (this
> >> exists in the reference, but should moved into the user's guide and
> >> expanded).
> >> -- Linking with the Csound API libraries in various platforms,
> >> languages, toolchains: at a minimum C, C++, Python, and Java on
> >> Windows/MinGW, Linux, and OS X.
> >> -- Using the basic Csound API to just render a csd.
> >> -- Using the performance-thread stuff to embed Csound in programs that
> >> also do other things while Csound runs.
> >> -- Using the event channel stuff with client GUIs.
> >> -- Using the Csound file management stuff.
> >> -- Feeding audio into, and out of, Csound as it runs; this currently
> >> works with C, C++, and Java at least but few people do it because it
> >> is very hard to just figure out.
> >>
> >> Regards,
> >> Mike
> >>
> >> On 10/21/09, Jacob Joaquin  wrote:
> >>> What I meant when I said write the API for composers is that we need
> >>> to write docs for our target audience.  That's everyone from people
> >>> who just want to algorithmically generate some sine waves to full on
> >>> developers using Csound as a synth engine in their software.  As you
> >>> put it, making the API docs easy and well documented.
> >>>
> >>> I may have jumped the gun with my disapproval of doxygen. I really
> >>> don't care what is used as long as the manual itself is well written
> >>> and well organized. I'm just happy that there seems to be much
> >>> enthusiasm for this much needed manual. We should still take the time
> >>> to study the alternatives, and try to find the right platform for the
> >>> job at hand.
> >>>
> >>> In the mean time, maybe can try to define what the goals for the API
> >>> manual
> >>> are?
> >>>
> >>> Best,
> >>> Jake
> >>> ---
> >>> The Csound Blog - http://csound.noisepages.com/
> >>>
> >>>
> >>>
> >>> On Wed, Oct 21, 2009 at 7:29 AM, Steven Yi  wrote:
> >>>> Agreed.  It's the same issue with Javadocs.  One thing I liked about
> >>>> Rory's example he just posted is the main page has quite a bit of
> >>>> info.  I don't see it as either-or but really we need both,
> >>>> documentation on the level of API library as well as higher-level
> >>>> integration documentation to explain how to use the pieces together.
> >>>> Whether we create a Doxygen doc and separate doc for big-picture or
> >>>> try to do as Rory shows by integrating the big-picture doc isn't a big
> >>>> issue for me as long as both are represented.
> >>>>
> >>>> As for designing the API docs for composers, I don't know what that
> >>>> means really. When I'm composing I don't want to think about API's. :P
> >>>>  If it means making the API easy to use and well documented, then I'm
> >>>> all for it.
> >>>>
> >>>> steven
> >>>
> >>> ------------------------------------------------------------------------------
> >>> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> >>> is the only developer event you need to attend this year. Jumpstart your
> >>> developing skills, take BlackBerry mobile applications to market and stay
> >>> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> >>> http://p.sf.net/sfu/devconference
> >>> _______________________________________________
> >>> Csound-devel mailing list
> >>> Csound-devel@lists.sourceforge.net
> >>> https://lists.sourceforge.net/lists/listinfo/csound-devel
> >>>
> >>
> >>
> >> --
> >> Michael Gogins
> >> Irreducible Productions
> >> http://www.michael-gogins.com
> >> Michael dot Gogins at gmail dot com
> >>
> >> ------------------------------------------------------------------------------
> >> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> >> is the only developer event you need to attend this year. Jumpstart your
> >> developing skills, take BlackBerry mobile applications to market and stay
> >> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> >> http://p.sf.net/sfu/devconference
> >> _______________________________________________
> >> Csound-devel mailing list
> >> Csound-devel@lists.sourceforge.net
> >> https://lists.sourceforge.net/lists/listinfo/csound-devel
> >>
> >
> > ------------------------------------------------------------------------------
> > Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> > is the only developer event you need to attend this year. Jumpstart your
> > developing skills, take BlackBerry mobile applications to market and stay
> > ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> > http://p.sf.net/sfu/devconference
> > _______________________________________________
> > Csound-devel mailing list
> > Csound-devel@lists.sourceforge.net
> > https://lists.sourceforge.net/lists/listinfo/csound-devel
> >
> 
> 


-- 
Saludos,
Felipe Sateler

Iain mentioned sphinx. I'm currently using it. Seems to be an easy,
straight forward way of writing docs. Instead of xml tags, it uses
restructured text as its method of markup.  For example: *italics*,
**bold**, ``code``.  For some people, this is easier to read and write
with. It supports auto-syntax highlighting.  It's extensible, so
writing a module that auto-highlights Csound code is certainly in the
realm of the possible.

Sphinx may not be the right solution, but I believe it is worthy of a look.

Sphinx
http://sphinx.pocoo.org/

If you skim through the manual, you can see the source code for each
page just by clicking "Show Source" in the right hand column.

Best,
Jake



On Wed, Oct 21, 2009 at 9:19 AM, Felipe Sateler  wrote:
> The problem with LaTeX is that it is not very good at generating html
> output, which would be ideal, so that the manual can be searched by
> search engines.
>
> On Wed, 2009-10-21 at 12:15 -0400, Michael Gogins wrote:
>> I do not care for the toolchain used with the Csound manual. If there
>> is any way to use LaTeX (my preference, used for the tutorials I have
>> written) or anything else, I would like to hear about it.
>>
>> Reasons:
>>
>> docbook toolchain is harder to install and configure than LaTeX,
>> especially on Windows.
>> docbook is harder to edit than LaTeX.
>> docbook takes longer to compile than LaTeX
>> docbook output does not look as good as LaTeX output
>>
>> I understand that docbook provides various alternative output formats
>> (better than LaTeX does) and I am not proposing to change it for the
>> Csound reference manual. I would just prefer something better suited
>> to the task of a tutorial or user guide.
>>
>> Regards,
>> Mike
>>
>> On 10/21/09, Jacob Joaquin  wrote:
>> > I think this is a great start. Two manuals sounds like a very
>> > plausible solution. And if later it makes sense to combine them into a
>> > single doc, the Csound API User's Guide could be one section, while
>> > the reference manual could be another section.
>> >
>> > If we work under the philosophy of "release early, release often" then
>> > perhaps we could start prioritizing what needs to be done first, so
>> > that we can get some information up ASAP. This way, more people can
>> > start getting their hands on the API sooner, while at the same time,
>> > help communicate to the outside world that Csound is still very much
>> > an active project.
>> >
>> > As soon as I get some time, I'll look into writing some examples.  And
>> > I'll be happy to proof read anything and everything.
>> >
>> > Best,
>> > Jake
>> > ---
>> > The Csound Blog - http://csound.noisepages.com/
>> >
>> >
>> >
>> > On Wed, Oct 21, 2009 at 8:44 AM, Michael Gogins
>> >  wrote:
>> >> As I said previously, we need two manuals, not one. We need the
>> >> current API reference manual generated from Doxygen, which and and
>> >> should be be improved by improving the comments in the source code.
>> >>
>> >> We also need a separate "Csound API User's Guide" to cover material such
>> >> as:
>> >>
>> >> -- What the basic purposes and uses of the API are and could be.
>> >> -- What the various layers in the API are and what they are for (this
>> >> exists in the reference, but should moved into the user's guide and
>> >> expanded).
>> >> -- Linking with the Csound API libraries in various platforms,
>> >> languages, toolchains: at a minimum C, C++, Python, and Java on
>> >> Windows/MinGW, Linux, and OS X.
>> >> -- Using the basic Csound API to just render a csd.
>> >> -- Using the performance-thread stuff to embed Csound in programs that
>> >> also do other things while Csound runs.
>> >> -- Using the event channel stuff with client GUIs.
>> >> -- Using the Csound file management stuff.
>> >> -- Feeding audio into, and out of, Csound as it runs; this currently
>> >> works with C, C++, and Java at least but few people do it because it
>> >> is very hard to just figure out.
>> >>
>> >> Regards,
>> >> Mike
>> >>
>> >> On 10/21/09, Jacob Joaquin  wrote:
>> >>> What I meant when I said write the API for composers is that we need
>> >>> to write docs for our target audience.  That's everyone from people
>> >>> who just want to algorithmically generate some sine waves to full on
>> >>> developers using Csound as a synth engine in their software.  As you
>> >>> put it, making the API docs easy and well documented.
>> >>>
>> >>> I may have jumped the gun with my disapproval of doxygen. I really
>> >>> don't care what is used as long as the manual itself is well written
>> >>> and well organized. I'm just happy that there seems to be much
>> >>> enthusiasm for this much needed manual. We should still take the time
>> >>> to study the alternatives, and try to find the right platform for the
>> >>> job at hand.
>> >>>
>> >>> In the mean time, maybe can try to define what the goals for the API
>> >>> manual
>> >>> are?
>> >>>
>> >>> Best,
>> >>> Jake
>> >>> ---
>> >>> The Csound Blog - http://csound.noisepages.com/
>> >>>
>> >>>
>> >>>
>> >>> On Wed, Oct 21, 2009 at 7:29 AM, Steven Yi  wrote:
>> >>>> Agreed.  It's the same issue with Javadocs.  One thing I liked about
>> >>>> Rory's example he just posted is the main page has quite a bit of
>> >>>> info.  I don't see it as either-or but really we need both,
>> >>>> documentation on the level of API library as well as higher-level
>> >>>> integration documentation to explain how to use the pieces together.
>> >>>> Whether we create a Doxygen doc and separate doc for big-picture or
>> >>>> try to do as Rory shows by integrating the big-picture doc isn't a big
>> >>>> issue for me as long as both are represented.
>> >>>>
>> >>>> As for designing the API docs for composers, I don't know what that
>> >>>> means really. When I'm composing I don't want to think about API's. :P
>> >>>>  If it means making the API easy to use and well documented, then I'm
>> >>>> all for it.
>> >>>>
>> >>>> steven
>> >>>
>> >>> ------------------------------------------------------------------------------
>> >>> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
>> >>> is the only developer event you need to attend this year. Jumpstart your
>> >>> developing skills, take BlackBerry mobile applications to market and stay
>> >>> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
>> >>> http://p.sf.net/sfu/devconference
>> >>> _______________________________________________
>> >>> Csound-devel mailing list
>> >>> Csound-devel@lists.sourceforge.net
>> >>> https://lists.sourceforge.net/lists/listinfo/csound-devel
>> >>>
>> >>
>> >>
>> >> --
>> >> Michael Gogins
>> >> Irreducible Productions
>> >> http://www.michael-gogins.com
>> >> Michael dot Gogins at gmail dot com
>> >>
>> >> ------------------------------------------------------------------------------
>> >> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
>> >> is the only developer event you need to attend this year. Jumpstart your
>> >> developing skills, take BlackBerry mobile applications to market and stay
>> >> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
>> >> http://p.sf.net/sfu/devconference
>> >> _______________________________________________
>> >> Csound-devel mailing list
>> >> Csound-devel@lists.sourceforge.net
>> >> https://lists.sourceforge.net/lists/listinfo/csound-devel
>> >>
>> >
>> > ------------------------------------------------------------------------------
>> > Come build with us! The BlackBerry(R) Developer Conference in SF, CA
>> > is the only developer event you need to attend this year. Jumpstart your
>> > developing skills, take BlackBerry mobile applications to market and stay
>> > ahead of the curve. Join us from November 9 - 12, 2009. Register now!
>> > http://p.sf.net/sfu/devconference
>> > _______________________________________________
>> > Csound-devel mailing list
>> > Csound-devel@lists.sourceforge.net
>> > https://lists.sourceforge.net/lists/listinfo/csound-devel
>> >
>>
>>
>
>
> --
> Saludos,
> Felipe Sateler
>
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel
>
>



-- 
The Csound Blog - http://csound.noisepages.com/

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net
https://lists.sourceforge.net/

I don't agree that the doxygen-generated manuals are good. But that is my
opinion.

Victor
----- Original Message ----- 
From: "Michael Gogins" 
To: "Developer discussions" 
Sent: Wednesday, October 21, 2009 4:44 PM
Subject: Re: [Cs-dev] API documentation


> As I said previously, we need two manuals, not one. We need the
> current API reference manual generated from Doxygen, which and and
> should be be improved by improving the comments in the source code.
>
> We also need a separate "Csound API User's Guide" to cover material such 
> as:
>
> -- What the basic purposes and uses of the API are and could be.
> -- What the various layers in the API are and what they are for (this
> exists in the reference, but should moved into the user's guide and
> expanded).
> -- Linking with the Csound API libraries in various platforms,
> languages, toolchains: at a minimum C, C++, Python, and Java on
> Windows/MinGW, Linux, and OS X.
> -- Using the basic Csound API to just render a csd.
> -- Using the performance-thread stuff to embed Csound in programs that
> also do other things while Csound runs.
> -- Using the event channel stuff with client GUIs.
> -- Using the Csound file management stuff.
> -- Feeding audio into, and out of, Csound as it runs; this currently
> works with C, C++, and Java at least but few people do it because it
> is very hard to just figure out.
>
> Regards,
> Mike
>
> On 10/21/09, Jacob Joaquin  wrote:
>> What I meant when I said write the API for composers is that we need
>> to write docs for our target audience.  That's everyone from people
>> who just want to algorithmically generate some sine waves to full on
>> developers using Csound as a synth engine in their software.  As you
>> put it, making the API docs easy and well documented.
>>
>> I may have jumped the gun with my disapproval of doxygen. I really
>> don't care what is used as long as the manual itself is well written
>> and well organized. I'm just happy that there seems to be much
>> enthusiasm for this much needed manual. We should still take the time
>> to study the alternatives, and try to find the right platform for the
>> job at hand.
>>
>> In the mean time, maybe can try to define what the goals for the API 
>> manual
>> are?
>>
>> Best,
>> Jake
>> ---
>> The Csound Blog - http://csound.noisepages.com/
>>
>>
>>
>> On Wed, Oct 21, 2009 at 7:29 AM, Steven Yi  wrote:
>>> Agreed.  It's the same issue with Javadocs.  One thing I liked about
>>> Rory's example he just posted is the main page has quite a bit of
>>> info.  I don't see it as either-or but really we need both,
>>> documentation on the level of API library as well as higher-level
>>> integration documentation to explain how to use the pieces together.
>>> Whether we create a Doxygen doc and separate doc for big-picture or
>>> try to do as Rory shows by integrating the big-picture doc isn't a big
>>> issue for me as long as both are represented.
>>>
>>> As for designing the API docs for composers, I don't know what that
>>> means really. When I'm composing I don't want to think about API's. :P
>>>  If it means making the API easy to use and well documented, then I'm
>>> all for it.
>>>
>>> steven
>>
>> ------------------------------------------------------------------------------
>> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
>> is the only developer event you need to attend this year. Jumpstart your
>> developing skills, take BlackBerry mobile applications to market and stay
>> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
>> http://p.sf.net/sfu/devconference
>> _______________________________________________
>> Csound-devel mailing list
>> Csound-devel@lists.sourceforge.net
>> https://lists.sourceforge.net/lists/listinfo/csound-devel
>>
>
>
> -- 
> Michael Gogins
> Irreducible Productions
> http://www.michael-gogins.com
> Michael dot Gogins at gmail dot com
>
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel 


------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

I don't know about Java, but PortAudio and PortMIDI are not particularly
great on the documentation side.

Victor
----- Original Message ----- 
From: "Michael Gogins" 
To: "Developer discussions" 
Sent: Wednesday, October 21, 2009 4:33 PM
Subject: Re: [Cs-dev] API documentation


>I think the documentation standard for Java is very high, and I think
> most technical writers and programmers would agree.
>
> There are tutorials for all typical use cases of a very large system,
> they go into adequate technical detail, there are overviews of the
> entire Java system  and of each subsystem, and I find the javadoc API
> reference to be complete and almost entirely error-free.
>
> I have had to do less stumbling around and experimenting after reading
> the Java documentation than with any other system, with the single
> exception of the Sybase documentation, which sets the standard in my
> opinion. Python is quite well documented, but it is harder to navigate
> the Python documentation than the Java documentation.
>
> Regards,
> Mike
>
>
>
> On 10/21/09, victor  wrote:
>> While I have not used all of the packages below, I have used some of 
>> them,
>> and my opinion of their documentation standard is not very high.
>>
>> Victor
>>
>> ----- Original Message -----
>> From: "Michael Gogins" 
>> To: "Developer discussions" 
>> Sent: Wednesday, October 21, 2009 2:34 PM
>> Subject: Re: [Cs-dev] API documentation
>>
>>
>>>I have verified that the following projects use Doxygen or similar
>>> tools that transform comments in source code to generate reference
>>> manuals. These include some of the important tools and third party
>>> packages used by Csound.
>>>
>>> Java API reference
>>> FLTK class reference
>>> wxWidgets class reference
>>> PortAudio reference
>>> PortMidi reference
>>> The GNU libstd++ reference (i.e. the Standard C++ Library that we use
>>> to build the C++ parts of Csound)
>>>
>>> I submit that most Csound developers would have learned something
>>> useful from the above sources. Unless you guys know all this stuff by
>>> heart.
>>>
>>> Regards,
>>> Mike
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>> On 10/21/09, jpff  wrote:
>>>> Like Victor I am suspicious of doxygen "manuals".  I have not seen one
>>>> yet that told be anything useful.
>>>> ==John ffitch
>>>>
>>>> ------------------------------------------------------------------------------
>>>> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
>>>> is the only developer event you need to attend this year. Jumpstart 
>>>> your
>>>> developing skills, take BlackBerry mobile applications to market and 
>>>> stay
>>>> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
>>>> http://p.sf.net/sfu/devconference
>>>> _______________________________________________
>>>> Csound-devel mailing list
>>>> Csound-devel@lists.sourceforge.net
>>>> https://lists.sourceforge.net/lists/listinfo/csound-devel
>>>>
>>>
>>>
>>> --
>>> Michael Gogins
>>> Irreducible Productions
>>> http://www.michael-gogins.com
>>> Michael dot Gogins at gmail dot com
>>>
>>> ------------------------------------------------------------------------------
>>> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
>>> is the only developer event you need to attend this year. Jumpstart your
>>> developing skills, take BlackBerry mobile applications to market and 
>>> stay
>>> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
>>> http://p.sf.net/sfu/devconference
>>> _______________________________________________
>>> Csound-devel mailing list
>>> Csound-devel@lists.sourceforge.net
>>> https://lists.sourceforge.net/lists/listinfo/csound-devel
>>
>>
>> ------------------------------------------------------------------------------
>> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
>> is the only developer event you need to attend this year. Jumpstart your
>> developing skills, take BlackBerry mobile applications to market and stay
>> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
>> http://p.sf.net/sfu/devconference
>> _______________________________________________
>> Csound-devel mailing list
>> Csound-devel@lists.sourceforge.net
>> https://lists.sourceforge.net/lists/listinfo/csound-devel
>>
>
>
> -- 
> Michael Gogins
> Irreducible Productions
> http://www.michael-gogins.com
> Michael dot Gogins at gmail dot com
>
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel 


------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

I believe pdfs produced by latex are searched by Google. I will check.
Mkg

On Oct 21, 2009 12:46 PM, "victor" <Victor.Lazzarini@nuim.ie> wrote:

I don't know about Java, but PortAudio and PortMIDI are not particularly
great on the documentation side.

Victor ----- Original Message ----- From: "Michael Gogins" <michael.gogins@gmail.com> To: "Develop...

Sent: Wednesday, October 21, 2009 4:33 PM Subject: Re: [Cs-dev] API documentation >I think the doc...

"but you are wrong that there is a need to replace the reference"

But we do not have a reference manual for the API

==John ffitch

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

Just a minor comment: The License in the main page should be at the bottom.

I agree that there should be a separate API referece and a User's
manual. I'm not sure the API User's manual should go in the Csound
Reference manual, but we can put it there.

Cheers,
Andrés

On Wed, Oct 21, 2009 at 3:24 PM, Rory Walsh  wrote:
> Yes I agree but doxygen manuals can include all this info. Check out
> the manuals for the projects Michael listed above, especially the
> wxWidgets which I use extensively.
> http://docs.wxwidgets.org/2.6/wx_classref.html Each of the class refs
> include examples where needed. There is also an overview page too, all
> this can be done with doxygen. I've played around with the current
> reference manual and it's a nightmare to edit.
>
> Rory.
>
>
> 2009/10/21 Stéphane Rollandin :
>> yes, doxygen stuff does not explain how to use the API. while it is very
>> much worthwhile, IMO it is definitely in need of some human-written
>> documentation giving an overall picture of the whole API structure and
>> usage.
>>
>> Stef
>>
>>
>>
>> ------------------------------------------------------------------------------
>> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
>> is the only developer event you need to attend this year. Jumpstart your
>> developing skills, take BlackBerry mobile applications to market and stay
>> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
>> http://p.sf.net/sfu/devconference
>> _______________________________________________
>> Csound-devel mailing list
>> Csound-devel@lists.sourceforge.net
>> https://lists.sourceforge.net/lists/listinfo/csound-devel
>>
>
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel
>



-- 


Andrés

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

Yes we do.

On Oct 22, 2009 2:52 AM, "jpff" <jpff@codemist.co.uk> wrote:

"but you are wrong that there is a need to replace the reference"

But we do not have a reference manual for the API

==John ffitch ------------------------------------------------------------------------------ Come ...

I repeat -- we do not have a reference manual for the API.  There are
many functions in the API that do not appear in the current texts
which are language specific (and not the language I was using).  The
student's work was a failure as we could not find out how to use the
API.

==John ffitch

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

We do need both a manual and a guide and some language-specific  
tutorials (graded from simple to advanced), and links to some  
successful full-blown language-specific projects/models that use the  
API - like Blue, TamTam, Cecilia4, CsoundAC, etc.  These manuals and  
tutorials should probably not be in the Canonical Csound5 Manual but  
rather should all be in a new developers section/manual/page/wiki/site  
- and might include other developer documents/tutorials etc... (on  
adding opcodes, etc...)

-dB

Dr. Richard Boulanger  -  rboulanger@berklee.edu



On Oct 22, 2009, at 10:05 AM, jpff wrote:

> I repeat -- we do not have a reference manual for the API.  There are
> many functions in the API that do not appear in the current texts
> which are language specific (and not the language I was using).  The
> student's work was a failure as we could not find out how to use the
> API.
>
> ==John ffitch
>
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart  
> your
> developing skills, take BlackBerry mobile applications to market and  
> stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel


------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

As far as I know all functions in the API show up in the reference
manual, although there are not explanations for a lot of them, at
least the signatures are recorded.

What language were you using?

Regards,
Mike

On 10/22/09, jpff  wrote:
> I repeat -- we do not have a reference manual for the API.  There are
> many functions in the API that do not appear in the current texts
> which are language specific (and not the language I was using).  The
> student's work was a failure as we could not find out how to use the
> API.
>
> ==John ffitch
>
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel
>


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

------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net

On Thu, 2009-10-22 at 10:18 -0400, Dr. Richard Boulanger wrote:
> We do need both a manual and a guide and some language-specific  
> tutorials (graded from simple to advanced), and links to some  
> successful full-blown language-specific projects/models that use the  
> API - like Blue, TamTam, Cecilia4, CsoundAC, etc.  These manuals and  
> tutorials should probably not be in the Canonical Csound5 Manual but  
> rather should all be in a new developers section/manual/page/wiki/site  
> - and might include other developer documents/tutorials etc... (on  
> adding opcodes, etc...)

I think stub entries pointing people in the write direction from the
main manual would be good though.

Iain
> 
> -dB
> 
> Dr. Richard Boulanger  -  rboulanger@berklee.edu
> 
> 
> 
> On Oct 22, 2009, at 10:05 AM, jpff wrote:
> 
> > I repeat -- we do not have a reference manual for the API.  There are
> > many functions in the API that do not appear in the current texts
> > which are language specific (and not the language I was using).  The
> > student's work was a failure as we could not find out how to use the
> > API.
> >
> > ==John ffitch
> >
> > ------------------------------------------------------------------------------
> > Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> > is the only developer event you need to attend this year. Jumpstart  
> > your
> > developing skills, take BlackBerry mobile applications to market and  
> > stay
> > ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> > http://p.sf.net/sfu/devconference
> > _______________________________________________
> > Csound-devel mailing list
> > Csound-devel@lists.sourceforge.net
> > https://lists.sourceforge.net/lists/listinfo/csound-devel
> 
> 
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay 
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Csound-devel mailing list
> Csound-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/csound-devel


------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay 
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net