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 mailto:tikhon@jelv.is> wrote:

Genuinely curious: do you think a `Synopsis.md` would be that much easier than the current system with a potentially long description in

Hi all, Using Markdown would be a great idea. And, if Haddock were to support Markdown, and packages were migrated gradually to that, the inconsistency would disappear (eventually). IIRC, adding Markdown to Hadock was suggested on this list before, and the major argument against it was that Markdown didn't have a standard. Now, it has one, called CommonMark[1]. Barring any (further) copyright issues with the name, that looks to be a great step forward for Markdown. [1]: http://commonmark.org Regards, Jonathan Paugh On 09/15/2014 03:11 PM, Michael Snoyman wrote: 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

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