[Haskell-cafe] No fish, please

[Daniel Fischer]

On Wednesday 18 May 2011 23:39:47, Andrew Coppin wrote:
> On 18/05/2011 05:28 AM, Don Stewart wrote:
> > I'm intrigued by  the idea of Hackage docs that don't use Haddock.
> 
> 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.
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.

> 
> Also, Haddock generates API reference documentation. It does not really
> support generating tutorials, introductions, HOWTOs, and all the other
> types of useful documentation that a project ought to have.
> 
> > 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.

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

Haskellwiki, bitbucket, github, ...

> Hackage provides hosting for the code itself, but you can
> only host documentation there if it's Haddock.)

Yes, hackage is code hosting and not tutorial etc. hosting. Maybe 
integrating that would be a good thing, but even so, there are feasible 
ways of making additional documentation available.
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.