[Haskell-cafe] No fish, please

[Andrew Coppin]

>> This is basically the reason I asked. Currently Cabal assumes that
>> Haddock is the only tool of its kind. If somebody built a better
>> Haddock, you wouldn't be able to use it. (Unless you named the
>> executable "haddock" and made it accept the same command options.)
>
> Or maybe support for that tool would be integrated into Cabal and cabal and
> hackage.

I believe the correct approach would be to make it easy to configure 
Cabal to use any tool that might be produced one day, rather than 
integrating support for each specific tool that actually exists.

> But even while such a tool is not yet available, it would be worth thinkng
> about hackage offering the possibility to display other docs than haddock-
> generated ones.

Agreed.

>>> IF you do have better docs, host them somewhere, and put a link
>>> prominently in the .cabal file synopsis.
>>
>> That works, but it does mean that you can't read the documentation
>> offline.
>
> Make it downloadable?
> Include the docs in the package (extra-source-files: thedocs.tar.gz) and
> mention it in the package descripiton for a (less than optimal) workaround.

I thought extra-source-files: is only for Haskell source code?

>> (It also requires you to have somewhere to host, which not
>> everybody has.
>
> Haskellwiki, bitbucket, github, ...

BitBucket only works for Mercurial, GitHub only works for Git. The 
Haskell wiki might be OK, and has the nice advantage that other people 
can improve it. (Do we think Hackage will ever get a wiki per package?) 
The other thing is, you can bet as soon as you put your package's 
documentation on the wiki and link it from the package description, the 
URL will change at some point, breaking the link.

> Sure, a centralised documentation-hosting would have advantages over
> sprinkling over all the free project-hosting services, but the situation is
> not unbearably dire as is.

Granted. I'm just saying how it could be better.