Michael Gogins wrote:

> Of course, there are always other possibilities. Please do 
> not interpret my ideas as criticisms of your excellent work, 
> which I use constantly.

No problem.

> Documentation could be generated using doxygen from comments in the
> code.

I don't think the docstring concept works very well in practice. Anyone
who has hacked the TeX sources like I have would probably agree. More
troubling, I find doxygen's HTML output difficult to navigate and
therefore unusable. Their PDF output is also cumbersome to use (huge
type, no bookmarks, etc.)

Would this would require someone to have doxygen installed in order to
build Csound? Bad idea.

> It would also be possible to insert the documentation directly into
> the source code

I think adding more comments to the source code would be appreciated.
Provided that they don't degrade the readability of the code. Of
course, this increases the burden on future maintainers.

In practice, I think programmers hack code and tend to neglect updating
its surrounding comments. When those comments are in a format as
arbitrary as doxygen's, I think this makes matters worse. This means
one would have to learn doxygen's many peculiarities before one could
contribute to Csound.

In short, I don't like doxygen: a bad implementation of a bad concept!

> Then Csound itself could scan the opcodlst table to build up 
> an internal documentation system, which could be printed
> out online using a "--help keyword" option

I could provide text files from the manual to implement a similar
scheme.

> online help browser in GUI versions of Csound.

You can render HTMLHelp and JavaHelp formats from my DocBook sources.


=====
-- 
kwconder at yahoo dot com

__________________________________
Do you Yahoo!?
Yahoo! Finance: Get your refund fast by filing online.
http://taxes.yahoo.com/filing.html