swift - 将 Apple DocC 作为 Apple 帮助手册文件运行

Question

随着用于从源代码生成文档的 DocC 的引入，是否可以获取 DocC 的输出并将其用作 Apple 帮助手册（用于 macOS 应用程序内部）的真实来源？

• DocC介绍：https ://developer.apple.com/videos/play/wwdc2021/10166/
• 适用于 Mac 应用程序的 Apple 帮助手册：https ://developer.apple.com/library/archive/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/authoring_help/authoring_help_book.html#//apple_ref/doc/uid/TP30000903-CH206-CIHEHEAC

Answer 1

可能不是。它们是完全不同的动物。帮助手册是一个完整的网站，对某些类型的锚点有一些帮助。DocC 是一种非常特定类型的信息的高度受限、形式化的表示。确实，即使您将这两种东西融合在一起，您也不会想要；帮助手册帮助用户，而 DocC 向程序员显示编程 API。

举个例子，这是我写的一本帮助书：

http://www.aeth.com/sd5help/index.html

您不可能使用 DocC 来表达这一点。如果问题是您正在寻找一种工具来帮助您编写帮助书籍，那么 DocC 不是它。

Answer 2

是否可以获取 DocC 的输出并将其用作 Apple Help Book 的真实来源？

• 是的，但可能不值得。

---

@matt提到：

DocC 是一种非常特定类型的信息的高度受限、形式化的表示。

不过我不同意。您可以使用 DocC 创建文章页面：树懒入门

---

使用 DocC 创建 Apple Help Book的问题：

• DocC 文档只支持基本的 markdown 语法，所以你的格式化选项是有限的。

• DocC 将文档导出为单页 Web 应用程序，Apple Help Book 期望每个帮助页面都有单独的 html 文件。所以你需要自动生成静态 html 文件。

• DocC 文档不允许您为索引添加自定义元标记或为锚点添加关键字和名称。（也许你可以在markdown中使用评论，然后从评论中自动生成它们。但是我不确定markdown中的评论是否会保留在DocC生成的文件中）

• 您仍然需要使用帮助索引器来索引它们。

---

@matt提到：

帮助手册帮助用户，而 DocC 向程序员显示编程 API。

您绝对可以将两者融合并使用 DocC 生成的文件作为您的事实来源，但如果您更喜欢 markdown 语法，我更愿意使用其他 html 编辑器或更好的 markdown 编辑器。