[Haskell-cafe] Hackage package "synopsis" sections

[Ivan Lazar Miljenovic]

On 16 September 2014 14:13, Michael Snoyman <michael at snoyman.com> wrote:
>
>
> 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.

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.

>
> 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
>
>
>
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
>



-- 
Ivan Lazar Miljenovic
Ivan.Miljenovic at gmail.com
http://IvanMiljenovic.wordpress.com