[Haskell-cafe] Github support for cabal files

[Ivan Lazar Miljenovic]

On 23 July 2011 10:35, Joris Putcuyps <joris.putcuyps at gmail.com> wrote:
> Hello everybody
>
> I'm looking for a way to avoid having two files with almost the same
> information on github: README.markdown and package.cabal.
>
> As far as I can tell, a new github README parser[1] can be written,
> but it only supports README files with different extensions and requires
> either ruby or a script which converts stdin into html.
>
> Another solution would be that haddock supports a README file, just
> like github, as the index.html of the cabal package.
>
> Github houses a lot of cabal packages so more people could benefit from
> this solution.
>
> Greetings
>
> Joris
>
> [1]: https://github.com/github/markup

I don't have any of my packages on Github, but I'd like to point out a
few things:

1) The description field in a .cabal file uses Haddock syntax (and a
slightly mangled one at that, what with not being able to have blank
lines) rather than Markdown.

2) I see the package description and a README as being two different
things: the description gives you an overview of what a package
is/does and why you'd want to use it, the README gives you more
information about _how_ you'd use it.  There is some overlap, but it's
usually in the sense that the description in the .cabal file as being
a subset of the README.

That said, it would be nice if Cabal supported explicit fields for
README, TODO, ChangeLog, etc. files rather than banging them all in
Extra-Source-Files.

-- 
Ivan Lazar Miljenovic
Ivan.Miljenovic at gmail.com
IvanMiljenovic.wordpress.com