8

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?

finnsson
  • 4,037
  • 2
  • 35
  • 44
  • 2
    Looks like you can't actually have {} in the fields. I read the parser and there doesn't seem to be any prevision for escaping the {}s which denote a non-indentation-sensitive area in the Cabal file. (BTW, isn't "OPTIONS_GHC" deprecated? Probably better to say `{-# LANGUAGE TemplateHaskell #-}`.) I looked for examples of people trying to do this on Hackage, and all I found was (presumably) your attempt. Maybe move the cut-n-paste code into a different file... or make a non-backward-compatible change to the parser :( – jrockway Aug 29 '10 at 20:47
  • Oh yeah, and I use `test-framework-th` and I figured out what pragmas I needed without that detail in the description. So maybe the docs are unnecessary. :) – jrockway Aug 29 '10 at 20:48
  • @jrockway: Thanks. I'll just use `(...)` instead of `{...}`. – finnsson Aug 31 '10 at 12:38
  • @jrockaway -- being an unanswered questions pest here -- i think you should submit your comment as an answer :-) – sclv Jan 27 '11 at 15:08

2 Answers2

3

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!"
John Millikin
  • 197,344
  • 39
  • 212
  • 226
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.

Raeez
  • 2,423
  • 15
  • 12