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.