Meanwhile is a branched-storyline comic written and illustrated by Jason Shiga, originally published as a printed book. Interactive game developer Andrew Plotkin designed and coded the iOS version, available on the iOS App Store [iTunes link]. While I’ve seen the print edition, my first experience of the story was via the iOS app, as it will be for most readers.

Story

Meanwhile is about a boy named Jimmy who buys some ice cream. Then things get complicated.

Mechanics

The comic is an infinite canvas; the app pans across the storyboard following the branching pathways. There’s a subtle rhythm in how the panels are laid out; sequences which happen quickly or follow naturally are clustered together in a single viewport. Surprise reveals, or shifts in time and place, are often in panels located far from their antecedent; the app reinforces this shift by swiftly panning across the story world. There’s an ever-present tension between this sense of place, and knowing that the canvas itself is too hopelessly tangled to really follow.

Design

There was a moment in my first readthrough where I laughed out loud in surprise; the mechanics and the story clicked perfectly. An interactive narrative may begin life as a purely conceptual idea about form (“I’d like to tell a choose-your-own-adventure story as a comic book”). If it’s successful, it will just appear to have been the natural way to tell that story. Interactivity isn’t an add-on or an enhancement — it’s a genre in its own right, not substitutable with another method of expression.

Meanwhile is expertly paced — one of the hardest things to control in an interactive work. There’s a gentle opener (certainly a comic book should not need instructions), some set-up with intriguing foreshadowing, and then quickly “goes wide”, providing branch points which clearly lead to a variety of outcomes.

There are even a few puzzles to solve, a feat given the fact that the entire story is plainly visible. Puzzles mean the story isn’t simply about tapping through all the branches until you’ve exhausted the narrative tree. Problem-solving provides narrative drive and consequences for failure; as a reader, I was motivated to succeed. (And discovering the “one path [that] will lead you to happiness and success” was particularly satisfying.)

Tech notes

Requires iOS 4.2+, 28.3MB

Meanwhile is available for iPhone/iPod as well as iPad. I played on my iPhone, which feels more “right” to me than the larger viewport available on the iPad. Unfortunately the artwork is not high-res and looks a little grainy on a Retina screen; I’d love to see an update with new art. There are subtle sound effects which I didn’t notice until a later playthrough; they aren’t necessary for the story and I happen to prefer my interactive works to be silent, so this is purely optional.

Accessibility

The application is also accessible with VoiceOver. Each panel has textual description of the depicted events and dialog, making it fully playable for visually-impaired users. Hooray!

Conclusion: Highly recommended and well-worth $4.99 USD.

The result is Caveman, a Python tool to validate HTML5 cache manifests. It scrapes the HTML page you specify, finding resources, then compares them to the cache manifest and reports problems.

Full blog post and complete documentation on Caveman.

If you’re logged in to Ibis Reader from a computer (not the mobile interface), you can now upload one or even many EPUB files at a time just by dragging. Here’s how it looks in Chrome:

This menu will open up on a “drag” event, meaning that you’ve moved some file from your desktop onto the Ibis Reader window.

When you “drop” the file into that space, a progress bar appears showing the upload time:

This uses the HTML5 <progress> element on supported browsers.

When complete, you’ll be taken to your personal library of books and the new book will be at the top.

If there’s an error, you’ll see it on the upload dialog:

Try it with multiple files simultaneously!

Support

This should work in Firefox 5+ and recent versions of Chrome. It doesn’t currently work in Safari 5.x.

For browsers which don’t support drag and drop yet we also improved the normal file upload method (in which you click “Add a Book” to upload by selecting a file from your computer). The “Add a Book” feature now supports multiple file upload, so if you select multiple files from the dialog, it will upload them in succession.

This will work on Safari as well as other browsers which support multi-file upload.

In any scenario, if you upload multiple files and one has an error, the upload process will stop at that file (other files that came before will successfully be added to your library).

Enjoy!

Tech details

Safari 5 currently has a bug that prevents the <progress> element from being nested inside of a block-level element like a <div> (This was a WebKit bug whose fix just hasn’t made it into Safari yet.) In Safari you may not see the progress bar because of this.

