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.