[Haskell-cafe] Github support for cabal files

[Joris Putcuyps]

On Sat, 23 Jul 2011 10:47:18 +0000
Ivan Lazar Miljenovic <ivan.miljenovic at gmail.com> wrote:

> 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.
> 
Hello

About your first point, I'm aware of that. It would have been
nice if .cabal and haddock used markdown, this is very popular, thanks
to pandoc. Then generating html, pdf, texinfo, ... would be very easy.

When you create a package in github you add a short description,
probably the same as the synopsis from .cabal. The description
from .cabal could still go in the README.

I agree that the README will probably contain more than just a
description, it is more like a "man page". Having this also parsed by
haddock for the html docs would also make me content.

Joris