The fact is, there are pretty good algorithms for hyphenation.  The Hunspell project has a library that powers, among other projects, OpenOffice.org and extends the algorithm that was implemented for TeX long ago.  Time to bring some of that goodness to Cocoa!

I implemented a simple category for NSString to add UTF-8 soft hyphens to a string. In this post I show how to use it in your project, including some examples.

Setup

First, gather all required files:

• Get NSString+Hyphenate from GitHub
• Download the Hyphen library
• The Hyphen library contains the hyphenation dictionary for US English but if you want to support more languages you can download more dictionaries from OpenOffice.org

Second, after unzipping put the code in place.

• Add the NSString+Hyphenate .h and .m file to your project.
• To statically add the hyphen library to your project add the hyphen.h, hyphen.c and hnjalloc.h, hnjalloc.c files.

Third, and finally, add the .dic files to the Hyphenate.bundle and add the bundle to your project. Your project source tree should now contain all the necessary files and look something like this.

Usage

The Hyphenate category gives you one method: -stringByHyphenatingWithLocale:. Its usage is straightforward:

    NSString* text = @"It was in the fourth year of my apprenticeship to Joe, and it was a Saturday night.";
    NSLocale* en = [[[NSLocale alloc] initWithLocaleIdentifier:@"en_US"] autorelease];
    NSString* hyphenated = [text stringByHyphenatingWithLocale:en];

UIKit has limited support for the soft hyphen. This is the result for setting the string above to a UILabel, UITextView and UIWebView respectively.

As you can see, UILabel will simply display all soft hyphens. The behavior of UITextView and UIWebView is more useful: the soft hyphen is shown only when needed and it allows word wrapping.

Using (X)HTML

Since UITextView is pretty limited in how much you can style and typeset text, a UIWebView will usually be the way to go for displaying nicely looking, hyphenated text.

Obviously running -stringByHyphenatingWithLocale: on an HTML document will not give the required result. Unfortunately, unless you are willing to use libxml2 directly, your options for working with XML documents on the iPhone are limited.

The best option (as far as I know) is to use TouchXML, a friendly wrapper for libxml2 with an API that mimics Cocoa’s NSXML* classes. However, TouchXML only supports reading XML documents, not creating them. To apply hyphenation, we would need at least a way to modify text nodes. Luckily that turned out to only require a small change to TouchXML, which you can find as a patch in the hyphenate repository.

Next, after patching and setting up TouchXML, we use a simple XPath expression to fetch all the text nodes and modify each.

    CXMLDocument* document = [[[CXMLDocument alloc] init...] autorelease];
 
    NSArray* textNodes = [document nodesForXPath:@"//body//text()" error:NULL];
    for (CXMLNode* node in textNodes) {
       [node setStringValue:[[node stringValue] stringByHyphenatingWithLocale:en]];
    }
 
    NSString* hyphenatedDocument = [[[NSString alloc] 
                                     initWithData:[document XMLData] 
                                     encoding:NSUTF8StringEncoding] autorelease];

Note that this code is a bit of a oversimplification. Whether this simple XPath expression is appropriate for you wholly depends on your actual documents.

Compare the results with and without hyphenation:

For more information and documentation, check out the hyphenate repository on GitHub.

(Texts from Charles Dicken’s Great Expectations.)

Update 1: I have now found KissXML to be a better option than TouchXML for my purposes. Also, it supports setting the text nodes out of the box, no patching necessary!

Update 2: Frank Zheng has figured out a simple solution to use hyphenation in Core Text. See his blogpost for more information. Thanks, Frank!

Introducing MoProPro

MoProPro automates as much as possible of a very specific, but for iPhone developers very common and tedious, task: adding tester’s UDIDs to an existing ad hoc distribution provisioning profile and downloading the new version of the profile. While this doesn’t sound that hard, compare ‘Before’ and ‘After’

Both the ‘Before’ and ‘After’ scenario assume you’ve already set up your app, a distribution certificate, a mobile provisioning profile and acquired the UDID ’1234567890DEADBEEFCOFFEE098766654321ABCD’ that you want to add to your testers…

Before

1. Go to the iPhone Dev Center website
2. Click login
3. Fill in credentials and login
4. Go to the iPhone Developer Program Portal
5. Go to the Devices page
6. Click on Add Devices
7. Enter and name the UDID, submit
8. Go to the Provisioning page
9. Click on Distribution
10. Find the right (ad hoc) provisioning profile for your app
11. Click on Edit, click on Modify
12. Check all boxes of the newly added devices, submit
13. Wait a bit, refresh the page, until the Download button appears again
14. Download the new provisioning profile

Most of this process is pretty mechanical and boring. Also, most of this process could be smoother if Apple had made a better web interface, based on common use-cases, which will hopefully happen somewhere in the future. But, in the meantime, and for people that just like the command prompt, witness ‘After’:

After

Using the Terminal, go your project’s directory (containing the Info.plist file, and a .mopropro file containing the ADC credentials for this project) and run:

$ mopropro 1234567890DEADBEEFCOFFEE098766654321ABCD "Name for Device"
Saved new provisioning profile to 'Example_Ad_Hoc.mobileprovision'
$

That’s it.

If you add the -v switch, you can see (more or less) what it does, for example:

Validating input... Ok.
Getting App Id... com.example.app
Logging in... Ok.
Looking up existing devices... Done.
Adding 1 device... Submitted.
Looking up provisioning profile...
 - Found 5 profiles
 - Found 2 matching profiles
 - Found Ad Hoc profile
 - Adding devices
Saving profile with new devices... Ok.
Waiting a bit while the new profile is generated... Ok.
Trying to retrieve new profile... Got it!
Saved new provisioning profile to 'Example_Ad_Hoc.mobileprovision'

The script has some more options and can also accept multiple devices. All ‘documentation’ can be found in the README in MoProPro’s repository on GitHub. Enjoy!

About

MoProPro uses the excellent WWW::Mechanize library to automate using the iPhone Dev Center website. The Plist library is used for getting the application identifier out of the Info.plist file. YAML is used as the format for the configuration and input files.