I would have preferred to let you drop the files anywhere on the site, rather than just in that big box, but Chrome requires that the drop point for file uploads be inside of a <form>. You’ll see the same paradigm if you use Gmail’s drag and drop support for attachments (did you know you could do that?)

Note: I’m going to give examples using a number of bare-metal tools available on Mac OS X. These are probably portable to Linux and even Windows if you were motivated, but I’m not going to explain how to install them or set them up (here or in the comments). Google is your friend.

To get started, download all of the EPUB 3 schemas (I put them in an epub30-schemas/ directory), install the absolute latest version of the RELAX NG validator Jing (jing-20091111/ for me), download the Schematron tools at iso-schematron-xslt1.zip is for XSLT1 processors (iso-schematron for me), and make sure you’ve got access to both xsltproc and java. Finally, save this as svrl_as_text.xsl:

<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
            xmlns:svrl="http://purl.oclc.org/dsdl/svrl"
            version="1.0">
  <xsl:output method="text"/>

  <xsl:template match="*|node()">
    <xsl:apply-templates/>
  </xsl:template>
  <xsl:template match="svrl:failed-assert|
                       svrl:successful-report">
    <xsl:text>FAILURE: </xsl:text>
    <xsl:value-of select="local-name(.)"/>
    <xsl:text>: </xsl:text>
    <xsl:value-of select="normalize-space(svrl:text/text())"/>
    <xsl:text>&#10;</xsl:text>
  </xsl:template>
</xsl:stylesheet>

Layout of the EPUB 3 schemas

All of the schemas for EPUB 3 are available as RELAX NG and sometimes Schematron. Each one has specific strengths, so we use both schemas whenever possible to get a complete list of all the validation issues. The EPUB 3 schemas are broken into separate files for each type of document inside an EPUB 3. You should notice that there is a RELAX NG Compact .rnc file for each type:

epub30-schemas/epub-nav-30.rnc        # EPUB Navigation Document
epub30-schemas/epub-svg-30.rnc        # SVG Content Documents
epub30-schemas/epub-xhtml-30.rnc      # XHTML Content Documents
epub30-schemas/media-overlay-30.rnc   # Media Overlay Documents
epub30-schemas/ocf-container-30.rnc   # META-INF/container.xml
epub30-schemas/ocf-encryption-30.rnc  # META-INF/encryption.xml
epub30-schemas/ocf-signatures-30.rnc  # META-INF/signatures.xml
epub30-schemas/package-30.rnc         # Package Documents

Unsurprisingly, you use a RELAX NG validator with epub30-schemas/media-overlay-30.rnc to validate a Media Overlay document.

A few of these documents also have a Schematron schema with the same prefix but ending with .sch, which is used to express other requirements that aren’t possible in RELAX NG:

epub30-schemas/epub-nav-30.sch
epub30-schemas/epub-svg-30.sch
epub30-schemas/epub-xhtml-30.sch
epub30-schemas/media-overlay-30.sch
epub30-schemas/package-30.sch

There are some standalone Schematron validators, but we’re actually going to roll our own tool for more human-readable output.

There’s a third file extension too, .nvdl, which is short for Namespace-based Validation Dispatching Language. These files are supposed to wrap these two schemas together for unified validation tools, but there isn’t good software support for NVDL today. Ignore the .nvdl files for now.

What to validate

I’m currently interested in the EPUB Navigation Document, a reformulation of EPUB’s NCX document as XHTML, so these are the examples we’ll use. However, this approach should work for any of the other document types if you go through the same setup.

