[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:
- Export the document to your Help folder.
- Open the main page of your document and insert the appropriate
AppleTitle
and AppleIcon
tags.
- 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:

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.