Using HTML from Tinderbox 7 to make a Help Book

In the previous article, I showed how to make a set of (X)HTML files which should provide the content for a Help Book, and can be added to a Mac app in development to provide good support for that app’s help. Now comes the proof of that pudding: building the Help Book.

Before going any further, I made a Zip archive of the working folder in case I screwed anything up. I then stripped out the unwanted items from Tinderbox’s export, being the folder Prototypes and Prototypes.html. This leaves index.html, four body pages, two images, and my basic.css stylesheet, in a flat structure.

The next step is to build that folder into the correct hierarchy for the Help bundle. For the top level, I created a folder named LockRattler, the same as the app for which it is designated. Within that goes Contents, then inside that Resources, and finally my export folder from Tinderbox. That last item has to be renamed to a localised language folder such as en.lproj, which contains the English localisation. You can also use, as appropriate, en-GB.lproj for British English, uk.lproj, fr.lproj, de.lproj, and so on according to the language localisation.

Within en.lproj, together with my exported Tinderbox files, I created a file named InfoPlist.strings, which contains localised versions of any strings needed in the main Info.plist. In this case, I just used
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>CFBundleName</key> <string>LockRattler Help</string> <key>HPDBookTitle</key> <string>LockRattler Help</string> </dict> </plist>

I also made an icon file, which will be used for my Help Book when results are displayed in a search. This should be a 256 pixel square in JPEG format, and I placed that in the Resources folder, alongside my en.lproj folder.

The key file to create next is the Info.plist to be stored in the Contents folder, alongside the Resources folder. This is all standard, and can be copied from any other example. There are six values which need to be set carefully, and should be self-explanatory:
<key>CFBundleDevelopmentRegion</key> <string>en</string> <key>CFBundleIdentifier</key> <string>co.eclecticlight.lockrattler.help</string> <key>HPDBookAccessPath</key> <string>index.html</string> <key>HPDBookIconPath</key> <string>LockRattler.jpg</string> <key>HPDBookIndexPath</key> <string>lockrattler.helpindex</string> <key>HPDBookTitle</key> <string>LockRattler Help</string>

If you lay your Resources folder out differently, you will need to ensure that those paths are correct.

This completes all the content for the Help bundle apart from the Help Index, so I made a Zip archive of the folder in case things went wrong.

Creating the Help Index is a precarious business. The fundamental tool is the command tool hiutil, which Apple has wrapped in a friendly front-end in its Help Indexer app, one of the supplementary tools for Xcode. Both seem to throw lots of errors which appear alarming, but the Help Index usually gets built just the same.

If you prefer to do this in Terminal, a standard command goes something like
hiutil -Caf lockrattler.helpindex LockRattler
when it is run from the folder just above the help folder. You can then check the index with a command like
hiutil -Af lockrattler.helpindex
which should list the body pages included.

I then put that Help Index, named lockrattler.helpindex, in the en.lproj folder, and checked the names against the Info.plist to make sure that they tallied. To turn that top-level folder, currently named LockRattler, into a Help bundle, I simply appended the .help extension to it.

The final stage of adding help support is to incorporate your complete Help bundle into your Xcode project. I opened that project folder, and created a folder there named Resources, within the project. I then copied the LockRattler.help bundle into that Resources folder.

Simply placing the bundle in the right place does not include it in the project, though. I opened the LockRattler project in Xcode, incremented its version numbers ready to build a new release, and then added the Help bundle to the project through the Add Files to “LockRattler”… command in the File menu.

There are now two very important changes which must be made to the app’s Info.plist file. Rather than editing them directly, I went through Xcode’s interface to them, by selecting the project and then the Info section of its settings. I added two new entries there, by selecting an existing entry and clicking on the + item which appears next to that item’s key:
Help Book directory name – a String – whose value is LockRattler.help
Help Book identifier – also a String – whose value is co.eclecticlight.lockrattler.help

I then checked those again against the Help Book name, and the CFBundleIdentifier I gave in the Help Book’s Info.plist. I also selected the app’s Info.plist file directly to check that Xcode had changed that correctly.

Whilst I was doing this, I added a full set of Tooltips to the app’s window. I then ran a Clean to ensure that the next build would be from scratch, built it to run, and tested the app out.

If this is the first time that your app has had a Help Book, Xcode appears to ensure that is properly registered with the help system. If it has already had a Help Book and this is just an update, you may find that the changed Help Book is not used. This is because of the way that Help Book registration works. You will then need to install your new version in /Applications to induce the helpd service to recognise and use the new Help Book properly.

When testing your Help Book in the app, don’t forget to try some searches which should return hits from it.

My last step now before deciding that an app is ready for release is to check its signature. This is accomplished from the command line, using (for example)
codesign --verify --verbose LockRattler.app

When everything is looking good, it is time to ship the finished app.

If you want to explore my completed help folder, ready to be made into the Help bundle, it is here: lockrattlerhelp
You can of course look into LockRattler 3.3, which is available from the Downloads item in the menu above.

9Comments

Add yours

1

Tony on March 16, 2017 at 11:46 am

This is a great series of articles. I wish I’d had it when I was wrestling with help some months ago (I gave up but I shall use them when I revisit the subject).