Here is a valid, if short, EPUB Navigation Document:

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:epub="http://www.idpf.org/2007/ops"
      profile="http://www.idpf.org/epub/30/profile/content/">
  <head>
    <title>EPUB Navigation Document Example (Good)</title>
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
  </head>
  <body>
    <section class="frontmatter TableOfContents">
      <header>
        <h1>Contents</h1>
      </header>
      <nav epub:type="toc" id="toc">
        <ol>
          <li class="toc-prelin" id="toc-prelim">
            <a href="prelims.html">Introduction</a>
          </li>
          <li class="toc-ch01" id="toc-ch01">
            <a href="ch01.html">Chapter 1</a>
          </li>
          <li>
            <a href="copyright.html">Copyright Page</a>
          </li>
        </ol>
      </nav>
      <nav epub:type="landmarks" id="guide">
        <h2>Guide</h2>
        <ol>
          <li>
            <a epub:type="toc" href="#toc">Table of Contents</a>
          </li>
          <li>
            <a epub:type="bodymatter" href="chapter_001.xhtml">Begin Reading</a>
          </li>
          <li>
            <a epub:type="copyright-page" href="copyright.xhtml">Copyright Page</a>
          </li>
        </ol>
      </nav>
    </section>
  </body>
</html>

And here is one with a few errors that should be reported as invalid:

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:epub="http://www.idpf.org/2007/ops"
      profile="http://www.idpf.org/epub/30/profile/content/">
  <head>
    <title>EPUB Navigation Document Example (Bad)</title>
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
  </head>
  <body>
    <section class="frontmatter TableOfContents">
      <header>
        <h1>Contents</h1>
      </header>
      <nav>
        <!-- this is omitted, which is invalid: epub:type="toc" id="toc" -->
        <ol>
          <li class="toc-prelin" id="toc-prelim">
            <a href="prelims.html">Introduction</a>
          </li>
          <li class="toc-ch01" id="toc-ch01">
            <a href="ch01.html">Chapter 1</a>
            <!-- This is invalid -->
            <span/>
          </li>
          <li>
            <a href="copyright.html">Copyright Page</a>
          </li>
        </ol>
      </nav>
      <nav epub:type="landmarks" id="guide">
        <h2>Guide</h2>
        <ol>
          <li>
            <a epub:type="toc" href="#toc">Table of Contents</a>
          </li>
          <li>
            <a epub:type="bodymatter" href="chapter_001.xhtml">Begin Reading</a>
          </li>
          <li>
            <a epub:type="copyright-page" href="copyright.xhtml">Copyright Page</a>
          </li>
        </ol>
      </nav>
    </section>
  </body>
</html>

RELAX NG validation with Jing

Once you’ve got jing setup, it’s pretty straightforward to validate our files (above) against the appropriate .rnc. We’ll be using the epub30-schemas/epub-nav-30.rnc schema.

When you run jing against a file and it passes, you get no output (good) and an exit code of 0. I’m calling jing as java -jar jing-20091111/bin/jing.jar, passing the -c flag to tell it to expect a Compact version of RELAX NG, and then the schema filename followed by the filename of the document to validate:

$ java -jar jing-20091111/bin/jing.jar -c epub30-schemas/epub-nav-30.rnc good.nav.html
$ echo $? # What was the exit code?
0

Unlike earlier versions of jing, the latest versions have much clearer error reports on invalid documents (we also saw this improvement in epubcheck 1.2 thanks to George Bina from oXygen):

$ java -jar jing-20091111/bin/jing.jar -c epub30-schemas/epub-nav-30.rnc bad.nav.html
bad.nav.html:21:20: error: element "span" not allowed here; expected the element end-tag or element "ol"

…and the exit code is not 0, just as expected:

$ echo $?
1

We can take apart that first bit out output, bad.nav.html:21:20, to know which file had the error (we could run it on many at once) and also the line number (21) and character on that line (20). Line 21 has just what we would expect given the error message (a span instead of another ol or the end of this one), but for other errors it can be quite illuminating:

$ sed -n -e 21p bad.nav.html
            <span/>

Note: For really large documents, you may get an java.lang.OutOfMemoryError or other exception. Find out how to give jing more “heap space”.

Schematron validation with XSLT

Validating the Schematron schemas is a little more involved, but it catches some validation errors than jing and RELAX NG just cannot find. First we turn the .sch file into a re-usable XSLT stylesheet that produces Schematron Validation Report Language (SVRL). We can then run that stylesheet on any document of that type inside an EPUB 3 file to produce SVRL, which we then transform into something human-readable.

First we create our validation stylesheet, epub-nav-30.sch.xsl, from the epub30-schemas/epub-nav-30.sch Schematron schema:

