On 24 July 2011 21:11, Joris Putcuyps wrote:

On Sat, 23 Jul 2011 19:25:53 -0700 Greg Weber 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`.

Sure, that would be nice; question is, who's going to implement the necessary support in Cabal and Hackage at the very least? :p -- Ivan Lazar Miljenovic Ivan.Miljenovic@gmail.com IvanMiljenovic.wordpress.com