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, addingversion="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 anol 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 themeta 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...
