[Haskell-cafe] Hackage package "synopsis" sections

[Mike Izbicki]

One problem with using the README file as the synopsis is that a lot
of the standard information in a README file would be out of place
when displayed on hackage.  For example, many READMEs have:

* installation instructions
* a list of contributors
* a list of known bugs
* how to contribute bug reports
* licensing information

Some of this information is very out of place on hackage, some of it
is duplication of the standard fields in the cabal file, and some of
it is just not things that a new user needs to see on their first
visit to the package documentation.

Maybe this could be solved by having the name of the synopsis file as
a variable the author can specify.  It can default to README(.md) but
can be overridden to something else for authors who choose to do so.

On Tue, Sep 16, 2014 at 11:20 PM, Mike Izbicki <mike.izbicki at gmail.com> wrote:
> One problem with using the README file as the synopsis is that a lot
> of the standard information in a README file would be out of place
> when displayed on hackage.  For example, many READMEs have:
>
> * installation instructions
> * a list of contributors
> * a list of known bugs
> * how to contribute bug reports
> * licensing information
>
> Some of this information is very out of place on hackage, some of it
> is duplication of the standard fields in the cabal file, and some of
> it is just not things that a new user needs to see on their first
> visit to the package documentation.
>
> Maybe this could be solved by having the name of the synopsis file as
> a variable the author can specify.  It can default to README(.md) but
> can be overridden to something else for authors who choose to do so.
>
> On Tue, Sep 16, 2014 at 8:58 PM, Michael Snoyman <michael at snoyman.com> wrote:
>>
>>
>> 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
>>
>>
>>
>> _______________________________________________
>> Haskell-Cafe mailing list
>> Haskell-Cafe at haskell.org
>> http://www.haskell.org/mailman/listinfo/haskell-cafe
>>