[Haskell-cafe] Re: a cabal/database lib experience

[Claus Reinke]

>> absolutely, this has occurred to me too.  There should be a stanard Cabal 
>> README file, and Don's mkcabal tool could drop it in the tree.
> 
> This occurred to me too. My current plan for mkcabal is that it creates:
> 
>    foo.cabal
>    Setup.lhs
>    README
>    LICENSE
> 
> based on a series of interactive questions, or command line args.

is mkcabal going to be a standard part of cabal installations?

btw, here is some suggested text for the useful "how to write.." page you 
started (I know it is a wiki, but I don't want to mess up the page at this point;-).

thanks,
claus

-------------------------------------------- 0. The intended user experience

When Haskell programmers go out in search of existing functionality, be it a
library, a tool, or an application, the intended approach is roughly this:

1 visit haskell.org,
2 find the library/program they are looking for 
    (if not found, try mailing list; if it is hidden, try improving haskell.org;
     if it does not exist, try contributing code/documentation/requirements/..) 
3 download
4 install
5 enjoy

but each of these steps is endangered by several potential road blocks, and
code authors can do a lot to help code users avoid such blocks. Even if steps 
1/2 are successful, and ensuring step 5 is the main concern of code authors 
and users, it is often steps 3/4 that get in the way:

- which is the latest version? what state is it in? is it still maintained/in use?
- what are its aims? where is the documentation?
- which is the right version for given OS and Haskell implementation?
- how is it packaged, and what tools are needed to get and unpack it?
- how is it installed, and what tools are needed to install it?
- how do we avoid IDR (infinite dependency recursion)?
- how do we provide/acquire the knowledge and tool-chains needed?

There is a well-established tradition for communicating the answers to 
these questions: the README text file, placed in a prominent position
at the code's location (these days often accompanied, but not replaced,
by a more extensive web page). But as other communities, the Haskell
community has Haskell-specific answers to many of these questions,
independent of the particular Haskell code to publish. 

This document is all about how to publish your Haskell code in such a 
way as to make the Haskell code users' experience as smooth as possible. 
Until there is a version of this text targetted more specifically at code users, 
they might find it helpful to browse this page for insights into the Haskell 
code authors' mind- and tool-set.