.cabal 中的 {} 用于 Haskell 中的 Haddock 文档

Question

收到该行

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

如果我在 .cabal 文件的文档部分（描述）中

haddock: parsing haddock prologue failed

，则在运行时

$ cabal haddock

我会收到错误消息，但如果我去掉 { 和 }一切正常。是否有某种方法可以转义 {} 以便可以在说明中使用它们？

Answer 1

Haddock 有两种代码块语法——用 @ 分隔块的语法允许您使用 HTML 转义符，它可用于嵌入 Cabal 解析器无法处理的字符。

不幸的是，Cabal 似乎从 @ 分隔的块中去除了前导空格，因此您还必须在任何带有空格的行前面加上 HTML 编码的空格 。

这是一个示例：

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

它呈现为：

我的包带有代码示例！

{-# LANGUAGE TemplateHaskell #-}

主要=做
    $templatePrint“你好！”
    $templatePrint“你好！”

Answer 2

OPTIONS_GHC 本身并未被弃用（例如，您可以利用它来启用特定的构建选项），但使用它来打开/关闭语言功能并不被认为是好的做法。请改用 {-# LANGUAGE ... #-} 编译指示。

例如 {-# LANGUAGE TemplateHaskell,foreignFunctionInterface, RankNTypes #-}

另外，使用包罗万象的 -fglasgow-exts 被认为是不好的形式。最好只包含您需要的扩展，这样对于任何刚接触您的代码的人来说都更清楚需要哪些扩展。