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 fileI began with the OPF file, adding
version="3.0"to the initial
packageelement 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:
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:
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:
<item id="milkweed" href="milkweed.xhtml" media-type="application/xhtml+xml" properties="scripted" />
And then I removed the
guidesection, which is no longer required by Apple (and was already deprecated in the EPUB 3 spec).
<!--new to 1.1 guide is removed -->
New TOC fileEPUB 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
ollist 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>
<li><a href="title.xhtml">The Monarch Butterfly Book</a></li>
Then, as a replacement to the
guidesection, add a landmarks section, which works very similarly:
<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>
Finally, declare the new toc.xhtml file in the OPF file, paying special attention to the
<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 filesIn each of the XHTML files, I had to change the
metatag where I declared the character set. It was:
<meta content="text/html; charset=UTF-8" />
and it should be:
I also had a few documents that somehow still had extraneous
DOCTYPEelements. 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">
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:
ValidatingOnce 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 iBookstoreFinally, 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...