Monday, September 27, 2010

On using Pages for EPUB (part 1)

Apple recently announced that they had added EPUB export to their word-processing software, Pages. If you already own Pages, you just have to go to Software Update to get the new features. My first tests show that it creates perfectly reasonable EPUB files that pass EpubCheck 1.05 with no errors.

Several people have asked me to do a quick rundown on the usefulness of this feature, and so I've been playing with it to a bit. But lately, I've been having trouble doing anything quickly, so instead of obsessing about getting this just right, I'm going to write a series of blog posts as I pull out all the details.

Before I write anything else, I have to tell you that I'm used to laying out technical books in InDesign. With that in mind, I will try not to complain about (or even mention) Pages' weaknesses as a layout program, and instead concentrate how it converts its documents to EPUB format.

Use Word Processing Templates

First and foremost, you should always choose Word Processing templates (or blank ones) when doing an EPUB project. Pages won't let you export documents based on Page Layout templates.

Use Inline Images (not Floating)

Second, most of Pages’ templates include so-called “floating images” which do not export to EPUB. You either have to choose a template with inline images, or convert the images yourself before exporting. For the record, Pages uses the word floating in a way that is quite confusing for those already versed in web design, where floating has to do with text wrap. Indeed what Pages means by floating is much more akin to “absolute positioning” in CSS. Indeed, it means that the image is not linked to the text, and is instead fixed to a particular area of the page (where it “floats”). If you add more text around or on top of the image, its position is not affected. Since there are no physical pages in an exported EPUB, it doesn't make sense to export a “floating” image.

An “inline image” in contrast is anchored to a specific spot in the text. Add more text before or after that point and the image will move to a new position on the page. EPUB documents are rivers of text and inline images.

You can also choose whether or not text should wrap around your inline images, which I describe in more detail in the next section.

Note that to add inline images to your document, you must hold down the Command key while dragging an image from the Media box. You can also select an existing image, go to the Wrap section of the Inspector, and choose Inline (moves with text).

It's rather easy to stick images between words. That'll look OK in Pages,

images within text in Pages

but it won't look at all right in EPUB.

Image within text, in iPad

Be sure that the anchor symbol is at the beginning of the paragraph.

Wrapping Text around Images

Pages does support wrapping text around images, and even exports such wrapping to EPUB (in contrast with InDesign). Simply go to the Wrap section of the Inspector and choose the desired wrap configuration.

Unfortunately, you have to assign the same amount of extra space to three sides of a wrapped image. That is, if the image is wrapped to the left, and you accept the default value of 12pts for the Extra Space in the Wrap Inspector, Pages will export the image with a style that assigns the margin-bottom, margin-top, and margin-right to precisely 2.5641%, which for the margin-top and margin-bottom is exactly 2.5641% too much, especially if the image should be aligned with the top of the paragraph. The result isn't so pretty:

Text Wrap in Pages in EPUB

You have to decide whether you'd rather have the text jammed up next to the image on all three sides, whether you'd rather have extra space on all three sides, or whether you're willing to go into the EPUB and manually change the CSS (which you can read about in my book).

Creating a Cover

Pages has the useful but perhaps tricky option of converting the first page of your document into the cover of your EPUB file. It basically takes a screenshot of all the images and text on the first page and saves it in PNG format, and then designates the PNG file as the cover. This is signficant for a few reasons. First, this is the only place in your EPUB document where you can maintain the exact layout of the original page. If your text begins in the middle of the page, it will begin in the middle of the page in the cover as well. If the image takes up half the page, it will continue to do so. This means that you should be careful to choose a section that has a layout that will make sense as a cover. In particular, if you reduce it to a tiny icon, will it still be legible?

And unfortunately, the quality of the resulting PNG file is less than stellar. The only place you can really see the cover in a large size is opposite the table of contents when you're holding the iPad horizontally. In my rough example, it's pretty blurry:

Cover from Pages in iPad

I guess I'd recommend using really big text, and not very much of it.

If you don't use the first page as the cover, Pages makes a screenshot of your first page anyway to display opposite the table of contents, though it uses a generic icon of the book in the book list.

Aligning text (centering, justification)

