Broken documentation on Hackage.

[Mateusz Kowalczyk]

On 07/01/14 01:23, Peter Selinger wrote:
> Thanks, that's even better!
>
> However, I find that the --contents-location option to cabal haddock
> does not work properly.  Apparently it not only prevents index.html
> from being built (which makes modest sense), but it also prevents
> index-frames.html from being built (which does not). So in the frames
> view, one of the frames will just say "Sorry, it's just not here".
> That's not very nice. Also, if one loads the "/frames.html" URL
> directly, it still points to the non-existing index.html, rather than
> the one given by --contents-location. I think these are bugs.
>
> For example, see
> http://hackage.haskell.org/package/yi-monokai-0.1.1.1/docs/Yi-Style-Monokai.html
> and click on "Frames".

Ah, I do not use frames so I did not notice.

> One workaround is to run "cabal haddock" twice: first without the
> --contents-location option, and then with it. Slightly annoying, but
> it works. It has the disadvantage that if one goes directly to the
> ".../frames.html" URL, one will still see the old index.html.
>
> Another workaround is to omit the --contents-location option
> altogether, and to manually create an index.html that is just a
> forward to the correct location, i.e.:
>
> <meta HTTP-EQUIV="REFRESH" content="0; url=http://hackage.haskell.org/package/newsynth-0.1.0.0">
> If your browser does not take you there automatically, please go to
> <a href=http://hackage.haskell.org/package/newsynth-0.1.0.0>http://hackage.haskell.org/package/newsynth-0.1.0.0</a>.
>
> Only this last solution seems to do the correct thing all the time.
> For an example, see
> http://hackage.haskell.org/package/newsynth-0.1.0.0/docs/frames.html
>
> Your instructions have been *very* helpful. But it's a lot of details
> and finnicky cabal directives to keep track of for doing this all the
> time. I've turned your instructions into a Makefile to automate this
> task; see attached. In principle, only the first two lines should need
> to be customized. Then "make doc-upload" will build the documentation
> and upload it correctly.

That looks very useful but I have a few questions about it:
* Why a Makefile as opposed to a Bash script or something? I don't
think there's a way to pass arguments into a Makefile like to Bash
scripts, save for environmental variables. I'd much rather prefer a
command line flag for a script in my PATH rather than having to change
the file each time.

* This file makes us change the top two lines (user and package name)
and uses ‘read’ for everything else. Why not fully go with one way or
the other? Personally, I'd prefer arguments rather than ‘read’ (much
easier to repeat commands/script against) but it's up to personal taste.

* Can we not grab to project name from the cabal file just like you do
with version?

* Your ‘--html-location’ has ‘$$pkg’ in it, how come? Is that some
kind of escape?

* Considering you seem to know what you're doing much more than I am,
is there any way to detect cabal sandboxes?

I'm trying your makefile now (running with make -f /tmp/Makefile
doc-upload) and
it's giving me an error:

```
[snip]
Haddock coverage:
 100% ( 18 / 18) in 'Yi.Style.Monokai'
Documentation created: dist/doc/html/yi-monokai/index.html
rm -r yi-monokai-0.1.1.1-docs
rm: cannot remove ‘yi-monokai-0.1.1.1-docs’: No such file or directory
make: *** [yi-monokai-0.1.1.1-docs.tar.gz] Error 1
```

It works fine if I comment out the ‘rm -r’. Perhaps that should be
allowed to fail somehow.

> I know, Cabal somehow was supposed to make Makefiles obsolete. Alas.
> Fortunately, the Makefile is only for the package maintainer, and not
> for the package user.
>
> -- Peter

I think that cabal-install should really have the option to do all
this rather than have people write up scripts like this, resulting in
trial and error.

--
Mateusz K.