Wednesday, June 30, 2010

Beating iBooks Bugs

Yesterday and the day before I spent an inordinate amount of time doing trial-and-error testing with iBooks 1.1's latest bugs. Basically, if the default Full Justification is left ON in the Settings panel for iBooks, iBooks then overrides any left alignment setting specified by the book designer. Indeed, center alignment is often disregarded as well.

I posted my fruitless efforts to this blog and shared them on Twitter in the amazing #eprdctn group, and this morning found that others had worked on this problem and found a solution. I am in awe of the cooperation, generosity, and sticktoitiveness of this group. Thank you!

There are two parts to the problem. For some reason, iBooks ignores the text-align property when that Full Justification setting is ON. It is also known that iBooks ignores any font information set with the span tag.

The solution, discovered by Anthony Levings, is curious. Just by inserting empty span elements (no class necessary) within each and every p element, and without assigning a single CSS declaration to the span itself, iBooks suddenly pays attention to the text alignment settings in the CSS of the p element.
Fixing Apple's bug

Rick Gordon, meanwhile, reminded us of The Span Bug: iBooks ignores font information applied through a span element. Rick suggests using some other element besides span, like the otherwise little-used cite, so that you also maintain a given font for the body of the ebook. And while it is true that using an element in this way is a hack, it is also true that the resulting ePub will validate, will have the font the designer intended, and will not break in other ereaders. It is also true that if Apple would follow the EPUB standard, these hacks would be unnecessary.
Fixing Apple's bug

It's important to remember that (according to the official CSS spec) the text-align property only works with block-level elements, so it must be applied to the p selector. On the other hand, since iBooks doesn't support applying font information to a p, div, or span element, you must declare the font information with the cite element. In addition, many ereaders/browsers apply italics to cite by default, so you'll have to add font-style: normal to neutralize that effect.
Fixing Apple's bug

It is my personal opinion that standards are an extremely important tool and that software manufacturers (read: ereader and web browser creators) should follow the published and specified standards so that those of us creating content can be confident that what we create will work in as many ereaders/browsers as possible and be compatible not only with current but also with future versions of the software. It is only when we all agree on the rules that this is possible.

When those software manufacturers don't follow the rules, I believe we content creators have the liberty to work around those deficiencies, but that we should do so in the most standards-compliant way possible.

So, in this case, Apple doesn't follow the EPUB spec that it says it supports and ignores a perfectly valid CSS property, text-align. Designers add in fairly harmless span elements that solve the problem. I call that an extremely reasonable compromise. 

Apple doesn't follow the EPUB spec in allowing span elements to convey font information. Designers use less common XHTML elements in a non-semantical way to resolve the issue. I am less comfortable with this solution, since using those elements in non-standard ways deprives them of their true meaning. Nevertheless, since those elements are rarely used anyway, I'm willing to go with this compromise as well.

You will have to make your own judgment.

