Versioning in iBooks 3 (part 1)

Another promising new feature announced by Tim Cook about iBooks 3 is the ability to make updates to an ebook, and then make those updates available to readers who have already bought the book. There were a few minor errors in my Monarch Butterfly book so I decided I would use it as a guinea pig to test versioning.

The first thing to note is that versioning only exists for EPUB 3 documents. They can be flowing or fixed layout, but they have to be EPUB 3.

So, my first task was to update the Monarch Butterfly fixed layout book to EPUB 3.

Changes to the OPF file

I began with the OPF file, adding version="3.0" to the initial package element and adding the namespaces that Apple recommends.

I updated the title of my book to indicate the version number, though I'm not sure this is necessary (or desired).

I added the required modification date and time:

<meta property="dcterms:modified">2012-11-06T12:00:00Z</meta>

Pay special attention to the time format: CCYY-MM-DDTHH:MM:SSZ. I tried putting just the year, and EpubCheck gave me an error. Note that both the T and the Z are required.

To make sure my fonts are recognized, Apple now requires this line instead of the com.apple.ibooks.metadata.plist file:

<meta property="ibooks:specified-fonts">true</meta>

And then comes the part where Apple lets you specify the version of your book. You are allowed two dots and three components (so 1.2.1) and up to four numbers per component (which seems excessive, frankly). And these aren't decimal numbers: trailing 0's count to keep them ordered; 1.10 is later than 1.9.

<meta property="ibooks:version">1.1</meta><!--controls versioning in iBooks3-->

Then, since my book is fixed layout, I had to add the EPUB 3 specific metadata:

<meta property="rendition:layout">pre-paginated</meta>
<meta property="rendition:spread">auto</meta>
<meta property="rendition:orientation">auto</meta>

Because my books' pages include Javascript, I had to add properties="scripted" to each of the pages which links to a Javascript file, even if it didn't use Javascript in that particular page.

<item id="milkweed" href="milkweed.xhtml" media-type="application/xhtml+xml" properties="scripted" />

And then I removed the guide section, which is no longer required by Apple (and was already deprecated in the EPUB 3 spec).

</spine>
<!--new to 1.1 guide is removed -->
</package>

New TOC file

EPUB 3 requires a new XHTML-based TOC file, which is a lot easier to write than the old toc.ncx format, since it's just formed by an ol list with links to the various TOC entries. For a Fixed Layout book, for which you want iBooks to create its graphic TOC (made of the covers of the books), just create a single entry to the first page, or cover in my case:

<nav id="toc" epub:type="toc">
<h1 class="chapter">Table of Contents</h1>
<ol>
<li><a href="title.xhtml">The Monarch Butterfly Book</a></li>
</ol>
</nav>

Then, as a replacement to the guide section, add a landmarks section, which works very similarly:

<nav epub:type="landmarks">
<h1>Guide</h1>
<ol>
<li><a epub:type="ibooks:reader-start-page" href="title.xhtml">The Monarch Butterfly Book</a></li>
<li><a epub:type="cover" href="title.xhtml">Cover</a></li>
<li><a epub:type="bodymatter" href="milkweed.xhtml">First page</a></li>
</ol>
</nav>

Finally, declare the new toc.xhtml file in the OPF file, paying special attention to the properties attribute:

<item id="toc" href="toc.xhtml" media-type="application/xhtml+xml" properties="nav"/><!--new in 1.1-->

That's it for the OPF file.

Changes to the XHTML files

In each of the XHTML files, I had to change the meta tag where I declared the character set. It was:

<meta content="text/html; charset=UTF-8" />

and it should be:

<meta charset="UTF-8"/>

I also had a few documents that somehow still had extraneous DOCTYPE elements. I got rid of those and made sure that each XHTML document started like this:

<?xml version="1.0" ?>
<html xmlns:epub="http://www.idpf.org/2007/ops" xmlns="http://www.w3.org/1999/xhtml">
<head>

There were also a few places I had erroneously used character entities, things like © to show the © symbol. Now that I had the proper character set declaration, that was no longer necessary (or allowed). So I simply removed the character entities and replaced them with the characters themselves, typed in directly.

<p>Copyright ©2012 by Elizabeth Castro...

As far as content, I also fixed the error on page 24, which had the blinking arrows in the wrong place:



And put them where they go:



I also changed the Javascript so that the arrows would blink more slowly. People seem to have had difficulty finding the captions. It's actually a tricky problem. I want the photos to be displayed without distractions, but I want to offer clues. I haven't quite found the perfect solution yet.

Validating

Once of all of the changes were made, I used EpubCheck to make sure I had done it all correctly. I used the latest version: EpubCheck3RC.

Uploading the new file to the iBookstore

