{} in .cabal for Haddock-documentation in Haskell

8
votes

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?

2
haskellcabalhaddock
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
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
@jrockway: Thanks. I'll just use (...) instead of {...}. - finnsson
@jrockaway -- being an unanswered questions pest here -- i think you should submit your comment as an answer :-) - sclv

2 Answers

3
votes

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!"
2
votes

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.