On 24 July 2011 21:11, Joris Putcuyps <[email protected]> wrote: > On Sat, 23 Jul 2011 19:25:53 -0700 > Greg Weber <[email protected]> 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 [email protected] IvanMiljenovic.wordpress.com _______________________________________________ Haskell-Cafe mailing list [email protected] http://www.haskell.org/mailman/listinfo/haskell-cafe
