[Haskell-cafe] Github support for cabal files

[Greg Weber]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20110723/73698e99/attachment.htm>