On Sat, 23 Jul 2011 10:47:18 +0000 Ivan Lazar Miljenovic wrote:

On 23 July 2011 10:35, Joris Putcuyps 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