$ xsltproc -o epub-nav-30.sch.xsl iso-schematron/iso_svrl_for_xslt1.xsl epub30-schemas/epub-nav-30.sch

Now we can use epub-nav-30.sch.xsl on any EPUB Navigation Document:

$ xsltproc epub-nav-30.sch.xsl bad.nav.html

<?xml version="1.0" standalone="yes"?>
<svrl:schematron-output xmlns:svrl="http://purl.oclc.org/dsdl/svrl" xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:schold="http://www.ascc.net/xml/schematron" xmlns:sch="http://www.ascc.net/xml/schematron"
xmlns:iso="http://purl.oclc.org/dsdl/schematron" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" title="" schemaVersion="">
  <!--   
		   
		   
		 -->
  <svrl:ns-prefix-in-attribute-values uri="http://www.w3.org/1999/xhtml" prefix="html"/>
  <svrl:ns-prefix-in-attribute-values uri="http://www.idpf.org/2007/ops" prefix="epub"/>
  <svrl:active-pattern id="nav-ocurrence" name="nav-ocurrence"/>
  <svrl:fired-rule context="html:body"/>
   ... many more lines ...

…but we rarely want to read the SVRL it outputs directly (although sometimes it is worth it for the extra detail it contains), so we need to send it through another stylesheet (svrl_as_text.xsl from above) to get a human-readable output:

$ xsltproc epub-nav-30.sch.xsl bad.nav.html | xsltproc svrl_as_text.xsl -
FAILURE: failed-assert: Exactly one 'toc' nav element must be present
FAILURE: failed-assert: Spans within nav elements must contain text
FAILURE: failed-assert: nav elements other than 'toc', 'page-list' and 'landmarks' must contain a heading as the first child

These are completely new issues that jing could not catch. Note that the issue about the span is actually distinct from the one above, which said it was in the wrong place, whereas this says that it has the wrong content (none at all, in fact).

Unlike jing, we don’t get meaningful exit codes. Although that is not too hard to add, it’s slight tricky to get all of the errors and exit codes rather than just exiting on the first one, which can make you think your document is less invalid than it really is. We still get no output for valid documents:

$ xsltproc epub-nav-30.sch.xsl good.nav.html | xsltproc svrl_as_text.xsl -
# no output

I’m certain to have made lots of mistakes in the examples above. If you spot some, please let me know in the comments and I’ll correct the post.

Anyone who’s ever been to a digital publishing conference knows that there is always a bewildering array of products that create and display enhanced content: ebooks that contain video, audio, animation, or other forms of interactivity. Generally each new platform requires an entirely different way of preparing the content and all the multimedia assets. While the production of static ebooks has become relatively standardized (using EPUB2), publishers are still struggling with how to produce more digital-native products without tremendous expense and constant re-tooling.

I’m optimistic that EPUB3 will provide significant headache-reduction in this area. While creating high-quality static, pure-text ebooks still has challenges, things are a lot better today than even a year ago. If we’re to see similar consolidation in the enhanced ebook space in the same timeframe, publishers are going to have to be firm that they will only (or at least primarily) produce standards-based multimedia books.

Slides from DBW

EPUB3 interactivity demo in iBooks

The talk includes a video demo. I had created an EPUB document several months ago for a research project, using Abroad by Thomas Crane as source material (edition from the Internet Archive). I wanted to emulate the accelerometer-driven animation of the Alice for iPad book using only the tools available in EPUB3.

Since the source was a heavily-illustrated children’s book, EPUB’s reflow capability was not really an asset. This quality made the book perfect for use in Apple’s fixed-layout mode. The video below shows the book running in iBooks on an iPad:

Accelerometer

In the first example, I use the accelerometer interface in JavaScript (some sample code), to cause the ship to “sail” back and forth as the user tilts the device.

Animation

In the second example, if the user touches any of the birds on the title page, they fly away. I modified the jQuery Path library to use CSS3 transforms to efficiently animate along a curve. JavaScript performance in iBooks appears to be somewhat worse than Mobile Safari; optimizing using CSS3 rather than DOM position updates is recommended.

Canvas, Processing.js, HTML5 audio

I’m a big fan of the Processing visual programming language. In the last example, the train appears to give off puffs of steam; each time the steam comes out of the train the puffs are in slightly different positions.

I embedded Processing.js code (which is itself then interpreted by JavaScript) and rendered the puffs to a transparent canvas. The puffs appear in a slightly random position, fade out as they reach the top of the page and then spawn anew.

Finally, there’s also an event bound to the invisible canvas: tapping on it will fire an HTML5 audio (a sample of a train).

(At this time we’re not able to share the demo EPUB file itself.)

The goal of this post is to simply document the extension and show how to create new works with it. I’m not going to debate whether it’s a good thing for the ecosystem here.

Install Phone Disk

Anyone working extensively with iBooks EPUB development should first grab a copy of the invaluable Phone Disk. This allows Mac and Windows computers to browse most of the iOS device filesystem as a normal drive, including opening and inspecting EPUB books.

Download a fixed-layout EPUB sample from the iBookstore

iBooks samples do not have DRM and so can be opened and read normally. A good bet is to download one of the “Children’s Picture Books”; these tend to be fixed-layout books.

Find the display-options file

The key component of the extension is the addition of the file META-INF/com.apple.ibooks.display-options.xml. This file tells iBooks that the book is the fixed-layout type, and typically looks something like this:

<?xml version="1.0" encoding="UTF-8"?>
<display_options>
    <platform name="*">
        <option name="fixed-layout">true</option>
    </platform>
</display_options>

There are a number of options here which are detailed in the iBookstore Asset Guide (v4.5), including how to define two-page spreads.

The first thing I tried with one of the samples was to validate it with the latest epubcheck 1.1:

Epubcheck Version 1.1
WARNING: /Users/liza/foo.epub: item (iTunesMetadata.plist) exists in the zip file, but is not declared in the OPF file
WARNING: /Users/liza/foo.epub: item (iTunesArtwork) exists in the zip file, but is not declared in the OPF file

These are just warnings; the fixed-layout book is valid. You can try opening them in other EPUB readers, with varying success depending on how wild the book designer got with the fixed-positioning.

Inspect the OPF and NCX

One immediate surprise to iBooks developers is that you’re likely to find an embedded font (now supported in any iBooks EPUB). Otherwise there’s nothing added to the OPF.

The NCX examples I found did not include all of the XHTML pages; I’m not sure whether that’s just a function of the book being a sample.

Structure of a fixed-layout book

In a typical EPUB, each chapter or major division of content is a single XHTML file. In the fixed-layout model, each XHTML file corresponds to a single physical page. So while it’s typical to name most EPUB XHTML files like chapter01.html, chapter02.html, in the fixed-layout book you’re apt to see a layout like:

cover.xhtml	font		package.opf	page001.xhtml	page003.xhtml	toc.ncx
css		images		page000.xhtml	page002.xhtml	page004.xhtml

XHTML content

The one unusual element in the fixed-layout content will be this HTML, which is required:

<meta name="viewport" content="width=1000, height=1000"></meta>

The specific width/height is per-book and based on the desired dimensions of the page. iBooks uses this information to scale the screen size appropriately (more on this later).

Otherwise the XHTML should look relatively normal (other than being very short). In fact the XHTML will be exceptionally readable since these books are by necessity all hand-coded at the moment.

CSS

Here’s where things get interesting:

The body element must be defined with an absolute width/height that matches the viewport above:

body {
	width: 1000px;
	height: 1000px;
}

Images and text will often be absolutely-positioned. z-index and other advanced positioning techniques are also supported. Font sizes are specified in pixels, not ems (users can zoom fixed-layout books, but the text will not reflow). Background colors are useful in this model as the XHTML content is full-bleed and does not usually have the goofy fake book margin.

Since this is all standard CSS 2.1 (or CSS3), these books don’t technically require a specialized reading system; any one based on a modern browser, like the mobile version of Ibis Reader, could potentially consume these books if the reading system could scale the pages appropriately.

Interactivity

It’s been noted that my original JavaScript in EPUB example no longer works in more recent versions of iBooks. This had nothing to do with the JavaScript parts themselves; instead the problem was that Apple began squashing the positioning information needed to align the popups.

