Wednesday, February 23, 2011

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.

 Photos shifted at top

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

double-click doesn't fill screen

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 photos, my code

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).

expanded photos

(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.

my code, their photos

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.

show invisibles2

And there it is.

The problem

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.

Shift is gone

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!

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.

 Problem solved

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.


  1. Non-breaking spaces can be very useful in formatting poetry in an ePub but their invisibility can be a vexing problem as you've shown. So we should keep our fingers away from that Option key on Macs.

    On a Mac, you can type a non-breaking space with Option + Space. It's harder on Windows (see:

  2. And, much thanks for your help in clearing this matter up for me! (I'm the rank beginner who got those non-breaking spaces into my document by accident.)

  3. In general, I think it's best to use BBEdit with Show Invisibles on. But then, I use nonbreaking spaces a lot in HTML and XML. It's a way to make sure that a space (in any position), multiple spaces, a blank line, or even an entire empty paragraph is respected. You can use them to shift an element slightly left or right (as in your example). You can also use them as a fixed-width space in justified text. And of course, you can keep text together, as with an initial with the rests of a person's name. The list goes on.

  4. Quick question for you. I can't seem to find anything that shows me how to embed an audio file in an eBook created on Pages on my iMac. I don't want the reader to need to navigate to a webpage.

    Many thanks.

  5. Thanks for this post which let's us know that the experts get stumped by the little things, too. The problems really challenge our brains to think creatively. I've learned to stick with it, and I'll finally find the solution.

  6. I can't export any video to work in anepub format. I'm using cs4. I can see it fine as a PDF on a computer but not the iPad. Is this something adobe is working on?
    Any ideas?

  7. Is there a way to insert a non-breaking hyphen in an epub and have it honored in readers like the iPad, kindle, etc.? I have a hyphenated brand name that canoot be split on two lines.

  8. To replicate the effect of a non-breaking hyphen, try wrapping in <nobr> tags.

    For example:

    <nobr>non-breaking</nobr> hyphen

    This worked for me in iBooks.


More of my books