[Haskell-cafe] Hackage bug? Autobuild failure on literate source with ignored code blocks.

[Duncan Coutts]

On Sun, 2009-09-27 at 21:06 +0100, John Millikin wrote:
> According to <http://www.haskell.org/haskellwiki/Literate_programming>,
> the following should compile properly because the second block of code
> will be ignored by GHC:
> 
> \begin{code}
> main = putStrLn "Hello world!"
> \end{code}
> 
> \begin{code}%
> main = -- TODO
> \end{code}%

It looks to me like the advice on that wiki page is incorrect.

The Haskell98 report states:

        An alternative style of literate programming is particularly
        suitable for use with the LaTeX text processing system. In this
        convention, only those parts of the literate program that are
        entirely enclosed between \begin{code}...\end{code} delimiters
        are treated as program text; all other lines are comment. More
        precisely:
        
              * Program code begins on the first line following a line
                that begins \begin{code}.
              * Program code ends just before a subsequent line that
                begins \end{code} (ignoring string literals, of course).

The key phrases is "a line that begins \begin{code}". In other words, a
line "\begin{code}%" does indeed begin a code block.

> However, Hackage's automatic build system seems to pre-process the
> literate source in such a way that the ignored block is included in
> the .hs source, resulting in a compilation error:

Right. Having checked the H98 report I think this is the correct
behaviour.

> Although Hackage fails to build the package, it works fine on my local
> system when I run "cabal configure && cabal build && cabal haddock". Is
> this a bug in the Hackage auto-build mechanism, or have I done something
> wrong when uploading the package?

It looks like ghc gets this wrong and ignores "\begin{code}%". I have
filed this as http://hackage.haskell.org/trac/ghc/ticket/3549

Your local Cabal version is older than the one Hackage is using and that
older version lets haddock (ie ghc) do the pre-processing where as in
the current version Cabal does the unlitting before running haddock.
That explains the difference you observe.

The solution is not to use "\begin{code}%" and assume it will not be
recognised as the start of a code block.

Duncan