Troubleshooting EPUB ebook files

I get emails all the time asking me if I can help figure out what's not working in someone's web site or ebook. Generally, I don't have the time to futz with other people's files, mostly because I'm futzing with my own. It's amazing how easy it is to introduce minor errors that then hide from you right in plain sight. I'd like to show you my system for finding them.

Here's what happened. Some new friends from Girona, who are publishing image-laden travel ebooks were trying to use my photo block technique outlined in Expandable Photo Blocks in iBooks on iPad. But they had two problems. First, the initial line of photos was shifted to the right a few spaces, and second, the photos were not opening up full screen when double-clicked.

 

OK, so shifted photos and they're too small.



Is it CSS, XHTML, or something else? My first line of attack is always to find a similar file that works and compare it with the file that doesn't work. Since they had used my Waldenphotos example as a starting point, I opened up that document to compare.

The first thing I noticed was that the CSS that I had put in the header of the XHTML document was now in the external CSS for their document. Could that be what was causing the problem? Certainly I had found that iBooks sometimes treats external CSS erroneously. So I copied the original CSS from my Waldenphotos example to the travel book and tried it out. Nope, same shift.

OK, what else is different between my file and theirs? Could they have some weird CSS? I didn't feel like going through their CSS, so I just changed the name of the CSS file so that it wouldn't load. The shift remained. (This would cause an error on EpubCheck, of course, but an EPUB file doesn't have to be valid to be viewed and tested in iBooks.)

A bit flummoxed, I decided to copy the whole photo block from my example to theirs. I tend to do this sort of thing last, because it involves copying all of the images as well, but I couldn't think of anything else about the code that could be the problem.



My photo block worked. Now I know the issue is not about CSS, it's either the XHTML or the photos.

What else is different between what works and what doesn't? Could it be the photos themselves? I suspected they weren't the proper size since they weren't going full screen, could smaller photos result in that shift as well? I looked at them and found that indeed, they measured 640 x 480 each. I resaved them at 1600 x 1200 and retested, but the shift remained (although now they went full screen when double-clicked).



(Note that resizing them from 640 x 480 to 1600 x 1200 results in pixelation. This wouldn't be a good method for fixing the photos. But since I was interested in what was making them display so small, I didn't care about the pixelation.)

Next, I insert their photos into my XHTML code. There's no shift.



That rules out anything about the photos themselves. It must be the XHTML code. I'm staring right at it, and I'm telling you I can't see anything different. I go bit by bit, checking for extra spaces, or something else weird. Nothing.

Next, I try comparing the two blocks of code using BBEdit's Compare Two Front Documents. This is the kind of work a computer excels at. Unfortunately, when the spacing doesn't match between two documents, BBEdit has a hard time pinpointing where the problem is. Even though the code is practically identical, it tells me that they are completely different because there are returns in different places.

BBEdit added a new feature to its compare command that tries to show you just where the difference is even in a long line. But at first, it's so subtle, I don't really notice it.

So, I try to match up the returns and spacing. BBEdit is still telling me that the files are different but it's not showing me anything obvious.



So, it must be something invisible.

I use BBEdit's Show Invisibles command to show the returns and spacing around the photo block code.



And there it is.



Three gray bullet marks in their photo block. I don't know what they are. A sideways L is a return, a triangle is a tab, and a dot is a space, but I'm not familiar with bullets. Google finds me this enlightening article: they are non-breaking spaces. I remove them and test again, and the shift disappears.



There's still one important step. What if all of those other things I tried somehow combined with the non-breaking spaces to remove the shift? So I go back to their original document, with the CSS intact and the original photos, and I remove the non-breaking spaces. If the spaces were the problem, the shift will disappear. If not, it was a combination.

When I retest, the shift is back!



Aargh. I go back to the XHTML document and realize I didn't save before compiling the EPUB. I make little mistakes like this a lot... and am used to checking the simple stuff. (Are you working on the file you think you are? Is it in the folder you think it is? Did you save the changes? Did you type it right?) I save the XHTML file, rezip again, and send it back to iBooks. This is test #13. Unlucky? Nope. It works.

 

This shift is gone and we now know for sure it was due to the non-breaking spaces. Now we can move forward.

One of the most excruciating parts of the troubleshooting process for me is making very small incremental changes when I want to change everything at once to see if I can fix it. The problem with changing everything at once is that you then don't know what the issue was, and how to avoid it in the future.

And with ebooks on the iPad in particular, remember that iBooks has that annoying caching habit.

Images and example file used with permission.

Apple's iOS is nothing without the Apps

Do you know the story of the fisherman who pulls a goldfish out of the sea? It offers him a wish if he will throw it back. The fisherman asks for a loaf of bread. He goes back to his wife who berates him and sends him back over and over, each time asking for and receiving more and more and more from the fish. The sea is each time more stormy, the fish more crabby, and the wife more greedy, until her final wish to be made ruler over the sun and the moon is too much even for the fish. This time when the fisherman returns home, he finds that the palaces and wealth earlier given by the fish are gone, and they have returned to their initial, miserable existence. I thought of this story today as I bombarded my poor Twitter followers with my outrage over Apple's statement yesterday, and I finally decided it would be better in a coherent post than in highly-edited mini-bites.

First, Apple's statement says two important things.

1: If you have an app, and you sell anything for it anywhere, you MUST offer those same things at the same price in-app. (In-app is Apple-speak for using their API and giving them 30%.)

Here's the direct Apple quote: "However, Apple does require that if a publisher chooses to sell a digital subscription separately outside of the app, that same subscription offer must be made available, at the same price or less, to customers who wish to subscribe from within the app."

So, if you sell ebooks on your website and giveaway or sell an app that reads those ebooks, you MUST offer in-app purchases of those ebooks.

There are some that are saying that as long as you don't link from the app, then you're OK. That's not what this says. It says if you sell content elsewhere, you must sell it in-app through Apple.

The one thing that it doesn't say is how this policy affects those of us who generate content but do not sell or give away apps. Me, for example. I assume Apple is not requiring itself to sell my book in-app, despite the fact that it can be purchased and loaded into its iBooks app.

To take that scenario further, what about if someone besides Amazon developed a Kindle-book-reading app? They, presumably, would not have to offer Kindle books in-app. That doesn't facilitate the buying experience for readers, but it keeps Apple out of Amazon's pocket.

2: You may not offer links from your app to your website.

The direct Apple quote: "In addition, publishers may no longer provide links in their apps (to a web site, for example) which allow the customer to purchase content or subscriptions outside of the app."

Now, maybe you could interpret this to mean that links to parts of your web site that aren't direct sales are OK, but honestly, I wouldn't want to be relying on Apple's largesse on this point.

Me? I think Apple has gone too far. They are acting as if they, and they alone created this big happy universe populated with hundreds of millions of credit cards just waiting to be charged and that app developers are just interloping goldminers trying to cash in.

But iOS is nothing without the apps. What would you have? Mail? the phone that didn't work until Verizon finally offered coverage? Safari? The clock? Oh yeah, the gyroscope, ooh!

Apple owes more to its developers than a capricious change of policy whenever it feels like it. Not to mention to its users who didn't expect that a large number of apps on which they relied, for which they actually bought the device, would suddenly stop working... or cost 30% more.

More reading:
Apple Statement: Apple Launches Subscriptions on the App Store
Apple's Big Subscription Bet: Briliant, Brazen Or Batsh*t Crazy?
Apple is actually asking for 10% of SaaS mobile revenue
Does Apple really want to have a "no links to your local bookstore" rule?
Apple's New Subscription Model is Evil
Apple's Subscription Rules Raise Possible Antitrust Issues
Apple's New Subscription Rules Could Kill Streaming Music Services
Why Apple's Change of Subscription Service Rules Will Backfire, For The Users
Rhapsody won't bow to Apple's subscription policy

EPUB Straight to the Point - in other languages

I just got a note from a reader in Germany who bought EPUB für iPad & Co:Ebooks erstellen und optimieren von Text bis Multimedia, the German translation of my EPUB Straight to the Point, published by Addison-Wesley Buch with an ISBN of 978-3-8273-3051-2. He wanted a copy of my new Fixed Layout miniguide. After I sent it to him (it's free to anyone who's bought a copy of my book, from any store, in any language), I went to find the German edition, which I didn't realize was already for sale. It's for sale on Amazon.de, among other places.

There's also a Dutch edition. I know this because the Dutch translator sent me a photo! It's published by Pearson Education Uitgeverij and is called Aan de slag met ePub. Its ISBN is 9789043022163.

The prize for first translation, however, goes to Pearson in France for the French edition, Créez des documents ePub: Concevoir des livres électroniques pour iPad et autres liseuses, both in print and in EPUB, without DRM! Awesome!


Do you have a foreign language edition of EPUB Straight to the Point? I'd love to hear about it, and what you think of it.

Page Breaks, Turning off Hyphenation, and Horizontal Bolding Bug in iBooks

Apple came out with version 1.2.1 of the iBooks app yesterday and though I haven't had a chance to look at it carefully, I have been hearing from Twitter that the page-break bug that I mentioned in Page Breaks in iBooks 1.2 —in which the CSS page-break properties had to be in a local stylesheet within the XHTML file instead of in an external CSS file—has been fixed. External CSS now works as it should. Yay.

The second thing that I wanted to mention was that iBooks 1.2 is a bit bossy with its new hyphenation feature and applies it automatically to every paragraph in your document. But, you probably don't want to have hyphenations in your headers.



To suppress hyphenation, you can use the -webkit-hyphens property (Thanks, Rick!) just on your header elements:

h1, h2, h3 {-webkit-hyphens:none;}

Finally, I've just noticed something very strange in iBooks. When I hold a book vertically, my headers are in a normal weight.



But when I hold it horizontally, the headers are suddenly displayed in boldface.



I can't quite figure out why this might be. There is no font-weight assigned to the header elements at all. Seems like a bug to me. Lord knows I've certainly tried to achieve different layouts in different orientations!

Fixed Layout EPUBs for iPad and iPhone

In December, Apple released version 1.2 of iBooks, their ereader app for iPad, iPhone, and iPod Touch. There were a number of interesting features added, including support for hyphenation and page breaks, but the feature that caught most eyes was the ability to create “fixed layout” books in which text and images could be precisely positioned in horizontal two-page spreads in order to approximate a children's book or other image-heavy non-fiction book.

I'm not completely convinced by the idea of fixed layout books. I find them complicated to lay out and not much more useful than a PDF for reading the content. They lack EPUBs most important feature: the ability to reflow when the size and font of the text are changed.

On the other hand, they do let you make really beautiful pages in an EPUB-format file!



And since people have repeatedly asked me to explain how to create these fixed-layout books, I took advantage of the opportunity to do something I've been wanting to try for a while: publish a miniguide companion to my EPUB Straight to the Point book. This miniguide explains everything you need to know in order to created fixed layout EPUB files with spreads, images, and embedded fonts.

If you already own a copy of my EPUB Straight to the Point book, I'll email you the miniguide free of charge. In fact, it may already be in your inbox. If you don't receive it automatically, just drop me a line, with your name, email, and proof of purchase, and I'll get you a copy.

If you haven't bought my book, you can buy the Fixed Layouts miniguide separately for $4. As a bonus, you will receive a $4 coupon toward the purchase of my EPUB Straight to the Point book. The only catch is I can currently only offer you the $4 coupon if you buy the EPUB version of the book from my site. The coupon won't be valid anywhere else (but I'm working on it).

Got any questions? Let me know. As always, I'd love to hear what you think.