In the previous article, I showed how to make a set of (X)HTML files which should provide the content for a Help Book, and can be added to a Mac app in development to provide good support for that app’s help. Now comes the proof of that pudding: building the Help Book.
Before going any further, I made a Zip archive of the working folder in case I screwed anything up. I then stripped out the unwanted items from Tinderbox’s export, being the folder Prototypes and Prototypes.html. This leaves index.html, four body pages, two images, and my basic.css stylesheet, in a flat structure.
The next step is to build that folder into the correct hierarchy for the Help bundle. For the top level, I created a folder named LockRattler, the same as the app for which it is designated. Within that goes Contents, then inside that Resources, and finally my export folder from Tinderbox. That last item has to be renamed to a localised language folder such as en.lproj, which contains the English localisation. You can also use, as appropriate, en-GB.lproj for British English, uk.lproj, fr.lproj, de.lproj, and so on according to the language localisation.
Within en.lproj, together with my exported Tinderbox files, I created a file named InfoPlist.strings, which contains localised versions of any strings needed in the main Info.plist. In this case, I just used
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
I also made an icon file, which will be used for my Help Book when results are displayed in a search. This should be a 256 pixel square in JPEG format, and I placed that in the Resources folder, alongside my en.lproj folder.
The key file to create next is the Info.plist to be stored in the Contents folder, alongside the Resources folder. This is all standard, and can be copied from any other example. There are six values which need to be set carefully, and should be self-explanatory:
If you lay your Resources folder out differently, you will need to ensure that those paths are correct.
This completes all the content for the Help bundle apart from the Help Index, so I made a Zip archive of the folder in case things went wrong.
Creating the Help Index is a precarious business. The fundamental tool is the command tool
hiutil, which Apple has wrapped in a friendly front-end in its Help Indexer app, one of the supplementary tools for Xcode. Both seem to throw lots of errors which appear alarming, but the Help Index usually gets built just the same.
If you prefer to do this in Terminal, a standard command goes something like
hiutil -Caf lockrattler.helpindex LockRattler
when it is run from the folder just above the help folder. You can then check the index with a command like
hiutil -Af lockrattler.helpindex
which should list the body pages included.
I then put that Help Index, named lockrattler.helpindex, in the en.lproj folder, and checked the names against the Info.plist to make sure that they tallied. To turn that top-level folder, currently named LockRattler, into a Help bundle, I simply appended the
.help extension to it.
The final stage of adding help support is to incorporate your complete Help bundle into your Xcode project. I opened that project folder, and created a folder there named Resources, within the project. I then copied the LockRattler.help bundle into that Resources folder.
Simply placing the bundle in the right place does not include it in the project, though. I opened the LockRattler project in Xcode, incremented its version numbers ready to build a new release, and then added the Help bundle to the project through the Add Files to “LockRattler”… command in the File menu.
There are now two very important changes which must be made to the app’s Info.plist file. Rather than editing them directly, I went through Xcode’s interface to them, by selecting the project and then the Info section of its settings. I added two new entries there, by selecting an existing entry and clicking on the + item which appears next to that item’s key:
Help Book directory name – a String – whose value is
Help Book identifier – also a String – whose value is
I then checked those again against the Help Book name, and the CFBundleIdentifier I gave in the Help Book’s Info.plist. I also selected the app’s Info.plist file directly to check that Xcode had changed that correctly.
Whilst I was doing this, I added a full set of Tooltips to the app’s window. I then ran a Clean to ensure that the next build would be from scratch, built it to run, and tested the app out.
If this is the first time that your app has had a Help Book, Xcode appears to ensure that is properly registered with the help system. If it has already had a Help Book and this is just an update, you may find that the changed Help Book is not used. This is because of the way that Help Book registration works. You will then need to install your new version in /Applications to induce the
helpd service to recognise and use the new Help Book properly.
When testing your Help Book in the app, don’t forget to try some searches which should return hits from it.
My last step now before deciding that an app is ready for release is to check its signature. This is accomplished from the command line, using (for example)
codesign --verify --verbose LockRattler.app
When everything is looking good, it is time to ship the finished app.
If you want to explore my completed help folder, ready to be made into the Help bundle, it is here: lockrattlerhelp
You can of course look into LockRattler 3.3, which is available from the Downloads item in the menu above.