[Haskell-cafe] Hackage package "synopsis" sections

[Michael Snoyman]

On Wed, Sep 17, 2014 at 12:10 AM, Richard Lewis <richard at rjlewis.me.uk>
wrote:

> So there's clearly an important technical hurdle to be overcome for
> this: what markup language is to be used?; and where should the
> synposis be stored?
>
> But I can't help thinking that the real work is in getting the
> synopses written. Encouraging package authors/maintainers to add them
> to their own packages is one possible way forward.
>
>
Actually, if we get the README support in place, I think it should be much
easier to get package authors to write synopses. Most projects have a
README file already, and getting it included in Hackage would now be a
one-line pull request (adding `extra-source-files: README.extension`). It
will hopefully be easier to get authors to elaborate on their READMEs then
because:

1. They're serving double duty, both in the project repository and on
Hackage.
2. It's trivial for outside developers to send pull requests against a
simple text file. I've received quite a few such contributions on projects
I maintain, even from people not ready to work on the code itself.


> At Mon, 15 Sep 2014 11:28:38 -0700,
> Tikhon Jelvis wrote:
>
> > 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.
>
> Another, as Tikhon suggests, would be for others to write them and
> send pull requests (or whatever) to the maintainers.
>
> At Mon, 15 Sep 2014 20:10:18 -0400,
> Dominick Samperi wrote:
>
> > I think this is a great idea, but it probably needs a complementary
> > "nudge" if it is going to have a significant impact. This could be
> > incorporated into the package submission process where the submitter
> > runs a final check and is warned when examples are not provided for
> > exported functions (unless an "opt out" flag is turned on for
> > functions that have "obvious" semantics).
>
> And yet another, as Dominick suggests, is effectively to require a
> synposis when a package is submitted. In CPAN, it's just become part
> of the culture, but it's also not required and you do find packages
> without a synposis.
>
> If there's interest, I'd like to solicit some discussion on this part
> of the proposal on this thread...
>
> There may also be a potentially significant difference between
> Hackage/Haskell and CPAN/Perl: most CPAN packages tend to be quite
> small and specific in their purpose and consequently have just a few,
> simple common use cases which suit a synposis very well. Hackage
> packages, on the other hand, are quite often more broad in their
> scope, often comprising many modules. Also, Perl has only one
> semantics for organising code at the finest level: sequential,
> imperative statements. In Haskell, some packages actually define whole
> coding styles. As a result, it's always pretty obvious how to write a
> few isolated lines of Perl code, but not necessarily so with Haskell
> code. Anyway, I'm sure all this can be overcome, and/or argued
> against.
>
> Richard
> --
> -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
> Richard Lewis
> j: ironchicken at jabber.earth.li
> @: lewisrichard
> http://www.richardlewis.me.uk/
> -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
> _______________________________________________
> 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/20140917/77d44a66/attachment.html>