[Haskell-cafe] Hackage package "synopsis" sections

[Michael Snoyman]

On Tue, Sep 16, 2014 at 7:24 AM, Ivan Lazar Miljenovic <
ivan.miljenovic at gmail.com> wrote:

> 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.
>
>
I'm not implying that we should get rid of any existing functionality:
cabal fields should remain exactly as they are now. I was proposing that,
in addition, if a Synopsis.md file is present, that it be displayed on the
Hackage page.

But now that you bring up Github READMEs, that's clearly the right name for
this proposal, so consider it amended: if a README or README.md file is
present, that's what should be used.

Michael
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20140916/37abb558/attachment.html>