On Wed, Sep 17, 2014 at 12:10 AM, Richard Lewis <richard@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@jabber.earth.li
@: lewisrichard
http://www.richardlewis.me.uk/

-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe