Digging Deep into iWork Document Sharing in Mountain Lion

If you use Apple’s iWork apps, and you sync documents across multiple Macs and iOS devices, get OS X Mountain Lion. Now. It’s okay; I’ll wait till you get back. 

Got it? Good. Now let’s talk about why you’re about to be overjoyed.

Last Wednesday, along with Mountain Lion, Apple released updates to the Mac versions and iOS versions of iWork. With this trio of updates installed, any changes you make to an iWork document one device are “instantly available” on the others (a feature I previewed in a Macworld article last month). This is a huge improvement! Prior to this (as I covered in another Macworld article), such instant iWork syncing was impossible. In fact, syncing iWork documents, especially between Macs and iOS devices, was so clumsy and limited that it was just about not worth the bother.

Until last week, one big unanswered question remained: Would this new file sharing method really work as well as Apple’s advance publicity indicated? We can now answer this question. The short answer is…yes! It works. It works very well, amazingly well. It’s not perfect, but it’s darn close.

Getting what you need

To access the new file sharing features in iWork, you need Mountain Lion. Although the iWork app updates run in Lion, the new options covered here only show up in Mountain Lion. You also need to enable iCloud on all the devices that will be sharing documents (for more information on saving documents in Mountain Lion, including via iCloud, see my previous User Friendly View column).

If you already own iWork on your Mac, the updates are free. One minor note: You may have previously purchased iWork apps either from the Mac App Store or from outside the Store. If you have the former, get the iWork updates from the Mac App Store. For the latter, use Software Update from the Apple menu.

In Mountain Lion, both routes wind up going through the App Store app to do the downloads. However, if you have the outside-the-Store versions, this does not mean that you now own the App Store versions. You don’t. That’s why, for example, if you check the Purchases list in the App Store app, your iWork apps are still not listed.

Don’t worry, the iWork apps are the same no matter what their source. There is no reason to replace (at an added cost!) an outside-the-Store version with an App Store version. It is worth noting, however, that the outside-the-Store versions represent an exception to Apple’s “rule” that only apps sold from the App Store can access iCloud. I guess, as Apple makes the rules, it can also break them.

Sharing iWork documents

Once I had everything in place, I was ready to test drive the new sharing features. For my first test, I created a document in Pages on my Mac and saved the document to iCloud.

Saving a Pages doc

Saving a new Pages document from my Mac to iCloud.

Next, I launched Pages on my iPad, which is linked to my same iCloud account. Sure enough, the document I had just created on my Mac was now in the Documents list on my iPad. I tapped the file’s icon and it opened.

Opening Pages on an iPad

The icon for the just-saved Pages document (Pages Test, in upper left) shows up on iPad.

At this point, any changes I made (and saved) to the document one one device were almost immediately reflected in the document on the other device. [Note: As Pages for iOS does not have a Save command, I closed a document to save it.]

Especially impressive is that if the same document is open on both devices, and I make a change on one device, I can watch the change appear on the other device while simply staring at the screen. Very slick — and exactly as Apple promised this would work.

Similarly, if you are viewing an iWork app’s Documents list on the iPad or an Open dialog on a Mac, you can see a progress bar move across a document’s icon after making a change to the document on the other device. This is the indication that the document is getting synced.

If you have ever struggled with syncing iWork documents before, this is the equivalent of a glorious sunrise after a long and dark night.

Dealing with conflicts

Next, I wanted to know how the iWork apps would deal with document conflicts. That is, what would happen if I made different edits to the same document on two different synced devices (Mac and iPad, say) at about the same time? Would the iWork apps be able to figure out what I had done and know how handle it without getting messed up? 

The answer is: Yes. When this happens, a Resolve Conflict dialog pops up, telling you that “Modifications aren’t in sync.” From the dialog, you can choose which document you want to keep. You can even select to keep both, in which case two separate documents are created. Cool! 

Resolve Conflict

iWork’s Resolve Conflict dialog.

Sharing and syncing via iWork at iCloud.com

Prior to Mountain Lion, the best way to share (and, in some manner, sync) iWork documents among devices was via the iWork section of iCloud.com (as I’ve covered previously). With Mountain Lion, the iCloud.com interface becomes superfluous. The iWork section still exists, but presumably only for the benefit of those poor souls not yet running Mountain Lion.

Peering inside the Mobile Documents folder

Copies of all documents stored in iCloud are automatically locally stored on your Mac. You’ll find them in the Mobile Documents folder, located inside the invisible Home directory Library folder (to get here, hold down the Option key and select Library from the Finder’s Go menu). Every Mac app that supports iCloud document storage has its own folder here. For example, Pages’ folder here is named com~Apple~Pages. Page’s currently-stored iCloud documents are inside this folder. 

On iOS devices, apps that sync with iCloud similarly store their documents in a Mobile Documents folder, although you can only see this if you jailbreak your device. For example, using PhoneView to view the contents of my jailbroken iPad, I navigated to User>Library>Mobile Documents>com~Apple~Pages>Documents. Here I found local copies for all the iCloud-stored documents seen in Pages’ Documents list. That’s why I can open these files on my iPad even when in Airplane mode, with no connection to iCloud. [Note: In its iCloud developer documentation, Apple refers to the Mobile Documents location as an app’s out-of-the-sandbox “ubiquity container.”]

You can turn off iCloud syncing separately for each iOS iWork app. To do so for Pages, for example, go to Settings>Pages and disable the Use iCloud option. If you do so, the next time you launch Pages, a message appears prompting you to choose what to do with the saved files. If you choose “Keep on My iPad,” they will be moved from the Mobile Documents location to within the Pages app itself — “sandboxed” in Pages.app>Library>Application Support>Documents.

When iCloud is off

If you turn Use iCloud off (in the Settings option shown on left),
the dialog on the right appears the next time you launch Pages.

Apple would prefer that you stay away from the Mobile Documents folder (unless you’re planning on getting rid of your Mac). However, I have found working with the folder to be fairly robust. For example, if I dragged a Pages document from my Desktop to the Pages section of the Mobile Documents folder, the file soon appeared on my iPad. In almost all my testing, OS X, iOS and iCloud handled my hammering very well — doing more-or-less what I would have hoped.

Dealing with document incompatibilities

Even with these latest updates, the iWork apps on iOS devices still do not support the full range of features and document attributes available via their Mac siblings. This means that, when importing a document from a Mac to an iOS device, some attributes may get stripped out of the document. For example, in Keynote, you’ll find that comments are not imported, certain fonts are not supported, and some transitions are dropped. When this happens, you should see an Import Warning message on your iOS device, informing you exactly what is about to get removed.

Import Warning

iWork’s Import Warning dialog on an iPad.
Oddly, despite this warning, my iOS Keynote document retained its Shimmer transitions.

In addition to the Import Warning, a related message may show up in the latest iWork for iOS apps. The new “Open Document” message typically appears when first opening a document that originated on a Mac. The message appears even when the Import Warning message does not pop up. It thus indicates a more general formatting concern. The message states that the “document may look different on your iOS device than on your Mac.” It allows you to choose either to open the document or make a copy of the document.

[Note: You can bypass this warning, and forgo the opportunity to open up a copy, by going to Settings > Pages (or Keynote or Numbers) and turning off “Ask to Open Copies.”]

"look different" warning

iWork’s Open Document warning on an iPad.

What’s the effect of opening the original document vs. making a copy? If you chose to open the document directly (and make any changes to it), the document is converted to an iOS compatible format (as detailed in the next section) — and this same format change is synced back to iCloud. This means you may lose certain unique attributes of the Mac version. However, I didn’t detect any visual differences between the iOS and Mac versions in my testing. Mainly, the message appears to be a generic warning that things “may look different” after the conversion. If you instead chose to make a copy, the original remains unaltered while the copy is converted to the iOS-compatible format.

After a document has been converted to the iOS format, the “Open Document” warning should no longer pop up when you next select to open the document. However, if you later edit the document back on your Mac, which reverts it to the Mac format, the warning will return on your iPad. Given this see-sawing of formats, it’s probably wise to minimize the number of times you shift back and forth between the Mac and iOS platforms for editing a document.

Understanding iWork file formats


This is your last chance. After this, there is no turning back. You take the blue pill - the story ends, you wake up in your bed and believe whatever you want to believe. You take the red pill - you stay in Wonderland and I show you how deep the rabbit-hole goes. (Morpheus, in The Matrix)


If you’re not especially familiar with the nuances of iWork documents, you may be wondering at this point: Why does syncing iWork documents have all of these complications? Why isn’t it as simple as syncing documents from most other apps? The answers require digging deeper into the workings of OS X and iWork apps. If that’s not your cup of tea, feel free to stop here.

Mac vs. iOS file formats. The key point (as I indicated above and explained in detail in yet another Macworld column) is that iWork documents for Macs and iOS devices have separate formats. It’s not just that an iOS iWork document may be missing some Mac-only features; the two files are actually different types of documents. I’m not sure why Apple felt it was necessary to do this, but they did. Almost all the other complications derive from this initial decision.

For most apps that have versions on both platforms, their documents typically can be equally well opened on Macs and iOS devices. Such is not the case for iWork apps.

You cannot open a Mac-formatted iWork document on an iOS device. It must be “imported” first. Importing a Mac iWork document to an iOS device doesn’t simply copy the document to the iOS device, it converts it to the iOS format.

Similarly, you cannot directly open an iOS formatted iWork file on a Mac. That’s why, prior to Mountain Lion, you needed the iWork interface in iCloud.com to download an iOS/iCloud document back to your Mac; the download process converted the file back to a Mac format.

If this all sounds irritating and inconvenient, you’re right. This is where Mountain Lion comes to the rescue. While these format conversions remain required in Mountain Lion, the new OS X and iWork software handle the conversions automatically and behind-the-scenes, so that you hardly notice they’re taking place. The end result is true syncing of files across platforms.

-tef packages. Actually, the file format situation is even more complicated than I’ve explained thus far. There are not just two, but (almost) three separate iWork file formats…

Let’s assume you are running Mountain Lion and the latest iWork software. On your Mac, if you save an iWork document locally to your drive, the file is saved in iWork’s traditional Mac format. In this case, the file will end with an extension that matches the name of the creating app. For example, a Pages document might be named “QuarterlyReport.pages.” Prior to iOS and iCloud, this was the only Pages format. 

If you instead save the document to iCloud, the document’s format is different. First, a -tef is added to the end of the file’s name, such as “QuaterlyReport.pages-tef.” These -tef files are actually folder “packages,” not standard files. I call this the iCloud format of iWork files. Under normal circumstances, all iWork documents in the Mobile Documents folder — and in iCloud — have this -tef extension.

I was pleasantly surprised to find that Mountain Lion is smart enough to do an on-the-fly conversion of the iCloud format back to the Mac format. That is, if you drag a .pages-tef file from the Mobile Documents folder to the Mac’s Desktop, Mountain Lion’s Finder converts it back to the .pages file format. Similarly, you can open a .pages-tef file in Pages on your Mac and save it to your Desktop. Doing so will also convert the document to its .pages Mac-format equivalent.

None of this happens in Lion. If you double-click a -tef item in Lion, the file will not open at all. Instead, you get a message that says the file cannot be opened “because its file type isn’t supported.”

Here’s the final wrinkle: There are two variations of iWork -tef files. When you save an iWork file to iCloud on your Mac, it is saved in the Mac variation. If you select the Show Package Contents contextual menu for such a -tef file, you will see something like this:

tef package: Mac format

Inside a Pages -tef package as created on a Mac and saved to iCloud. 
The index file is the equivalent of a traditional Mac-format .pages file.

This is the format variation that will trigger the Open Document warning on an iOS device. The package remains in this format until the first time you open the file on an iOS device. At this point, it is converted to the iOS variation, which will look something like this:

tef package: iOS format

The same Pages -tef package, after being open on an iPad and converted to the iOS variation.
The index.db file is not the same as the index file in the prior figure.

The file remains in this iOS variation format unless and until you open, edit and re-save the file (to iCloud) on your Mac. In that case, the file reverts back to the Mac -tef variation. And so on and so on. Whew!

Bottom line

Mark this day. Finally, there is true on-the-fly syncing of iWork documents between Macs and iOS devices.

There are still a few unwelcome complications, thanks mainly to the lingering use of separate formats for the different platforms. It would be better if Apple could have dumped the legacy arrangement and employed a single format, one that supported all document attributes on all devices. But, assuming this could not be, what we now have is the next best thing.

I would also appreciate it if Apple offered end-user documentation that clarified the relevant intricacies of how all of this works, saving me the hassle of trying to disentangle them myself. 

That aside, Mountain Lion and the new iWork apps do a superb job of handling file sharing and syncing. Well done, Apple.