如何在Haddock文档中嵌入图片

Question

我该如何在本地Haddock文档中嵌入图片？

例如，我注意到lens包只使用外部链接来显示图片，但我想将图片存储在本地。

（这个问题与邮件列表上未回答的问题非常相似。）

- amindfv

Answer 1

如果您想在本地存储图像，可以：

-- A longer description of the package.
description: Some haskell package description.

    <<file:///home/user/your_image.png>>

结果：

如果您不想或无法通过相对路径添加图像，只需使用图像名称而不是完整路径：

<<your_image.png>>

在这种情况下，您的图像必须位于project/docs目录中。

- 0xAX

---

我找不到任何方法来破解它以获取相对路径，因此它很脆弱，因为它假定文档将在用户驱动器上使用的目录中。是吗？ - amindfv

是的，你说得对。如果你无法获取到图片的相对路径，你也可以添加“<<Haskell-Logo-Variation.png>>”，然后 Haskell-Logo-Variation.png 图片必须放在项目的文档目录中。 - 0xAX

太好了！这正是我在寻找的。你能把它添加到你的答案中吗？另外请注意，如果你的图片在 docs/images/ 中，你可以用 <<images/some_img.jpg>> 引用它。 - amindfv

有人想到了如何钩入Cabal以自动将图片复制到文档目录吗？ - lpsmith

如果您已经有了包含图像的文档目录，则 cabal-install 应该会将文档与图像一起放置。 - amindfv

（至少对于包目录中的文档） - amindfv

Answer 2

正如您所引用的邮件列表线程中解释的那样，一种选择是使用数据URL将图像嵌入到文档中。这使得源代码本身读起来有些不愉快（因为它与大量的base64编码数据交织在一起），但使用Haddock的命名块可以帮助解决这个问题，通过将所有图像放置在文件末尾的命名块中。关于这种方法的实际示例，请参见circle-packing软件包的Haddock文档。

- Brent Yorgey

---

很奇怪，它不应该阻止你在Cabal包中引用数据文件。o_o - Christopher Done

我不认为Haddock知道任何关于Cabal甚至ghc-pkg的事情，对吗？ - Dag

数据 URL 技巧非常不错。这可能会解决我们从 lens 中获取维基时遇到的性能问题。(我们已经将 lens.cabal 文件中的链接更改为指向 imgur，因为它没有缓存禁用问题。) - Edward Kmett

有趣的是，如果你尝试创建一张比“圆形填充”包中的图片大得多的图像，haddock 就会因栈溢出而死掉。=/ - Edward Kmett

Answer 3

正如Ian Ross在博客文章中所解释的那样，您可以使用extra-doc-files cabal选项将额外的文件捆绑到文档中。

- phadej