Documentation for creating Apple Help Book support can be found here. Basically, one needs to specify both the Help Book directory (folder) name and the Help Book name (AppleTitle meta tag). The application must also have a unique Bundle ID so that the Help Viewer can reference the application. The Help Book consists of pure HTML files, images, and optional CSS styling. It is easy to create and develop a Help Book outside of the application. The "Hello, World" Help Book HTML can be used as a starter or checkout any application's exiting Help Book folder now that you know where to find it.
The Help Book viewer does not automatcially open the file named index.html as does a web server. The root file must contain a META tag specifing the name AppleTitle. The content of this tag must match the value specified in the helpbookname attributer of the jarbundler task. This META tag is used to both designate the root HTML file and its content is used by the Help Viewer in its "Library" listing.
<html>
<head>
.
.
<meta name="AppleTitle" content="Hello World Help"/>
.
.
</head>
Finally, the developer needs to create a JNI library in order to communicate between the "Help" menu item and the "Help Book Viewer" or whichever application is being used to render Help Book help. This is a very simple file and usage is demonstrated in the "Hello, World" example. Windows and Linux users will not be able to generate the JNI library on their platforms. In order to generate a univeral binary JNI you can use Xcode and the tutorial found here. This process can only be done under Mac OS X with the "Apple Developer Tools" installed. Windows and Linux developer will have to obtain the JNI library from a Mac OS X system.
The example/build.xml file shows how to create a JNI library from source with ANT using command lines.
The application created in this example will have a single Help Book located at Contents/Resources/HelpBook. The next example shows how to support multiple Help Books for different languages.
<jarbundler dir="${basedir}"
.
.
.
helpbookfolder="HelpBook"
helpbookname="Hello World Help" >
<!-- Copy the HelpBook JNI library -->
<javafilelist dir="${basedir}/build" files="libHelpBookJNI.jnilib"/>
<!-- Specify the HelpBook contents -->
<helpbook>
<fileset dir="${basedir}/HelpBook"/>
<helpbook/>
</jarbundler>
The following example shows the use of Help Books to support English, German and Swedish. The default Help Book folder name and Help Book name are set in the JarBundler tag. The English Help Book uses these defaults.
The German Help Book specifes both the Help Book folder name and Help Book name, effectivly overriding the JarBundler defaults.
The Swedish Help Book uses the default Help Book foldername but specifies it's own Help Book name. The Swedish locale is specfied using it's ISO country code, sv. The ISO codes of en and de could have been used in place of English and German.
The directory HelpBook/commom could contain images and CSS stylesheets common to all Help Books. During help book development use a symbolic link to move the common directory into the HTML tree.
<jarbundler dir="${basedir}"
.
.
.
helpbookfolder="HelpBook"
helpbookname="Hello World Help" >
.
.
.
<helpbook locale="English">
<fileset dir="HelpBook/English" />
<fileset dir="HelpBook/common" />
</helpbook>
<helpbook foldername="Hilfebuch" name="Hallo Welt Hilfe" locale="German">
<fileset dir="HelpBook/German" />
<fileset dir="HelpBook/common" />
</helpbook>
<helpbook name="Hjälp" locale="sv">
<fileset dir="HelpBook/Swedish" />
<fileset dir="HelpBook/common" />
</helpbook>
</jarbundler>
During development the Help Viewer sometimes refuses to update the contents of a Help Book which changed. The Apple Developer Docs suggest to delete or edit the file ~/Library/Preferences/com.apple.help.plist. This file contains the list of known Help Books. If you double-click on this file the XML Property Editor applicaiton will be launched and re can 'delete' your bundle ID entry and "save" this file. Deleting this file does no harm but is a less elegant way to deal with the problem.
This document also suggests deleting the folder ~/Library/Caches/com.apple.helpui to help with refresh problem during development.