Here, Apple falls into its own trap. You can set the alignment (centering, justification, or just plain left or right) in Pages, and it even exports it properly, but because Apple displays all text as justified in iBooks unless you use special tricks, the text in the exported EPUB won't be aligned as you wished.


Pages exports information for the following CSS properties for each and every paragraph (you can forget the Cascade): color, font-size, font-style, font-variant, font-weight, letter-spacing, margin-bottom, margin-top, padding-left, padding-right, text-align, text-decoration, text -indent, text-transform.

Not only that but it gives values to 4 decimal places! Four! A retina display for the iPad must be coming soon...

I write in my book about the perils of specifying too many values in the CSS: basically, you're breaking the Cascade of inheritance on which CSS gets its strength.


You can choose to create section breaks, page breaks, column breaks, and layout breaks. The most you'll ever get is a <br style="clear: both;" /> That's not going to get you an actual page break, or any other kind, but it will keep the text that follows from wrapping around any previous elements. I've found that the Layout Break is the most useful for this function as it doesn't add extra page breaks in Pages (which, of course, does support them).

(To be continued)


  1. Many thanks! I suspect these glitches are the result of Apple's internal policy of rating 'intelligence' over real-life experience. According to some reports, people who work with OS X are shifted to iOS and back, resulting in delays for one or the other.

    The iPhone 4 antenna debacle was a result of not having anyone on the team with hand's on experience with radio transmission. An old radio ham myself, the instant I heard Steve Jobs hyping that external antenna band I thought, "But you can't touch an active, transmitting antenna!" The same can be said about ePub coding. Experience matters a lot.

    Apple's stumbles with iBooks and now ePub for Pages suggest that there are few (if any) people experienced in book layout (and the underlying coding) at Apple. Smart these people may be. But they also seem lost and thrashing about. Programmers are being asked to make decisions that programmers shouldn't have to make.

    Liz, if I knew Steve Jobs personally, I'd be lobbying him to hire you as their ePub/ebook consultant at some fabulous fee. Alas, I don't, so all I can do is encourage you to keep pointing these flaws out in the hope that someone at Apple is listening.

    --Michael W. Perry, author of Untangling Tolkien

  2. Yes, I too am very grateful for these very helpful insights.

  3. Liz, I'm preparing an ePub book with many pictures. I find the pics don't make it to ePub if there are too many (25±) in a chapter.

    For those of us who want to use ePub for photo books, do you know where I might go to find out:

    What the file size limitations are.

    What are optimum pixel dimension and ppi. (I've tried your recommended pixel size— 600 x 860 px), but pics are fuzzy when double-tapped.

    I realize it's just the beginning, but would like Apple to see that ePub and iPad are potentially great tools for pictures as well as text. Thanks

  4. Apple provides a "best practices" document that I found so useful that I imported it as a template. It can be downloaded at:

    This template will have the necessary paragraph styles predefined for you. They can be selected from at least three different areas of the application. In addition to the MacLorem type text fillers, there are lots of hints and other useful info.

  5. Hi Liz. You mention that you use inDesign for your technical books. Do you have a workflow tip for converting apple Pages documents to inDesign? thanks, Alan

  6. Hello, I am curious about being able to place Text over a picture, While leaving the text separate so that it may still be re sized. Is this possible?

  7. iBooks is still misbehaving! I've created a book with inline images and text wrap as you've discussed, but I notice that whenever the div block (image and caption together) is pushed to the next page, iBooks more than likely will run the text on top of the image. It's frustrating to no end. This can occur simply by the user changing the font size. Grrr.

  8. Liz, I have a question that I haven't been able to find an answer for anywhere (including two of your books).

    Is there anything you can do to affect the quality of the "in place" graphic in an epub? If you click on the image to increase the size, then all the text in legible. However, the "in place" graphic contains text that is too small and pixelized to read.

    My guess is that there's not anything I can do without altering the original graphic, but I want to verify that before I tell my client.

    Please help!


  9. Hi Liz, why do images not scale correctly when formatting with Pages. Is there a special setting to format images in Pages, for them to scale correctly to say an iPhone. Why do the images get cut off when viewed on an iPhone?

    Thanks so much


More of my books