[Haskell-cafe] Haddock markup questions

[Mateusz Kowalczyk]

On 10/04/14 17:22, Christiaan Baaij wrote:
> Hello list,
> 
> I have two questions regarding proper markup for my haddock documentation.
> I'm using the latest released haddock, version 2.14.2.
> 
> The first is about deprecation pragma's and operators usint '<' and '>'
> I have the following deprecation message:
> 
>> {-# DEPRECATED Comp "Use 'Applicative' interface and ('<^>') instead" #-}
> 
> Haddock however generates the following:
> http://christiaanb.github.io/clash-prelude/CLaSH-Prelude.html#t:Comp
> 
> Where 'Applicative' gets a proper link to the applicative type class... but
> '<^>' is translated to a link to '^'... which is a page that doesn't exists.
> 
> I can get haddock to not generate a link using:
> 
>>> {-# DEPRECATED Comp "Use 'Applicative' interface and ('\\<^\\>')
> instead" #-}
> 
> But that's unwanted, as those backslashes show up in GHC(i) messages.
> So: how do I get haddock to not parse my '<^>' operator as a link/URL?

Hm, strange, technically we parse identifiers first and links second so
this should work without a problem unless Haddock doesn't recognise it
as an identifier.

I actually now notice in the parser that we don't consider ^ to be a
valid symbol so that's probably the culprit! Good catch, if that's
actually the case here then you can expect it to be fixed in the next
release, perhaps with 7.8.3 or something. Unfortunately the way we do
identifier parsing now is that we slurp everything that looks like a
valid identifier and afterwards we ask GHC to actually tell us if it's
it's something we know about. It seems like a bug caused by me not being
careful when reading the relevant part of the report, deepest apologies!
I do wish we had a better way of parsing these identifiers but I can't
think of one.

> 
> My second question is again about getting links to operators in general.
> If you take a look at, e.g.,
> http://hackage.haskell.org/package/base-4.7.0.0/docs/Control-Applicative.html
> You can see that proper documentation links are generated to the '<*>' and
> such operators.
> However, if you take a look at the documention I tried to generate for my
> library:
> http://christiaanb.github.io/clash-prelude/CLaSH-Signal-Implicit.html#v:-60--94-
> You can see that the referenced '^>' operator does not get a proper link.
> So my question: how do I get haddock to create proper links for my
> referenced operators.

Sounds like it's the same issue.

> I should note that I create haddock docs using 'cabal haddock' instead of
> calling haddock directly.
> 
> Best regards,
> 
> Christiaan
> 
> 
> 
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
> 


-- 
Mateusz K.