And if you want to learn the latest in ePub creation techniques, or share some of your techniques with the rest of us, come visit us at #eprdctn!


  1. Thanks for drawing all this together, and for the mention. One thing that I think might need to be clarified for newcomers is that the 〈p〉 and 〈span〉 classes do allow you to specify font size, colour, weight, text align, margin, and so on. It is just font-family they don't take any notice of. This is important because don't (at least some) ereaders ignore 〈i〉 and 〈em〉 tags meaning that italics and bold, etc. should be applied using 〈span〉 classes?

  2. Liz,

    Thanks for helping to pull all this together in a coherent package. It really does help keep it sorted out.

    Your tireless efforts in this skirmish really are appreciated.

    Walt (

  3. liz said:
    > It is my personal opinion
    > that standards are
    > an extremely important
    > tool and that software
    > manufacturers (read:
    > ereader and web browser
    > creators) should follow
    > the published and specified
    > standards so that those of us
    > creating content can be
    > confident that what we
    > create will work in as
    > many ereaders/browsers
    > as possible and be
    > compatible not only with
    > current but also with
    > future versions of the
    > software. It is only when
    > we all agree on the rules
    > that this is possible.

    that certainly sounds reasonable.

    but it ignores a certain reality,
    which is that the programmers
    actually determine the reality;
    the spec-writers merely engage
    in a form of wish-fulfillment...

    the .epub format was created
    by the corporate publishers,
    who have proven themselves,
    time and again, to be dinosaurs.

    i often think "i.d.p.f." stands for
    "i design poor formats".

    even now, some 10 years after
    the first version of .epub was
    put together, there is _still_
    no reference implementation.

    if the i.d.p.f. was _serious_
    about this format, they would
    have coded open-source
    reference implementations
    -- both a viewer-program
    and an authoring-tool --
    as the first order of business.

    and they would have included
    programmers as consultants
    -- the primary consultants --
    as they designed the format.

    and they would have made
    a _simple_ format, instead of
    this monster, which is fraught
    with unnecessary complications
    of the type you talk about here.

    but i think they made the thing
    obtuse on purpose, trying to
    raise the bar to entry for the
    smaller publishers and authors
    who want to do it ourselves...

    so the price is being paid now
    by people like you, who have to
    plow through the resultant mess.


  4. The validator cannot tell you are using the wrong element for the semantics of the document. So no, you can’t use CITE for a non-CITE purpose any more than you can use empty SPANs with classnames. You can’t.

    Further, only paragraphs following other paragraphs are indented, not all paragraphs. Hence p+p { text-indent: 1em }.

    Actually qualified Web developers need you to support Web standards, the foundation of ePub, and not to act like a 1997-era Razorfish hack throwing darts at a board with HTML “tags” Post-It-Noted to it.

  5. @joeclark: You're correct that adjacent sibling selectors appear to work in iBooks, which is a good thing to be exploited. Please note though, that this was code directly from an Apple document, not something that Liz or anyone here cooked up — blame Apple.

    Secondly, the approach of everything being a classed p tag with spans even where they serve no purpose is the way InDesign (unfortunately) generates epub code — blame Adobe (or blame the production person who didn't want to toally rewrite it).

    As far as a book developer being willing to write hacks to get around bugs, flaws, and omissions in iBooks' rendering (blame Apple again): People will do what they need to do to get the result they want. Since formatting epub code for submission to the iBooks Store is essentially a closed-loop process targeted for a single platform, the ramifications of moving away from semantic orthodoxy is less heinous than where you are puttin up a web page which might be rendered on any browser. (And actually, at this point, I've decided that the abbr tag is a better candidate than cite, since it is even less needed.

    I take your point that it's a hack; and I don't like it. But I believe that in a closed-loop system, the end justifies the means, especially when the only viable alternative is to dumb down your code so much that 1997 sounds like the future.

  6. And, of course, it wouldn't even be a "hack" at all if Apple had just been upfront from the beginning that they weren't going to really support the ePub standard. It would just be "iBooks format" :p

    Steve Jobs said "We use the epub format: It is the most popular open book format in the world." So of course ePub publishers should be irritated that their ePub standard files don't display properly.

    Complaining about this or that being a "hack" or "poor coding" is ridiculous-there IS no "good coding" practice to work off of right now. Everyone here KNOWS these aren't all perfect ePub practices. iBooks is NOT an ePub display program. They ARE workable iBooks practices for now, and I for one am grateful they are available :)

  7. Hello Liz, thanks for all of your debugging suggestions. Perhaps you have a solution for this one.

    I am trying to use the margin-bottom property to add space between paragraphs (to resemble your first winnie the pooh photo here

    Here is the CSS I'm using. It works great in Calibre and Digital Editions, but seems to be ignored by the iPad. Any thoughts? Thank you much!

    .body {
    color: rgb(0, 0, 0);
    display: block;
    font-family: "Verdana";
    font-size: 0.88889em;
    font-style: normal;
    font-weight: normal;
    line-height: 1.2em;
    margin-bottom: 0.6em;
    margin-left: 0;
    margin-right: 0;
    margin-top: 0;
    text-align: left;
    text-indent: 0

  8. I haven't tested it, but my first thought is to add !important.

  9. That worked great, thank you so much!

  10. btw, on the bullet issue, i changed the font-family to inherit from "Verdana" and that solved it, in case you hear of anyone having issues. thanks

  11. Thanks Liz — you're providing a great resource for struggling ePub creators.
    Do you know if anyone found a way to disable iBooks' auto-hyphenation? (another thing it does surprisingly badly).

  12. Yes, you can disable iBooks' auto-hyphenation by adding a line in the body definition:


    (Thanks to Rick Gordon for this info.)

  13. Thank you, thank you, thank you.
    I'm finding it difficult to track down such seemingly basic information. You have just solved the last piece of this excrutiating puzzle (at least for my current project).
    Does your HTML, XHTML & CSS book cover such intricacies of creating ePubs specifically?

  14. @Dwayne. So glad to have been helpful. It's pretty tricky, isn't it?! My HTML book does not talk about EPUB specifically but it certainly gives a good background on using HTML and CSS that you can then use to format your EPUB files.

    My EPUB book talks about specific techniques with HTML and CSS for EPUB itself.

  15. I ended up "solving" the centered-text problem in iBooks by defining the h6 tag to look like plain text, but centered. I don't use h6 for actual headings (I never need to go down that far), so there's no conflict; and for whatever reason, iBooks seems to respect the alignment of headings.

  16. Have anyone tested it in iBooks 2.1 ?
    Because it doesn't work for me in iBooks 2.1...

  17. Please note that the "put empty span tags inside the heading text" trick no longer works for left-align and p tags with the latest version of iBooks. I guess they read this post! It does seem to still work for center and right-align, but that is not the big problem, the big problem is left-align headings.

    When using indesign, the solution is to not convert headings to text using the main menu or right-click options (that maps them to p tags that CAN NOT be left-aligned), and to choose Bullets: map to unordered lists, and Numbers: map to ordered lists in the EPUB Export options dialog, which maps them to ul and ol tags which ARE left-aligned.

    Then there is no problem.




More of my books