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.