Before hacking on Haddock support...

[Roberto Zunino]

Duncan Coutts wrote:
> On Tue, 2007-07-10 at 15:45 +0200, Roberto Zunino wrote:
>> ...would you please review this patch? ;-)
> 
> Done!

Thank you very much!
I will run my tests on the current darcs when I can find some time.

> I changed this so it's:
> 
> ./Setup configure
> ./Setup haddock --hyperlink-source
> 
> or if you want to specify your own hscolour.css then it's:
> 
> ./Setup haddock --hyperlink-source --hscolour-css=...

That's fine for me.

(Actually, I find --hyperlink-source slightly misleading, since it can
suggest that links are added in the source itself, like Programatica.
Maybe --hyperlink-to-source?)

> I think hscolour should have a way to find or specify its own default
> hscolour.css since at the moment we don't actually get any colouring.
> We'd like by default to use hscolour's default hscolour.css.

Agreed.

I believe that hscolour behaves like this because it's invoked once for
each file. Copying the css file each time would be (maybe) a bit weird,
and OTOH pointing to a globally installed one would be easily broken if
the colourised source is copied to a remote web server.

Maybe a reasonable approach for HsColour would be "copy the default css,
unless a css is already there"? This should be fairly easy to do...

>> Requirements: HsColour >=1.8, my hscolour.css file[2] (or your own, of
>> course!), darcs Haddock + a link-breaking-bug fix (already sent) + any
>> version bump (required: haddock > 0.8).
> 
> I've made a couple changes so it works with the current release of
> haddock-0.8. In particular I've made it use the %{MODULE/./-} variable
> rather than the %{FILE///-} one that's only supported by the darcs
> version of haddock.

I see %{LINE} was also changed into %{NAME}.

I actually started my patch from %{MODULE} and %{NAME}, but in my tests
I noticed some broken links (e.g. to class members). This was mainly due 
to the HsColour "weak" parser, which do not really parse Haskell, but 
merely uses some heuristics to add colour at the right spots.

Trying fix HsColour, I soon realized that that would pretty much require 
replacing its parser with a full-featured one. Instead, I implemented 
%{LINE}, both in HsColour and Haddock. This is so Haddock can use its 
real parser and then just point to the line without relying on the weak 
HsColour parser to agree on %{NAME}. HsColour (latest) and Haddock 
(darcs) have %{LINE} now.

Another issue was that %{MODULE} points to the _exporting_ module,
which sometimes merely re-exports a symbol, so sometimes (often for
standard libs) it is not very useful to point there. OTOH, %{FILE}
always points to the defining module.

My suggestion: for now, it is probably better to keep your 
%{MODULE}/%{NAME} URL. As soon as Haddock is released, it would be nice 
to add a version check and switch to the %{FILE}/%{LINE} URL.

> What was that link-breaking-bug fix? Was that a fix for haddock or for
> Cabal?

Haddock. ("Foo/Bar.hs" sometimes internally was "././Foo/Bar.hs" and 
then was mangled to ".-.-Foo-Bar.hs".)

Regards,
Zun.