[Cs-dev] Csound 5 Reference Manual
| Date | 2005-11-15 12:20 |
| From | Victor Lazzarini |
| Subject | [Cs-dev] Csound 5 Reference Manual |
I would like to start discussing a structure for the Csound 5 Manual,
which also might spark the debate on what should be included in the
standard distribution.
My idea is to first put together a lean, but updated and correct,
Reference Manual, excluding most of the user's guide text, which can
be compiled as a separate document. An initial structure for
such manual is proposed as:
Csound 5 Reference Manual
1. Csound Language
1.1 Frontends
1.1.1 Csound command-line program
1.1.2 CsoundVST
1.1.3 Csoundapi~
1.1.4 FlCsound
1.1.5 TclCsound
1.2 Orchestra Language
1.3 Score Language
2. Csound Utilities
2.1 Analysis utilities
2.2 File and soundfile utilities
2.3 Score utilities
3. Csound Host API
3.1 The C Language API
3.2 Language Wrappers
3.2.1 Python
3.2.2 Java
3.2.3 Common Lisp
3.2.4 Tcl/Tk
4. Csound Module API
I have included everything that seems to be working on all three platforms
(with the exception of CsoundVST I suppose). In moving towards deciding
what goes in to the standard distribution, I would like to make sure we only
include stuff that works in all platforms. Platform-dependent components,
such as frontends or plugin libraries can be distributed separately. This
excludes
of course the platform-specific IO modules, for which an exception should
always be made.
Victor Lazzarini
Music Technology Laboratory
Music Department
National University of Ireland, Maynooth
-------------------------------------------------------
This SF.Net email is sponsored by the JBoss Inc. Get Certified Today
Register for a JBoss Training Course. Free Certification Exam
for All Training Attendees Through End of 2005. For more info visit:
http://ads.osdn.com/?ad_id=7628&alloc_id=16845&op=click
_______________________________________________
Csound-devel mailing list
Csound-devel@lists.sourceforge.net |
| Date | 2005-11-15 13:53 |
| From | Istvan Varga |
| Subject | Re: [Cs-dev] Csound 5 Reference Manual |
Victor Lazzarini wrote: > Csound 5 Reference Manual > > 1. Csound Language > 1.1 Frontends > 1.1.1 Csound command-line program > 1.1.2 CsoundVST > 1.1.3 Csoundapi~ > 1.1.4 FlCsound > 1.1.5 TclCsound > 1.2 Orchestra Language > 1.3 Score Language > 2. Csound Utilities > 2.1 Analysis utilities > 2.2 File and soundfile utilities > 2.3 Score utilities > 3. Csound Host API > 3.1 The C Language API > 3.2 Language Wrappers > 3.2.1 Python > 3.2.2 Java > 3.2.3 Common Lisp > 3.2.4 Tcl/Tk > 4. Csound Module API Most of 1. and 2. (with the exception of the special frontends) is already in the CVS manual, although it may need to be better organized to improve the usability of the manual. However, 3. and 4. are largely undocumented at this time, so a lot of work is needed to add up to date API documentation. I would offer help in writing manuals, but the basic structure of the API documentation needs to be created first (perhaps with initially empty manual templates for each function first, which can be easily completed later by whoever has enough information on a particular issue). ------------------------------------------------------- This SF.Net email is sponsored by the JBoss Inc. Get Certified Today Register for a JBoss Training Course. Free Certification Exam for All Training Attendees Through End of 2005. For more info visit: http://ads.osdn.com/?ad_id=7628&alloc_id=16845&op=click _______________________________________________ Csound-devel mailing list Csound-devel@lists.sourceforge.net |
| Date | 2005-11-15 14:04 |
| From | Victor Lazzarini |
| Subject | Re: [Cs-dev] Csound 5 Reference Manual |
At 13:53 15/11/2005, you wrote: >Victor Lazzarini wrote: > >>Csound 5 Reference Manual >>1. Csound Language >> 1.1 Frontends >> 1.1.1 Csound command-line program >> 1.1.2 CsoundVST >> 1.1.3 Csoundapi~ >> 1.1.4 FlCsound >> 1.1.5 TclCsound >> 1.2 Orchestra Language >> 1.3 Score Language >>2. Csound Utilities >> 2.1 Analysis utilities >> 2.2 File and soundfile utilities >> 2.3 Score utilities >>3. Csound Host API >> 3.1 The C Language API >> 3.2 Language Wrappers >> 3.2.1 Python >> 3.2.2 Java >> 3.2.3 Common Lisp >> 3.2.4 Tcl/Tk >>4. Csound Module API > >Most of 1. and 2. (with the exception of the special frontends) >is already in the CVS manual, although it may need to be better >organized to improve the usability of the manual. That was my idea. >However, 3. and >4. are largely undocumented at this time, so a lot of work is >needed to add up to date API documentation. I would offer help in >writing manuals, but the basic structure of the API documentation >needs to be created first (perhaps with initially empty manual >templates for each function first, which can be easily completed >later by whoever has enough information on a particular issue). Yes, that information is not generally available, apart from the comments in the header files. What would be the most suitable format? Something akin to man pages (section 3)? I agree that we should have an unified format. However, I am not too keen on using Doxygen-type documentation. I think it would be better and more complete to do it by hand. I can offer to do bits of it, if needed. Victor Lazzarini Music Technology Laboratory Music Department National University of Ireland, Maynooth ------------------------------------------------------- This SF.Net email is sponsored by the JBoss Inc. Get Certified Today Register for a JBoss Training Course. Free Certification Exam for All Training Attendees Through End of 2005. For more info visit: http://ads.osdn.com/?ad_id=7628&alloc_id=16845&op=click _______________________________________________ Csound-devel mailing list Csound-devel@lists.sourceforge.net |
| Date | 2005-11-15 14:23 |
| From | Andy Baxter |
| Subject | Re: [Cs-dev] Csound 5 Reference Manual |
| Attachments | None |
| Date | 2005-11-15 14:34 |
| From | Istvan Varga |
| Subject | Re: [Cs-dev] Csound 5 Reference Manual |
Victor Lazzarini wrote: > Yes, that information is not generally available, apart from the > comments in the header files. What would be the most suitable > format? Something akin to man pages (section 3)? I agree that > we should have an unified format. Yes, that is what I have thought of, and the opcode manuals also have a similar structure to man pages. A manual for an API function is expected to have sections like name (with a one-line summary of the function), synopsis (prototype with argument names and required header file), description (this is where the use of the function is explained in detail, perhaps with a separate section for documenting each argument), return value (with information about possible error codes), notes/bugs (any special limitations or quirks), example (if any), see also, and maybe author. In the case of the plugin API, it should be noted if a function possibly does not return (i.e. may call longjmp on some errors), and for callback functions it should be documented if calling csound->Die() or csound->LongJmp() is allowed. In addition to the API reference, it would be useful to have general documentation on some topics, like how to create a plugin library or a simple host application, etc. ------------------------------------------------------- This SF.Net email is sponsored by the JBoss Inc. Get Certified Today Register for a JBoss Training Course. Free Certification Exam for All Training Attendees Through End of 2005. For more info visit: http://ads.osdn.com/?ad_id=7628&alloc_id=16845&op=click _______________________________________________ Csound-devel mailing list Csound-devel@lists.sourceforge.net |
| Date | 2005-11-15 14:44 |
| From | Victor Lazzarini |
| Subject | Re: [Cs-dev] Csound 5 Reference Manual |
Perhaps the extensions to the csound language text can be adapted for the plugin example. Iain Duncan was doing something for a host api as well. At 14:34 15/11/2005, you wrote: >In addition to the API reference, it would be useful to have >general documentation on some topics, like how to create a >plugin library or a simple host application, etc. Victor Lazzarini Music Technology Laboratory Music Department National University of Ireland, Maynooth ------------------------------------------------------- This SF.Net email is sponsored by the JBoss Inc. Get Certified Today Register for a JBoss Training Course. Free Certification Exam for All Training Attendees Through End of 2005. For more info visit: http://ads.osdn.com/?ad_id=7628&alloc_id=16845&op=click _______________________________________________ Csound-devel mailing list Csound-devel@lists.sourceforge.net |
| Date | 2005-11-15 15:03 |
| From | Victor Lazzarini |
| Subject | Re: [Cs-dev] Csound 5 Reference Manual |
How does this look like as an example of host API manual page? ============================================================== csoundCreate() Creates an instance of Csound. SYNOPSIS: CSOUND *csoundCreate(void *hostData) void *hostData: pointer to host supplied data. RETURN VALUE: On success, the function returns a pointer to the CSOUND structure defining the new Csound instance. DESCRIPTION: This function creates in memory an instance of csound. It takes, optionally, a pointer to the host dataspace, but this parameter can also be NULL. This function returns a pointer to the CSOUND structure, which is then used in further calls to the Csound host API, such as csoundCompile() or csoundPerform(). EXAMPLE: CSOUND *csound; csoundInitialize(NULL, NULL, 0); csound = csoundCreate(NULL); AUTHORS: John ffitch, Istvan Varga. ============================================================================== At 14:34 15/11/2005, you wrote: >Victor Lazzarini wrote: > >>Yes, that information is not generally available, apart from the >>comments in the header files. What would be the most suitable >>format? Something akin to man pages (section 3)? I agree that >>we should have an unified format. > >Yes, that is what I have thought of, and the opcode manuals >also have a similar structure to man pages. A manual for an >API function is expected to have sections like name (with a >one-line summary of the function), synopsis (prototype with >argument names and required header file), description (this >is where the use of the function is explained in detail, >perhaps with a separate section for documenting each argument), >return value (with information about possible error codes), >notes/bugs (any special limitations or quirks), example (if >any), see also, and maybe author. In the case of the plugin >API, it should be noted if a function possibly does not return >(i.e. may call longjmp on some errors), and for callback >functions it should be documented if calling csound->Die() >or csound->LongJmp() is allowed. >In addition to the API reference, it would be useful to have >general documentation on some topics, like how to create a >plugin library or a simple host application, etc. > > >------------------------------------------------------- >This SF.Net email is sponsored by the JBoss Inc. Get Certified Today >Register for a JBoss Training Course. Free Certification Exam >for All Training Attendees Through End of 2005. For more info visit: >http://ads.osdn.com/?ad_id=7628&alloc_id=16845&op=click >_______________________________________________ >Csound-devel mailing list >Csound-devel@lists.sourceforge.net >https://lists.sourceforge.net/lists/listinfo/csound-devel Victor Lazzarini Music Technology Laboratory Music Department National University of Ireland, Maynooth ------------------------------------------------------- This SF.Net email is sponsored by the JBoss Inc. Get Certified Today Register for a JBoss Training Course. Free Certification Exam for All Training Attendees Through End of 2005. For more info visit: http://ads.osdn.com/?ad_id=7628&alloc_id=16845&op=click _______________________________________________ Csound-devel mailing list Csound-devel@lists.sourceforge.net |
| Date | 2005-11-15 15:18 |
| From | Istvan Varga |
| Subject | Re: [Cs-dev] Csound 5 Reference Manual |
Victor Lazzarini wrote: This is generally OK, although it should be noted that csoundCreate() will implicitly call csoundInitialize(NULL,NULL,0) if it was not already done. I think RETURN VALUE is usually after DESCRIPTION, and the required header file could be mentioned in SYNOPSIS, but these are minor details. > How does this look like as an example of host API manual page? > ============================================================== > csoundCreate() > > Creates an instance of Csound. > > SYNOPSIS: > > CSOUND *csoundCreate(void *hostData) > > void *hostData: pointer to host supplied data. > > RETURN VALUE: > > On success, the function returns a pointer to the CSOUND structure > defining the new Csound instance. > > DESCRIPTION: > > This function creates in memory an instance of csound. It takes, > optionally, a pointer to the host dataspace, but this parameter can also > be NULL. This function returns a pointer to the CSOUND structure, which > is then used in further calls to the Csound host API, such as > csoundCompile() or csoundPerform(). > > EXAMPLE: > > CSOUND *csound; > > csoundInitialize(NULL, NULL, 0); > csound = csoundCreate(NULL); > > AUTHORS: > John ffitch, Istvan Varga. ------------------------------------------------------- This SF.Net email is sponsored by the JBoss Inc. Get Certified Today Register for a JBoss Training Course. Free Certification Exam for All Training Attendees Through End of 2005. For more info visit: http://ads.osdn.com/?ad_id=7628&alloc_id=16845&op=click _______________________________________________ Csound-devel mailing list Csound-devel@lists.sourceforge.net |
| Date | 2005-11-15 16:03 |
| From | Victor Lazzarini |
| Subject | Re: [Cs-dev] Csound 5 Reference Manual |
I suppose in keeping with the current CVS manual pages, we'll have to do these pages as xml files, will we not? Victor At 15:18 15/11/2005, you wrote: >Victor Lazzarini wrote: > >This is generally OK, although it should be noted that >csoundCreate() will implicitly call csoundInitialize(NULL,NULL,0) >if it was not already done. I think RETURN VALUE is usually >after DESCRIPTION, and the required header file could be mentioned >in SYNOPSIS, but these are minor details. > >>How does this look like as an example of host API manual page? >>============================================================== >>csoundCreate() >>Creates an instance of Csound. >>SYNOPSIS: >>CSOUND *csoundCreate(void *hostData) >>void *hostData: pointer to host supplied data. >>RETURN VALUE: >>On success, the function returns a pointer to the CSOUND structure >>defining the new Csound instance. >>DESCRIPTION: >>This function creates in memory an instance of csound. It takes, >>optionally, a pointer to the host dataspace, but this parameter can also >>be NULL. This function returns a pointer to the CSOUND structure, which >>is then used in further calls to the Csound host API, such as >>csoundCompile() or csoundPerform(). >>EXAMPLE: >>CSOUND *csound; >>csoundInitialize(NULL, NULL, 0); >>csound = csoundCreate(NULL); >>AUTHORS: >>John ffitch, Istvan Varga. > > >------------------------------------------------------- >This SF.Net email is sponsored by the JBoss Inc. Get Certified Today >Register for a JBoss Training Course. Free Certification Exam >for All Training Attendees Through End of 2005. For more info visit: >http://ads.osdn.com/?ad_id=7628&alloc_id=16845&op=click >_______________________________________________ >Csound-devel mailing list >Csound-devel@lists.sourceforge.net >https://lists.sourceforge.net/lists/listinfo/csound-devel Victor Lazzarini Music Technology Laboratory Music Department National University of Ireland, Maynooth ------------------------------------------------------- This SF.Net email is sponsored by the JBoss Inc. Get Certified Today Register for a JBoss Training Course. Free Certification Exam for All Training Attendees Through End of 2005. For more info visit: http://ads.osdn.com/?ad_id=7628&alloc_id=16845&op=click _______________________________________________ Csound-devel mailing list Csound-devel@lists.sourceforge.net |
| Date | 2005-11-15 16:16 |
| From | Victor Lazzarini |
| Subject | Re: [Cs-dev] Csound 5 Reference Manual |
In which case, would this be the xml version (sorry, I am guessing here) |