Archive

Archive for June, 2009

Open any page or location in your Help Book

June 29th, 2009 Comments off

Anchors

So you wrote your documentation using VoodooPad and you want to open a page of your choice, for instance, the “Quick Start” page.
But you don’t want this page to be the index page.

You know you can open your Help Book with this code:

[[NSApplication sharedApplication] showHelp: nil];

What you want to use is this:

NSString* bookName = [[NSBundle mainBundle] 
                              objectForInfoDictionaryKey: @"CFBundleHelpBookName"];
[[NSHelpManager sharedHelpManager] openHelpAnchor: @"__ANCHOR__" inBook: bookName];

(where __ANCHOR__ is an actual HTML anchor in your Help Book)

Creating the anchors

There are two parts to this. First, create page aliases in VoodooPad and second, update your WebExportPageTemplate to output those aliases.

VoodooPad Page Aliases

Any page in VoodooPad can have one or more aliases. They can be added by clicking the Info button on the Toolbar and clicking on the “+” button at the bottom of the Info panel. You can add as many as you want.

Tip: If you have multiple languages for your Help file, make sure that the aliases match the openHelpAnchor: above. Since this string is not user-visible, it makes sense that it be the same across all Help files.

Modifying the page template

In your VoodooPad document, open the WebExportPageTemplate page.
On that page, insert the following code at a proper location (for instance, just after the <body>tag):

<a name = "$alias$"></a>

$alias$ is a special VoodooPad variable that is replaced by the first alias in the list you defined above. It can also be called $alias[0]$.

If you have more than one alias, and you want to have multiple anchors in your page (for instance, a header and a footer), you can use $alias[1]$, $alias[2]$, etc. But in general, your help pages will be small enough that one anchor/alias per page should be sufficient to open a given page in your Help book, directly from your application.

Indexing

Make sure you actually run the Help Indexer application on your HTML Help folder.

#!/bin/sh
"/Developer/Applications/Utilities/Help Indexer.app/Contents/MacOS/Help Indexer" \ 
               "$VPWebExportOutputDirectory"

This step is necessary for the Help System to find your anchors by name.

Categories: Development, MacOSX Tags: