Authoring Mac Help Books in 2020
Apple’s own documentation for Apple Help has moved to the documentation archive on their developer site. You’ll find tons of questions on Stack Overflow and other… more questionable sites. Apple did do a minor revision to their documentation back in 2013. 2013!!!
By now, 2020, Apple Help is neglected and well, crusty. Very crusty (no, not that Crusty). It still works but certain parts of it don’t seem to work as well anymore. Not sure why it’s neglected. They advise you include a Help Book in their HIG that was recently published — and they link to the documentation (from 2013). Personally, I think they have a lot of potential and a lot to offer. I just wish this was a component at Apple that would get some attention in both development and documentation.
[…]
I spent countless hours and days trying to piece together all the information from all corners of the internet to build a Help Book. It was super frustrating and excruciatingly time consuming. I don’t want anyone else to feel this way so I hope this speeds things up for the next Mac Developer who wants to include a Help Book with their awesome app!
I prefer the hiutil command-line tool over the Help Indexer app because I can invoke it from my build script.
Previously:
7 Comments RSS · Twitter
We used Texinfo to create an extensive Help Book for BibDesk, and it worked pretty well. I use OmniOutliner to create help files for TeX Live Utility, based on a script that Omni posted years ago, and it does all the heavy lifting.
https://www.omnigroup.com/blog/Helpify_the_Omni_Help_Emitter
Reading that blog post, I'm surprised to see there's a new Info.plist setup; we've always used the ones in the application's Info.plist, CFBundleHelpBookFolder and CFBundleHelpBookName, and there's no plist in the help book itself. Apple's documentation for Help Books and indexing has always sucked, to put it mildly.
I've wondered for a long while why they haven't leveraged Apple Books tech as the way to create Help Books. Creating HTML-based help books makes some sense in that the page can pull from an online source, look like your website etc, but the barrier to making even a *simple* help book in the Apple-esque style is way too high. Using iBooks Author (now Pages) to create eBooks would be waaaaay quicker, and allow easy drag and drop of movies and other rich content to include in the documentation.
I have an open feedback report on this. All y'all should join in. ;)
Mario put together a good overview. I second hiutil(1) for indexing. And the sidebar trick he missed is window.HelpViewer.showTOCButton(...).
But AppleHelp is truly terrible. It's one of the areas where, if I could go back in time, I'd tell myself to never touch it. It's way more trouble than it's worth. It's bad at everything.
You can't just set it up once and forget it. It keeps hurting you. You can make things work right, and then Apple will go change something internally (as they did in 10.13 or 10.14?) and your navigation breaks. The change isn't documented, of course, because the system wasn't really documented to begin with. Any time you reverse-engineer something, you're also committing to keep re-reverse-engineering it every year. It's not like Swift versions, where Xcode has an automatic "update" button that sometimes works.
It's not even WebKit. Not any modern one, at least. That would be too easy. It renders "HTML 4.01". (It uses "WebKitLegacy.framework"!) You can't even use &-abbreviations like "rarr" (for right arrow). Be prepared to type hex codes. HTML5? Not a chance. It's 15 years older than that.
And for what? You get to be part of the macOS system help. A user can open Help in Safari and type "xcode" in the search box and get Xcode help. Or help for your app. It sounds nice to have all of the system's help indexed in one place, but that particular use case is something I've never once wanted or used.
Save yourself. Pretend AppleHelp doesn't exist. Write HTML5, or use an authoring tool that can generate that. Then have your "Help" menu item open a custom window with a WKWebView. You can write a simple browser in like 20 minutes these days. I guarantee that whatever effort you spend building an AppleHelp clone, you will get a better result (today and in the future) than the same amount of time spent reverse-engineering AppleHelp.
I wish AppleHelp got maintained and documented, because a usable help system would be a great addition to the macOS developer toolkit. My second wish is that Apple put a bullet in its head, because in its current state it's quicksand for helpful developers.
I happened to be updating my help documentation when I took some time off to search for alternatives to the agony. I'm using Help Crafter, available on the App Store. Without it, I'd have given up long ago. Sadly, it is hard to find on the store and the developer seems to have moved on.
Very interesting...
I would edit some existing Apple File for my personal use.
I suppose that it's possible ?
What tool would you recommend me?
Thanks in advance
