Csounders-

A few thoughts that have occurred to me as I read the posts (from which I
quote) on this topic:

Richard Bowers:
>the list itself reveals a wide range of levels understanding of >csound.

This is a problem with any list of "Known Bugs," regardless where it
resides. When I find a bug, in my own use of Csound, I usually discover
that it is between my ears. So for a "Known Bugs" list to be anything more
than a rehashing of half the posts to the list, each would need to be
verified by someone, most likely John ffitch. Seems like a waste of his (or
anyone's) time, when he could just fix it instead. Hmm...that's exactly
what happens now....
....as long as he knows about it:

John ffitch:
>If no one reports an error then it is unlikely to
>get fixed unless it kicks one of my pieces -- 

Larry Troxler:
>Actually, my idea wasn't just to document known errors, but to >document
>known non-errors, IOW to document that someone somewhere is >sucessfully
>using a certain ugen, so that someone can feel confident in using 

Why not just assume they all work, until you find out otherwise, either
through the list or by personal experience? I realize that can be
frustrating, but that's why the list exists.

In some cases, what appears to be a bug may only be a lack of understanding
about what the opcode is supposed to do. Often this is due to unclear
documentation - a situation I am always trying to improve. (More about that
later)

Several people already send me suggestions for improvement on this or that
opcode's documentation. I greatly appreciate this, and attempt to credit
those contributions on my "What's New" page with each release.

I do not think the manual is an appropriate place to document known bugs,
except *maybe* in an appendix. However, John usually fixes bugs in his next
release that have been brought to his attention since the last one. Any
list in the manual would be out of date as soon as it is published. 

A few opcodes already carry warnings in the manual. Ideally, these should
come from programmer who wrote the code.

Richard again:
>It may be good to organise the sections differently 

This has been under way for some weeks and will be take place in version
3.59 of the Acrobat (pdf) and HTML manuals. It is quite a large job and
taking some time, so it will be a few more weeks before it is ready.

Note to those who keep a printed copy of the Acrobat manual - go buy paper.
Version 3.59 is a complete reprint. Version 3.57 cannot be upgraded to
version 3.59.

Richard:
>I feel that some of the examples may be added to and the >consistent
>format expanded to allow for other common features (eg. default >settings may
>be explicitly stated

Defaults usually are stated for optional arguments. I believe (but could be
wrong) that most required arguments do not have defaults.

Inconsistent use of examples is still one of the biggest problems with the
manual as it exists, IMO. I have added a one or two myself, but I simply
don't have time to write and test them all.

I've had in mind for a while, to initiate a "Csound Example Project" to
fill out the manuals' examples. This seems to me the best way for users to
be certain that the opcode they are about to use really works, and their
understanding of how it works, and what it is supposed to do, is accurate.

After the current re-edit of the manual is finished, I'll try to  come up
with some guidelines for anyone wishing to submit them.

-David.


_________________________________________________________
Do You Yahoo!?
Get your free @yahoo.com address at http://mail.yahoo.com