[Haskell-cafe] Hackage package "synopsis" sections

[Tikhon Jelvis]

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>
wrote:

>
>
> On Mon, Sep 15, 2014 at 8:38 PM, Richard Lewis <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
>> 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
> http://www.haskell.org/mailman/listinfo/haskell-cafe
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20140915/50ddf7a9/attachment.html>