关于ios的帮助文档

对于cocoa开发当中出现的帮助文档，是一个非常重要和常用的基本功能。根据apple官方的建议，通常的帮助文档应该放到每个application的资源当中，或者是每个plugin的bundle当中。

对于apple的帮助文档，通常是一个HTML4的帮助文档，并且通过苹果官方的help viewer去查找和使用帮助文档。

在使用帮助文档的时候，需要注意，帮助文档必须首先进行了注册，否则的话help viewer是无法找到的。对于help而言，是完全可以定义扩展名为.bundle的文件，而扩展名为.help的帮助文件是留给apple自己使用的，第三方公司是无权使用的。

注册的方法分为，使用info.plist自动注册，或者使用API进行注册使用。

Editing the Information Property List File

To register a help book, you need to include the CFBundleHelpBookFolder and CFBundleHelpBookName keys in your Info.plist file. The CFBundleHelpBookFolder key identifies the help book folder; the value associated with this key should be a string specifying the folder name. For example, here is how you would enter the name of the SurfWriter help book folder:

<key>CFBundleHelpBookFolder</key>

<string>SurfWriter.Help</string>

The CFBundleHelpBookName key identifies the help book. The value associated with this key should be a string specifying the help book title, as defined by the AppleTitle tag in the title page of the book. For example, here is how you would enter the title of the SurfWriter Help book:

<key>CFBundleHelpBookName</key>

<string>com.mycompany.surfwriter.help</string>

Using the Apple Help Registration Function

Applications that call Apple Help functions must first call the Apple Help function AHRegisterHelpBookWithURL to register their help book. You would typically do this during application initialization. Once your application has called AHRegisterHelpBookWithURL, your help content is accessible through the use of the Apple Help functions.

OSStatus RegisterMyHelpBook(void)

{

CFBundleRef myApplicationBundle;

CFURLRef myBundleURL;

OSStatus err = noErr;

myApplicationBundle = NULL;

myBundleURL = NULL;

myApplicationBundle = CFBundleGetMainBundle();// 1

if (myApplicationBundle == NULL) {err = fnfErr; goto bail;}

myBundleURL = CFBundleCopyBundleURL(myApplicationBundle);// 2

if (myBundleURL == NULL) {err = fnfErr; goto bail;}

if (err == noErr) err = AHRegisterHelpBookWithURL(myBundleURL);// 3

return err;

}

一个简单的示例，描述具体的帮助文档的创建和使用。

一、帮助文档的注册。

// Register our Help Book
FSRef fsref;
NSString * path = [pluginBundle bundlePath];
NSURL * url = [NSURL fileURLWithPath:path];
CFURLGetFSRef((CFURLRef)url, &fsref);
err = AHRegisterHelpBook(&fsref);

二、帮助文档的使用

OSStatus err;
// the log macro is a no-op on release builds
// so we mark 'err' unused so we avoid the warning
#pragma unused(err)


PDEProlog(@"shouldShowHelp:");

PDELog(@"Opening Help Book");
CFStringRef helpbook = CFSTR("OutputBinsPDE2Help");
err = AHGotoPage(helpbook, NULL, NULL);
PDELog(@"Result %i attempting to open %@", err, helpbook);

三、在info.plist当中标明帮助文档，从而使帮助文档与bundle合并在一起编译。

<key>CFBundleHelpBookFolder</key>
<array>
<string>OutputBinsPDE2Help</string>
</array>