Apple Help Books are just a bunch of usual HTML files in a folder. Add some images, maybe CSS support and a help index, and your Apple Help Book is done. — This much is ad.
Of course we use UDO, the Universal DOcument Format application. UDO can create finished HTML files for the Apple Help Book format very easily. If you are interested to create manuals in various formats from a simple source format, just take a look at UDO right now or later. But of course you can use any other appropriate tool for creating your HTML files.
This much is important, that the index.htm (or however your home page for the help book is named) contains the following lines in the HTML head:
<meta name="AppleTitle" content="iCalamus Help">
<meta name="AppleIcon" content="iCalamus%20Help/img/iC_feather_16.png">
These example lines refer to our iCalamus Help Books. Of course your content values will be somewhat else. Please note that spaces (and maybe localized special characters) have to be coded in the right URL format!
The help books have to be placed in the folder Resources in their appropriate localized .lproj subfolders. These Help folders may contain just everything, e.g. more subfolders for images or CSS files. We recommend to place an index.htm or similar file as homepage file directly in the Help folder, even if other help book pages may be placed in subfolders.
Important: Apple Help Viewer cannot reference to files outside a Help folder until now. Thus you cannot place e.g. all image files which could be shared by all languages in a shared folder outside the various localized Help folders. This may increase the application package size a bit.
We suggest that you use a unique folder name for your Help Books although you might want to localize the folder names, too. Localization of folder names within the Resources folder in an application package doesn't play a major role.
Add two new key-value pairs to the Info.plist of your application, as follows:
<key>CFBundleHelpBookFolder</key>
<string>iCalamus Help</string>
<key>CFBundleHelpBookName</key>
<string>iCalamus Help</string>
This way Apple Help Viewer gets general information about a non-localized Help Book of your application.
We originate that you have already organized your language specific files (.nib, .strings, etc.) within the Resources folder in language folders. In the past, folder names like English.lproj, German.lproj, etc. were used. Apple now recommends to use the ISO identifiers, so the example folders mentioned just now should be named en.lproj and de.lproj now.
Create the following files if they do not exist already (we continue using iCalamus in our examples and show the already supported languages in iCalamus right now):
/Resources/English.lproj/InfoPlist.strings
/Resources/cs.lproj/InfoPlist.strings
/Resources/da.lproj/InfoPlist.strings
/Resources/de.lproj/InfoPlist.strings
/Resources/fr.lproj/InfoPlist.strings
/Resources/it.lproj/InfoPlist.strings
/Resources/lv.lproj/InfoPlist.strings
/Resources/nl.lproj/InfoPlist.strings
/Resources/pl.lproj/InfoPlist.strings
/Resources/sv.lproj/InfoPlist.strings
Now enter the following localized CFBundleHelpBookName string in all these files, like the following example (of course it's iCalamus again):
English.lproj/InfoPlist.strings:
CFBundleHelpBookName = "iCalamus Help";
cs.lproj/InfoPlist.strings:
CFBundleHelpBookName = "Nápověda iCalamusu";
da.lproj/InfoPlist.strings:
CFBundleHelpBookName = "iCalamus-hjælp";
de.lproj/InfoPlist.strings:
CFBundleHelpBookName = "iCalamus-Hilfe";
fr.lproj/InfoPlist.strings:
CFBundleHelpBookName = "Aide d'iCalamus";
it.lproj/InfoPlist.strings:
CFBundleHelpBookName = "Aiuto iCalamus";
lv.lproj/InfoPlist.strings:
CFBundleHelpBookName = "iCalamus palīdzība";
nl.lproj/InfoPlist.strings:
CFBundleHelpBookName = "iCalamus Help";
pl.lproj/InfoPlist.strings:
CFBundleHelpBookName = "Pomoc iCalamusa";
sv.lproj/InfoPlist.strings:
CFBundleHelpBookName = "iCalamus Hjälp";
These files inform Apple Help Viewer, which localized names of the localized Help Books it must list in its Library menu.
You have to tell Cocoa that choosing a distinct menu item should open Apple Help Viewer. Open your application MainMenu.nib in Interface Builder and connect the menu entry 'Help > AppName Help' with the action [NSApplication showHelp]. Repeat this for all localized versions of MainMenu.nib. (Select the relevant menu entry in IB, open the inspector and choose 'Connections > Target/Action': showHelp:.
This function belongs to the class NSApplication and doesn't need to be called in the source code of your application. It's already assigned in the NIB accordingly. This means: Zero code lines for showing your Help Books!
In order to let Apple Help Viewer find keywords faster in your help files, you have to index them. This is done by the Help Indexer. You should find this tool right here:
/Developer/Applications/Utilities/Help Indexer.app.
When you start Help Indexer you will see just a simple dialog:
Click on 'Select' and browse to the help folder of the first language for which you want to create a help index (Czech in our following example).
After that Help Indexer should look almost like this:
Do not click on 'Create Index' now! You should set some preferences first. Open the Help Indexer 'Preferences' dialog now — you know where.
The interesting options here are 'Use remote root for missing files and updates' and 'Prefer network files to local files'. These options allow you to activate the underlying elegance of Apple Help Viewer as it should basically try and get the requested help pages from your online server first instead of loading the (maybe already outdated) pages offline from your application package. Enter your online manual URL in the edit field like shown in our example.
Now you can close the Preferences dialog with 'OK' and create your first index. You will then see a file named iCalamus Help.helpindex in the help folder.
Apple Help Viewer gets all information about the help books of your application from these files.
For all other languages you now have to repeat the steps as described above:
Offline HTML pages which Apple Help Viewer reads from the application package, have to be pure HTML files, which may even include CSS files, but have to dispense with all other luxuries. Use the advantage that Apple Help Viewer can be forced to prefer online pages from your web server. You might want to pimp your online pages with e.g. PHP or other functions which are shown in the Apple Help Viewer like in any other usual browser.
Because Apple Help Viewer cannot deal with .php files, you have to declare the desired file extensions for the PHP parser on your web server, be it .html or .htm files. Your ISP (Internet Service Provider) will tell you how to manage this. Often web pages are served by an Apache server, so you have to adjust its httpd.conf file accordingly to let the PHP parser on the server parse .html or .htm files for PHP code, too.
We have decided to use the extension .html for pure HTML files and use .htm for files which also may contain PHP code. This way we can create the finished pure HTML files for the application package very fast with UDO (see above). Then we exchange the HTML head and foot by PHP code, using a RegEx search over all .htm files, in order to e.g. embed PHPWebNotes in the online pages. This free available script from the web offers to add user contributed notes to manual pages online. Many web programmers are surely familiar with this invaluable function from the PHP online manual.
An example showing this is – what else would you have expected – our iCalamus manual.