Getting haddock docs links right
Esa Ilari Vuokko
eivuokko at gmail.com
Thu Aug 9 09:54:37 EDT 2007
There appears to be big hole in how we handle haddock generated docs,
with ghc, at least in Windows. I am very much not expert on this, so
please let me know if any of this is wrong!
I think the problem is that every stage on current infrastructure
assumes they know where docs are, and are going to be. In a matter of
fact, they do not.
* haddock assumes
* either absolute locations, or
* docs bunched together.
* Cabal just redirects the information from ghc-pkg and commandline.
* Ghc build/install assumes docs are crammed into it's installation
directory, but at least has $topdir functionality to defer decision
making a bit.
Here I have few situations that are currently broken, at least when
using packages as generated by cabal+cabal2wix.
* User install ghc in different location than c:\ghc\ghc-6.6.1
- all links to base and other bundled packages are broken.
* User has different localisation or drive for Program Files
than packager - all links to other non-ghc-bundled packages
(And when cabal2wix supports non-admin installs:)
* User-installed packages - all links to user-installed packages
How can we solve this?
* installing packages in common directory structure similar to
docs bundled with ghc. (Cabal's --html-location can achieve this)
* This directory structure contains no package versions?, so only
one version of package can be installed (patch haddock).
* non-admin packages cannot refer correctly to admin packages,
as docs would be in different dirs (fix: copy files around as
* No links from non-ghc-bundled packages to, well, anything.
* Solves nothing, except no frustrating broken links - let
them assume we can't do it.
* Duncan suggested using html entities - it would require writing
out small index at post-install. Anyone know if this is possible
and reliable technique?
* Reinstalling package in a different location might leave
dependent packages with broken links.
* Using a post-install step to rewrite links.
* Seems fragile.
* Installs require even more logic.
* Writing a local web server that does all the correct uri mapping
* Rather heavy, and additional dependency.
* Your idea here!
More information about the cabal-devel