Finally, I uploaded it to Apple's iBookstore with iTunes Producer. When you make changes to a book that already exists, you only have to change the parts in iBooks Producer that are different, and it will only update those pieces of your package. So, I updated the description and then on the Assets page, I clicked the Choose button under Publication, and selected the new updated EPUB file. This screenshot is actually after I've done that. iTunes Producer doesn't give a lot of feedback.



And then I got the error I was suspecting:



I was expecting it because Apple says that you have to say what changed in a "Version_whats_new" XML file. I hadn't been able to find where that was.

It turns out I had downloaded the latest version of iTunes Producer, but I hadn't installed it. Once I did that, I was able to add the What's new information on the Book page:



Then I delivered the package again (no need to upload the book files again), and it went through without a hitch.

What I am most interested to see now is how it notifies me (and all of you who have purchased the book through the iBookstore) about the new changes. The new description went live almost immediately, but when I go to iTunes Connect, it tells me that the EPUB 3 version is under review.



And indeed, I don't see that little update icon that Tim Cook promised. Though I'm left with questions: When does iBooks check? Does versioning only work in iBooks 3? Do I have to open and close the app to force a check?



When I go to the Purchased section of the iBookstore, I also see that it shows that the book was already downloaded and I have no opportunity to update it. I assume that when the changes go live, this button will change.



If you haven't bought the book yet, you'll be able to tell if you have the new version by checking page 24 and clicking the info arrow to see where those arrows show up.

And I'll keep you posted about how long it takes to go live. It seems like a really important feature to me. I would have liked to add a note or bookmark to see if those are maintained, but fixed layout format doesn't allow them. I'll have to update one of my other books...

Non-allowed characters in filenames in EPUB

I got an email from a reader yesterday wondering about an error that iTunes Producer was giving as it rejected his EPUB submission to the iBookstore (despite having passed EpubCheck with nary a murmur), to wit:

ERROR ITMS-9000: "Invalid URI in NCX file Title Page.html :
Illegal character in path at index 5: Title Page.html" at Book
(MZItmspBookPackage)

When he converted the spaces to underscores, the errors went away and iTunes Producer accepted his book.

His book was originally created in InDesign, and it was InDesign that failed to convert the spaces to their hex equivalents so that iTunes Producer wouldn't choke.

Until Adobe updates its software, and for everyone who codes on their own or with some other tool, I recommend restricting filenames to the 26 unaccented letters of the English alphabet, the dash (-), and the underscore (_). That includes the names of documents in an InDesign book, images, videos, audio, CSS files you apply upon export, whatever.

Note that you can have spaces in titles, say Chapter 1, just not in filenames of those chapters, e.g., chapter1.xhtml.

A quick search on Mobile Read reveals that this is not a new issue.

Thanks so much to Edward Matte who brought this to my attention and shared his error reports and progress with me (and all of us).

Back in the USSA

Almost a week and it both feels like we've always been here and like I'm a time traveler overlapping my steps, looking at the old me living my old life. Very strange. It's going to take a few days to get up to speed. But I've got lots to talk about!

My Catalonia Press has published a new book, “What Catalans Want”, by Toni Strubell, a collection of interviews of interesting and important Catalan public figures, including Jordi Pujol, Oleguer Presas, Elisenda Paluzie, and many more. It's available in gorgeous color (with beautiful photographs of the interviewees by Lluís Brunet), will be available in a more economical black and white edition, and or course can also be found in EPUB and Kindle formats, from Amazon, Apple's iBookstore, or directly from Catalonia Press, where you can also download a sample.

Next, Apple has just published a new iBookstore Assets guide (4.7 Rev 4), which promises to give information about creating Read Aloud EPUB books. If you're an iTunes Connect member (more info here), you can download it from the Deliver Your Content section. (I have a new miniguide coming soon on the same subject, and will announce it here as soon as it's ready.)

In addition, there's a new version of iTunes Producer (2.4) available from Software Update that promises that "common EPUB errors can now be fixed automatically". Not sure what that means, but I'll let you know when I do.



Finally, I recently noticed that two EPUB samples that I had posted to the iBookstore over a year ago had just been approved by Apple. It wasn't that they were studying them all this time; they had said they were not accepted into the iBookstore because they were just samples. I disagreed, couldn't figure out how to delete them altogether and just left them there languishing with those sad red dots. Imagine my surprise when I look up my Sales info and see that people are downloading them left and right. It doesn't seem quite right to me that Apple should first reject them and then a year later decide to approve them without telling me. For the record, the samples are about how to embed audio and video and are OK as far as they go. They are pretty outdated, however, and have been superseded by my much more complete Audio and Video in EPUB miniguide.

More soon!