[Haskell-cafe] Haddock/hscolour integration broken on Hackage?

[Roberto Zunino]

Malcolm Wallace wrote:
> "David Menendez" <zednenem at psualum.com> writes:
> 
> 
>>I was looking at the Data.Binary documentation[1] on Hackage, and I've
>>noticed some problems with the associated source listings[2].
>>
>>First, none of the "Source" links work. They all refer to fragment IDs
>>(e.g., "#Binary") that are not defined. I'm not sure if this is a
>>problem with hscolor, haddock, or hackage.

I suspect this is because current cabal does not use %LINE links, as I 
did in my original patch. See for discussion

http://article.gmane.org/gmane.comp.lang.haskell.cabal.devel/727/match=haddock

Unfortunately %LINE is not yet widely available (only in darcs Haddock).

> Some of the source links do work, e.g. #encodeFile.  I believe those
> that do not work are due to a documented limitation of hscolour, that it
> is unable to lexically discover class methods, in order to place an
> anchor in front of them.

%LINE would sidestep this issue.

>>Second, the source listing itself[2] is invalid HTML[3]. The W3C
>>validator lists 678 errors. Of these, 677 are have to do with the line
>>number anchors, all of which start with parentheses.
> 
> 
> Oops.  The line number anchors were added to hscolour in a patch
> contributed by a third party, which I accepted in good faith.

That's me, I am sorry for that.

I chose "(line" and a prefix for the anchors because no 
otherwise-generated anchor by HsColour can cause a conflict with it. I 
see now that was indeed a poor choice. Would be enough to use the %xx 
encoding of parenthesis? Would you instead use another prefix (it is 
enough that no haskell identifier can start with it)? Maybe ".line" or 
"-line" ?

If you want me to send a patch for that, I will. And I'll run the HTML 
validator this time.

>  Since I
> have no need of line number anchors myself, maybe the easiest solution
> is simply to rollback that patch for the next version of hscolour.

Wrt removing line anchors, I still think that %LINE is the right way to 
go (well, either that or including a full-featured parser in HsColour).
But, of course, the maintainer has the last word about it! :-)

Regards,
Zun.