In recent work for publishers I’ve found ways to get around those limitations, but they’ve been quite awkward and difficult to author. Would the “freedoms” of positioning in the fixed-layout books allow the original sample to work again?

Yes!

I took my original file and made only three changes:

1. I added the com.apple.ibooks.display-options.xml file just as shown above.
2. I added the viewport directive to the XHTML file and set it (arbitrarily to 600 pixels wide, 800 pixels tall).
3. I modified the CSS body directive to match the viewport.

The result:

Download the example EPUB (Creative Commons Attribution-Noncommercial-Share Alike 3.0)

Obviously the layout could use some work; there’s no longer any default margin added by the ereader, so the text bleeds out. Also my 600×800 dimensions don’t exactly match the iBooks aspect ratio, so there’s more fake book border. But you can see how this could be improved.

Note that the vast majority of EPUB books should not be formatted this way. This isn’t a one-way ticket to CSS Town. If the text on a particular XHTML page overflows the bottom of the single page, it will get cut off. You cannot mix fixed-layout and reflowable pages in the same EPUB file.

Font selection

Font formats and licensing are complicated. The ePub specification recommends that book designers and reading system implementers use OpenType fonts when possible (although TrueType fonts remain more common). If your font ends in a .otf extension, it’s an OpenType font. I’ll use OpenType in my discussion here.

Licensing

Font licenses may allow you to use the font in printed collateral or even digital documents, but may not allow you to embed that font for distribution elsewhere. It’s unclear whether specific foundries consider bundling a font with an ebook to be violating their license. Theoretically, nothing stops the end-user from unzipping the .epub file and taking out the font, so bundling it with an epub could be considered a form of distribution.

One method to allow font inclusion without violating any license is to employ font obfuscation. Adobe has released some open-source code in epub-tools to enable this, and provided detailed documentation for software developers who want to implement the algorithm. I’m not aware of any readers besides ADE that can read fonts obfuscated in this manner, though.

Fonts with open licenses

My preferred solution for bundling fonts is to dodge the entire licensing issue altogether by using an open license. The Bitstream Vera fonts have a generous license and good Unicode support, but don’t include all possible serif/italic/bold combinations. A later variant called DejaVu improves on this by including more faces and even better Unicode support.

My favorite fonts in terms of good Unicode support combined with an open license are the Liberation series. These are workhorse fonts designed to resemble the basic Microsoft set of Arial, Times and Courier. Nothing fancy, but they’re screen-readable and contain a wide range of characters.

How to embed a font

If you’re not afraid of specs, I recommend reviewing the CSS2 @font-face rule. But here’s the step-by-step:

0. Convert the font to OpenType

This is step 0 because it’s not strictly required, and you may already be starting from an OpenType font. I usually convert TTF fonts to OTF with FontForge. FontForge is not the friendliest software but it will do the job. Commercial font software will be much easier to use but tends to be expensive. Or you can just skip this step.

1. Add the font to the OPF package

Every file in your epub must be declared in the OPF manifest. This includes fonts. Put the font in the same place as your OPF file (usually a folder called OEBPS) and add it to the manifest. For example:

<item id="epub.embedded.font" href="MyFont.otf" media-type="font/opentype"/>

1.a Repeat for all combinations of faces

You will probably want to add additional packages to support all combinations of bold, italics, serif and sans-serif (as users may be able to switch serif settings in their reader).

2. Create the CSS @font-face rules

This is standard CSS from here on out; nothing ePub specific:

Declare the font itself

This tells CSS that you will be using a particular font in the document. It doesn’t say where it will be used, so just including this directive will have no effect:

@font-face {
  font-family : MyFont;
  font-weight : normal;
  font-style: normal;
  src : url(MyFont.otf);
}

Now we need to tell the CSS where this font should be used. To set it as the default font for the entire document, apply it to the <body> element:

body {
  font-family: "MyFont", serif;
}

This should be the last rule in your CSS.

Note that the generic “serif” declaration follows our declared font. I don’t recommend declaring any other fallback fonts besides just serif or sans-serif.

If you included italic or bold variants separately, add them as:

