On Thu, 2007-11-29 at 11:18 +0000, Alistair Bayley wrote:
I'm of a mind to fix two things in cabal: - the haddock command runs unlit first, THEN cpp - the unlit module preserves comments, for the benefit of haddock
Sounds great. Send your patches to cabal-devel@haskell.org. You may also like to subscribe to that mailing list.
Have subscribed. Also, have a question about Cabal's unlit. I intend to change it's behaviour slightly, so that lines that are not completely empty (e.g. a single space) are treated as comment lines, rather than blanks. This makes it possible to write Haddock sections that contain paragraphs e.g.
You may also like to consider a previous discussion on this issue: http://www.haskell.org/pipermail/cabal-devel/2007-August/thread.html#725 Jón Fairbairn sent in some code he uses for turning .lhs files into something that haddock can understand. It may or may not be helpful to you.
Bullet list: <space> * bullet 1 <space> * bullet 2
becomes
-- Bullet list: -- -- * bullet 1 -- -- * bullet 2
which is what Haddock requires to render a bullet list.
Sounds reasonable.
This change might break programs that have otherwise blank lines containing spaces next to program lines. However, given that (AFAICT) unlit is only used in generating Haddock docs, and this is currently broken anyway for .lhs files, this doesn't seem like much of a concern.
True, though in future we may want to use it more widely.
Another possibility is to also relax (well, disable) the "program-line-next-to-comment-line" test in unlit. Again, we're only generating Haddock docs, so no major loss there. And this would permit programs that have blank-lines-with-spaces next to program lines.
I'm not sure I fully understand all this. What is required in H98? It requires blank lines next to program text at least with > bird track style. Is the question simply whether a line with only spaces counts as a blank line? Seems to me we should follow H98 whatever it says, and/or the current interpretation of implementations like ghc & hugs. Duncan