Re: [Haskell-cafe] Hackage package "synopsis" sections

I've had cases where some code I wanted to put in an example could not be expressed in haddock due to escaping rules. I would much rather be able to write a synopsis in markdown, or asciidoc, or HTML, rather than haddock markup. On Monday, September 15, 2014, Tikhon Jelvis wrote:

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 javascript:_e(%7B%7D,'cvml','michael@snoyman.com');> wrote:

...

On Mon, Sep 15, 2014 at 8:38 PM, Richard Lewis javascript:_e(%7B%7D,'cvml','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 javascript:_e(%7B%7D,'cvml','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 javascript:_e(%7B%7D,'cvml','Haskell-Cafe@haskell.org'); http://www.haskell.org/mailman/listinfo/haskell-cafe