Application "help" menu does not open main help book page

Question

konradedgar OP

Created 5d

Replies 3

Boosts 0

Participants 2

Following the official documentation, I'm trying to create a set of three localised Help Books.

The Help Books should be available in Spanish, English and Polish. Presently, I'm trying to complete English version.

App Structure

This is the plugin application consisting of main app and the plugin. The main app structure would looks as follows:

Files

. <XcodeProject Top>
├── Localizable.xcstrings
├── MyAppExtension
│   ├── MyAppExtension.swift
│   └── <other swift files>.swift
├──MyApp
│   ├── Info.plist
│   ├── +Array.swift
│   ├── +ButtonStyle.swift
│   ├── <other app swift files>.swift
├── Resources
    └── MyApp.help
                └── MyApp.help
                      └── Contents
                      ├── Info.plist
                      └── Resources
                          ├── English.lproj
                          │   ├── ExactMatch.plist
                          │   ├── InfoPlist.strings
                          │   ├── MyApp.helpindex
                          │   ├── MyApp.html
                          │   └── pgs
                          └── shrd

MyApp / MyApp.help / Info.plist file

Consists the following values:

Bundle name: MyApp
HPDBookAccessPath: MyApp.html
HPDBookTitle: My App Help
Default localization: en_gb

MyApp / Info.plist file

Contains the following entries:

Help Book directory name: MyApp.help
Help Book Identifier: MyApp Help
<other not related>

Build phase

The Copy Bundle Resources copies MyApp.help in MyApp/Resources.

Questions

Is the provided folder structure valid for creating a localised help books
Is there anything that is missing from across Info.plist files or is in the wrong places?
Why the MyApp -> Help opens the main help menu, not the app help

Boost

Answer 1

Etresoft OP

5d

Is the provided folder structure valid for creating a localised help books

I doubt it.

Is there anything that is missing from across Info.plist files or is in the wrong places?

It's hard to say. Many of these values are app-specific. They are correct only if they correspond to your app's specific files.

Why the MyApp -> Help opens the main help menu, not the app help

I don't understand your question.

Generally speaking, building an official help bundle is very difficult. There were some major functionality bugs for many years. I don't know if they ever got fixed. Very few developers bother with help bundles. Most just configure the help operation to open a page on their web site. And yes, as you might expect, those help pages are regularly broken.

Your diagram is showing the organization of your Xcode project. As far as the help project goes, all of that is irrelevant. What matters is the final output. I can't say for sure if your project will work or not. You'll have to test it yourself. You will probably only be able to test it when it is installed in /Applications. That was true at one time at least.

Help books are very delicate. The best course of action is to find one of those rare 3rd party apps that has one that works and copy what they've done. You can't copy Apple apps because they do really wild things with help that you can't replicate.

0

Answer 2

konradedgar OP

4d

Thanks for taking the time to comment on my question. Yes, I can see that the whole help mechanism looks very delicate. Although there are some elements that appeal to me, like ability to nicely integrate contextual help.

Sorry for the vague, question let me clarify. When you try to access help, which functions correctly, let's say in Safari following menu options Help -> Safari Help will open a page with Safari help welcome page. The title you see says Safari User Guide.

I'm not able to achieve that outcome in my app. When I follow menu options MyApp -> MyApp Help, the help viewer does not open on the landing page for MyApp but on the generic welcome page. The title says Need help? Find answers here.

Concerning your point:

Help books are very delicate. The best course of action is to find one of those rare 3rd party apps that has one that works and copy what they've done. You can't copy Apple apps because they do really wild things with help that you can't replicate.

I reckon this may be a very good suggestion, I'll definitely have a look also happy to consider any pointers of good projects with nicely implemented help. https://github.com/scris/skim-pdf has decently implemented multilingual help so I will start there.

0

Answer 3

Etresoft OP

3d

Don't put too much time into it. I just double-checked and I don't see any changes. It still seems fundamentally broken.

The biggest problem I encountered was that the "anchor" functionality doesn't work anymore. I can't confirm this because I'm not using a true help book anymore. But it still seems broken. I can use the hiutil tool to create a help index file, but the same tool can't read a help index file. That ultimately seemed to be the reason that caused anchors to be broken.

While Skim is using a true help book, it looks like they haven't updated it in years. For example, it doesn't support dark mode. Apple did eventually update the help UI to support dark mode, so I know this works.

Also, debugging is difficult. The system will cache the first help book it finds for your app and won't ever look again. You'll need to manually kill the "helpd" process to get it to load a new help book. It might also only look for help books in /Applications.

It was just way too many hassles for me. I implemented my own help UI and that works great. It works very similarly to Apple's UI and solves all the problems I mentioned above. I used to publish it on GitHub, but nobody cares about Mac help.

And finally, one thing that Apple has changed recently is not a good change. Before, the help UI was a floating window in your app. Now, the help is run by the new "Tips" app. So when users want help, it takes them out of your app. Plus, the built-in help search functionality will search all apps, potentially showing your users some great features in competing apps.

My solution was a fixed UI with a real help book underneath. My app's help would still be incorporated into the system help, but without all the downsides. Unfortunately, because help apps are so rare, a certain developer of a popular app checker app started to flag my app as being suspicious because my help bundle didn't have a separate signature from the rest of the app. Obviously that's wrong, but what can you do?

There are lots of reasons to build your own help, and many reasons to avoid Apple's help architecture.

0