a cabal/database lib experience (was: [Haskell-cafe] Trivialdatabase access in Haskell)

[Paul Moore]

On 12/12/06, Claus Reinke <claus.reinke at talk21.com> wrote:
> >> if you're using Haskell at all, you *are* the Haskell community.
>
> > [..lots of "I searched, I found, I tried, I got this error, I thought,
> >    I tried this workaround, I got to this point, now I'm stuck here..]
>
> I just wanted to comment that I find this kind of "experience report"
> very helpful, especially if someone does not give up at the first hurdle,
> and goes through the trouble of writing up all the frustrating steps and
> thoughts rather than summarizing ("it didn't work"/"I got it to work
> after some fiddling") - thanks!

Thank you! That's exactly the sort of report I was trying to give,
although (from my point of view) it's pretty hard to report this sort
of thing without feeling like you're giving a complaining and
ungrateful impression. It's nice to have the reassurance that I got my
message across.

On 12/12/06, Bayley, Alistair <Alistair_Bayley at invescoperpetual.co.uk> wrote:
> Yes, this is embarrasing. We have made a number of assumptions which
> Paul exposed:

It's hardly embarrassing - as Claus pointed out, the developers of any
package are *always* too close to the problem to see this sort of
issue.

>  - users should know to do darcs get, then runhaskell Setup.hs
> configure/build/install
>  - users should know to look for Haddock docs
>  - users should know how to look for and install dependent libraries
> (Cabal-1.1.6.1, in this case)

Yes, those are probably the key ones I tripped up on.

> If you're an experienced Haskell programmer then these assumptions are
> valid, so yes, we do need to do more for the novice.

One thing that (from my POV as a Windows user) helped enormously in
the Python community was adding the ability to distutils (their Cabal
equivalent) to build Windows binary installers. With that, it became
relatively easy for developers to package up binaries of their
libraries, which made the Windows experience a simple "download and
run" one.

I've no idea if that is a practical or useful goal for Cabal, and I
anticipate it being a long time before I'm at a level of understanding
where I could help in implementing it, but it may be something to
think about.

> >     - sample code for "trivial queries" (aka, I know about
> > databases, but
> >         I need to see the way this particular library handles
> > things, so that I
> >         can figure out whether it is the right one for me) is
> > not obvious to find
>
> We have made a reasonable effort in Takusen to document the API
> extensively, and give example code. The problem seems to be that the
> documentation is too well hidden:
>   http://darcs.haskell.org/takusen/doc/html/Database-Enumerator.html

Yes, I suspect that's the case.

> The best thing I can think of now is to put a reference to this in the
> README file. Any other ideas? I wanted to keep the documentation in
> Haddock (so that it stays close to, and hopefully consistent with, the
> source) but maybe that's not the best idea for this kind of
> documentation, which is really a HOW-TO manual.

Something as simple as "here's how to issue a query and print the
results" in the README would have been enough for me. When I get to
that point, I'll write a few lines and let you see what you think.

> If you have any further Takusen-specific questions, don't hesitate to
> contact me. Also, if you're having trouble installing or chasing down
> dependent libraries then I should be able to help.

Thanks for the offer. As others have pointed out, the level of help
available from "the community" is excellent - it's just that needing
to ask for help puts off those of us who work on a "let's just play
with this Haskell stuff while my backup runs" basis :-)

The backup has finished now, so I must run. Thanks again!
Paul.