Xcode 9 - Can't Update Help Book

I trashed the cached versions of the app in:

username>Library>Developer>XCode>Derived Data>appname-(long text of goblygook).Build.Products>Debug>App

and ... > Release.

I read the Apple Help Programming Guide - How to register Your Help Book.

This one drove me mad for several hours as well. I *think* this will fix it: Follow all the steps you outline above, then do this:

1. Select your help folder in the project navigator in Xcode
2. In the far-right window pane in Xcode (top says, "Identity and Type"), make sure there's a check-box next to your app in the "Target Membership" section.

After I did that, built, and run, Help works normally.

I *really* wish Help wasn't so hard in Xcode. There should be a simple, elegant markdown editor in Xcode that manages all the Help indexing and file creation for you.

Thanks. I checked the check box and help still doesn't work. One important fact that might make a difference: You describe the help "folder". The documentation clearly requires this to be a bundle. Adding the .help suffix makes it a help bundle, not a help folder. The check box isn't mentioned. Yes Help Book authoring is a nightmare, including the poor, out-of-date documentation.

Looking in other Application bundles, the help folders are .help bundles, not folders.

The documentation also says that you can manually register your help Book using AHRegisterHelpBook. This is wrong. This is a 32-bit Carbon function that won't link in a Cocoa project. Also supposedly you can manually register it using BOOL yesOrNo = [[NSHelpManager sharedHelpManager] registerBooksInBundle: [NSBundle mainBundle]]; This will return YES but the help Book will still not be available.

Thanks. This is really curious (and frustrating). The most recent Apple documentation on building a Help Book goes back to 2013.

You’re right about the help file being a bundle in the complied app. When I said “folder”, I meant the folder in the Xcode project before it gets built. I’m assuming that during the project build, Xcode parses the help index file and packages the help folder as a .help bundle within the app bundle.

It’s a little ironic that “Help” is one of the hardest things to get help with in Xcode. 😐

Good news:

If I check the Target Membership box and add the .help suffix to the Help folder (changing it to a help bundle) it will work. It's even pretty flexible about the Help Book Identifier and directory name in the Info.plists.

Bad news:

I can't validate my archived App if the Help Folder is a .help bundle:

Invalid Bundle Identifier. The application bundle contains a tool or framework Appname [com.Appname.pkg/Payload/Appname.app/Contents/Resources/Appname Help.help] using the bundle identifier 'com.Appname.Appname Help.help', which is not a valid bundle identifier.

XCode 9 will be happy to add my Help Book to the App *IF* the help Book Folder is a .help bundle but not if it's a folder. The App store won't validate the archive if the Help Book Folder is a .help bundle. Since this started when I "upgraded" to XCode 9, I'm wondering if this is some peculiarity to the New XCode, not described in the 2011 documentation.

I tried to fix this this problem with various strings in the .plists and the Help Book in a folder and in a .help bundle. XCode 9 won't provide my application with a Help Book if the files are in a folder but it will always do it if the files are in a .help bundle. iTunes won't validate the archive if the project is built with a Help.help bundle. I submitted a bug report.

That's pecular. I haven't added the ".help" extension to my help folder, and it's working fine. Can you create an Xcode project from scratch and get it to work? Here's the general procedure I follow to create a Help Book:

Begin by assuming the app we've written is called, My Cool App

• Use a mark-down editor (like LightPaper) to create your help pages, then export them to html.
• Call the root folder of your help files, MyCoolAppHelp (no spaces)
• Create a 16 x 16 png version of your app icon and put in the root folder of your html help files. Assume it's called, icon-16.png
• Create two meta tags and insert them at the top of the entry file in your help folder (e.g. index.html). The trailing space before the /> is important:
  • <meta name="AppleTitle" content="My Cool App Help" />
  • <meta name="AppleIcon" content="MyCoolAppHelp/icon-16.png" />
• Setting up Help Indexer: Click on Show Details and turn off logging of status messages. Including the status messages for large help files simply produces too much noise that could hide any valid warning or error messages.
• Run Apple's indexer utility on the folder with all your html files. My experience has been that when you run it once, you'll get error messages. If you clear the log and run it again, it works fine -- go figure. This will create a special index file in your folder.
• After you run the indexer, drag the folder with all the html files (including the 16x16 png of the icon) into the project. Make sure to check Copy files if needed.
• Add the two items below to the info.plist file in your project. Help Book Directory Name and Help Book Identifier will be items listed in the pop-up menu.
  • Help Book directory name -> MyCoolAppHelp
  • Help Book identifier -> My Cool App Help

You forgot to mention the .plist that the documentation says you have to have in the Help Book folder.

And the documentation says the Help Book Identifier should be in reverse dns notation ie. com.coolApp.Help Book.

