[Haskell-cafe] Github support for cabal files

[Joris Putcuyps]

On Sat, 23 Jul 2011 19:25:53 -0700
Greg Weber <greg at gregweber.info> wrote:

> I think the haddock description field is a great barrior to
> documentation. I don't want to clutter my cabal file with lengthy
> documentation. Michael Snoyberg and I could not figure out how to
> document the Hamlet syntax because there is no way (as far as I know)
> to have literal unescaped, uninterpreted text. [1]
> When I go to a github repo, I expect that I can scroll down to the
> README and I will get a good overview. When I go to hackage, I expect
> nothing more than a synopsis, and I hope I can follow several links
> to find the information I am looking for.
> 
> It is suggested that the description field should point to a top level
> module with all the documentation, but although haddock is good for
> documenting code, it is not an ideal overview style, and not all
> packages lend themselves well to having one top-level module.
> 
> I would like a description field that just points to an external
> (README) file. Cabal could either use the pandoc library, or to avoid
> that dependency directly it could use the pandoc executable (that
> would have to be installed first by those of us that want this
> feature). Alternatively it could just allow an html file for the
> description and make me responsible for writing a script that runs
> pandoc and then invokes sdist.
> 
> [1] http://hackage.haskell.org/package/hamlet
> 
The cabal file should be compact, and quite often the
description field is very lengthy.
I would like it alot if I could reference a README.??? (pandoc
compatible extension) from cabal. Then it would be compatible with
github and give me more information in my haddock html pages which
were generated by `cabal haddock`.