I think the haddock description field is a great barrior to documentation. I don&#39;t want to clutter my cabal file with lengthy documentation.<div><div>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]</div>

<div>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.<br>

<div><br></div><div>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.</div>

<div><br></div><div>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.</div>

<div><div><br></div><div>[1] <a href="http://hackage.haskell.org/package/hamlet">http://hackage.haskell.org/package/hamlet</a></div></div></div></div>