Working around broken hiutil in Mountain Lion

For VideoBuffet, I use VoodooPad to author my help file. I learned about doing this from this blog post, and it’s been working well for me. Until the last VideoBuffet update, when suddenly my help anchors stopped working.

As the article states, you basically make a Run Script build phase in Xcode which exports the VoodooPad doc as HTML. Then, your VoodooPad doc is setup to run Apple’s help indexer (hiutil) to create the index. What the article doesn’t tell you is how to open your help to a particular page.

To do this, in VoodooPad you make an alias to the page to which you want to link, and give it a name (in the title bar, click Info; then, under Aliases, click the + button and type the name). The screenshot below shows VideoBuffet’s Preferences page, and you can see I’ve made an alias called “preferences”.

Voodoopad example

Finally, in code (like, in the Help button in the Preferences dialog), you can do this:

NSString *locBookName = [[NSBundle mainBundle] objectForInfoDictionaryKey:@"CFBundleHelpBookName"];
[[NSHelpManager sharedHelpManager] openHelpAnchor:@"preferences" inBook:locBookName];

…and the appropriate page will open up in Help Viewer. It works great, and I use this technique all over the place.

Back to the point. While testing VideoBuffet 1.0.3, I discovered that the help links were all broken. After a bit of hair-pulling I finally figured out that hiutil was giving me errors, and ending up not creating a proper index (it wasn’t getting as far as my anchors). After Googling it, to no avail, I posted a question on Stackoverflow, which, at the time of this writing still has no responses. If you know the answer, by all means, post it there. :)

I’ve since discovered that the version of hiutil that ships with Mountain Lion (version 1.3) was where this problem started showing up, and the version from Lion (1.2) works as it always did. So, my (terrible) workaround: use the version of hiutil which shipped in Lion.

Find yourself a Lion system, and copy /usr/bin/hiutil to the machine where you do your builds. I didn’t want to replace the newer hiutil, so I called the Lion copy hiutil_old, and changed the VoodooPad export script to use that one. There’s one other step: hiutil 1.2 depends on MPWXmlCore.framework, which no longer exists in Mountain Lion. So in order to use hiutil 1.2 on Mountain Lion, you need to copy MPWXmlCore.framework from a Lion system as well (it’s in /System/Library/PrivateFrameworks/).

Update: Some folks on the original stackoverflow question I posted note that if you specify a doctype of XHTML 1.0 and fixup any obvious markup errors, Mountain Lion’s hiutil works fine. After messing about with my export scripts, I can confirm that this does appear to work (though, I’m not sure VoodooPad is really doing 100% valid XHTML). In any case, with some changes I’ve made it work.

I’ve also since upgraded to VoodooPad 5, and there are some tweaks I had to make to ensure everything still works. Specifically, exporting aliases to anchors works differently now. I’ll post another entry showing my updated workflow for using VoodooPad to author help files, soon.

If you want to follow me, I’m @zpasternack on Twitter and on

2 thoughts on “Working around broken hiutil in Mountain Lion

  1. Thank you for the post. I can’t add anchors to index of .json file. Where I can download these two files? I started from Mountain Lion, I don’t see these files neither in Apple Development area, nor in Google search.

    • The only place to get those two files is from a Lion install. In other news, however, a few people are reporting some workarounds for this issue that you might try. See the recent responses in the stackoverflow question. I personally haven’t tried this, but when I do, I’ll update this post.

Comments are closed.