[Haskell-cafe] Hackage package "synopsis" sections

[Michael Snoyman]

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> 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
>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20140915/d6a72a1c/attachment-0001.html>