On 16 September 2014 14:13, Michael Snoyman <michael@snoyman.com> wrote:
>
>
> On Tue, Sep 16, 2014 at 2:36 AM, Mateusz Kowalczyk <fuuzetsu@fuuzetsu.co.uk>
> wrote:
>>
>> On 09/15/2014 09: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.
>>
>> The parser has been improved and the escaping rules have been made
>> saner. You shouldn't have real problems since 2.14 release which came
>> out along with GHC 7.8.1. If you have problems with escaping then I'd
>> like to hear about it on the issue tracker rather than stumbling upon
>> complaints on café.
>>
>
> I ran into these issues over four years ago, discussed them at the time, and
> the general consensus I got at the time was that these issues weren't going
> to be resolved, so I didn't follow up. I've seen nothing in recent release
> announcements to imply otherwise. To test this out, I put together a simple
> demonstration of a Hamlet synopsis in Markdown[1], and then converted it via
> Pandoc to Haddock[2]. I copied that Haddock content into a cabal file's
> description, then indented it, ran cabal haddock, and got:
>
>     cabal: hamlet.cabal:30: unexpected span: "!"
>
> For some reason, the trailing exclamation point is rejected by cabal. I
> tried removing the exclamation point, and it *did* generate content.
> However, all of the content was on the same line, because I needed to add
> periods between each block to deal with cabal's description parsing. After
> adding those periods, things *mostly* worked, except that my first code
> sample came out as:
>
>    <p>Hi, my name is #
>
> Notice how the {name} portion has been stripped away. So I see a number of
> ways that this current situation for writing synopses is inferior:
>
> 1. Far more people are comfortable writing Markdown than writing Haddock,
> even those of us who write a lot of Haddock. Tooling support for editing
> Markdown is also superior.
> 2. Having the synopsis in a separate file means that it's easy to give a
> link to the file on Github and get readable docs, which is *not* the case
> with linking to a cabal file.
> 3. I don't have to go through any preprocess step to convert from Markdown
> to Haddock if that's the way I want to edit.
> 4. Putting the synopsis in the cabal file means we have to deal with cabal
> rules *in addition to* Haddock rules, such as the periods between blocks and
> not having an exclamation point at the end of the line[3].
> 5. On top of all that, Haddock still can't handle the documentation I want
> to write for Hamlet, to demonstrate #{variable} interpolation.
>
> So again, I really like the idea of doing the same thing for synopses as we
> have already for changelogs.

I would instead prefer to have a Github-esque README that might be
displayed on Hackage pages, and keep the synopsis as a slightly longer
version of the description.  The description field is used by various
Cabal-based package creation tools for various *nix distributions to
provide a short blurb about what a package is, whereas the short guide
as to how to use a package is better suited to a README.