@font-face {
  font-family : MyFontBold;
  font-weight : bold;
  font-style: normal;
  src : url(MyFontBold.otf);
}

@font-face {
  font-family : MyFontItalic;
  font-weight : normal;
  font-style: italic;
  src : url(MyFontItalic.otf);
}

strong, b {
  font-family: "MyFontBold", serif;
}

em, i {
  font-family: "MyFontItalic", serif;
}

You may need to tweak the font assignments for particular elements. For example, <blockquote> is typically rendered in italics; you’ll need to assign that to the italic variant as well.

3. Validate your ePub

This has nothing to do with fonts, but you should be validating any ePub you generate.

4. Test it out

The earlier font embedding article contains a list of readers which support embedded fonts. If possible I recommend testing both on Adobe Digital Editions and a compatible eink reader.

(Many thanks to Keith Fahlgren at O’Reilly Media for teaching me about real-world embedded font support.)

Edited November 10, 2009 to include a pointer to DejaVu.)

Here’s the quick visualization I threw together (warning, it loads very slowly):

It skips any images that are broken or any that were listed as having the Twitter default icon. For some reason the raw data included a lot of default icons it shouldn’t have — for example, all of my tweets were listed with the default instead of my profile photo. Those are missing. I recommend starting with the XML instead (posted after I wrote this) and getting the profile icons directly via Twitter.

Source code that generates this from the raw text (not from the XML) follows:

#!/usr/bin/python
import re, copy, urllib, sys

# Pattern-match the twitter username
p = re.compile('^([^:]+):(.*)$')

data = []
tweet = None

for line in open('toc-tweets.txt'):

    # If we're not currently in a tweet, start a new record
    if not tweet:
        tweet = {}

    # Skip the useless relative date values
    if line.endswith('ago'):
        continue

    # This is an end-of-tweet marker, so push it on the stack
    # and reset the temporary datastore
    if line.startswith('*'):
        data.append(copy.deepcopy(tweet))
        tweet = None
        continue

    # Grab the user's image
    if line.startswith('http://'):
        tweet['img'] = line
        continue

    m = p.search(line)
    if m:
        # If we matched the regexps then we have a line containing a valid tweet
        tweet['name'] = m.group(1)
        tweet['message'] = m.group(2).replace('&', '&')

# Put in chronological order
data.reverse()

print '''<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />
    <title>#toc timeline</title>
    <script src="http://www.google.com/jsapi" type="text/javascript"></script>
    <script type="text/javascript">
      google.load("jquery", "1.3");
    </script>
    <script src="jqueryui/jquery-ui-personalized-1.6rc6.min.js" type="text/javascript"></script>
    <style type="text/css">
       .tweet span { display: none; width: 300px; height:200px;  }
       .tweet { display: inline; z-index: -1;}
       .drop { width: 240px; height: 135px; padding: 0.4em; position:absolute;background:white;z-index:99;}
       .drop h3 { margin: 0; padding: 0.4em; text-align: center; }

    </style>
    <link rel="stylesheet" type="text/css" href="jqueryui/theme/ui.all.css"></link>
    <script type="text/javascript">
    jQuery(document).ready(function() {
      $('.tweet').click(function() {
        $(this).find('span').toggle('fast');
      });
    });
    </script>
   </head>
<body>
'''

images = {}

for t in data:
    if 'default_profile' in t['img']:
        continue
    image = t['img'].replace('mini', 'bigger')
    if image not in images:
        sys.stderr.write("Checking %s\n" % image)
        i = urllib.urlopen(image).read()
        if 'Error' in i:
            sys.stderr.write("Skipping...")
            continue
        images[image] = 1

    print '''
<span class="tweet">
  <img src="%s" alt="%s" width="73" height="73" />
  <span class="ui-widget-content ui-corner-all drop">
    <h3 class="ui-widget-header ui-corner-all"><a href="http://twitter.com/%s">%s</a></h3>
    <blockquote>%s</blockquote>
  </span>
</span>
''' % ( t['img'].replace('mini', 'bigger'),
       t['name'],
       t['name'],
       t['name'],
       t['message'])

print '''
</body>
</html>
'''