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

[Bayley, Alistair]

> From: libraries-bounces at haskell.org 
> [mailto:libraries-bounces at haskell.org] On Behalf Of Claus Reinke
> 
> That situation seems to be slightly embarrassing (if only because we
> are tempted to think that we have no time for the traditional README 
> and INSTALL files - after all, all darcs/cabal stuff is 
> self-explanatory, 
> isn't it, and has been discussed to death somewhere, hasn't 
> it, and the 
> library does the obvious thing, doesn't it, and isn't quite 
> ready for prime 
> time yet anyway, at which time it is going to be carved in stone and 
> documented thoroughly by a team of Pulitzer-price-winning authors?-)


I guess I should comment, as one of the Takusen authors.

Yes, this is embarrasing. We have made a number of assumptions which
Paul exposed:
 - 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)

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

It is nice to actually get some kind of feedback, even if negative. It
means we can make our library nicer to install and use, which hopefully
will encourage more users to install and use it...


>     + add a dedicated command "cabal", which does nothing more
>         than "runhaskell Setup", but is more memorable and suggestive

Did you mean an executable that comes with cabal or the compiler (i.e.
in ghc's bin), or something provided by the library author? From my POV
(as a library author) I could provide a cabal.bat (for Windows users)
and a cabal.sh (for everyone else), but that seems a bit messy.


>     - cabal/darcs/haddock are no replacement for minimal help texts:
>         cabal should require the existence of a README (darcs should
>         complain if there is a *.cabal, but no README..).

Yes. I will create one of these.


>     - 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

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.


>     - distributions are bare-boned:
> >         Option 2, Takusen, leads to a file listing, but no 
> downloadable package.

My fault for not providing a proper release. I'm still learning about
darcs, so the instructions in
 
http://www.haskell.org/haskellwiki/How_to_write_a_Haskell_program#Releas
es
are quite valuable.

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.

Alistair
*****************************************************************
Confidentiality Note: The information contained in this message,
and any attachments, may contain confidential and/or privileged
material. It is intended solely for the person(s) or entity to
which it is addressed. Any review, retransmission, dissemination,
or taking of any action in reliance upon this information by
persons or entities other than the intended recipient(s) is
prohibited. If you received this in error, please contact the
sender and delete the material from any computer.
*****************************************************************