GHC's CPP and Cabal's unlit

[Bayley, Alistair]

(Posting from a different account because your reply hasn't reach google mail yet)

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

I also have a program which I use to unlit Takusen's source:
  http://darcs.haskell.org/takusen/Bird2Hs.hs

But it is more lenient than the H98 standard for .lhs files. It's pretty easy to modify the existing Unlit module in Cabal, so I'll do that.


> > Another possibility is to also relax (well, disable) the
> > "program-line-next-to-comment-line" test in unlit.
> 
> 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.


I think that's the real question: should Cabal's unlit be faithful to the H98 standard, or should it be treated simply as a Haddock preprocessor? (and therefore can be a little lax)

H98 does require that code and comments are properly separated by blank lines, where a blank line consists only of whitespace:
  http://haskell.org/onlinereport/syntax-iso.html#sect9.4
So what I've proposed would be a deviation from the standard.

I do need a way of ensuring that I can write paragraphs in contiguous comment blocks. e.g. so this

|
para 1
 
para 2

becomes

-- |
-- para 1
-- 
-- para 2

rather than

-- |
-- para 1

-- para 2

(Haddock will ignore the second paragraph).

Perhaps using a single period on a line as a convention for a blank comment line? e.g.

|
para 1
.
para 2


Or maybe I can enhance the unlit algorithm so that it can detect whether or not a blank line precedes a program line and behave accordingly.

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