Home > Six Days of Cocoa > Day Four: Integrating Help in your application using VoodooPad

Day Four: Integrating Help in your application using VoodooPad

May 11th, 2009

[Update September 12th, 2009: VoodooPad 4.2.2 fixes the one bug in this post. Thanks Gus!.]
[Update June 28, 2009: there is an issue with the Help Indexer script and Snow Leopard. Contact me for the details, which only matter if you have Snow Leopard.][Update August 30th, 2009: now that Snow Leopard has been released, I updated the Help Indexer script to run with hiutil.]

Documentation

I’m a big fan of using the right tool for the right job, and I also found myself suffering from “blank page syndrome” when it came time to write initial documentation for iChibi.

I really like VoodooPad for its ability to quickly transfer ideas from my head to some kind of structured document, which I am free to revise later.

VoodooPad even has a web export module, which can create a set of pages that are compatible with Apple Help. Excellent! I could now overcome the blank page and start writing some documentation.

The process

If you write all your documentation in VoodooPad, you must follow these steps to create a valid Help folder to integrate in your application:

  1. Export the document to your Help folder.
  2. Open the main page of your document and insert the appropriate AppleTitle and AppleIcon tags.
  3. Drag-and-drop your Help folder to Help Indexer (/Developer/Applications/Utilities/Help Indexer.app), to auto-generate the index.

That’s still a lot of clicking.

Integrating with Xcode

In order to make sure that when I release software, I ship the latest of everything I like to add build phases to Xcode and have it perform all these tasks automatically. I sometimes run these scripts in Release builds only, because I don’t want to waste any time in the compile-link-debug cycle of a Debug build.

Here is the script I use within Xcode. You can use it too, just add a new “Run Script” phase to your target:

Run Script build phase in Xcode

if [[ ${CONFIGURATION} == "Release" ]]
then
	# Set to whatever you have as CFBundleHelpBook in your Info.plist
	HELP_FOLDER="$TARGET_BUILD_DIR/$UNLOCALIZED_RESOURCES_FOLDER_PATH/English.lproj/Help/"
	HELP_DOC="iChibi Help.vpdoc"
	# Clean folder, so we don't have extra junk in there
	rm -r "$HELP_FOLDER"
	echo "Generating documentation..."
	open "$SRCROOT/doc/$HELP_DOC"
	osascript -e "tell application \"VoodooPad Pro\"" \
		-e "tell document \"$HELP_DOC\"" \
		-e "web export to \"$HELP_FOLDER\" with properties {fileExtension:\"html\"}" \
		-e "end tell" -e "end tell"
fi

(You will want to replace the name and path of your VoodooPad Help document and output folder, of course.)

What this does is delete the current Help folder, and re-generate it using AppleScript to tell VoodooPad to export the proper document to the Help folder.

But wait, there’s more!

In this Xcode build script, there is nothing about setting the AppleTitle or the AppleIcon, nor is there any Help Indexer. Those are all handled by VoodooPad using built-in scripts.

VoodooPad’s Web Export behavior can be overriden by specially-named pages:

  • WebExportPageTemplate
    This page overrides the Export Module selection in the Web Export function.
    This is your basic html page, with extra markup for the actual page content ($page$). The only notable addition I made was to add two comments in the <head> section:
    	<!-- AppleTitle -->
    <!-- AppleIcon -->

    These will be used postflight script below.

  • WebExportPostflightScript
    This page will be run as a shell script with a few interesting environment variables, notably $VPWebExportOutputDirectory. Here is the content of the page:
    #!/bin/sh
    
    # Replace AppleTitle comment in index.html with appropriate value
    perl -pi -e 's/<!-- AppleTitle -->/<meta name=\"AppleTitle\" content=\"iChibi Help\">/' "$VPWebExportOutputDirectory/index.html"
    
    # Replace AppleIcon comment in index.html with appropriate value
    perl -pi -e 's/<!-- AppleIcon -->/<meta name=\"AppleIcon\" content=\"appicon16.png\">/' "$VPWebExportOutputDirectory/index.html"
    
    # Index documentation
    if [ -a "/usr/bin/hiutil" ]; then
      # Using hiutil on Snow Leopard
      /usr/bin/hiutil --create "$VPWebExportOutputDirectory"Help/" --file "$VPWebExportOutputDirectory"Help/Help.helpindex"
    else
      # Using Help Indexer.app
      "/Developer/Applications/Utilities/Help Indexer.app/Contents/MacOS/Help Indexer" "$VPWebExportOutputDirectory"Help/"
    fi
    
    exit 0
    
    

Tip: in the Page Info, check “Skip on Export” for those two files since they are not needed by the Help Viewer.

You can download iChibi’s Help document (VoodooPad format) and use it as a starting point for your Help document.


Bugs to iron out


The build script activates VoodooPad (brings it forward) and leaves the Web Export dialog active. You have to manually dismiss this dialog, or use AppleScript to tell VoodooPad to quit. I don’t like the heavy-handed “quit” approach because I may be working in other VoodooPad documents, and don’t want them to disappear even if they are auto-saved (thanks, VoodooPad!).

There is probably a way to dismiss the dialog using AppleScript and accessibility (e.g. "tell button 3 of dialog 'Web Export' to perform action") but that strikes me as even more of a hack. I hope Gus can fix it in an upcoming release of VoodooPad :-) .

This is fixed in VoodooPad 4.2.2.

Categories: Six Days of Cocoa Tags:
  1. May 15th, 2009 at 19:26 | #1

    This is cool stuff. I do something similar with a NoteBook document for Meerkat’s help. I’ll have to blog it up.

  2. Tim
    July 29th, 2009 at 10:10 | #2

    Hi Philippe,

    Could you elaborate on the Help Indexer in Snow Leopard issue? I think I have just run into the same thing myself. The application does not exit after creating the help index, thus blocking the build.

  3. July 29th, 2009 at 12:26 | #3

    Replied privately… Contact me at developer (at-sign) casgrain (dot) com if you did not get it.

Comments are closed.