[haskell-art] trouble getting hsc3 to produce sound

[Brent Yorgey]

On Mon, Mar 16, 2009 at 11:16:54AM +1100, Rohan Drape wrote:
> hello brent,
> 
> just saw your post on planet haskell
> 
> > For example, here’s the documentation for pan2:
> 
> the unit generator documentation proper is not in haddock.  you don't
> want to read it in a browser because you want to be able to play &
> edit the examples.
> 
> did you read the "Help Files" section of the tutorial?

I did, but (a) hitting C-c C-h doesn't seem to work (it gives some sort
of error about "Wrong type argument: stringp, nil" and (b) it simply
didn't occur to me that the example files in the Help directory would
contain complete documentation for unit generators, and the Haddock
documentation wouldn't.

I don't mean to sound like I am complaining---I'm not.  hsc3 is
fantastic, and a lot of effort has obviously been put into the
documentation!  I'm just sharing my initial impression that the
documentation was not where I expected to find it, so I think there
can be some improvement along those lines.  When I try to learn about
a new Haskell library I usually look in two places for documentation:
(1) in the Haddock documentation on Hackage and (2) linked from the
library's web page, if there is one.  Adding something to the README
is good but doesn't necessarily help---if people install via
cabal-install (as I did) they will never see the README file, since
the tarball gets unpacked in some temporary location by cabal just
long enough to build and install the library.

I have a couple suggestions.  One is that some meta-documentation be
added to the Haddock documentation in Sound.SC3 pointing people to the
appropriate places to find further documentation.  I will actually
soon send along a darcs patch adding something along these lines, feel
free to use it if you think this is a good idea and you like what I've
written.  The other much longer-term suggestion is to include
everything currently in Help/UGen in the Haddock documentation as
well.  I could imagine a scheme where the files in Help/UGen are
automatically extracted from Haddock documentation, so there would be
no issues with keeping things in sync.  This is what I would do, but
of course, this is just my 2c.  And as I hinted in my blog post, I
certainly may be willing to do some of this sort of thing myself, at
some point in the future when I become more familiar with things.

Thanks again for the helpful response!

-Brent