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...
I think it may also require iOS 6 on the device, though I'm still trying to get a real confirmation of that.
ReplyDeleteI can add a few things about my eBook Typography book
ReplyDeleteMy first change to 1.1 got accepted very quickly, but then I may have been one of the first to try it out. The problem was that this first revision had a problem. ... I left in the com.apple file as well as adding the meta tags in the opf. This meant that embedding fonts didn't work, so I was desperate to re-version again.
Second change to 1.1.1 was in review for a good while and then I was told in he ticket that the changes We're too complicated for people to understand. It's did NOT come in an email, so I missed it for a while. OK I fixed this and 1.1.1 is available now.
When in iBooks3 on the iPad you will see a little number top left in your store button. And then under purchases my book will indicate that it can be updated.
The version information does show in iBooks store but ONLY the last version info shows up in the web page for the book at Apple. This has now led me to create yet another version with my version popup to have a version history! maybe a version history page would be a good idea if we are to move books into the same, space as apps. maybe ePub:type versionhistory ��
One more thing. Currently my book does not show as being 'iBooks3 required' on the store. I suspect that this might be because I left in the NCX TOC as well as the XHTML one. I though we needed that to be backward compatible, but I will remove this and see what happens.
Hi Liz
ReplyDeleteMy ePub3 flow book was validated with no errors. Can view on other devices. But when open with iPad or iPhone it crashed or freeze. What would be the problem? I also follow apple Guide line too.
Best
Tayy
Thanks for this article. I'm working on two ebooks in InDesign and you've convinced me that I need to get them right the first time. Updating won't be just a matter of uploading another file.
ReplyDeleteHi Liz,
ReplyDeletein the article, you mention adding 'meta property="ibooks:version"' twice in the opf.
(First 'meta property="ibooks:version">3.01.1</meta'.
As I try to understand it, determining it's epub-3 is done in the package-element, but Apple makes it confusing by using a "ibooks:version 3" example in their documentation later on as well.
Hi Liz,
ReplyDeleteWhat version of iTunes Producer are you using? I had used 2.8 (333) and uploaded a newly versioned 1.0.1 epub 3.0 along with the What's New box filled in, and it complained about only epub3 files being allowed to have the What's New box filled in. So I removed the contents of the What's New and the epub seemed to upload ok, though I still received the "Version_whats_new" messages you refer to. Then I pasted my What's New back in the box, and uploaded just that change and it seemed to send ok too! How odd.
Anyways, my 1.0.1 has been "in review" for over a week now. By the way, on top of the versioning, one thing I really like about the latest changes is that they decided to get rid of the options file. Great news for people like me who are aching for a more standard approach to building these epub files.
rgds
Tim
I have been in touch with Apple about all of this, and I think they are as confused as me!
ReplyDeleteThere are a few issues which may get resolved:
If I look at the page for my book on the iBookstore FROM my iPad (through the iBooks app), then I can see a version history. Not only that, the line breaks in my version text are respected.
This is good news but:
When I look at the iBookstore in a browser (iTunes.apple), then I only see the latest version number and description. This text does NOT respect my line breaks that I entered in Producer.
If I look at my book in iTunes then there is no version information at all.
My next version will include a version history, so I can be sure that my customers see all changes if they have leapt over a previous version.
I imagine that you've noticed that iTunes Producer 2.8 now enables one to publish in many countries without the hassle you chronicled n earlier versions. They must be listening.
ReplyDelete"adding the namespaces that Apple recommends."
ReplyDeleteWhere can i find out about this? Can't find it anywhere. Tried some things but always get Epubcheck error about "ibooks" (with epubcheck 3.0-RC-1). Any examples available that have this part?
thanks
In answer to last comment (mine), I think I found the required info in the Asset guide which I had difficultly previously locating on Apple's website
ReplyDeleteI believe that versioning is also available for *.ibooks files created with iBooks Author.
ReplyDeleteFrom Sweden:
ReplyDeleteI wasn't aware that iPad already has EPUB3. Any write-up available on bugs (if any :-) and which features are supported and which are not? Any other readers that support EPUB3?
Regarding versioning with epub 3 and this metadata line:
ReplyDeletemeta property="ibooks:version">3.0</meta
Are we supposed to leave this line out of the opf file if it is the original book. Or is the meta property line to be included with the number 1.0, for book version 1.
I'm confused since Liz's monarch book has version 3.0 as part of the information section on the itunes store description page. There is no versioning history included?