Your previous article (Help Help 3) also mentioned the need to put the app into Applications for updates to be recognised. However, you also say that for the first helpbook, “Xcode appears to ensure that is properly registered”. If I take that literally, I am left wondering how it works on another user’s computer since Xcode is not there to help (as that other user might still choose to install outside of Applications). If Xcode ensures some special behaviour on the app’s first run then the location doesn’t matter?

For the help system to depend upon the location of the app to function correctly (or at all) seems a very poor design; I would accept that it might not integrate a new app’s helpbook until that app is run (or first run?).

Do you have a definitive view on the app location issue?

LikeLike
- 2
  
  hoakley on March 16, 2017 at 11:55 am
  
  Thank you. I have some more coming tomorrow morning too, as there is a minor glitch in the example as it stands, with respect to search.
  According to its .plist, helpd only watches /Applications and /Applications/Utilities. However, other apps can ask the Help system to register a new Help Book. So in normal practice for users, they should trigger recognition of the Help Book when they move an app into either of those two folders.
  Xcode has a problem, in that it runs apps from other folders. Despite that, when you first run an app within Xcode which has a Help Book, that does get registered with helpd and work. However on subsequent builds, helpd doesn’t seem to recognise the changed Help Book. It might do so if there is no version of the app installed in either of its watched folders, though.
  (And of course, wouldn’t all this be so much easier if Apple could be bothered to update and expand its documentation.)
  Howard.
  
  LikeLike
3

Tony on March 16, 2017 at 4:36 pm

Thanks for the prompt clarification. The one-off nature of the Xcode ‘fix’ may explain some of my previous problems.

I am surprised that launching an application doesn’t automatically refresh the cached Help info when it is launched. I wonder if we’re expected to supply that piece of code (as you say, if only it were documented)?

I may be living in the past but I cling to the idea that it is desirable just to be able to drag a Mac application to where you want it to install it. Whilst I routinely keep my apps in Applications, I occasionally have something that I regard as “temporary” that I wish to put elsewhere, generally somewhere that belongs to a single user account.

LikeLike
- 4
  
  hoakley on March 16, 2017 at 4:50 pm
  
  I’ve just tested this out with a fresh build (after a Clean) in Xcode, using an updated Help Book. When run in Xcode, the old Help Book was delivered. When copied to another folder in my Home folder, the old Help Book was still delivered. Only when I replaced the registered copy of the app in /Applications was the new Help Book provided, at last.
  It’s because the Help Book is identified by its signature, and helpd then tells HelpViewer where to find the Help bundle for that signature – which is inevitably the app in /Applications. If you have three different versions of the same Help Book in different versions of the app, helpd and HelpView will only recognise one, and normally that in /Applications.
  It’s not a good system, and all this is undocumented.
  Howard.
  
  LikeLike
5

G.J. Parker on January 22, 2019 at 9:20 pm

Thanks for posting this. I’m having some problems on High Sierra and Xcode 10.1.

First, in the InfoPlist.strings, CFBundleName, it appears you want the name of the App (not App Help). Otherwise when running the app, the menu bar it says “App Help”, not just “App”.

Second in your Info.plist you put in Contents, you need to head the header and trailing stuff for xml. I did this, but i only included the six values.

i used hiutil to build the index instead of the clunky Help Indexer. It seemed to work fine, at least it generated a valid helpindex.

Alas, even after a clean and a rebuild, Help says “The selected content is currently unavailable” which, i guess, is a slight improvement over “No Help availabe” or whatever it says when you don’t have a *.help at all.

Any clue? In the info.plist, should i include all of the App’s main Info.plist?

Again, thanks. Apple’s documentation for the Help system hurts. At least for me.

LikeLiked by 1 person
- 6
  
  hoakley on January 22, 2019 at 9:55 pm
  
  1. No, that’s correct as written above.
  2. Yes, the values given there are the settings contained within the standard header and footer.
  I wish you success – it is a pain, and I tend to use the wonderful Help Crafter for all but the simplest Help books.
  Howard.
  
  LikeLike
  - 7
    
    G.J. Parker on January 22, 2019 at 11:12 pm
    
    Thanks for the reply.
    
    i’m doing something wrong when I put it into Xcode since the final app package doesn’t have the correct layout at all. there’s no app.help in Contents/Resources but instead en.lproj, etc. instead… it appears to have ‘unwrapped’ app.help. It may not be helping that my app has a space in its name.
    
    i’m assuming that the current Lockrattler’s help was generated as above and there the app package is what is expected. So, user error on my end.
    
    Take care,
    
    LikeLiked by 1 person
    - 8
      
      hoakley on January 22, 2019 at 11:57 pm
      
      What I do is drag the completed Help bundle into the project folder at the main level, not in Resources. In Xcode, I then add that bundle to the project, clean it, and rebuild.
      The current Help book in LockRattler is built using Help Crafter – it has got lengthy and complex, I’m afraid.
      Don’t hesitate to ask if you’re still having problems. My email address is in the main About page if you prefer.
      Howard.
      
      LikeLike
9

G.J. Parker on January 23, 2019 at 1:16 am

It appears i missed selecting “Create folder references” instead of “Create Groups” when i added the help bundle. Finally joy.

Of course, now i see i have some typos in the Help.

Thanks again!

LikeLiked by 1 person

Share this:

Related