haddock-2.3.0 literate comments discarded from .lhs input

[Duncan Coutts]

On Wed, 2009-05-27 at 21:17 +0100, Duncan Coutts wrote:

> To be clear, here's what I'm imagining:
> 
> blah/package.conf
> blah/lib/foo-1.0/libfoo-1.0.a
> 
> and package.conf would contain foo-1.0 with paths looking like
> "$dbdir/lib/foo-1.0". That is, we interpret $dbdir (or whatever var name
> we agree on) as being "blah/" because that's the dir containing the db.

Ian has convinced me that we do actually need two vars. We need one for
file paths and one for urls.

For example, consider
haddock-html: $pkgroot/doc/ghc-6.10.1/libraries/base

This is supposed to expand to a URL like
file:///usr/share/doc/ghc-6.10.1/libraries/base

or something similar on Windows. It's especially important that it is a
file:// url on windows because normal windows paths are not absolute
urls like unix ones are.

Now if we've only got one var like $pkgroot then we cannot encode
file:///usr/share/doc/ghc-6.10.1/libraries/base
and also be able to interpret it relative for tools that grok the var.
You could say:
haddock-html: file://$pkgroot/doc/ghc-6.10.1/libraries/base
but then tools that want to construct relative paths have to disentangle
the file:// prefix.

So, we suggest that we have two vars, $pkgroot and $pkgrooturl. These
are to be interpreted as the directory containing the package
registration information, eg the package.conf file in the case of ghc.
Hugs and nhc do not use package databases but they do use individual
files for each package's registration info. So again $pkgroot(url) is
just the dir containing the file.

Now tools may well be expected to understand these vars. We cannot
always have hc-pkg expand it, because for hugs and nhc there is no
hc-pkg, it's just the simple text files. A tool using the Cabal lib to
read the set of installed packages could benefit from the var expansion
but not one reading the files directly.

As a convenience ghc-pkg field does do variable expansion, and that's
probably the right tradeoff. Tools that parse the output of ghc-pkg
dump/describe can be expected to do the var expansion (and of course
they may want to see and construct relative paths).

The only thing is that tools then need to know the path to use for the
$pkgroot. In particular for the --global and --user packages which are
not specified to hc-pkg by their path.

Why not continue to use $topdir and $httptopdir? Because these things
are not guaranteed to exist. They only make sense for a relocatable
compiler installation. Users (especially distro packagers) may choose to
do non-relocatable installations following the FSH spec. However the
package file/db itself always exists. Also it's more general, it allows
multiple relocatable sets of packages, each with their own package
file/db, where as $topdir is tied to the installation of the compiler
itself.

Duncan