Xcode 9 - Can't Update Help Book

Developer Tools & Services Xcode Xcode

Created Sep ’17

Replies 22

Boosts 0

Views 5.9k

Participants 3

I "upgraded" to XCode 9 today, hoping that it would support the new ISO Appendix K safe string functions (it doesn't). It has always been difficult to get XCode to update a Mac application's Help Book. In the past I have been able to do it by following these instructions:

Delete any other versions of the app and empty the trash.

Update the Help.plist

Create a new Help.helpindex file using the Help Indexer

Remove the help folder from project.

Delete the system’s cached help folder using the terminal command: rm -rf ~/Library/Caches/com.apple.help*

Sometimes it helps to restart your machine now

Sometimes it helps to execute the termanal command rm -rf ~/Library/Caches/com.apple.help* again

Clean and rebuild the project without the Help folder

Add the new Help folder, clean and rebuild

Check to be sure that the new help book is added

Now this doesn't work. When I run my project with the new Help Book the Help Book window says:

The selected topic is currently unavailable.

The topic you were trying to view could not be found.

XCode logs:

2017-09-20 13:45:49.466114-0600 app[2349:187674] Entering AHRegisterHelpBookWithURL

2017-09-20 13:45:49.466228-0600 app[2349:187674] Entering AHRegisterHelpBookWithURL: 0

Can anyone tell me how to get XCode 9 to do this?

Answered by Tlaloc in 263612022

I got it to work. Important:

1. The help Book authoring guide refers to the Help Book folder as a bundle and shows it in the app bundle hierarchy as a .help bundle DON'T make the Help Book folder a bundle with a .help extension.

2. When you add the Help Folder to the project, be sure to check the radio button in the add files dialog as " Create Folder references..."

3. In XCode 9 dragging the help folder into the project won't automatically include it as a member of the target. Highlight the help folder in the project navigator. in the right pane check the Target Membership check box.

4. Check the strings in the help-Info.plist very carefully. The help-Info.plist strings I had in older versions of the project worked before but not now.

5. In my project I won't have app help unless I include a correct help-Info.plist.

Boost

Easiwriter OP

Dec ’17

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

Tlaloc OP

Aug ’22

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?

Tlaloc OP

Sep ’22

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.

Tlaloc OP

Oct ’23

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:

I deleted the existing version in the Applications folder.
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.

Tlaloc OP

Oct ’23

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.

Tlaloc OP

Oct ’23

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.

Tlaloc OP

Nov ’23

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.