<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Sep 17, 2014 at 12:10 AM, Richard Lewis <span dir="ltr"><<a href="mailto:richard@rjlewis.me.uk" target="_blank">richard@rjlewis.me.uk</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">So there's clearly an important technical hurdle to be overcome for<br>
this: what markup language is to be used?; and where should the<br>
synposis be stored?<br>
<br>
But I can't help thinking that the real work is in getting the<br>
synopses written. Encouraging package authors/maintainers to add them<br>
to their own packages is one possible way forward.<br>
<br></blockquote><div><br></div><div>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:<br><br></div><div>1. They're serving double duty, both in the project repository and on Hackage.<br></div><div>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.<br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
At Mon, 15 Sep 2014 11:28:38 -0700,<br>
<span class="">Tikhon Jelvis wrote:<br>
<br>
> Maybe we could have a guerrilla campaign of pull requests adding<br>
> examples and a bit of explanation to every package you like that<br>
> doesn't have them... That could also be a good way for beginners who<br>
> want to contribute to start.<br>
<br>
</span>Another, as Tikhon suggests, would be for others to write them and<br>
send pull requests (or whatever) to the maintainers.<br>
<br>
At Mon, 15 Sep 2014 20:10:18 -0400,<br>
<span class="">Dominick Samperi wrote:<br>
<br>
> I think this is a great idea, but it probably needs a complementary<br>
> "nudge" if it is going to have a significant impact. This could be<br>
> incorporated into the package submission process where the submitter<br>
> runs a final check and is warned when examples are not provided for<br>
> exported functions (unless an "opt out" flag is turned on for<br>
> functions that have "obvious" semantics).<br>
<br>
</span>And yet another, as Dominick suggests, is effectively to require a<br>
synposis when a package is submitted. In CPAN, it's just become part<br>
of the culture, but it's also not required and you do find packages<br>
without a synposis.<br>
<br>
If there's interest, I'd like to solicit some discussion on this part<br>
of the proposal on this thread...<br>
<br>
There may also be a potentially significant difference between<br>
Hackage/Haskell and CPAN/Perl: most CPAN packages tend to be quite<br>
small and specific in their purpose and consequently have just a few,<br>
simple common use cases which suit a synposis very well. Hackage<br>
packages, on the other hand, are quite often more broad in their<br>
scope, often comprising many modules. Also, Perl has only one<br>
semantics for organising code at the finest level: sequential,<br>
imperative statements. In Haskell, some packages actually define whole<br>
coding styles. As a result, it's always pretty obvious how to write a<br>
few isolated lines of Perl code, but not necessarily so with Haskell<br>
code. Anyway, I'm sure all this can be overcome, and/or argued<br>
against.<br>
<span class=""><br>
Richard<br>
--<br>
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-<br>
Richard Lewis<br>
</span>j: <a href="mailto:ironchicken@jabber.earth.li">ironchicken@jabber.earth.li</a><br>
@: lewisrichard<br>
<a href="http://www.richardlewis.me.uk/" target="_blank">http://www.richardlewis.me.uk/</a><br>
<div class="HOEnZb"><div class="h5">-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-<br>
_______________________________________________<br>
Haskell-Cafe mailing list<br>
<a href="mailto:Haskell-Cafe@haskell.org">Haskell-Cafe@haskell.org</a><br>
<a href="http://www.haskell.org/mailman/listinfo/haskell-cafe" target="_blank">http://www.haskell.org/mailman/listinfo/haskell-cafe</a><br>
</div></div></blockquote></div><br></div></div>