[Haskell-cafe] Synopsis vs Description vs README (was: is it normal for docs to be pending for 24 hours?)
Herbert Valerio Riedel
hvriedel at gmail.com
Mon Nov 14 15:23:14 UTC 2016
On 2016-11-13 at 18:04:51 +0100, Michael Snoyman wrote:
> I regularly get complaints of "why don't you do X," where X is a
> significant amount of extra work. Writing up dual descriptions in both
> README.md and cabal description fields is a prime example, and something I
> argued very hard for on Hackage.
> I'm disappointed with the way the description is displayed; I'd have
> much preferred that the README.md files I write would have been used.
Maybe the reasoning behind this wasn't explained well enough, so let me
The three seemingly overlapping parts
serve three different purposes and have different technical properties
(and you find a very similar 3-part division in e.g. Debian's packaging
a) the synopsis is a single-line short title which `cabal list` or
search results show as a single line; it should give a first rough
idea what the package is about in order to decide whether you want
to look closer at b)
b) this is like a paper abstract, giving you the gist of what a package
is about, and wether to give it a try; it's displayed by e.g.
`cabal info somepkg` or at the top of Hackage packages; this should
contain enough information to know the feature scope of the package
in order to decide whether to continue looking at c) and/or the
The description field is typically just a few paragraphs, and
ideally fits on a terminal screen; you don't want it to be too long,
as it's supposed to be an elevator-pitch for your package.
c) Finally, the README is for additional information which isn't
suitable for the description-field (like e.g. more in-depth
explainations, history about package (NB: not the changelog), code
examples, installation instructions, information about contributing
etc...); also, since the README is quite easily rather large is
*not* included in the 01-index.tar
So while there may appear to be some overlap between b) and c), it's
really not that much; and there's precedent for doing it this way.
Also note there's a technical boundary between b) & c) in that a) & b)
are indexed; i.e. by being inside the `.cabal` meta-data, they are
contained in 01-index.tar, and thus are available to external tooling
for text-indexing; Moreover, the synopsis/description fields are part of
the meta-data that gets registered with ghc-pkg, so that information is
available via `ghc-pkg` as well.
Whereas in order to access/search c) you'd currently have to download
the source-tarball (or bypass hackage-security, and access hackage.h.o's
web-services directly but that would come with its own technical
problems by doing so). So READMEs are rather out-of-band information,
and should be treaated as such.
> If you look on resourcet on Hackage, for example, there's a much more
> thorough description of the package at the bottom. I think this was a
> major mistake, but there's not much I can do about it.
Btw, you can modify the current `description` (as well as the
`synopsis`) field via .cabal editing on Hackage if you want to set a
more meaningful description for the benefit of e.g. `cabal info resourcet`
or also Hackage users (since the README is *not* indexed bythe Hackage
More information about the Haskell-Cafe