[Haskell-cafe] Github support for cabal files

[Ivan Lazar Miljenovic]

On 24 July 2011 21:11, Joris Putcuyps <joris.putcuyps at gmail.com> wrote:
> On Sat, 23 Jul 2011 19:25:53 -0700
> Greg Weber <greg at gregweber.info> 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 at gmail.com
IvanMiljenovic.wordpress.com