如何最好地为 macOS 应用编写 Apple 帮助手册？

Question

macOS 应用程序，例如 Photos.app，为用户提供帮助面板

有没有办法在您自己的 macOS 应用程序中编写这样的帮助手册？有没有办法至少提供一个用于目录的工具栏？

我特别询问 UI 和所有用户交互。不是通常如何创建和注册帮助手册。

更新

这是我能够从其他人那里找到/收集/学习的内容。帮助手册似乎运行在名为“HelpViewer”的单独应用程序/进程上。任何显示帮助的 Apple macOS 应用程序都使用非公开的 DDMViewerController。

Apple 帮助手册的 Apple macOS 应用程序“index.html”使用了“app.css”和“app.js”。Javascript 操作 DOM 以创建切换侧边栏的“显示-隐藏”链接。无法找到如何指示 HelpViewer 使用侧边栏。

早在 2014 年就有一个 WWDC 演讲，“Introducing the Modern WebKit API”，讨论了允许 Webview 和 Cocoa 之间通信的“用户脚本”和“脚本消息”。https://developer.apple.com/videos/play/wwdc2014/206/

AFAICS，没有办法让 HelpViewer 显示自定义视图或侧边栏。我的猜测是你必须自己实现一切。那是一个 NSSplitViewController、NSToolbar、NSOutlineView，任何与“app.css”一起使用的 Javascript 以获得外观和感觉。

Answer 1

目前，从 10.13 开始，无法实现地图和其他内置 macOS 应用程序中所示的侧边栏。

从 10.10 开始的 macOS 版本（内置应用程序）使用 HTML 和 JavaScript 实现侧边栏导航，并且 Apple Help Viewer 本身提供了window.HelpViewer带有一些钩子的对象，这些钩子可以启用/禁用 Help Viewer 的目录按钮。启用后，它将回调到您自己的 JavaScript，您可以在其中通过 CSS 或 JS 显示/隐藏 TOC。

大约从10.10开始，苹果的非内置应用程序也开始使用这种技术。例如，iTunes 和 Xcode 都可以帮助做到这一点。

从 10.13 开始，macOS 有了更新版本的 Help Viewer，它提供了实际的 Cocoa 本机目录和窗口拆分器，以及window.HelpViewer;上的一些新属性。据推测，这些可用于启用/禁用 Cocoa 侧边栏并填充 TOC，但这些都没有记录，我不确定 Apple 之外的任何人是否能够逆向工程此功能。

无论如何，如果您向 10.13 之前的用户提供帮助手册，并且使用未记录的 API 会限制 App Store 中的应用程序（尽管我不确定 Apple 是否会扫描帮助手册 JavaScript 来了解 API 使用情况），那么这是行不通的作为他们审查的一部分）。

（苹果内置应用程序帮助的工作方式现在也有很多其他变化，但这完全是另一个话题。）

因此，现在的答案是我们不能，或者不应该，或者只是不知道如何做。替代方案包括使用 jekyll-apple-help（无隶属关系）或 Middlemac 3（我的项目）之类的东西，或者只是自己动手。

对于那些有兴趣了解苹果如何做到这一点的人，我在这里记录了很多内容（披露：链接到我自己的网站）。