From: libraries-bounces@haskell.org [mailto:libraries-bounces@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. *****************************************************************