Haddock and literate Haskell: annotations must be marked as source?
Hi all, I've developed a bit of a taste for literate Haskell lately, being a verbose sort of guy. Unfortunately, it doesn't seem to interact with Haddock in the way I'd like/expect. I just wanted to check that my understanding of the situation is correct before I (regretfully) give up on LHS. It seems to me that Haddock only picks up annotation comments (ie those that should be included in the produced documentation) from literate Haskell source when those annotations are themselves marked up as source - it seems not to recognise them in the general text. For example, I was expecting/hoping that from the point of view of Haddock, the following literate Haskell code with an annotation-marked paragraph (starts with a vertical bar) in the non-source text. | Turn a foo into a bar.
foo :: Foo -> Bar foo b = ...
ought to be equivalent to the following "illiterate" Haskell: -- | Turn a foo into a bar. foo :: Foo -> Bar foo b = ... ie, it should produce Haddock docs where the definition of foo is annotated with that comment. Sadly, that appears not to be the case. It appears the literate version needs to look like this:
-- | Turn a foo into a bar foo :: Foo -> Bar foo b = ...
which to my mind rather defeats the purpose of being literate. So: am I right that this is the intended/expected behaviour? If not, how does one get round it? If so, could someone perhaps comment on the prospects/complexity of implementing this - or the reasons why it is in fact a bad idea? Many thanks! -Andy
From: haskell-cafe-bounces@haskell.org [mailto:haskell-cafe-bounces@haskell.org] On Behalf Of Andy Gimblett
It seems to me that Haddock only picks up annotation comments (ie those that should be included in the produced documentation) from literate Haskell source when those annotations are themselves marked up as source - it seems not to recognise them in the general text.
It appears the literate version needs to look like this:
-- | Turn a foo into a bar foo :: Foo -> Bar foo b = ...
which to my mind rather defeats the purpose of being literate.
So: am I right that this is the intended/expected behaviour?
Haddock currently uses ghc's parser, and I believe the literate preprocessor discards comments. I think there is an item on the haddock wishlist to preserve the literate comments, but I'm not certain... This problem has been solved in cabal, BTW. Cabal preprocesses .lhs itself, rather than trust the compiler to do it, and it preserves the comments. If you generate you haddocks with cabal, then you should be able to use the markup the way you expected. The Takusen source files are written in this style. For example, see: http://darcs.haskell.org/takusen/Database/Enumerator.lhs Alistair ***************************************************************** Confidentiality Note: The information contained in this message, and any attachments, may contain confidential and/or privileged material. It is intended solely for the person(s) or entity to which it is addressed. Any review, retransmission, dissemination, or taking of any action in reliance upon this information by persons or entities other than the intended recipient(s) is prohibited. If you received this in error, please contact the sender and delete the material from any computer. *****************************************************************
On Thu, 2009-09-24 at 17:49 +0100, Andy Gimblett wrote:
So: am I right that this is the intended/expected behaviour? If not, how does one get round it? If so, could someone perhaps comment on the prospects/complexity of implementing this - or the reasons why it is in fact a bad idea?
As Brad says, we implemented this in Cabal by doing a non-standard "unlit" operation. So cabal haddock will "do the right thing" for your examples. Running haddock directly and letting it do the unlitting will get different results. If the consensus is that the style of unliting that Cabal is doing is generally "the right thing" then perhaps we can standardise it and have ghc/haddock do it directly. Duncan
On 24 Sep 2009, at 18:28, Duncan Coutts wrote:
On Thu, 2009-09-24 at 17:49 +0100, Andy Gimblett wrote:
So: am I right that this is the intended/expected behaviour? If not, how does one get round it? If so, could someone perhaps comment on the prospects/complexity of implementing this - or the reasons why it is in fact a bad idea?
As Brad says, we implemented this in Cabal by doing a non-standard "unlit" operation. So cabal haddock will "do the right thing" for your examples. Running haddock directly and letting it do the unlitting will get different results.
That's great news for me, except: that's what I tried first, and I've just tried it again and it still doesn't seem to work for me. Perhaps I am doing something wrong...? Here's a toy example LHS file: http://hpaste.org/fastcgi/hpaste.fcgi/view?id=9802 and here's the corresponding .cabal file: http://hpaste.org/fastcgi/hpaste.fcgi/view?id=9803 and here's a screenshot of the resultant HTML: http://is.gd/3DzmT (produced via "runghc Setup configure && runghc Setup haddock" ) Any idea what I'm doing wrong? One thing I did try was removing the blank line between the annotation and the code. Of course, that breaks the LHS rules, so it doesn't build. (I wondered if it was special cased for this purpose.) Thanks again, -Andy
On Thu, 2009-09-24 at 19:48 +0100, Andy Gimblett wrote:
That's great news for me, except: that's what I tried first, and I've just tried it again and it still doesn't seem to work for me. Perhaps I am doing something wrong...?
You're quite right, it got broken with the move to haddock2. The code in Cabal-1.6 skips the pre-processing when using haddock2, assuming haddock will handle it. In the current Cabal development version it works properly and I get the right output for your example. Duncan
On 24 Sep 2009, at 20:10, Duncan Coutts wrote:
On Thu, 2009-09-24 at 19:48 +0100, Andy Gimblett wrote:
That's great news for me, except: that's what I tried first, and I've just tried it again and it still doesn't seem to work for me. Perhaps I am doing something wrong...?
You're quite right, it got broken with the move to haddock2. The code in Cabal-1.6 skips the pre-processing when using haddock2, assuming haddock will handle it. In the current Cabal development version it works properly and I get the right output for your example.
Ah, righto. In that case, I won't shy away from LHS, and I'll be patient for the next Cabal release, or maybe even check out the development version. :-) Many thanks for your reassurance! Cheers, -Andy
From: haskell-cafe-bounces@haskell.org [mailto:haskell-cafe-bounces@haskell.org] On Behalf Of Andy Gimblett Sent: 24 September 2009 20:19
On 24 Sep 2009, at 20:10, Duncan Coutts wrote:
On Thu, 2009-09-24 at 19:48 +0100, Andy Gimblett wrote:
That's great news for me, except: that's what I tried first, and I've just tried it again and it still doesn't seem to work for me. Perhaps I am doing something wrong...?
You're quite right, it got broken with the move to haddock2. The code in Cabal-1.6 skips the pre-processing when using haddock2, assuming haddock will handle it. In the current Cabal development version it works properly and I get the right output for your example.
Ah, righto. In that case, I won't shy away from LHS, and I'll be patient for the next Cabal release, or maybe even check out the development version. :-)
Doh. I forgot that little detail. You need cabal > 1.6.0.2, which unfortunately is the last released version. The current development one should do it (very easy to install with cabal :-). Alistair ***************************************************************** Confidentiality Note: The information contained in this message, and any attachments, may contain confidential and/or privileged material. It is intended solely for the person(s) or entity to which it is addressed. Any review, retransmission, dissemination, or taking of any action in reliance upon this information by persons or entities other than the intended recipient(s) is prohibited. If you received this in error, please contact the sender and delete the material from any computer. *****************************************************************
participants (3)
-
Andy Gimblett -
Bayley, Alistair -
Duncan Coutts