RE: a cabal/database lib experience (was: [Haskell-cafe] Trivialdatabase access in Haskell)
From: [EMAIL PROTECTED] [mailto:[EMAIL PROTECTED] 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. * ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: a cabal/database lib experience (was: [Haskell-cafe] Trivialdatabase access in Haskell)
On 12/12/06, Claus Reinke [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: a cabal/database lib experience (was: [Haskell-cafe] Trivialdatabase access in Haskell)
On 12/12/06, Donald Bruce Stewart [EMAIL PROTECTED] wrote: bulat.ziganshin: there is a great wikipage on creating your own library, thanks to Donald, who is started it. but there is no even simpler page about using libraries. while we don't have cabal-get it will be great to setup such page The wiki can be edited by anyone! Start now! My plan is to write up what I end up doing (plus some notes on my false starts, if they seem helpful) on the wiki. I'll probably add a new page off the Libraries and Tools page - does that sound reasonable? I have to admit that I haven't found the obvious place on the wiki for this yet - I'm familiar with wikis in general, but the structure of the Haskell wiki is a bit hard to get to grips with. That's not a very helpful comment, because I can't articulate *why* I feel this :-( As a data point, the old Haskell wiki felt a bit easier to navigate - maybe because it was less structured in some way. Paul. ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: a cabal/database lib experience (was: [Haskell-cafe]Trivialdatabase access in Haskell)
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) and there you have the beginnings of your README file!-) If you're an experienced Haskell programmer then these assumptions are valid, so yes, we do need to do more for the novice. the difference, as far as it is relevant for getting going, is often just context, which can be rectified by surprisingly small steps, such as collecting the assumptions in one obvious-to-find file. + 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 yes, part of the cabal infrastructure, not something from the library author. as Simon has pointed out, cabal-setup is going to do the job, and with a more descriptive name. thanks, claus ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: a cabal/database lib experience (was: [Haskell-cafe]Trivialdatabase access in Haskell)
On 12/12/06, Claus Reinke [EMAIL PROTECTED] wrote: the difference, as far as it is relevant for getting going, is often just context, which can be rectified by surprisingly small steps, such as collecting the assumptions in one obvious-to-find file. Indeed. I can now confirm that it's *not* hard to get takusen set up - it's just a bit hard to find out it's not hard :-) Paul ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: a cabal/database lib experience (was: [Haskell-cafe]Trivialdatabase access in Haskell)
[trimmed replies] On 12/12/06, Paul Moore [EMAIL PROTECTED] wrote: On 12/12/06, Claus Reinke [EMAIL PROTECTED] wrote: the difference, as far as it is relevant for getting going, is often just context, which can be rectified by surprisingly small steps, such as collecting the assumptions in one obvious-to-find file. Indeed. I can now confirm that it's *not* hard to get takusen set up - it's just a bit hard to find out it's not hard :-) If you generalize from takusen there, I think you'll understand a lot about Haskell :-) Cheers, Kirsten -- Kirsten Chevalier* [EMAIL PROTECTED] *Often in error, never in doubt Dare to be naive.--R. Buckminster Fuller ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
