You should provide an index file in your Help Book folder before building a Mac OS Application. I use Apple's 2015 Help Indexer application. After I run it it creates a file called HelpBookFolderName.helpindex. This appears to do nothing. When I use the application's Help->search menu field to look for keywords in the Help Book they aren't found. Also the title page has a find field that can't find anything. Does anyone have similar problems or solutions to this problem?
Got a tip for us?
Let us know
Become a MacRumors Supporter for $50/year with no ads, ability to filter front page stories, and private forums.
macOS Help Indexer
- Thread starter Senor Cuete
- Start date
- Sort by reaction score
Yes, in the HPDBookIndexPath, but I may have if wrong. I have com.appname.indexfilename. Searching for HPDBookIndexPath in the documentation finds nothing so I'll look in the guide for the creating help books.
I'm reading the Help Book authoring guide. Even when I change it to helpbookfoldername.helpindex it doesn't work. I'll keep reading.
If the name of the index file is 'helpbookfoldername.helpindex', then it should work (I just set all mine to a generic 'help.helpindex').
Note that the help books are cached, so you may not immediately see any changes. When making changes, you might try also changing the help book version (CFBundleShortVersionString) and/or build number (CFBundleVersion) in the help book's Info.plist.
Note that the help books are cached, so you may not immediately see any changes. When making changes, you might try also changing the help book version (CFBundleShortVersionString) and/or build number (CFBundleVersion) in the help book's Info.plist.
Thanks. 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 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 2015 Help Indexer application doesn't support drag and drop. Should I index the .help bundle of the help book or the English.lproj folder that contains it 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 com.mycompany.surfwriter.help but in the illustration it has it as Surf Writer Help. Which is it?
It's 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 up to date and needs work.
Thank you so much for your help.
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 com.mycompany.surfwriter.help but in the illustration it has it as Surf Writer Help. Which is it?
It's 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 up to date and needs work.
Thank you so much for your help.
My help book appears so I must have the two keys right but it's still not searchable. No, clearing the cache doesn't help. The terminal command to index the help book, hiutil(1) is undocumented. so no help there.
I have a help book sample on my GitHub page if you wanted to take a look at what I did there. The example is for a RubyMotion project, but the only real difference is in how the application Info.plist keys are added. I use the Help Indexer.app from the Additional Tools for Xcode (whichever Xcode I have installed).
Thanks. My help book is like yours. The Help indexer App that I have, version 4.3, won't open a package (.help extension) so I can't index the English.lproj folder. I looked for a newer version on Apple Developer Support bu I can't find it or a newer version. I guess I'll have to try the command line indexer.
I am also running version 4.3, but you can go to Apple's Developer Downloads and get the Additional Tools for Xcode for whatever version you are running.
The help bundle is like any other, you can show the package contents and drag the lproj folder(s) onto the indexer - I usually leave off the .help extension in order to navigate it as a regular folder, and only add the extension when I am mostly done.
The help bundle is like any other, you can show the package contents and drag the lproj folder(s) onto the indexer - I usually leave off the .help extension in order to navigate it as a regular folder, and only add the extension when I am mostly done.
The Help Indexer.app in the additional tools for Xcode 12 is still version 4.3, so you might be stuck with temporarily removing (or changing) the .help extension so that it can be navigated as a regular folder.
After spending many hours carefully reading the craptacular Apple Help Programming Guide and reading your github page I have found that it's impossible to get the Apple Help Application to recognize the .helpindex so my Help Book is searchable. Putting the .helpindex in the .lproj folder and putting its name in the <key>HPDBookIndexPath</key> with and without a path does nothing. Thank you so much for your help. I have tried to do this to Mac applications several times over the years but never succeeded. I give up.
I lost quite a bit of hair myself. Searching across help books doesn't seem to kick in unless there is a matching term in the current application, and even then it doesn't pick up on words you would think should match, such as "window". Things do seem to get indexed, but I don't have a clue how it figures out what does. Anymore I just use it for the particular application's documentation or a quick reference and call it good.
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.
I found a pretty good explanation of the hiutil command here:
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.
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'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.
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.
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'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.
After reading many posts about this situation on various internet bulletin boards, etc. I have arrived at the cause of the problem:
Starting with macOS 10.14 Apple broke the whole application Help system, and didn't tell developers or document it in any way.
If you want to provide help (which is required by the Human Interface Guidelines and makes your application better) find some way to do it without trying to use apple's application help system. It F***ed.
Starting with macOS 10.14 Apple broke the whole application Help system, and didn't tell developers or document it in any way.
If you want to provide help (which is required by the Human Interface Guidelines and makes your application better) find some way to do it without trying to use apple's application help system. It F***ed.