[Haskell-cafe] Haddock Secrets?

[Bayley, Alistair]

> From: haskell-cafe-bounces at haskell.org 
> [mailto:haskell-cafe-bounces at haskell.org] On Behalf Of 
> Gregory Crosswhite
> 
> Is there some secret to getting Haddock to work with literate 
> Haskell sources that I am missing?
> 
> For example, when I download Takusen and type
> 
> 	cabal configure
> 	cabal haddock
> 
> It produces HTML files complete with a table of contents, but 
> with all of the documentation stripped out.  Oddly, I know 
> that it is *possible* to process the literate sources into 
> documentation because it appears on Hackage!

You need a recent version of cabal i.e. >= 1.6.0.3. I don't think the haddock version matters much (cabal can handle haddock-1 and haddock-2, I think).

The problem is that haddock does not retain literate comments i.e. the .lhs preprocessor is run before haddock parses the file, and literate comments are stripped.

This has been fixed in cabal by having cabal preprocess the .lhs file itself, with a special preprocessor that retains literate comments. The resulting .hs file is passed to haddock, and voilà.

Before cabal solved the problem, I used to run a similar custom preprocessor over the Takusen source tree, and then invoke haddock manually to create the html docs.

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.
*****************************************************************