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 :-)

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.