Interesting. I've never done either of those things and Help has always worked for me. The entry on the .plist editor in Xcode says "Help Book Identifier", but when I look at the package contents on the compiled app, the entry in that .plist file says: CFBundleHelpBookName, and everything works, including passing validation testing in iTunes connect.

I built six macOS apps using those Help instructions above, and they all worked fine. Changes are hard (because things get cached all over the place), but the initial implementation of Help went fine.

Help needs help :-)

I got it to work. Important:

Great info! Thanks.

https://developer.apple.com/library/content/documentation/IDEs/Conceptual/AppDistributionGuide/ConfiguringYourApp/ConfiguringYourApp.html

"The bundle ID string must be a uniform type identifier (UTI) that contains only alphanumeric characters (A-Z,a-z,0-9), hyphen (-), and period (.)."

So it looks like you could make your help book a bundle if the name doesn't contain a space.

I had a similar problem in that my app stopped showing the latest help contents after I updated them. Other posts suggested that the problem lay with the library Cache and that deleting com.apple.helpd and com.apple.helpviewer would solve the problem. It did until just last week when the problem came back. I did a search for the bundle identifier and found it in com.apple.parsecd as well. Deleting that fixed the problem

This is happening again with XCode 13.4.1. I have changed the text in my Help Book using the editor in XCode. After clearing the caches, the build folder and jumping through all of the other firey hoops mentioned in this thread it is still building the App with a cached version of the Help Book, so I can't update it. As you can see from this post's history this wound has been festering for at least FOUR YEARS. Does anyone have any ideas of how to fix this?

I filed a bug report with apple. They replied that none of those methods for clearing the old help book will work. HV cached are stored in ~/Library/Caches/com.apple.held. The correct way to clear the cached Help Books is to use the terminal command hiutil -P ~/Library/Caches/com.apple.held. Be sure to delete other versions of the app because the OS might index versions in /Applications and ~/Applications. Interestingly man hiutil in the terminal doesn't list the P flag but it does seem to exist because the command hiutil -P ~/Library/Caches/com.apple.held does seem to delete the cached version of the Help Book.

I worked on my Application. I did NOTHING to change the Help Book except change one small bit of text. I did everything listed in this thread:

1. I deleted the existing version in the Applications folder.
2. I cleared the Help data bases with hiutil -P ~/Library/Caches/com.apple.help.d.

I have done this many times before but now with MacOS Sonoma 14.0 I get errors:

Received termination response from helpd HPDHelpDataIsTerminating: Shutdown request successfully sent to helpd Unable to clear caches at path: /Users/myname/Library/Containers/com.apple.helpviewer Error: Error Domain=NSCocoaErrorDomain Code=513 "“Help Viewer” couldn’t be removed because you don’t have permission to access it." UserInfo={NSUserStringVariant=(Remove), NSFilePath=/Users/myName/Library/Containers/com.apple.helpviewer, NSUnderlyingError=0x600000d90d80 {Error Domain=NSPOSIXErrorDomain Code=1 "Operation not permitted"}} Caches not cleared: There was a problem clearing Help Viewer and helpd cache files, see logs for details

There is nothing relevant in the logs. The Help Book is properly registered in the .plist as it has been for years. When my Application calls showHelp the help window appears with no content but if I search for terms in the Help Book they appear in the Show all Help Topics with the name of the section they are in but clicking on them leads to a page with the warning "The Selected Content is not Available". Is this some new bug for help editing?

Also trying to force the Application to load the Help Book with stuff like [[NSHelpManager sharedHelpManager] registerBooksInBundle: [NSBundle mainBundle]]; does nothing.

XCode isn't logging Entering AHSRegistered Help Book as it should either.

It's pretty weird that my Help Book has worked for a long time now but suddenly stopped after I upgraded to XCode 15.0.1. The .plists are all correct and not changed. The Help Book is correctly registered. You have to wonder why this would suddenly fail. Help Viewer is not currently being supported by Apple and the documentation is TEN YEARS OLD. At this point it would be easier to write my own help viewer. My help files are just html files anyway. Perhaps there is some documentation describing how to display them in an NSWindow with an NSScrollingTextView. It has to be easier than dealing with the agonizing nightmare of AHRegistered help books.

After going over everything over and over I was able to get it to work. The only difference between this and other attempts was that I deleted the old version of the application with Launchpad, not by dragging it to the trash. This may make a difference as far as deleting the caches goes.

Apple Help is a really useful feature. It goes with your application so it's there even if your user is in a remote location with no internet. BUT the implementation is pretty flakey. I'm going to replace it with an NSDocument to make it easier to program and maintain.

I found out that after you delete any other copies of the application and clear the help caches with hiutil -P ~/Library/Caches/com.apple.helpd the help book still won't appear in your app when running it in your development environment with Xcode. BUT if you archive your application and then distribute it, for example as a copy to your applications folder it will.