macOS No Help Book

[Senor Cuete]

I "upgraded" to XCode 13.1. I made some changes to my code and built the project. I want to release a new version to the App Store but I found that the new build has no Help Book. The Help Viewer window appears but there is no content. When I launch Help XCode logs:
2021-11-01 08:27:56.065040-0600 Appname[1563:27743] Entering AHRegisterHelpBookWithURL - which is normal. I didn't edit the property lists or the Appname.help bundle. Everything in the .plists looks right as described in the 2013!!! Help Authoring Guide. This looks like an XCode bug to me. Looking at the forums at the Apple developer website I see that someone else experienced the same problem. Any suggestions?

 

[casperes1996]

My immediate thought is to try and download the latest Xcode Beta release and see if it behaves differently.
Alternatively you should also be able to download older releases from the developer portal

 

[krissimon]

I have the same problem. As I mentioned in the Developer Forum (https://developer.apple.com/forums/thread/693559?login=true&page=1#693490022), i beleve it is a macos Monterey bug. All .help bundles are normal folders after I updated to 12.0.1.

 

[Senor Cuete]

In an attempt to troubleshoot this I went over the ancient crappy documentation. The localization folder and CFBundleDevelopmentRegion used to be English.lproj but now in different places it the documentation it says the should be en, en_US, en_us or en-us or en-US.

 

[casperes1996]

In an attempt to troubleshoot this I went over the ancient crappy documentation. The localization folder and CFBundleDevelopmentRegion used to be English.lproj but now in different places it the documentation it says the should be en, en_US, en_us or en-us or en-US.

So did changing this fix anything for you?

 

[Senor Cuete]

So did changing this fix anything for you?

No. This is probably a bug in XCode, since older versions of the software still display the Help Book Correctly.

 

[Senor Cuete]

More bad news: I restored an earlier version of XCode from my Time Machine backup disk. When I launch it it says that it's incompatible with macOS 12 Monterey and to get the latest version XCode - 13.1 from the App Store. I guess we'll have to wait for Apple to fix this.

 

[Senor Cuete]

To update my application I'll have to create a separate volume on my hard drive and install earlier versions of macOS and XCode. This page:https://developer.apple.com/download/ says that I can do it. It links to another page, https://support.apple.com/en-us/HT208891, that tells how to create a volume and install the earlier OS but there's no link to a description of where to get XCode 12. Does anyone know how to get this?

 

[casperes1996]

To update my application I'll have to create a separate volume on my hard drive and install earlier versions of macOS and XCode. This page:https://developer.apple.com/download/ says that I can do it. It links to another page, https://support.apple.com/en-us/HT208891, that tells how to create a volume and install the earlier OS but there's no link to a description of where to get XCode 12. Does anyone know how to get this?

Follow your first link there and hit "more" in the top right. Then you can just search for Xcode 12

 

[Senor Cuete]

More bad news: I decided to Install macOS 11 Big Sur on another volume. After It took three hours to download, the installer reported an error:

"Install macOS Big Sur" cannot be opened from a newer version of macOS. For more information, visit https://support.apple.com/HT201372

I am creating an installer on an external drive using the terminal command:

sudo /Applications/Install\ macOS\ Big\ Sur.app/Contents/Resources/createinstallmedia --volume /Volumes/discName.

 

[Senor Cuete]

I successfully created a bootable volume with macOS 11 Big Sur. It took more than 24 hours to download, install move my files over and verify everything. I got the .xip of XCode 12 from the developer site. macOS 12.1 Monterey wont run the .xip because it's not signed by a developer. I have to go to the System Preferences -> Security & Privacy control panel and tell it to open it anyway but it can't because Archive Utility posts an alert: "Unable to expand "XCode_12.5.1.xip". It is in an unsupported format.

Seriously? WTF?

 

[casperes1996]

I successfully created a bootable volume with macOS 11 Big Sur. It took more than 24 hours to download, install move my files over and verify everything. I got the .xip of XCode 12 from the developer site. macOS 12.1 Monterey wont run the .xip because it's not signed by a developer. I have to go to the System Preferences -> Security & Privacy control panel and tell it to open it anyway but it can't because Archive Utility posts an alert: "Unable to expand "XCode_12.5.1.xip". It is in an unsupported format.

Seriously? WTF?

That sounds to me like something went wrong during the download. The xip should be signed and work just fine.
Why are you opening it from Monterey and not Big Sur?
I recommend re-downloading the Xcode xip.

 

[Senor Cuete]

I tried to unzip it with both OSes. On both it verifies the .xip then says it's unsigned. In order to unzip it I have to tell Security to unzip it anyway and then both versions of Archive Utility refuse to unzip a .xip file. There's one other possibility - to try to restore an older version of XCode with Time Machine. This should be a cautionary tale for anyone else who wants to go back to an older OS / XCode to get around Apple's big screwup with XCode 13. Maybe you want to think twice about that...

 

[nili49]

Back to the original problem: When I run my program in XCode, my Helpbook is empty. But when I put the program in the Applications folder and open the program, the helpbook reappears. I guess it is not a problem of Xcode but of Monterey.

 

[prime17569]

@Senor Cuete

Have you tried with Xcode 13.0 on Monterey? 13.0 includes the Big Sur SDK so this might help you to figure out if this is an SDK or macOS bug.

EDIT: Also might be worth it to move one of the system apps (e.g. Chess) out of Applications and see if it has the same issue. (Chess.app is open source - opensource.apple.com - so you can see what they're doing with the Help book.)

 

[Senor Cuete]

As a Mac developer I feel that I should always upgrade to the newest OS and XCode to be sure my applications will run on the newest software for my clients so I'm running macOS Monterey 12.0.1 and XCode 13.1. I found out that applications will display the Help Book *IF* the applications are in the Applications directory. But Monterey has a second horrible bug - the exit(173) bug that I asked about in the other thread. This is a problem in Monterey that will only be fixed in a macOS update. Looking at the Apple developer forums and bug reports, it's obvious that a great many other developers have the same problem and can't update their apps at the App Store until this is fixed. I filed a support incident twice on this and developer support just trashes the request. This leads me to think that they can't help with this and as a developer you can't do anything about it and they will fix it - someday hopefully.

If anyone is using a beta release of macOS It would be very helpful if you would call exit(173) in your app and see what happens. Maybe this will be fixed in a newer Monterey.

 

[prime17569]

As a Mac developer I feel that I should always upgrade to the newest OS and XCode to be sure my applications will run on the newest software for my clients so I'm running macOS Monterey 12.0.1 and XCode 13.1.

That makes sense. I was simply wondering whether it was an SDK bug or an OS bug. Using Xcode 13.0 would help you figure out precisely what the problem is, since it runs on Monterey but has the Big Sur SDK. (And, if this is an SDK bug, you should still be able to use the Big Sur SDK for some time until Apple mandates the Monterey SDK - hopefully, they fix the bug by then.)

BTW I'm still using Xcode 13.0 to compile my apps (SwiftUI & Mac Catalyst) for the Mac because it looks like there are some SwiftUI view metrics changes (padding, spacing, etc.) in the Monterey SDK, and I'm not yet ready to deal with those. My app works fine on Monterey.

About the exit(173) bug, please see my post on the other thread: https://forums.macrumors.com/threads/no-receipt.2323233/post-30630816

 

[Senor Cuete]

This is fixed in macOS 12.2.

 

[prime17569]

This is fixed in macOS 12.2.

Great!

Apple should do more releases that are purely bug fixes like this one. Perhaps they should have each point release alternate between bug fixes and new features like they're doing with 12.2 which has quite a few security and bug fixes but no new APIs and 12.3 which introduces Universal Control and many other new APIs and features.

 

[Endre Olah]

Hi Guys, I am new in Help Book preparation. I could get to the point until my Help Book appears and could set the TOC button active, but the documentation is so weak that it would be great if somebody could help me with a working example of a Help Book. If somebody might share a book.help folder of a project, I would really appreciate it.

 

[Senor Cuete]

A Help Book is basically just a .html web site. You should structure it the way that they do it in the help authoring guide. The main page has to have a few special tags in its metadata. It has to be registered with a few fields in the info.plists. Then it will be registered with the app and open when the app's help menu is hit it will invoke first responder-> show help.