cabal user's guide comment

[Duncan Coutts]

On Sat, 2011-05-14 at 11:22 -0400, Jake Penton wrote:
> Greetings. 
> 
> What is a package?
> 
> The reason I ask this question is stated below. If I am posting to the
> wrong list, let me know. Also, my tone by be slightly abrasive: I am
> rather frustrated. If I have misread the Cabal user's guide, or am
> otherwise have my head up my butt, feel free to let me know. Also if I
> can help (which I doubt, as a beginner) tell me how.

This is very timely. I'm currently rewriting the user guide.

> My work involves becoming reasonably accomplished in haskell, at which
> I am a relative beginner. As it is important to be able to use a
> language in its natural ecosystem, I sat down yesterday to study
> packages, Cabal, and ghc-pkg.  I found this to be rather hard going,
> mostly because of the documentation - particularly the Cabal user's
> guide. I appreciate the fact that one of more people went to
> considerable effort to compose the user's guide, which I get for free.
> However, I feel that editorial improvements are in order.

You're right, it's very dated and presents info in an unhelpful order.

> I find the user's guide unhelpful for several reasons, but I shall
> only point out one thing in this post: The user's guide fails to
> provide, early on, information that is IMHO essential to a clear
> understanding of cabal: What IS a package, i.e. what does the physical
> implementation of a package look like?

Here's my current introduction, let me know what you think:

http://code.haskell.org/~duncan/cabal/user-guide/#introduction

I've also got a quickstart for creating packages, which is not quite
done but here it is anyway:
http://code.haskell.org/~duncan/cabal/user-guide/developing-packages.html#quickstart
(down to but not yet including the bit on package dependencies)

I'll post updates to to this list when it's ready for some feedback.
Particularly as a beginner and with strong opinions on the current state
of the user guide I'd most appreciate your feedback.

Any more notes or comments on what you would like, or woulh have liked
to know would be helpful to me as I work on the new introductory
sections.

> The user's guide dances all around this. It mentions the "aims" of
> cabal, that it provides interfaces, that "developers write packages",
> that "users install Cabal packages", etc. Under the subheading
> "Packages" the user's guide says that a "package is the unit of
> distribution", etc. Ok....
> 
> The first hint that a package might possibly be implemented as a
> hierarchy of directories/files is under the subheading "Creating a
> package", which makes reference to adding files to the root directory
> of a package. If that is what a package is (which I remain unsure
> about) this is too little information, and far too late. To add to the
> confusion, the examples of packages given in this subsection are NOT
> examples of packages. They are displays of some kind of file or other
> - a package description file, or something - whatever a .cabal file
> might be.

So you mean in the sense that the implementation of a package consists
of a bunch of files, .hs source files etc + these special packaging
files (the .cabal and Setup.hs).

So you want to know what the layout of these should be, or how module
names match file names etc? It's certainly true that we don't talk about
that, partly because there are not many restrictions, though there is
the assumption that apart from package dependencies all the files are
self-contained and live under one package root directory.

Is it enough just to say this an give an example?

>  In summary, I think the user's guide stands in need of a substantial
> rewrite.

Yes, that was my analysis too. That and that I/we have all been putting
it off for too long.

Duncan