GHC's CPP and Cabal's unlit

[Duncan Coutts]

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 at 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