How to Create a Searchable Help Bo… | Apple Developer Forums

Developer Forums

I read the Apple Help Programming Guide. I very carefully re-organized my help book folders so the help book is localized (which I don't need to do). I had to edit the HTML files to get some links to work. Now that I renamed my help book folder to a .help it's a bundle and the file opening dialog in the 2015 Help Indexer application won't open it so I have to create a folder with a copy of the files and use that to create an index since the Help Indexer application doesn't support drag and drop either. Should I be indexing the .help bundle or the English.lproj folder that contains the index in the examples?

The documentation is ambiguous, In the Help Book Registration section it gives two examples of how to register the help Book. First it says the <key>CFBundleHelpBookFolder</key> should be <string>SurfWriter.Help</string> then in the illustration it has it as Surf Writer Help. Then it has the <key>CFBundleHelpBookName</key> as <string>com.mycompany.surfwriter.help</string> but in the illustration it has it as Surf Writer Help. Which is it?

The help Book is still not searchable but I'll clear the cache with the terminal command: rm -rf ~/Library/Caches/com.apple.help* and see if it helps.

Like almost all of the Developer documentation the Apple Help Programming guide is not current and needs work.

Sorry if these questions have been asked before. The Developer Forums seem to be broken. No matter what I search for there are no previous posts.

macOS

2.8k

Posted by

Tlaloc

Reply

Accepted Reply

There is nothing wrong with my help book. When I have problems like this one I tend to think it's my fault and re-read the documentation. My Help Book is configured correctly. The problem is that XCode 13, or more likely macOS Monterey 12.0.1 will only display the Help Book if the application bundle is in the Applications folder. So problem solved, sort of, you can't display the Help Book while debugging your Mac App in XCode. You have to archive it and export it to the Applications folder to see the Help Book. I can't update my application at the App Store anyway because of the infamous exit(173) bug in macOS Monterey.

Also the hiutil (Help Indexer app) does nothing in Monterey anyway so don't bother creating a help Index.

Posted by

Tlaloc

THANK YOU! I never would have figured that out on my own.

—
avitzur
Oh my. I spent almost an afternoon on this issue. Thank you! Btw, we can just copy the debug one to the Application folder to do testing.

—
Kjuly

Replies

The keys in the .plists are displayed differently in XCode than they actually are in the file. For example when you open the application’s .plist in Xcode it shows the CFBundleHelpBookName as Help Book Name. This is not helpful. In the Apple Help Programming Guide these are given as their actual names in the <key> fields so I advise you to open and edit them with an external editor like BBEdit.

The CFBundleHelpBookFolder should be appname.help (name of the help bundle).

The CFBundleHelpBookName should be the title of the Help Book as it is in the Apple Title meta tag in the home page of the Help Book as it is in the illustration, NOT com.mycompany.appname.help as it says in the text.

Because Help Books are cached you will have to clear the cache every time you edit the Help Book with the terminal command rm -rf ~/Library/Caches/com.apple.help*

The Apple Help Programming Guide is poor and out of date. An example of how to add a Help book to your application can be found on GitHub:

https://github.com/Red-Menace/RubyMotionRonin/tree/master/Help%20Book%20Sample.

The Help Indexer application you can download from Xcode Additional Tools is terrible: It can’t open files in a bundle so you have to create your Help Book as a folder and rename it as a .help when you’re done, before adding it to your .xcodeproj.

I can follow the instructions to give my application a Help Book but I want it to be searchable. After many hours of trying I find that it’s impossible to do it. The guide says to put the .helpindex in the localized .lproj folder and include its name in the Help Book’s info.plist in the HPDBookIndexPath key. This doesn’t work.

Adding a Help Book to a Mac application has been a real PITA for years. This is something that Apple should improve.

Posted by

Tlaloc

Update: Apple is still telling developers to include a Help Book in its User interface guidelines, BUT:

Apple help viewer is buggy - some things don't even work. The documentation is terrible and hasn't been updated since a minor change - IN 2013! The Help indexer application is terrible and is from 2015. It is no longer available from Apple.

If Apple wants to get rid of Help Books it should just tell us. This is a terrible way to do it and this is a terrible way to treat developers.

Posted by

Tlaloc

Based on posts I found, with newer versions of the OS you have to create
an index using the hiutil command in the terminal. The type of index
file created by the indexer application won't work. Of course this is
completely undocumented. hiutil can create two types if index files.
Supposedly you have to create the type that's used by Spotlight. The
documentation mentions hiutil and hiutil(1). Although I have been
programming the Mac since 1988 I have absolutely no idea of how to use
terminal commands so when I type man hiutil into the terminal it's just
complete ishcabibble to me. Computers with GUIs were invented so you
wouldn't have to deal with very complex command line programming. It
seems ironic that I would have to learn ANOTHER very complex technology
just to create one file in my application. If anyone has any guidance
about what terminal command to enter I'll try it, otherwise I won't
bother.

Posted by

Tlaloc

In order to do less typing I set the working directory to the Resources directory in the help bundle, using the chdir pathname command.
I use the command: hiutil -Cf Resources/English.lproj/help.helpindex English.lproj
This creates a help.helpindex file in the English.lproj folder. As per the documentation the other html files are in a sub directory.
To be sure that I'm not looking at a cached version of the application's help I use the terminal command:
rm -rf ~/Library/Caches/com.apple.help*
The name of the help.helpindex file is in the help bundle's info.plist file in the HPDBookIndexPath dictionary.

My application's help is still not searchable. Only the main help page is searchable. When I open the index file with BBEdit I see lots of keywords from the other html files but the Help application won't find them. Using the parameter -Caf doesn't help. it's likely that I need some other file specifier but I can't see what it would be.

Posted by

Tlaloc

After reading a lot of comments on internet forums about this and trying to make it work with XCode I have concluded that Apple broke the Help Book authoring tools, documentation and API's with OS 10.14 and didn't bother to tell developers. Thanks, Apple.

Posted by

Tlaloc

It's obnoxious isn't it. What did you end up doing? I'm thinking of a few options...

Include HTML in bundle, display in WKWebView within my app.
Include HTML in bundle, send user to web browser to view.
Include a PDF in bundle, send user to Preview or whatever to view it.
Try a Help Book, even though the docs are 8 years old and I see lots of confusing posts online about it.

Posted by

rnikander

I created an html help book in a .help bundle in my application and use Help Viewer as I always did years ago. Apple still uses help books in its own applications. The help menu item in the menu bar is linked to firstResponder: showHelp which shows the help book if the Help Book directory Name and Help Book Identifier in the application .plist are the name of the helpbook.help bundle. The MainMenu.xib's file owner is an NSApplication. This provides the showHelp IBAction.

Posted by

Tlaloc

Ahh... the joy of Apple Help programming!

Great (Nov. 2021) post on the topic:

"Why won’t that Help book open?", https://eclecticlight.co/2021/11/16/why-wont-that-help-book-open/

Provides some tips when working on Help Books.

I've found that copying an existing (e.g. Apple) help book and starting from there (adding content for your own app) worked best for me in the past.

Even managed to enable print for (local) Help Books via reverse engineering Apple's user guides, something my users have been asking for.

Posted by

JayMcBee

There is nothing wrong with my help book. When I have problems like this one I tend to think it's my fault and re-read the documentation. My Help Book is configured correctly. The problem is that XCode 13, or more likely macOS Monterey 12.0.1 will only display the Help Book if the application bundle is in the Applications folder. So problem solved, sort of, you can't display the Help Book while debugging your Mac App in XCode. You have to archive it and export it to the Applications folder to see the Help Book. I can't update my application at the App Store anyway because of the infamous exit(173) bug in macOS Monterey.

Also the hiutil (Help Indexer app) does nothing in Monterey anyway so don't bother creating a help Index.

Posted by

Tlaloc

THANK YOU! I never would have figured that out on my own.

—
avitzur
Oh my. I spent almost an afternoon on this issue. Thank you! Btw, we can just copy the debug one to the Application folder to do testing.

—
Kjuly

Another thing I learned is that at least on Monterey if you do not include a PkgInfo file containing the text "BNDLhbwr" (without the quotes) inside your help bundle, Finder will not recognize it as such and it will continue to display it as a normal folder. I discovered this through trial and error using Xcode's PkgInfo as a starting point to force this.

Posted by

jvarela

Is a Pkginfo file just a file with the ".Pkginfo" file extension? Is this documented anywhere?

Posted by

Tlaloc

I got it - putting a file named "PkgInfo" with the text "BNDLhbwr" in my appname.help/Contents folder turns the .help folder into a package. This is interesting but it doesn't fix the no help book bug. The help Book will only be displayed if the app bundle is in the Applications folder. Also as far as I can tell this is an undocumented "feature" of macOS Monterey 12.0.1.

Posted by

Tlaloc

I was also trying to find information about how to create a help book. With the information found on this page and on the old Apple Help Programming Guide I was able to create a working help book. I have created a blog post that describes the steps I took: https://fred.appelman.net/?p=196

Creating a link is not allowed, so you have to do copy paste for this.

Posted by

FredA