[Haskell-cafe] Hackage package "synopsis" sections

[Jonathan Paugh]

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:
> 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 <tikhon at jelv.is
<mailto:tikhon at 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
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 at snoyman.com
<javascript:_e(%7B%7D,'cvml','michael at snoyman.com');>> wrote:
>
>
>
>         On Mon, Sep 15, 2014 at 8:38 PM, Richard Lewis
<richard at rjlewis.me.uk
<javascript:_e(%7B%7D,'cvml','richard at 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 at haskell.org
<javascript:_e(%7B%7D,'cvml','Haskell-Cafe at 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 at haskell.org
<javascript:_e(%7B%7D,'cvml','Haskell-Cafe at haskell.org');>
>         http://www.haskell.org/mailman/listinfo/haskell-cafe
>
>
>
>
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
>