Getting haddock docs links right

Esa Ilari Vuokko eivuokko at
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
  are wrong.

(And when cabal2wix supports non-admin installs:)

* User-installed packages - all links to user-installed packages
  are wrong.

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
     post-install step.)

 * 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
   for user.
   * Rather heavy, and additional dependency.

 * Your idea here!


More information about the cabal-devel mailing list