developer.casgrain.com

[Update 16/02/2011 – This no longer works now that Twitter has disabled basic_auth. Oh well….]
[Update 21/07/2009 – Twilight is now called Daylight.]

If you follow what I do on this blog and on my podcast with Philippe Guitard, you know that I like Mercurial (hg), one of the newer distributed version control systems.

In particular, I really like Murky as a GUI front-end to Mercurial. In fact, I’m working on the French localization with Olivier Kaluzny.

I want to create a tweet from @ichibiapp or @daylightapp for every commit. I do this with other apps and subversion, and find it pretty handy to catch new commits to production. Plus, if you follow these products on Twitter, you too can get on the inside track of the software releases.

If you want to do the same for your Mercurial repositories, here’s how:

1. Put this shell script, called commit-twitter, in your $PATH and mark it as executable (chmod a+x commit-twitter):

   #!/bin/sh
   # Simple script to send the first line of the commit message as a tweet
   if [ $# -ne 2 ]
   then
     echo "Usage: `basename $0` twitter-username twitter-password"
     exit 1
   fi
   TWITTER_USER=$1
   TWITTER_PASS=$2
   TWEET=$(hg log -r $HG_NODE --template '{desc|firstline}')
   curl -s -u "$TWITTER_USER:$TWITTER_PASS" -d "status=$TWEET" http://twitter.com/statuses/update.xml & > /dev/null
   

   
   The script takes two arguments, username and password, and checks that you have those two arguments. Then it extracts the tweet from the log using the HG_ environment variables set by Mercurial.
   Finally, it uses curl to generate the tweet, using silent mode (-s), running in the background with & (to return immediately) and sending the output to /dev/null.
   

2. Add the following lines to your repository’s .hg/hgrc file, creating it if it does not exist:

   [hooks]
   commit.tweet = commithook-twitter <twitter-username> <twitter-password>
   

3. There is no Step 3!

Voilà! Every time you commit to Mercurial, the first line of your commit message will be posted as a tweet to the specified twitter account.

[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:

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.

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.