{"id":16,"date":"2009-05-11T15:23:53","date_gmt":"2009-05-11T20:23:53","guid":{"rendered":"http:\/\/developer.casgrain.com\/?p=16"},"modified":"2011-02-16T22:56:39","modified_gmt":"2011-02-17T03:56:39","slug":"day-four-integrating-help-in-your-application-using-voodoopad","status":"publish","type":"post","link":"http:\/\/developer.casgrain.com\/?p=16","title":{"rendered":"Day Four: Integrating Help in your application using VoodooPad"},"content":{"rendered":"

[Update September 12th, 2009: VoodooPad 4.2.2<\/a> fixes the one bug in this post. Thanks Gus!.]<\/em>
\n[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.]<\/em><\/s>[Update August 30th, 2009: now that Snow Leopard has been released, I updated the Help Indexer script to run with hiutil<\/code>.]<\/em><\/p>\n

Documentation<\/h3>\n

\nI’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<\/a>.<\/p>\n

\nI really like VoodooPad<\/a> for its ability to quickly transfer ideas from my head to some kind of structured document, which I am free to revise later.<\/p>\n

\nVoodooPad 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.<\/p>\n

The process<\/h3>\n

If you write all your documentation in VoodooPad, you must follow these steps to create a valid Help folder to integrate in your application:<\/p>\n

    \n
  1. Export the document to your Help folder.\n<\/li>\n

  2. Open the main page of your document and insert the appropriate AppleTitle<\/code> and AppleIcon<\/code> tags<\/a>.\n<\/li>\n

  3. Drag-and-drop your Help folder to Help Indexer (\/Developer\/Applications\/Utilities\/Help Indexer.app<\/code>), to auto-generate the index.\n<\/li>\n<\/ol>\n

    That’s still a lot of clicking.<\/p>\n

    Integrating with Xcode<\/h3>\n

    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.<\/p>\n

    \nHere is the script I use within Xcode. You can use it too, just add a new “Run Script” phase to your target:<\/p>\n

    \n\"Run<\/p>\n

    \r\nif [[ ${CONFIGURATION} == \"Release\" ]]\r\nthen\r\n\t# Set to whatever you have as CFBundleHelpBook in your Info.plist\r\n\tHELP_FOLDER=\"$TARGET_BUILD_DIR\/$UNLOCALIZED_RESOURCES_FOLDER_PATH\/English.lproj\/Help\/\"\r\n\tHELP_DOC=\"iChibi Help.vpdoc\"\r\n\t# Clean folder, so we don't have extra junk in there\r\n\trm -r \"$HELP_FOLDER\"\r\n\techo \"Generating documentation...\"\r\n\topen \"$SRCROOT\/doc\/$HELP_DOC\"\r\n\tosascript -e \"tell application \\\"VoodooPad Pro\\\"\" \\\r\n\t\t-e \"tell document \\\"$HELP_DOC\\\"\" \\\r\n\t\t-e \"web export to \\\"$HELP_FOLDER\\\" with properties {fileExtension:\\\"html\\\"}\" \\\r\n\t\t-e \"end tell\" -e \"end tell\"\r\nfi<\/pre>\n
    \n(You will want to replace the name and path of your VoodooPad Help document and output folder, of course.)<\/p>\n
    \nWhat 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.<\/p>\n
    But wait, there’s more!<\/h3>\n
    In this Xcode build script, there is nothing about setting the AppleTitle<\/code> or the AppleIcon<\/code>, nor is there any Help Indexer. Those are all handled by VoodooPad using built-in scripts.<\/p>\n
    \nVoodooPad’s Web Export behavior can be overriden by specially-named pages<\/a>:<\/p>\n