Genuinely curious: do you think a `Synopsis.md` would be that much easier than the current system with a potentially long description in the .cabal file? I could see a case either way. Or maybe I'm just misunderstanding the distinction.

On the one hand, a separate file makes organization easier and markdown is a known quantity; on the other, it seems functionally equivalent to what we *can* do now albeit with Haddock syntax and in a file full of other details.

I could see why a file would be easier, and maybe that's enough to encourage more people to write one. We could even have .cabal just render the existing README file or something! On the other hand, that would take some effort and sometimes using Haddock markup and sometimes using markdown would be confusing.

Maybe we could have a guerrilla campaign of pull requests adding examples and a bit of explanation to every package you like that doesn't have them... That could also be a good way for beginners who want to contribute to start.

On Mon, Sep 15, 2014 at 10:40 AM, Michael Snoyman <michael@snoyman.com> wrote:

On Mon, Sep 15, 2014 at 8:38 PM, Richard Lewis <richard@rjlewis.me.uk> wrote:
Hi there,

If any of you have ever used CPAN you may
agree with me that the synopsis sections
customarily included in each package's POD
are generally invaluable for getting a quick
overview of how to use the facilities
provided by that package.

I wonder if we might be able to encourage
the Hackage community to do something
similar? Perhaps in the cabal description
authors could include a synopsis with a
few code examples?

Obviously, I ought to start the ball rolling but
I don't actually have any code published on
Hackage.

Any thoughts?

Richard
--
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Richard Lewis
@lewisrichard
http://web.rjlewis.me.uk/
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe

I'd love to see it work similar to the new changelog feature. Imagine if you could add a `Synopsis.md` file to your cabal sdist, and Hackage rendered it to HTML and displayed it?

Michael

_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe