[arch-haskell] local docs bugged?

[Magnus Therning]

On Tue, Jan 01, 2013 at 06:23:01PM -0500, tam at hiddenrock.com wrote:
> With a fresh install of ghc and only ghc, I have a handy-dandy set
> of documentation rooted at /usr/share/doc/ghc/html.  The
> particularly useful (to me) part is described by
> libraries/index.html, which points to all the module-specific
> documentation.  Except it doesn't.  With just ghc installed, I then
> added haskell-text, and the documentation isn't updated.  I poked
> around and it appears the documentation under libraries/dist-haddock
> *is* updated, but the relative paths are broken for most (all?)
> except the stuff from haskell-text.  I also installed haskell-parsec
> and its documentation shows up only under libraries/dist-haddock.
> 
> In /etc/pacman.conf, after [core] and before [extra] and
> [community]:
> 
>     [haskell-core]
>     SigLevel = Optional
>     Server = http://xsounds.org/~haskell/core/$arch
>     Server = http://www.kiwilight.com/haskell/core/$arch
> 
>     [haskell-web]
>     SigLevel = Optional
>     Server = http://archhaskell.mynerdside.com/$repo/$arch
> 
> Summary:
> 
>     /usr/share/doc/ghc/html/libraries/index.html points to
>     documentation concerning modules shipped with ghc
> 
>     post-install for haskell-text and haskell-parsec runs
>     gen_contents_index, which seems to put their documentation in
>     the index at
>     /usr/share/doc/ghc/html/libraries/dist-haddock/index.html and
>     *NOT* in /usr/share/doc/ghc/html/libraries/index.html
> 
>     /usr/share/doc/ghc/html/libraries/dist-haddock/index.html seems
>     to correctly point to documentation regarding modules from
>     haskell-* packages
> 
>     /usr/share/doc/ghc/html/libraries/dist-haddock/index.html seems
>     to NOT correctly point to documentation regarding modules from
>     the 'ghc' package
> 
> 
> 
> Did I fat-finger something?  Am I wrong to expect all the module
> docs to be available from
> /usr/share/doc/ghc/html/libraries/index.html ?  I could swear it was
> previously; maybe it broke during the switch to 7.6?
> 
> This commit seems relevant:
> 
>     http://www.haskell.org/pipermail/cvs-ghc/2012-January/069567.html
> 
> but it's not clear (to me) what the difference is between
> libraries/* and libraries/dist-haddock/*.

This seems to indeed be the case.  However, AFAIK we don't do anything
special when generating the documentation so this feels like an
upstream bug.

Maybe we should drop the use of the upstream script and use something
simpler instead.  This seems to work well enough:

    #! /bin/bash
    
    HADDOCK=haddock-ghc-7.6.1
    HADDOCK_LIBS=/usr/share/doc/ghc/html/libraries
    HADDOCK_FILES=
    for f in $(find -L $HADDOCK_LIBS -name \*.haddock ! -name ghc.haddock); do
        HADDOCK_FILES="$HADDOCK_FILES -i $(dirname $f),$f"
    done
    
    $HADDOCK --gen-index --gen-contents -o . -t 'Local Haskell Libraries' \
        $HADDOCK_FILES

/M

-- 
Magnus Therning                      OpenPGP: 0xAB4DFBA4 
email: magnus at therning.org   jabber: magnus at therning.org
twitter: magthe               http://therning.org/magnus


Perl is another example of filling a tiny, short-term need, and then
being a real problem in the longer term.
     -- Alan Kay
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 230 bytes
Desc: not available
URL: <http://www.haskell.org/pipermail/arch-haskell/attachments/20130102/a1854467/attachment.pgp>