Broken documentation on Hackage.

[Peter Selinger]

Hi Mateusz,

of course you could do the same thing with a bash script. It's a
matter of personal taste and workflow. Just for the record, you can
pass arguments into a Makefile like this: "make PACKAGE=bla". And "$$"
is indeed an escape, to denote a literal dollar sign (as opposed to a
Makefile variable).

Sorry about the bug. It should be "rm -rf". 

I'm not sure about the wisdom of adding new functionality to
cabal-install just to compensate for bugs in the Hackage documentation
builder.  It seems that the packages build correctly everywhere else,
so there is no reason in principle why the Hackage documentation
builder could not be fixed to build them. I see the manual uploading
as more of a temporary workaround. 

As for the bug with --contents-location and frames, it doesn't come up
in the Hackage documentation builder because it apparently disables
frames. There must be another (undocumented?) option for turning
frames off.

-- Peter

Mateusz Kowalczyk wrote:
> 
> > 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.