用于 Haskell 中 Haddock 文档的 .cabal 中的 {} 是什么？

Question

如果我获取了这行代码

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

在.cabal文件的文档部分（描述）中，我会收到错误消息。

haddock: parsing haddock prologue failed

运行时

$ cabal haddock

但是如果我去掉 { 和 } ，一切都能正常工作。有没有办法转义 {} 以便它们可以用于描述中？

- finnsson

---

看起来你实际上不能在字段中使用 {}。我阅读了解析器，似乎没有对表示 Cabal 文件中不缩进敏感区域的 {} 进行转义的预设。（顺便说一句，“OPTIONS_GHC”是否已被弃用？最好说 {-# LANGUAGE TemplateHaskell #-} ）我在 Hackage 上寻找尝试此操作的示例，但我找到的只有（可能是）你的尝试。也许将剪切-粘贴代码移入另一个文件中……或者对解析器进行不向后兼容的更改 :( - jrockway

哦，对了，我使用 test-framework-th，并且在没有描述中的细节的情况下找出了我需要的编译指示。因此，也许文档是不必要的。 :) - jrockway

@jrockway：谢谢。我将使用(...)而不是{...}。 - finnsson

@jrockaway -- 在这里成为一个未回答问题的讨厌鬼--我认为你应该将你的评论提交为答案 :-) - sclv

Answer 1

代码块语法

Haddock有两种代码块的语法 - 使用@来限定代码块的语法可以使用HTML转义，这可以用于嵌入Cabal的解析器无法处理的字符。

不幸的是，似乎Cabal会从@限定的代码块中去除前导空格，因此您还必须在任何行的前缀上加上一个HTML编码的空格 。

以下是一个示例：

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

这将被渲染为：

My package with a code example!

{-# LANGUAGE TemplateHaskell #-}

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

- John Millikin

Answer 2

OPTIONS_GHC本身并没有过时（例如，您可以使用它来启用特定的构建选项），但是将其用于打开/关闭语言功能被认为不是良好的实践。请改用{-# LANGUAGE ... #-} pragma。

例如：{-# LANGUAGE TemplateHaskell, ForeignFunctionInterface, RankNTypes #-}

此外，使用全包含的-fglasgow-exts被认为是不好的形式。最好只包括您需要的扩展，这样对于任何新接触您的代码的人来说，哪些扩展是必需的就更清晰了。

- Raeez

---

这是一个好建议，但它甚至没有试图回答问题。 - Ben Millwood