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 try again. The three seemingly overlapping parts a) synopsis b) description c) README serve three different purposes and have different technical properties (and you find a very similar 3-part division in e.g. Debian's packaging and others): 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 Haddocks. 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 search service).