[Haskell-cafe] Hackage package "synopsis" sections

[Michael Snoyman]

On Tue, Sep 16, 2014 at 2:36 AM, Mateusz Kowalczyk <fuuzetsu at 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.

Michael

[1] http://lpaste.net/111103
[2] http://lpaste.net/111104
[3] For the record, I was completely unaware of this limitation, and
stumbled upon it by accident when putting together this example.


> I think just about the only thing nowadays that might surprise people is
> that tokens stretch over newlines but this is by design, especially
> considering one can embed code.
>
> > I would much rather be able to
> > write a synopsis in markdown, or asciidoc, or HTML, rather than haddock
> > markup.
> >
>
> As I mention on the other e-mail, you can now use pandoc to achieve
> this. If people really care then it should not be difficult to
> co-ordinate with cabal + Hackage and make it parse your favourite format
> and splice it into synopsis.
>
> I'd quite like the complaints about the existing Haddock markup, the
> rules are pretty damn close to what Markdown uses.
>
> --
> Mateusz K.
> _______________________________________________
> 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/20140916/8c9498a9/attachment.html>