{} in .cabal for Haddock-documentation in Haskell

Question

If I got the line

> { -# OPTIONS_GHC -fglasgow-exts -XTemplateHaskell #- }

in the documentation-part (description) of the .cabal-file I'll get the error message

haddock: parsing haddock prologue failed

when running

$ cabal haddock

but if I get rid of the { and } everything works fine. Is there some way to escape {} so they can be used in the description?

Answer 1

Haddock has two syntaxes for code blocks -- the syntax that delimits blocks with @ allows you to use HTML escapes, which can be used to embed characters that Cabal's parser can't deal with.

Unfortunately, it seems that Cabal strips the leading whitespace from @-delimited blocks, so you also have to prefix any lines with spaces with an HTML-encoded space  .

Here's am example:

description:
  My package with a code example!
  .
  @
  {-\# LANGUAGE TemplateHaskell \#-}
  .
  main = do
      $templatePrint "hello!"
      $templatePrint "world!"
  @

Which renders to:

My package with a code example!

{-# LANGUAGE TemplateHaskell #-}

main = do
    $templatePrint "hello!"
    $templatePrint "hello!"

Answer 2

OPTIONS_GHC itself is not deprecated (you'd utilize this to enable particular build options, for example), but using it to turn on/off language features is not considered good practice . Use {-# LANGUAGE ... #-} pragmas instead.

e.g. {-# LANGUAGE TemplateHaskell, ForeignFunctionInterface, RankNTypes #-}

Also, it's considered bad form to utilize the all-encompassing -fglasgow-exts. Better to just include the extensions you need, and that way it's clearer which are required for anyone new to your code.