Simple Online Help and Help Book Synchronisation

Posted in

Blog
Cocoa

So, I have written a simple, but hopefully effective, html help page for my Cocoa app. I have posted it on my web site and provided a link in my app to access it. The help is all on one page but it's not too large or unwieldy and I like it. Internal links are used to navigate around the page and one click can print the whole thing for those who want a paper copy.

And now I want to make an OS X help book with the same content in the same format ie: one simple html file. It won't be an Apple compliant help book but I don't care because I don't particularly like the task orientated approach. I want something I can read. And I want something that I can edit and update quickly both for the web and for the app help book.

Also, it is quick and easy to make a synchronous edit to the web based help when an issue or query arises. Thus the help will hopefully remain more up to date and relevant.

The details of adding a help book to a Cocoa app are well documented.

The help files are HTML so at the simplest level one can simply drop an index.html file into the help book folder identified in the app info.plist. Note that if you are fiddling about and have multiple index(somename).html files in the help folder then the help book may display one of those instead. My help book folder has the following structure:

App Name
- css folder
  - help.csss
  - style.css
- gfx folder
  - image1.png
  - image2.png
  - ...
- index.html

My web site uses Drupal and my goal was:

Grab the base HTML help text from the Drupal page editor and drop it into the app help folder as index.html.
Grab a copy of the Drupal template stylesheet and drop it into the app help css subfolder.
Grab a copy of the web help images and drop them into the app help css subfolder.

This was largely achieved and the rendered output in the help book matches that in Safari (maybe this should be no surprise). No HTML or CSS layout manipulation was required though I did check that the basic help text was XHTML compliant. There are some points to note:

index.html

The index file requires a simple template that the the raw Drupal extracted mark-up can be dropped into:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta http-equiv="content-type" content="text/html;charset=utf-8" />
        <title>AppName Help</title>
        <meta name="AppleTitle" content="AppName Help" />
        <meta name="AppleIcon" content="AppName Help/gfx/appicon16x16.png" />
        <meta name="robots" content="anchors" />
        <link href="css/help.css" rel="stylesheet" media="all" />
        <link href="css/style.css" rel="stylesheet" media="all" />
    </head>

    <body>
        <div id="frame">
            <div class="help">

                <!-- insert help html here --!>

            </div>
        </div>
    </body>

</html>

The web HTML is dropped into the help div. This produces a help book which invariably flashes up some of your content and then displays a page stating "Internet connection required", even though an Internet connection is alive and kicking. This will occur if your help HTML or CSS contains even one image URL that cannot be successfully resolved to and obtained from the help folder. So if an image is missing from the help folder you will likely see this.

style.css

Except for the image url rewriting mentioned above the Drupal theme CSS style sheet was modified as follows:

Body selector background-colour property was removed.

Notes

Another point to note is that help book URLs seem to need to be relative to the document. Image URLs that are rooted with / will not be found and the Internet connection required page will pop up again. The same applies to image URLs used in CSS background properties.

So I apply the following:

Keep all help images for an app in a separate web folder

If all the app help images are in the one separate web folder it makes it a trivial matter to copy them from the web into the app help gfx folder. It also means that all image URLs in the index.html and the style sheet can be updated using a global search and replace of the form /sites/mysite/files/images/myapp/help/* to gfx/*.

Keep help book CSS separate from the Drupal CSS

The Drupal derived CSS is dropped straight in as style.css - the only mod being the image path URL replacement. Any separate help book specific CSS goes into help.css. It should require minimal content:

#frame	{ 
	text-align: left; 
	margin-top: 12px;
	margin-right: auto; 
	margin-left: auto; 
	width: 560px
}

Submitted by Jonathan Mitchell on Wed, 08/26/2009 - 22:50