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`. _______________________________________________ Haskell-Cafe mailing list [email protected] http://www.haskell.org/mailman/listinfo/haskell-cafe
